@urbicon-ui/design-engine 6.1.8

package/src/rubric/rubric.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { MAX_RUBRIC_SCORE, RUBRIC_CRITERIA, renderRubric } from './rubric.js';
+
+describe('rubric criteria', () => {
+  it('keeps the eight A/B-test criteria', () => {
+    expect(RUBRIC_CRITERIA).toHaveLength(8);
+    expect(MAX_RUBRIC_SCORE).toBe(40);
+  });
+
+  it('has unique ids and complete anchors', () => {
+    const ids = new Set(RUBRIC_CRITERIA.map((c) => c.id));
+    expect(ids.size).toBe(RUBRIC_CRITERIA.length);
+    for (const c of RUBRIC_CRITERIA) {
+      expect(c.name).toBeTruthy();
+      expect(c.measures).toBeTruthy();
+      for (const score of [1, 3, 5] as const) {
+        expect(c.anchors[score], `${c.id} anchor ${score}`).toBeTruthy();
+      }
+    }
+  });
+
+  it('anchors technical correctness on validate_design', () => {
+    const correctness = RUBRIC_CRITERIA.find((c) => c.id === 'correctness');
+    expect(correctness?.anchors[5]).toContain('validate_design');
+  });
+});
+
+describe('renderRubric', () => {
+  const md = renderRubric();
+
+  it('renders every criterion and the total', () => {
+    for (const c of RUBRIC_CRITERIA) expect(md).toContain(c.name);
+    expect(md).toContain(`/${MAX_RUBRIC_SCORE}`);
+  });
+
+  it('tells the judge to run validate_design first', () => {
+    expect(md).toContain('validate_design');
+  });
+
+  it('describes the panel-of-lenses approach for variant selection', () => {
+    expect(md.toLowerCase()).toContain('lens');
+  });
+});

package/src/rubric/rubric.ts

