---
name: design-system
description: Build or edit app UI using @carbonid1/design-system. For changes to the shared package itself, use design-system-package.
---

# Design System

Use `@carbonid1/design-system` primitives and semantic tokens. Check the relevant
exports and types before adding a component; they are the API reference.

## Shared constraints

- Use `Tooltip`, `ContextMenu`, and `toast()` for those interactions.
- Use `lucide-react` icons. Search the Lucide icon catalog before creating a
  custom icon with Lucide's `Icon` and `iconNode`.
- Use semantic color tokens. Surfaces use `bg-background`, `bg-card` with
  `shadow-card`, `bg-surface-inset` with `inset-shadow-surface`, or `bg-popover`
  with `shadow-popover`. Reserve `bg-muted`, `bg-accent`, and `bg-secondary` for
  interaction states and fills, never card or inset surfaces.
- For a missing capability, compose existing primitives when they satisfy the
  requirement. If the task requires extending the shared package and that work
  is within the authorized scope, use `design-system-package` and continue.
  Ask when an unresolved product decision or work beyond that scope needs user input. Keep
  reusable tokens and primitives in the package; avoid silent app-local forks.

## Visual language

- Rows and cards use `rounded-lg` with `space-y-1` gaps, not hairline dividers.
- Selected buttons and button-styled links use `selected` with the appropriate
  ARIA state. The system owns the selection tint and ring; avoid border-left
  accents. See the controls reference for composition details.
- Hover actions use `opacity-0 group-hover:opacity-100 group-focus-within:opacity-100`
  with outer-row `hover:bg-accent` so keyboard focus reveals the action.
- Reserve badges for categorical states, filters, or interactive values. Use
  secondary text, alignment, or grouping for routine facts; omit internal or
  redundant categories.
- Icon buttons use at least `p-1.5`, with icons at least `w-4 h-4`.
- Avatars use real images, without letter or initial placeholders.
- Skeletons match the real structure, counts, dimensions, and spacing. Async
  elements that always render reserve their space; user-triggered UI and
  conditional banners do not need advance placeholders.
- Empty fillable slots use transparent or background-matched surfaces with a
  dashed border. Filled slots adopt their real elevation and a solid border.

## Read for the affected UI

- Buttons, links, dialog actions, tooltips, and toggles:
  [controls](references/controls.md).
- Typeset or Markdown prose: [Typeset](references/typeset.md).
- Delete and removal interactions: [destructive actions](references/destructive-actions.md).
- Palette setup, color roles, and elevation details:
  [theming](references/theming.md).
