nap-design-system

Files (4)

• SKILL.md
• components.md · references/
• patterns.md · references/
• tokens.md · references/

SKILL.md (first lines)

# NAP Design System

NAP's web UI is **React + Vite + TailwindCSS (v3) + shadcn/ui**, themed by the
shared `@neutree-ai/theme` package. Every color is a **semantic OKLCH token**, not
a raw Tailwind palette color. Follow this skill to produce UI that matches the
existing app instead of generic AI-looking output.

## How to use this skill

- Read this file for the hard rules and the quick reference.
- Read `references/tokens.md` before choosing any color.
- Read `references/components.md` before hand-rolling a control — a shadcn
  component or variant almost certainly already exists.
- Read `references/patterns.md` for surfaces, glass panels, icons, dark mode,
  typography, and the recurring layout conventions.

## The hard rules (do not violate)

1. **Colors must be semantic tokens.** Use `bg-card`, `text-muted-foreground`,
   `border-border`, `bg-primary`, `text-warning`, etc. **Never** raw palette
   colors (`bg-slate-800`, `text-blue-500`, `#1e293b`) and **never** inline
   `style={{ color: ... }}`. Tokens carry light/dark automatically; raw colors
   break dark mode and the theme.
2. **Icons are `lucide-react`, never emoji.** Emoji must never stand in for an
   icon. Import the named icon component (`import { Plus } from "lucide-react"`).
3. **No unilateral component swaps.** Reuse `@/components/ui/*`; don't pull in a
   new UI library or reinvent a button/dialog/tooltip that already exists.
4. **Compose classes with `cn()`** from `@/lib/utils` (clsx + a customized
   tailwind-merge) so overrides merge correctly. Don't string-concatenate
   classes.
5. **Tune opacity, not hue.** Need a softer/stronger shade of a token? Use the
   alpha modifier: `bg-primary/90`, `bg-success/15`, `border-info/30`. Don't
   reach for a different palette color.
6. **Polish in place.** When you add a region, finish it to production quality
   (spacing, states, dark mode) rather than leaving a rough draft.

## Token quick reference

Semantic roles (each has a `-foreground` pair where text sits on it):

| Role | Use for |
| --- | --- |
| `background` / `foreground` | page surface + default text |
| `card` / `card-foreground` | raised panels, cards |
| `popover` / `popover-foreground` | menus, popovers, dropdowns |
| `primary` | primary actions, focused/active accent (a vivid blue-violet) |
| `secondary` | secondary buttons / low-emphasis fills |
| `muted` / `muted-foreground` | subtle fills + de-emphasized text |
| `accent` | hover backgrounds, gentle highlights |
| `border` / `input` / `ring` | borders, field borders, focus rings |
| `destructive` | delete/danger |
| `success` / `warning` / `info` | status semantics (green / amber / blue) |
| `chart-1..9` | categorical chart series (Tremor) |
| `tag-{slate,rose,amber,emerald,sky,violet,orange,pink}` | user-selectable tag colors |
| `sidebar-*` | the app sidebar surface |

Full values, the alpha pattern, and dark-mode behavior: `references/tokens.md`.

## Component quick reference

`@/components/ui/` (shadcn/ui + a few custom). Highlights — full inventory and
variant cheat-sheets in `references/components.md`:

- **Button** — variants `default | destructive | outline | secondary | ghost | link`; sizes `default | sm | lg | icon`.
- **Badge** — solid (`default | secondary | destructive | success | warning`) and soft tints (`success-soft | destructive-soft | accent-soft | info-soft | warning-soft | muted-soft`) for status chips.
- **Card** (`Card/CardHeader/CardTitle/CardDescription/CardContent/CardFooter`), **Dialog**, **DropdownMenu**, **Popover**, **Tooltip**, **Tabs**, **Select**, **Combobox**, **Input/Textarea/Label/Checkbox/Switch**, **Alert**, **Progress**, **ScrollArea**, **Separator**, **SegmentedControl**, **Spinner**, **Sonner** (toasts), plus app-specific ones (`copy-button`, `confirm-button`, `cron-editor`, `diff-view`, `key-value`, `markdown`, `empty-hero`).

## Stack facts

- Path alias `@/*` → `web/src/*`. `cn` lives at `@/lib/utils`.
- Tailwind config: `web/tailwind.config.js`. Tokens are wired as
  `oklch(var(--token) / <alpha-value>)`, so `/NN` opacity modifiers work on
  every semantic color.
- Theme variables: `@neutree-ai/theme/variables.css` (imported in
  `web/src/index.css`). Dark mode is **class-based** (`.dark` on the root).
- Variants are authored with `class-variance-authority` (cva).
- Custom font sizes: `text-micro` (9px), `text-mini` (10px), `text-tiny` (11px).
- Radius scales off `--radius` (`rounded-lg/md/sm`).

From neutree-ai/agent-platform, Apache-2.0.

More from neutree-ai/agent-platform