@urbicon-ui/design-engine 6.2.0 → 6.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/design-engine",
-  "version": "6.2.0",
+  "version": "6.3.3",
   "description": "Deterministic design engine for Urbicon UI — the zero-dependency design linter, manifest parser and quality rubric that power the design loop (validate · context · judge).",
   "license": "MIT",
   "repository": {

package/src/linter/linter.test.ts

@@ -507,3 +507,66 @@ describe('rule metadata', () => {
     expect(ids(lintDesign(code).findings)).toEqual(ids(lintDesign(code).findings));
   });
 });
+
+describe('deep-internal-import', () => {
+  it('flags a deep import into a package component file', () => {
+    const code =
+      "<script>import Button from '@urbicon-ui/blocks/primitives/Button/Button.svelte';</script>";
+    expect(has(lintDesign(code).findings, 'deep-internal-import')).toBe(true);
+  });
+  it('flags an internal-directory path even without a file extension', () => {
+    const code = "<script>import { x } from '@urbicon-ui/blocks/icons/registry';</script>";
+    expect(has(lintDesign(code).findings, 'deep-internal-import')).toBe(true);
+  });
+  it('does NOT flag the package root or documented public subpaths', () => {
+    const code = [
+      "import { Button } from '@urbicon-ui/blocks';",
+      "import { addDays } from '@urbicon-ui/blocks/date';",
+      "import en from '@urbicon-ui/blocks/i18n/en';",
+      "import '@urbicon-ui/blocks/style/index.css';"
+    ].join('\n');
+    expect(has(lintDesign(code).findings, 'deep-internal-import')).toBe(false);
+  });
+});
+
+describe('hardcoded-motion', () => {
+  it('flags a hardcoded duration and a cubic-bezier easing', () => {
+    const code =
+      '<div class="transition-transform duration-[250ms] ease-[cubic-bezier(0.4,0,0.2,1)]">';
+    expect(lintDesign(code).findings.filter((f) => f.ruleId === 'hardcoded-motion')).toHaveLength(
+      2
+    );
+  });
+  it('flags a fractional-second duration', () => {
+    expect(has(lintDesign('<div class="duration-[0.2s]">').findings, 'hardcoded-motion')).toBe(
+      true
+    );
+  });
+  it('does NOT flag motion tokens or named eases', () => {
+    const code =
+      '<div class="duration-[var(--blocks-duration-fast)] ease-[var(--blocks-ease-smooth)] ease-out">';
+    expect(has(lintDesign(code).findings, 'hardcoded-motion')).toBe(false);
+  });
+});
+
+describe('token-hallucination — intent typos', () => {
+  it('flags a misspelled intent (`bg-primay` → `bg-primary`)', () => {
+    expect(has(lintDesign('<button class="bg-primay">').findings, 'token-hallucination')).toBe(
+      true
+    );
+  });
+  it('flags a misspelled intent on a text utility (`text-sucess`)', () => {
+    expect(has(lintDesign('<span class="text-sucess">').findings, 'token-hallucination')).toBe(
+      true
+    );
+  });
+  it('does NOT flag arbitrary, far-from-intent cores (`bg-brand`, `bg-cover`)', () => {
+    const { findings } = lintDesign('<div class="bg-brand text-on-brand bg-cover">');
+    expect(has(findings, 'token-hallucination')).toBe(false);
+  });
+  it('does NOT flag a valid intent', () => {
+    expect(
+      has(lintDesign('<div class="bg-primary text-success">').findings, 'token-hallucination')
+    ).toBe(false);
+  });
+});

package/src/linter/rules.ts

@@ -13,6 +13,7 @@ import {
   KNOWN_BAD_NAMESPACES,
   KNOWN_FOREIGN_CORES,
   SEMANTIC_NAMESPACES,
+  suggestIntentTypo,
   VALID_TOKEN_CORES
 } from './tokens.js';
 import type { Finding, Rule } from './types.js';
@@ -261,6 +262,94 @@ const dynamicClassInterpolation: Rule = {
   }
 };
 
