# Contributing

Tokens live as DTCG JSON in `shared/design/tokens/json/`. Terrazzo builds them into CSS, and a small script adds the Tailwind theme, the text-style utilities, the TypeScript module and the pages on this site. A change takes three steps and ends in a pull request.

## 1. Edit the token files

Each collection has one file with its default mode: `primitives`, `semantic` (light), `direction` (standard), `dimension` and `layout` (mobile). The other modes sit in `modes/`: `theme-dark`, `direction-color-blind` and `layout-tablet`, `layout-desktop` and `layout-wide`. Text styles are in `typography` and shadows in `effects`.

A token's CSS name lives in `$extensions["finance.umia"].css`. Point to another token with an alias like `{primitives.color.green.500}` instead of copying its value.

## 2. Regenerate

```bash
just design-build
```

This runs Terrazzo, then rewrites `styles.css`, the TypeScript module and the Markdown in `shared/design/docs/foundations/`. This site copies those files when it builds.

## 3. Review and open a pull request

Read the diff of the token files and the generated files, and check the screens in the hub that use the changed tokens. Run `bun --filter @umia/design test`, then open a pull request. Don't edit generated files by hand.

## Writing a component page

Each component has one page at `src/content/docs/components/<name>.mdx`, with its previews in `src/components/previews/<name>.tsx`. The previews import the real component from `web/hub/components/ui`, so the page always matches what ships.

Keep the sections in this order, which follows Carbon and Primer:

1. One sentence on what the component is for, then `ComponentMeta` with its status, source file and Figma node.
2. A playground with the main props as controls and code you can copy.
3. When to use it and when not to. Every "when not to" names what to use instead.
4. An anatomy diagram on a live example, with numbered parts. Mark the optional ones.
5. One example row each for variants, sizes, icons and states, then how to choose between them.
6. Rules for writing the label, with at least one `DoDont` pair.
7. How it behaves with a keyboard and a pointer.
8. What it needs to be accessible, such as labels, focus, ARIA and contrast.
9. Every prop with its type, default and a short note. Props that aren't listed pass through to the HTML element.
10. Related components, and when each one fits better.

Show rules as `DoDont` pairs where you can. Seeing the wrong version teaches faster than reading about it.

Only previews that need JavaScript get `client:load`, which means the playground and the anatomy. Every other example is plain HTML, so leave the directive off.

## Editing these guides

The guides live in `web/design/src/content/docs/`. Keep each one short. The Foundations pages are generated, so fix their wording at the source in `shared/design`.