@etus/seven-skill 0.1.0-beta.1

package/cli/engine/profile/profiler.mjs

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven Design System. Detector architecture adapted from
+// impeccable (Paul Bakaus, Apache-2.0). See packages/seven-skill/NOTICE.md.
+function profileNow() {
+  return typeof performance !== 'undefined' && performance.now
+    ? performance.now()
+    : Date.now();
+}
+
+function createDetectorProfile() {
+  return { events: [] };
+}
+
+function recordProfileEvent(profile, event) {
+  if (!profile) return;
+  const normalized = {
+    engine: event.engine || 'unknown',
+    phase: event.phase || 'unknown',
+    ruleId: event.ruleId || 'unknown',
+    target: event.target || '',
+    ms: Number.isFinite(event.ms) ? event.ms : 0,
+    findings: Number.isFinite(event.findings) ? event.findings : 0,
+  };
+  if (event.detail) normalized.detail = event.detail;
+  if (Array.isArray(event.findingIds) && event.findingIds.length) {
+    normalized.findingIds = event.findingIds;
+  }
+  if (typeof profile === 'function') {
+    profile(normalized);
+  } else if (typeof profile.record === 'function') {
+    profile.record(normalized);
+  } else if (Array.isArray(profile.events)) {
+    profile.events.push(normalized);
+  } else if (Array.isArray(profile)) {
+    profile.push(normalized);
+  }
+}
+
+function extractFindingIds(findings) {
+  if (!Array.isArray(findings) || findings.length === 0) return [];
+  return [...new Set(findings.map(f => f?.id || f?.type || f?.antipattern).filter(Boolean))];
+}
+
+function profileFindings(profile, meta, callback) {
+  if (!profile) return callback();
+  const started = profileNow();
+  const findings = callback();
+  recordProfileEvent(profile, {
+    ...meta,
+    ms: profileNow() - started,
+    findings: Array.isArray(findings) ? findings.length : 0,
+    findingIds: extractFindingIds(findings),
+  });
+  return findings;
+}
+
+function profileStep(profile, meta, callback) {
+  if (!profile) return callback();
+  const started = profileNow();
+  try {
+    return callback();
+  } finally {
+    recordProfileEvent(profile, {
+      ...meta,
+      ms: profileNow() - started,
+      findings: 0,
+    });
+  }
+}
+
+async function profileFindingsAsync(profile, meta, callback) {
+  if (!profile) return callback();
+  const started = profileNow();
+  const findings = await callback();
+  recordProfileEvent(profile, {
+    ...meta,
+    ms: profileNow() - started,
+    findings: Array.isArray(findings) ? findings.length : 0,
+    findingIds: extractFindingIds(findings),
+  });
+  return findings;
+}
+
+async function profileStepAsync(profile, meta, callback) {
+  if (!profile) return callback();
+  const started = profileNow();
+  try {
+    return await callback();
+  } finally {
+    recordProfileEvent(profile, {
+      ...meta,
+      ms: profileNow() - started,
+      findings: 0,
+    });
+  }
+}
+
+function percentile(sortedValues, pct) {
+  if (!sortedValues.length) return 0;
+  const idx = Math.min(
+    sortedValues.length - 1,
+    Math.max(0, Math.ceil((pct / 100) * sortedValues.length) - 1),
+  );
+  return sortedValues[idx];
+}
+
+function summarizeDetectorProfile(profile) {
+  const events = Array.isArray(profile)
+    ? profile
+    : (Array.isArray(profile?.events) ? profile.events : []);
+  const groups = new Map();
+  for (const event of events) {
+    const key = [
+      event.engine || 'unknown',
+      event.phase || 'unknown',
+      event.ruleId || 'unknown',
+      event.target || '',
+    ].join('\u0000');
+    let group = groups.get(key);
+    if (!group) {
+      group = {
+        engine: event.engine || 'unknown',
+        phase: event.phase || 'unknown',
+        ruleId: event.ruleId || 'unknown',
+        target: event.target || '',
+        calls: 0,
+        totalMs: 0,
+        findings: 0,
+        samples: [],
+      };
+      groups.set(key, group);
+    }
+    const ms = Number.isFinite(event.ms) ? event.ms : 0;
+    group.calls += 1;
+    group.totalMs += ms;
+    group.findings += Number.isFinite(event.findings) ? event.findings : 0;
+    group.samples.push(ms);
+  }
+  return [...groups.values()]
+    .map(group => {
+      const samples = group.samples.sort((a, b) => a - b);
+      return {
+        engine: group.engine,
+        phase: group.phase,
+        ruleId: group.ruleId,
+        target: group.target,
+        calls: group.calls,
+        totalMs: Number(group.totalMs.toFixed(3)),
+        avgMs: Number((group.totalMs / group.calls).toFixed(3)),
+        p50: Number(percentile(samples, 50).toFixed(3)),
+        p95: Number(percentile(samples, 95).toFixed(3)),
+        findings: group.findings,
+      };
+    })
+    .sort((a, b) => b.totalMs - a.totalMs);
+}
+
+export {
+  profileNow,
+  createDetectorProfile,
+  recordProfileEvent,
+  extractFindingIds,
+  profileFindings,
+  profileStep,
+  profileFindingsAsync,
+  profileStepAsync,
+  percentile,
+  summarizeDetectorProfile,
+};

