@urbicon-ui/mcp-server 6.1.4

package/src/design-linter/heuristics.ts

@@ -0,0 +1,162 @@
+/**
+ * Distribution heuristics — stage 2 of the validator. These are *judgements*
+ * about how design properties are spread across a page, not facts, so they emit
+ * `info`/`heuristic` findings with a light score impact. They operationalise the
+ * Design-Quality guidance ("Color = meaning", "Spacing = hierarchy", "Vary
+ * visual weight", "Commit to a radius") and target the exact monotony that
+ * scored lowest in design-quality evaluation (uniform spacing, rainbow
+ * intents, identical Cards, zero radius strategy).
+ *
+ * Thresholds are named constants so the eval-suite (WP5) can tune them with data
+ * instead of guesswork.
+ */
+
+import type { Finding } from './types.js';
+
+/**
+ * Chromatic intents only — `neutral` is structural greyscale, so neutral
+ * backgrounds (common and legitimate) must not count toward a decorative
+ * "rainbow". `info` is a distinct blue hue and does count.
+ */
+const CHROMATIC_INTENTS = ['primary', 'secondary', 'success', 'warning', 'danger', 'info'] as const;
+
+/** Tunable thresholds. Kept together so evaluation can adjust them in one place. */
+export const HEURISTIC_THRESHOLDS = {
+  /** Distinct intent hues used as backgrounds before it reads as a decorative "rainbow". */
+  rainbowIntentFamilies: 4,
+  /** Minimum spacing utilities before uniformity is judged (avoids nagging tiny snippets). */
+  minSpacingUtilities: 6,
+  /** Minimum Card instances before monotony is judged. */
+  minCards: 4,
+  /** Minimum structural surfaces before a missing radius strategy is worth a nudge. */
+  minSurfacesForRadius: 3
+} as const;
+
+/** All atoms inside class strings, lower-cased, comments already masked upstream. */
+function collectAtoms(code: string): string[] {
+  const atoms: string[] = [];
+  // class="...", class={...}, slotClasses={{ base: '...' }} — grab quoted runs of utility-ish text.
+  const stringRe = /["'`]([^"'`]*?)["'`]/g;
+  for (const m of code.matchAll(stringRe)) {
+    const body = m[1]!;
+    if (!/[a-z]-/.test(body) && !/\b(flex|grid|block|hidden|relative|absolute)\b/.test(body))
+      continue;
+    for (const atom of body.split(/\s+/)) {
+      if (atom) atoms.push(atom);
+    }
+  }
+  return atoms;
+}
+
+/** "Color = meaning": flag a decorative rainbow of intent backgrounds. */
+function checkIntentRainbow(atoms: string[]): Finding[] {
+  const families = new Set<string>();
+  const bgIntent = new RegExp(
+    `^bg-(${CHROMATIC_INTENTS.join('|')})(?:-(?:hover|active|subtle|emphasis|\\d{2,3}))?(?:\\/\\d{1,3})?$`
+  );
+  for (const atom of atoms) {
+    const m = atom.match(bgIntent);
+    if (m) families.add(m[1]!);
+  }
+  if (families.size >= HEURISTIC_THRESHOLDS.rainbowIntentFamilies) {
+    return [
+      {
+        ruleId: 'intent-rainbow',
+        severity: 'info',
+        kind: 'heuristic',
+        message: `${families.size} different intent hues used as backgrounds (${[...families].join(', ')}). Reads as decoration, not meaning.`,
+        fix: 'Let neutral surfaces dominate (80–90%). Reserve intent colour for genuine status/severity/action signals.'
+      }
+    ];
+  }
+  return [];
+}
+
+/** "Spacing = hierarchy": flag a single uniform rhythm tier. */
+function checkSpacingUniformity(atoms: string[]): Finding[] {
+  const values = new Set<string>();
+  let total = 0;
+  const spacingRe = /^(?:gap|gap-x|gap-y|space-x|space-y)-(\d+(?:\.\d+)?|px)$/;
+  for (const atom of atoms) {
+    const m = atom.match(spacingRe);
+    if (m) {
+      values.add(m[1]!);
+      total++;
+    }
+  }
+  if (total >= HEURISTIC_THRESHOLDS.minSpacingUtilities && values.size <= 1) {
+    return [
+      {
+        ruleId: 'spacing-uniform',
+        severity: 'info',
+        kind: 'heuristic',
+        message: `All ${total} spacing utilities use one value (\`${[...values][0] ?? '?'}\`). No tight-within vs generous-between rhythm.`,
+        fix: 'Use two tiers: tight (`gap-2`/`gap-3`) within related items, generous (`gap-8`/`gap-10`) between sections.'
+      }
+    ];
+  }
+  return [];
+}
+
+/** "Vary visual weight": flag many identical Cards (same variant + padding). */
+function checkCardMonotony(code: string): Finding[] {
+  const cardRe = /<Card\b([^>]*)>/g;
+  const signatures: string[] = [];
+  for (const m of code.matchAll(cardRe)) {
+    const attrs = m[1]!;
+    const variant = attrs.match(/\bvariant=(?:"([^"]*)"|'([^']*)'|\{['"]([^'"]*)['"]\})/);
+    const padding = attrs.match(/\bpadding=(?:"([^"]*)"|'([^']*)'|\{['"]([^'"]*)['"]\})/);
+    const v = variant ? (variant[1] ?? variant[2] ?? variant[3]) : 'default';
+    const p = padding ? (padding[1] ?? padding[2] ?? padding[3]) : 'default';
+    signatures.push(`${v}/${p}`);
+  }
+  if (signatures.length >= HEURISTIC_THRESHOLDS.minCards) {
+    const distinct = new Set(signatures);
+    if (distinct.size === 1) {
+      return [
+        {
+          ruleId: 'card-monotony',
+          severity: 'info',
+          kind: 'heuristic',
+          message: `All ${signatures.length} Cards share one look (\`${[...distinct][0]}\`). Visual weight does not vary.`,
+          fix: 'Differentiate: prominent content `variant="elevated"`/`padding="lg"`, secondary `variant="outlined"`/`padding="md"`.'
+        }
+      ];
+    }
+  }
+  return [];
+}
+
+/** "Commit to a radius": nudge when structural surfaces exist but no radius override does. */
+function checkRadiusStrategy(code: string, atoms: string[]): Finding[] {
+  // Only count genuine container surfaces. A bare `border`/`border-b` atom is far
+  // more often a table row, list divider, or input frame than a Card-like surface,
+  // so including it inflated the count into false positives (review finding #1).
+  const surfaceCount =
+    (code.match(/<Card\b/g)?.length ?? 0) +
+    (code.match(/<(?:Dialog|Drawer|Popover)\b/g)?.length ?? 0);
+  const hasRadiusOverride = atoms.some((a) => /^rounded(?:-|$)/.test(a));
+  if (surfaceCount >= HEURISTIC_THRESHOLDS.minSurfacesForRadius && !hasRadiusOverride) {
+    return [
+      {
+        ruleId: 'no-radius-strategy',
+        severity: 'info',
+        kind: 'heuristic',
+        message: 'Multiple surfaces but no explicit radius — relying solely on component defaults.',
+        fix: 'If the default tier radii do not match your design identity, commit to one philosophy (`rounded-lg`/`rounded-xl`/`rounded-2xl`) applied consistently via `class`/`slotClasses`.'
+      }
+    ];
+  }
+  return [];
+}
+
+/** Run all heuristics over the (comment-masked) code. */
+export function runHeuristics(code: string): Finding[] {
+  const atoms = collectAtoms(code);
+  return [
+    ...checkIntentRainbow(atoms),
+    ...checkSpacingUniformity(atoms),
+    ...checkCardMonotony(code),
+    ...checkRadiusStrategy(code, atoms)
+  ];
+}

package/src/design-linter/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Public API of the Urbicon UI design linter.
+ *
+ * The linter is the deterministic half of the "generate → validate → fix" loop
+ * (docs/DESIGN-MCP.md, Option B). It is consumed by the `validate_design` MCP
+ * tool and, programmatically, by the eval-suite (WP5) which scores generated
+ * pages without an LLM in the loop.
+ */
+
+export { HEURISTIC_THRESHOLDS } from './heuristics.js';
+export { lintDesign, maskComments, SCORE_WEIGHTS } from './linter.js';
+export { RULES } from './rules.js';
+export { VALID_TOKEN_CORES } from './tokens.js';
+export type { Finding, FindingKind, LintOptions, LintReport, Rule, Severity } from './types.js';

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

@@ -0,0 +1,257 @@
+import { describe, expect, it } from 'vitest';
+import { lintDesign, maskComments } from './linter.js';
+import type { Finding } from './types.js';
+
+function ids(findings: Finding[]): string[] {
+  return findings.map((f) => f.ruleId);
+}
+function has(findings: Finding[], ruleId: string): boolean {
+  return findings.some((f) => f.ruleId === ruleId);
+}
+
+describe('raw-tailwind-color', () => {
+  it('flags numbered chromatic palette utilities', () => {
+    const { findings } = lintDesign(
+      '<div class="bg-blue-500 text-red-600 border-l-amber-400">x</div>'
+    );
+    expect(findings.filter((f) => f.ruleId === 'raw-tailwind-color')).toHaveLength(3);
+  });
+  it('flags opacity-suffixed raw colours', () => {
+    expect(has(lintDesign('<div class="bg-green-500/40">').findings, 'raw-tailwind-color')).toBe(
+      true
+    );
+  });
+  it('does NOT flag library tokens (intents, neutral, surfaces)', () => {
+    const { findings } = lintDesign(
+      '<div class="bg-primary-500 bg-neutral-100 bg-surface-base text-success border-border-subtle">'
+    );
+    expect(has(findings, 'raw-tailwind-color')).toBe(false);
+  });
+});
+
+describe('dark-mode-override', () => {
+  it('flags dark: variants', () => {
+    expect(
+      has(
+        lintDesign('<div class="bg-white dark:bg-surface-elevated">').findings,
+        'dark-mode-override'
+      )
+    ).toBe(true);
+  });
+  it('flags the important-modifier form dark:!', () => {
+    expect(
+      has(lintDesign('<div class="dark:!bg-surface-elevated">').findings, 'dark-mode-override')
+    ).toBe(true);
+  });
+  it('does NOT flag plain semantic tokens', () => {
+    expect(
+      has(lintDesign('<div class="bg-surface-elevated">').findings, 'dark-mode-override')
+    ).toBe(false);
+  });
+});
+
+describe('focus-not-visible', () => {
+  it('flags focus: and group-focus:', () => {
+    expect(has(lintDesign('<button class="focus:ring-2">').findings, 'focus-not-visible')).toBe(
+      true
+    );
+    expect(
+      has(lintDesign('<div class="group-focus:opacity-100">').findings, 'focus-not-visible')
+    ).toBe(true);
+  });
+  it('does NOT flag focus-visible: or focus-within:', () => {
+    const { findings } = lintDesign(
+      '<button class="focus-visible:ring-2 focus-within:bg-surface-hover">'
+    );
+    expect(has(findings, 'focus-not-visible')).toBe(false);
+  });
+});
+
+describe('hardcoded-z-index', () => {
+  it('flags numeric and bracketed z-index', () => {
+    expect(has(lintDesign('<div class="z-10">').findings, 'hardcoded-z-index')).toBe(true);
+    expect(has(lintDesign('<div class="z-[999]">').findings, 'hardcoded-z-index')).toBe(true);
+  });
+  it('does NOT flag the z-index token form or z-auto', () => {
+    const { findings } = lintDesign('<div class="z-[var(--z-modal)] z-auto">');
+    expect(has(findings, 'hardcoded-z-index')).toBe(false);
+  });
+});
+
+describe('dynamic-class-interpolation', () => {
+  it('flags interpolated Tailwind utility fragments', () => {
+    expect(
+      has(
+        lintDesign("<div class=\"gap-{isHero ? '4' : '3'}\">").findings,
+        'dynamic-class-interpolation'
+      )
+    ).toBe(true);
+    expect(
+      has(lintDesign('<div class={`py-${pad}`}>').findings, 'dynamic-class-interpolation')
+    ).toBe(true);
+  });
+  it('does NOT flag interpolation that is not a Tailwind root (ids, data keys)', () => {
+    const { findings } = lintDesign('<label for={`field-${id}`}>');
+    expect(has(findings, 'dynamic-class-interpolation')).toBe(false);
+  });
+});
+
+describe('token-hallucination', () => {
+  it('flags invented status-* and -fg tokens', () => {
+    expect(has(lintDesign('<div class="bg-status-danger">').findings, 'token-hallucination')).toBe(
+      true
+    );
+    expect(has(lintDesign('<div class="text-success-fg">').findings, 'token-hallucination')).toBe(
+      true
+    );
+  });
+  it('flags intent-with-bad-suffix and namespace typos', () => {
+    expect(has(lintDesign('<div class="bg-primary-muted">').findings, 'token-hallucination')).toBe(
+      true
+    );
+    expect(has(lintDesign('<div class="bg-surface-raised">').findings, 'token-hallucination')).toBe(
+      true
+    );
+  });
+  it('does NOT flag valid tokens', () => {
+    const valid =
+      '<div class="bg-surface-subtle text-text-primary bg-primary bg-primary-500 text-success bg-feedback-success-subtle border-border-strong">';
+    expect(has(lintDesign(valid).findings, 'token-hallucination')).toBe(false);
+  });
+  it('does NOT flag genuine Tailwind utilities or arbitrary values', () => {
+    const { findings } = lintDesign(
+      '<div class="bg-transparent bg-[#fff] text-sm bg-cover from-transparent">'
+    );
+    expect(has(findings, 'token-hallucination')).toBe(false);
+  });
+  it('does NOT flag font-size cores sharing the text- namespace', () => {
+    const { findings } = lintDesign('<div class="bg-text-sm text-text-2xl border-text-base">');
+    expect(has(findings, 'token-hallucination')).toBe(false);
+  });
+  it('keeps the opacity suffix in the reported match', () => {
+    const f = lintDesign('<div class="bg-surface-raised/50">').findings.find(
+      (x) => x.ruleId === 'token-hallucination'
+    );
+    expect(f?.match).toBe('bg-surface-raised/50');
+  });
+  it('flags shadcn/ui vocabulary — the top hallucination source (round-3 finding)', () => {
+    const code =
+      '<div class="text-foreground bg-accent text-muted-foreground bg-card bg-surface text-fg text-fg-muted border-card-foreground bg-destructive">x</div>';
+    const matches = lintDesign(code)
+      .findings.filter((f) => f.ruleId === 'token-hallucination')
+      .map((f) => f.match);
+    for (const t of [
+      'text-foreground',
+      'bg-accent',
+      'text-muted-foreground',
+      'bg-card',
+      'bg-surface',
+      'text-fg',
+      'text-fg-muted',
+      'border-card-foreground',
+      'bg-destructive'
+    ]) {
+      expect(matches, t).toContain(t);
+    }
+  });
+});
+
+describe('heuristics', () => {
+  it('flags an intent rainbow of ≥4 chromatic background hues', () => {
+    const code =
+      '<div class="bg-primary"></div><div class="bg-success"></div><div class="bg-warning"></div><div class="bg-danger"></div>';
+    expect(has(lintDesign(code).findings, 'intent-rainbow')).toBe(true);
+  });
+  it('does NOT count neutral backgrounds toward the rainbow', () => {
+    const code =
+      '<div class="bg-neutral-100"></div><div class="bg-neutral-200"></div><div class="bg-surface-base"></div><div class="bg-surface-elevated"></div>';
+    expect(has(lintDesign(code).findings, 'intent-rainbow')).toBe(false);
+  });
+  it('flags uniform spacing (one rhythm tier)', () => {
+    const code =
+      '<div class="gap-4"><div class="gap-4"></div><div class="gap-4"></div><div class="gap-4"></div><div class="gap-4"></div><div class="gap-4"></div></div>';
+    expect(has(lintDesign(code).findings, 'spacing-uniform')).toBe(true);
+  });
+  it('does NOT flag two-tier spacing', () => {
+    const code =
+      '<div class="gap-10"><div class="gap-3"></div><div class="gap-3"></div><div class="gap-10"></div><div class="gap-3"></div><div class="gap-10"></div></div>';
+    expect(has(lintDesign(code).findings, 'spacing-uniform')).toBe(false);
+  });
+  it('flags identical Cards (no visual-weight variation)', () => {
+    const card = '<Card variant="elevated" padding="md">x</Card>';
+    expect(has(lintDesign(card.repeat(4)).findings, 'card-monotony')).toBe(true);
+  });
+  it('does NOT flag differentiated Cards', () => {
+    const code =
+      '<Card variant="elevated" padding="lg">x</Card><Card variant="outlined" padding="md">x</Card><Card variant="outlined" padding="md">x</Card><Card variant="quiet" padding="sm">x</Card>';
+    expect(has(lintDesign(code).findings, 'card-monotony')).toBe(false);
+  });
+  it('nudges when surfaces exist but no radius strategy does', () => {
+    const code = '<Card>a</Card><Card>b</Card><Card>c</Card>';
+    expect(has(lintDesign(code).findings, 'no-radius-strategy')).toBe(true);
+  });
+  it('does NOT nudge once a radius override is present', () => {
+    const code =
+      '<Card class="rounded-xl">a</Card><Card class="rounded-xl">b</Card><Card class="rounded-xl">c</Card>';
+    expect(has(lintDesign(code).findings, 'no-radius-strategy')).toBe(false);
+  });
+  it('does NOT treat bordered table rows / dividers as surfaces (no false radius nudge)', () => {
+    const code =
+      '<table><tr class="border-b"><td>a</td></tr><tr class="border-b"><td>b</td></tr><tr class="border-b"><td>c</td></tr></table>';
+    expect(has(lintDesign(code).findings, 'no-radius-strategy')).toBe(false);
+  });
+  it('can be skipped via skipHeuristics', () => {
+    const code = '<Card variant="elevated" padding="md">x</Card>'.repeat(4);
+    const { findings } = lintDesign(code, { skipHeuristics: true });
+    expect(findings.every((f) => f.kind === 'deterministic')).toBe(true);
+  });
+});
+
+describe('comment masking', () => {
+  it('ignores violations inside HTML and block comments', () => {
+    const code =
+      '<!-- class="focus:ring-2 bg-blue-500" --><div class="bg-surface-base">/* z-50 */</div>';
+    const { findings } = lintDesign(code);
+    expect(findings).toHaveLength(0);
+  });
+  it('keeps line numbers correct after masking', () => {
+    const masked = maskComments('a\n<!--\nx\n-->\nfocus:ring');
+    expect(masked.split('\n')).toHaveLength(5);
+  });
+});
+
+describe('scoring', () => {
+  it('scores clean code 100', () => {
+    const { score } = lintDesign('<div class="bg-surface-base text-text-primary">clean</div>');
+    expect(score).toBe(100);
+  });
+  it('deducts per finding and floors at 0', () => {
+    const oneError = lintDesign('<div class="bg-blue-500">');
+    expect(oneError.score).toBe(90);
+    // Per-line dedupe collapses identical hits on one line, so spread distinct hits across lines.
+    const many = lintDesign(
+      Array.from({ length: 12 }, () => '<div class="bg-blue-500">').join('\n')
+    );
+    expect(many.score).toBe(0);
+  });
+  it('reports severity counts', () => {
+    const { counts } = lintDesign('<div class="bg-blue-500 bg-status-x">');
+    expect(counts.error).toBeGreaterThanOrEqual(1);
+    expect(counts.warning).toBeGreaterThanOrEqual(1);
+  });
+});
+
+describe('rule metadata', () => {
+  it('every finding carries a fix hint', () => {
+    const code =
+      '<button class="bg-blue-500 dark:bg-red-500 focus:ring z-50 gap-{x} bg-status-bad">';
+    for (const f of lintDesign(code).findings) {
+      expect(f.fix.length).toBeGreaterThan(0);
+      expect(f.ruleId.length).toBeGreaterThan(0);
+    }
+  });
+  it('produces a stable id ordering for the same input', () => {
+    const code = '<div class="z-50 bg-blue-500">';
+    expect(ids(lintDesign(code).findings)).toEqual(ids(lintDesign(code).findings));
+  });
+});

package/src/design-linter/linter.ts

@@ -0,0 +1,62 @@
+/**
+ * The design linter engine: masks comments, runs the deterministic rules and the
+ * distribution heuristics, and reduces the findings to a 0–100 score. Pure and
+ * dependency-free so it is trivially unit-testable (one of the explicit wins of
+ * a linter over prose guidance — see docs/DESIGN-MCP.md, Option B).
+ */
+
+import { runHeuristics } from './heuristics.js';
+import { RULES } from './rules.js';
+import type { Finding, LintOptions, LintReport, Severity } from './types.js';
+
+/** Per-severity score deduction. Errors dominate (they are real defects). Centralised for tuning. */
+export const SCORE_WEIGHTS: Record<Severity, number> = {
+  error: 10,
+  warning: 5,
+  info: 2
+};
+
+/**
+ * Blank out comment bodies while preserving newlines (so line numbers stay
+ * correct) — keeps the rules from firing on `focus:` in a `<!-- … -->` note or a
+ * `/* … *\/` block. Line comments are intentionally left alone: masking `//`
+ * safely (without eating `https://`) is not worth the complexity for v1.
+ */
+export function maskComments(code: string): string {
+  const blankKeepNewlines = (s: string) => s.replace(/[^\n]/g, ' ');
+  return code
+    .replace(/<!--[\s\S]*?-->/g, blankKeepNewlines)
+    .replace(/\/\*[\s\S]*?\*\//g, blankKeepNewlines);
+}
+
+const SEVERITY_ORDER: Record<Severity, number> = { error: 0, warning: 1, info: 2 };
+
+/** Lint one code unit. Returns findings, a score, and severity counts. */
+export function lintDesign(code: string, opts: LintOptions = {}): LintReport {
+  const masked = maskComments(code);
+  const lines = masked.split('\n');
+
+  const findings: Finding[] = [];
+  for (const rule of RULES) {
+    findings.push(...rule.check(lines, masked));
+  }
+  if (!opts.skipHeuristics) {
+    findings.push(...runHeuristics(masked));
+  }
+
+  findings.sort((a, b) => {
+    const lineDiff = (a.line ?? Infinity) - (b.line ?? Infinity);
+    if (lineDiff !== 0) return lineDiff;
+    return SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+  });
+
+  const counts = { error: 0, warning: 0, info: 0 };
+  let deduction = 0;
+  for (const f of findings) {
+    counts[f.severity]++;
+    deduction += SCORE_WEIGHTS[f.severity];
+  }
+  const score = Math.max(0, 100 - deduction);
+
+  return { findings, score, counts, filename: opts.filename };
+}