# Repository Instructions

## SHD design-system maintenance

Treat `docs/DESIGN_SYSTEM.md` and the shared tokens and patterns in `src/app.css`
as maintained parts of the product.

Whenever a change makes a significant visual or interaction-design decision,
update the design system in the same change. This includes:

- introducing or changing colors, typography, spacing, borders, elevation, or motion;
- creating a new reusable layout, navigation, table, editor, form, card, status, or feedback pattern;
- materially changing dashboard density, hierarchy, responsive behavior, or accessibility behavior;
- changing the semantic meaning of an existing visual state;
- establishing a pattern that future pages or components should follow.

For significant design changes:

1. Reuse or extend the CSS custom properties in `src/app.css`; do not scatter
   near-duplicate hard-coded values throughout new components.
2. Update `docs/DESIGN_SYSTEM.md` with the new or revised rule, token, pattern,
   usage guidance, and responsive or accessibility considerations.
3. Refactor repeated UI into a reusable component when that makes the pattern
   clearer and reduces divergence.
4. Preserve the SHD design principles: tactical but restrained, data-first,
   square and engineered, orange reserved for action and emphasis, and explicit
   textual state indicators.
5. Verify hover, pressed, focus-visible, pending, disabled, error, success, and
   reduced-motion behavior where applicable.
6. Run `npm run check` and `npm run build` before completing the change.

Minor alignment fixes, isolated bug fixes, and corrections that do not introduce
or revise a reusable design decision do not require a documentation update.

If uncertain whether a visual change is significant, update the design system.