The system agrees on these before anything else.

Slate is the product. Color is the data.

Chrome is fully monochrome. The moment color appears, it means something — a band, a status, a verdict, or the one brand accent, which is brand and never state. Semantic color is always paired with a label; never the only indicator.

The accent belongs to the brand, not to data. It appears as marketing and brand furniture (eyebrow dots, links, article rules, OG cards, illustration highlights) and as link color in product chrome — never inside the mark, never on band pills or buttons, and the focus ring stays neutral. Utilities: text-brand, bg-brand-soft, border-brand-border.

One family. A deliberate scale. Tabular numbers everywhere that counts.

Geist Sans for UI, Geist Mono for tabular and code-ish content. The scale is Tailwind-aligned and used sparingly — three sizes per screen is enough almost always.

Ten-pixel corners. Shadows so light they almost aren't there.

Shape is quiet — the point is content, not chrome. Shadows are hover-reveal only; nothing glows, nothing floats at rest.

A 4-pixel grid. A six-pixel gutter. A page that breathes.

Card padding is p-6 (24px). Section stack is space-y-6. Page max is 72rem (max-w-6xl). Everything else falls out of the 4-pixel grid.

Lucide. 1.5px stroke. Sixteen pixels unless there's a reason otherwise.

One icon set, stroke-based, neutral weight. Always paired with a label or used in a known slot. No sparkle, no emoji, no unicode as icon (except → and · as glyphs).

Write like someone who knows they're right and doesn't need to raise their voice.

Sober, self-assured, lightly dry. Short sentences. Closer to The Economist than to TechCrunch. No superlatives, no startup language, no emoji, no exclamation marks.

The shortest route to getting the system wrong.

A short list of the mistakes we keep catching in review. Each one looks small; together they are what separates 'looks like Evalgist' from 'looks like a dashboard'.

Four variants. One size by default. The primary is near-black.

Every button below is the real <Button> from @evalgist/design-system. If a variant gets renamed or removed, this page will stop compiling.

Four jobs. Four palettes. Always paired with a glyph or a label.

Every badge below is the real <Badge> from the package — if the cva config drifts, these chips will look wrong or the build will fail.

Slate border, white fill, near-black text, neutral focus ring.

Real <Input>, <Label>, and <Select> from the package. The focus ring is the canonical neutral 2px at 30% — never chromatic.

White fill. Slate-200 border. Ten-pixel corners. Lifts only on hover.

All real <Card*> primitives from the package. Padding is p-6 (roomy) or p-4 (dense).

Shared primitives for dense product surfaces.

Batch A and B primitives cover status, menus, tables, confirmations, forms, and notifications. Product-specific rows, filters, and panels stay in the app.

The destructive variant carries a faint tinted surface and edge so an error reads as a distinct surface, not just red text; the body and the per-item manifest stay neutral for legibility. Compose a two-column manifest inside AlertDescription (filenames in an aligned column, reasons in the second) and put the dismiss in AlertAction.

Navigation that disappears once you know where you are.

Sidebar and topbar are Shortlist-specific, so they don't live in the shared package. They're shown here as a reference for how the tokens and primitives compose. See section 16 for the page-level contract and the PageHeader primitive that pairs with this chrome.

The page owns its title. The topbar carries context.

Pages render their H1 via PageHeader. The topbar carries utility plus page-provided route context: a single immediate-parent back-link on nested detail routes, or a compact breadcrumb only when a multi-route wizard needs to expose its intermediate steps. Ordinary routes and sidebar-backed creation routes leave the left slot empty. Reading the URL to reconstruct the current route name in the topbar remains forbidden.

1. Pages own their H1. Every routable page renders <PageHeader title="…">. Nothing else duplicates the route name.
2. The topbar is utility plus route context. Identity, credit balance, global actions, plus a page-provided parent back-link (or a breadcrumb on multi-route wizards). The topbar never derives the active route name from the URL.
3. Orientation is sidebar + page H1. Two signals, one from the shell and one from the page. No third.
4. Parent context belongs in the topbar. Ordinary depth-0/1 routes leave the left slot empty. Sidebar-backed creation routes also leave it empty. Depth-2+ routes render one immediate parent back-link, labeled by the parent entity. When that parent is a redirect-only route, the link skips to the nearest landable index and uses the landing-page label. Multi-route wizards may render a breadcrumb of their own intermediate steps. Sibling views never appear there. On small screens the back-link replaces the product lockup in the left slot — route context wins, and the brand stays in the menu drawer.

Three bands. Four qualification verdicts. One progress bar that tells the story.

Confidence is a band, not a percentage — shown in English, backed by evidence. Progress is the <Progress> primitive; the band is a <Badge>.

The inline empty surface. Dashed border, neutral icon plate, one action at most.

<EmptyState> is the section-level empty primitive — drop it inside a section that has no rows yet. The action slot accepts any React node so the design system stays Next-agnostic; consumers compose their own link primitive.

Label, number, optional hint. Chrome stays monochrome; color rides the data.

A page-header strip used on dashboards. The icon is optional and quiet; the colored bubble is gone. Destructive tone applies to the value when a number is genuinely bad — never as decoration.

Small-print row of commitments, sitting under a CTA.

Used on commerce and billing surfaces to reassure right where the decision happens. Middle-dot separators, muted text, screen-readers skip the separator. Three to five items reads best — past that, split or trim.

Rotating demo with explicit play, pause, and progress.

`useAutoCycle()` drives the active index, owns prefers-reduced-motion, and pauses on hover or focus. `<AutoCycleProgressBar>` and `<AutoCyclePauseToggle>` give consumers a ready-to-place control. The bar pauses in place — hover does not reset progress.