@@ -0,0 +1,140 @@
+/**
+ * The design-quality scoring rubric — the qualitative half of the design loop
+ * (docs/DESIGN-MCP.md, step 3). Where `validate_design` answers "is it correct?"
+ * deterministically, the rubric answers "is it good?" through a judge.
+ *
+ * The eight criteria have been validated empirically against design-quality
+ * comparisons, scoring each 1–5 and summing to /40. Keeping the same instrument
+ * means new evaluations are directly comparable to that baseline. This is the
+ * SINGLE SOURCE for the criteria: the
+ * `get_design_principles(as="rubric")` tool renders it to Markdown, and the
+ * eval-suite (WP5) imports the same constants to score programmatically.
+ */
+
+export interface RubricCriterion {
+  id: string;
+  /** Display name for the criterion. */
+  name: string;
+  /** One line on what the criterion measures. */
+  measures: string;
+  /** Anchored descriptions for scores 1, 3 and 5 (the judge interpolates 2 and 4). */
+  anchors: { 1: string; 3: string; 5: string };
+}
+
+export const RUBRIC_CRITERIA: readonly RubricCriterion[] = [
+  {
+    id: 'distinctiveness',
+    name: 'Design Language Distinctiveness',
+    measures: 'Whether the page has its own visual identity or reads as a generic template.',
+    anchors: {
+      1: 'The most common layout imaginable — a Tailwind-UI starter with no personality.',
+      3: 'A few custom touches (one heading style, one composition) over conventional bones.',
+      5: 'A coherent, deliberate identity: custom compositions over default components, a consistent typographic voice, signature moments.'
+    }
+  },
+  {
+    id: 'color',
+    name: 'Color Scheme Coherence',
+    measures: 'Whether colour carries meaning or merely decorates.',
+    anchors: {
+      1: 'Decorative colour — a rainbow of intents; intent colours where neutral belongs.',
+      3: 'Intent mapping mostly correct, but some decorative or noisy colour remains.',
+      5: 'Neutral surfaces dominate (80–90%); intent colour appears only for genuine status, severity, or action.'
+    }
+  },
+  {
+    id: 'spacing',
+    name: 'Spacing Consistency',
+    measures: 'Whether spacing expresses hierarchy.',
+    anchors: {
+      1: 'One uniform rhythm everywhere (e.g. all `space-y-6`).',
+      3: 'Some variation, but no clear within-vs-between system.',
+      5: 'A clear two-tier rhythm (tight within items, generous between sections), with data-driven variation where it helps.'
+    }
+  },
+  {
+    id: 'radius',
+    name: 'Radius & Shape Language',
+    measures: 'Whether shape is a deliberate choice.',
+    anchors: {
+      1: 'Zero radius intent — component defaults only, no shape strategy.',
+      3: 'Some radius use, but inconsistent (mixed methods, no hierarchy).',
+      5: 'A deliberate radius hierarchy (e.g. hero > standard > compact) applied consistently via `class`/`slotClasses`.'
+    }
+  },
+  {
+    id: 'ux',
+    name: 'UX Pattern Originality',
+    measures: 'Whether interaction patterns go beyond the textbook.',
+    anchors: {
+      1: 'Textbook only — divider lists, stacked buttons, defaults throughout.',
+      3: 'A few genuine UX touches (a thoughtful empty state, a useful affordance).',
+      5: 'Creative, effective patterns that serve the content — original compositions, state-driven layout.'
+    }
+  },
+  {
+    id: 'hierarchy',
+    name: 'Visual Hierarchy',
+    measures: 'Whether the eye is guided to what matters.',
+    anchors: {
+      1: 'Everything equally weighted — nothing dominates; labels compete with data.',
+      3: 'Some dominance, but flat regions remain.',
+      5: 'Each section has one clearly dominant element; metadata is recessed; visual weight tracks importance.'
+    }
+  },
+  {
+    id: 'cohesion',
+    name: 'Overall Design Cohesion',
+    measures: 'Whether the page reads as one designed artifact.',
+    anchors: {
+      1: 'Cohesive only through sameness, or parts feel grafted on / disconnected.',
+      3: 'Mostly unified, with a section or two that drift.',
+      5: 'A single design DNA — consistent radius, typographic voice, and component logic tie the whole page together.'
+    }
+  },
+  {
+    id: 'correctness',
+    name: 'Technical Correctness',
+    measures: 'Whether the code is valid and uses real component APIs and design tokens.',
+    anchors: {
+      1: 'Hallucinated tokens, broken dynamic classes, or wrong component APIs — would not render as intended.',
+      3: 'Largely correct with a few token or API slips.',
+      5: 'Valid semantic tokens, correct Svelte 5 and component APIs, no broken classes. Anchor this with `validate_design` — a passing linter (0 errors/warnings) puts this at 4–5.'
+    }
+  }
+];
+
+export const MAX_RUBRIC_SCORE = RUBRIC_CRITERIA.length * 5;
+
+/** Render the rubric as Markdown for a judge (served by `get_design_principles(as="rubric")`). */
+export function renderRubric(): string {
+  let md = '# Design-Quality Rubric\n\n';
+  md += `Score a generated UI on each of the ${RUBRIC_CRITERIA.length} criteria from **1 to 5**, then sum to **/${MAX_RUBRIC_SCORE}**. `;
+  md +=
+    'For every score, cite specific evidence from the code (a class, a component, a layout choice) — a number without a reason is not a judgement.\n\n';
+  md += '**Before scoring, run `validate_design` on the code.** It deterministically catches the ';
+  md +=
+    'correctness failures (hallucinated tokens, broken dynamic classes) that a judge tends to miss, and it anchors the *Technical Correctness* criterion.\n\n';
+
+  for (const [i, c] of RUBRIC_CRITERIA.entries()) {
+    md += `## ${i + 1}. ${c.name}\n\n`;
+    md += `*${c.measures}*\n\n`;
+    md += `- **1** — ${c.anchors[1]}\n`;
+    md += `- **3** — ${c.anchors[3]}\n`;
+    md += `- **5** — ${c.anchors[5]}\n\n`;
+  }
+
+  md += '---\n\n';
+  md += '## Using the rubric\n\n';
+  md +=
+    '- **As a single judge:** score all criteria, sum to /' +
+    MAX_RUBRIC_SCORE +
+    ', and list the two lowest as the concrete revision targets.\n';
+  md +=
+    '- **As a panel (recommended for variant selection):** run one judge per *lens* — correctness, hierarchy, paradigm-fidelity, distinctiveness — rather than N identical judges. Diversity of lens catches failures redundancy cannot.\n';
+  md +=
+    '- **For N variants:** score each, pick the winner, then graft the best ideas from the runners-up before a final `validate_design` pass.\n';
+  md +=
+    '- **Reward deviation within the rules.** A safe, generic page should not outscore a distinctive one that stays inside the paradigm. Penalise AI-slop sameness on *Distinctiveness* and *UX Pattern Originality*.\n';
+  return md;
+}

