@carbonid1/design-system 4.1.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonid1/design-system",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Shared React UI primitives + design tokens (themes, postcss config)",
   "repository": {
     "type": "git",
@@ -22,7 +22,9 @@
   "files": [
     "src",
     "themes",
-    "postcss.mjs"
+    "postcss.mjs",
+    "skills",
+    "scripts"
   ],
   "dependencies": {
     "@tailwindcss/postcss": "^4.2.0",
@@ -76,6 +78,7 @@
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "test": "vitest --run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "postinstall": "node scripts/install-skill.mjs"
   }
 }

package/scripts/install-skill.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { mkdir, rm, symlink } from 'node:fs/promises'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const SKILL_SRC = join(PKG_DIR, 'skills', 'design-system')
+
+if (!PKG_DIR.includes(`${process.platform === 'win32' ? '\\' : '/'}node_modules${process.platform === 'win32' ? '\\' : '/'}`)) {
+  process.exit(0)
+}
+
+const consumerRoot = process.env.INIT_CWD || process.cwd()
+const skillDest = join(consumerRoot, '.claude', 'skills', 'design-system')
+
+try {
+  await mkdir(dirname(skillDest), { recursive: true })
+  await rm(skillDest, { recursive: true, force: true })
+  await symlink(SKILL_SRC, skillDest, 'dir')
+  console.log(`[@carbonid1/design-system] linked skill → ${skillDest}`)
+} catch (err) {
+  console.warn(`[@carbonid1/design-system] could not link skill: ${err.message}`)
+}

package/skills/design-system/SKILL.md

@@ -0,0 +1,65 @@
+---
+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, adding dropdowns, selects, tooltips, icons, toasts, context menus, or any interactive element. Use when choosing between native HTML elements and custom components. Also use when working with skeletons, loading states, layout shifts, or async-loaded UI elements. Triggers on: dropdown, select, tooltip, tag, badge, icon, component, UI, design system, shared component, skeleton, loading state, layout shift, context menu, right-click menu, button, theme, palette.'
+---
+
+# 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 {
+  Button, Kbd, ProgressRing, Slider, Switch,
+  ContextMenu, Select, Tooltip,
+  Toaster, toast,
+  ThemeProvider, ThemeCycler, useTheme,
+  cn, getModKey,
+} 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), read that package's `CLAUDE.md` — this file is for *using* the design system, not building it.
+
+## Core rules
+
+- Never use native `<select>` — use `Select`
+- 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).
+- Tooltip: rely on defaults (`position="top"`, `delay={200}`). Only override when the default is wrong (e.g. header → `position="bottom"`, data-viz progressive disclosure → `delay={600}`). When a tooltip trigger also opens a popover, pass `disabled={open}`.
+- Icon toggle state: `<Icon fill={active ? 'currentColor' : 'none'} />` — not two different components.
+
+## 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** — badge/chip components, never comma-separated text
+- **Touch targets** — icon buttons `p-1.5` minimum, icons `w-4 h-4` minimum
+- **Avatars** — only with real images, no letter/initial placeholders
+
+## 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 `react-hotkeys-hook` → 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.

package/skills/design-system/references/theming.md