• Wrap the visual container with {...cycle.containerProps} — that wires pointer and focus pause.
• Render <AutoCyclePauseToggle cycle={cycle} /> next to the content title so the affordance is discoverable.
• Render <AutoCycleProgressBar cycle={cycle} /> along the bottom of the same container — the bar drives the cycle.
• Map your items with cycle.active and cycle.jumpTo(i) for the click-to-pin affordance. Set aria-current on the active item.
• Under prefers-reduced-motion: reduce, the bar and toggle render nothing and the cycle does not advance. Static state shows item 0.

Three-to-five short Q&As that handle the predictable objections.

Native <details> so it works without JavaScript, collapses by default, opens to one item at a time without state management. Use on commerce, pricing, and onboarding surfaces — anywhere a small set of repeat questions blocks a decision.

Destructive actions get a card, a typed guard, and one red accent.

One surface for every irreversible action across products. The industry consensus — Mintlify, Clerk, GitBook, Hume, 1Password, Stripe — is no leading icon: the destructive button is the sole accent, which also matches our monochrome-chrome rule that colour is reserved for the action. The typed-confirmation guard is the safety feature; bypass it and the user can delete data with one click.

One pill, one decision.

Surfaces dirty-state in an edit flow and offers the resolution actions inline. The status text is the subject — the actions are the verbs. Pulse dot communicates 'something is pending' without urgency.

Use in edit flows where the user can leave the page mid-change. The bar is sticky-bottom by default; pass className="static" to demo it inline (as on this page). One primary action only — never two. Avoid for global app toasts; the toast primitive is the right tool for transient, non-blocking confirmations.

Four states, one cue at a time.

The icon-tile-plus-row pattern used by setup strips and task checklists. State lives in the icon tile and, when current, in a single hairline on the row. The badge says the same thing in words. Never two cues for the same state — pick one.

1. One cue per state. A ring and a badge for the same row is two voices saying the same word. The badge stays; the row hairline replaces the louder cues we tried first.
2. Tile fill stays monochrome except for complete. Emerald 50/700 is reserved for finished work — the only state that earns a semantic colour. Current is signalled by the row, not by a tinted tile.
3. Blocked and not-started share the tile. The badge does the differentiating. Two near-identical tile treatments with different badges is correct; two ways of saying "this is not the active step" is not.
4. aria-current="step" on the current row. The visual cue is paired with the assistive-technology cue, not a substitute.
5. Not yet a primitive. The pattern lives inline in apps/shortlist/components/jobs/setup-progress-strip.tsx. When a second surface needs the same icon-tile-plus-state vocabulary, extract <StatusIconTile> into @evalgist/design-system/ui and refer back to this section.

Inspect, recover, continue.

Reusable patterns for operational product states: inspection sheets, compact progress histories, visible action menus, and source-backed evidence blocks. These are deliberately quiet; their job is to preserve context and make the next action unambiguous.

Page chrome recedes. The evidence surface stays white.

These primitives extract the reusable layout spine from the Shortlist sample: a muted route canvas, constrained work area, object identity header, context strip, and composable toolbar. Apps own routing, state, labels, and data.

Bounded work surfaces for document flows.

Composite primitives extracted from the Shortlist sample: a muted application canvas, white work surfaces, thin borders, restrained shadows, and dense operational states that preserve the user's work.

Keep criteria, evidence, and the human decision together.

These patterns come from the Shortlist sample, but the contracts are product-neutral: a queue of items, a dossier, source-backed criteria, and side-by-side evidence when comparison matters.

Short, mechanical, monochrome. 150–200ms on hover. Nothing bounces.

Motion is the loudest signal a page can send. Quiet motion keeps the focus on the content. Every consumer transition lives within the durations below; ambient and rotating UI uses the named keyframes.

• AnimatedGridPattern renders nothing below sm (640px) and respects `prefers-reduced-motion: reduce`.
• AutoCycleProgressBar and AutoCyclePauseToggle render nothing under reduced motion; the cycle does not advance.
• No fade-in on page load. Use `animate-in fade-in-0` only on content swaps the user triggered.
• No bounces, no springs, no chromatic ring transitions.

One sober link for prose and policy. Underlined, foreground, neutral focus ring.

The real <TextLink> from @evalgist/design-system. Use it for legal and policy links instead of hand-rolling an anchor className. Pass asChild to wrap next/link; render a plain anchor for external URLs.

For the precise policy, see Privacy, Terms, and Subprocessors.

The full overview lives on evalgist.ai/shortlist.

Two surfaces: the white card, and the grey canvas. Controls adapt to the one they sit on.

Interactive controls hover to --accent. On a white card that slate-100 hover reads fine. On the grey canvas (the app shell paints bg-muted), the same hover equals the canvas and the control disappears. Mark a region data-surface="canvas" and the contract remaps hover one step darker; any card nested inside resets it automatically. No per-call-site opt-in.

Hover the buttons above to see it: on the canvas the hover fill is distinct from the grey; inside the card it returns to the standard slate-100. The Select and Input rest on white in both, so they lift off the canvas instead of sinking into it.

Filters belong to the table, not floating above it.

<DataTable> wraps the real <Table> in its own card surface with an optional toolbar — a non-scrolling strip on the same surface as the rows. The body scrolls horizontally for wide tables while the toolbar stays put. Distinct from <ActionToolbar>, which is a standalone bulk-action bar that sits above content.

Reload is utility chrome, not a call to action.

<RefreshButton> is an icon-only ghost control: no label competing with the page title. The name lives in an aria-label and a tooltip; the glyph spins and the control disables while a refresh is in flight. It belongs in the page header's actions slot. Requires a TooltipProvider ancestor — the app shell mounts one.