package/cli/engine/registry/seven-antipatterns.mjs

@@ -0,0 +1,494 @@
+// SPDX-License-Identifier: Apache-2.0
+// ETUS Digital — Seven Design System. Detector architecture adapted from
+// impeccable (Paul Bakaus, Apache-2.0). See packages/seven-skill/NOTICE.md.
+
+import {
+  SEVEN_INTERNAL_PACKAGES,
+  TOKEN_DEFINITION_PATH_SEGMENTS,
+} from '../shared/constants.mjs'
+
+/**
+ * Seven anti-pattern catalog. The registry shape (id, category, name,
+ * description, skill cross-reference) mirrors the upstream detector, but the
+ * rules are Seven's own — tuned to the Seven Design System. `category` is
+ * 'quality' (real design / a11y / drift) or 'slop' (an AI tell, Seven-flavored).
+ *
+ * Three tiers of rule:
+ *  - Text rules: regex-on-source. Need no computed-style cascade.
+ *  - Element rules: per-element computed-style checks (static-html + browser).
+ *  - Page rules: whole-document checks (static-html + browser).
+ */
+const ANTIPATTERNS = [
+  // ── Seven text rules (Phase 1) ───────────────────────────────────────────
+  {
+    id: 'non-inter-font',
+    category: 'quality',
+    name: 'Non-Inter font family',
+    description:
+      'Font family is not Inter, JetBrains Mono, or a system fallback. Seven is Inter-only for sans and JetBrains Mono for code. Substitute Inter at the same size and surface the swap.',
+    skillReference: 'reference/typography.md',
+  },
+  {
+    id: 'hardcoded-color-not-token',
+    category: 'quality',
+    name: 'Hardcoded color literal',
+    description:
+      'Hex, rgb, hsl, or OKLCH color literal where an @etus/tokens CSS variable exists. Runtime code consumes var(--token); raw color literals belong only in packages/tokens/sources. When the literal matches a token value, the finding names the exact token.',
+    skillReference: 'reference/color-and-contrast.md',
+  },
+  {
+    id: 'raw-tailwind-palette-color',
+    category: 'quality',
+    name: 'Raw Tailwind palette color',
+    description:
+      'A Tailwind default-palette color utility (bg-green-500, text-neutral-900, border-red-200, ring-blue-500). The palette paints a color that bypasses @etus/tokens exactly as a hex literal does. Use a Seven color token via bg-[color:var(--*)] or the equivalent utility.',
+    skillReference: 'reference/color-and-contrast.md',
+  },
+  {
+    id: 'missing-color-type-hint',
+    category: 'quality',
+    name: 'Missing Tailwind v4 color type hint',
+    description:
+      'A Tailwind v4 arbitrary value referencing a color token is missing the color: hint (e.g. bg-[var(--primary)] instead of bg-[color:var(--primary)]). Lightning CSS drops the unhinted value silently.',
+    skillReference: 'reference/color-and-contrast.md',
+  },
+  {
+    id: 'missing-length-type-hint',
+    category: 'quality',
+    name: 'Missing Tailwind v4 length type hint',
+    description:
+      'A Tailwind v4 text-[var(--*)] arbitrary value resolving to a length is missing the length: hint. Lightning CSS drops the unhinted value silently.',
+    skillReference: 'reference/color-and-contrast.md',
+  },
+  {
+    id: 'leading-none-with-length-var',
+    category: 'quality',
+    name: 'leading-none with arbitrary length var',
+    description:
+      'leading-none combined with text-[length:var(--*)] zeroes line-height in Tailwind v4. Use leading-tight, leading-snug, a literal leading-[1.1], or inline style.',
+    skillReference: 'reference/typography.md',
+  },
+  {
+    id: 'fuchsia-in-ui-chrome',
+    category: 'slop',
+    name: 'Fuchsia on UI chrome',
+    description:
+      'Fuchsia is reserved for charts in Seven. On UI chrome (buttons, inputs, borders) it is an anti-pattern. Allowed inside <svg> and on elements tagged data-role="chart".',
+    skillReference: 'reference/color-and-contrast.md',
+  },
+  {
+    id: 'pt-pt-vocab',
+    category: 'quality',
+    name: 'European Portuguese vocabulary',
+    description:
+      'European Portuguese vocabulary in pt-BR chrome. Seven product copy is Brazilian Portuguese; use the pt-BR equivalent.',
+    skillReference: 'reference/ux-writing.md',
+  },
+  {
+    id: 'pure-black-or-white',
+    category: 'quality',
+    name: 'Pure black or white',
+    description:
+      'Pure #000 or #fff. Seven uses tinted neutrals from the OKLCH ramp; pure black and white read as harsh and unrefined.',
+    skillReference: 'reference/color-and-contrast.md',
+  },
+
+  // ── Inverted / retuned for Seven ─────────────────────────────────────────
+  {
+    id: 'side-stripe-border',
+    category: 'slop',
+    name: 'Side-stripe accent border',
+    description:
+      'A border-left or border-right thicker than 1px used as a colored accent stripe — the most recognizable tell of AI-generated UIs and banned in Seven. Use a full 1px var(--border), a background tint, a leading icon, or restructure the element.',
+    skillReference: 'reference/spatial-design.md',
+  },
+  {
+    id: 'gradient-text-decorative',
+    category: 'slop',
+    name: 'Decorative gradient text',
+    description:
+      'Decorative gradient text (background-clip: text + gradient). Seven text is solid color from the OKLCH ramp; gradient fills on headings and metrics are banned.',
+    skillReference: 'reference/color-and-contrast.md',
+  },
+  {
+    id: 'shadows-not-borders',
+    category: 'slop',
+    name: 'Glow shadow instead of border',
+    description:
+      'A colored, blurred box-shadow on a dark surface (the AI "dark glow" look) — or a shadow standing in for card chrome. Seven cards carry hierarchy with 1px borders; shadows are reserved for overlays.',
+    skillReference: 'reference/spatial-design.md',
+  },
+
+  // ── Universal design-quality / a11y rules ────────────────────────────────
+  {
+    id: 'low-contrast',
+    category: 'quality',
+    name: 'Low contrast text',
+    description:
+      'Text does not meet WCAG 2.1 AA contrast (4.5:1 for body, 3:1 for large text). Increase the contrast between text and background using Seven token pairs.',
+    skillReference: 'reference/color-and-contrast.md',
+  },
+  {
+    id: 'gray-on-color',
+    category: 'quality',
+    name: 'Gray text on colored background',
+    description:
+      'Gray text looks washed out on a colored background. Use a darker shade of the background hue, or a near-white foreground token, for legible contrast.',
+    skillReference: 'reference/color-and-contrast.md',
+  },
+  {
+    id: 'nested-cards',
+    category: 'slop',
+    name: 'Nested cards',
+    description:
+      'A card inside a card. Seven flattens hierarchy — use a section divider, a labeled list, or a Tabs view instead of nesting bordered containers.',
+    skillReference: 'reference/spatial-design.md',
+  },
+  {
+    id: 'monotonous-spacing',
+    category: 'quality',
+    name: 'Monotonous spacing',
+    description:
+      'The same spacing value used everywhere — no rhythm. Seven rhythm is intentional: tighter inside a card, looser between cards, looser still between sections.',
+    skillReference: 'reference/spatial-design.md',
+  },
+  {
+    id: 'flat-type-hierarchy',
+    category: 'quality',
+    name: 'Flat type hierarchy',
+    description:
+      'Font sizes too close together — no clear hierarchy. Walk the Seven Text/Heading ramp; pair scale with weight contrast.',
+    skillReference: 'reference/typography.md',
+  },
+  {
+    id: 'layout-transition',
+    category: 'quality',
+    name: 'Layout property animation',
+    description:
+      'Animating width, height, padding, or margin triggers reflow and looks janky. Seven motion animates transform and opacity only.',
+    skillReference: 'reference/motion-design.md',
+  },
+  {
+    id: 'line-length',
+    category: 'quality',
+    name: 'Line length too long',
+    description:
+      'Text lines wider than ~80 characters are hard to read. Add a max-width (65ch to 75ch) to body text containers.',
+    skillReference: 'reference/spatial-design.md',
+  },
+  {
+    id: 'cramped-padding',
+    category: 'quality',
+    name: 'Cramped padding',
+    description:
+      'Text sits too close to the edge of its container. Add padding scaled to the font size inside bordered or tinted containers.',
+    skillReference: 'reference/spatial-design.md',
+  },
+  {
+    id: 'body-text-viewport-edge',
+    category: 'quality',
+    name: 'Body text touching viewport edge',
+    description:
+      'Body paragraphs bleed flush against the viewport edge with no container padding. Wrap content in a padded container or apply max-width with mx-auto.',
+    skillReference: 'reference/spatial-design.md',
+  },
+  {
+    id: 'tight-leading',
+    category: 'quality',
+    name: 'Tight line height',
+    description:
+      'Line height below 1.3x the font size makes multi-line text hard to read. Seven body text uses 1.5 leading.',
+    skillReference: 'reference/typography.md',
+  },
+  {
+    id: 'skipped-heading',
+    category: 'quality',
+    name: 'Skipped heading level',
+    description:
+      'Heading levels skip (e.g. h1 then h3 with no h2). Screen readers use heading hierarchy for navigation; skipping levels breaks the document outline.',
+    skillReference: 'reference/typography.md',
+  },
+  {
+    id: 'justified-text',
+    category: 'quality',
+    name: 'Justified text',
+    description:
+      'Justified text without hyphenation creates rivers of uneven word spacing. Use text-align: left for body copy.',
+    skillReference: 'reference/typography.md',
+  },
+  {
+    id: 'tiny-text',
+    category: 'quality',
+    name: 'Tiny body text',
+    description:
+      'Body text below 12px is hard to read. Seven body content uses --text-base (16px); labels use --text-xs (12px) at minimum.',
+    skillReference: 'reference/typography.md',
+  },
+  {
+    id: 'all-caps-body',
+    category: 'quality',
+    name: 'All-caps body text',
+    description:
+      'Long passages in uppercase are hard to read. Seven reserves uppercase for short monospaced data-table column headers; body copy is sentence case.',
+    skillReference: 'reference/typography.md',
+  },
+  {
+    id: 'wide-tracking',
+    category: 'quality',
+    name: 'Wide letter spacing on body text',
+    description:
+      'Letter spacing above 0.05em on body text slows reading. Seven labels use Inter at default tracking; wide tracking is a Display-only choice.',
+    skillReference: 'reference/typography.md',
+  },
+  {
+    id: 'bounce-easing',
+    category: 'slop',
+    name: 'Bounce or elastic easing',
+    description:
+      'Bounce, elastic, or spring easing. Seven motion is decelerated and stops — no overshoot in chrome. Use --ease-default or --ease-out-quart.',
+    skillReference: 'reference/motion-design.md',
+  },
+  {
+    id: 'everything-centered',
+    category: 'slop',
+    name: 'Everything centered',
+    description:
+      'Every text element is center-aligned. Seven chrome is left-aligned with intentional asymmetry; center only deliberate display surfaces.',
+    skillReference: 'reference/spatial-design.md',
+  },
+
+  // ── Seven element-level rules ────────────────────────────────────────────
+  {
+    id: 'missing-tactile-press',
+    category: 'quality',
+    name: 'Clickable without tactile press',
+    description:
+      'A clickable affordance (button, role="button", interactive list item) with no transform-based micro-press transition. Seven gives every affordance the system-wide tactile press (hover translateY -1px, active 0.5px).',
+    skillReference: 'reference/motion-design.md',
+  },
+  {
+    id: 'pill-on-button',
+    category: 'slop',
+    name: 'Pill radius on a button',
+    description:
+      'A button with border-radius 9999 / rounded-full. Buttons stay on the component radius scale (md 8). Pill radius is for badges, status indicators, and avatar triggers only.',
+    skillReference: 'reference/spatial-design.md',
+  },
+  {
+    id: 'radius-mixed-scales',
+    category: 'quality',
+    name: 'Mixed radius scales',
+    description:
+      'A component-scale radius (4 / 8 / 12) mixed with a surface-scale radius (16 / 20 / 24 / 32) on the same element. The two radius stacks are not interchangeable; mixing them produces "almost looks right" drift.',
+    skillReference: 'reference/spatial-design.md',
+  },
+  {
+    id: 'non-lucide-icon',
+    category: 'slop',
+    name: 'Non-Lucide icon',
+    description:
+      'An inline <svg> that is not a Lucide icon (Lucide uses 24x24 viewBox, 2px stroke, round line caps and joins, no fill). Seven uses the Lucide set exclusively.',
+    skillReference: 'reference/typography.md',
+  },
+  {
+    id: 'emoji-in-chrome',
+    category: 'slop',
+    name: 'Emoji in UI chrome',
+    description:
+      'An emoji character inside button, label, or heading text. Seven chrome uses Lucide icons, not emoji glyphs, which render inconsistently across platforms.',
+    skillReference: 'reference/ux-writing.md',
+  },
+  {
+    id: 'forbidden-em-dash',
+    category: 'quality',
+    name: 'Em-dash or en-dash in copy',
+    description:
+      'An em-dash or en-dash in user-facing copy. Seven copy uses a comma, a colon, or a sentence break; the long dash reads as machine-generated prose.',
+    skillReference: 'reference/ux-writing.md',
+  },
+]
+
+/**
+ * Which engines can detect each rule.
+ *  - regex: source text scan. Catches text rules and the regex-matchable
+ *    CSS/Tailwind shapes of element/page rules.
+ *  - static-html: parsed-document computed-style cascade.
+ *  - browser: rendered-page text + stylesheet extraction.
+ */
+const TEXT_RULE_IDS = new Set([
+  'non-inter-font',
+  'hardcoded-color-not-token',
+  'raw-tailwind-palette-color',
+  'missing-color-type-hint',
+  'missing-length-type-hint',
+  'leading-none-with-length-var',
+  'fuchsia-in-ui-chrome',
+  'pt-pt-vocab',
+  'pure-black-or-white',
+  'emoji-in-chrome',
+  'forbidden-em-dash',
+])
+
+/** Element/page rules the static-html cascade can resolve. */
+const STATIC_HTML_RULE_IDS = new Set([
+  'side-stripe-border',
+  'gradient-text-decorative',
+  'shadows-not-borders',
+  'low-contrast',
+  'gray-on-color',
+  'nested-cards',
+  'monotonous-spacing',
+  'flat-type-hierarchy',
+  'layout-transition',
+  'line-length',
+  'cramped-padding',
+  'body-text-viewport-edge',
+  'tight-leading',
+  'skipped-heading',
+  'justified-text',
+  'tiny-text',
+  'all-caps-body',
+  'wide-tracking',
+  'bounce-easing',
+  'everything-centered',
+  'missing-tactile-press',
+  'pill-on-button',
+  'radius-mixed-scales',
+  'non-lucide-icon',
+])
+
+const RULE_ENGINE_SUPPORT = {
+  // Every rule is reachable by the regex engine on raw source.
+  regex: new Set(ANTIPATTERNS.map((r) => r.id)),
+  // Text rules + element/page rules the static cascade can resolve.
+  'static-html': new Set([...TEXT_RULE_IDS, ...STATIC_HTML_RULE_IDS]),
+  // The browser engine extracts rendered markup + stylesheet text and runs
+  // the same text + static-html checks against the rendered document.
+  browser: new Set([...TEXT_RULE_IDS, ...STATIC_HTML_RULE_IDS]),
+}
+
+/**
+ * Per-rule exemptions. Resolved against the file being scanned:
+ * - skipPackages: skip files whose owning package.json name is in the set.
+ * - skipPathSegments: skip files whose path contains any segment.
+ * Test fixtures bypass exemptions entirely (see detect facade).
+ */
+const NO_EXEMPTION = { skipPackages: new Set(), skipPathSegments: [] }
+const DOC_PATH_SEGMENTS = ['docs/audits/', 'docs/proposals/', 'docs/plans/']
+
+const RULE_EXEMPTIONS = {
+  // Text rules.
+  'non-inter-font': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: [] },
+  'hardcoded-color-not-token': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: TOKEN_DEFINITION_PATH_SEGMENTS },
+  'raw-tailwind-palette-color': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: TOKEN_DEFINITION_PATH_SEGMENTS },
+  'missing-color-type-hint': NO_EXEMPTION,
+  'missing-length-type-hint': NO_EXEMPTION,
+  'leading-none-with-length-var': NO_EXEMPTION,
+  'fuchsia-in-ui-chrome': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: [] },
+  'pt-pt-vocab': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: [] },
+  'pure-black-or-white': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: TOKEN_DEFINITION_PATH_SEGMENTS },
+  // Inverted / retuned.
+  'side-stripe-border': NO_EXEMPTION,
+  'gradient-text-decorative': NO_EXEMPTION,
+  'shadows-not-borders': NO_EXEMPTION,
+  // Universal design-quality / a11y.
+  'low-contrast': NO_EXEMPTION,
+  'gray-on-color': NO_EXEMPTION,
+  'nested-cards': NO_EXEMPTION,
+  'monotonous-spacing': NO_EXEMPTION,
+  'flat-type-hierarchy': NO_EXEMPTION,
+  'layout-transition': NO_EXEMPTION,
+  'line-length': NO_EXEMPTION,
+  'cramped-padding': NO_EXEMPTION,
+  'body-text-viewport-edge': NO_EXEMPTION,
+  'tight-leading': NO_EXEMPTION,
+  'skipped-heading': NO_EXEMPTION,
+  'justified-text': NO_EXEMPTION,
+  'tiny-text': NO_EXEMPTION,
+  'all-caps-body': NO_EXEMPTION,
+  'wide-tracking': NO_EXEMPTION,
+  'bounce-easing': NO_EXEMPTION,
+  'everything-centered': NO_EXEMPTION,
+  // Seven element-level rules.
+  'missing-tactile-press': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: [] },
+  'pill-on-button': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: [] },
+  'radius-mixed-scales': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: [] },
+  'non-lucide-icon': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: [] },
+  // Emoji and the long dash legitimately appear in audit/proposal prose.
+  'emoji-in-chrome': { skipPackages: SEVEN_INTERNAL_PACKAGES, skipPathSegments: DOC_PATH_SEGMENTS },
+  'forbidden-em-dash': { skipPackages: new Set(), skipPathSegments: [...TOKEN_DEFINITION_PATH_SEGMENTS, ...DOC_PATH_SEGMENTS] },
+}
+
+/**
+ * Grounding audit. Every rule is either 'token' — its data comes from the
+ * @etus/tokens snapshot, so it tracks the design system automatically — or
+ * 'heuristic' — it enforces a language fact, a CSS/tooling mechanic, an a11y
+ * standard, or a structural pattern that no token defines. The audit is a
+ * durable artifact: a rule's verdict is inspectable, and 'heuristic' is a
+ * deliberate verdict, not an unfinished one.
+ */
+const RULE_GROUNDING = {
+  // Token-grounded — data sourced from @etus/tokens.
+  'non-inter-font': { grounding: 'token', reason: 'Allowed families read from the fontFamily tokens.' },
+  'hardcoded-color-not-token': { grounding: 'token', reason: 'Literal colors resolved to the exact token via the color snapshot.' },
+  'raw-tailwind-palette-color': { grounding: 'token', reason: 'Exists to enforce the @etus/tokens boundary against the Tailwind palette.' },
+  'pure-black-or-white': { grounding: 'token', reason: 'Anchored on the base-black / base-white token values, which it names.' },
+  'tiny-text': { grounding: 'token', reason: 'Floor is the smallest font-size token.' },
+  'radius-mixed-scales': { grounding: 'token', reason: 'Component and surface radius tiers derived from the radius tokens.' },
+  'pill-on-button': { grounding: 'token', reason: 'Pill threshold anchored on the full-radius token.' },
+  'bounce-easing': { grounding: 'token', reason: 'Exempts cubic-beziers that match a sanctioned easing token.' },
+  // Heuristic — no token defines the rule.
+  'missing-color-type-hint': { grounding: 'heuristic', reason: 'Tailwind v4 / Lightning CSS mechanic.' },
+  'missing-length-type-hint': { grounding: 'heuristic', reason: 'Tailwind v4 / Lightning CSS mechanic.' },
+  'leading-none-with-length-var': { grounding: 'heuristic', reason: 'Tailwind v4 line-height interaction bug.' },
+  'fuchsia-in-ui-chrome': { grounding: 'heuristic', reason: 'Hue-band detection plus svg/chart context — no token lookup.' },
+  'pt-pt-vocab': { grounding: 'heuristic', reason: 'Language vocabulary — a linguistic fact, not a token.' },
+  'side-stripe-border': { grounding: 'heuristic', reason: 'Structural pattern: thick one-sided colored border.' },
+  'gradient-text-decorative': { grounding: 'heuristic', reason: 'CSS shape: background-clip:text with a gradient.' },
+  'shadows-not-borders': { grounding: 'heuristic', reason: 'Detects a colored blurred shadow standing in for chrome.' },
+  'low-contrast': { grounding: 'heuristic', reason: 'WCAG 2.1 AA ratio — an accessibility standard.' },
+  'gray-on-color': { grounding: 'heuristic', reason: 'Gray-on-colored-background legibility heuristic.' },
+  'nested-cards': { grounding: 'heuristic', reason: 'Structural: a bordered container inside another.' },
+  'monotonous-spacing': { grounding: 'heuristic', reason: 'Spacing-variety judgment — no token threshold.' },
+  'flat-type-hierarchy': { grounding: 'heuristic', reason: 'Type-scale spread judgment — no token threshold.' },
+  'layout-transition': { grounding: 'heuristic', reason: 'CSS fact: animating layout properties causes reflow.' },
+  'line-length': { grounding: 'heuristic', reason: 'Readability heuristic (~80 characters).' },
+  'cramped-padding': { grounding: 'heuristic', reason: 'Text-to-edge proximity heuristic.' },
+  'body-text-viewport-edge': { grounding: 'heuristic', reason: 'Layout heuristic: body text flush to the viewport.' },
+  'tight-leading': { grounding: 'heuristic', reason: 'Readability ratio (1.3x) — no token threshold.' },
+  'skipped-heading': { grounding: 'heuristic', reason: 'Document-structure / a11y outline rule.' },
+  'justified-text': { grounding: 'heuristic', reason: 'CSS fact: justify without hyphenation.' },
+  'all-caps-body': { grounding: 'heuristic', reason: 'Readability heuristic for long uppercase runs.' },
+  'wide-tracking': { grounding: 'heuristic', reason: 'Body-context letter-spacing threshold (0.05em).' },
+  'everything-centered': { grounding: 'heuristic', reason: 'Layout-distribution heuristic.' },
+  'missing-tactile-press': { grounding: 'heuristic', reason: 'Detects presence of a transform-press transition.' },
+  'non-lucide-icon': { grounding: 'heuristic', reason: 'SVG attribute shape (24x24 viewBox, 2px stroke).' },
+  'emoji-in-chrome': { grounding: 'heuristic', reason: 'Unicode emoji ranges in chrome text.' },
+  'forbidden-em-dash': { grounding: 'heuristic', reason: 'Character rule — em-dash / en-dash in copy.' },
+}
+
+export function getRuleGrounding(id) {
+  return RULE_GROUNDING[id] || { grounding: 'heuristic', reason: 'Unclassified.' }
+}
+
+export function getAntipattern(id) {
+  return ANTIPATTERNS.find((rule) => rule.id === id)
+}
+
+export function getRulesForCategory(category) {
+  return ANTIPATTERNS.filter((rule) => rule.category === category)
+}
+
+export function getRuleEngineSupport(engine) {
+  return RULE_ENGINE_SUPPORT[engine] || new Set()
+}
+
+export function getRuleExemption(id) {
+  return RULE_EXEMPTIONS[id] || { skipPackages: new Set(), skipPathSegments: [] }
+}
+
+export function getRuleIds() {
+  return ANTIPATTERNS.map((r) => r.id)
+}
+
+export { ANTIPATTERNS, RULE_ENGINE_SUPPORT, RULE_EXEMPTIONS, RULE_GROUNDING }