package/src/search/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Public API of the search module — the component-catalog schema, the discovery
+ * ranker, and the `llm.txt` section parser. Shared by the `urbicon` CLI
+ * (`find` / `get-component`) and the remote MCP server (`find_components` /
+ * `get_component`) so local and remote knowledge agree (DESIGN-MCP-V2 §5,
+ * "engine/search + content"). Pure and dependency-free; consumers own the file I/O
+ * (locating the bundle via `@urbicon-ui/design-content`, reading it themselves).
+ */
+
+export { matchComponents } from './match.js';
+export { extractSection, type LlmTxtSection } from './section.js';
+export type { ComponentCatalog, ComponentCatalogEntry, RecipeEntry } from './types.js';

package/src/search/match.ts

@@ -0,0 +1,115 @@
+import type { ComponentCatalogEntry } from './types.js';
+
+interface ScoredEntry {
+  entry: ComponentCatalogEntry;
+  score: number;
+}
+
+/**
+ * Rank catalog entries against a free-text query — the component-discovery ranker
+ * behind both `find_components` (remote MCP) and `urbicon find` (CLI), so local and
+ * remote discovery agree. Pure and dependency-free: each query keyword scores on an
+ * exact / substring / fuzzy (Levenshtein ≤ 2) name-or-slug hit, a tag hit, a
+ * description hit, and a weak prop-name hit; an explicit `tags` filter adds weight.
+ * Keywords shorter than two characters are dropped. Returns the top `limit` entries
+ * with a positive score, best first; an empty list when nothing matches.
+ */
+export function matchComponents(
+  components: ComponentCatalogEntry[],
+  query: string,
+  tags?: string[],
+  limit = 5
+): ComponentCatalogEntry[] {
+  const keywords = query
+    .toLowerCase()
+    .split(/[\s,\-_]+/)
+    .filter((w) => w.length > 1);
+
+  const scored: ScoredEntry[] = components.map((entry) => {
+    let score = 0;
+    const nameLower = entry.name.toLowerCase();
+    const slugLower = entry.slug.toLowerCase();
+    const descLower = entry.description.toLowerCase();
+
+    for (const kw of keywords) {
+      // Exact match
+      if (nameLower === kw || slugLower === kw) {
+        score += 10;
+      } else if (nameLower.includes(kw) || slugLower.includes(kw)) {
+        score += 7;
+      } else {
+        // Fuzzy match on name/slug (Levenshtein distance <= 2)
+        const nameDist = levenshtein(nameLower, kw);
+        const slugDist = levenshtein(slugLower, kw);
+        const minDist = Math.min(nameDist, slugDist);
+        if (minDist <= 1) {
+          score += 6;
+        } else if (minDist <= 2) {
+          score += 3;
+        }
+      }
+
+      // Tag match
+      if (entry.tags.some((t) => t.toLowerCase() === kw)) {
+        score += 5;
+      }
+
+      // Description match
+      if (descLower.includes(kw)) {
+        score += 3;
+      }
+
+      // Prop name match
+      if (entry.keyProps.some((p) => p.toLowerCase().includes(kw))) {
+        score += 1;
+      }
+    }
+
+    if (tags && tags.length > 0) {
+      const entryTags = entry.tags.map((t) => t.toLowerCase());
+      for (const tag of tags) {
+        if (entryTags.includes(tag.toLowerCase())) {
+          score += 5;
+        }
+      }
+    }
+
+    return { entry, score };
+  });
+
+  return scored
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((s) => s.entry);
+}
+
+function levenshtein(a: string, b: string): number {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  // Early exit for large length differences
+  if (Math.abs(a.length - b.length) > 2) return 3;
+
+  const matrix: number[][] = [];
+
+  for (let i = 0; i <= a.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= b.length; j++) {
+    matrix[0]![j] = j;
+  }
+
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i]![j] = Math.min(
+        matrix[i - 1]![j]! + 1,
+        matrix[i]![j - 1]! + 1,
+        matrix[i - 1]![j - 1]! + cost
+      );
+    }
+  }
+
+  return matrix[a.length]![b.length]!;
+}

