---
name: design-system
description: 'Shared UI components and design patterns for carbonid1 apps built on @carbonid1/design-system. ALWAYS use when building UI, creating components, styling Typeset or Markdown prose, adding dropdowns, selects, tooltips, icons, toasts, context menus, badges, or any interactive element. Triggers on: dropdown, select, tooltip, tag, badge, icon, component, UI, typeset, prose, Markdown rendering, using the design system, layout shift, skeleton, context menu, right-click menu, button, theme, palette. To MODIFY @carbonid1/design-system itself — add or change a primitive, token, variant, or the barrel/exports — use the design-system-package skill instead.'
---

# Design System

Primitives live in `@carbonid1/design-system`. **Check the package's exports and types before building anything new.** This file is direction and taste, not API reference — the types are the docs.

```ts
import {
  Badge,
  Button,
  buttonVariants,
  Kbd,
  ProgressRing,
  Slider,
  ContextMenu,
  Select,
  Tooltip,
  Toaster,
  toast,
  ThemeProvider,
  ThemeCycler,
  useTheme,
  cn,
  getModKey,
  useHotkeys,
} from '@carbonid1/design-system'
```

Palettes are chosen by importing one theme CSS per app: `@carbonid1/design-system/themes/reader` (InkVoice) or `/themes/dashboard` (CoI Calculator).

If you're editing `@carbonid1/design-system` itself (adding a primitive, changing a token), use the `design-system-package` skill — this file is for _using_ the design system, not building it.

## Core rules