+/** Subpath segments that are internal to an `@urbicon-ui` package — never a public export. */
+const INTERNAL_SUBPATH_SEGMENTS = new Set([
+  'primitives',
+  'components',
+  'lib',
+  'dist',
+  'src',
+  'icons'
+]);
+
+/**
+ * A deep import into an `@urbicon-ui` package: either a concrete component/module
+ * file (`…/Button.svelte`, `…/foo.js`) or a path through an internal directory
+ * (`primitives/`, `components/`, …). The documented public subpaths — `./date`,
+ * `./style/*.css`, `./i18n/en` — are flat, extensionless-or-CSS, and stay allowed.
+ */
+function isDeepInternalSubpath(subpath: string): boolean {
+  if (/\.svelte(\.[jt]s)?$|\.[jt]s$/.test(subpath)) return true;
+  return subpath.split('/').some((seg) => INTERNAL_SUBPATH_SEGMENTS.has(seg));
+}
+
+const deepInternalImport: Rule = {
+  id: 'deep-internal-import',
+  severity: 'error',
+  description: 'Deep/internal import into an `@urbicon-ui` package instead of its public root.',
+  check(lines) {
+    // The module specifier of any import / export-from / @import / dynamic import.
+    const re = /['"](@urbicon-ui\/[a-z-]+)\/([^'"]+)['"]/g;
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(re)) {
+        const pkg = m[1]!;
+        const subpath = m[2]!;
+        if (!isDeepInternalSubpath(subpath)) continue;
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `Deep import \`${pkg}/${subpath}\` reaches into ${pkg}'s internals — they can move between releases.`,
+          fix: `Import from the package root: \`import { … } from '${pkg}'\`.`,
+          line: i + 1,
+          match: `${pkg}/${subpath}`
+        });
+      }
+    });
+    return dedupeByLine(findings);
+  }
+};
+
+const hardcodedMotion: Rule = {
+  id: 'hardcoded-motion',
+  severity: 'error',
+  description:
+    'Hardcoded transition duration or `cubic-bezier()` easing instead of a motion token.',
+  check(lines) {
+    // `duration-[250ms]` / `duration-[0.2s]` — but not `duration-[var(--blocks-duration-fast)]`.
+    const duration = /\bduration-\[\d+(?:\.\d+)?m?s\]/g;
+    // `ease-[cubic-bezier(…)]` — but not `ease-[var(--blocks-ease-smooth)]` or named `ease-out`.
+    const easing = /\bease-\[cubic-bezier\([^\]]*\)\]/g;
+    const findings: Finding[] = [];
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(duration)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `Hardcoded transition duration \`${m[0]}\` bypasses the motion scale (no global speed / reduced-motion control).`,
+          fix: 'Use a duration token: `duration-[var(--blocks-duration-fast)]` / `-normal` / `-slow`.',
+          line: i + 1,
+          match: m[0]
+        });
+      }
+      for (const m of line.matchAll(easing)) {
+        findings.push({
+          ruleId: this.id,
+          severity: this.severity,
+          kind: 'deterministic',
+          message: `Hardcoded \`cubic-bezier()\` easing \`${m[0]}\` bypasses the motion system's easing tokens.`,
+          fix: 'Use an easing token: `ease-[var(--blocks-ease-smooth)]` / `-snappy` / `-gentle`, or a named Tailwind ease (`ease-out`).',
+          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
@@ -284,7 +373,25 @@ const tokenHallucination: Rule = {
     lines.forEach((line, i) => {
       for (const m of line.matchAll(re)) {
         const core = m[2]!;
-        if (!looksSemantic(core)) continue;
+        if (!looksSemantic(core)) {
+          // Not in our vocabulary — but a bare core one edit from an intent is almost
+          // certainly a misspelling (`bg-primay` → `bg-primary`), where the namespace
+          // heuristic alone would let it pass silently. Arbitrary cores (`bg-cover`,
+          // `bg-brand`) are far from every intent and stay unflagged.
+          const intended = suggestIntentTypo(core);
+          if (intended) {
+            findings.push({
+              ruleId: this.id,
+              severity: this.severity,
+              kind: 'deterministic',
+              message: `\`${m[1]}-${core}\` looks like a typo of \`${m[1]}-${intended}\`.`,
+              fix: `Did you mean \`${m[1]}-${intended}\`? Valid intents: ${INTENT_NAMES.join(', ')}.`,
+              line: i + 1,
+              match: m[0]
+            });
+          }
+          continue;
+        }
         if (validCores.has(core)) continue;
 
         findings.push({
@@ -348,6 +455,8 @@ export const RULES: Rule[] = [
   darkModeOverride,
   focusNotVisible,
   hardcodedZIndex,
+  hardcodedMotion,
+  deepInternalImport,
   dynamicClassInterpolation,
   tokenHallucination,
   ...MARKUP_RULES

package/src/linter/tokens.test.ts

@@ -2,7 +2,12 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
-import { resolveValidTokenCores, VALID_TOKEN_CORES } from './tokens.js';
+import {
+  isSingleEditApart,
+  resolveValidTokenCores,
+  suggestIntentTypo,
+  VALID_TOKEN_CORES
+} from './tokens.js';
 
 /**
  * Drift guard: the hardcoded {@link VALID_TOKEN_CORES} is the design-engine's
@@ -109,3 +114,31 @@ describe('resolveValidTokenCores', () => {
     expect(VALID_TOKEN_CORES.has('surface-brand')).toBe(false);
   });
 });
+
+describe('isSingleEditApart', () => {
+  it('detects single substitutions, insertions, deletions, and adjacent transpositions', () => {
+    expect(isSingleEditApart('primay', 'primary')).toBe(true); // insertion
+    expect(isSingleEditApart('primaryy', 'primary')).toBe(true); // deletion
+    expect(isSingleEditApart('prinary', 'primary')).toBe(true); // substitution
+    expect(isSingleEditApart('priamry', 'primary')).toBe(true); // transposition
+  });
+  it('rejects identical strings and edits of distance ≥ 2', () => {
+    expect(isSingleEditApart('primary', 'primary')).toBe(false);
+    expect(isSingleEditApart('brand', 'primary')).toBe(false);
+    expect(isSingleEditApart('prmiarx', 'primary')).toBe(false); // two edits
+  });
+});
+
+describe('suggestIntentTypo', () => {
+  it('maps a one-edit misspelling to the intended intent', () => {
+    expect(suggestIntentTypo('primay')).toBe('primary');
+    expect(suggestIntentTypo('sucess')).toBe('success');
+    expect(suggestIntentTypo('wraning')).toBe('warning'); // transposition
+  });
+  it('returns null for exact intents, hyphenated cores, and unrelated words', () => {
+    expect(suggestIntentTypo('primary')).toBeNull(); // exact intent, not a typo
+    expect(suggestIntentTypo('primary-subtle')).toBeNull(); // hyphenated — left to whitelist
+    expect(suggestIntentTypo('brand')).toBeNull(); // far from every intent
+    expect(suggestIntentTypo('cover')).toBeNull();
+  });
+});

package/src/linter/tokens.ts

@@ -115,6 +115,9 @@ const INTERACTIVE_CORES = [
 /** 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;
 
+/** Skeleton loading tokens → `bg-skeleton-shimmer` (the shimmer overlay sweep). */
+const SKELETON_CORES = ['skeleton-shimmer'] as const;
+
 function buildIntentCores(): string[] {
   const cores: string[] = [];
   for (const intent of INTENT_NAMES) {
@@ -138,7 +141,8 @@ export const VALID_TOKEN_CORES: ReadonlySet<string> = new Set([
   ...WARM_NEUTRAL_STEPS.map((s) => `warm-neutral-${s}`),
   ...FEEDBACK_CORES,
   ...INTERACTIVE_CORES,
-  ...CHART_CORES
+  ...CHART_CORES,
+  ...SKELETON_CORES
 ]);
 
 /**
@@ -227,4 +231,62 @@ export const KNOWN_BAD_NAMESPACES: Record<string, string> = {
   '-fg': 'Use `text-on-primary` / `text-on-surface` for foreground-on-intent text.'
 };
 
+/**
+ * Whether `a` and `b` differ by exactly one typo: a single substitution,
+ * insertion, deletion, or adjacent transposition (Optimal String Alignment
+ * distance 1). Deliberately stricter than Levenshtein ≤ 2 — it catches the common
+ * typo classes (`primay`→`primary`, `sucess`→`success`, `priamry`→`primary`)
+ * while keeping unrelated words (`brand`, `cover`, `accent`) clearly apart, so
+ * the typo check never fires on a legitimately different utility.
+ */
+export function isSingleEditApart(a: string, b: string): boolean {
+  if (a === b) return false;
+  if (a.length === b.length) {
+    let diffs = 0;
+    let at = -1;
+    for (let i = 0; i < a.length; i++) {
+      if (a[i] !== b[i]) {
+        diffs++;
+        if (at === -1) at = i;
+      }
+    }
+    if (diffs === 1) return true; // one substitution
+    // adjacent transposition: two diffs that are a swapped neighbouring pair
+    return diffs === 2 && at >= 0 && a[at] === b[at + 1] && a[at + 1] === b[at];
+  }
+  if (Math.abs(a.length - b.length) !== 1) return false;
+  // one insertion/deletion: the shorter is the longer with a single char removed
+  const [short, long] = a.length < b.length ? [a, b] : [b, a];
+  let i = 0;
+  let j = 0;
+  let skipped = false;
+  while (i < short.length && j < long.length) {
+    if (short[i] === long[j]) {
+      i++;
+      j++;
+    } else if (!skipped) {
+      skipped = true;
+      j++;
+    } else {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * If `core` is a likely typo of an intent name — a single bare word one edit away
+ * from `primary`/`secondary`/… but not an exact intent — return the intended
+ * intent, else `null`. Hyphenated cores (`primary-subtle`, `success-foo`) are left
+ * to the namespace/whitelist checks; only the bare intent word is typo-matched.
+ */
+export function suggestIntentTypo(core: string): string | null {
+  if (core.includes('-')) return null;
+  if ((INTENT_NAMES as readonly string[]).includes(core)) return null;
+  for (const intent of INTENT_NAMES) {
+    if (isSingleEditApart(core, intent)) return intent;
+  }
+  return null;
+}
+
 export { INTENT_NAMES, INTENT_VARIANTS, SCALE_STEPS };

package/src/manifest/manifest.test.ts

@@ -172,6 +172,25 @@ describe('parseManifest — product intent', () => {
     expect(parseManifest(md).intent.references).toEqual(['Linear', 'Stripe']);
   });
 
+  it('joins a soft-wrapped Audience value instead of truncating at the first line', () => {
+    const md =
+      '## Product Intent\n\n**Audience:** Homeowners with rooftop solar and a battery — non-experts who glance\nat production, consumption and savings.\n';
+    expect(parseManifest(md).intent.audience).toBe(
+      'Homeowners with rooftop solar and a battery — non-experts who glance at production, consumption and savings.'
+    );
+  });
+
+  it('keeps the continuation items of a soft-wrapped inline reference list', () => {
+    const md = '## Product Intent\n\n**References:** Linear, Stripe, Notion,\nFigma, Things\n';
+    expect(parseManifest(md).intent.references).toEqual([
+      'Linear',
+      'Stripe',
+      'Notion',
+      'Figma',
+      'Things'
+    ]);
+  });
+
   it('returns an empty intent when the section is absent', () => {
     const intent = parseManifest('# Bare\n\nsome prose\n').intent;
     expect(intent).toEqual({ voice: [], references: [], antiReferences: [] });

package/src/manifest/manifest.ts

@@ -106,35 +106,62 @@ function parseIntent(body: string): ProductIntent {
   if (section === null) return emptyIntent();
   const lines = section.split('\n');
 
+  // A line that opens a different labelled field, or a heading — either terminates
+  // the value currently being gathered.
+  const isFieldOrHeading = (l: string): boolean => /^\*\*[^*]+:\*\*/.test(l) || /^#{1,6}\s/.test(l);
+
+  // `**Label:** value`, joining soft-wrapped continuation lines into one value —
+  // a Markdown line-wrap inside the value (common for a sentence-long Audience) is
+  // a continuation, not a truncation point. Stops at the first blank line, the next
+  // labelled field, or a heading.
   const inlineField = (label: string): string | undefined => {
-    const re = new RegExp(`^\\*\\*${label}:\\*\\*\\s*(.+)$`);
-    for (const l of lines) {
-      const m = l.match(re);
-      if (m) return m[1]!.trim();
+    const labelRe = new RegExp(`^\\*\\*${label}:\\*\\*\\s*(.*)$`);
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i]!.match(labelRe);
+      if (!m) continue;
+      const parts = m[1]!.trim() ? [m[1]!.trim()] : [];
+      for (let j = i + 1; j < lines.length; j++) {
+        const l = lines[j]!;
+        if (l.trim() === '' || isFieldOrHeading(l)) break;
+        parts.push(l.trim());
+      }
+      const value = parts.join(' ').trim();
+      return value === '' ? undefined : value;
     }
     return undefined;
   };
 
-  // Items under a `**Label:**`: an inline comma list on the label line and/or the
-  // bullet lines that follow it, up to the next labelled field. Blank/prose lines
-  // in between are skipped, not treated as terminators.
+  // Items under a `**Label:**`: an inline comma list on the label line (and its
+  // soft-wrapped continuation lines) and/or the bullet lines that follow it, up to
+  // the next labelled field. Blank/prose lines are skipped, not terminators.
   const listField = (label: string): string[] => {
     const items: string[] = [];
     const labelRe = new RegExp(`^\\*\\*${label}:\\*\\*\\s*(.*)$`);
     let capturing = false;
+    let inInlineRun = false; // still gathering the soft-wrapped inline comma value
     for (const l of lines) {
       if (!capturing) {
         const m = l.match(labelRe);
         if (m) {
           capturing = true;
+          inInlineRun = true;
           const inline = m[1]!.trim();
           if (inline) items.push(...splitList(inline));
         }
         continue;
       }
-      if (/^\*\*[^*]+:\*\*/.test(l)) break; // next labelled field ends this one
+      if (isFieldOrHeading(l)) break; // next labelled field / heading ends this one
       const bullet = l.match(/^\s*[-*]\s+(.+)$/);
-      if (bullet) items.push(bullet[1]!.trim());
+      if (bullet) {
+        items.push(bullet[1]!.trim());
+        inInlineRun = false; // bullets started — later loose lines aren't inline-list continuation
+        continue;
+      }
+      if (l.trim() === '') {
+        inInlineRun = false; // blank closes the inline run (bullets may still follow)
+        continue;
+      }
+      if (inInlineRun) items.push(...splitList(l.trim())); // soft-wrapped continuation of the inline list
     }
     return items;
   };