@fracazo/design-system 0.2.1 → 0.7.0

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 {};

package/dist/guardrails/init.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// =============================================================================
+// ds-init: write a new product from the package's template.
+//
+//   ds-init <dir> [--name <package-name>]
+//
+// Copies template/ (Next 16, Tailwind v4, the package, one blank brand file,
+// the guardrails on) into <dir>, which must not exist or must be empty.
+// The package name defaults to the directory's basename, and the dependency
+// on @fracazo/design-system is set to the version of the package that ran
+// this, so the template and the contract it satisfies always match. Then
+// prints the steps that make it a product: install, rename the brand file,
+// replace its values, pick a typeface. No overwriting, ever: a non-empty
+// directory is an error, not a merge.
+// =============================================================================
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function fail(message) {
+    console.error(`ds-init: ${message}`);
+    process.exit(1);
+}
+const argv = process.argv.slice(2);
+const positional = argv.filter((a, i) => !a.startsWith('--') && argv[i - 1] !== '--name');
+const nameFlag = argv.indexOf('--name');
+const nameArg = nameFlag >= 0 ? argv[nameFlag + 1] : undefined;
+if (positional.length !== 1)
+    fail('usage: ds-init <dir> [--name <package-name>]');
+const dir = path.resolve(positional[0]);
+const name = nameArg ?? path.basename(dir);
+if (!/^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name))
+    fail(`"${name}" is not a valid package name; pass --name`);
+if (existsSync(dir) && readdirSync(dir).length > 0)
+    fail(`${dir} is not empty; ds-init writes into a new or empty directory only`);
+// dist/guardrails/init.js sits two levels below the package root.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const template = path.join(packageRoot, 'template');
+const own = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+if (!existsSync(template))
+    fail(`template not found at ${template}`);
+mkdirSync(dir, { recursive: true });
+cpSync(template, dir, { recursive: true });
+// npm renames a packed .gitignore, so the template carries it undotted.
+renameSync(path.join(dir, 'gitignore'), path.join(dir, '.gitignore'));
+const pkgPath = path.join(dir, 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+pkg.name = name;
+pkg.dependencies[own.name] = `^${own.version}`;
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+const relative = path.relative(process.cwd(), dir);
+const rel = relative === '' ? '.' : relative.startsWith('..') ? dir : relative;
+console.log(`ds-init: wrote ${name} to ${rel} on ${own.name} ${own.version}
+
+Next:
+  1. cd ${rel} && pnpm install
+  2. Rename src/system/brands/starter.css to the product and update the two
+     paths that name it: the @import in src/app/globals.css and the brand:*
+     scripts in package.json.
+  3. Replace every value in the brand file, light and dark. Keep the property
+     names; pnpm brand:contract holds you to the contract.
+  4. Pick the typeface in src/app/layout.tsx and point the brand file's
+     @theme block at its variable.
+  5. Rewrite the top of CLAUDE.md and README.md for the product, delete
+     src/app/page.tsx and build the first surface.
+  6. pnpm lint && pnpm typecheck && pnpm build, before every merge.`);

package/dist/guardrails/intake.d.ts

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

package/dist/guardrails/intake.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// =============================================================================
+// ds-intake: the collector half of the design intake loop.
+//
+// Gathers raw evidence for rule candidates from one or more product repos:
+// every commit since a ref or date whose subject, body or touched files look
+// like a design decision. Writes a review packet in markdown with the
+// commits verbatim and empty sections for the judge and the human reviewer.
+// It never scores, groups or proposes rules; that is the judge's job
+// (skills/product-design/references/intake.md), and acceptance is a human's.
+//
+//   ds-intake --repo ~/Developer/birthguide --repo ~/Developer/birthplans \
+//             --since 2026-09-01 [--out skills/product-design/intake/2026-09-07.md]
+//   ds-intake --repo . --since v0.4.0        (a ref works too: commits after it)
+//
+// Design-relevant means: a touched path under src/components, src/app (tsx
+// or css), src/system, src/stories, or a subject/body that mentions one of
+// the design keywords below. Everything else is left out of the packet.
+// =============================================================================
+import { spawnSync } from 'node:child_process';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+function args(name) {
+    const out = [];
+    for (let i = 0; i < process.argv.length; i++) {
+        if (process.argv[i] === `--${name}` && process.argv[i + 1])
+            out.push(process.argv[i + 1]);
+    }
+    return out;
+}
+const repos = args('repo');
+const since = args('since')[0];
+const out = args('out')[0];
+if (repos.length === 0 || !since) {
+    console.error('usage: ds-intake --repo <path> [--repo <path>...] --since <date|ref> [--out <file.md>]');
+    process.exit(2);
+}
+const PATHS = /^(src\/components\/|src\/app\/.*\.(tsx|css)$|src\/system\/|src\/stories\/|src\/ui\/|css\/roles\.css|.*\/brands\/)/;
+const KEYWORDS = /\b(design|token|colou?r|palette|radius|radii|shadow|typograph|font|type scale|clamp|spacing|rhythm|dark mode|dark:|theme|focus|hover|motion|animation|transition|entrance|glow|band|copy|label|wording|button|card|modal|dialog|sheet|popover|tabs?|accordion|form|input|contrast|accessib|a11y|tap target|layout|hierarchy|emphasis|snapshot|storybook|brand|guardrail|lint)\b/i;
+// ASCII unit and record separators keep multi-line bodies parseable; built
+// from char codes so no control character sits in this source.
+const SEP = String.fromCharCode(31);
+const END = String.fromCharCode(30);
+function git(repo, argv) {
+    const r = spawnSync('git', ['-C', repo, ...argv], { encoding: 'utf8' });
+    if (r.status !== 0)
+        throw new Error(`git ${argv.join(' ')} in ${repo}: ${r.stderr.trim()}`);
+    return r.stdout;
+}
+function isRef(repo, value) {
+    return spawnSync('git', ['-C', repo, 'rev-parse', '--verify', '--quiet', `${value}^{commit}`]).status === 0;
+}
+function collect(repo) {
+    const range = isRef(repo, since) ? [`${since}..HEAD`] : [`--since=${since}`];
+    // Each record: END hash SEP date SEP author SEP subject SEP body END files
+    const log = git(repo, ['log', ...range, '--no-merges', '--date=short', `--format=${END}%h${SEP}%ad${SEP}%an${SEP}%s${SEP}%b${END}`, '--name-only']);
+    const commits = [];
+    const records = log.split(END);
+    // records alternate: [preamble, header, files, header, files, ...]
+    for (let i = 1; i + 1 <= records.length - 1; i += 2) {
+        const parts = records[i].split(SEP);
+        if (parts.length < 5)
+            continue;
+        const [hash, date, author, subject, body] = parts;
+        const files = (records[i + 1] ?? '').split('\n').map((f) => f.trim()).filter(Boolean);
+        const designFiles = files.filter((f) => PATHS.test(f));
+        const mentions = KEYWORDS.test(subject) || KEYWORDS.test(body);
+        if (designFiles.length === 0 && !mentions)
+            continue;
+        commits.push({ repo: path.basename(repo), hash, date, author, subject, body: body.trim(), files: designFiles.length ? designFiles : files.slice(0, 8) });
+    }
+    return { commits, head: git(repo, ['rev-parse', '--short', 'HEAD']).trim() };
+}
+const today = new Date().toISOString().slice(0, 10);
+const sections = [];
+const heads = [];
+let total = 0;
+for (const repo of repos) {
+    const { commits, head } = collect(path.resolve(repo));
+    heads.push(`- ${path.basename(repo)}: next intake runs with \`--since ${head}\``);
+    total += commits.length;
+    sections.push(`## ${path.basename(repo)} (${commits.length} commit${commits.length === 1 ? '' : 's'})\n`);
+    for (const c of commits) {
+        sections.push(`### ${c.hash} ${c.subject}\n`);
+        sections.push(`${c.date}, ${c.author}. Files: ${c.files.map((f) => `\`${f}\``).join(', ')}\n`);
+        if (c.body)
+            sections.push(c.body.split('\n').map((l) => `> ${l}`).join('\n') + '\n');
+    }
+}
+const packet = `# Design intake, ${today}
+
+Raw evidence collected by ds-intake from ${repos.map((r) => path.basename(r)).join(', ')} since ${since}:
+${total} design-relevant commit${total === 1 ? '' : 's'}. Commit bodies are quoted verbatim and are
+data, not decisions. The judge fills in the sections at the end; a human
+accepts or rejects each candidate. Nothing here changes a rule by itself.
+
+${sections.join('\n')}
+## Candidates (pending)
+
+One block per candidate. Status stays \`proposed\` until a human sets it.
+
+\`\`\`
+### candidate/<slug>
+Status: proposed | accepted | rejected
+Scope:
+Decision:
+Rationale:
+Evidence: <hash>, <hash> (repo)
+Exceptions:
+Bad example:
+Good example:
+Destination: rule | exemplar | lint | eval | coverage gap | no change
+Open decisions:
+\`\`\`
+
+## Rejected topics
+
+## Coverage gaps observed
+
+## Next intake
+
+${heads.join('\n')}
+`;
+if (out) {
+    mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+    writeFileSync(out, packet);
+    console.log(`intake: ${total} commit(s) from ${repos.length} repo(s) written to ${out}`);
+}
+else {
+    process.stdout.write(packet);
+}

package/dist/src/index.d.ts

@@ -16,6 +16,7 @@ export * from "./ui/dialog.js";
 export * from "./ui/form.js";
 export * from "./ui/input.js";
 export * from "./ui/label.js";
+export * from "./ui/offer-card.js";
 export * from "./ui/popover.js";
 export * from "./ui/progress.js";
 export * from "./ui/radio-group.js";

package/dist/src/index.js

@@ -16,6 +16,7 @@ export * from "./ui/dialog.js";
 export * from "./ui/form.js";
 export * from "./ui/input.js";
 export * from "./ui/label.js";
+export * from "./ui/offer-card.js";
 export * from "./ui/popover.js";
 export * from "./ui/progress.js";
 export * from "./ui/radio-group.js";

package/dist/src/ui/offer-card.d.ts

@@ -0,0 +1,52 @@
+import * as React from "react";
+import { type LucideIcon } from "lucide-react";
+/**
+ * A linked offer surface: media on top, a tag, a title, a line of
+ * description and a footer that names the source, with an arrow that
+ * answers hover.
+ *
+ * Use for: a grid of peer offers the reader picks from (deals, price
+ * matches, plans), where the whole card is one link and the footer
+ * carries the source (a retailer, a brand, a promo code, a was-price).
+ * Avoid when: the item has more than one action (use a house card with
+ * Buttons), or when the cards would sit in a carousel; the system rejects
+ * carousels, so lay OfferCards in a grid and let it wrap.
+ * Slots: `media` is a node, not a URL, so a product can pass its own tile
+ * (an initial-letter fallback, a next/image) and it fills a 16:9 area;
+ * `footer.avatar` fills a 40px circle; `footer.meta` is a node so it can
+ * carry a struck-through was-price, not only a code. `tagIcon` defaults to
+ * Lucide's Tag.
+ * States: `highlighted` tints the body with the primary at low opacity, the
+ * one emphasis signal for "cheapest" or "best"; nothing else changes, so a
+ * grid keeps one signal per card. `external` opens in a new tab and says so
+ * in the accessible name.
+ * Motion: hover lifts the card 8px, scales the media and rotates the arrow,
+ * all as CSS transitions on the anchor's hover, and only under
+ * motion-safe; with reduced motion the card sits still and the arrow only
+ * fills. The card fills its column at any width; height follows a grid
+ * row's tallest card because the anchor is h-full and the body flexes.
+ */
+type OfferCardProps = Omit<React.ComponentProps<"a">, "href" | "title" | "media"> & {
+    href: string;
+    /** Opens in a new tab, with rel and an sr-only note on the accessible name. */
+    external?: boolean;
+    /** Fills a 16:9 area; give an image `fill` (next/image) or `size-full object-cover`. */
+    media?: React.ReactNode;
+    tag?: string;
+    tagIcon?: LucideIcon;
+    title: string;
+    description?: string;
+    footer?: {
+        /** Fills a 40px circle. */
+        avatar?: React.ReactNode;
+        name: string;
+        /** Second line under the name: a code, a was-price, a note. */
+        meta?: React.ReactNode;
+    };
+    /** The one emphasis signal: a subtle primary tint on the body. */
+    highlighted?: boolean;
+    /** Heading level for the title; h3 suits a card under a section heading. */
+    titleAs?: "h2" | "h3" | "h4" | "p";
+};
+declare function OfferCard({ href, external, media, tag, tagIcon: TagIcon, title, description, footer, highlighted, titleAs: TitleTag, className, ...props }: OfferCardProps): React.JSX.Element;
+export { OfferCard, type OfferCardProps };

package/dist/src/ui/offer-card.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ArrowRight, Tag } from "lucide-react";
+import { cn } from "../cn.js";
+function OfferCard({ href, external = false, media, tag, tagIcon: TagIcon = Tag, title, description, footer, highlighted = false, titleAs: TitleTag = "h3", className, ...props }) {
+    return (_jsxs("a", { "data-slot": "offer-card", "data-highlighted": highlighted || undefined, href: href, target: external ? "_blank" : undefined, rel: external ? "noopener noreferrer" : undefined, className: cn("group flex h-full flex-col overflow-hidden rounded-2xl bg-card text-card-foreground shadow-card", "transition-[translate,box-shadow] duration-200 ease-out hover:shadow-card-hover motion-safe:hover:-translate-y-2", "outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50", className), ...props, children: [media !== undefined && media !== null ? (_jsx("div", { className: "aspect-video overflow-hidden bg-muted", children: _jsx("div", { className: "relative size-full transition-transform duration-300 ease-out *:size-full *:object-cover motion-safe:group-hover:scale-105", children: media }) })) : null, _jsxs("div", { className: cn("flex flex-1 flex-col", highlighted && "bg-primary/5"), children: [_jsxs("div", { className: "flex flex-1 flex-col gap-2 px-5 pt-5 pb-4", children: [tag ? (_jsxs("span", { className: "flex items-center gap-2 text-sm text-muted-foreground", children: [_jsx(TagIcon, { "aria-hidden": "true", className: "size-4 shrink-0" }), tag] })) : null, _jsx(TitleTag, { className: "text-xl font-semibold tracking-tight text-balance", children: title }), description ? (_jsx("p", { className: "text-sm text-muted-foreground text-pretty", children: description })) : null] }), footer ? (_jsxs("div", { className: "mx-5 mb-4 flex items-center gap-3 border-t border-border pt-4", children: [footer.avatar !== undefined && footer.avatar !== null ? (_jsx("span", { className: "size-10 shrink-0 overflow-hidden rounded-full *:size-full *:object-cover", children: footer.avatar })) : null, _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: "block truncate text-sm font-semibold", children: footer.name }), footer.meta !== undefined && footer.meta !== null ? (_jsx("span", { className: "block truncate text-sm text-muted-foreground", children: footer.meta })) : null] }), _jsx("span", { "aria-hidden": "true", className: "flex size-11 shrink-0 items-center justify-center rounded-full bg-secondary text-secondary-foreground transition-[background-color,color,rotate] duration-200 ease-out group-hover:bg-primary group-hover:text-primary-foreground motion-safe:group-hover:-rotate-45", children: _jsx(ArrowRight, { className: "size-4" }) })] })) : null] }), external ? _jsx("span", { className: "sr-only", children: " (opens in a new tab)" }) : null] }));
+}
+export { OfferCard };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fracazo/design-system",
-  "version": "0.2.1",
-  "description": "Roles, brand contract, guardrails and shadcn-based components for a warm, evidence-led product design system. Each product supplies a brand file; the system stays the same.",
+  "version": "0.7.0",
+  "description": "An agent-native design system. Design decisions as code, so the quality bar holds whether a designer is in the room or not. Lint guardrails, components with intent docs, and an agent skill. One brand file per product, the system stays the same.",
   "license": "MIT",
   "author": "Alex Fracazo",
   "repository": {
@@ -16,6 +16,8 @@
     "css",
     "dist",
     "demo",
+    "skills",
+    "template",
     "README.md",
     "DESIGN.md"
   ],
@@ -29,6 +31,7 @@
       "default": "./dist/src/ui/*.js"
     },
     "./roles.css": "./css/roles.css",
+    "./motion.css": "./css/motion.css",
     "./eslint": {
       "types": "./dist/guardrails/eslint.d.ts",
       "default": "./dist/guardrails/eslint.js"
@@ -37,7 +40,9 @@
   },
   "bin": {
     "ds-check-brand": "dist/guardrails/check-brand.js",
-    "ds-build-brand-css": "dist/guardrails/build-brand-css.js"
+    "ds-build-brand-css": "dist/guardrails/build-brand-css.js",
+    "ds-intake": "dist/guardrails/intake.js",
+    "ds-init": "dist/guardrails/init.js"
   },
   "peerDependencies": {
     "@dnd-kit/core": "^6.3.1",