---
name: design-system-package
description: 'Building or modifying the @carbonid1/design-system package itself — its primitives, tokens, and variants — NOT using it in an app. Use when adding or changing a DS primitive/component, editing or adding a design token or CSS variable, adding or renaming a variant (a new buttonVariants option), updating the package exports/barrel, or extracting an app-local component into the design system. Triggers on: add a primitive, new design-system component, change a token, add a semantic color, edit themes/reader.css or themes/dashboard.css, add a variant, button variant, new buttonVariants, rename a variant, update the barrel/exports, extract or lift a component into the design system, promote to a DS primitive, modify @carbonid1/design-system, wrap a Base UI primitive, add a Storybook story to a DS primitive, write a changeset for a DS change. To merely USE existing primitives while building app UI, load the design-system skill instead.'
---

# Design System — Package Development

How to **build and change `@carbonid1/design-system` itself** — the shared primitives, tokens, and variants every carbonid1 app consumes. This is the opposite end from the `design-system` skill, which is for _using_ the system in app code. Reach for this the moment a task means editing the package: adding a primitive, changing a token or variant, updating exports, or lifting an app-local component into the system.

The package lives at `packages/design-system` in the `packages` monorepo. This skill is the single source for how we build it — the rules, the Storybook MCP workflow, the token recipe, testing, and release; the package's `AGENTS.md` just points here.

## Before you add anything — study what exists

- **Read the real exports and types.** The barrel is `src/index.ts`; each primitive is `src/<Name>/<Name>.tsx`, with a `.types.ts` when it exports its own prop types and a `.stories.tsx` when it has visual states to show; helpers are `src/helpers/<name>/<name>.ts`, with a co-located test when there's logic worth testing. The types are the API — don't guess props; read them (use the Storybook MCP below).
- **Study comparable shadcn source for structure and accessibility**, then own it. shadcn is a good reference for how a primitive is composed, and we already follow its token _naming_ (~99% token-driven, as validation). But **never import a shadcn component and never add a shadcn runtime dependency** — we hand-own every value and behavior. Reference, not dependency.

## Build rules

- **Base UI is the foundation.** Wrap `@base-ui/react` — not Radix, not hand-rolled. Check Base UI first when adding anything new; for interactive primitives it carries the accessibility and keyboard behavior you'd otherwise reimplement wrong.
- **Compound API for multi-part primitives.** Export a namespace (`ContextMenu.Root`, `.Trigger`, `.Popup`…), not a monolith with config props — mirrors Base UI's own shape and lets consumers compose.
- **Theme-agnostic, tokens only.** Every primitive must render correctly under **every palette × light/dark** with zero consumer styling. Semantic tokens only — no `blue-500`, no hex. The four-tier elevation contract (`bg-background` / `bg-card` / `bg-surface-inset` / `bg-popover`) is the only source of surface elevation; `bg-muted` / `bg-accent` / `bg-secondary` are reserved for interaction states and are never a surface. Full token inventory + rationale: the co-installed `design-system` skill's `references/theming.md` (`.claude/skills/design-system/references/theming.md`).
- **`'use client'` at the top of every interactive file.** Consumers are Next.js server-component apps; hooks, handlers, and Base UI primitives all need a client boundary.
- **Tree-shakable.** The `src/index.ts` barrel is fine because `package.json` sets `"sideEffects": ["**/*.css"]` — unused exports drop. Don't add module-level side effects to component files.
- **Primitive vs product.** This package owns _primitives_ (button, menu, badge) and _patterns every app needs identically_ (toast, undo, destructive tiers). It does **not** own app-specific chrome (page headers, drawers, nav) — those stay in the consumer until a second app wants the same shape.

## Prefer evolving the system over an app-local workaround