package/src/search/search.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from 'vitest';
+import { matchComponents } from './match.js';
+import { extractSection } from './section.js';
+import type { ComponentCatalogEntry } from './types.js';
+
+function makeEntry(
+  overrides: Partial<ComponentCatalogEntry> & Pick<ComponentCatalogEntry, 'name' | 'slug'>
+): ComponentCatalogEntry {
+  return {
+    package: '@urbicon-ui/blocks',
+    group: 'primitives',
+    description: '',
+    tags: [],
+    import: `import { ${overrides.name} } from '@urbicon-ui/blocks';`,
+    llmTxtPath: '',
+    variants: [],
+    keyProps: [],
+    keyPropTypes: {},
+    slots: [],
+    hasExamples: false,
+    relatedComponents: [],
+    ...overrides
+  };
+}
+
+const Button = makeEntry({
+  name: 'Button',
+  slug: 'button',
+  description: 'Click to trigger an action',
+  tags: ['action'],
+  keyProps: ['intent', 'variant', 'size']
+});
+
+const Input = makeEntry({
+  name: 'Input',
+  slug: 'input',
+  description: 'Single-line text field',
+  tags: ['form'],
+  keyProps: ['value', 'error']
+});
+
+const Dialog = makeEntry({
+  name: 'Dialog',
+  slug: 'dialog',
+  description: 'Modal overlay container',
+  tags: ['overlay']
+});
+
+const catalog = [Button, Input, Dialog];
+
+describe('matchComponents', () => {
+  it('ranks an exact name match first', () => {
+    const results = matchComponents(catalog, 'button');
+    expect(results[0]?.name).toBe('Button');
+  });
+
+  it('matches by case-insensitive substring of the name', () => {
+    const results = matchComponents(catalog, 'Butt');
+    expect(results.some((r) => r.name === 'Button')).toBe(true);
+  });
+
+  it('fuzz-matches a single-character typo', () => {
+    const results = matchComponents(catalog, 'Buton'); // typo: missing "t"
+    expect(results[0]?.name).toBe('Button');
+  });
+
+  it('ignores matches that are too distant', () => {
+    const results = matchComponents(catalog, 'xyzzy');
+    expect(results).toEqual([]);
+  });
+
+  it('scores tag matches when the tag keyword is present in the query', () => {
+    const results = matchComponents(catalog, 'form');
+    expect(results[0]?.name).toBe('Input');
+  });
+
+  it('filters by the explicit tags argument', () => {
+    const results = matchComponents(catalog, 'container', ['overlay']);
+    expect(results.some((r) => r.name === 'Dialog')).toBe(true);
+  });
+
+  it('respects the limit', () => {
+    const many = Array.from({ length: 10 }, (_, i) =>
+      makeEntry({ name: `Button${i}`, slug: `button-${i}`, description: 'click' })
+    );
+    const results = matchComponents(many, 'button', undefined, 3);
+    expect(results).toHaveLength(3);
+  });
+
+  it('drops words shorter than two characters before matching', () => {
+    // "a" and "x" below are too short and should be filtered;
+    // only "button" remains and should drive the match.
+    const results = matchComponents(catalog, 'a x button');
+    expect(results[0]?.name).toBe('Button');
+  });
+
+  it('uses the prop-name match as a weak signal', () => {
+    const results = matchComponents(catalog, 'intent');
+    expect(results.some((r) => r.name === 'Button')).toBe(true);
+  });
+
+  it('returns an empty list when the query has no usable keywords', () => {
+    const results = matchComponents(catalog, ', , ');
+    expect(results).toEqual([]);
+  });
+});
+
+// Regression for the DateGrid/Planner discovery fix: planning-board queries
+// used to steer toward Calendar (a timed-event scheduler). With Planner in the
+// catalog they must land on Planner instead — driven purely by its catalog
+// description/tags/slug, no hardcoded keyword map.
+describe('matchComponents — Planner discovery', () => {
+  const Calendar = makeEntry({
+    name: 'Calendar',
+    slug: 'calendar',
+    description: 'Event display and date selection with month, week and day views.',
+    tags: ['display'],
+    relatedComponents: ['DatePicker']
+  });
+  const Planner = makeEntry({
+    name: 'Planner',
+    slug: 'planner',
+    description:
+      'Date-indexed planning board — a week, month or custom-range grid whose cells hold your domain content (meals, shifts, bookings, content slots) via a generic cell snippet.',
+    tags: ['display', 'layout'],
+    keyProps: ['items', 'getDate', 'view', 'cell'],
+    relatedComponents: ['Calendar', 'DatePicker']
+  });
+  const dateCatalog = [Calendar, Planner];
+
+  for (const query of ['planner', 'meal planner', 'weekly plan', 'shift schedule', 'week board']) {
+    it(`ranks Planner first for "${query}"`, () => {
+      const results = matchComponents(dateCatalog, query);
+      expect(results[0]?.name).toBe('Planner');
+    });
+  }
+
+  it('still ranks Calendar first for an event/appointment query', () => {
+    const results = matchComponents(dateCatalog, 'event calendar');
+    expect(results[0]?.name).toBe('Calendar');
+  });
+});
+
+describe('extractSection', () => {
+  const llm = [
+    '# Button',
+    '',
+    'Click to trigger an action.',
+    '',
+    '### Examples',
+    '',
+    '```svelte',
+    '<Button intent="primary">Save</Button>',
+    '```',
+    '',
+    '### API',
+    '',
+    '| Prop | Type | Default |',
+    '| --- | --- | --- |',
+    '| intent | string | primary |',
+    '',
+    '### Slots (slotClasses keys)',
+    '',
+    '`base`, `label`'
+  ].join('\n');
+
+  it('returns everything before the first ### as the overview', () => {
+    const overview = extractSection(llm, 'overview');
+    expect(overview).toContain('# Button');
+    expect(overview).toContain('Click to trigger an action.');
+    expect(overview).not.toContain('### Examples');
+  });
+
+  it('extracts a named section up to the next heading', () => {
+    const api = extractSection(llm, 'api');
+    expect(api).toContain('### API');
+    expect(api).toContain('| intent | string | primary |');
+    expect(api).not.toContain('### Slots');
+  });
+
+  it('maps the parenthesised slots heading to the slots section', () => {
+    const slots = extractSection(llm, 'slots');
+    expect(slots).toContain('`base`, `label`');
+  });
+
+  it('returns null for a section that is absent', () => {
+    expect(extractSection(llm, 'variants')).toBe(null);
+  });
+
+  it('treats content with no headings as all-overview', () => {
+    expect(extractSection('Just a description, no sections.', 'overview')).toBe(
+      'Just a description, no sections.'
+    );
+  });
+});