- Never build a tooltip, context menu, or toast from scratch — use `Tooltip`, `ContextMenu`, `toast()`
- All icons from `lucide-react` — search `lucide.dev/icons` before creating anything custom. If nothing fits, build via Lucide's `Icon` + `iconNode`, don't reach for another library.
- All color through semantic tokens — no hardcoded Tailwind color classes. See [references/theming.md](references/theming.md).
- **Missing a token or primitive? Surface it, don't invent one.** When the palette has no token — or the package no component — for what you're building, stop and ask the user, offering 2–3 concrete paths (extend the design system, compose what's already there, or a deliberately-scoped one-off). A silent one-off forks the system: these tokens exist so a single decision propagates everywhere, and a bespoke color or component quietly breaks that. Asking is cheap; an unnoticed fork is expensive to unwind later.
- Tooltip: rely on defaults (`position="top"`, `delay={400}`). Only override when the default is wrong (e.g. header → `position="bottom"`, data-viz progressive disclosure → `delay={600}`, a snappy reveal → a lower `delay`). When a tooltip trigger also opens a popover, pass `disabled={open}`.
- Icon toggle state: `<Icon fill={active ? 'currentColor' : 'none'} />` — not two different components.

## Typeset prose

Typeset owns semantic document presentation; the application still owns parsing, streaming, and
custom component rendering.

```css
@import '@carbonid1/design-system/typesets/base';
@import '@carbonid1/design-system/typesets/compact';
```

Apply `typeset typeset-compact` to the rendered document root. Import the base stylesheet once, then
only the presets that application uses. Add `.not-typeset` or `[data-not-typeset]` around injected
application components that must retain their own design-system styling.

## Buttons & links

- **Active/selected state** — pass `selected` (toolbar toggles, segmented controls, filter chips, tabs, nav links). It applies the selection tokens (`bg-primary/10` + `ring-1 ring-primary/20`, tint held on hover); never hand-layer those classes. `selected` is visual only — set the matching ARIA yourself: `aria-pressed` on toggle buttons, `aria-current` on nav links. It rides both `Button` and `buttonVariants(...)`.
- **Dialog actions** — `Dialog.Trigger` and `Dialog.Close` supply behavior, not button appearance. Compose a `Button` through `render` so one component owns the complete visual contract; don't attach `buttonVariants(...)` to the behavior primitive.
  ```tsx
  <Dialog.Close
    render={
      <Button variant="ghost" size="small">
        Cancel
      </Button>
    }
  />
  ```
- **A link that looks like a button** — apply `buttonVariants({ variant, size, selected })` to the `Link`, not `<Button render={<Link/>}>`. Base UI's `Button` is button-semantic: rendering an `<a>` through it either warns or forces `role="button"`, which breaks navigation for screen readers. Keep the element a real link and style it:
  ```tsx
  <Link
    href={href}
    aria-current={active ? 'page' : undefined}
    className={cn(buttonVariants({ variant: 'ghost', size: 'small', selected: active }))}
  >
    {label}
  </Link>
  ```
  The `cn(...)` wrap is load-bearing, not cosmetic: `buttonVariants` is cva, which concatenates without merging, so only `cn` (tailwind-merge) drops the variant's own `hover:bg-accent` in favor of the `selected` tint.

## Visual Language

- **Discrete elements** — rows/cards use `rounded-lg` with `space-y-1` gaps, never flat lists with hairline dividers
- **Selection** — `bg-primary/10` tint + `ring-1 ring-primary/20`, never border-left accents
- **Hover reveal** — action buttons use `opacity-0 group-hover:opacity-100 group-focus-within:opacity-100` with outer row `hover:bg-accent`. The `group-focus-within` is required — without it, keyboard users tab to an invisible button.
- **Metadata** — use the quietest representation that preserves scanning. Reserve
  badges/chips for concise categorical states, filters, or individually
  interactive values; prefer secondary text, alignment, grouping, icons, or
  restrained surface tone for routine facts. Do not expose an internal category
  or repeat information merely because a `Badge` primitive exists.
- **Touch targets** — icon buttons `p-1.5` minimum, icons `w-4 h-4` minimum
- **Avatars** — only with real images, no letter/initial placeholders

## Elevation

Four-tier contract — every themed surface picks one of these tokens. Layering is recessed: cards are sheets on the desk, controls are carved INTO sheets, popovers lift OFF the desk.

| Token              | Role                                    | Pair with              |
| ------------------ | --------------------------------------- | ---------------------- |
| `bg-background`    | Page (the desk)                         | —                      |
| `bg-card`          | Raised paper on the desk — peak surface | `shadow-card`          |
| `bg-surface-inset` | Inset block carved into a card          | `inset-shadow-surface` |
| `bg-popover`       | Floating layer above everything         | `shadow-popover`       |

`bg-surface-inset` covers form inputs, preview boxes, quote blocks, and language tabs. `bg-popover` covers drawers, menus, and command palettes.

**`bg-muted`, `bg-accent`, `bg-secondary` are RESERVED for interaction states** — hover backgrounds, skeleton placeholders, badge fills, soft tints. They are never the background of a card or an inset block. Mixing them in breaks the layering contract; see [references/theming.md](references/theming.md) for the deeper rationale.

**Empty placeholders** — when a slot is meant to be filled (`AddBookCard`, file drop zone, audio preview slot before recording), render a transparent or background-matched surface with `border-dashed`. The empty state reads as a missing piece on its parent surface — never as a recessed input or a card. Once filled, swap to a solid border and the surface adopts its real elevation.

## Destructive Actions

Two tiers. Pick by how hard the action is to redo, not how scary it feels.

| Severity         | Pattern                      | Example                              |
| ---------------- | ---------------------------- | ------------------------------------ |
| **Hard to redo** | Undo toast (5s + Cmd/Ctrl+Z) | Delete a record, remove history item |
| **Easy to redo** | No confirmation              | Toggle flag, remove a tag            |

**Undo toast:** action executes immediately → toast with description `${getModKey()}+Z to undo` + "Undo" action button (5s auto-dismiss) → store holds `lastDeleted` for restoration → global `mod+z` hotkey via `useHotkeys` (re-exported from the design system) → sequential deletes overwrite the buffer (only latest is undoable). Never add a modal confirmation for hard-to-redo actions — the undo toast is the confirmation.

## Layout Stability

Skeleton → real UI transitions must not shift layout. The skeleton is a dimensional contract.

- Skeletons match real UI structure, counts, heights, spacing. Update the skeleton when the real UI changes.
- Async elements that always render (selectors, user controls) show a same-sized placeholder while loading — never `null`.
- Doesn't apply to user-triggered UI (modals, drawers, toasts) or conditional banners — these are unpredictable by nature.

## Theming

`ThemeProvider` wraps the app (toggles `.dark` via `next-themes`). `ThemeCycler` mounts once to register `Shift+T` for cycling system → light → dark. `useTheme` is the next-themes re-export for programmatic access.

Both palettes define the same token names on `:root` + `.dark`, so primitive code and consumer code don't care which palette is active.
