@carbonid1/design-system 5.7.9 → 5.7.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@carbonid1/design-system",
3
- "version": "5.7.9",
3
+ "version": "5.7.11",
4
4
  "description": "Shared React UI primitives + design tokens (themes, postcss config)",
5
5
  "repository": {
6
6
  "type": "git",
@@ -1,31 +1,30 @@
1
1
  #!/usr/bin/env node
2
- import { lstat, mkdir, rm, symlink } from 'node:fs/promises'
2
+ import { lstat, mkdir, readdir, rm, symlink } from 'node:fs/promises'
3
3
  import { dirname, join, resolve } from 'node:path'
4
4
  import { fileURLToPath } from 'node:url'
5
5
 
6
6
  const PKG_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..')
7
- const SKILL_SRC = join(PKG_DIR, 'skills', 'design-system')
7
+ const SKILLS_SRC_ROOT = join(PKG_DIR, 'skills')
8
+ const SEP = process.platform === 'win32' ? '\\' : '/'
8
9
 
9
- if (
10
- !PKG_DIR.includes(
11
- `${process.platform === 'win32' ? '\\' : '/'}node_modules${process.platform === 'win32' ? '\\' : '/'}`,
12
- )
13
- ) {
10
+ // Only link when installed as a dependency (under node_modules); never when
11
+ // running inside the package's own checkout.
12
+ if (!PKG_DIR.includes(`${SEP}node_modules${SEP}`)) {
14
13
  process.exit(0)
15
14
  }
16
15
 
17
16
  const consumerRoot = process.env.INIT_CWD || process.cwd()
18
- const skillDestinations = [
19
- join(consumerRoot, '.claude', 'skills', 'design-system'),
20
- join(consumerRoot, '.agents', 'skills', 'design-system'),
17
+ const skillsRoots = [
18
+ join(consumerRoot, '.claude', 'skills'),
19
+ join(consumerRoot, '.agents', 'skills'),
21
20
  ]
22
21
 
23
- async function removeExistingSkillLink(skillDest) {
22
+ async function linkSkill(skillName, skillSrc, skillDest) {
24
23
  try {
25
24
  const stat = await lstat(skillDest)
26
25
  if (!stat.isSymbolicLink()) {
27
26
  console.warn(`[@carbonid1/design-system] skipped existing non-symlink skill: ${skillDest}`)
28
- return false
27
+ return
29
28
  }
30
29
  } catch (err) {
31
30
  if (err.code !== 'ENOENT') {
@@ -34,18 +33,30 @@ async function removeExistingSkillLink(skillDest) {
34
33
  }
35
34
 
36
35
  await rm(skillDest, { recursive: true, force: true })
37
- return true
36
+ await symlink(skillSrc, skillDest, 'dir')
37
+ console.log(`[@carbonid1/design-system] linked skill ${skillName} → ${skillDest}`)
38
38
  }
39
39
 
40
- for (const skillDest of skillDestinations) {
41
- try {
42
- await mkdir(dirname(skillDest), { recursive: true })
43
- if (!(await removeExistingSkillLink(skillDest))) {
44
- continue
40
+ let skillNames = []
41
+ try {
42
+ skillNames = (await readdir(SKILLS_SRC_ROOT, { withFileTypes: true }))
43
+ .filter(entry => entry.isDirectory())
44
+ .map(entry => entry.name)
45
+ } catch (err) {
46
+ // A postinstall hook must never break the consumer's install over a missing
47
+ // skills directory (corrupt cache, broken publish) — warn and bow out.
48
+ console.warn(`[@carbonid1/design-system] could not read skills directory: ${err.message}`)
49
+ process.exit(0)
50
+ }
51
+
52
+ for (const skillsRoot of skillsRoots) {
53
+ for (const skillName of skillNames) {
54
+ const skillDest = join(skillsRoot, skillName)
55
+ try {
56
+ await mkdir(dirname(skillDest), { recursive: true })
57
+ await linkSkill(skillName, join(SKILLS_SRC_ROOT, skillName), skillDest)
58
+ } catch (err) {
59
+ console.warn(`[@carbonid1/design-system] could not link skill ${skillName}: ${err.message}`)
45
60
  }
46
- await symlink(SKILL_SRC, skillDest, 'dir')
47
- console.log(`[@carbonid1/design-system] linked skill → ${skillDest}`)
48
- } catch (err) {
49
- console.warn(`[@carbonid1/design-system] could not link skill: ${err.message}`)
50
61
  }
51
62
  }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: design-system
3
- 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, badges, or any interactive element. Triggers on: dropdown, select, tooltip, tag, badge, icon, component, UI, design system, layout shift, skeleton, context menu, right-click menu, button, theme, palette.'
3
+ 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, badges, or any interactive element. Triggers on: dropdown, select, tooltip, tag, badge, icon, component, UI, 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.'
4
4
  ---
5
5
 
6
6
  # Design System
@@ -31,13 +31,14 @@ import {
31
31
 
32
32
  Palettes are chosen by importing one theme CSS per app: `@carbonid1/design-system/themes/reader` (InkVoice) or `/themes/dashboard` (CoI Calculator).
33
33
 
34
- 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.
34
+ 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.
35
35
 
36
36
  ## Core rules
37
37
 
38
38
  - Never build a tooltip, context menu, or toast from scratch — use `Tooltip`, `ContextMenu`, `toast()`
39
39
  - 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.
40
40
  - All color through semantic tokens — no hardcoded Tailwind color classes. See [references/theming.md](references/theming.md).
41
+ - **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.
41
42
  - 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}`.
42
43
  - Icon toggle state: `<Icon fill={active ? 'currentColor' : 'none'} />` — not two different components.
43
44
 
@@ -0,0 +1,55 @@
1
+ ---
2
+ name: design-system-package
3
+ 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.'
4
+ ---
5
+
6
+ # Design System — Package Development
7
+
8
+ 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.
9
+
10
+ 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.
11
+
12
+ ## Before you add anything — study what exists
13
+
14
+ - **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).
15
+ - **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.
16
+
17
+ ## Build rules
18
+
19
+ - **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.
20
+ - **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.
21
+ - **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`).
22
+ - **`'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.
23
+ - **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.
24
+ - **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.
25
+
26
+ ## Prefer evolving the system over an app-local workaround
27
+
28
+ 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.
29
+
30
+ ## Adding a semantic color token
31
+
32
+ 1. Define the token in **both** `themes/reader.css` and `themes/dashboard.css`, in both `:root` and `.dark`. Use `oklch` for perceptual uniformity. Light and dark values may use different hue families if the role reads better that way.
33
+ 2. Bridge it in the `@theme inline` block in each theme CSS so Tailwind generates utilities (`--color-my-token: var(--my-token);`).
34
+ 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 oklch variables.
35
+
36
+ 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.
37
+
38
+ ## Storybook MCP
39
+
40
+ `@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.
41
+
42
+ - **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.
43
+ - **Registered as** the `design-system-storybook` MCP server in `.mcp.json` (project scope). Reconnect Claude Code after the first launch to pick it up.
44
+ - **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.
45
+ - React-only and preview-stage upstream; `@storybook/addon-mcp` is pinned to `^0.6.0` and may churn.
46
+
47
+ ## Verify before you ship
48
+
49
+ - **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/`.
50
+ - **Run the story tests** through the Storybook MCP (`run-story-tests`) in a self-healing loop until interaction + a11y pass.
51
+ - **Prove it in a consuming app.** The real proof a change works is a consumer — usually komora — rendering it; a primitive that typechecks can still look wrong under a palette you never opened.
52
+
53
+ ## Releasing — how a change reaches consumers
54
+
55
+ A change is invisible to consumers until it's published. **Write a changeset** (`pnpm changeset`) for the agent who'll adopt the release: lead with what's new and worth using, flag breaking changes, show old → new. `pnpm release` (version → publish to npm → push tags) is a **human laptop step — don't run it.** A consumer then bumps `@carbonid1/design-system`, and its postinstall re-links the shipped skills. So a DS change won't appear in komora until it's both released _and_ komora bumps the dep.