Overview

Proposing a pattern

How a new component or pattern gets approved before it’s used.

Nothing new reaches the site until it has been on this page and approved. That keeps one way of doing each thing, and gives every change a place to be looked at in both themes and at phone width.

The steps

  1. 1Look here first. Search the sidebar. If something almost fits, add a prop or a size to it rather than building a new one.
  2. 2Build it in its kit. Put the component in the right folder of src/components (or a new kit folder), pure logic in a .ts file beside it with a test.
  3. 3Register it as proposed. Add an entry to src/design-system/registry.js with status “proposed”, what it replaces, and a live example in examples.jsx.
  4. 4Show it. Open its page here: light and dark, 390px wide, keyboard only. Screenshot it for the pull request.
  5. 5Get it approved. The site owner approves it in the pull request. Only then does its status change to “approved” (with the date), and only then may pages use it. The tests block it until then.

Retiring a piece

Mark it Deprecated, say what replaces it in its summary, and move every use to the replacement. The tests fail while anything still imports it; delete it when nothing does.

What the tests check

  • Every component file in src/components is in the registry, with the exports it lists.
  • Only approved components are imported outside the design system; nothing imports a deprecated one.
  • Every component has a live example here, or a link to the page that shows it.
  • Pages and templates define no components of their own and render no raw buttons, inputs, selects or tables.
  • Colors are tokens; text sizes come from the type scale; headings use a type role.
  • Copy says “tap”, not “click”, and names games the way games-config does.