can't take :disabled, so it's marked [aria-disabled="true"]. These get the
LIGHT treatment (dim + muted + not-allowed), NOT the solid grey-box of form
controls: a disabled option reads as FADED, not filled (Radix/shadcn). */
.menu__item[aria-disabled="true"],
.cmdp__item[aria-disabled="true"],
.combobox__item[aria-disabled="true"],
.list__row[aria-disabled="true"] {
color: var(--k-fg-muted);
opacity: var(--k-disabled-opacity);
cursor: not-allowed;
pointer-events: none;
}
/* === Role Canvas · `selectable` — the generative binding ===================
The kit's ONE selected treatment (chromatic fill + the inset --k-selected-edge)
bound once to the ARIA state that NAMES selection (aria-selected on option /
row / gridcell / tab, aria-checked on radio) + a thin [data-role="selectable"]
for markup not yet wired to ARIA. Wrapped in :where() so it carries ZERO
specificity — a true FLOOR: any component rule (even a single class) overrides
it completely, while UNKNOWN markup (a selectable we never built) inherits the
uniform look for free. This is what stops chip / list / tab / table / segmented
from each re-rolling the selected state. See contracts.ts + ROLE-CANVAS.md
(role → guaranteed treatment). Enforced by audit:role-treatments. */
:where(
[data-role="selectable"][aria-selected="true"],
[data-role="selectable"][aria-checked="true"],
[data-role="selectable"].is-selected,
[role="option"][aria-selected="true"],
[role="row"][aria-selected="true"],
[role="gridcell"][aria-selected="true"],
[role="tab"][aria-selected="true"],
[role="radio"][aria-checked="true"]
) {
background: var(--k-state-selected-bg, var(--k-primary-soft));
box-shadow: var(--k-selected-edge);
}
/* === Role Canvas · `surface` — the generative binding (perceptual role) ====
ARIA has no attribute for "this is a raised surface", so this role — one of the
perceptual roles ARIA can't name — binds to the thin [data-role="surface"].
Same zero-specificity :where() FLOOR: an UNKNOWN container tagged
data-role="surface" inherits the kit's separation treatment (surface bg +
hairline border + radius + the sm elevation) so it reads as "off the ground",
while any component (.card, .stat, .pane, .well…) fully overrides it. The
perceptual companion to the ARIA-named `selectable` binding. Enforced by
audit:role-treatments; the surface-vs-bg contrast itself is guarded by the
foundation coherence rail. */
:where([data-role="surface"]) {
background: var(--k-surface);
color: var(--k-fg);
border: 1px solid var(--k-border);
border-radius: var(--k-radius-lg);
box-shadow: var(--k-shadow-sm);
}
/* === Role Canvas · `control` — the generative binding (perceptual role) =====
The most common role; its guarantee is height · focus-ring · hit-target. The
FOCUS ring is already universal (the :focus-visible rule below) and the
hit-target floor picks [data-role="control"] up in the coarse-pointer block,
so the piece the generative binding adds is the HEIGHT invariant — the
proof-of-one-role (--k-control-h-* centralised → zero drift). Bound to the thin
[data-role="control"] (+ an optional [data-size] for the sm/lg tiers), in a
zero-specificity :where() floor so any component (.btn / .in / .select-trigger…)
overrides it while an UNKNOWN control inherits the exact kit height + vertical
centering. */
:where([data-role="control"]) {
display: inline-flex;
align-items: center;
min-height: var(--k-control-h-md);
}
:where([data-role="control"][data-size="sm"]) { min-height: var(--k-control-h-sm); }
:where([data-role="control"][data-size="lg"]) { min-height: var(--k-control-h-lg); }
/* === Role Canvas · `text-slot` — the generative binding (perceptual role) ===
The guarantee: text that must not break the layout. The kit already ships the
explicit `.truncate` utility (24ch cap); this is its ROLE form — an unknown
element tagged [data-role="text-slot"] inherits the single-line clamp and, via
min-width:0, actually shrinks inside a flex parent (the classic truncation
gotcha). Zero-specificity :where() floor; any component overrides it. */
:where([data-role="text-slot"]) {
min-width: 0;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
/* === Role Canvas · `overlay` — the generative binding =======================
A floating list surface must cap its height and scroll the overflow so a long
list can't run off-screen. Bound to the ARIA roles that name a floating list
(role=menu / role=listbox) + a thin [data-role="overlay"] — an UNKNOWN dropdown
inherits the height cap + scroll. Zero-specificity :where() floor; any component
(.menu / .cmdp__list) overrides it. Only the CSS half of the guarantee lives
here: focus-trap / ESC / focus-return are a BEHAVIOUR concern, deliberately
left to the framework or the optional behavior.js shim (the Radix-complement
boundary). NB [role=dialog] is excluded — a modal sizes itself, not from a
dropdown height cap. */
:where([data-role="overlay"], [role="menu"], [role="listbox"]) {
max-height: var(--k-overlay-max, 22rem);
overflow: hidden auto;
}
/* === Role Canvas · `tone-bearer` — the generative binding (perceptual role) =
Unlike the other roles, tone-bearer isn't one treatment but a FAMILY keyed to a
tone VALUE — so it binds to [data-role="tone-bearer"] + [data-tone="…"]. Each
tone maps to the paired --k--soft tint + its --k--soft-fg, the
AA-derived ink the tone-bearer token gate already guarantees legible — so an
UNKNOWN badge/pill/banner tagged with a tone inherits a tint that its text is
provably readable on. Base (no tone) = a neutral chip. Zero-specificity
:where() floor; any component (.badge/.alert/.banner) overrides it. Enforced by
audit:role-treatments (the binding + the paired-ink guarantee). */
:where([data-role="tone-bearer"]) {
background: var(--k-surface-sunken, var(--k-surface-2));
color: var(--k-fg-muted);
}
:where([data-role="tone-bearer"][data-tone="primary"]) { background: var(--k-primary-soft); color: var(--k-primary-soft-fg); }
:where([data-role="tone-bearer"][data-tone="secondary"]) { background: var(--k-secondary-soft); color: var(--k-secondary-soft-fg); }
:where([data-role="tone-bearer"][data-tone="accent"]) { background: var(--k-accent-soft); color: var(--k-accent-soft-fg); }
:where([data-role="tone-bearer"][data-tone="success"]) { background: var(--k-success-soft); color: var(--k-success-soft-fg); }
:where([data-role="tone-bearer"][data-tone="warning"]) { background: var(--k-warning-soft); color: var(--k-warning-soft-fg); }
:where([data-role="tone-bearer"][data-tone="danger"]) { background: var(--k-danger-soft); color: var(--k-danger-soft-fg); }
:where([data-role="tone-bearer"][data-tone="info"]) { background: var(--k-info-soft); color: var(--k-info-soft-fg); }
/* Focus ring — keyboard focus only (avoids mouse-click flashes).
--k-focus-ring-offset is +2px (outset) by default — lifts the ring
off the element for clear visibility on standalone buttons/inputs.
(Modern browsers already wrap the outline around the element's own
border-radius, so no radius override is needed here.) */
:focus-visible {
outline: var(--k-focus-ring-width) solid var(--k-ring);
outline-offset: var(--k-focus-ring-offset);
}
/* Inset focus rings for container-bound children.
System rule: elements that sit inside a tightly-packed parent (tabs row,
segmented control, menu list, table row, nav stack) put the ring INSIDE
their own box. Prevents bleeding into adjacent siblings or parent edges.
Pattern parity with Linear, Notion, Apple HIG, Material 3. */
.tab:focus-visible,
.segctrl__btn:focus-visible,
.menu__item:focus-visible,
.cmdp__item:focus-visible,
.tbl__row:focus-visible,
.navrow:focus-visible,
.accordion summary:focus-visible,
.convo:focus-visible,
.combobox__item:focus-visible,
.tree__row:focus-visible,
.list__row:focus-visible,
.phoneinput__country:focus-visible,
.fab-stack__btn:focus-visible,
.chip__remove:focus-visible,
.taginput__remove:focus-visible,
.calendar__cell:focus-visible,
.kanban__card:focus-visible,
.navsuite__item:focus-visible,
.navmenu__item:focus-visible,
.att-chip__x:focus-visible,
.list__item:focus-visible,
.barchart__bar:focus-visible {
outline-offset: -2px;
}
/* Placeholder — a designed state of every text field, not the browser default.
Faint tier + opacity:1 (Firefox dims placeholders otherwise) so the empty-field
hint is consistent and clears the same quiet contrast everywhere. */
.in::placeholder,
.tx::placeholder,
.searchinput__field::placeholder,
.numinput__field::placeholder,
.pwinput__field::placeholder {
color: var(--k-fg-muted);
opacity: 1;
}
/* Browser autofill — repaint Chrome's native yellow fill back to the kit field
surface (a huge inset box-shadow over the native bg) so an autofilled email/
password keeps the one-family look and stays legible in dark mode, where the
native fill can drop ink to near-invisible. Covers every field shape so they
all inherit it. (See the focus-radius autofill trap.) */
.in:-webkit-autofill, .in:-webkit-autofill:focus,
.tx:-webkit-autofill,
.numinput__field:-webkit-autofill,
.pwinput__field:-webkit-autofill,
.searchinput__field:-webkit-autofill,
.phoneinput__field:-webkit-autofill {
-webkit-text-fill-color: var(--k-fg);
-webkit-box-shadow: 0 0 0 100vmax var(--k-field-bg, var(--k-input-bg)) inset;
caret-color: var(--k-fg);
}
/* Form validation — combine with the input border (use --k-bw for width):
red · .in.is-success green · .in.is-warning amber.
Each state owns ONE coherent ring: border + halo share the state hue so they
read as a single softening ring (not "colored border + separate indigo halo"). */
.in[aria-invalid='true'],
.in.is-error,
.phoneinput--invalid,
.numinput--invalid,
.pwinput--invalid,
.searchinput--invalid {
border-color: var(--k-input-error-border);
}
.in.is-success { border-color: var(--k-input-success-border); }
.in.is-warning { border-color: var(--k-input-warning-border); }
/* Validation borders are SEMANTIC — keep a ≥1px width even when Borders is Off
(--k-bw: 0px), so error/success/warning feedback never vanishes. */
.in.is-error,
.in.is-success,
.in.is-warning,
.in[aria-invalid='true'],
.phoneinput--invalid,
.numinput--invalid,
.pwinput--invalid,
.searchinput--invalid {
border-width: max(1px, var(--k-bw));
border-style: solid;
}
/* State-matched focus halos — border + halo SAME state color → one coherent ring. */
.in[aria-invalid='true']:focus,
.in[aria-invalid='true']:focus-within,
.in.is-error:focus,
.in.is-error:focus-within,
.phoneinput--invalid:focus-within,
.numinput--invalid:focus-within,
.pwinput--invalid:focus-within,
.searchinput--invalid:focus-within {
border-color: var(--k-input-error-border);
box-shadow: 0 0 0 var(--k-ring-w, 3px) color-mix(in srgb, var(--k-input-error-border) 28%, transparent);
}
.in.is-success:focus,
.in.is-success:focus-within {
border-color: var(--k-input-success-border);
box-shadow: 0 0 0 var(--k-ring-w, 3px) color-mix(in srgb, var(--k-input-success-border) 28%, transparent);
}
.in.is-warning:focus,
.in.is-warning:focus-within {
border-color: var(--k-input-warning-border);
box-shadow: 0 0 0 var(--k-ring-w, 3px) color-mix(in srgb, var(--k-input-warning-border) 28%, transparent);
}
/* Pressed / :active tier — the nav families carried a hover wash but no pressed
state, so a tap jumped hover→release with no tactile confirm. Uses the new
--k-state-press layer (a notch stronger than --k-state-hover). Buttons, slider,
numinput, kanban already have their own :active, so they're not duplicated. */
.menu__item:active,
.navrow:active,
.navsub__item:active,
.navmenu__item:active,
.sidenav__toggle:active { background: var(--k-state-press); }
/* Composed-field disabled — plain .in gets :disabled for free, but the wrapper
fields (number/password/search/phone/tag input) hold the disabled
inside, so the WRAPPER needs the dimming. Covers a real [disabled] descendant
(:has) and an explicit [aria-disabled] on the wrapper. */
.numinput:has(:disabled), .pwinput:has(:disabled),
.searchinput:has(:disabled), .phoneinput:has(:disabled),
.taginput:has(:disabled),
.numinput[aria-disabled="true"], .pwinput[aria-disabled="true"],
.searchinput[aria-disabled="true"], .phoneinput[aria-disabled="true"],
.taginput[aria-disabled="true"] {
opacity: var(--k-disabled-opacity, 0.55);
cursor: not-allowed;
pointer-events: none;
}
/* Touch-target floor (WCAG 2.5.5 / 2.5.8) — on a COARSE pointer (touch), tappable
* controls grow to a 44px minimum so they're comfortably hit-able, WITHOUT
* inflating dense desktop (fine-pointer) layouts where this never fires. Covers
* the full interactive roster, not just buttons/inputs: row/item-like controls
* grow vertically (min-height); icon-only controls become 44×44 squares.
* NOTE: sub-token visual controls whose box IS the visual (toggle knob, checkbox/
* radio 16px box, the 3px slider track, the chip × and eye glyphs) are NOT here —
* forcing min-height on them would distort the visual; they need a hit-expanding
* ::after pseudo, which collides with their existing ::after art, so that's a
* separate careful pass. Their text LABEL usually already provides the target. */
@media (pointer: coarse) {
.btn, .in, .select-trigger,
.menu__item, .navsub__item, .navmenu__item, .list__row,
.tab, .segctrl__btn, .calendar__cell, .sidenav__toggle,
.phoneinput__country,
[data-role="control"] { min-height: var(--k-touch-target); }
.btn--icon, .btn--circle,
.lightbox__btn, .alert__close, .banner__close, .toast__close {
min-width: var(--k-touch-target); min-height: var(--k-touch-target);
}
/* iOS-zoom guard — Mobile Safari ZOOMS the page when a focused field's
font-size is < 16px (and never zooms back). Every field uses --k-type-small
(~12-13px), so on a coarse pointer we floor the field text to 16px. Desktop
(fine pointer) keeps the dense --k-type-small. Covers the bare fields, the
custom select/OTP, and the inner of every composed wrapper. */
.in, textarea.in, select.select, .select-trigger, .otp__slot,
.numinput input, .pwinput input, .searchinput input, .phoneinput input,
.taginput input, .cmdp__input, .combobox__input {
font-size: max(var(--k-type-small), var(--k-type-input-min));
}
}
/* ========================================================================
* UIcockpit kit — the design contract (one config → this whole system)
*
* The tier ladder. Style the FOUNDATION once; every layer above inherits it,
* so your UI looks like the configurator preview — not a default.
*
* FOUNDATION — the token layer (colour · type · shape · space · motion, in the
* :root / .dark blocks above) + 5 structural/motion glue upstream of
* the catalog:
* Composition utilities, Button finish, Roll-down item stagger, TwoColumnLayout, Layout primitives
*
* ATOMS — the bare vocabulary (55): the reusable elements with real
* state contracts. Only meaningful inside something larger; these + the tokens
* are what guarantee a consumer's UI looks like the preview.
* Rating, Toolbar, Buttons, Card, Button group, Aspect ratio, Scroll area, Form, Badges & pills, Alert, Tabs, Table, Tooltip, Avatar, Switch / toggle, Slider, Progress, Skeleton, Select trigger, Spinner, Navigation row, Interactive list row, KBD, Code, Accordion, Pagination & breadcrumb, Sparkline, Combobox, Dropdown menu, Stepper, Tag input, Popover, Hover Card, Segmented control / Toggle group, Separator, Description list, Banner, Input OTP, Attachment chip family, Inline status & meta micro-components, Navigation menu, Context menu, Form primitives, NumberInput, PasswordInput, SearchInput, PhoneInput, List, Radio card, Chip, Chat message, Tool call, Reasoning, Citation, Prose
*
* COMPONENTS — stand-alone pieces of app (25), composed FROM the atoms — the
* surface IS the component (dialog, sidebar, data tiles, auth, …).
* Entity card, Action panel, Activity feed, Danger zone, Auth, Lightbox, Calendar, Calendar range, Dialog, Command palette, Chart, Usage meter, Menubar, Resizable, File upload dropzone, Toast stack, Sheet / Drawer, Alert Dialog, Stat tile, Carousel, InfoCard, Timeline, CodeBlock, WizardStepper, Filter bar
*
* SECTIONS — the page-region tier (14): adaptive app frames that ARRANGE
* components per container width (scaffold · nav suite · pane). Sections own
* arrangement, never look; components slot into panes; panes assemble into PAGES
* (your screens).
* Page header, Section, Data table, Empty state, Sidebar, App bar, Calendar week, Calendar year, Pricing, File grid, Form panel, Adaptive scaffold, Nav suite, Pane
* ======================================================================== */
/* === Composition utilities — the mid-tier "phrase book" =================
Named bundles that components are quietly made of, promoted to first-class
classes so an agent reaches for the bundle instead of re-deriving it from
atoms (the coherence-compiler middle tier). Surfaced by the first-customer
build test: each was hand-rebuilt across unrelated components. */
/* Eyebrow — the caps / tracked / muted micro-label (section kickers, table
heads, nav groups, stat labels). Was copy-pasted ~15× as a property block;
this is the canonical bundle (= the former .page-head__eyebrow). */
.eyebrow {
font-size: var(--k-type-eyebrow);
font-weight: var(--k-weight-semibold);
letter-spacing: var(--k-track-eyebrow);
text-transform: uppercase;
color: var(--k-fg-muted);
}
/* Tabular figures — money, counts, timers, IDs keep their column as the value
changes (no horizontal jitter). The single most-reached-for un-named helper. */
.num { font-variant-numeric: tabular-nums; }
/* Metric — the label → tabular-value → sub trio. The extractable CORE of
.stat-tile (minus its card + icon chrome), so any KPI, route leg, score, plan
figure or flight time drops in without re-composing three tokens by hand.
(The build test rebuilt this 4× inside one flight card.) */
.metric { display: flex; flex-direction: column; gap: var(--k-s-2); min-width: 0; }
.metric__label {
font-size: var(--k-type-caption);
font-weight: var(--k-weight-medium);
letter-spacing: var(--k-track-eyebrow);
text-transform: uppercase;
color: var(--k-fg-muted);
}
.metric__value {
font-size: var(--k-type-h2);
font-weight: var(--k-weight-semibold);
font-family: var(--k-font-display);
font-variant-numeric: tabular-nums;
letter-spacing: var(--k-track-display);
line-height: var(--k-leading-tight);
color: var(--k-fg);
}
.metric__sub { font-size: var(--k-type-caption); color: var(--k-fg-muted); }
/* Optional icon slot — for a labelled figure that carries a glyph (a forecast day:
label → icon → value). Sizes your SVG via the icon scale + currentColor. */
.metric__icon { color: var(--k-fg-muted); line-height: 0; }
.metric__icon svg { width: var(--k-icon-md); height: var(--k-icon-md); }
/* Icon-tile — a soft-tinted square holding an icon (stat-tile marks, list leads,
nav glyphs). The tint pair + radius + centering, named once instead of redefined
inline at each owner. */
.icon-tile {
display: inline-grid;
place-items: center;
width: 2rem;
height: 2rem;
flex: none;
border-radius: var(--k-radius-md);
background: var(--k-primary-soft);
color: var(--k-primary-soft-fg);
}
.icon-tile svg { width: var(--k-icon-md); height: var(--k-icon-md); }
/* Scrubber — a media transport progress (audio/video player): a sunken track, a
played fill, and a draggable-looking knob at the playhead. The mid-tier media
idiom .progress (display-only, no handle) and .slider (a form control) both miss.
Visual only — wire the seek/drag + value yourself (behaviour contract). Set the
played amount inline: .scrubber__fill width + .scrubber__knob left = the %. */
.scrubber { position: relative; height: var(--k-s-4); border-radius: 999px; background: var(--k-surface-sunken); cursor: pointer; }
.scrubber__fill { position: absolute; inset: 0 auto 0 0; border-radius: 999px; background: var(--k-primary); }
.scrubber__knob {
position: absolute;
top: 50%;
width: var(--k-s-12);
height: var(--k-s-12);
border-radius: 50%;
background: var(--k-surface);
border: max(1.5px, var(--k-bw)) solid var(--k-primary);
box-shadow: var(--k-shadow-sm);
transform: translate(-50%, -50%);
}
/* Canvas — the brand-atmosphere background (the radial mesh behind premium heroes,
landing sections, app shells). The --k-canvas token is otherwise buried in a
token comment; naming it as a class is the discoverability fix — an agent reaches
for class="canvas" instead of hand-rolling a gradient off-grammar. Full-bleed:
sit content on top; pair with .eyebrow + a headline for a hero. */
.canvas { background: var(--k-canvas); }
/* === Rating ============================================================
A star scale for reviews / products / recipes / restaurants. Read-only
display: render N filled stars + the rest as .rating__star--empty, with an
optional .rating__count ("4.8" or "(120)"). The kit has no dedicated rating
colour, so a filled star borrows the warning tone's amber — a contrast-safe
gold. Pass star SVGs as children; the scale rides --k-icon-sm. */
.rating { display: inline-flex; align-items: center; gap: var(--k-s-2); color: var(--k-rating); line-height: 0; }
.rating > svg { width: var(--k-icon-sm); height: var(--k-icon-sm); flex: none; }
.rating__star--empty { color: var(--k-border); }
.rating__count { margin-inline-start: var(--k-s-4); font-size: var(--k-type-caption); color: var(--k-fg-muted); line-height: 1; }
/* === Toolbar ===
A composition primitive: a horizontal row of controls (search, filters,
selects, action buttons) that GUARANTEES every direct control child shares
one height. Tokens make values consistent; they can't stop you putting a
.btn--sm next to a default .in — this recipe can. It forces all direct
.btn / .in / .select / .select-trigger children onto a single shared
height (--tb-h), so adjacent controls always line up regardless of the
size modifier each carries. Use .toolbar instead of a bare .card__row
whenever you place mixed controls side by side.
.toolbar → md height (the stature default; matches plain controls)
.toolbar--sm → compact bar (dense app/table toolbars)
.toolbar__spacer → flex gap that pushes trailing controls to the right */
.toolbar {
--tb-h: var(--k-control-h-md);
display: flex;
align-items: center;
/* The gap here separates UNRELATED items/groups — comfortable (--k-space).
RELATED controls (a filter pair, a label+select, a button cluster) go in a
.toolbar__group, which sits tight (8px). Two gap levels = the eye reads
what belongs together. This is the structural answer to "buttons should be
closer than separate groups": grouping, not one flat gap. */
gap: var(--k-space, 8px);
flex-wrap: wrap;
}
.toolbar--sm { --tb-h: var(--k-control-h-sm); }
/* A cluster of related controls — tight 8px between members, so an [Epic][Type]
filter pair reads as one unit while still sitting --k-space away from the
search field or the avatar stack. */
.toolbar__group {
display: inline-flex;
align-items: center;
gap: var(--k-gap, var(--k-s-8));
}
/* An inline label that names the control next to it ("Group by", "Sort"). The
eyebrow tier so it reads as a quiet annotation, not a control. A reusable
primitive instead of ad-hoc inline styles, so a label+select cluster is
rebuildable from the export — not preview-only. NOT in the height-invariant
selector below: it's text, vertically centered by the group, not a control. */
.toolbar__label {
font-size: var(--k-type-eyebrow);
font-weight: var(--k-weight-medium);
color: var(--k-fg-muted);
text-transform: uppercase;
letter-spacing: var(--k-track-eyebrow);
white-space: nowrap;
}
/* Height is forced on controls whether they sit directly in the bar or inside
a group, so grouping never breaks the one-height invariant. */
.toolbar > .btn,
.toolbar > .in,
.toolbar > .searchinput,
.toolbar > .select,
.toolbar > .select-trigger,
.toolbar > .segctrl,
.toolbar__group > .btn,
.toolbar__group > .in,
.toolbar__group > .searchinput,
.toolbar__group > .select,
.toolbar__group > .select-trigger,
.toolbar__group > .segctrl {
min-height: var(--tb-h);
height: var(--tb-h);
}
/* C8 — the invariant is DEFAULT-ON. The enumerated controls above get an EXACT
height; every OTHER direct child of the bar (or a group) gets the bar height
as a FLOOR, so a control the kit hasn't listed (numinput, taginput, slider, a
future atom) can't silently escape and break the single-height row. Opt-outs
are the non-controls: the inline label (text) and the spacer (empty flex). */
.toolbar > *,
.toolbar__group > * {
min-height: var(--tb-h);
}
.toolbar > .toolbar__label,
.toolbar__group > .toolbar__label,
.toolbar > .toolbar__spacer {
min-height: 0;
}
.toolbar__spacer { flex: 1 1 auto; min-width: 0; }
/* === Buttons ===
Horizontal padding uses max() against --k-radius-md so it scales when
the user picks a larger radius. At pill (md=26px) the curve dominates
the visual width, so we expand padding to keep the label clear of the
curve — a best-practice rule of thumb: padding-inline >= radius * 0.75. */
.btn {
display: inline-flex;
align-items: center;
justify-content: center;
gap: var(--k-s-6);
/* Default button height is Scale-driven and equals the input height per tier:
* Compact → 32px · Default → 36px · Comfortable → 40px (shadcn h-8/9/10 family).
* Padding-block is 0 because min-height + flex centering handles vertical
* positioning, and removing padding-block keeps the height exact. */
min-height: var(--k-btn-h, var(--k-btn-h-default, 36px));
padding-block: 0;
/* Horizontal padding scales with TWO dimensions:
* 1. Button height (Scale drives 32/36/40px) — taller buttons need
* more side padding to stay optically balanced. height × 0.4
* matches Apple HIG / Material defaults.
* 2. Pill detection — when --k-radius-button is huge (999px), the
* curve eats horizontal space, so we add a pill-only bump
* proportional to height (≈ ×0.55) so the label clears the curve.
* Clamped to 0.55×height to keep pill+bold from going absurd.
* The 14px floor + radius-md fallback stay as safety nets. */
/* --btn-r: the radius THIS button family uses. Solid buttons (primary/
secondary/danger) follow the button-radius token; ghost controls override
it to the box radius below — they read as fields / quiet toolbar controls,
not buttons, so "Button radius" shouldn't reshape them. One var drives BOTH
the corner and the pill-aware padding so they can never disagree. */
/* Comp-tier hook (H2 lazy override): --k-btn-radius is NEVER defined by
default — zero bytes until a consumer/agent sets it ("square corners on
just my buttons"). Same pattern on the other hooks below. */
--btn-r: var(--k-btn-radius, var(--k-radius-button, var(--k-radius-md)));
padding-inline: max(
14px,
calc(var(--k-radius-md) * 0.75),
calc(var(--k-btn-h-default, 34px) * 0.4),
min(
calc(var(--btn-r) * 0.5),
calc(var(--k-btn-h-default, 34px) * 0.55)
)
);
border-radius: var(--btn-r);
font-size: var(--k-type-small);
font-weight: var(--k-ui-weight, 600);
/* line-height: 1 collapses the text line-box to exactly its font-size,
so the label centers cleanly against icons via align-items: center.
Without this, inherited 1.15-1.5 line-heights make the text box taller
than the icon, and the visual baseline of glyphs drifts a pixel or two
above/below the icon's optical center. */
line-height: 1;
text-transform: var(--k-ui-transform, none);
letter-spacing: var(--k-ui-tracking, 0);
font-family: var(--k-font-body);
/* Unified motion — every button animates bg + transform + shadow + filter
* on the same tokens, so hover-lift and the click-press feel consistent
* across primary/secondary/ghost/outline/link/icon. */
transition:
background var(--k-dur, 200ms) var(--k-ease, ease),
transform var(--k-dur-fast, 120ms) var(--k-ease, ease),
box-shadow var(--k-dur-fast, 120ms) var(--k-ease, ease),
filter var(--k-dur-fast, 120ms) var(--k-ease, ease),
border-radius var(--k-dur-fast, 120ms) var(--k-spring, var(--k-ease, ease));
border: max(1px, var(--k-bw)) solid transparent;
cursor: pointer;
}
/* Unified press — what :active does: a 0.96 scale squish (the house feel).
* Generic so ghost/outline/link get it too. */
.btn:active:not(:disabled) {
transform: scale(0.96);
}
/* SVG icons inside buttons should never shrink and should render as a
* standalone flex item, not as inline-text-baseline content. Most preview
* usage already passes display:block via Lucide, but explicit-here guards
* against fonts/icons that use vertical-align tricks. */
.btn > svg {
flex-shrink: 0;
display: block;
}
/* === Button finish — configurable signature ===========================
* Three finishes ship out of the box, picked via cfg.buttonFinish:
* clean → soft ambient shadow, no top-highlight, no pressed-inset (default).
* tactile → top-edge highlight + pressed-inset on :active (macOS-native).
* soft → larger ambient shadow + bigger lift (Notion/Linear floating).
* The recipe references three tokens — they're computed in buildTokens
* based on the user's finish choice. Spring + hover-lift are constant
* across all three so every finish feels "alive". */
/* The LOUD tier — the AIMED ACCENT (CP2 / confident-pro gap #4). Only the
* primary and the destructive primary carry a brand fill AND a resting lift +
* shadow. That elevation is the "one aimed accent per surface" rule made
* structural: in any button row, exactly one control rises off the surface and
* wears colour, so the eye lands on THE action without being told. Everything
* quieter (secondary/ghost/outline/link) stays flat. */
.btn--primary,
.btn--danger {
box-shadow: var(--k-btn-shadow, var(--k-shadow-sm));
transition:
background var(--k-dur, 200ms) var(--k-ease, ease),
transform var(--k-dur-fast, 140ms) var(--k-ease-spring, cubic-bezier(.34,1.56,.64,1)),
box-shadow var(--k-dur-fast, 140ms) var(--k-ease-spring, cubic-bezier(.34,1.56,.64,1));
}
.btn--primary:hover:not(:disabled),
.btn--danger:hover:not(:disabled) {
transform: translateY(var(--k-btn-lift, -1px));
}
/* The aimed-accent press — a Material state-layer darken on top of the unified
* scale-press, and the resting lift collapses (shadow → press) so the button
* physically depresses on the spring curve. The feedback you FEEL (gap #3). */
.btn--primary:active:not(:disabled),
.btn--danger:active:not(:disabled) {
filter: brightness(0.94);
box-shadow: var(--k-btn-shadow-press, none);
}
.btn--primary { background: var(--k-btn-bg, var(--k-primary)); color: var(--k-btn-fg, var(--k-primary-fg)); }
.btn--primary:hover { background: var(--k-primary-hover); }
/* The QUIET NEUTRAL tier — secondary is a FLAT GREY button (shadcn's neutral
* secondary), not a brand fill. No resting shadow, no lift: it sits beside the
* primary without competing for the eye. Hover deepens toward --k-fg (mode-
* correct: darkens on light, lightens on dark). This is the change that turns
* "brand sprinkled across buttons" into "one aimed accent". */
.btn--secondary {
background: var(--k-neutral);
color: var(--k-neutral-fg);
transition:
background var(--k-dur-fast, 140ms) var(--k-ease, ease),
transform var(--k-dur-fast, 120ms) var(--k-ease, ease);
}
.btn--secondary:hover:not(:disabled) { background: color-mix(in srgb, var(--k-neutral), var(--k-fg) 7%); }
.btn--secondary:active:not(:disabled) { filter: brightness(0.97); }
/* Ghost = the quietest control (toolbar filter, dropdown trigger, secondary icon
action), NOT a primary button — so it follows the box/field radius, not the
button-radius. Keeps "Button radius" scoped to actual filled buttons. For a
real button pair (Cancel next to Save), use .btn--secondary, not ghost.
BORDERLESS (B★3): a ghost is text + a hover wash — no resting border, so it
reads distinctly quieter than .btn--outline (which IS the bordered-quiet
variant) and toolbars/icon-buttons stop looking boxy. The shadcn ghost. */
.btn--ghost { background: transparent; color: var(--k-fg); border-color: transparent; }
.btn--ghost:hover { background: var(--k-state-hover); }
.btn--danger { background: var(--k-danger); color: var(--k-danger-fg); }
/* Outline = the shadcn outline variant: neutral surface + foreground text +
subtle border + a hairline shadow-xs lift. Colour lives on the glyph (Google
logo etc.), NOT the label — a coloured-text outline reads louder than a quiet
secondary should. (Was primary-text/primary-border, which competed with the
real primary CTA.) */
.btn--outline { background: var(--k-surface); color: var(--k-fg); border-color: var(--k-border); box-shadow: var(--k-shadow-xs); }
.btn--outline:hover { background: var(--k-state-hover); }
.btn--link {
background: transparent;
color: var(--k-primary);
padding-inline: 0;
padding-block: 0;
text-decoration: underline;
text-underline-offset: 3px;
}
.btn--link:hover { color: var(--k-primary-hover); }
/* Icon buttons — always a perfect 1:1 square. Previously used asymmetric
* padding (6px 8px) which let the glyph width drive the button width, so
* a heart vs a magnifier vs a chevron all rendered different aspect ratios
* AND the shape morphed when stature / radius changed. Now the geometry
* is decoupled from content: aspect-ratio + matching min-w/h, padding 0.
* Border-radius still follows --k-radius-button so sharp themes get
* rounded-square icon buttons, pill themes get circles. For things that
* must ALWAYS be round (FAB, save/wishlist, story rings) add .btn--circle. */
.btn--icon {
width: var(--k-in-h-default);
height: var(--k-in-h-default);
min-width: var(--k-in-h-default);
padding: 0;
justify-content: center;
aspect-ratio: 1;
}
/* Icon buttons stay square at every size — re-assert padding:0 so the later
.btn--sm / .btn--lg padding-inline doesn't squish the glyph's flex box
(was collapsing icons to ~3px; most visible with thin/small-dot icons). */
.btn--icon.btn--sm { width: var(--k-row-h-sm); height: var(--k-row-h-sm); min-width: var(--k-row-h-sm); padding: 0; }
.btn--icon.btn--lg { width: var(--k-control-h-lg); height: var(--k-control-h-lg); min-width: var(--k-control-h-lg); padding: 0; }
/* Always-round modifier — for FAB / wishlist / save buttons that should
* read as a circle regardless of theme radius. Pairs with .btn--icon so
* the geometry is square and the 999px radius lands as a perfect circle. */
.btn--circle { border-radius: 999px; }
/* Toggle button (H4) — a press-and-STAY .btn, driven by aria-pressed (the
* consumer flips the attribute; CSS owns both looks). Compose with a quiet
* tier (.btn--outline / .btn--ghost): off = that quiet resting look, on =
* the SECONDARY container — selection wears a container, primary stays the
* one loud CTA (same rule as .chip--filter). The round⇄square shape axis
* comes free: switching on morphs the corner from the button radius down to
* the box radius, so pill themes get the M3-Expressive pill→rounded-square
* toggle signature and the existing border-radius spring animates it. Sharp
* themes morph nothing (the min() collapses) — shape stays a signal here,
* never a second look. */
.btn--toggle[aria-pressed="true"] {
background: var(--k-secondary-soft);
color: var(--k-secondary-soft-fg);
border-color: transparent;
border-radius: min(var(--btn-r), var(--k-radius-md));
box-shadow: none;
}
.btn--toggle[aria-pressed="true"]:hover:not(:disabled) {
background: var(--k-secondary-soft);
filter: brightness(0.97);
}
/* Size variants — same height/pill-aware padding logic as the base .btn,
* just with smaller/larger floors. The "row-h" tokens give us the right
* intrinsic height per tier so the height×0.4 / pill×0.55 math lands
* proportional even when the user overrides .btn size explicitly. */
.btn--sm {
min-height: var(--k-row-h-sm, 28px);
padding-block: 0;
padding-inline: max(
10px,
calc(var(--k-radius-md) * 0.6),
calc(var(--k-row-h-sm, 28px) * 0.4),
min(
calc(var(--btn-r) * 0.5),
calc(var(--k-row-h-sm, 28px) * 0.55)
)
);
font-size: var(--k-type-eyebrow);
}
.btn--lg {
min-height: var(--k-control-h-lg);
padding-block: 0;
padding-inline: max(
18px,
calc(var(--k-radius-md) * 0.85),
calc(var(--k-control-h-lg) * 0.4),
min(
calc(var(--btn-r) * 0.5),
calc(var(--k-control-h-lg) * 0.55)
)
);
font-size: var(--k-type-body);
}
/* H4 ramp ends — XS (the densest toolbar/table-row action) and XL (the "big
* central action": M3-Expressive's hero button; our deliberate FAB
* replacement — same prominence, no floating Android cosplay). */
.btn--xs {
min-height: calc(var(--k-row-h-sm, 28px) - 0.25rem);
padding-block: 0;
padding-inline: max(
8px,
calc(var(--k-radius-md) * 0.5),
min(calc(var(--btn-r) * 0.4), calc(var(--k-row-h-sm, 28px) * 0.45))
);
font-size: var(--k-type-caption);
}
.btn--xl {
min-height: calc(var(--k-control-h-lg) + 1rem);
padding-block: 0;
padding-inline: max(
24px,
calc(var(--k-radius-md) * 1),
calc(var(--k-control-h-lg) * 0.5),
min(calc(var(--btn-r) * 0.5), calc(var(--k-control-h-lg) * 0.7))
);
font-size: var(--k-type-h3);
}
.btn--link { border-radius: 0; } /* Link buttons never want a button-radius pill */
/* Full-width block button — fills its container, label stays centered. The
* dominant card-footer CTA pattern (Save / Review order / Update security).
* Composes with any variant + size. */
.btn--block { width: 100%; }
/* Loading — width-locked spinner state. The button's element children fade to
* opacity:0 (keeping the button's width so it doesn't collapse) and a centred
* spinner draws in the button's own currentColor; pointer events are blocked.
* Wrap the label in an element (label or an icon) — a bare text
* node can't be hidden by > *. Pair with aria-busy="true" + disabled on the
* control for the a11y half. Honours reduced-motion via the k-spin token. */
.btn--loading { position: relative; pointer-events: none; }
.btn--loading > * { opacity: 0; }
.btn--loading::after {
content: '';
position: absolute;
top: 50%;
left: 50%;
width: 1em;
height: 1em;
margin: -0.5em 0 0 -0.5em;
border: 2px solid currentColor;
border-top-color: transparent;
border-radius: 50%;
animation: var(--k-anim-spin, k-spin 800ms linear infinite);
}
/* Stacked action buttons (Save / Cancel) sit on the TIGHT --k-stack-gap (8 at
* default), not the wider field rhythm they'd otherwise inherit from the card's
* flex gap. The negative margin nets the flex gap (--k-space) down to --k-stack-
* gap. shadcn pattern: form fields space-y-4/6, action buttons gap-2. */
.card > .btn--block + .btn--block,
.dialog > .btn--block + .btn--block,
.card__col > .btn--block + .btn--block {
margin-top: calc(var(--k-stack-gap, 8px) - var(--k-space, 16px));
}
/* === Card ================================================================
* The fundamental surface container: a bordered, rounded, padded box on the
* --k-surface plane that holds any component. Anatomy — .card__head (title +
* desc), the flex body (default), .card__row / .card__col for inline / stacked
* control clusters, and a hairline-divided .card__foot action zone. Padding
* follows --k-pad (the card minimum); the internal rhythm follows --k-space so
* raising padding never balloons the gaps (the shadcn p-6 / space-y split). */
.card {
display: flex;
flex-direction: column;
gap: var(--k-space, 16px);
box-sizing: border-box;
margin: 0;
/* --k-card-* = lazy comp-tier hooks (H2): undefined by default, override
per-scope to restyle JUST cards without touching the system tokens. */
padding: var(--k-card-pad, var(--k-pad, 24px));
background: var(--k-card-bg, var(--k-surface));
color: var(--k-fg);
border: 1px solid var(--k-card-border-color, var(--k-border));
border-radius: var(--k-card-radius, var(--k-radius-lg));
box-shadow: var(--k-shadow-sm);
}
/* Interactive — a whole card that's one click target (link/button card). Adds
the affordance the base .card lacks: pointer, a hover lift, an :active press,
and a focus ring. Put it on a