@fracazo/design-system 0.2.1 → 0.7.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.
@@ -215,7 +220,7 @@ Source order is reading order; landmarks and heading levels are real;
 
 ## Components
 
-The package ships seventeen shadcn-based components under
+The package ships eighteen components, seventeen shadcn-based and one house primitive, under
 `@fracazo/design-system/ui/*`. Each carries an intent block at the top of
 its source (one line, then Use for, Avoid when, Variants); that block is
 the contract and is updated whenever variants change. In brief:
@@ -245,6 +250,11 @@ the contract and is updated whenever variants change. In brief:
   bespoke. **Calendar** exists for range selection; a single date uses a
   native input. **SortableList** ranks a small capped set with drag,
   touch and keyboard.
+- **OfferCard** is the one house primitive: a linked offer surface with
+  a media slot, tag, title, description and a source footer, for a grid
+  of peer offers. The whole card is one link; `highlighted` is its single
+  emphasis signal; hover motion is CSS transitions under motion-safe.
+  It lays out in a grid, never a carousel.
 
 A component that must import app code (stores, data clients, routes)
 does not belong in the package; it stays in the product, like

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 eighteen 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`) |
-| `@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` |
+| `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 eighteen components (button, card, dialog, form, select, sortable-list, offer-card and the rest), each with intent JSDoc: use for, avoid when, variants |
+| `@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 {};