Codex

How the app talks back — every state surface (alert, toast, status mark, loading, empty, error) speaks one language. This is a cross-cutting law like card-design-language.md, not a page class: it applies inside every page class. The kit is src/components/feedback/; the living example is /labs/components/feedback.

One tone vocabulary, many surfaces. Five tones — success / warning / error / info / neutral — are pinned once in feedback/tone.ts as a complete recipe (Solar glyph, foreground pair, soft wash, tinted border, solid dot). Every status-bearing component composes those strings; none restates a green-/amber-/red-/sky- literal. Before this law, "failing" was red-500 on dashboards, rose-600 on detail pages and red-600 on KPI strips — the vocabulary exists so that drift is structurally impossible.

The families: green = good, amber = caution, red = failure, sky = informational. Good and bad were emerald and rose until v0.85; on a glowing tick meter rose reads pink and emerald reads teal, and the Opt-in rate spectrum's pure red→green became the reference the vocabulary moved to — one edit in tone.ts, every surface followed, which is the point of having a vocabulary. neutral keeps tone props total and renders in the muted greys.

They are the same surface at two lifetimes; both render the tone recipe.

• Alert (feedback/alert.tsx) is persistent: for states the user must be able to re-read — a degraded integration, an expiring trial, a failed payment. It lives in the page, at the top of the region it describes. Tone colors the frame (glyph, wash, border); body copy stays muted grey.
• Toast (the ui/toast seam, fired with toast.*) is an alert that walks away: it confirms an action the user just took. If the user would need to read it twice, it must not be a toast.

Toast semantics (extends the cross-class "mutations toast" law):

• Every mutation toasts: toast.success on completion, toast.error with an action: {label: "Retry"} on failure.
• Instant settings changes toast (docs/settings.md).
• Long mutations use toast.promise so the pending state is visible.
• Never toast on page load, on read-only navigation, or "for information" — that's an Alert (persistent) or nothing.
• The engine is Appica's Base UI toast behind the @/components/ui/toast seam (component-engine doctrine, AGENTS.md): stacking with expand-on-hover, swipe-dismiss, countdown progress, pause-on-hover and live regions live in the engine; the seam owns the firing API (sonner-shaped toast.*) and the tone glyphs. Call sites import ONLY the seam — never a toast package — and nobody adds a second toast library or hand-rolls one.

StatusDot (glanceable "this has a state") and StatusBadge (labelled mono pill for table cells and card corners), both in feedback/status.tsx. pulse means live/ongoing; settled states hold still. Tone is earned, not decorative — a badge that is always success should be neutral.

Meter (feedback/meter.tsx) is the third mark: a segmented tick bar that shows where a reading sits in a known range — usage against a quota, a score out of 100, a rate on a poor→perfect scale, health across a fleet. That is the ARIA meter role, and it is the line between this part and ui/progress (progressbar): progress is a task getting done and stops mattering at 100%; a meter is a reading the viewer judges. The anatomy is the Opt-in rate card's — tall thin ticks, an unlit muted-foreground/20 track, every lit tick glowing in its own colour (never a blanket glow over the bar) — with two marks: a pointer above the bar for "you are here" (the value) and a notch through it for "you should be here" (a target, the calendar's position). The fill names an intent, never a class: a Tone (same green/amber/red as every dot), primary for a brand-neutral quantity, current for a hue the host binds (a metric's own colour), spectrum for the one graded poor→perfect scale (pinned once, inside the part), or a per-tick function for bars whose ticks carry individual states. value decides how many ticks are lit; fill decides what a lit tick wears; the track is not configurable. pulse is the same word as on StatusDot — live readings breathe, a period meter holds still. Gallery history: nine cards hand-rolled this bar before it was legislated, and five of them carried a [filter:none] override against the shared primitive's default glow — a repeated override is the signal that the default is wrong.

Ring (feedback/ring.tsx) is the meter's round sibling: the same reading drawn as one arc over a muted track for a SQUARE slot — a row of gauges, a card's centrepiece — with the figure in the hole and the unit on the label. Same meter role, same ink vocabulary, the same notch for the target. Its ink is the caller's ruling (a gauge rests muted and earns a tone by threshold) and its light follows the ink: a muted ring never glows. It was extracted from three hand-drawn copies under the chart law's three-times rule (docs/charts.md).

• Known incoming shape → Skeletons in that shape. The page keeps its bones and nothing jumps on arrival. This is the default.
• Unknown shape → LoadingState (feedback/loading.tsx): centered spinner + mono caption. Legitimate at route level (loading.tsx) and in freeform regions only.
• A spinner where a skeleton was possible is the class's anti-pattern: it discards layout knowledge the code already had.

EmptyState (feedback/empty.tsx): a glyph that names the situation, a title that states it, a description that says what to do about it (never a restatement of the title). Two species:

• First-run ("no projects yet") — carries the ONE action that ends the emptiness.
• Filter-miss ("no results") — carries NO action; the fix is loosening the filters already on screen. DataViewEmpty is this species.

• Regions (a widget, a panel, a tab) wrap in AsyncBoundary (feedback/async-boundary.tsx): Suspense for pending, ErrorState with a working retry for failure. React-query's error reset is pre-wired, so retry refetches instead of re-throwing the cached error.
• Routes are covered by src/app/(app)/error.tsx / loading.tsx — the shell survives, the page area fails in the same ErrorState voice.
• ErrorState (feedback/error-state.tsx) is the one failure face: error-toned empty + retry. Don't invent per-module error cards.

Which floating surface a task gets follows from the task, not taste:

One rule across all: floating surfaces carry --shadow-overlay / --overlay-border (docs/theming.md) — never a page-level shadow.

Dialog anatomy. A dialog has three fixed slots: DialogHeader (title band), DialogBody (the ONLY scroll region), DialogFooter (actions). Header and footer are pinned — long content scrolls between them, never under them — and both separate from the body with dashed seams, the same hairline language as cards. Forms inside a dialog wrap body + footer (<form className="flex min-h-0 flex-1 flex-col">) so the submit lives in the pinned footer. Content placed directly in DialogContent without DialogBody is the anti-pattern that breaks the pinning. Floating surfaces share the card family's face: rounded-xl, overlay tokens — toasts included.

Dates and numbers render through src/lib/format.ts (fmtDate, fmtDateTime, fmtRelative, fmtInt, fmtCompact, fmtPercent, fmtCurrency) — locale pinned for SSR determinism. Numeric columns pair with tabular-nums. New modules don't hand-roll toLocaleString calls or invent date patterns.

• A status color literal (green-, red-, …) on a status surface instead of the tone vocabulary. (Palette literals stay legitimate as data-differentiating accents in charts/demo blocks — that's the card language's rule, unchanged.)
• A toast the user would need to read twice; an alert for "saved ✓".
• A silent mutation, or a failure toast without a retry action.
• A spinner where the incoming layout was known.
• A progressbar for a reading, or a Meter for a task: if the viewer asks "is this good?" it is a meter; if it will hit 100% and stop mattering it is progress.
• A hand-rolled tick bar, or a glow filter on the meter's container: reuse Meter, and let each lit tick cast its own light.
• An empty state whose description restates its title, or a filter-miss empty with a call-to-action button.
• A region that can crash its page — wrap it.
• Mixed icon families on status surfaces: status glyphs are Solar, same as the system header law.