@fracazo/design-system 0.2.1 → 0.6.0

package/DESIGN.md

@@ -14,6 +14,11 @@ refuses to ship, and where each brand differs. It is deliberately short.
 The stylesheet carries the visual decisions; this file carries judgment,
 and gains a rule only when the same correction has been made twice.
 
+Agents load `skills/product-design/SKILL.md` first: it names the request
+mode, routes to the reference that applies, and cites rules by stable ID
+from `skills/product-design/references/rules.md`. This file stays the
+narrative those rules point back to.
+
 Read `css/roles.css` for the roles and the brand contract, the component
 source in `src/ui/*` for each component's intent, and the product's own
 CLAUDE.md for the rules that are local to it.

package/README.md

@@ -1,13 +1,20 @@
 # @fracazo/design-system
 
-Roles, a brand contract, guardrails and components for a warm, evidence-led
-product design system. The package ships the half of the system that is the same
-for every product; each product supplies one brand file with its values.
-Change the brand file and the whole product re-skins; the roles never move.
+An agent-native design system. Design decisions as code, so the quality bar lives in the tooling.
 
-Built for [BirthGuide](https://birthguide.com.au) and
-[birthplans.app](https://www.birthplans.app), designed to start the next
-product from.
+When a team ships faster, the design review queue is the first thing that breaks. Either every change waits on a designer, or the bar drops quietly. Neither works.
+
+This package moves the bar out of the review queue and into the tooling, where it holds whether a designer is in the room or not.
+
+It lives in three places.
+
+**Lint.** Eight ESLint rules catch what a reviewer would: colour literals, radius literals, stock palette, dark pairs, arbitrary sizes, focus rings, text on dark surfaces. The build fails before anyone posts a screenshot.
+
+**Components.** Each of the seventeen components carries its own guidance in JSDoc: use for, avoid when, variants. The decision sits where it gets made, not in a doc nobody opens.
+
+**The agent skill.** AI tools load the design rules before they build or review any UI, route to the reference that applies, and cite rules by stable ID. The system proposes, the human commits.
+
+Built for BirthGuide and birthplans.app, and designed to start the next product from.
 
 ## What is in the package
 
@@ -15,15 +22,46 @@ product from.
 |---|---|
 | `css/roles.css` | The system: the dark variant, the Tailwind v4 `@theme` mapping, the radius ramp, fluid type roles, band rhythm, the eight aliasing semantics, and the **brand contract** at the top |
 | `ds-check-brand` | Holds a brand file to the contract: nothing missing, nothing extra |
+| `ds-intake` | Collects design-relevant commits from product repos into an intake packet the agent proposes and a human commits (see the skill's `references/intake.md`) |
 | `ds-build-brand-css` | Composes the plain-CSS token file a product serves publicly (e.g. `/brand.css`) |
+| `ds-init` and `template/` | Writes a new product: Next 16, Tailwind v4, this package, a blank brand file and the guardrails on, pinned to the package version that wrote it |
+| `css/motion.css` | The animation vocabulary the components use (enter, exit, accordion, the fade, zoom, blur and slide utilities); `roles.css` imports it |
 | `@fracazo/design-system` and `./ui/*` | `cn` and seventeen shadcn-based components (button, card, dialog, form, select, sortable-list and the rest), each with intent JSDoc: use for, avoid when, variants |
-| `@fracazo/design-system/eslint` | Two guardrails: no raw colours and no arbitrary fluid type sizes in a `className` |
+| `@fracazo/design-system/eslint` | Eight guardrails as an ESLint plugin, one per rule ID: colour literals, arbitrary clamp sizes, dark pairs, radius literals, stock palette, `focus:` rings, text on always-dark surfaces, em dashes |
 | `demo/index.html` | A showcase page that renders the roles in both modes off a served `/brand.css` |
+| `skills/product-design/` | The agent skill: request modes, routed references, rules with stable IDs, exemplars, coverage gaps. Point your CLAUDE.md or AGENTS.md at its `SKILL.md` |
 | `DESIGN.md` | The written authority: who the reader is, the priority order, how a page is composed, the rejection list, one short chapter per brand |
 
 Brand files live in each product repo, not here. The contract is what keeps
-them honest. A new product starts from the `design-system-starter` template:
-Next 16, Tailwind v4, this package, a blank brand file and the guardrails on.
+them honest.
+
+## Start a product
+
+```bash
+pnpm dlx --package @fracazo/design-system ds-init my-product
+```
+
+That writes `template/` into `my-product`: Next 16, Tailwind v4, this
+package, every role with an achromatic placeholder in
+`src/system/brands/starter.css`, the house base layer in `globals.css`, the
+pre-paint dark script, `designSystemGuardrails()` with no exemptions, and
+`pnpm lint` running ESLint plus `ds-check-brand`. It refuses a non-empty
+directory. Then:
+
+1. `pnpm install`.
+2. Rename the brand file to the product and update the two paths that name
+   it: the `@import` in `globals.css` and the `brand:*` scripts.
+3. Replace every value in the brand file, light and dark. Keep the property
+   names; `pnpm brand:contract` holds you to them. `DESIGN.md` says what
+   each role is for and which six semantics are meant to diverge in dark.
+4. Pick the typeface in `layout.tsx` and point the brand file's `@theme`
+   block at its variable.
+5. Rewrite the top of `CLAUDE.md`, delete `page.tsx`, build the first
+   surface. `pnpm lint && pnpm typecheck && pnpm build` before every merge.
+
+The template is proven against the package it ships with: its brand file
+passes the contract and a product written from it lints, typechecks and
+builds before a release.
 
 ## Consume it
 
@@ -38,7 +76,8 @@ pnpm add @fracazo/design-system
 ```
 
 Import the roles, then exactly one brand file, at the top of your global
-stylesheet. Order matters: roles first.
+stylesheet. Order matters: roles first. `roles.css` also brings in the
+motion vocabulary the components use, so no animation library is needed.
 
 ```css
 @import "tailwindcss";
@@ -89,10 +128,35 @@ export default defineConfig([
   designSystemGuardrails({
     files: ['src/**/*.{ts,tsx}'],
     ignores: ['src/components/pdf/**', 'src/lib/email.ts'],
+    // Clean rules are errors by default; stock palette, focus: rings,
+    // on-dark text and em dashes start as warnings. Turn each up once
+    // the product is clean, or down while a pass is pending.
+    severity: { 'no-stock-palette': 'error', 'no-arbitrary-clamp': 'warn' },
   }),
 ])
 ```
 
+A deliberate one-off names the rule and the reason:
+
+```tsx
+{/* eslint-disable-next-line design-system/no-radius-literal -- phone bezel, not a UI corner */}
+```
+
+## Tell your agent when to load the skill
+
+In the product's CLAUDE.md or AGENTS.md:
+
+```
+When shaping, building, reviewing or writing copy for user-facing UI, load
+node_modules/@fracazo/design-system/skills/product-design/SKILL.md first.
+Skip it for backend-only work, telemetry, generated files and tests with no
+shipped UI.
+```
+
+The skill names the request mode, routes to the reference that applies and
+cites rules by stable ID. `DESIGN.md` is the narrative those rules point
+back to.
+
 ## The two tiers, in one paragraph
 
 Primitives hold literals (`--brand`, `--band`, `--ink`) and live in the brand
@@ -102,7 +166,8 @@ primary, accent, ring and their foregrounds) or hold a brand-tuned literal
 in the brand file (the six that diverge in dark: secondary, muted, border,
 input, muted-foreground, accent-foreground). Dark border and input as
 translucent hairlines is a design decision, not duplication; never "fix" a
-divergent semantic by aliasing it.
+divergent semantic by aliasing it. Change the brand file and the whole product
+re-skins; the roles never move.
 
 ## Versioning
 

package/css/motion.css

@@ -0,0 +1,155 @@
+/* =============================================================================
+   Design system motion (css/motion.css)
+
+   The animation vocabulary the package's components and the products use:
+   enter and exit keyframes driven by custom properties, the accordion
+   height keyframes, and the utilities that set those properties. Imported
+   by roles.css, so one import covers roles and motion. Class names and
+   values match tw-animate-css 1.4.0 for exactly the subset in use, so
+   dropping that import changes nothing on screen; the subset is the point.
+   Add a utility here only when a component or a product needs it.
+
+   Duration and easing read --tw-duration and --tw-ease first, so Tailwind's
+   duration-* and ease-* utilities tune a single animation; the defaults are
+   150ms ease for enter and exit, 200ms ease-out for the accordion.
+   ============================================================================= */
+
+/* Non-inherited so a child that animates never picks up its parent's offsets. */
+@property --tw-animation-delay { syntax: "*"; inherits: false; initial-value: 0s; }
+@property --tw-animation-direction { syntax: "*"; inherits: false; initial-value: normal; }
+@property --tw-animation-duration { syntax: "*"; inherits: false; }
+@property --tw-animation-fill-mode { syntax: "*"; inherits: false; initial-value: none; }
+@property --tw-animation-iteration-count { syntax: "*"; inherits: false; initial-value: 1; }
+@property --tw-enter-blur { syntax: "*"; inherits: false; initial-value: 0; }
+@property --tw-enter-opacity { syntax: "*"; inherits: false; initial-value: 1; }
+@property --tw-enter-rotate { syntax: "*"; inherits: false; initial-value: 0; }
+@property --tw-enter-scale { syntax: "*"; inherits: false; initial-value: 1; }
+@property --tw-enter-translate-x { syntax: "*"; inherits: false; initial-value: 0; }
+@property --tw-enter-translate-y { syntax: "*"; inherits: false; initial-value: 0; }
+@property --tw-exit-blur { syntax: "*"; inherits: false; initial-value: 0; }
+@property --tw-exit-opacity { syntax: "*"; inherits: false; initial-value: 1; }
+@property --tw-exit-rotate { syntax: "*"; inherits: false; initial-value: 0; }
+@property --tw-exit-scale { syntax: "*"; inherits: false; initial-value: 1; }
+@property --tw-exit-translate-x { syntax: "*"; inherits: false; initial-value: 0; }
+@property --tw-exit-translate-y { syntax: "*"; inherits: false; initial-value: 0; }
+
+@theme inline {
+  /* Fractions the numbered utilities resolve against (fade-in-0, zoom-in-95). */
+  --percentage-0: 0;
+  --percentage-5: .05;
+  --percentage-10: .1;
+  --percentage-15: .15;
+  --percentage-20: .2;
+  --percentage-25: .25;
+  --percentage-30: .3;
+  --percentage-35: .35;
+  --percentage-40: .4;
+  --percentage-45: .45;
+  --percentage-50: .5;
+  --percentage-55: .55;
+  --percentage-60: .6;
+  --percentage-65: .65;
+  --percentage-70: .7;
+  --percentage-75: .75;
+  --percentage-80: .8;
+  --percentage-85: .85;
+  --percentage-90: .9;
+  --percentage-95: .95;
+  --percentage-100: 1;
+  --percentage-translate-full: 1;
+
+  /* animate-in / animate-out */
+  --animate-in: enter var(--tw-animation-duration, var(--tw-duration, .15s)) var(--tw-ease, ease) var(--tw-animation-delay, 0s) var(--tw-animation-iteration-count, 1) var(--tw-animation-direction, normal) var(--tw-animation-fill-mode, none);
+  --animate-out: exit var(--tw-animation-duration, var(--tw-duration, .15s)) var(--tw-ease, ease) var(--tw-animation-delay, 0s) var(--tw-animation-iteration-count, 1) var(--tw-animation-direction, normal) var(--tw-animation-fill-mode, none);
+
+  @keyframes enter {
+    from {
+      opacity: var(--tw-enter-opacity, 1);
+      transform: translate3d(var(--tw-enter-translate-x, 0), var(--tw-enter-translate-y, 0), 0) scale3d(var(--tw-enter-scale, 1), var(--tw-enter-scale, 1), var(--tw-enter-scale, 1)) rotate(var(--tw-enter-rotate, 0));
+      filter: blur(var(--tw-enter-blur, 0));
+    }
+  }
+  @keyframes exit {
+    to {
+      opacity: var(--tw-exit-opacity, 1);
+      transform: translate3d(var(--tw-exit-translate-x, 0), var(--tw-exit-translate-y, 0), 0) scale3d(var(--tw-exit-scale, 1), var(--tw-exit-scale, 1), var(--tw-exit-scale, 1)) rotate(var(--tw-exit-rotate, 0));
+      filter: blur(var(--tw-exit-blur, 0));
+    }
+  }
+
+  /* Accordion content height; Radix supplies the variable. */
+  --animate-accordion-down: accordion-down var(--tw-animation-duration, var(--tw-duration, .2s)) var(--tw-ease, ease-out) var(--tw-animation-delay, 0s) var(--tw-animation-iteration-count, 1) var(--tw-animation-direction, normal) var(--tw-animation-fill-mode, none);
+  --animate-accordion-up: accordion-up var(--tw-animation-duration, var(--tw-duration, .2s)) var(--tw-ease, ease-out) var(--tw-animation-delay, 0s) var(--tw-animation-iteration-count, 1) var(--tw-animation-direction, normal) var(--tw-animation-fill-mode, none);
+
+  @keyframes accordion-down {
+    from { height: 0; }
+    to { height: var(--radix-accordion-content-height, auto); }
+  }
+  @keyframes accordion-up {
+    from { height: var(--radix-accordion-content-height, auto); }
+    to { height: 0; }
+  }
+}
+
+/* Enter */
+@utility fade-in { --tw-enter-opacity: 0; }
+@utility fade-in-* {
+  --tw-enter-opacity: calc(--value(number) / 100);
+  --tw-enter-opacity: --value(--percentage-*, [*]);
+}
+@utility zoom-in { --tw-enter-scale: 0; }
+@utility zoom-in-* {
+  --tw-enter-scale: calc(--value(number) * 1%);
+  --tw-enter-scale: calc(--value(ratio));
+  --tw-enter-scale: --value(--percentage-*, [*]);
+}
+@utility blur-in { --tw-enter-blur: 20px; }
+@utility blur-in-* {
+  --tw-enter-blur: calc(--value(number) * 1px);
+  --tw-enter-blur: --value(--blur-*, [*]);
+}
+@utility slide-in-from-top { --tw-enter-translate-y: -100%; }
+@utility slide-in-from-top-* {
+  --tw-enter-translate-y: calc(--value(integer) * var(--spacing) * -1);
+  --tw-enter-translate-y: calc(--value(--percentage-*, --percentage-translate-*) * -100%);
+  --tw-enter-translate-y: calc(--value(ratio) * -100%);
+  --tw-enter-translate-y: calc(--value(--translate-*, [percentage], [length]) * -1);
+}
+@utility slide-in-from-bottom { --tw-enter-translate-y: 100%; }
+@utility slide-in-from-bottom-* {
+  --tw-enter-translate-y: calc(--value(integer) * var(--spacing));
+  --tw-enter-translate-y: calc(--value(--percentage-*, --percentage-translate-*) * 100%);
+  --tw-enter-translate-y: calc(--value(ratio) * 100%);
+  --tw-enter-translate-y: --value(--translate-*, [percentage], [length]);
+}
+@utility slide-in-from-left { --tw-enter-translate-x: -100%; }
+@utility slide-in-from-left-* {
+  --tw-enter-translate-x: calc(--value(integer) * var(--spacing) * -1);
+  --tw-enter-translate-x: calc(--value(--percentage-*, --percentage-translate-*) * -100%);
+  --tw-enter-translate-x: calc(--value(ratio) * -100%);
+  --tw-enter-translate-x: calc(--value(--translate-*, [percentage], [length]) * -1);
+}
+@utility slide-in-from-right { --tw-enter-translate-x: 100%; }
+@utility slide-in-from-right-* {
+  --tw-enter-translate-x: calc(--value(integer) * var(--spacing));
+  --tw-enter-translate-x: calc(--value(--percentage-*, --percentage-translate-*) * 100%);
+  --tw-enter-translate-x: calc(--value(ratio) * 100%);
+  --tw-enter-translate-x: --value(--translate-*, [percentage], [length]);
+}
+
+/* Exit */
+@utility fade-out { --tw-exit-opacity: 0; }
+@utility fade-out-* {
+  --tw-exit-opacity: calc(--value(number) / 100);
+  --tw-exit-opacity: --value(--percentage-*, [*]);
+}
+@utility zoom-out { --tw-exit-scale: 0; }
+@utility zoom-out-* {
+  --tw-exit-scale: calc(--value(number) * 1%);
+  --tw-exit-scale: calc(--value(ratio));
+  --tw-exit-scale: --value(--percentage-*, [*]);
+}
+@utility slide-out-to-top { --tw-exit-translate-y: -100%; }
+@utility slide-out-to-bottom { --tw-exit-translate-y: 100%; }
+@utility slide-out-to-left { --tw-exit-translate-x: -100%; }
+@utility slide-out-to-right { --tw-exit-translate-x: 100%; }

package/css/roles.css

@@ -61,6 +61,9 @@
    highlight primitive in light and follows it into dark by itself.
    ============================================================================= */
 
+/* Motion vocabulary (animate-in, fade-in-0, accordion-down ...). */
+@import "./motion.css";
+
 @custom-variant dark (&:is(.dark *));
 
 @theme inline {

package/dist/guardrails/eslint.d.ts

@@ -1,21 +1,88 @@
+type Node = {
+    type: string;
+    [key: string]: unknown;
+};
+type ReportDescriptor = {
+    node?: Node;
+    loc?: {
+        line: number;
+        column: number;
+    } | {
+        start: {
+            line: number;
+            column: number;
+        };
+        end: {
+            line: number;
+            column: number;
+        };
+    };
+    messageId: string;
+    data?: Record<string, string>;
+};
+type RuleContext = {
+    report(descriptor: ReportDescriptor): void;
+    sourceCode: {
+        text: string;
+    };
+};
+type RuleModule = {
+    meta: {
+        type: 'problem' | 'suggestion';
+        docs: {
+            description: string;
+            url?: string;
+        };
+        messages: Record<string, string>;
+        schema: [];
+    };
+    create(context: RuleContext): Record<string, (node: Node) => void>;
+};
+export declare const rules: Record<string, RuleModule>;
+/**
+ * @deprecated Selector arrays for `no-restricted-syntax`, kept so configs
+ * written against 0.2 and 0.3 keep working. Use designSystemGuardrails()
+ * or the plugin's rules instead; they carry per-rule IDs and severities.
+ */
 type Restriction = {
     selector: string;
     message: string;
 };
 export declare const noArbitraryColour: Restriction[];
 export declare const noArbitraryTypeClamp: Restriction[];
+export type RuleId = keyof typeof rules & string;
+export type Severity = 'error' | 'warn' | 'off';
+/** The plugin object, for configs that want to wire rules by hand. */
+export declare const plugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: Record<string, RuleModule>;
+};
+/** Defaults: clean rules are errors; rules that need a cleanup pass first are warnings. */
+export declare const defaultSeverity: Record<RuleId, Severity>;
 export interface GuardrailOptions {
     /** Glob(s) the rules apply to. Default: src/**\/*.{ts,tsx}. */
     files?: string[];
-    /** Glob(s) exempt from the rules: renderers that genuinely cannot use CSS variables. */
+    /** Glob(s) exempt from every rule: renderers that genuinely cannot use CSS variables. */
     ignores?: string[];
+    /** Per-rule overrides of the default severities. */
+    severity?: Partial<Record<RuleId, Severity>>;
 }
-/** A flat-config block: spread it into your eslint.config array. */
-export declare function designSystemGuardrails({ files, ignores, }?: GuardrailOptions): {
+/** A flat-config block: put it in your eslint.config array. */
+export declare function designSystemGuardrails({ files, ignores, severity }?: GuardrailOptions): {
     files: string[];
     ignores: string[];
-    rules: {
-        'no-restricted-syntax': (string | Restriction)[];
+    plugins: {
+        'design-system': {
+            meta: {
+                name: string;
+                version: string;
+            };
+            rules: Record<string, RuleModule>;
+        };
     };
+    rules: Record<string, Severity>;
 };
 export {};

package/dist/guardrails/eslint.js

@@ -1,18 +1,11 @@
 // =============================================================================
 // ESLint guardrails.
 //
-// Two rules that keep design decisions in the token layer instead of in
-// component files:
-//   1. No raw colour values in a className (hex, oklch(), rgb(), hsl()),
-//      including Tailwind arbitrary utilities like bg-[#fff]. Colours come
-//      from the semantic or primitive utilities the roles define.
-//   2. No arbitrary fluid type size in a className (text-[clamp(...)]).
-//      Fluid sizes are named roles (text-display, text-section-title,
-//      text-lede); a genuinely new size becomes a token first.
-//
-// Both match string literals and template-literal chunks nested under any
-// className attribute, so cn() and ternaries are covered. Non-className
-// colour (JS colour maps, inline style objects) is deliberately not matched.
+// The mechanical half of the design system's rules, as a flat-config plugin.
+// Every rule here has a record in skills/product-design/references/rules.md
+// under the same ID (design-system/<id> matches rule/<id>), which carries the
+// scope, the why, the exceptions and an example pair. The message cites the
+// ID so a finding can be traced.
 //
 //   import { designSystemGuardrails } from '@fracazo/design-system/eslint'
 //   export default defineConfig([
@@ -20,32 +13,207 @@
 //     designSystemGuardrails({
 //       files: ['src/**/*.{ts,tsx}'],
 //       ignores: ['src/components/pdf/**'],   // renderers that cannot use CSS vars
+//       severity: { 'no-stock-palette': 'error' },   // override a default
 //     }),
 //   ])
 //
-// A deliberate one-off carries `// eslint-disable-next-line
-// no-restricted-syntax -- <reason>` so the exception is visible in review.
+// Defaults: the rules a clean codebase already satisfies are errors; the ones
+// that need a cleanup pass first (stock palette, focus: rings, em dashes,
+// on-dark text) are warnings, so they surface without blocking a merge. Turn
+// each up to error once the product is clean. A deliberate one-off carries
+// `// eslint-disable-next-line design-system/<id> -- <reason>` so the
+// exception is visible in review.
+//
+// No dependency on eslint's types: the rule shapes below are the subset the
+// plugin needs, typed locally so the package stays dependency-free.
 // =============================================================================
-const COLOUR_REGEX = '(#[0-9a-fA-F]{3,8}|oklch\\(|rgba?\\(|hsla?\\()';
-const COLOUR_MESSAGE = 'Arbitrary colour value in className. Use a semantic or primitive utility (bg-primary, text-muted-foreground, border-border, bg-surface) instead; see DESIGN.md. A deliberate one-off carries an eslint-disable-next-line stating why.';
-const TYPE_CLAMP_REGEX = 'text-\\[clamp\\(';
-const TYPE_CLAMP_MESSAGE = 'Arbitrary fluid type size in className. Use a named type role (text-display, text-section-title, text-lede) or add a token to roles.css; a deliberate one-off carries an eslint-disable-next-line stating why.';
+const RULES_DOC = 'skills/product-design/references/rules.md';
+// ─── helpers ─────────────────────────────────────────────────────────────────
+const SKIP_KEYS = new Set(['parent', 'loc', 'range', 'tokens', 'comments']);
+/** Depth-first walk over every ESTree node under `node`, including itself. */
+function walk(node, visit) {
+    visit(node);
+    for (const key of Object.keys(node)) {
+        if (SKIP_KEYS.has(key))
+            continue;
+        const value = node[key];
+        if (Array.isArray(value)) {
+            for (const item of value)
+                if (item && typeof item === 'object' && 'type' in item)
+                    walk(item, visit);
+        }
+        else if (value && typeof value === 'object' && 'type' in value) {
+            walk(value, visit);
+        }
+    }
+}
+/** Every string chunk inside a className attribute: literals and template quasis. */
+function classChunks(attr) {
+    const out = [];
+    walk(attr, (n) => {
+        if (n.type === 'Literal' && typeof n.value === 'string')
+            out.push({ node: n, text: n.value });
+        if (n.type === 'TemplateElement') {
+            const cooked = n.value?.cooked;
+            if (typeof cooked === 'string')
+                out.push({ node: n, text: cooked });
+        }
+    });
+    return out;
+}
+function isClassName(attr) {
+    const name = attr.name;
+    return attr.type === 'JSXAttribute' && name?.name === 'className';
+}
+/** A rule that reports any className chunk matching `pattern`. */
+function classNameRule(id, description, pattern, message) {
+    return {
+        meta: {
+            type: 'problem',
+            docs: { description, url: `${RULES_DOC}#rule${id}` },
+            messages: { violation: `${message} (rule/${id})` },
+            schema: [],
+        },
+        create(context) {
+            return {
+                JSXAttribute(node) {
+                    if (!isClassName(node))
+                        return;
+                    for (const chunk of classChunks(node)) {
+                        const match = chunk.text.match(pattern);
+                        if (match)
+                            context.report({ node: chunk.node, messageId: 'violation', data: { match: match[0] } });
+                    }
+                },
+            };
+        },
+    };
+}
+// ─── rules ───────────────────────────────────────────────────────────────────
+const STOCK_HUES = 'red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone';
+const COLOUR_UTILITIES = 'bg|text|border|ring|from|to|via|fill|stroke|outline|decoration|divide|accent|caret|placeholder|shadow';
+export const rules = {
+    'no-colour-literal': classNameRule('no-colour-literal', 'No raw colour value (hex, oklch, rgb, hsl) in a className', /#[0-9a-fA-F]{3,8}|oklch\(|rgba?\(|hsla?\(/, 'Arbitrary colour value in className. Use a semantic or primitive utility (bg-primary, text-muted-foreground, border-border, bg-surface); a missing value is a role to add, not a literal to inline'),
+    'no-arbitrary-clamp': classNameRule('no-arbitrary-clamp', 'No arbitrary fluid type size in a className', /text-\[clamp\(/, 'Arbitrary fluid type size in className. Use a named type role (text-display, text-section-title, text-lede) or add a token to roles.css'),
+    'no-dark-pairs': classNameRule('no-dark-pairs', 'No hand-authored dark: colour with an arbitrary value', new RegExp(`(^|[\\s"'\`])dark:(${COLOUR_UTILITIES})-\\[`), 'Hand-authored dark colour pair in className. The token owns both themes; write the single theme-aware class'),
+    'no-radius-literal': classNameRule('no-radius-literal', 'No arbitrary radius in a className', /(^|[\s"'`])rounded(-[a-z]{1,2})?-\[/, 'Arbitrary radius in className. The ramp is rounded-sm to rounded-4xl plus rounded-20; a new radius becomes a token first'),
+    'no-stock-palette': classNameRule('no-stock-palette', "No Tailwind default palette colour in product UI", new RegExp(`(^|[\\s"'\`:])(${COLOUR_UTILITIES})-(${STOCK_HUES})-(50|[1-9]00|950)(?![\\w-])`), "Tailwind's stock palette in className ({{match}}). It competes with the brand and ignores dark mode; use a token"),
+    'focus-visible': classNameRule('focus-visible', 'Focus rings use focus-visible:, not focus:', /(^|[\s"'`])focus:(ring|outline|border)/, 'focus: paints a ring for pointer users too (Radix autofocus makes this visible on open). Use focus-visible:'),
+    'on-dark-ramp': {
+        meta: {
+            type: 'problem',
+            docs: { description: 'Text on an always-dark surface comes from the on-dark ramp', url: `${RULES_DOC}#ruleon-dark-ramp` },
+            messages: {
+                violation: 'Theme-varying text token ({{match}}) inside an always-dark surface (bg-dark). It only matches in one theme; use the on-dark ramp, text-dark-ink to text-dark-faint-2 (rule/on-dark-ramp)',
+            },
+            schema: [],
+        },
+        create(context) {
+            const DARK_SURFACE = /(^|[\s"'`])bg-dark(-2)?(?![\w-])/;
+            // A light surface nested inside a dark one (a phone mock's screen, a
+            // force-light document preview) resets the context; its subtree is
+            // not walked.
+            const LIGHT_SURFACE = /(^|[\s"'`])(bg-(white|background|card|popover|surface|surface-2|band|band-2|primary|secondary|muted|accent)|force-light)(?![\w-])/;
+            const VARYING_TEXT = /(^|[\s"'`:])text-(ink|ink-2|ink-3|foreground|muted-foreground)(?![\w-])/;
+            const attributes = (el) => {
+                const opening = el.openingElement;
+                return (opening?.attributes ?? []).filter(isClassName);
+            };
+            const hasClass = (el, re) => attributes(el).some((a) => classChunks(a).some((c) => re.test(c.text)));
+            const check = (el) => {
+                for (const attr of attributes(el)) {
+                    for (const chunk of classChunks(attr)) {
+                        const match = chunk.text.match(VARYING_TEXT);
+                        if (match)
+                            context.report({ node: chunk.node, messageId: 'violation', data: { match: match[0].trim() } });
+                    }
+                }
+                for (const child of el.children ?? [])
+                    walkJsx(child);
+            };
+            // Walk JSX children, descending through expressions (ternaries, maps)
+            // but stopping at any element that paints a light surface.
+            const walkJsx = (n) => {
+                if (n.type === 'JSXElement') {
+                    if (hasClass(n, LIGHT_SURFACE))
+                        return;
+                    check(n);
+                    return;
+                }
+                for (const key of Object.keys(n)) {
+                    if (SKIP_KEYS.has(key))
+                        continue;
+                    const v = n[key];
+                    if (Array.isArray(v))
+                        v.forEach((x) => x && typeof x === 'object' && 'type' in x && walkJsx(x));
+                    else if (v && typeof v === 'object' && 'type' in v)
+                        walkJsx(v);
+                }
+            };
+            return {
+                JSXElement(node) {
+                    if (!hasClass(node, DARK_SURFACE))
+                        return;
+                    for (const child of node.children ?? [])
+                        walkJsx(child);
+                },
+            };
+        },
+    },
+    'no-em-dash': {
+        meta: {
+            type: 'suggestion',
+            docs: { description: 'No em dashes anywhere in source, comments included', url: `${RULES_DOC}#ruleno-em-dash` },
+            messages: { violation: 'Em dash. Use a comma, colon, full stop or parentheses (rule/no-em-dash)' },
+            schema: [],
+        },
+        create(context) {
+            return {
+                Program() {
+                    const lines = context.sourceCode.text.split('\n');
+                    lines.forEach((line, i) => {
+                        let col = line.indexOf('\u2014');
+                        while (col !== -1) {
+                            context.report({ loc: { start: { line: i + 1, column: col }, end: { line: i + 1, column: col + 1 } }, messageId: 'violation' });
+                            col = line.indexOf('\u2014', col + 1);
+                        }
+                    });
+                },
+            };
+        },
+    },
+};
 const forClassName = (regex, message) => [
     { selector: `JSXAttribute[name.name='className'] Literal[value=/${regex}/]`, message },
-    {
-        selector: `JSXAttribute[name.name='className'] TemplateElement[value.cooked=/${regex}/]`,
-        message,
-    },
+    { selector: `JSXAttribute[name.name='className'] TemplateElement[value.cooked=/${regex}/]`, message },
 ];
-export const noArbitraryColour = forClassName(COLOUR_REGEX, COLOUR_MESSAGE);
-export const noArbitraryTypeClamp = forClassName(TYPE_CLAMP_REGEX, TYPE_CLAMP_MESSAGE);
-/** A flat-config block: spread it into your eslint.config array. */
-export function designSystemGuardrails({ files = ['src/**/*.{ts,tsx}'], ignores = [], } = {}) {
+export const noArbitraryColour = forClassName('(#[0-9a-fA-F]{3,8}|oklch\\(|rgba?\\(|hsla?\\()', 'Arbitrary colour value in className. Use a semantic or primitive utility instead (rule/no-colour-literal).');
+export const noArbitraryTypeClamp = forClassName('text-\\[clamp\\(', 'Arbitrary fluid type size in className. Use a named type role (rule/no-arbitrary-clamp).');
+/** The plugin object, for configs that want to wire rules by hand. */
+export const plugin = {
+    meta: { name: '@fracazo/design-system', version: '0.4.0' },
+    rules,
+};
+/** Defaults: clean rules are errors; rules that need a cleanup pass first are warnings. */
+export const defaultSeverity = {
+    'no-colour-literal': 'error',
+    'no-arbitrary-clamp': 'error',
+    'no-dark-pairs': 'error',
+    'no-radius-literal': 'error',
+    'no-stock-palette': 'warn',
+    'focus-visible': 'warn',
+    'on-dark-ramp': 'warn',
+    'no-em-dash': 'warn',
+};
+/** A flat-config block: put it in your eslint.config array. */
+export function designSystemGuardrails({ files = ['src/**/*.{ts,tsx}'], ignores = [], severity = {} } = {}) {
+    const ruleConfig = {};
+    for (const id of Object.keys(rules))
+        ruleConfig[`design-system/${id}`] = severity[id] ?? defaultSeverity[id];
     return {
         files,
         ignores,
-        rules: {
-            'no-restricted-syntax': ['error', ...noArbitraryColour, ...noArbitraryTypeClamp],
-        },
+        plugins: { 'design-system': plugin },
+        rules: ruleConfig,
     };
 }

package/dist/guardrails/init.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};