@psnext/design-system 2.2.0 → 2.4.0

package/SKILL.md

@@ -12,18 +12,44 @@ component catalog, full token inventory, theming model — is in
 
 ## Decision order
 
+Work down this ladder in order — each step is only allowed after the one above it
+demonstrably can't produce the design:
+
 1. **Pattern first**: does a pattern (`patterns/Header`, `DataTable`, `Footer`,
    `SectionCard`, `SectionHeading`, `MediaObject`) or layout (`Container`, `Stack`,
-   `TwoColumn`, `PageBackground`) already solve it? Use it.
+   `TwoColumn`, `MultiColumn`, `PageBackground`) already solve it? Use it.
 2. **Primitive second**: compose from `primitives/*` (64 of them — check the catalog
    in DESIGN.md §6 before writing anything custom).
-3. **Custom last**: build with token utilities only; never raw colors, never a
-   parallel component that shadows an existing one.
+3. **Stock rendering**: render the chosen component with its variants/props as
+   designed. Pick the variant from its "Choosing a variant" table in DESIGN.md
+   (intent + light/dark look + tell) — don't guess from the variant name.
+4. **Layout tweaks only**: `className` may place and size the component in its
+   context — margin, width, flex/grid placement, alignment. It must never repaint
+   it (no `bg-*`/`text-*` color/`border-*` color/`hover:*` on a variant).
+5. **Exception — last resort, and marked**: only when 1–4 can't get there:
+   - **Component missing from the DS** → build custom from token utilities only
+     (tokens, px-named radii, `ring-focus`; never raw colors, never `dark:`,
+     never a parallel component that shadows an existing one).
+   - **Component exists but no variant fits** → do NOT re-skin it (see the
+     anti-pattern below); add or request a variant. If you must ship now, mark
+     the deviation at the call site so it stays auditable:
+     `// DS-EXCEPTION: <why> — <what the DS should provide instead>`
+
+Every `DS-EXCEPTION` is a design-system backlog item — sweep them with
+`grep -rn "DS-EXCEPTION"` and either upstream the need into a real
+variant/component or remove the deviation. Exceptions feed the DS; they must
+never silently erode it.
 
 Import per subpath: `@psnext/design-system/primitives/Button`. The DS bundles Radix,
 cva, lucide-react, recharts, sonner, react-hook-form, zod — import primitives from the
-DS, not from those libraries directly (exception: `toast()` from `"sonner"`, and
-`lucide-react` icons which are the standard icon set).
+DS, not from those libraries directly (exception: `toast()` from `"sonner"`).
+
+**Icons**: prefer the DS `Icon` — `<Icon icon="search" />` (typed lucide name, lazy /
+code-split) for content icons, or `<Icon as={Search} />` (sync, bare `<svg>`) with a
+lucide **or a custom** icon component, e.g. inside a component's icon slot. `Icon`
+inherits the surrounding text color by default, so it's correct on a Button; pass
+`color` or a `text-*` class to override. Raw `lucide-react` icons still work as icon-slot
+children (`<Button><Search /></Button>`) — those slots style a direct-child `[&>svg]`.
 
 ## Class-writing rules (do / don't)
 
@@ -38,10 +64,41 @@ DS, not from those libraries directly (exception: `toast()` from `"sonner"`, and
 | `text-danger-txt` for errors | `text-destructive`, `text-red-500` | severity family is info/success/warning/danger |
 | `cn(...)` from the DS for merged classes | template-string concat | cn's tailwind-merge knows the numeric radius scale |
 | suffix matches property: `bg-*-bg`, `text-*-txt` | `text-primary-bg` | token suffix encodes the valid context |
+| pick the variant that already looks right | re-skin a variant with paint classes | variants bundle hover/active/focus states — overrides break them (see below) |
 
 Figma → code: px ÷ 4 = spacing step (16px → `p-4`); radius px maps 1:1 (`rounded-12`);
 heading levels map to `<Heading size={n}>`.
 
+## Never re-skin a variant (anti-pattern)
+
+A component variant is a **package deal**: rest + hover + active + focus + disabled
+states, tuned together. Overriding its paint with `className` only changes the rest
+state — the interaction states still belong to the original variant, and the result
+is visibly broken.
+
+Real failure seen in the wild:
+
+```tsx
+// ✗ WRONG — outline button "made primary" with a bg override
+<Button variant="outline" className="bg-primary-invert-bg text-primary-invert-txt">
+// Looks primary at rest. On hover, outline's own hover:bg-outline-hover-bg fires
+// and the fill flickers to a translucent gray — broken hover, broken contrast.
+
+// ✓ RIGHT — that look already exists as a variant
+<Button variant="default">
+```
+
+Rules:
+
+- **`className` on a DS component is for layout only** — margin, width, flex/grid
+  placement, alignment. Never for paint: `bg-*`, `text-*` color, `border-*` color,
+  `hover:*`, `rounded-*` that fight the variant.
+- **If the look you want isn't a variant, that's a DS gap** — don't patch it at the
+  call site. Add/request a variant (cva) so the states are designed together.
+- This applies to **every** cva-styled component (Button, Badge, Tabs, Card, Alert, …),
+  not just Button. If you catch yourself writing a paint class on one, stop and check
+  the component's variant table in DESIGN.md first.
+
 ## Recipes
 
 **Page scaffold**
@@ -85,6 +142,27 @@ tokens inside flip; do not hand-pick dark colors.
   with `cn`); don't wrap in extra divs to fight specificity.
 - **`!important` on library-styled elements** (e.g. toast classNames) will override
   richColors/severity styling — scope with `data-[type=…]` variants instead.
