Contributing to the Design System

Scope

The design system covers:

• Tokens — Color, typography, spacing, motion (packages/config-tailwind/theme.css)
• Shared components — React components used in 2+ apps (packages/ui/src/)
• Design docs — This Starlight site (apps/design/)

App-level, one-off components live in their respective apps and are not part of the design system until they are promoted.

When to Promote a Component

Promote an app-level component to packages/ui when:

1. The component is used (or clearly needed) in 2 or more apps
2. The component has stable, well-defined props
3. There are no app-specific dependencies in the component

Do not promote prematurely. A component built for one use case rarely has the right API for two.

Adding a Token

1. Identify the token need — new color, font, or spacing value
2. Check that the token doesn’t already exist or can’t be derived from an existing one
3. Add to packages/config-tailwind/theme.css in the @theme {} block:

   --color-brand-gold: #B8960C; /* speaking award accent */

4. Add documentation to the relevant token page in apps/design/src/content/docs/tokens/
5. Open a PR with title: design: add brand-gold color token

Adding a Shared Component

1. Build and stabilize the component at the app level first
2. Copy to packages/ui/src/components/<name>.tsx
3. Export from packages/ui/src/index.tsx
4. Add a docs page at apps/design/src/content/docs/components/<name>.mdx
5. Update astro.config.mjs sidebar if needed
6. Open a PR with title: design: promote <Name> to shared ui

Writing Component Docs

Each component docs page should include:

• Import — package path and import statement
• Variants — all visual states with code examples
• Props — TypeScript interface
• States — hover, focus, disabled, loading
• Usage rules — when to use each variant, what to avoid
• Full example — a realistic usage in context

Use the button.mdx page as the template.

PR Conventions

Title prefix	When
design:	New token, component, or docs page
fix(design):	Bug fix in a token value or component
docs(design):	Copy edits to existing docs
refactor(design):	Restructuring without behavior change

All design PRs target develop following the standard GitFlow model (see the engineering docs at docs.brettjohnson.xyz).

Figma Sync

When adding or modifying tokens:

1. Update the Figma design file (link in repo README)
2. Ensure the Figma token name matches the CSS variable name (strip --color- prefix, use PascalCase in Figma)
3. Notify the brand designer in the PR description

Review Requirements

Design PRs require:

• At least 1 engineer approval
• Visual review (screenshot or Storybook link) for any component change
• No Lighthouse regression (CI enforced)