Getting started for designers

You're a designer. Your output is mocks, screens, specs, or Figma artefacts that hand off cleanly to engineering. This page tells you where the visual system lives, what to copy, and what never to fork.

Three artefacts you'll touch

1. The Figma file. The canonical visual source. Every component, every token, every page has a matching Figma frame. Ask in #design-system for the file URL — it lives at a fixed location and isn't published publicly because it carries unshipped work.
2. This site. Every token has a copy-on-click swatch and every component has a live preview. When you're not in Figma, you're here.
3. /design-system.json (browse). The structured manifest agents fetch. Designers don't usually consume it directly, but knowing it exists matters when you're handing off — engineering will pull from it.

Copy a token

Every token on this site is click-to-copy. Click a swatch → its CSS variable name lands in your clipboard. Option-click → its hex value.

Hover over any cell in /foundations/tokens to see the affordance. The interaction respects prefers-reduced-motion (instant feedback instead of the bounce) and stays AA-legible against every theme.

Map Figma to code

Each Figma component has a matching code export. The mapping convention:

The pattern is <Component> / <Variant> / <Size or State> in Figma → matching prop signature in code. When the mapping isn't obvious, reach for Figma Code Connect — Matter's Code Connect map is maintained in the repo.

What to design

• A new screen. Compose from existing components. The Recipes section shows the canonical layouts for full screens. Mirror the recipe; don't invent layout grammars.
• A new variant. When an existing component nearly fits, propose a variant through Governance — the bar is "this variant appears in ≥ 3 real screens" or "the existing variant would mislead the user." Don't ship one-off variants directly into a screen.
• A new component. When nothing fits, propose a new component. The proposal template lives at /governance#new-component-proposal.

What never to fork

• Tokens. Never invent a hex that isn't in the token surface. If you need a color that's not there, propose it.
• Type sizes. The display scale and body ramp are the canonical typography. Don't add a sixth size to either.
• Motion durations. The five durations + five easings are the motion vocabulary. New durations need a proposal.
• Component variants. Stable components have a fixed variant axis. Adding a variant is a brand decision, not a per-design one.

Figma-to-code handoff

When you're shipping a screen to engineering:

1. Annotate variants. Every component instance in your mock should map to a documented variant. If something's a one-off, flag it explicitly.
2. Reference tokens, not hex. Engineering reads your spec for token names (--fg-muted), not values. The hex is incidental.
3. Link the recipe. If your screen mirrors a documented recipe, link to it in the handoff doc. If it doesn't, write a brief recipe entry first (or propose one in #design-system).

The design-to-code workflow page covers the full handoff in detail.

What you can do that engineering can't

• Adjust spacing inside a component slot. If a Pill's icon-text gap reads wrong in your composition, propose a fix to the recipe — don't override it locally.
• Pick the right component for the context. Engineering will reach for whatever component fits the data; you read the page semantically and pick the component whose narrative matches.
• Catch contrast failures early. Every preview on this site renders at light + dark + forced-colors. Catching a contrast bug in design beats catching it in code.

When you're stuck

Two questions to ask in #design-system:

1. "Is there a component for X?" — usually yes; search Components.
2. "Is there a pattern for X?" — usually yes; search Patterns.

If both come back empty, you're proposing something new. The Governance page is the next stop.