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.
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.
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.
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.
/* 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.
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.
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.
{
"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"]
}
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.jsonis valid andindex.tsexports the component and its*Propstypes. - 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.jsonand tested. npm test,npm run typecheckandnpm run checkpass.- Your demos render in
all-demos.test.tsxwithout errors or axe violations. - The docs site shows every demo with no console errors (
npm run dev). - Copy follows
DESIGN.mdsection 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): oneexport *for each folder that has anindex.ts. Gitignored. registry/*.json- Written by
npm run registry(scripts/gen-registry.mjs): one file per component with its metadata and full source, plusindex.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.