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.

Shared anchored composers

• Keep one provider and one persistent panel/input outside the page column; make static bars and navigation items supply presets, optional prefills and placement requests instead of mounting editors. Verify DOM identity across open/close, preset switches and client route navigation.
• Port the reference's actual menu source and measured geometry, not a sibling's approximation or a delegate's prose summary. Include surrounding state: the resting hero launcher must fold away while subnav opens, or its uncovered white strip reads as a broken oversized menu. Check both surfaces together, including hover intent, strip controls and artwork containment.
• Reused artwork can carry conflicting Tailwind individual transforms; inspect computed translate as well as transform. Prefer the reference's plain artwork markup inside its intended container rather than layering overrides over a differently positioned component.
• On the research homepage, use the reference's badge-left/hamburger-right mobile header and blue artwork-backed accordion menu, with no header CTA/search clutter. Reuse the shared mobile modal mechanics and composer preset data, not a second editor. Keep one route-aware mobile wing launcher for singleton search: bottom-right normally, in article header chrome where the corner would cover prose. For a requested desktop proximity dock, reuse that same launcher as a centered badge, reveal on bottom-viewport pointer proximity and keyboard focus, honor reduced motion, and hide it whenever the hero or a modal/composer owns the interaction. When handing off from the mobile modal to Cmd+K, release its focus trap and scroll lock without refocusing the old trigger.
• Treat an already-open composer's keyboard/nav activation as a destination-aware transfer, not a blind toggle. Measure the input's painted bounds before changing direction or placement, then translate the same node from those bounds without replaying entrance choreography; test mid-flight reversal and query retention. Cancel pending hover on keyboard activation and ignore stationary-pointer reentry caused by the panel moving underneath it until real pointer movement resumes.
• Keep fixed viewport points independent of presets, alongside element/parent, viewport-region and cursor placement. Distinguish following an anchor from freezing its opening position; verify fixed placement while the document scrolls.
• Express placement as target (element, parent, viewport or pointer), target anchor, panel origin, offset and width policy. Measure untransformed layout height during a scale entrance: transformed bounds make a bottom-anchored panel drift. Recompute on content resize, ancestor scroll and visualViewport changes.
• Apply hover transitions to :not(:hover):not(:focus-visible) so entering a link is immediate. Remove surface-specific transition overrides that re-enable enter animation; transition background and foreground together on exit to avoid partially inverted rows. Verify computed hover duration and colors during rapid row-to-row movement, not only the settled color.
• Keep the composer host transparent and input opaque so color never flashes through white chrome. For subnav, animate only x/y translation on placement changes and whole-surface scale on entry/exit, anchored center-top (center-bottom for bottom docking). Use each preset's natural height immediately: no height/width tween, clip reveal, row stagger or entrance replay on preset switches. Preserve the shared header's equal-width slots; draw hover underlines and active outlines without changing their geometry.
• Center keycap glyphs using an inner cap-trimmed label, not the font's line box and descender space. Use the reference's actual SVG paths for arrows and chevrons rather than Unicode glyphs; compare opacity as well as geometry when icons appear heavier.
• Keep the composer’s trailing action icons identical across static, navigation and keyboard launch modes. Retain the shortcut note except in static-open mode, and reuse Hermes Desktop’s native-font Kbd/KbdGroup styling as a generic web primitive instead of ad-hoc shortcut text.
• Preserve partial-label hierarchy from reference source: keep a canonical string for search and explicit inline segments for muted portions, including their whitespace. Render the same segments in nav and search, and retain their relative opacity when the row inverts on hover.
• Use distinct layouts for grouped nav presets and typed search when the reference does: compact search rows should ellipsize previews to one line and omit missing-description cells. Do not force article excerpts into nav-sized description columns.
• Let wheel scrolling override selection: only keyboard-driven selection may auto-scroll, and only within the results viewport. Bypass the page smooth-scroll driver for the composer and test scrolling back to the first result after keyboard navigation.
• Anchor bottom-docked composers with CSS bottom, not a top coordinate derived from content height. ResizeObserver plus requestAnimationFrame corrects too late when search results shrink or reappear; sample every frame while typing repeated characters and backspacing to empty, including after viewport resize. For tall research search results, cap the whole panel at visual-viewport height minus twice its bottom inset, leaving equal top/bottom clearance at maximum height while the input stays anchored and results scroll internally; preserve in-flow and subnav placement.
• Treat the compact nav row and portaled subnav as one pointer boundary: use capture-phase tracking plus direct leave handlers so children cannot swallow dismissal. Pointer dismissal must not restore the old trigger's focus; open styling comes from the current request, while keyboard focus has a distinct cue. Keep spacing in noninteractive slots and anchor to the actual compact link border. Composer link fills enter instantly and take .7s to leave.
• Keep static-to-live composer handoff geometrically identical: no scale or translation on the white bar; animate only the results. Show the same blue input border on static-open surfaces without changing their existing border-box dimensions. During wing-square unfolding, drive mask inset and wing translation from one registered inherited CSS property, with fixed equal clearance; avoid independent animation tracks. Account for clientLeft when measuring offsetLeft and verify intermediate frames, interruption and mobile. Cmd+K must not resize the separate hero launcher. Sequence dock arrival, bar unfolding, controls and results rather than animating them all together; retain that ordering on reversal and verify both white surfaces, not just the overlay. Resolve fold masks against current dimensions to prevent cached-width jumps.
• When a folded composer has a colored edge, inspect the bar’s computed border and later chrome overrides before changing results opacity. Fade the border with the existing registered fold progress while retaining its width; this preserves the expanded border, square geometry and interrupted motion without adding another clock.
• Make Cmd+K results visibly slide upward behind the opaque stationary white bar after it unfolds; a ≤1% displacement reads as a pop, not a slide. Keep this entrance separate from static/subnav motion and never replay it on query changes.
• Give Cmd+K dismissal separate beats: clear content, fold into a wing square, hold the opaque square for 880ms, then ease out scale 1.01 and a 2px downward slide before the slower opacity fade finishes. Measure the visible wing’s displacement while still opaque, not only the last invisible keyframe; couple scale and translation timing so their geometry cannot create an upward rebound. Use scale 1.01 and a ≤1% vertical offset from the opposite side of arrival; keep existing placement translation independent, preserve the bottom edge during typing, and resume interrupted animation from its current pose. Verify the held beat with both fixed animation-clock screenshots and real elapsed time.

Correcting an established design

• Treat criticism of a specific effect or font as a targeted correction, not permission to replace the accepted sculpture, palette, or composition. Preserve what the user praised and vary one visual dimension at a time.
• Keep research reading previews inside the measured inline-contents column and derive their labels/excerpts from live headings and source paragraphs. Cache document geometry behind RAF/ResizeObserver, ignore explorer-internal mutations, and suppress the rail until contents leave view and whenever wide media or the footer occupies its bounds. Exercise preview pointer transfer, keyboard anchors, fractional scroll rounding, and the narrow-screen contents fallback on the real article route.
• Adopt requested authoring tools without discarding a stronger existing design. A Blender migration should retain the approved silhouette and detail unless the user asks to change them.