Kaotypr Design System cheat sheet

bg-background

the page itself, the lowest layer

bg-card

elevated content blocks (article cards, dashboard tiles, list rows that read as separate)

bg-popover

transient floating layers (dropdowns, tooltips, command palettes, comboboxes, datepickers)

bg-muted

low-emphasis fills inside a card or surface (input wells, deemphasized sections, code blocks, sidebar groups)

bg-secondary

secondary buttons, badges, low-emphasis interactive controls (NOT a backdrop)

bg-accent

highlight surface for active nav items, selected list rows, current-step indicators

text-foreground

primary body text, headings, labels — the default

text-foreground-subtle

captions, helper text, deemphasized headings (still legible)

text-muted-foreground

muted body copy on bg-muted, placeholders that aren't using --placeholder-color, ancillary metadata

text-foreground-disabled

disabled control labels — never use for design choice, only for disabled state

border-border

default outlines, dividers between sibling cards

border-border-subtle

low-contrast separators inside a card, table row dividers, list item separators

border-border-strong

emphasized outlines, hover/active outlines on cards, table column separators in dense layouts

border-input

form inputs only (slightly stronger than -subtle for affordance)

rounded-input

form inputs, search boxes, single-line text controls

rounded-button

buttons, icon buttons, segmented controls

rounded-chip

tags, filter pills, badges, status chips (pill-shaped)

rounded-card

content cards, dashboard tiles, list-row cards

rounded-popover

dropdowns, tooltips, comboboxes, hover cards

rounded-dialog

modal dialogs, alert dialogs (always centered, scrim behind)

rounded-sheet

side sheets, drawers, mobile bottom sheets

shadow-card

content cards at rest

shadow-popover

floating layers (dropdowns, tooltips, comboboxes)

shadow-overlay

modal dialogs and side sheets — the highest elevation

shadow-focus

focus-ring glow on inputs (paired with the ring token)

shadow-inset

pressed states, sunken wells, scrollable region indicators

bg-state-hover

hover affordance on buttons, list rows, nav items (4–6% layer)

bg-state-focus

keyboard-focus background — usually paired with the focus ring

bg-state-active

pressed state (8–12% layer)

bg-state-expanded

open/expanded affordance: aria-expanded='true' on triggers, current open menu item

bg-state-selected

persistent selection: selected row in a table, picked option in a list, current step in a wizard

duration-instant

0ms — feedback that should feel immediate (toggle flips, focus rings); also the motion-reduce: fallback

duration-fast

micro-interactions: hover, ripple, tooltip show, pressed feedback

duration-normal

layout reveals, panel slides, accordion expand, tab content swap

duration-slow

page transitions, large surface entrances, modal open

duration-slower

confidence-builder moments only (success animations, celebratory reveals)

max-w-(--container-prose)

article-style reading content, ~65ch — comfortable for body copy

max-w-(--container-content)

marketing pages, single-column docs, narrow forms

max-w-(--container-dashboard)

app shells with sidebars, multi-column dashboards (default for product UI)

max-w-(--container-wide)

data-heavy tables, design canvases, full-bleed dashboards

<div className="flex gap-3 rounded-card border bg-{status} text-{status}-foreground border-{status}-border p-4">
  <Icon weight="fill" className="size-5 shrink-0" />
  <div>
    <p className="font-medium">Title</p>
    <p className="text-sm opacity-90">Body</p>
  </div>
</div>

<Badge className="bg-success text-success-foreground border border-success-border">
  Active
</Badge>

<div className="rounded-card bg-card text-card-foreground shadow-card ring-1 ring-border-subtle p-(--density-card-padding)">
  …
</div>

className="focus-visible:outline-none focus-visible:ring-(length:--ring-width) focus-visible:ring-ring/40 focus-visible:border-ring"

className="hover:bg-state-hover active:bg-state-active aria-expanded:bg-state-expanded"

<DialogOverlay className="fixed inset-0 bg-overlay z-overlay" />
<DialogContent className="z-modal rounded-dialog bg-popover text-popover-foreground shadow-overlay" />

<SheetContent className="z-modal rounded-sheet bg-popover text-popover-foreground shadow-overlay">
  …
</SheetContent>

<PopoverContent className="z-popover rounded-popover bg-popover text-popover-foreground shadow-popover border-border-subtle">
  …
</PopoverContent>

<TooltipContent className="z-tooltip rounded-popover bg-popover text-popover-foreground shadow-popover px-2 py-1 text-xs">
  …
</TooltipContent>

<Toast className="z-toast rounded-card bg-card text-card-foreground shadow-overlay border-border-subtle p-4">
  …
</Toast>

<div className="flex flex-col items-center gap-3 rounded-card bg-muted/40 border border-border-subtle p-(--density-card-padding) text-center">
  <Icon className="size-(--size-icon-lg) text-muted-foreground" />
  <p className="font-medium">No items yet</p>
  <p className="text-sm text-muted-foreground">Get started by creating one.</p>
</div>

<div className="rounded-card bg-card border border-border-subtle p-(--density-card-padding) space-y-3">
  <div className="h-4 w-1/3 rounded bg-muted animate-pulse" />
  <div className="h-3 w-2/3 rounded bg-muted animate-pulse" />
</div>

<label className="flex flex-col gap-1.5">
  <span className="text-sm font-medium">Email</span>
  <input
    type="email"
    className="h-(--density-control-h) rounded-input border-input bg-background px-3 text-base md:text-sm focus-visible:outline-none focus-visible:ring-(length:--ring-width) focus-visible:ring-ring/40 focus-visible:border-ring"
  />
</label>

<a
  href="#"
  data-active={isActive}
  className="flex items-center gap-2 rounded-input px-3 h-(--density-control-h) text-sm hover:bg-state-hover data-[active=true]:bg-state-selected data-[active=true]:text-foreground"
>
  …
</a>

<html data-density="compact"> {/* or scope to a section */}
  …controls auto-tighten via --density-* tokens
</html>

const palette = Array.from({ length: 12 }, (_, i) => `var(--color-chart-${i + 1})`);
<Bar fill={palette[0]} /> // anchored to brand

<motion.div
  initial={{ opacity: 0 }}
  animate={{ opacity: 1 }}
  transition={{ duration: 0.4 }}
  className="motion-reduce:!duration-(--duration-instant)"
/>

Either gate behind motion-safe: or collapse to --duration-instant under motion-reduce:.