package/src/search/section.ts

@@ -0,0 +1,47 @@
+/**
+ * Slice a named section out of a component's `llm.txt` — the `### …` blocks that
+ * `docs-gen` emits (Examples, Variants, API, Slots), plus a synthetic `overview`
+ * (everything before the first `###`). Pure string logic so `get_component` (remote)
+ * and `urbicon get-component` (CLI) extract identically; each consumer owns the I/O
+ * (locating and reading the file). Returns `null` when the section is absent.
+ */
+
+export type LlmTxtSection = 'overview' | 'examples' | 'variants' | 'api' | 'slots';
+
+const SECTION_HEADING_MAP: Record<string, LlmTxtSection> = {
+  examples: 'examples',
+  variants: 'variants',
+  api: 'api',
+  'slots (slotclasses keys)': 'slots'
+};
+
+export function extractSection(content: string, section: LlmTxtSection): string | null {
+  if (section === 'overview') {
+    const firstH3 = content.indexOf('\n### ');
+    if (firstH3 === -1) return content.trim();
+    return content.slice(0, firstH3).trim();
+  }
+
+  const lines = content.split('\n');
+  let capturing = false;
+  const result: string[] = [];
+
+  for (const line of lines) {
+    if (line.startsWith('### ')) {
+      const heading = line.slice(4).trim().toLowerCase();
+      const mapped = SECTION_HEADING_MAP[heading];
+      if (mapped === section) {
+        capturing = true;
+        result.push(line);
+        continue;
+      } else if (capturing) {
+        break;
+      }
+    }
+    if (capturing) {
+      result.push(line);
+    }
+  }
+
+  return result.length > 0 ? result.join('\n').trim() : null;
+}

package/src/search/types.ts

@@ -0,0 +1,44 @@
+/**
+ * The component-catalog schema — the shape of the version-pinned
+ * `component-catalog.json` that `@urbicon-ui/design-content` ships and `docs-gen`
+ * assembles. It lives in the engine (not the content package) so the search logic
+ * and every consumer — the `urbicon` CLI's `find`/`get-component`, the remote MCP
+ * server's `find_components`/`get_component` — share one authoritative type, while
+ * `design-content` stays a pure path locator (DESIGN-MCP-V2 §5, "engine/search + content").
+ */
+
+export interface ComponentCatalogEntry {
+  name: string;
+  slug: string;
+  package: string;
+  group: 'primitives' | 'components' | 'core' | 'auth';
+  description: string;
+  tags: string[];
+  import: string;
+  llmTxtPath: string;
+  variants: { name: string; values: string[]; default?: string }[];
+  keyProps: string[];
+  keyPropTypes: Record<string, string>;
+  slots: string[];
+  hasExamples: boolean;
+  relatedComponents: string[];
+}
+
+export interface RecipeEntry {
+  id: string;
+  title: string;
+  description: string;
+  components: string[];
+  code: string;
+  features: string[];
+  /** Layer-4 composition pattern this recipe is an instance of (e.g. "dashboard"). Cross-links to `get_pattern`. */
+  pattern?: string;
+}
+
+export interface ComponentCatalog {
+  generated: string;
+  version: string;
+  components: ComponentCatalogEntry[];
+  recipes: RecipeEntry[];
+  tags: string[];
+}