ui-polish

name	ui-polish
description	Complete execution rules for detail and motion polish on XID interfaces. Covers twelve dimensions -- alignment, spacing, typography, color contrast, interaction states, micro-interactions, motion choreography, copy, edge states, responsiveness, performance, code -- split into a brand register (landing) and a product register (Hosted UI / account / console / docs)
when_to_use	A reviewer says the details are unfinished, final polish before shipping, filling in missing interaction states, adding or tuning motion, fixing alignment and spacing, or the last quality pass before release
allowed-tools	["Read","Edit","Write","Glob","Grep","Bash"]
metadata	{"category":"frontend","stack":"react-stylex"}

UI detail and motion polish: XID execution rules

Division of labor with the frontend-design skill: that one owns layout design for new surfaces (anti-template rules, design inputs); this one owns closing out the details of an interface that already works. Polish is the last step. If a surface is functionally incomplete, finish the function first -- never polish a half-built thing.

0. Pick the register first (before touching anything)

Two budgets, split by surface, never mixed:

	brand (landing, apps/server/src/routes/home)	product (Hosted UI, account, console, org, platform, docs)
Role	The design is the product: one rehearsed signature entrance	The design serves the task: motion only communicates state
Motion budget	Entrance choreography up to 500-800ms, one hero moment	150-250ms across the board, no page-load choreography
Typography	Fluid clamp, large sizes at low weight	Fixed rem steps (0.6875rem to 1.375rem) plus one clamped page title
Color	Committed is allowed (brand color can hold area)	Restrained is the floor: accent only for primary action, selection, status
Density	Breathing room first	Density is the value: long table rows are the normal case
Gutter	clamp(1.25rem, 3vw, 4.5rem) (routes/home/landing-styles.ts)	clamp(1rem, 2.5vw, 4rem) (styles/product-surface.stylex.ts)
Tokens	lx from routes/home/landing-theme.stylex.ts	tokens from styles/tokens.stylex.ts

The public docs site (routes/docs) is the one hybrid: it uses the product tokens set and the product motion budget, but keeps fluid clamp type. Treat it as product unless a change is explicitly about marketing presentation.

1. Hard numbers (red lines -- violations get fixed, not discussed)

Contrast:

• Body text >= 4.5:1, large text (>= 18px, or bold >= 14px) >= 3:1, placeholders also 4.5:1
• The most common failure is mid-grey body text on a tinted pale background. When you are near the line, move toward ink. "Pale grey looks refined" is an illusion
• Never grey text on a colored background: use a darker step of the same hue, or vary the opacity of the text color

Typography:

• Display clamp upper bound <= 6rem (the landing hero currently tops out at 5rem); display letter-spacing floor >= -0.04em, tighter than that and characters collide
• Tracking is size-dependent -- never one global value. Display and headings take negative tracking on a gradient by size (-0.01em to -0.04em, tighter as the size grows), body takes 0, sizes below 1rem take no negative tracking. Positive tracking on mono microlabels is the deliberate brand exception (0.06-0.08em)
• text-wrap: balance on headings, text-wrap: pretty on long paragraphs. Body line-height 1.5-1.65, headings 1.04-1.2
• ALL CAPS only for labels of four words or fewer (XID's mono microlabel is exactly this case). Never ALL CAPS body text
• Two families only: --xid-font (Inter Variable) for everything, --xid-font-mono for microlabels, code, and inline identifiers. Never introduce a third
• Light text on a dark background gets +0.05-0.1 line-height: light type reads lighter and needs more air

Layering and z-index:

• Use a semantic z order (dropdown -> sticky -> backdrop -> modal -> toast -> tooltip). Arbitrary 999 / 9999 values are banned. The codebase currently uses only small integers (10 for sticky rails, 20 for the site header); keep new values in that range and in that order

2. Motion system

Duration table (the 100 / 300 / 500 rule):

Duration	Purpose	Examples
100-150ms	Immediate feedback	Press, toggle, color change
200-300ms	State change	Menu open, tooltip, hover, tab
300-500ms	Layout change	Collapsible panel, modal, drawer
500-800ms	Entrance sequence	Landing hero and page entrance only

Spring physics (the motion library; shared primitives in apps/server/src/lib/motion/):

• Presets: springDefault (bounce 0, 0.4s, most UI) / springSnappy (0.3s, popovers) / springPress (0.25s, press feedback) / springMomentum (bounce 0.2, 0.4s, drag-and-fling only)

• Interruptibility: gesture-driven and interactive transitions use a motion spring so they resume from the current value and can reverse at any time. Pure state toggles may stay CSS transitions. The Reveal entrance system stays as it is

• Press feedback is immediate: interactive elements scale to 0.97 on :active in 100-150ms, fired on pointer-down, not on release. Button already does this at 120ms

• Popovers, drawers, and dialogs: AnimatePresence plus popoverMotion, with transform-origin anchored to the trigger, and the same path in and out

• Reduced motion: AppMotionConfig sets reducedMotion="user" globally, and styles.css has the 0.01ms fallback. Transform and layout animations degrade to a crossfade automatically

• Easing is limited to the ease-out exponential family: quart cubic-bezier(0.25, 1, 0.5, 1), quint cubic-bezier(0.22, 1, 0.36, 1), expo cubic-bezier(0.16, 1, 0.3, 1). Decorative bounce and elastic CSS easing are banned -- they are dated and they steal attention. Gesture-momentum cases may use spring bounce <= 0.2 (springMomentum)

• Exit duration is roughly 75% of entrance

• Staggered lists are legitimate: on the landing surface stagger through Reveal's delayMs, and cap total sequence length at 500ms. Copying a scroll reveal onto every section is an AI reflex -- each reveal has to earn what it reveals

• A reveal MUST enhance content that is already visible by default. Never make visibility depend on a class-triggered transition: in a headless environment or a hidden tab it never fires and the block renders blank

• Motion material is not limited to transform and opacity. Blur, backdrop-filter, clip-path, mask, and shadow are all legitimate over small areas once you have verified they stay smooth. Never animate layout properties (width, height, top, left, margin) casually -- if you need reflow, use grid-template-rows or FLIP

• will-change goes only on animations you know are expensive, applied on hover or an .animating class. Never pre-apply it globally

• Scroll triggers always use IntersectionObserver and unobserve after the first hit

• prefers-reduced-motion is not optional: every animation needs a degraded path (crossfade or instant). XID's global fallback lives in styles.css; check any new component-level animation yourself

• Perceived performance: micro-interactions target under 80ms (the threshold for "instant"). Optimistic updates are for low-risk actions only -- never for payments or destructive operations

• XID wiring: landing entrances reuse Reveal (IntersectionObserver plus reduced-motion already handled). New keyframes are module-level constants. Express state with StyleX conditional values, never descendant selectors

3. Complete interaction states (eight per interactive element)

default / hover / focus-visible / active / disabled / loading / error / success. A missing state is a hole in the experience, not a follow-up ticket. XID specifics:

• focus-visible uses the global outline in styles.css (2px solid var(--xid-accent), offset 2px). A component MUST NOT set outline: none without providing a replacement
• Loading uses Skeleton sized to the real row height so there is no CLS. A spinner in the middle of an empty area is lazy
• Async buttons set isLoading on Button, which handles the disabled state and the Spinner (the spinner takes currentColor, so it adapts to its context)
• ConfirmDialog (apps/server/src/routes/account/ConfirmDialog.tsx) is the shared confirmation surface for destructive actions. Do not invent a second one

4. Detail checklist (the twelve polish dimensions, walked in order)

1. Alignment and spacing: every value comes from the spacing scale, no orphan values like 13px. Icons optically align with text (geometric centering usually needs a 1px offset). Turn on a grid overlay to check alignment
2. Information architecture: equal conceptual weight gets equal visual weight. The "shape" of a multi-step action (modal vs full page, inline vs route, save-on-blur vs explicit submit) matches the neighboring features. One concept keeps one name
3. Typography: same size and weight for same-class elements; widows and orphans handled with balance / pretty; numbers use tabular-nums
4. Color: tokens only, no literal colors (brand override and darkTheme work by flipping CSS variables). Same meaning gets the same color. Verify light and dark
5. Micro-interactions: every state change has a transition from the duration table, all in the same easing family
6. Copy: one name per thing; consistent punctuation (labels take no period, sentences do); buttons are verb plus object; link text stands on its own. English source strings go through lingui macros, and new copy goes extract -> translate -> compile (see the lingui-i18n skill)
7. Icons: one family, one size scale, from the Icon component in apps/server/src/routes/home/landing-icons.tsx -- the only icon set in the repo. Never emoji as icons
8. Forms: labels wired up (the aria chain in Field), required fields marked, one validation timing throughout (blur or submit, pick one), sensible tab order
9. Edge states: loading / empty (teach the user, do not just say "nothing here") / error (offer a way out) / overlong content (a truncation or wrapping strategy) / no data
10. Responsiveness: check every breakpoint. The codebase uses 48rem (768px) and 64rem (1024px) as its two main breakpoints, so verify at 360px, 768px, 1024px, and a wide viewport. Touch targets

    = 44x44. Mobile body text >= 14px. No horizontal scrolling

11. Performance: no CLS (fixed image dimensions, skeletons at row height); expensive effects confined to small areas; 60fps measured, not assumed
12. Code: remove console.log, dead code, unreferenced styles. Replace one-off implementations with the shared components (Section / SectionRow / MetricsBand / DataTable / EmptyState / PageHeader). Any new orphan value is a prompt to ask whether it belongs in the tokens

5. Absolute bans (XID edition)

• Side rules used as colored emphasis (border-left / border-right thicker than 1px)
• Gradient text (background-clip: text)
• Decorative glassmorphism; repeating-linear-gradient stripe backgrounds
• The hero-numbers template (big number, small label, gradient garnish); infinitely repeated grids of equally sized cards
• A 1px border and a >= 16px blur shadow on the same element (the "ghost card"); card radius above 16px (the token ramp tops out at --xid-radius-lg, 0.875rem)
• Hand-drawn SVG doodles; decorative bounce or elastic CSS easing (gesture-momentum spring bounce <= 0.2 remains legal)
• Text overflowing its container -- test headings at every breakpoint and lower the clamp ceiling when they overflow
• Copy using the Empower / Unlock / Transform / Seamless family, or em dashes, or repeated "not just X, but Y" constructions
• XID exemption: the mono microlabel and the slash section marker are an established part of the brand system (they come from the design), so they do not count as the "eyebrow on every section" reflex. Inter Variable is locked in the tokens, so the reflexive font rejection does not apply either. Within that system, never stack a second eyebrow or numbering form on top

6. Workflow

1. Pick the register (section 0) and read the matching budget
2. Walk the real interface: start the dev server, take screenshots in both light and dark at three or more breakpoints, and record findings against the twelve dimensions in section 4. Tag each one cosmetic or functional
3. Fix functional first. Then work the list dimension by dimension, and for each issue grep the whole repo for the same pattern and fix it everywhere. A systemic problem gets a systemic fix, not a one-line patch
4. Verify: re-screenshot and compare, run pnpm exec vp check --fix, run the relevant vitest suites. If you touched copy, add pnpm run i18n:audit. If you touched landing claims, add pnpm run seo:audit. Before handoff, pnpm run check and pnpm test are the gates CI runs
5. Done means every dimension's list is empty, or the remainder is stated explicitly as an accepted trade-off with a reason. Never cite "the scripts passed" as evidence that polish is finished -- only what you saw in a browser counts