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

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.