Components

Use when — A widget or a settings group earns a frame (CN-15's card half).

Never — Around a lone paragraph, around another card, or per row of dense data (CN-16 — a card earns its border).

• title + data on the face; the WHY one hover away (the card contract)
• card-in-card nesting
• dressing a table as a stack of cards

Use when — A state or a count that can change (CN-17).

Never — Decoration — a badge that can never change is a label in costume.

• keep it one word or a number
• sentences on a badge
• reusing status tones for series colors

Use when — Any lifecycle state anywhere — one chip carries every state on the face (DL-FMT-05).

Never — For decoration or series identity — tones are reserved for state meaning.

• derive the tone from the state word (statusTone), declared once
• let a long grade label auto-disclose
• recomputing tones per surface
• a sentence on a pill

Use when — A person or character appears in a list, a row, or chrome.

Never — As a decorative filler for entities that have no identity to show.

• always provide the initials fallback (no broken-image state)
• human-photo placeholders for characters — a robot is unmistakably a robot

Use when — A member row, a settlement line, a setting — the between-justified row the app leans on.

Never — For dense tabular data (that is Table/CN-15) or a single key-value pair (plain rows).

• one trailing slot; keep the title truncatable
• the description carries the WHY, quietly
• two competing trailing controls
• a row that is secretly a table

Use when — Between groups where space alone cannot carry the break.

Never — When proximity already groups (CN-11 — space does the explaining first).

• prefer the two-tier gap rhythm; add a rule only on top of it
• a rule between every row — that is a table's job

Use when — The loading state of a known shape (the five mandatory states).

Never — As a stand-in for data that simply does not exist — that is the designed zero (DL-STA-03), not a shimmer.

• match the real content's silhouette
• skeletons that never resolve
• shimmering an honest empty

Use when — A known action is genuinely in flight and its duration is unknown (indeterminate).

Never — As progress toward a real bar (use Progress — a spinner promises nothing), or spinning forever with nothing behind it.

• carry an accessible busy label
• resolve to the real state — a spinner is a state, not a decoration
• a spinner that never resolves
• a spinner dressed as determinate progress

Use when — Dense data as rows — edge-to-edge, divider-separated (CN-15).

Never — For two key-value pairs (plain rows) or for layout.

• right-align and tabular-nums the numbers (DL-FMT-02)
• one status chip per row at most
• a card per row
• center-aligning money

Use when — Real progress toward a real bar (a goal's settled receipts vs its target).

Never — Indeterminate spinners dressed as progress, or progress toward an invented goal (DL-VIZ-02).

• label with the numbers (n of N) beside the bar
• a bar with no denominator

Use when — A real, dignified zero (DL-STA-03 — the empty is one of the five mandatory states).

Never — As a stand-in for a loading shape (that is Skeleton), or to hide an error behind a friendly blank.

• say what is absent and the one thing that would fill it
• keep the single action optional and records-nothing
• a blank the person wonders about
• an empty that reads as a failure

Use when — A person commits an action — one primary per screen, its decline twin beside it.

Never — As navigation dressed as an act (use a link), or full-bleed (a control is fit-content, never inflated — layout:no-inflation).

• label with the outcome, short (the action slot's ceiling)
• pair every primary with its records-nothing decline
• a bare generic verb (Submit / OK) — outcome-labels refuses it
• more than one primary act on a screen

Use when — 2–4 related actions that read as one control (a view switch, an alignment set).

Never — For unrelated actions (they get their own buttons with space), or as navigation dressed as a control.

• keep the members parallel — same weight, same size
• one pressed state at a time when it is a choice
• mixing a primary and a decline inside one group
• a group of one (that is just a button)

Use when — One-line typed values inside a propose-first form.

Never — For values the record already knows (CN-06 — recognition over recall).

• always a visible Label — placeholder is an example, not a name
• placeholder-as-label
• collecting what the law refuses to hold (payment instruments)

Use when — Prose the person authors (a piece, a why, a note).

Never — For structured values a picker or select can constrain (CN-05 — prevention beats messages).

• state consequences before commitment, at the Confirm crossing
• unbounded fields feeding slots with declared ceilings

Use when — One choice among a closed set too long for radios (5+).

Never — With a single option — render the plain label instead (DL-CMP-03).

• inherent order when the set has one (DL-RNK-02)
• a select of two (radios read faster)

Use when — Independent opt-ins; each box a separate fact.

Never — For mutually exclusive choices (radio-group).

• consent words verbatim beside a consent box
• pre-checked consent — consent is the person's own act (L49)

Use when — 2-4 mutually exclusive choices, all visible.

Never — Long sets (select) or a single option (plain label, DL-CMP-03).

• describe each option's consequence inline
• a default that pre-decides a consequential choice

Use when — A live toggle whose effect is instant and reversible.

Never — For choices that take effect at a Confirm (checkbox in a form).

• state what ON means beside it
• a switch that silently records — every write is a visible act

Use when — A bounded continuous value where feel matters more than precision.

Never — For exact amounts (money is typed, never slid).

• show the current value as a number beside it
• sliders for consequential quantities

Use when — A view option (dense/roomy) — presentation, not data.

Never — For anything that writes to the record.

• aria-pressed always
• toggles as primary acts

Use when — Sibling view modes when at least two exist.

Never — A single mode — no single-option switcher (DL-CMP-03).

• mark the active one visibly, not by color alone
• mixing acts into a view-mode strip

Use when — Every real form input sits in a Field — it carries the label/description/error scaffold honestly.

Never — As a layout grid (that is the blueprint's job) or to hide an error away from its control.

• the error renders in place, toned destructive, naming what to fix (CN-09)
• the description carries the WHY quietly
• an error that appears only in a popup
• a label that does not point at its control

Use when — 2-5 peer views of ONE subject, each complete.

Never — As navigation between subjects (that is the sidebar's job) or with one tab (DL-CMP-03).

• name tabs by content, not by verb
• burying the primary act in the second tab

Use when — A long read-projection split into real pages with real URLs.

Never — Infinite scroll in disguise, or hiding the total (honest truncation shows n of N).

• aria-current on the active page
• paginating eight rows

Use when — Console surfaces under the shell — Home / the leaf.

Never — On a public door (a stranger has no hierarchy yet).

• keep leaves short — the crumb is chrome, not a title
• duplicating the page title as the last crumb AND an h1 twice the size

Use when — A message that belongs IN the flow, beside what it concerns (DL-FMT-04).

Never — For transient popups (the toast pattern is refused here) or to bury a refusal away from its cause.

• name what happened, why, and the one next step in plain words (CN-09)
• error codes on the surface
• stacking alerts — one message, placed well

Use when — A focused read or confirm that must interrupt — rare by design.

Never — For content that could live on the page (a modal is a claim on attention).

• closable by backdrop and ✕ — leaving records nothing
• modal-in-modal
• forms with multiple acts inside a dialog

Use when — Progressive disclosure at page scale — the honesty story, an inspector, secondary detail.

Never — For the primary task (a sheet is an aside, not a page).

• one quiet affordance opens it; closing loses nothing
• stacking sheets
• acts inside a sheet that belong on the page

Use when — A small structured disclosure richer than a tooltip (a mini-form, a legend).

Never — For hover-only hints (tooltip) or page-scale content (sheet).

• keep it dismissible by clicking away
• popovers as menus (dropdown-menu exists)

Use when — 2-6 secondary actions on one anchor (the ... affordance).

Never — Hiding THE primary act in a menu.

• destructive items last, visually distinct
• menus of one item
• nesting submenus

Use when — Previewing an entity behind a link (a person, a piece) without leaving.

Never — On touch-primary surfaces as the only path to the content.

• always give the link a real destination too
• hover-only access to anything that matters

Use when — The honesty rider, the grade explanation, the reassurance — one hover away (the typography disclosure law).

Never — For content a person MUST see to act safely — that goes on the face.

• keep the face word short; the tooltip carries the sentence
• tooltips on tooltips
• burying a refusal in a tooltip

Use when — Long reference content where one section at a time is the honest reading.

Never — Hiding content a decision needs at glance (the glance budget is not an accordion).

• summaries that say what opens
• burying refusals or consequences below the fold of a closed section

Use when — One optional drill (raw JSON, the full floor one rung down — DL-CNT-07).

Never — As the default state for primary content.

• closed by default only when the summary truly summarizes
• nesting collapsibles three deep (the depth budget)

Use when — A bounded region that must scroll inside the page (a long list in a panel).

Never — To make dishonestly-tall content fit — cut or paginate first (the inclusion law).

• give it an accessible label when it is the main content
• nested scroll traps

Use when — Showing the data's month — settlements by day, a cycle's cadence, a deadline in context.

Never — Rendering 'today' from ambient time (no clock in render — pass the day in as data).

• mark days from spine data
• Monday-first, tabular numerals
• a calendar as decoration when a plain date reads faster (DL-FMT-03)

Use when — A browsable strip of peers (blueprints shelves, blueprint walls) where horizontal browsing is the honest shape.

Never — To hide required content behind swipes — a carousel is browsing, not disclosure.

• keep slides scannable without swiping (peek the next one)
• auto-advance (motion nobody asked for)
• burying the only act on slide 3

Use when — One choice from a long finite set the person knows by name.

Never — As a search over an unbounded space (that is a read-projection's job) or when the set fits a select.

• render the whole option set (a projection, not a fetch-as-you-type)
• free-text smuggled through a picker — validate at the engine

Use when — The app shell's primary navigation, and any inner left menu of named things (the design-system docs menus) — a menu is a menu; only the container differs.

Never — A second primary-navigation system beside the shell's — one shell, one nav (the navigation-menu row's law).

• derive menu items from a single home (SURFACES, kit-meta, templates.yaml) so the menu cannot drift
• carry active state as aria-current, never color alone
• a scrolling page taking the sidebar with it — the sidebar is sticky, its own overflow scrolls
• kit-level collapse state — collapse belongs to the chrome island

Use when — An empty, first-time, or refused state earns a picture — 'nothing here' and 'this is refused' are real, dignified states (DL-STA-03 / DL-FMT-04).

Never — As decoration on a full state, or to soften a refusal into something it is not — the drawing carries the state, never disguises it.

• strokes currentColor so it themes with the surface (light + dark)
• pair with a plain title + the one action that would fill the state (the Empty component)
• a remote/CDN image (a fetch the page cannot make honestly)
• alarm-red art for a calm refusal — a boundary is not an emergency