Playground

Contributing a component

The recipe, a worked example, the checklist and the generated files.

Before you start

Read AGENTS.md (layout, API conventions, accessibility bar, ownership rules) and DESIGN.md (look, tokens, copy). Look at packages/react/src/components/button/ and copy its shape. This guide follows that recipe with a small example.

bash
npm install --cache "$TMPDIR/npm-cache"   # once
npm run dev                               # docs on :5180, live components and CSS
npm test                                  # vitest + axe for every component
npm run typecheck                         # react and docs
npm run check                             # css contrast and colour lint, typecheck, tests
npm run build                             # css dist, react dist, docs site
npm run registry                          # regenerate registry/ and llms*.txt

The recipe

One folder per component, five files, plus one stylesheet. Hooks use packages/react/src/hooks/<name>/ with the same shape.

layout
packages/react/src/components/status-dot/
  status-dot.tsx        the component
  status-dot.test.tsx   behaviour tests and one axe test
  status-dot.demo.tsx   export const demos: Demo[]
  meta.json             name, title, category, description, status, css, a11y, keywords
  index.ts              export the component and its Props type, nothing else
packages/css/src/components/status-dot.css   styles, tokens only

A worked example: StatusDot

The component: forwardRef to the root element, className merged with cx(), a string-union variant with the common value as the default, remaining props spread onto the root, a named export and no default export.

status-dot.tsx
import {forwardRef, type HTMLAttributes} from 'react';
import {cx} from '../../utils/cx';

export interface StatusDotProps extends HTMLAttributes<HTMLSpanElement> {
  tone?: 'ok' | 'warning' | 'danger';
  /** The status in words. The colour alone is not enough, so this is required. */
  label: string;
}

/** A small coloured dot with a text label for screen readers and for sighted users. */
export const StatusDot = forwardRef<HTMLSpanElement, StatusDotProps>(function StatusDot({tone = 'ok', label, className, ...rest}, ref) {
  return (
    <span ref={ref} className={cx('status-dot', `status-dot-${tone}`, className)} {...rest}>
      <span className="status-dot-mark" aria-hidden="true" />
      {label}
    </span>
  );
});

The stylesheet uses tokens only. npm run check fails on a raw hex colour. The build picks up every .css file in that folder, so there is no list to edit.

status-dot.css
/* packages/css/src/components/status-dot.css: tokens only, no raw colours. */
.status-dot { display: inline-flex; align-items: center; gap: var(--s2); font-size: var(--text-sm); }
.status-dot-mark { inline-size: var(--s2); block-size: var(--s2); background: currentColor; border-radius: var(--round); }
.status-dot-ok .status-dot-mark { color: var(--ok); }
.status-dot-warning .status-dot-mark { color: var(--warning); }
.status-dot-danger .status-dot-mark { color: var(--danger); }

Tests check what a user sees: roles, names, keyboard, ref forwarding, plus one axe test. Portal content is found with screen, not container.

status-dot.test.tsx
import {render, screen} from '@testing-library/react';
import {createRef} from 'react';
import {axe} from '../../test/axe';
import {StatusDot} from './status-dot';

describe('StatusDot', () => {
  it('shows the label and defaults to the ok tone', () => {
    render(<StatusDot label="Online" />);
    expect(screen.getByText('Online')).toHaveClass('status-dot', 'status-dot-ok');
  });
  it('applies the tone class and forwards the ref', () => {
    const ref = createRef<HTMLSpanElement>();
    render(<StatusDot ref={ref} tone="danger" label="Offline" />);
    expect(ref.current).toHaveClass('status-dot-danger');
  });
  it('has no axe violations', async () => {
    const {container} = render(<StatusDot label="Online" />);
    expect(await axe(container)).toHaveNoViolations();
  });
});

The demo is picked up by this site and by all-demos.test.tsx (axe, no console errors) with no further wiring.

status-dot.demo.tsx
import type {Demo} from '../../demo';
import {StatusDot} from './status-dot';

export const demos: Demo[] = [
  {
    title: 'Tones',
    description: 'The label carries the meaning; the colour is extra.',
    render: () => (
      <div style={{display: 'flex', gap: 'var(--s4)', flexWrap: 'wrap'}}>
        <StatusDot label="Online" />
        <StatusDot tone="warning" label="Degraded" />
        <StatusDot tone="danger" label="Offline" />
      </div>
    ),
  },
];

meta.json is validated by npm run registry: name equals the folder, category is one of the eleven (layout, typography, buttons, forms, data-display, feedback, overlays, navigation, effects, blocks, hooks), status is stable or beta, and a11y has at least one line.

meta.json
{
  "name": "status-dot",
  "title": "Status dot",
  "category": "feedback",
  "description": "A coloured dot with a text label that shows the state of something.",
  "status": "beta",
  "css": ["status-dot.css"],
  "a11y": [
    "The status is text, so it is read as is; the dot is hidden from assistive technology.",
    "Colour is never the only signal."
  ],
  "keywords": ["presence", "indicator", "state"]
}
index.ts
export {StatusDot} from './status-dot';
export type {StatusDotProps} from './status-dot';

This example is for illustration; it is not in the repository. Prefer composing an existing component over adding a new one when a small variant will do.

Checklist: definition of done

  • The folder has all five files, meta.json is valid and index.ts exports the component and its *Props types.
  • CSS is in its own file, uses tokens only, and works in warm, dark and midnight, all eight accents, the font, corner and density options, at 360px and 1200px.
  • Keyboard and screen reader behaviour is implemented, listed in meta.json and tested.
  • npm test, npm run typecheck and npm run check pass.
  • Your demos render in all-demos.test.tsx without errors or axe violations.
  • The docs site shows every demo with no console errors (npm run dev).
  • Copy follows DESIGN.md section 7: verbs, plain words, no exclamation marks.
  • No new dependency, or the reason is written in the pull request.

Add props, never change or remove one. Commit small, with messages like status-dot: add danger tone.

What is generated

Do not edit these by hand and do not commit them unless you are the maintainer (see the ownership rules in AGENTS.md).

packages/react/src/index.ts
Written by scripts/gen-index.mjs (run by build, test and typecheck): one export * for each folder that has an index.ts. Gitignored.
registry/*.json
Written by npm run registry (scripts/gen-registry.mjs): one file per component with its metadata and full source, plus index.json. The CLI reads these.
llms.txt, llms-full.txt
Written by the same script: a short index and a full reference for language models.
apps/docs/src/props.generated.json
The props tables on component pages, written before dev and build.

CI runs npm run registry and fails if registry/, llms.txt or llms-full.txt differ from what is committed, so the maintainer regenerates them when a component lands.