ui-system

UI System

Reuse what the app already has. Don't invent a parallel UI kit.

Do

1. Read DESIGN.md / area docs for the surface you're in.
2. Find the existing component/helper (button, input, dialog, progress, relative-time, dropdown, back row, …). Copy how Settings / Projects / etc. already do it.
3. Prefer a variant on an existing primitive over a new component. When asked to reuse an animated count, use the existing implementation in place (export a private component if needed); do not create or relocate it into a new primitive file as part of the visual iteration.
4. Colors/spacing/type from existing CSS vars / tokens (including the app's Tailwind v4 setup). No one-off hex/shadow stacks.
5. Match the app's look: if the app doesn't use borders/shadows/sparkles, neither does your feature.
6. Hover paints instantly; only the exit eases. Put the transition on the resting state and drop it while hovered (transition-colors duration-100 hover:transition-none, or transition: none on :hover), including sibling-dimming groups. Only a named exception fades both ways (e.g. the catalog arc border). Audit every hover you add or touch; verify computed transition-property while hovered (transition-none leaves duration).

Extending an existing interaction

• Preserve existing controls when adding stacking, queueing, or depth. Support inline approvals beneath their tool row and floating approvals as distinct placements of the same stack, not a replacement of one with the other; do not restyle Run/Reject without a request. Share the gesture controller, depth geometry, resistance, release thresholds, departure and promotion motion with toasts; changing placement or content must not fork the maths. Button and keyboard decisions must produce the same perceptible card-clearing motion as a gesture, while consumers retain exact-request and approval policy ownership. Inspect live prior art such as Sonner's stacked promotion and momentum dismissal before tuning; decorative back edges and a small fade alone do not create a physical clearing sensation. Bound the visual pile and verify it in the real thread as well as floating placements. For Cursor-reference work, follow its measured single-silhouette treatment rather than preserving an older two-edge mock. Keep the host stable while the live pending list grows and drains, retain the current entry on arrival, and animate the departing card inertly. Drive counts and rear-depth visibility from live pending entries, not a fixed demo total. Exercise real tool-row additions/completions during approval so the stack cannot migrate or remount underneath a different tool.