When a consumer needs something the system doesn't have — a token, a variant, a primitive — the default is to **add or extend it here**, not to fork a one-off in the app. A bespoke color or component in one app quietly breaks the single-decision-propagates-everywhere contract the tokens exist to keep; that's why the consume-side rule is to surface a missing token, not invent one. **Extracting an app-local component into the package** is the same move in reverse: generalize it (theme-agnostic, no app-specific copy or data logic), give it a compound API if it's multi-part, add stories for every state, and export it from the barrel.

## Adding a semantic color token

1. Define the token in **both** `themes/reader.css` and `themes/dashboard.css`, in both `:root` and `.dark`. Match the existing perceptual color format for uniformity. Light and dark values may use different hue families if the role reads better that way.
2. Bridge it in the `@theme inline` block in each theme CSS so Tailwind generates utilities (`--color-my-token: var(--my-token);`).
3. Use it via Tailwind classes in components (`bg-my-token`, `text-my-token-foreground`). Opacity modifiers like `bg-my-token/10` work natively on those color variables.

Use enough sub-variants for depth — don't squeeze a semantic color into just `base + foreground` when the role needs distinct text/background/border values. Opacity modifiers are a poor substitute for dedicated tokens tuned per role.

## Storybook MCP

`@storybook/addon-mcp` makes Storybook serve an MCP endpoint so an agent can read the primitives' real props, docs, and stories — and run their interaction/a11y tests in a self-healing loop — instead of guessing.

- **Start it:** `pnpm storybook` — fixed port **7006** (pet-project convention; consumer apps point their agents at this exact port). The endpoint is `http://localhost:7006/mcp` and only exists while Storybook is running.
- **Registered as** the `design-system-storybook` MCP server in `.mcp.json` (project scope). Reconnect Claude Code after the first launch to pick it up.
- **When Storybook is running, use it** before adding or changing a primitive: `list-all-documentation` for what exists, `get-documentation` for a component's props, `run-story-tests` to validate stories (interaction + a11y). Read props from the MCP — don't hallucinate them.
- React-only and preview-stage upstream; `@storybook/addon-mcp` is pinned to `^0.6.0` and may churn.

## Verify before you ship

- **Stories for everything visual** — `Component.stories.tsx`, one story per visual state, each rendering under both palettes × both modes (the `.storybook/preview.ts` toolbar switchers prove it in isolation before shipping). Story-level `.test()` methods for interaction behavior. **Vitest** for non-visual helpers in `src/helpers/`.
- **Run the story tests** through the Storybook MCP (`run-story-tests`) in a self-healing loop until interaction + a11y pass.
- **UI/UX Pro Max accessibility review** — For any visual, interactive, or token change, invoke the UI/UX Pro Max plugin review lens when available (prefer `ui-ux-pro-max:design-system` for primitives and tokens, `ui-ux-pro-max:ui-styling` for component styling, and `ui-ux-pro-max:ui-ux-pro-max` when unsure) and let it choose the relevant checks for the diff. The review must still cover keyboard navigation, visible focus states, contrast, accessible names/ARIA, screen-reader semantics, responsive behavior, interaction states, and reduced-motion behavior where they apply. In the handoff, name the lens used and summarize findings; for non-visual package housekeeping, say it does not apply. Package rules stay authoritative over broad style suggestions.
- **Prove it downstream.** The real proof a change works is at least one app or fixture outside the package rendering it; a primitive that type-checks can still look wrong under a palette you never opened.

## Releasing — how a change reaches consumers

A package change is invisible outside this repo until it's published. For release-intended package work, the agent owns the complete local release flow: implement, verify, review, write a changeset, run `pnpm release`, and leave the published version available for downstream dependency bumps. Do not stop for a separate publish approval unless the user explicitly asks to pause before release.

`pnpm release` is a local agent-run release step, not CI/GitHub automation. It versions packages, publishes to npm, pushes tags, and expects a clean `main`. Run it only for release-ready package work; don't run it for exploratory or unfinished changes.

Stop only for real blockers: failing checks, an unexpected major or breaking release, npm auth/2FA prompts, unrelated dirty work, merge conflicts, an unexpected release prompt, or a release script failure. Otherwise publish and continue.
