designlang 8.0.0 → 10.0.0

package/src/formatters/prompt-pack.js

@@ -0,0 +1,214 @@
+// Generates ready-to-paste prompts for v0, Lovable, Cursor, and Claude
+// Artifacts — plus atomic per-component "recipe cards". The point is to get an
+// LLM to reproduce a site's look without the user having to hand-translate the
+// extracted JSON. We inline the tokens, voice, section order, and library
+// guidance so the model has everything it needs in one message.
+
+function colorList(design) {
+  const all = (design.colors?.all || []).map(c => c.hex).filter(Boolean);
+  return [...new Set(all)].slice(0, 14);
+}
+
+function typeFamilies(design) {
+  return [...new Set((design.typography?.families || []).filter(Boolean))].slice(0, 4);
+}
+
+function scaleSnippet(scale = []) {
+  if (!scale.length) return '(not detected)';
+  return scale.slice(0, 8).map(s => (s.value || s) + (s.label ? ` (${s.label})` : '')).join(', ');
+}
+
+function radiiSnippet(borders) {
+  const r = (borders?.radii || []).slice(0, 6).map(x => (x.value || x).toString());
+  return r.length ? r.join(', ') : '(none)';
+}
+
+function shadowSnippet(shadows) {
+  const s = (shadows?.values || []).slice(0, 3).map(x => (x.value || x).toString());
+  return s.length ? s.join(' | ') : '(none)';
+}
+
+function librarySuggest(library) {
+  if (!library || library.library === 'unknown') return null;
+  const map = {
+    'shadcn/ui': 'Use shadcn/ui components (Button, Card, Dialog, Input, Sheet, Tabs). Pair with Tailwind.',
+    'radix-ui': 'Use Radix UI primitives for accessibility. Style with your preferred CSS solution.',
+    'headlessui': 'Use Headless UI primitives styled with Tailwind.',
+    'mui': 'Use MUI v5 components with a custom ThemeProvider matching the tokens below.',
+    'chakra-ui': 'Use Chakra UI components with a custom extendTheme({}) block.',
+    'mantine': 'Use Mantine UI components with MantineProvider theme overrides.',
+    'ant-design': 'Use Ant Design v5 with ConfigProvider theme tokens.',
+    'bootstrap': 'Use Bootstrap 5 utility classes. Customize via CSS variables.',
+    'heroui': 'Use HeroUI/NextUI components.',
+    'tailwind-ui': 'Use Tailwind UI patterns — no component library runtime, just Tailwind classes.',
+    'tailwindcss': 'Use plain Tailwind CSS without a component library.',
+    'vuetify': 'Use Vuetify 3 components with a custom theme object.',
+  };
+  return map[library.library] || null;
+}
+
+function sectionList(sectionRoles) {
+  if (!sectionRoles || !sectionRoles.sections) return [];
+  return sectionRoles.sections
+    .filter(s => s.role && s.role !== 'content' && s.role !== 'nav')
+    .map(s => {
+      const slot = s.slots?.heading ? ` — heading: "${s.slots.heading.slice(0, 80)}"` : '';
+      return `- ${s.role}${slot}`;
+    });
+}
+
+function voiceBlock(voice) {
+  if (!voice) return '';
+  const parts = [];
+  if (voice.tone) parts.push(`Tone: ${voice.tone}`);
+  if (voice.headingStyle) parts.push(`Headings: ${voice.headingStyle}`);
+  if (voice.pronounPosture) parts.push(`Pronoun posture: ${voice.pronounPosture}`);
+  if ((voice.ctaVerbs || []).length) parts.push(`CTA verbs: ${(voice.ctaVerbs || []).slice(0, 6).join(', ')}`);
+  return parts.join(' · ');
+}
+
+function coreBrief(design, opts = {}) {
+  const colors = colorList(design);
+  const fonts = typeFamilies(design);
+  const spacing = scaleSnippet(design.spacing?.scale);
+  const radii = radiiSnippet(design.borders);
+  const shadows = shadowSnippet(design.shadows);
+  const material = design.materialLanguage?.label || 'flat';
+  const intent = design.pageIntent?.type || 'landing';
+  const sections = sectionList(design.sectionRoles);
+  const voice = voiceBlock(design.voice);
+  const lib = librarySuggest(design.componentLibrary);
+  return {
+    colors, fonts, spacing, radii, shadows, material, intent, sections, voice, lib,
+  };
+}
+
+export function formatV0Prompt(design) {
+  const b = coreBrief(design);
+  return [
+    `Build a ${b.intent} page with this exact visual language.`,
+    '',
+    'COLORS:',
+    b.colors.map(c => `  ${c}`).join('\n'),
+    '',
+    `FONTS: ${b.fonts.join(', ') || 'system-ui'}`,
+    `SPACING: ${b.spacing}`,
+    `RADIUS: ${b.radii}`,
+    `SHADOWS: ${b.shadows}`,
+    `MATERIAL LANGUAGE: ${b.material}`,
+    b.voice ? `VOICE: ${b.voice}` : '',
+    b.lib ? `LIBRARY: ${b.lib}` : '',
+    '',
+    'SECTIONS (in order):',
+    (b.sections.length ? b.sections : ['- hero', '- features', '- cta', '- footer']).join('\n'),
+    '',
+    'Use Tailwind. Match these tokens exactly. Keep the material language consistent.',
+  ].filter(Boolean).join('\n');
+}
+
+export function formatLovablePrompt(design) {
+  const b = coreBrief(design);
+  return [
+    `Clone the design language of this ${b.intent} page and build a fresh equivalent.`,
+    '',
+    `Visual feel: ${b.material}. ${b.voice || ''}`,
+    `Primary palette: ${b.colors.slice(0, 5).join(', ')}.`,
+    `Typography: ${b.fonts.join(', ') || 'system-ui'}.`,
+    `Corner radius vocabulary: ${b.radii}.`,
+    `Shadow vocabulary: ${b.shadows}.`,
+    b.lib ? `Use: ${b.lib}` : '',
+    '',
+    'Page structure:',
+    (b.sections.length ? b.sections : ['- hero', '- features', '- social proof', '- cta', '- footer']).join('\n'),
+  ].filter(Boolean).join('\n');
+}
+
+export function formatCursorPrompt(design) {
+  const b = coreBrief(design);
+  return [
+    '# Design brief',
+    '',
+    `Page type: **${b.intent}**.`,
+    `Material language: **${b.material}**.`,
+    b.voice ? `Voice: ${b.voice}.` : '',
+    '',
+    '## Tokens',
+    '',
+    '```ts',
+    'export const tokens = {',
+    `  colors: [${b.colors.map(c => `'${c}'`).join(', ')}],`,
+    `  fonts: [${b.fonts.map(f => `'${f}'`).join(', ')}],`,
+    `  radii: [${(design.borders?.radii || []).slice(0, 6).map(r => `'${(r.value || r)}'`).join(', ')}],`,
+    `  shadows: [${(design.shadows?.values || []).slice(0, 3).map(s => `'${(s.value || s).replace(/'/g, "\\'")}'`).join(', ')}],`,
+    '};',
+    '```',
+    '',
+    '## Sections',
+    (b.sections.length ? b.sections : ['- hero', '- features', '- cta', '- footer']).join('\n'),
+    '',
+    b.lib ? `## Library\n\n${b.lib}` : '',
+  ].filter(Boolean).join('\n');
+}
+
+export function formatClaudeArtifactPrompt(design) {
+  const b = coreBrief(design);
+  return [
+    'Create a React artifact that reproduces this brand\'s design language.',
+    '',
+    `Page intent: ${b.intent}.`,
+    `Material language: ${b.material}.`,
+    b.voice ? `Voice: ${b.voice}.` : '',
+    b.lib ? `Library preference: ${b.lib}` : '',
+    '',
+    `Colors to use: ${b.colors.join(', ')}.`,
+    `Fonts: ${b.fonts.join(', ') || 'system-ui'}.`,
+    `Radius vocabulary: ${b.radii}.`,
+    '',
+    'Sections:',
+    (b.sections.length ? b.sections : ['- hero', '- features', '- cta', '- footer']).join('\n'),
+    '',
+    'Use Tailwind via CDN, lucide-react for icons, and keep the material language consistent across sections. Do not add extra decorative elements outside this vocabulary.',
+  ].filter(Boolean).join('\n');
+}
+
+export function formatRecipeCards(design) {
+  const clusters = design.componentClusters || [];
+  if (!clusters.length) return [];
+  const b = coreBrief(design);
+  return clusters.slice(0, 12).map((c, i) => {
+    const name = c.name || c.kind || `component-${i + 1}`;
+    const signals = [
+      b.lib,
+      `Radius: ${b.radii}`,
+      `Shadows: ${b.shadows}`,
+    ].filter(Boolean).join(' · ');
+    return {
+      name,
+      content: [
+        `# Recipe: ${name}`,
+        '',
+        `Build one ${name} component that matches this brand.`,
+        '',
+        `Palette: ${b.colors.slice(0, 6).join(', ')}`,
+        `Typography: ${b.fonts.join(', ') || 'system-ui'}`,
+        `Material: ${b.material}`,
+        signals ? `Signals: ${signals}` : '',
+        '',
+        '## Anatomy (detected)',
+        '```json',
+        JSON.stringify(c, null, 2).slice(0, 1500),
+        '```',
+      ].filter(Boolean).join('\n'),
+    };
+  });
+}
+
+export function buildPromptPack(design) {
+  return {
+    'v0.txt': formatV0Prompt(design),
+    'lovable.txt': formatLovablePrompt(design),
+    'cursor.md': formatCursorPrompt(design),
+    'claude-artifacts.md': formatClaudeArtifactPrompt(design),
+    recipes: formatRecipeCards(design),
+  };
+}

