@urbicon-ui/mcp-server 6.1.5 → 6.1.6

package/src/tools/validate-design.ts

@@ -1,12 +1,12 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Finding, LintReport, Severity } from '@urbicon-ui/design-engine/linter';
+import { lintDesign } from '@urbicon-ui/design-engine/linter';
 import { z } from 'zod';
-import type { Finding, LintReport, Severity } from '../design-linter/index.js';
-import { lintDesign } from '../design-linter/index.js';
 
 const SEVERITY_LABEL: Record<Severity, string> = {
   error: '🔴 Errors',
   warning: '🟠 Warnings',
-  info: '🔵 Heuristics'
+  info: '🔵 Slop-floor'
 };
 
 function renderFindings(findings: Finding[], severity: Severity): string {
@@ -24,17 +24,19 @@ function renderFindings(findings: Finding[], severity: Severity): string {
 }
 
 function renderReport(report: LintReport): string {
-  const { score, counts, findings, filename } = report;
+  const { scores, counts, findings, filename } = report;
   const hardFails = counts.error + counts.warning;
   const verdict = hardFails === 0 ? '✅ PASS' : '❌ NEEDS FIXES';
 
   let md = `# Design Validation — ${verdict}\n\n`;
   if (filename) md += `> \`${filename}\`\n\n`;
-  md += `**Score: ${score}/100** · ${counts.error} error(s), ${counts.warning} warning(s), ${counts.info} heuristic note(s)\n\n`;
+  md += `**Correctness ${scores.correctness}/100 · Slop-floor ${scores.slop}/100** · ${counts.error} error(s), ${counts.warning} warning(s), ${counts.info} slop note(s)\n\n`;
+  md +=
+    'Two axes, never mixed: **correctness** is the blocking gate (fix every error/warning to pass); **slop-floor** is advisory — system-agnostic "looks generic" signals to raise distinctiveness.\n\n';
 
   if (findings.length === 0) {
     md +=
-      'No issues found. Tokens are valid, no `dark:`/`focus:`/hardcoded z-index, and the distribution heuristics are satisfied.\n';
+      'No issues found. Tokens are valid, no `dark:`/`focus:`/hardcoded z-index, and the slop-floor heuristics are satisfied.\n';
     return md;
   }
 
@@ -57,7 +59,7 @@ function renderReport(report: LintReport): string {
 export function registerValidateDesignTool(server: McpServer): void {
   server.tool(
     'validate_design',
-    'Lint generated Svelte/HTML markup against the Urbicon UI design rules. Deterministic checks (raw Tailwind colours, `dark:`/`focus:` misuse, hardcoded z-index, broken dynamic classes, hallucinated tokens) plus distribution heuristics (intent-colour rainbow, uniform spacing, identical Cards, missing radius strategy). Returns a 0–100 score (each error −10, warning −5, heuristic −2, floored at 0) and per-finding fixes. Run this in a generate → validate → fix loop after producing UI code.',
+    'Lint generated Svelte/HTML markup against the Urbicon UI design rules. Two axes, never mixed: (1) **correctness** — deterministic defects (raw Tailwind colours, `dark:`/`focus:` misuse, hardcoded z-index, broken dynamic classes, hallucinated tokens, foreign-library component APIs like `tone=`/`variant="outline"`, icon-only buttons with no accessible name), the blocking gate; (2) **slop-floor** — system-agnostic "looks generic" heuristics (generic fonts, animated width/height, magic-number sizes, low-contrast text on colour, inline styles, `!important`, placeholder copy, emoji-as-icon, heading-level skips, small touch targets, intent-colour rainbow, uniform spacing/weights, identical Cards), advisory. Returns a correctness score and a slop-floor score (both 0–100; correctness −10/error, −5/warning; slop −10 per signal; floored) plus per-finding fixes. Run in a generate → validate → fix loop after producing UI code. Pass `extraTokens` to whitelist semantic tokens your project defines on top of Urbicon’s so they are not flagged as hallucinated.',
     {
       code: z
         .string()
@@ -73,11 +75,17 @@ export function registerValidateDesignTool(server: McpServer): void {
         .optional()
         .describe(
           'Skip the advisory distribution heuristics; report only deterministic violations. Default: false.'
+        ),
+      extraTokens: z
+        .array(z.string())
+        .optional()
+        .describe(
+          'Project-specific semantic token cores to treat as valid for this call, merged into the built-in whitelist so they are not flagged as hallucinated. A "core" is the part after the utility prefix: pass "surface-brand" (for `bg-surface-brand`), not "bg-surface-brand" and not the "--color-surface-brand" CSS variable. Use when your project extends the Urbicon token set or runs a newer library version than this server. This server is stateless and cannot read your CSS, so supply the cores explicitly.'
         )
     },
     { readOnlyHint: true },
-    async ({ code, filename, skipHeuristics }) => {
-      const report = lintDesign(code, { filename, skipHeuristics });
+    async ({ code, filename, skipHeuristics, extraTokens }) => {
+      const report = lintDesign(code, { filename, skipHeuristics, extraTokens });
       return { content: [{ type: 'text' as const, text: renderReport(report) }] };
     }
   );

package/src/data/recipe-loader.test.ts

@@ -1,49 +0,0 @@
-import { existsSync } from 'node:fs';
-import { describe, expect, it } from 'vitest';
-import { getRecipeDir } from '../utils/paths.js';
-import { getRecipeById, loadRecipes } from './recipe-loader.js';
-
-const recipesAvailable = existsSync(getRecipeDir());
-
-describe.skipIf(!recipesAvailable)('recipe-loader pattern annotations', () => {
-  it('parses the Layer-4 pattern reference from meta.ts', async () => {
-    const dashboard = await getRecipeById('dashboard');
-    expect(dashboard?.pattern).toBe('dashboard');
-
-    const login = await getRecipeById('login');
-    expect(login?.pattern).toBe('form-page');
-
-    const onboarding = await getRecipeById('onboarding-flow');
-    expect(onboarding?.pattern).toBe('onboarding-guide');
-  });
-
-  it('leaves pattern undefined for recipes without one', async () => {
-    const profile = await getRecipeById('profile-card');
-    // profile-card is a component-level snippet, not a page archetype → no pattern
-    expect(profile?.pattern).toBeUndefined();
-  });
-
-  it('loads the meal-planner recipe with its planning-board pattern + Planner code', async () => {
-    const mealPlanner = await getRecipeById('meal-planner');
-    expect(mealPlanner?.title).toBe('Meal Planner');
-    expect(mealPlanner?.pattern).toBe('planning-board');
-    expect(mealPlanner?.components).toContain('Planner');
-    expect(mealPlanner?.code).toContain('<Planner');
-  });
-
-  it('every annotated pattern names an existing pattern file', async () => {
-    const recipes = await loadRecipes();
-    const known = new Set([
-      'dashboard',
-      'form-page',
-      'settings-page',
-      'tab-navigation',
-      'onboarding-guide',
-      'planning-board'
-    ]);
-    for (const r of recipes) {
-      if (r.pattern)
-        expect(known, `recipe "${r.id}" → unknown pattern "${r.pattern}"`).toContain(r.pattern);
-    }
-  });
-});

package/src/data/recipe-loader.ts

@@ -1,131 +0,0 @@
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import { getRecipeDir } from '../utils/paths.js';
-import type { RecipeEntry } from './catalog-loader.js';
-
-let cachedRecipes: RecipeEntry[] | null = null;
-
-function extractRecipeCode(content: string): string {
-  const startMatch = content.match(/const\s+recipeCode\s*=\s*\n?\s*/);
-  if (!startMatch) return '';
-
-  const startIdx = (startMatch.index ?? 0) + startMatch[0].length;
-  const rest = content.slice(startIdx);
-
-  let depth = 0;
-  let endIdx = -1;
-
-  for (let i = 0; i < rest.length; i++) {
-    if (rest[i] === '`') {
-      depth = depth === 0 ? 1 : 0;
-    }
-    if (depth === 0 && rest[i] === ';') {
-      endIdx = i;
-      break;
-    }
-  }
-
-  if (endIdx === -1) return '';
-
-  const raw = rest.slice(0, endIdx);
-  const parts = raw.split(/`\s*\+\s*\n?\s*`/);
-  return parts.map((p) => p.replace(/^\s*`|`\s*$/g, '')).join('');
-}
-
-export async function loadRecipes(): Promise<RecipeEntry[]> {
-  if (cachedRecipes) return cachedRecipes;
-
-  const recipeDir = getRecipeDir();
-  const entries: RecipeEntry[] = [];
-
-  let dirs: string[];
-  try {
-    dirs = await readdir(recipeDir);
-  } catch {
-    cachedRecipes = [];
-    return [];
-  }
-
-  for (const dirName of dirs) {
-    const dirPath = resolve(recipeDir, dirName);
-    const dirStat = await stat(dirPath).catch(() => null);
-    if (!dirStat?.isDirectory()) continue;
-
-    // Read structured metadata from meta.ts
-    const metaPath = resolve(dirPath, 'meta.ts');
-    let meta: {
-      title: string;
-      description: string;
-      components: string[];
-      features: string[];
-      pattern: string;
-    };
-    try {
-      const metaContent = await readFile(metaPath, 'utf-8');
-      meta = parseRecipeMeta(metaContent);
-    } catch {
-      continue;
-    }
-
-    // Read recipeCode from +page.svelte (still embedded there for the live preview)
-    const pagePath = resolve(dirPath, '+page.svelte');
-    let code = '';
-    try {
-      const pageContent = await readFile(pagePath, 'utf-8');
-      code = extractRecipeCode(pageContent);
-    } catch {
-      // No page = no code, but metadata is still valid
-    }
-
-    entries.push({
-      id: dirName,
-      title: meta.title,
-      description: meta.description,
-      components: meta.components,
-      code,
-      features: meta.features,
-      pattern: meta.pattern || undefined
-    });
-  }
-
-  cachedRecipes = entries;
-  return entries;
-}
-
-export async function getRecipeById(id: string): Promise<RecipeEntry | null> {
-  const recipes = await loadRecipes();
-  return recipes.find((r) => r.id === id) ?? null;
-}
-
-function parseRecipeMeta(content: string): {
-  title: string;
-  description: string;
-  components: string[];
-  features: string[];
-  pattern: string;
-} {
-  const extractString = (key: string): string => {
-    const match = content.match(new RegExp(`${key}:\\s*['"]([^'"]*?)['"]`));
-    if (match?.[1]) return match[1];
-    // Multi-line string with concatenation
-    const multiMatch = content.match(new RegExp(`${key}:\\s*\\n?\\s*['"]([\\s\\S]*?)['"]`, 'm'));
-    return multiMatch?.[1]?.replace(/'\s*\+\s*\n?\s*'/g, '') ?? '';
-  };
-
-  const extractArray = (key: string): string[] => {
-    const match = content.match(new RegExp(`${key}:\\s*\\[([^\\]]+)\\]`, 's'));
-    if (!match?.[1]) return [];
-    return match[1]
-      .split(',')
-      .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
-      .filter((s) => s.length > 0);
-  };
-
-  return {
-    title: extractString('title'),
-    description: extractString('description'),
-    components: extractArray('components'),
-    features: extractArray('features'),
-    pattern: extractString('pattern')
-  };
-}

package/src/design-linter/heuristics.ts

@@ -1,162 +0,0 @@
-/**
- * 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

@@ -1,14 +0,0 @@
-/**
- * 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';