shd.build/AGENTS.md

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.