@urbicon-ui/mcp-server 6.1.4

package/src/design-linter/rules.ts

@@ -0,0 +1,348 @@
+/**
+ * Deterministic design rules. Each is a fact about the code — a regex/string
+ * match with no judgement — so it can carry `error`/`warning` severity and be
+ * covered by regression tests. The prose source is the Anti-Patterns section of
+ * `design-system/principles.md` plus the documented known failure modes
+ * (token hallucination, dynamic Tailwind classes).
+ */
+
+import {
+  INTENT_NAMES,
+  INTENT_PREFIXES,
+  KNOWN_BAD_NAMESPACES,
+  KNOWN_FOREIGN_CORES,
+  SEMANTIC_NAMESPACES,
+  VALID_TOKEN_CORES
+} from './tokens.js';
+import type { Finding, Rule } from './types.js';
+
+const SHADCN_FIX =
+  'This is shadcn/ui vocabulary, not Urbicon UI. Use surface tokens (`bg-surface-base`/`-elevated`), text tokens (`text-text-primary`/`-secondary`), or intents (`bg-primary`, `text-success`).';
+
+/** shadcn/ui-family cores (bare set + `-foreground` suffix + `fg`/`fg-`). */
+function isForeignVocab(core: string): boolean {
+  return (
+    KNOWN_FOREIGN_CORES.has(core) ||
+    core.endsWith('-foreground') ||
+    core === 'fg' ||
+    core.startsWith('fg-')
+  );
+}
+
+/** Tailwind's default chromatic palette names — none are Urbicon UI tokens. `neutral` is ours, so it is excluded. */
+const RAW_PALETTE =
+  'slate|gray|zinc|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose';
+
+/** Colour-bearing Tailwind prefixes (longest first so `border-l` wins over `border`). */
+const COLOR_PREFIXES = [
+  'ring-offset',
+  'border-x',
+  'border-y',
+  'border-t',
+  'border-r',
+  'border-b',
+  'border-l',
+  'border-s',
+  'border-e',
+  'bg',
+  'text',
+  'border',
+  'ring',
+  'divide',
+  'outline',
+  'decoration',
+  'fill',
+  'stroke',
+  'from',
+  'via',
+  'to',
+  'accent',
+  'caret',
+  'placeholder'
+];
+
+/** Tailwind utility roots that take a scale/value — used to catch broken dynamic interpolation. */
+const DYNAMIC_UTILITY_ROOTS = [
+  'gap',
+  'gap-x',
+  'gap-y',
+  'space-x',
+  'space-y',
+  'p',
+  'px',
+  'py',
+  'pt',
+  'pb',
+  'pl',
+  'pr',
+  'm',
+  'mx',
+  'my',
+  'mt',
+  'mb',
+  'ml',
+  'mr',
+  'w',
+  'h',
+  'min-w',
+  'min-h',
+  'max-w',
+  'max-h',
+  'size',
+  'text',
+  'bg',
+  'border',
+  'rounded',
+  'grid-cols',
+  'grid-rows',
+  'col-span',
+  'row-span',
+  'top',
+  'left',
+  'right',
+  'bottom',
+  'inset',
+  'z',
+  'leading',
+  'tracking',
+  'opacity',
+  'scale',
+  'rotate',
+  'translate-x',
+  'translate-y',
+  'duration',
+  'delay'
+];
+
+function dedupeByLine(findings: Finding[]): Finding[] {
+  const seen = new Set<string>();
+  const out: Finding[] = [];
+  for (const f of findings) {
+    const key = `${f.ruleId}:${f.line}:${f.match}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(f);
+  }
+  return out;
+}
+
+const rawTailwindColor: Rule = {
+  id: 'raw-tailwind-color',
+  severity: 'error',
+  description: 'Raw Tailwind palette colour (e.g. `bg-blue-500`) instead of a semantic token.',
+  check(lines) {
+    // Trailing `(?![a-z0-9-])` (not `\b`) so an optional `/NN` opacity suffix stays in the match.
+    const re = new RegExp(
+      `\\b(?:${COLOR_PREFIXES.join('|')})-(?:${RAW_PALETTE})-(?:50|100|200|300|400|500|600|700|800|900|950)(?:\\/\\d{1,3})?(?![a-z0-9-])`,
+      'g'
+    );
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `Raw Tailwind colour \`${m[0]}\` bypasses the token system (no dark-mode adaptation, no theming).`,
+          fix: 'Use a semantic token: `bg-surface-*`, `text-text-*`, `border-border-*`, or an intent (`bg-primary`, `text-success`).',
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+const darkModeOverride: Rule = {
+  id: 'dark-mode-override',
+  severity: 'error',
+  description: 'Manual `dark:` override instead of automatic `light-dark()` semantic tokens.',
+  check(lines) {
+    // `!` covers the Tailwind important modifier (`dark:!bg-…`).
+    const re = /\bdark:[a-z[!]/g;
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message:
+            'Manual `dark:` override. Dark mode resolves automatically via `light-dark()` semantic tokens.',
+          fix: 'Remove the `dark:` variant and rely on semantic tokens (`bg-surface-elevated` etc.), which already switch.',
+          line: i + 1,
+          match: m[0].slice(0, -1)
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+const focusNotVisible: Rule = {
+  id: 'focus-not-visible',
+  severity: 'error',
+  description: 'Plain `focus:` ring instead of keyboard-only `focus-visible:`.',
+  check(lines) {
+    // `focus:` followed by a utility start, but never `focus-visible:`/`focus-within:`
+    // (those contain `focus-`, not `focus:`). Catches `group-focus:` / `peer-focus:` too.
+    const re = /\bfocus:(?=[a-z[])/g;
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const _ of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message:
+            '`focus:` shows a focus ring on mouse clicks too. Keyboard-only rings are the house style.',
+          fix: 'Use `focus-visible:` instead of `focus:`.',
+          line: i + 1,
+          match: 'focus:'
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+const hardcodedZIndex: Rule = {
+  id: 'hardcoded-z-index',
+  severity: 'error',
+  description: 'Hardcoded z-index instead of a `z-[var(--z-*)]` token.',
+  check(lines) {
+    // `z-10`, `z-50`, `z-[999]` — but not `z-[var(--z-modal)]` or `z-auto`.
+    // Trailing `(?![\w-])` (not `\b`) so the bracket form terminates correctly after `]`.
+    const re = /\bz-(?:\d{1,4}|\[\d{1,4}\])(?![\w-])/g;
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `Hardcoded z-index \`${m[0]}\` collides with the layering scale and can sit behind/above the wrong overlay.`,
+          fix: 'Use a z-index token: `z-[var(--z-modal)]`, `z-[var(--z-dropdown)]`, `z-[var(--z-tooltip)]`, …',
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+const dynamicClassInterpolation: Rule = {
+  id: 'dynamic-class-interpolation',
+  severity: 'error',
+  description:
+    'String-interpolated Tailwind class fragment (e.g. `gap-{x}`) — never compiled by Tailwind.',
+  check(lines) {
+    // A Tailwind utility root immediately glued to a `{` or `${` interpolation.
+    // Tailwind needs static class names; `gap-${x}` produces no CSS at all.
+    const re = new RegExp(`\\b(?:${DYNAMIC_UTILITY_ROOTS.join('|')})-(\\$\\{|\\{)`, 'g');
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `Interpolated class fragment \`${m[0]}…\` — Tailwind only compiles static class names, so this utility is never generated.`,
+          fix: "Switch the whole class string per state: `class={isHero ? 'gap-4' : 'gap-3'}` — keep each utility a complete literal.",
+          line: i + 1,
+          match: m[0]
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+/**
+ * Token hallucination: a colour utility whose core *looks* like an Urbicon UI
+ * semantic token (right namespace / intent prefix) but is not in the validated
+ * whitelist. Narrow by construction — only fires on our own namespaces, so it
+ * never flags `bg-transparent`, `bg-cover`, or arbitrary `bg-[#fff]`.
+ */
+const tokenHallucination: Rule = {
+  id: 'token-hallucination',
+  severity: 'warning',
+  description:
+    'Colour utility referencing a non-existent semantic token (e.g. `bg-status-danger`).',
+  check(lines) {
+    const prefixAlt = COLOR_PREFIXES.join('|');
+    // capture: prefix, then the core up to a class boundary / opacity / end
+    const re = new RegExp(`\\b(${prefixAlt})-([a-z][a-z0-9-]*)(?:\\/\\d{1,3})?\\b`, 'g');
+    const findings: Finding[] = [];
+
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        const core = m[2]!;
+        if (!looksSemantic(core)) continue;
+        if (VALID_TOKEN_CORES.has(core)) continue;
+
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `\`${m[1]}-${core}\` is not a real token — likely hallucinated.`,
+          fix: suggestForBadCore(core),
+          line: i + 1,
+          match: m[0] // full token incl. any `/NN` opacity suffix
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+/** Does this utility core sit in one of our semantic namespaces / intent families? */
+function looksSemantic(core: string): boolean {
+  // Font-size cores (`text-sm`, `text-2xl`) share the `text-` namespace but are not colour tokens.
+  if (/^text-(?:xs|sm|base|lg|\d?xl)$/.test(core)) return false;
+  if (isForeignVocab(core)) return true; // shadcn/ui vocabulary — always foreign
+  if (SEMANTIC_NAMESPACES.some((ns) => core.startsWith(ns))) return true;
+  if (core.startsWith('status-')) return true; // owned-looking, never valid → flag
+  // intent-with-suffix: `primary-muted`, `success-foo` (bare `primary` is valid and caught by the whitelist)
+  for (const intent of INTENT_PREFIXES) {
+    if (core.startsWith(`${intent}-`)) return true;
+  }
+  if (core.endsWith('-fg')) return true; // `-foreground` is already covered by isForeignVocab above
+  return false;
+}
+
+function suggestForBadCore(core: string): string {
+  // The `-foreground` family is the most common shadcn pattern — give the precise replacement first.
+  if (
+    core === 'foreground' ||
+    core.endsWith('-foreground') ||
+    core === 'fg' ||
+    core.endsWith('-fg')
+  ) {
+    return 'Use `text-on-primary` / `text-on-surface` for foreground-on-intent text, or `text-text-primary`/`-secondary` for general text.';
+  }
+  if (isForeignVocab(core)) return SHADCN_FIX;
+  for (const [bad, hint] of Object.entries(KNOWN_BAD_NAMESPACES)) {
+    if (bad.endsWith('-') ? core.startsWith(bad) : core.endsWith(bad)) return hint;
+  }
+  if (core.startsWith('surface-'))
+    return 'Valid surfaces: surface-base/quiet/subtle/elevated/overlay/hover/active/selected/inverted.';
+  if (core.startsWith('feedback-'))
+    return 'Valid feedback tokens: feedback-{info,success,warning,error}[-subtle].';
+  const intent = INTENT_NAMES.find((n) => core.startsWith(`${n}-`));
+  if (intent)
+    return `Valid \`${intent}\` variants: ${intent}, ${intent}-hover, ${intent}-active, ${intent}-subtle, ${intent}-emphasis, or a scale step ${intent}-50…${intent}-950.`;
+  return 'Check `get_css_reference()` for the exact token name.';
+}
+
+/** All deterministic rules, in report order. */
+export const RULES: Rule[] = [
+  rawTailwindColor,
+  darkModeOverride,
+  focusNotVisible,
+  hardcodedZIndex,
+  dynamicClassInterpolation,
+  tokenHallucination
+];

package/src/design-linter/tokens.test.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { VALID_TOKEN_CORES } from './tokens.js';
+
+/**
+ * Drift guard: the hardcoded {@link VALID_TOKEN_CORES} is the mcp-server's
+ * standalone copy of the design tokens. When the blocks CSS source is present
+ * (i.e. running inside the monorepo) we re-derive the token cores from it and
+ * assert the two agree exactly. Any token added to / removed from the CSS that
+ * is not mirrored here will fail this test — keeping the hallucination detector
+ * honest. The mcp-server ships without the CSS, so this can only run in-repo.
+ */
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const styleDir = resolve(__dirname, '..', '..', '..', 'blocks', 'src', 'lib', 'style');
+const foundation = resolve(styleDir, 'foundation.css');
+const semantic = resolve(styleDir, 'semantic.css');
+const cssAvailable = existsSync(foundation) && existsSync(semantic);
+
+/** Token cores that intentionally live in CSS but are NOT colour-utility cores. */
+const EXCLUDED_PREFIXES = ['shadow-']; // shadows are used via `shadow-[var(--blocks-shadow-*)]`, not `bg-shadow-*`
+
+function deriveCoresFromCss(): Set<string> {
+  const cores = new Set<string>();
+  for (const file of [foundation, semantic]) {
+    const css = readFileSync(file, 'utf-8');
+    for (const m of css.matchAll(/--color-([a-z0-9-]+)\s*:/g)) {
+      const core = m[1]!;
+      if (EXCLUDED_PREFIXES.some((p) => core.startsWith(p))) continue;
+      cores.add(core);
+    }
+  }
+  return cores;
+}
+
+describe.skipIf(!cssAvailable)('token whitelist drift guard', () => {
+  it('recognises every colour token defined in the CSS (no forgotten additions)', () => {
+    const cssCores = deriveCoresFromCss();
+    const missing = [...cssCores].filter((c) => !VALID_TOKEN_CORES.has(c)).sort();
+    expect(missing, `CSS tokens missing from VALID_TOKEN_CORES: ${missing.join(', ')}`).toEqual([]);
+  });
+
+  it('contains no phantom tokens absent from the CSS (no invented entries)', () => {
+    const cssCores = deriveCoresFromCss();
+    const phantom = [...VALID_TOKEN_CORES].filter((c) => !cssCores.has(c)).sort();
+    expect(
+      phantom,
+      `Entries in VALID_TOKEN_CORES with no matching --color-* in CSS: ${phantom.join(', ')}`
+    ).toEqual([]);
+  });
+
+  it('each EXCLUDED_PREFIX still matches a real CSS token (exclusion not stale)', () => {
+    const css = readFileSync(foundation, 'utf-8') + readFileSync(semantic, 'utf-8');
+    for (const prefix of EXCLUDED_PREFIXES) {
+      expect(
+        css,
+        `EXCLUDED_PREFIX "${prefix}" no longer matches any --color-* token — may be stale`
+      ).toMatch(new RegExp(`--color-${prefix}`));
+    }
+  });
+});
+
+describe('token whitelist shape', () => {
+  it('includes representative tokens from each family', () => {
+    for (const core of [
+      'surface-base',
+      'text-primary',
+      'border-subtle',
+      'primary',
+      'primary-500',
+      'feedback-success-subtle',
+      'interactive-hover',
+      'chart-1'
+    ]) {
+      expect(VALID_TOKEN_CORES.has(core), core).toBe(true);
+    }
+  });
+});

package/src/design-linter/tokens.ts

@@ -0,0 +1,203 @@
+/**
+ * The authoritative set of Urbicon UI semantic design tokens, expressed as the
+ * "core" of a Tailwind colour utility (the part after `bg-`/`text-`/`border-`/…).
+ *
+ * SOURCE OF TRUTH: `packages/blocks/src/lib/style/{foundation,semantic}.css`
+ * (the `--color-*` custom properties). This list is hand-maintained but guarded
+ * against drift by `tokens.test.ts`, which re-derives the set from the CSS when
+ * run inside the monorepo and fails on any mismatch. The mcp-server ships
+ * standalone (no access to the blocks source at runtime), so the data must live
+ * here, not be read from disk.
+ *
+ * Why a whitelist: token hallucination is the single biggest weakness of
+ * design-quality guidance — the model invents plausible names like
+ * `bg-status-danger` or `text-success-fg`
+ * that do not exist. A deterministic whitelist turns that from a guess into a
+ * fact: a utility whose core looks semantic but is absent here is flagged.
+ */
+
+/** Surface background tokens → `bg-surface-*`. */
+const SURFACE_CORES = [
+  'surface-base',
+  'surface-quiet',
+  'surface-subtle',
+  'surface-elevated',
+  'surface-overlay',
+  'surface-interactive',
+  'surface-hover',
+  'surface-active',
+  'surface-disabled',
+  'surface-selected',
+  'surface-inverted'
+] as const;
+
+/** Text colour tokens → `text-text-*` (the `text-` namespace, used after a colour prefix). */
+const TEXT_CORES = [
+  'text-primary',
+  'text-secondary',
+  'text-tertiary',
+  'text-quaternary',
+  'text-disabled',
+  'text-inverted',
+  'text-on-primary',
+  'text-on-dark',
+  'text-on-surface'
+] as const;
+
+/** Border colour tokens → `border-border-*`. */
+const BORDER_CORES = [
+  'border-subtle',
+  'border-default',
+  'border-emphasis',
+  'border-strong',
+  'border-hairline'
+] as const;
+
+/** Intent palettes. Each has a bare token plus the four interaction variants. */
+const INTENT_NAMES = [
+  'primary',
+  'secondary',
+  'success',
+  'warning',
+  'danger',
+  'info',
+  'neutral'
+] as const;
+
+const INTENT_VARIANTS = ['hover', 'active', 'subtle', 'emphasis'] as const;
+
+/** Numbered foundation steps present on every intent scale. */
+const SCALE_STEPS = [
+  '50',
+  '100',
+  '200',
+  '300',
+  '400',
+  '500',
+  '600',
+  '700',
+  '800',
+  '900',
+  '950'
+] as const;
+
+/**
+ * `neutral` carries an extended ramp beyond the standard scale (finer steps for
+ * the surface ladder). Omitting these would make the hallucination rule flag a
+ * real token like `bg-neutral-650` — the drift guard in tokens.test.ts caught
+ * exactly that.
+ */
+const NEUTRAL_EXTRA_STEPS = ['0', '25', '650', '750', '850'] as const;
+
+/** Warm-neutral foundation scale (used by the Organic/Warm paradigm). Scale-only — no semantic variants. */
+const WARM_NEUTRAL_STEPS = SCALE_STEPS;
+
+/** Feedback tokens for status messaging → `bg-feedback-*` / `text-feedback-*`. */
+const FEEDBACK_CORES = [
+  'feedback-info',
+  'feedback-info-subtle',
+  'feedback-success',
+  'feedback-success-subtle',
+  'feedback-warning',
+  'feedback-warning-subtle',
+  'feedback-error',
+  'feedback-error-subtle'
+] as const;
+
+/** Interactive overlay tokens. */
+const INTERACTIVE_CORES = [
+  'interactive-hover',
+  'interactive-active',
+  'interactive-focus',
+  'interactive-disabled'
+] as const;
+
+/** Chart series tokens → `text-chart-1` … `text-chart-6`. */
+const CHART_CORES = ['chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5', 'chart-6'] as const;
+
+function buildIntentCores(): string[] {
+  const cores: string[] = [];
+  for (const intent of INTENT_NAMES) {
+    cores.push(intent); // bare, e.g. `bg-primary`
+    for (const variant of INTENT_VARIANTS) cores.push(`${intent}-${variant}`); // `bg-primary-subtle`
+    for (const step of SCALE_STEPS) cores.push(`${intent}-${step}`); // `bg-primary-500`
+  }
+  return cores;
+}
+
+/**
+ * Every valid semantic colour-utility core, as a Set for O(1) membership checks.
+ * `surface-base`, `text-primary`, `primary`, `primary-500`, `feedback-success`, …
+ */
+export const VALID_TOKEN_CORES: ReadonlySet<string> = new Set([
+  ...SURFACE_CORES,
+  ...TEXT_CORES,
+  ...BORDER_CORES,
+  ...buildIntentCores(),
+  ...NEUTRAL_EXTRA_STEPS.map((s) => `neutral-${s}`),
+  ...WARM_NEUTRAL_STEPS.map((s) => `warm-neutral-${s}`),
+  ...FEEDBACK_CORES,
+  ...INTERACTIVE_CORES,
+  ...CHART_CORES
+]);
+
+/**
+ * Namespaces that mark a utility core as "intended to be semantic". A core that
+ * starts with one of these but is NOT in {@link VALID_TOKEN_CORES} is a
+ * hallucinated token. Kept deliberately narrow so we never flag genuine Tailwind
+ * utilities (`bg-transparent`, `bg-cover`, arbitrary `bg-[#fff]`).
+ */
+export const SEMANTIC_NAMESPACES = [
+  'surface-',
+  'text-',
+  'border-',
+  'feedback-',
+  'interactive-',
+  'chart-'
+] as const;
+
+/** Intent prefixes (`primary-…`, `success-…`) that mark a core as semantic-intent. */
+export const INTENT_PREFIXES: readonly string[] = INTENT_NAMES;
+
+/**
+ * The shadcn/ui (and Radix) token vocabulary. This is the single most common
+ * hallucination source: with no explicit whitelist, models default to the
+ * dominant design-system convention in their training data — `text-foreground`,
+ * `bg-accent`, `text-muted-foreground`, `bg-card`, … — none of which exist in
+ * Urbicon UI. Discovered empirically during design-quality evaluation.
+ * These bare cores slip past the namespace/intent heuristics, so they are
+ * matched explicitly. (Suffix `-foreground` and the `fg`/`fg-` family are caught
+ * by rule in rules.ts.)
+ */
+export const KNOWN_FOREIGN_CORES: ReadonlySet<string> = new Set([
+  'foreground',
+  'background',
+  'muted',
+  'accent',
+  'card',
+  'popover',
+  'input',
+  'destructive',
+  'surface', // bare — the real page surface is `surface-base`
+  'muted-foreground',
+  'accent-foreground',
+  'card-foreground',
+  'popover-foreground',
+  'primary-foreground',
+  'secondary-foreground',
+  'destructive-foreground'
+]);
+
+/**
+ * Cores that are commonly hallucinated and have a known correct replacement.
+ * Drives a precise fix hint instead of a generic "unknown token".
+ */
+export const KNOWN_BAD_NAMESPACES: Record<string, string> = {
+  // `status-*` is the most frequent invention observed. Map to feedback/intents.
+  'status-':
+    'Use a `feedback-*` token (feedback-success, feedback-error, …) or a bare intent (`success`, `danger`).',
+  // `-fg` / `-foreground` suffixes are invented; the system uses `text-on-primary` etc.
+  '-fg': 'Use `text-on-primary` / `text-on-surface` for foreground-on-intent text.'
+};
+
+export { INTENT_NAMES, INTENT_VARIANTS, SCALE_STEPS };

package/src/design-linter/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Types for the Urbicon UI design linter.
+ *
+ * The linter turns the prose Anti-Patterns and Design-Quality guidance (served
+ * today by `get_design_principles`, `suggest_implementation`,
+ * `get_implementation_checklist`) into executable checks. Deterministic rules
+ * produce `error`/`warning` findings; distribution heuristics produce `info`
+ * findings. See design-linter/README context in docs/DESIGN-MCP.md.
+ */
+
+/** How serious a finding is. Drives the score deduction and the report grouping. */
+export type Severity = 'error' | 'warning' | 'info';
+
+/**
+ * Whether a finding comes from a deterministic rule (regex/string match — a fact
+ * about the code) or a statistical heuristic (a distribution judgement that can
+ * have false positives). Surfaced in the report so consumers can weight them.
+ */
+export type FindingKind = 'deterministic' | 'heuristic';
+
+/** A single linter finding, anchored to a location when one exists. */
+export interface Finding {
+  /** Stable rule identifier, e.g. `raw-tailwind-color`. Used for tests and suppression. */
+  ruleId: string;
+  severity: Severity;
+  kind: FindingKind;
+  /** Human-readable description of what is wrong. */
+  message: string;
+  /** Concrete fix hint — what to do instead. */
+  fix: string;
+  /** 1-based line number, when the finding is anchored to one. */
+  line?: number;
+  /** The offending snippet (e.g. the class token), when applicable. */
+  match?: string;
+}
+
+/** A deterministic rule: scans the source and emits findings. */
+export interface Rule {
+  id: string;
+  severity: Severity;
+  /** One-line description of what the rule enforces, shown in `validate_design` rule listings. */
+  description: string;
+  /**
+   * Run the rule over the already-prepared source lines.
+   * @param lines source split by `\n`, with comments masked (see linter.ts)
+   * @param raw the original source (for rules that need cross-line context)
+   */
+  check(lines: string[], raw: string): Finding[];
+}
+
+/** Aggregate result of linting one code unit. */
+export interface LintReport {
+  findings: Finding[];
+  /** Deterministic 0–100 design-quality score. 100 = no findings. */
+  score: number;
+  counts: { error: number; warning: number; info: number };
+  /** Optional label (e.g. filename) echoed back in the report. */
+  filename?: string;
+}
+
+/** Options for a lint run. */
+export interface LintOptions {
+  filename?: string;
+  /** Skip the distribution heuristics (the `info`-level checks). Default: false. */
+  skipHeuristics?: boolean;
+}