Flint Guides
Contributing
How a token or component gets into Flint, and what has to pass before it ships.
The path for anything new
- File an ASDS ticket describing the need.
- Reuse first. Build only when no token or component fits.
- Tokens first. Add or change tokens before touching a component.
- Every state, with an accessibility note.
- Add it to the workbench (
docs/src/workbench/benches.jsx) and walk it: every state, light and dark, both densities, keyboard only. - Document it here: usage, style, code and accessibility.
- Release: bump the version, add a changelog entry, tag it.
What the build checks
| Check | Fails when |
|---|---|
| Contrast | A text pair drops under 7:1, or a control edge, focus ring or chart color under 3:1, in either mode. |
| Usage | A control is drawn with a decorative border, or a density shrinks a control or target. |
| Parity | CSS, MUI, shadcn or Swift lands on a value tokens.json didn't give it, or the MUI theme hardcodes a color. |
| Docs and workbench | Any axe violation on any page, light or dark (workbench pages at both densities); a blocked script or style; sideways scroll at phone width; focus not landing and holding on headings; a workbench Hover row that looks like Default; or a semantic or component token with no row in the docs. |
Run the checks
Terminal
npm run build # tokens, contrast, usage, parity
cd docs && npm ci && npm run build && npm run verifyVersioning
Flint uses semver, separate from the apps that use it. A new token or component is a minor. A value fix is a patch. A rename or removal is a major. Deprecated tokens keep working for one minor release, then go in the next major.