@@ -0,0 +1,91 @@
+# Color & Theming
+
+## Philosophy
+
+Tokens represent semantic roles, not fixed hues. Each theme picks the best hue for that role in its own context — light and dark themes may use entirely different hue families for the same token. The design system is app-agnostic: swap the token values, everything updates.
+
+We use shadcn's token naming convention but own all color values. When pulling a new shadcn component, replace any generated color values with our hand-tuned tokens. This follows shadcn's own approach (~99% token-driven) as validation, not as a dependency.
+
+## Palettes
+
+`@carbonid1/design-system` ships multiple palettes — currently `reader` (InkVoice) and `dashboard` (CoI Calculator, admin-style UIs). Both define the same token names on `:root` + `.dark`; consumers choose one by importing the matching CSS:
+
+```ts
+import '@carbonid1/design-system/themes/reader'
+// or
+import '@carbonid1/design-system/themes/dashboard'
+```
+
+Primitives must render correctly under every palette × light/dark combination — that's the contract. Because both palettes hit the same token names, primitive code stays palette-agnostic and consumer code doesn't change when switching.
+
+## Rules
+
+- **All color through tokens.** Every color that appears in themed UI must reference a CSS variable. No hardcoded Tailwind color classes (`blue-500`, `amber-400`, `gray-300`) for meaning-bearing colors.
+- **Hardcoded only when physically fixed.** The only exception: values that must be constant regardless of theme (e.g. `bg-black/10` for modal backdrops). These are rare — 2-3 cases in the entire app.
+- **Opacity modifiers work natively.** Tailwind v4 supports `bg-token/20` on any color format including oklch CSS variables. No `color-mix()` workarounds needed.
+- **Use enough sub-variants for depth.** Don't squeeze a semantic color into just 2 tokens (base + foreground) when it serves distinct roles — text, background, and border often need different values to look intentional. Use 4-5 sub-variants (e.g. `foreground`, `muted`, `border`) when it gives the area more visual depth. Opacity modifiers on a single base color are a poor substitute for dedicated tokens tuned per role.
+
+## Token Inventory
+
+Tokens are defined in `globals.css` (`:root` + `.dark`), bridged in `@theme inline` block, consumed as Tailwind utilities.
+
+### Base tokens (from shadcn naming)
+
+| Token           | Role                                                            | Sub-variants |
+| --------------- | --------------------------------------------------------------- | ------------ |
+| `--background`  | Page background                                                 | —            |
+| `--foreground`  | Default text                                                    | —            |
+| `--card`        | Card surfaces                                                   | foreground   |
+| `--popover`     | Popover surfaces                                                | foreground   |
+| `--primary`     | Interactive color (buttons, links, selections, focus, progress) | foreground   |
+| `--secondary`   | Supporting surfaces                                             | foreground   |
+| `--muted`       | De-emphasized surfaces and text                                 | foreground   |
+| `--accent`      | Hover/expanded tints                                            | foreground   |
+| `--destructive` | Errors, danger                                                  | —            |
+| `--border`      | Default borders                                                 | —            |
+| `--input`       | Input borders                                                   | —            |
+| `--ring`        | Focus rings                                                     | —            |
+
+### Custom tokens
+
+| Token         | Role                                          | Sub-variants              |
+| ------------- | --------------------------------------------- | ------------------------- |
+| `--highlight` | Emphasis accent (e.g. live cursors, selection highlights) | foreground, muted         |
+| `--attention` | Warnings, notices, saved-for-later — "look at this"       | foreground, muted, border |
+| `--success`   | Completion, positive outcomes                 | foreground                |
+
+## How to Add a New Semantic Token
+
+1. **Define values** in `globals.css` — both `:root` (light) and `.dark`. Use oklch for perceptual uniformity. Light and dark values may use different hues if the role reads better that way.
+
+   ```css
+   :root {
+     --my-token: oklch(0.65 0.15 45);
+     --my-token-foreground: oklch(0.25 0.05 40);
+   }
+   .dark {
+     --my-token: oklch(0.7 0.12 200);
+     --my-token-foreground: oklch(0.95 0.02 195);
+   }
+   ```
+
+2. **Bridge in `@theme inline`** in `globals.css` so Tailwind generates utilities:
+
+   ```css
+   @theme inline {
+     --color-my-token: var(--my-token);
+     --color-my-token-foreground: var(--my-token-foreground);
+   }
+   ```
+
+3. **Use in components** via Tailwind classes:
+   ```tsx
+   <div className="bg-my-token text-my-token-foreground">
+   <span className="bg-my-token/10">  // opacity modifier for tints
+   ```
+
+## Notes
+
+- **`::selection`** uses solid oklch values, not opacity modifiers — semi-transparent backgrounds create visible seams at line boundaries.
+- **Tooltip** uses inverted tokens (`bg-foreground text-background`) since it's a dark-on-light / light-on-dark surface. Kbd badge: `bg-background/15`.
+- **DebugPanel** is excluded from token migration — physically fixed terminal aesthetic.