Temps Design System

Temps console design

Two documents govern console UI, and they cover different ground:

• DESIGN.md (repo root): the existing, authoritative reference for web/src as it stands today — full-width pages, compact empty states, shared tables/pagination, shadcn controls.
• web/packages/ds/docs/RULES.md: the same conventions, codified into a real package (@temps-sdk/ds) with templates, a token pipeline, and lint enforcement. Read RULES.md, brand-guidelines.md, and design-system-handoff.md in web/packages/ds/docs/ before building or reviewing anything that touches it.

Both describe the same visual system (Vercel-inspired Geist theme, near-black primary, state colors plus small provider brand marks). Neither is the old "operator ink" prototype (@temps-sdk/op, briefly @temps-sdk/ds, PR #915) — that had a different visual language (a glyph vocabulary, an "ink" skin class), zero consumers, and was deleted. Never reference it, its mockups, or its styling.

Scope boundary — read this before touching web/src

@temps-sdk/ds is real and lint-enforced, but production migration of web/src is partial. Do not assume an existing screen should move onto the new templates just because it fits one. The numbered follow-ups in design-system-handoff.md (≈39 hand-rolled page headers, ≥14 stat-tile/chart call sites, empty-placeholder/empty-state consolidation, useGlobalView) track remaining work; completed references are noted in the handoff. Migrating one of them is a deliberate task with its own review, not a drive-by change bundled into unrelated work.

What IS in scope without asking:

• Any new screen or panel in web/src — build it on the templates.
• Any change to web/packages/ds itself (new primitive, new template variant).
• The design-system/ sandbox app.

Classification procedure: data shape → template

For any screen (new, or one you're deliberately migrating), ask what it actually shows:

1. A collection of same-shaped things (projects, deployments, logs, alerts) → Ledger. Columns + rows + optional toolbar/pagination.
2. One thing, in detail (a single deployment, project, backup) → Detail, following the record recipe below.
3. Input the user submits (settings, onboarding/setup wizard) → Settings, built from Field/FormErrors.
4. None of the above cleanly fits (a dashboard, a custom visualization) — don't force a template. Compose primitives (PageHeader, Status, TimeChart, Callout) directly and say so in the PR description.

If the screen has no data yet (new feature, no operator config) — that's not "skip the template," that's PageState variant not-set-up. See CLAUDE.md's feature-discoverability rule: show the surface, state what's missing, give a concrete example, link to the settings page. Never render nothing.

The record recipe

Every Detail page, no exceptions: title → verdict → 4-6 facts → main column → aside.

• Title: PageHeader's title.
• Verdict: one Status badge answering "is this OK?" — PageHeader's verdict slot, directly under the title.
• Facts: 4-6 scannable key/value pairs. More than 6 means some of them belong in main, not the fact grid.
• Main: the record's actual content (logs, config, timeline).
• Aside: optional secondary content (related resources, metadata).

The wired-control rule

A control that can't act yet must look inert, not merely be disabled. Two concrete patterns in this package:

• Button's busy/busyLabel: never sets the native disabled attribute mid-action (it breaks focus and some screen readers stop announcing the button right when the user needs to know their click registered). Uses aria-disabled plus a click guard instead.
• EchoDialog's confirm button: same pattern, gated on the typed phrase matching exactly, for irreversible actions (delete, revoke, drop).

Apply this rule to any new control that has a "not ready yet" state — don't reach for plain disabled by default.

Commands

cd web/packages/ds
bun run lint             # typecheck + tokens:check + audit:records
bun run tokens:build     # regenerate src/tokens.css after editing tokens.json
bun run tokens:check     # fails on tokens.json / tokens.css / globals.css drift
bun run audit:records --dir src   # (via lint) raw hex/oklch/px/ms scan

cd design-system
bun run build   # sandbox app; see handoff workspace-install caveat before installing