+- **App-defined `@layer base` wiping the tokens**: an app that declares its own
+  base-layer `:root`/`body` rules (or a reset) can silently override the DS token
+  variables — every component then renders colorless while classes look correct.
+  Don't redefine base-layer custom properties; put app-level overrides *after* the
+  DS styles import, outside `@layer base`.
+
+**If the DS token variables are missing entirely** (components render but
+`--primary-bg` etc. aren't on `:root`), walk this tree in order:
+
+1. Devtools → inspect `<html>` → computed styles → search `--primary-bg`.
+   Present? The tokens are fine — suspect a wrong class name or missing `@source`.
+2. Absent → check the Tailwind entry CSS: `@import "tailwindcss"` then
+   `@import "@psnext/design-system/styles"`, and **all `@import`s before any other
+   statement** (including `@source` — a misplaced import can abort the rest).
+3. Confirm Tailwind is **v4** and this file is actually compiled by
+   `@tailwindcss/vite` / `@tailwindcss/postcss` (not served as plain CSS).
+4. Check nothing *later* redefines the vars: app `@layer base` blocks, resets, or
+   `:root` rules after the import (see the pitfall above — this has happened).
+5. Isolation test: `@import "@psnext/design-system/dist/styles/tokens/mode-light.css"`.
+   If vars appear now, the `/styles` subpath isn't resolving in your bundler —
+   report that, don't ship the workaround.
 - **Logo**: never recolor; wordmark ink follows mode automatically; no ThemeProvider
   needed.
 

package/bin/install-agent-skill.mjs

@@ -2,14 +2,14 @@
 // Install the design-system agent docs (SKILL.md + DESIGN.md) into a consumer
 // project as an Agent Skill, so coding agents load them for UI work.
 //
-//   npx @psnext/design-system              → .agents/skills/design-system/
+//   npx @psnext/design-system              → .agent/skills/design-system/
 //   npx @psnext/design-system <dir>        → <dir>/  (explicit destination)
 //
 // The two docs are copied verbatim from the installed package; SKILL.md links to
 // DESIGN.md as a sibling, so they must land in the same folder (this does that).
 
-import { copyFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { copyFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -20,7 +20,7 @@ if (args.includes("--help") || args.includes("-h")) {
   console.log(`Install @psnext/design-system agent docs as an Agent Skill.
 
 Usage:
-  npx @psnext/design-system              Copy SKILL.md + DESIGN.md into .agents/skills/design-system/
+  npx @psnext/design-system              Copy SKILL.md + DESIGN.md into .agent/skills/design-system/
   npx @psnext/design-system <dir>        Copy into an explicit destination folder
   npx @psnext/design-system --help       Show this help
 
@@ -32,7 +32,7 @@ The agent then loads the skill when writing or reviewing UI in this project.`);
 const positional = args.find((a) => !a.startsWith("-"));
 const dest = positional
   ? resolve(process.cwd(), positional)
-  : resolve(process.cwd(), ".agents/skills/design-system");
+  : resolve(process.cwd(), ".agent/skills/design-system");
 
 for (const doc of DOCS) {
   const src = join(PKG_ROOT, doc);
@@ -42,13 +42,45 @@ for (const doc of DOCS) {
   }
 }
 
-mkdirSync(dest, { recursive: true });
+// Whether the skill was already installed here (a re-run just refreshes the two
+// docs in place) — checked before we create anything.
+const isRefresh = DOCS.every((doc) => existsSync(join(dest, doc)));
+
+// Validate/create the destination one level at a time (for the default that's
+// .agent → skills → design-system): reuse a folder that already exists, create
+// the ones that don't, and bail with a clear message if a segment is occupied
+// by a file — otherwise mkdir would fail cryptically. Only walk segments under
+// the cwd; anything outside falls through to the recursive mkdir below.
+const chain = [];
+for (let cur = dest; cur.startsWith(process.cwd() + sep); cur = dirname(cur)) {
+  chain.unshift(cur);
+}
+for (const dir of chain) {
+  if (existsSync(dir)) {
+    if (!statSync(dir).isDirectory()) {
+      console.error(`✗ ${dir} already exists but is not a directory — move it aside and re-run.`);
+      process.exit(1);
+    }
+    continue; // reuse the existing folder
+  }
+  mkdirSync(dir); // parent already ensured by the outer→inner order
+}
+
+try {
+  mkdirSync(dest, { recursive: true }); // covers a destination outside the cwd
+} catch (err) {
+  console.error(`✗ Could not create ${dest}: ${err.message}`);
+  process.exit(1);
+}
+
 for (const doc of DOCS) {
   copyFileSync(join(PKG_ROOT, doc), join(dest, doc));
 }
 
 const rel = dest.startsWith(process.cwd()) ? `.${dest.slice(process.cwd().length)}` : dest;
-console.log(`✓ Installed @psnext/design-system agent skill → ${rel}/`);
+console.log(
+  `✓ ${isRefresh ? "Refreshed" : "Installed"} @psnext/design-system agent skill → ${rel}/`,
+);
 console.log("  • SKILL.md   — workflow playbook (the Agent Skill entry point)");
 console.log("  • DESIGN.md  — full token + component reference");
 console.log("\nRe-run this after upgrading the package to refresh the docs.");