package/src/index.js

@@ -25,7 +25,16 @@ import { extractModernCss } from './extractors/modern-css.js';
 import { extractWideGamut } from './extractors/wide-gamut.js';
 import { extractTokenSources } from './extractors/token-sources.js';
 import { extractInteractionStates } from './extractors/interaction-states.js';
+import { extractMotion } from './extractors/motion.js';
+import { extractComponentAnatomy, formatAnatomyStubs } from './extractors/component-anatomy.js';
+import { extractVoice } from './extractors/voice.js';
+import { extractPageIntent } from './extractors/page-intent.js';
+import { extractSectionRoles } from './extractors/section-roles.js';
+import { extractComponentLibrary } from './extractors/component-library.js';
+import { extractMaterialLanguage } from './extractors/material-language.js';
+import { extractImageryStyle } from './extractors/imagery-style.js';
 import { formatDtcgTokens } from './formatters/dtcg-tokens.js';
+import { formatMotionTokens } from './formatters/motion-tokens.js';
 
 function safeExtract(fn, ...args) {
   try { return fn(...args); } catch { return null; }
@@ -73,6 +82,9 @@ export async function extractDesignLanguage(url, options = {}) {
     wideGamut: safeExtract(extractWideGamut, rawData.light.modernColors || []) || { oklch: { count: 0, samples: [] }, oklab: { count: 0, samples: [] }, colorMix: { count: 0, samples: [] }, lightDark: { count: 0, samples: [] }, displayP3: { count: 0, samples: [] }, rec2020: { count: 0, samples: [] }, totalCount: 0 },
     tokenSources: [],
     interactionStates: safeExtract(extractInteractionStates, rawData.interactState || rawData.light.interactState) || { scrollSettled: false, menusOpened: 0, hover: { sampled: 0, changed: 0, deltas: [] }, accordionsOpened: 0, modals: [] },
+    motion: safeExtract(extractMotion, styles, rawData.light.keyframes) || { durations: [], easings: [], springs: [], keyframes: [], scrollLinked: { present: false, signals: [] }, stats: {}, feel: 'unknown' },
+    componentAnatomy: safeExtract(extractComponentAnatomy, rawData.light.componentCandidates) || [],
+    voice: safeExtract(extractVoice, { componentCandidates: rawData.light.componentCandidates, sections: rawData.light.sections }) || { tone: 'neutral', ctaVerbs: [], buttonPatterns: [], sampleHeadings: [] },
     score: null,
   };
 
@@ -118,6 +130,17 @@ export async function extractDesignLanguage(url, options = {}) {
 
   design.tokenSources = safeExtract(extractTokenSources, design, styles) || [];
 
+  // v10: page intent, section roles, component library, material language,
+  // imagery style. All additive — no existing field is modified.
+  design.pageIntent = safeExtract(extractPageIntent, rawData, { url: rawData.url, title: rawData.title }) || { type: 'unknown', confidence: 0, signals: [] };
+  design.sectionRoles = safeExtract(extractSectionRoles, rawData.light?.sections || [], design.regions, design.pageIntent) || { sections: [], counts: {}, readingOrder: [] };
+  design.componentLibrary = safeExtract(extractComponentLibrary, rawData.light?.stack || {}) || { library: 'unknown', confidence: 0, evidence: [], alternates: [] };
+  design.materialLanguage = safeExtract(extractMaterialLanguage, design) || { label: 'flat', confidence: 0, signals: [], metrics: {} };
+  design.imageryStyle = safeExtract(extractImageryStyle, rawData.light?.images || []) || { label: 'none', confidence: 0, counts: {}, signals: [] };
+  // Stash raw crawler output so downstream orchestration (multipage, smart)
+  // can rebuild the digest without re-crawling.
+  design._raw = rawData;
+
   // Per-route token extraction (Tier 2 multi-page reconciliation).
   if (Array.isArray(rawData.routes) && rawData.routes.length > 0) {
     design.routes = rawData.routes.map(r => {
@@ -165,3 +188,20 @@ export { watchSite } from './watch.js';
 export { diffDarkMode } from './darkdiff.js';
 export { applyDesign } from './apply.js';
 export { loadConfig, mergeConfig } from './config.js';
+export { extractMotion } from './extractors/motion.js';
+export { formatMotionTokens } from './formatters/motion-tokens.js';
+export { extractComponentAnatomy, formatAnatomyStubs } from './extractors/component-anatomy.js';
+export { extractVoice } from './extractors/voice.js';
+export { lintTokens } from './lint.js';
+export { checkDrift, formatDriftMarkdown } from './drift.js';
+export { visualDiff, formatVisualDiffHtml } from './visual-diff.js';
+// v10
+export { extractPageIntent } from './extractors/page-intent.js';
+export { extractSectionRoles } from './extractors/section-roles.js';
+export { extractComponentLibrary } from './extractors/component-library.js';
+export { extractMaterialLanguage } from './extractors/material-language.js';
+export { extractImageryStyle } from './extractors/imagery-style.js';
+export { extractLogo } from './extractors/logo.js';
+export { refineWithSmart } from './classifiers/smart.js';
+export { crawlCanonicalPages, computeCrossPageConsistency, discoverCanonicalPages } from './multipage.js';
+export { buildPromptPack, formatV0Prompt, formatLovablePrompt, formatCursorPrompt, formatClaudeArtifactPrompt } from './formatters/prompt-pack.js';

package/src/lint.js

@@ -0,0 +1,198 @@
+// designlang lint — audit a local token file for the same issues scoring flags on live sites.
+// Supports DTCG, flat design-tokens.json, Tailwind config (partial), and CSS variable files.
+
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+
+function hexToRgb(hex) {
+  const m = hex.replace('#', '').match(/^([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i);
+  if (!m) return null;
+  return { r: parseInt(m[1], 16), g: parseInt(m[2], 16), b: parseInt(m[3], 16) };
+}
+
+function relLum({ r, g, b }) {
+  const f = v => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); };
+  return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+}
+
+function contrast(a, b) {
+  const la = relLum(a), lb = relLum(b);
+  const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+function flattenDtcg(obj, prefix = '', out = []) {
+  for (const [k, v] of Object.entries(obj || {})) {
+    if (k.startsWith('$')) continue;
+    if (v && typeof v === 'object') {
+      if ('$value' in v) {
+        out.push({ name: prefix ? `${prefix}.${k}` : k, value: v.$value, type: v.$type });
+      } else {
+        flattenDtcg(v, prefix ? `${prefix}.${k}` : k, out);
+      }
+    }
+  }
+  return out;
+}
+
+function loadTokens(file) {
+  const raw = readFileSync(file, 'utf8');
+  const ext = extname(file);
+  if (ext === '.json') {
+    const json = JSON.parse(raw);
+    const flat = flattenDtcg(json);
+    if (flat.length) return flat;
+    // flat fallback: { colors: { primary: '#000' }, ... }
+    const out = [];
+    for (const [group, entries] of Object.entries(json)) {
+      if (!entries || typeof entries !== 'object') continue;
+      for (const [k, v] of Object.entries(entries)) {
+        out.push({ name: `${group}.${k}`, value: String(v), type: group.replace(/s$/, '') });
+      }
+    }
+    return out;
+  }
+  if (ext === '.css') {
+    const out = [];
+    for (const m of raw.matchAll(/--([\w-]+):\s*([^;]+);/g)) {
+      out.push({ name: m[1], value: m[2].trim(), type: 'unknown' });
+    }
+    return out;
+  }
+  throw new Error(`Unsupported file type: ${ext}. Use .json or .css.`);
+}
+
+function isColor(t) { return t.type === 'color' || /^#[\da-f]{3,8}$/i.test(t.value) || /^rgb/i.test(t.value); }
+function toHex(v) {
+  const m = v.match(/^#([a-f\d]{3,8})$/i);
+  if (m) {
+    const h = m[1];
+    if (h.length === 3) return '#' + h.split('').map(c => c + c).join('');
+    return '#' + h.slice(0, 6);
+  }
+  const rgb = v.match(/rgba?\(\s*(\d+)\s*,?\s*(\d+)\s*,?\s*(\d+)/i);
+  if (rgb) return '#' + [rgb[1], rgb[2], rgb[3]].map(n => (+n).toString(16).padStart(2, '0')).join('');
+  return null;
+}
+
+function dedupeClose(hexes, threshold = 8) {
+  const near = [];
+  for (let i = 0; i < hexes.length; i++) {
+    for (let j = i + 1; j < hexes.length; j++) {
+      const a = hexToRgb(hexes[i].value), b = hexToRgb(hexes[j].value);
+      if (!a || !b) continue;
+      const dist = Math.sqrt((a.r - b.r) ** 2 + (a.g - b.g) ** 2 + (a.b - b.b) ** 2);
+      if (dist > 0 && dist < threshold) near.push({ a: hexes[i].name, b: hexes[j].name, distance: Math.round(dist) });
+    }
+  }
+  return near;
+}
+
+function parsePx(v) {
+  const m = String(v).match(/^(-?\d*\.?\d+)px$/);
+  return m ? parseFloat(m[1]) : null;
+}
+
+function checkScale(values, label) {
+  const nums = values.map(parsePx).filter(n => n !== null && n >= 0).sort((a, b) => a - b);
+  if (nums.length < 3) return null;
+  const gaps = [];
+  for (let i = 1; i < nums.length; i++) gaps.push(nums[i] - nums[i - 1]);
+  // Heuristic: ratio wildly inconsistent?
+  const ratios = [];
+  for (let i = 1; i < nums.length; i++) if (nums[i - 1] > 0) ratios.push(nums[i] / nums[i - 1]);
+  const avg = ratios.reduce((s, r) => s + r, 0) / (ratios.length || 1);
+  const variance = ratios.reduce((s, r) => s + (r - avg) ** 2, 0) / (ratios.length || 1);
+  return { label, count: nums.length, values: nums, avgRatio: +avg.toFixed(2), variance: +variance.toFixed(3) };
+}
+
+export function lintTokens(file) {
+  const tokens = loadTokens(file);
+  const findings = [];
+  const scorecard = {};
+
+  const colors = tokens.filter(isColor).map(t => ({ name: t.name, value: toHex(t.value) || t.value })).filter(t => /^#[\da-f]{6}$/i.test(t.value));
+  const neighbors = dedupeClose(colors);
+  if (neighbors.length) {
+    findings.push({
+      severity: 'warn',
+      rule: 'color-sprawl',
+      message: `${neighbors.length} near-duplicate color pair(s) within 8 RGB units`,
+      detail: neighbors.slice(0, 5),
+    });
+  }
+  scorecard.colorDiscipline = Math.max(0, 100 - neighbors.length * 8);
+
+  const spacing = tokens.filter(t => /spacing|space|gap|size/i.test(t.name));
+  const spaceCheck = checkScale(spacing.map(t => t.value), 'spacing');
+  if (spaceCheck && spaceCheck.variance > 0.25) {
+    findings.push({
+      severity: 'warn',
+      rule: 'spacing-scale-inconsistent',
+      message: `Spacing scale ratios vary (variance ${spaceCheck.variance}). Consider a consistent ratio (1.5x, 2x).`,
+      detail: spaceCheck,
+    });
+  }
+  scorecard.spacingSystem = spaceCheck ? Math.max(30, 100 - Math.round(spaceCheck.variance * 200)) : 50;
+
+  const radii = tokens.filter(t => /radius|radii/i.test(t.name));
+  if (radii.length > 8) {
+    findings.push({
+      severity: 'warn',
+      rule: 'radius-sprawl',
+      message: `${radii.length} radius tokens — consider collapsing to 4-6.`,
+    });
+  }
+  scorecard.borderRadii = Math.max(30, 100 - Math.max(0, radii.length - 6) * 10);
+
+  const shadows = tokens.filter(t => /shadow|elevation/i.test(t.name));
+  if (shadows.length > 10) {
+    findings.push({
+      severity: 'info',
+      rule: 'shadow-sprawl',
+      message: `${shadows.length} shadow tokens — rarely need more than 6 elevation levels.`,
+    });
+  }
+  scorecard.shadows = Math.max(30, 100 - Math.max(0, shadows.length - 6) * 8);
+
+  // Contrast: try to find text/bg pairs by name.
+  const palette = colors;
+  const bgs = palette.filter(c => /bg|background|surface/i.test(c.name));
+  const fgs = palette.filter(c => /fg|text|foreground|ink|label/i.test(c.name));
+  const contrastFails = [];
+  for (const fg of fgs) {
+    for (const bg of bgs) {
+      const fgRgb = hexToRgb(fg.value), bgRgb = hexToRgb(bg.value);
+      if (!fgRgb || !bgRgb) continue;
+      const c = contrast(fgRgb, bgRgb);
+      if (c < 4.5) contrastFails.push({ fg: fg.name, bg: bg.name, ratio: +c.toFixed(2) });
+    }
+  }
+  if (contrastFails.length) {
+    findings.push({
+      severity: 'error',
+      rule: 'contrast-wcag-aa',
+      message: `${contrastFails.length} fg/bg pair(s) fail WCAG AA (4.5:1)`,
+      detail: contrastFails.slice(0, 10),
+    });
+  }
+  scorecard.accessibility = contrastFails.length ? Math.max(20, 100 - contrastFails.length * 12) : 100;
+
+  const avg = Math.round(Object.values(scorecard).reduce((s, v) => s + v, 0) / Object.keys(scorecard).length);
+  const grade = avg >= 90 ? 'A' : avg >= 80 ? 'B' : avg >= 70 ? 'C' : avg >= 60 ? 'D' : 'F';
+
+  return {
+    file,
+    tokenCount: tokens.length,
+    score: avg,
+    grade,
+    scorecard,
+    findings,
+    stats: {
+      colors: colors.length,
+      spacing: spacing.length,
+      radii: radii.length,
+      shadows: shadows.length,
+    },
+  };
+}