designlang 12.4.0 → 12.8.0

package/src/fuse.js

@@ -0,0 +1,154 @@
+// designlang pair — fuse two extracted designs across configurable axes.
+//
+// Picks each dimension from one source or the other so designers can run
+// experiments like "Stripe colours × Linear typography × Vercel motion".
+// Input: two full design objects from extractDesignLanguage(), an axis
+// map, and an output URL/title for branding the fused result.
+//
+// We deep-clone source objects before merging so callers' originals stay
+// intact. The fused design is structurally identical to a normal
+// extraction so every downstream emitter (DTCG, Tailwind, shadcn,
+// Figma, brand-book, pack) works on it untouched.
+
+const AXES = ['colors', 'typography', 'spacing', 'shape', 'motion', 'voice', 'components'];
+
+const DEFAULT_AXES = {
+  colors:     'a',
+  spacing:    'a',
+  shape:      'a',
+  motion:     'a',
+  typography: 'b',
+  voice:      'b',
+  components: 'b',
+};
+
+function host(url) {
+  try { return new URL(url).hostname; } catch { return String(url || ''); }
+}
+
+function clone(x) {
+  return x == null ? x : JSON.parse(JSON.stringify(x));
+}
+
+// Normalise the user's --<axis>-from flags into a single { axis: 'a'|'b' }
+// map. Anything they don't specify falls through to DEFAULT_AXES, which
+// is calibrated for a clean "visual A × voice B" crossover.
+function resolveAxes(opts = {}) {
+  const out = { ...DEFAULT_AXES };
+  for (const axis of AXES) {
+    const flag = opts[`${axis}From`];
+    if (flag === 'a' || flag === 'A') out[axis] = 'a';
+    else if (flag === 'b' || flag === 'B') out[axis] = 'b';
+  }
+  return out;
+}
+
+/**
+ * Fuse two extracted designs along configurable axes.
+ *
+ * @param {object} a — design from extractDesignLanguage(urlA)
+ * @param {object} b — design from extractDesignLanguage(urlB)
+ * @param {object} opts
+ * @param {'a'|'b'} [opts.colorsFrom='a']
+ * @param {'a'|'b'} [opts.typographyFrom='b']
+ * @param {'a'|'b'} [opts.spacingFrom='a']
+ * @param {'a'|'b'} [opts.shapeFrom='a']
+ * @param {'a'|'b'} [opts.motionFrom='a']
+ * @param {'a'|'b'} [opts.voiceFrom='b']
+ * @param {'a'|'b'} [opts.componentsFrom='b']
+ * @returns {object} { design, summary }
+ */
+export function fuseDesigns(a, b, opts = {}) {
+  if (!a || !b) throw new Error('fuseDesigns: both designs are required');
+  const axes = resolveAxes(opts);
+  const pick = (axis, sliceA, sliceB) => clone(axes[axis] === 'a' ? sliceA : sliceB);
+  const src = (axis) => axes[axis] === 'a' ? a : b;
+
+  // Start from a deep clone of A so meta-fields (e.g. raw crawler output)
+  // have a sensible default. Downstream emitters lean heavily on .meta.url
+  // for filenames + titles, so we synthesise a pair-specific URL.
+  const fused = clone(a);
+
+  // Colours — every sub-field in one block (primary, secondary, accent,
+  // neutrals, backgrounds, text, gradients, all). Mixing primary from
+  // one site and neutrals from another tends to produce off-brand greys,
+  // so we keep the whole palette together.
+  fused.colors = pick('colors', a.colors, b.colors);
+
+  // Typography — same logic. Families, scale, weights, headings, body
+  // travel as one unit because the type system is tightly coupled.
+  fused.typography = pick('typography', a.typography, b.typography);
+  // Pull related signals along with the type pick so the brand book
+  // renders coherently (specimen lines lean on voice.sampleHeadings).
+  if (axes.voice === axes.typography) {
+    // already aligned; keep voice-from picked below
+  }
+
+  // Spacing.
+  fused.spacing = pick('spacing', a.spacing, b.spacing);
+  // Layout often co-varies with spacing — move it together.
+  fused.layout = pick('spacing', a.layout, b.layout);
+
+  // Shape — radii + shadows + borders.
+  fused.borders = pick('shape', a.borders, b.borders);
+  fused.shadows = pick('shape', a.shadows, b.shadows);
+
+  // Motion.
+  fused.motion = pick('motion', a.motion, b.motion);
+  fused.animations = pick('motion', a.animations, b.animations);
+
+  // Voice.
+  fused.voice = pick('voice', a.voice, b.voice);
+
+  // Components — anatomy, clusters, library detection.
+  fused.componentAnatomy = pick('components', a.componentAnatomy, b.componentAnatomy);
+  fused.componentClusters = pick('components', a.componentClusters, b.componentClusters);
+  fused.componentLibrary = pick('components', a.componentLibrary, b.componentLibrary);
+  fused.components = pick('components', a.components, b.components);
+
+  // Material language and imagery style track colour by default — they
+  // describe the *visual* feel.
+  fused.materialLanguage = pick('colors', a.materialLanguage, b.materialLanguage);
+  fused.imageryStyle = pick('colors', a.imageryStyle, b.imageryStyle);
+
+  // CSS variables tend to mirror colour + typography. We keep the
+  // variables from whichever source contributed colour, since colour
+  // tokens are the dominant variable family.
+  fused.variables = pick('colors', a.variables, b.variables);
+
+  // Score, accessibility, css-health are *measurements* of the source
+  // sites — they don't apply to the fused design. Strip them so
+  // downstream consumers don't surface stale numbers.
+  fused.score = null;
+  fused.accessibility = src('colors').accessibility ? clone(src('colors').accessibility) : null;
+  fused.cssHealth = null;
+
+  // Synthesise meta. The pair URL is a virtual identifier so emitters
+  // produce non-colliding filenames (e.g. "stripe-x-linear").
+  const hostA = host(a.meta?.url);
+  const hostB = host(b.meta?.url);
+  fused.meta = {
+    ...(a.meta || {}),
+    url: `pair://${hostA}-x-${hostB}`,
+    title: `${hostA} × ${hostB}`,
+    pairedFrom: { a: a.meta?.url || hostA, b: b.meta?.url || hostB },
+    timestamp: new Date().toISOString(),
+    elementCount: (a.meta?.elementCount || 0) + (b.meta?.elementCount || 0),
+    pagesAnalyzed: 1,
+    fusedAxes: axes,
+  };
+  fused.fusedAxes = axes;
+
+  // Drop the raw crawler output — it belongs to a single page and
+  // confuses any consumer that tries to re-derive things from it.
+  delete fused._raw;
+
+  const summary = {
+    a: { url: a.meta?.url, host: hostA },
+    b: { url: b.meta?.url, host: hostB },
+    axes,
+  };
+  return { design: fused, summary };
+}
+
+export { AXES, DEFAULT_AXES };

package/src/recolor.js

@@ -0,0 +1,199 @@
+// designlang theme-swap — recolour an extracted design around a new brand
+// primary while preserving perceptual structure (lightness + chroma stay
+// close, only hue shifts). Operates on the design object produced by
+// extractDesignLanguage so every downstream emitter (DTCG, Tailwind,
+// shadcn, Figma vars, CSS vars) inherits the change for free.
+
+import { hexToOklch, oklchToHex } from './utils/color-gamut.js';
+
+// Below this chroma we treat the colour as a neutral and leave it alone.
+// Real-world brand palettes have chroma in the 0.05–0.30 range; pure
+// greys sit under ~0.02. 0.04 is a defensible split that keeps body text,
+// surfaces, and rule lines untouched while moving accents / brand inks.
+const NEUTRAL_CHROMA_MAX = 0.04;
+
+function normaliseHex(s) {
+  if (typeof s !== 'string') return null;
+  const t = s.trim().toLowerCase();
+  if (!t) return null;
+  const m = t.match(/^#?([0-9a-f]{3}|[0-9a-f]{6})$/);
+  if (!m) return null;
+  let body = m[1];
+  if (body.length === 3) body = body.split('').map(c => c + c).join('');
+  return '#' + body;
+}
+
+function hueDelta(h0, h1) {
+  // Shortest signed distance between two hues (-180..180).
+  let d = h1 - h0;
+  while (d > 180) d -= 360;
+  while (d < -180) d += 360;
+  return d;
+}
+
+function rotateHue(h, delta) {
+  let r = h + delta;
+  while (r < 0) r += 360;
+  while (r >= 360) r -= 360;
+  return r;
+}
+
+// Decide whether to recolour a given hex. We always preserve neutrals so
+// body text, surfaces, and rule lines look the same. We optionally allow
+// the caller to pin the lightness target (for the *primary* swap itself,
+// where the user's `--primary` value should land exactly).
+function recolourHex(hex, { hueShift, neutralKeep = true, target = null }) {
+  const oklch = hexToOklch(hex);
+  if (!oklch) return hex;
+  if (target) {
+    // Used for the primary itself — copy the target's L, C, h verbatim
+    // so the user gets exactly the colour they asked for, not a rotation.
+    return oklchToHex(target);
+  }
+  if (neutralKeep && oklch.C < NEUTRAL_CHROMA_MAX) return hex;
+  return oklchToHex({ L: oklch.L, C: oklch.C, h: rotateHue(oklch.h, hueShift) });
+}
+
+// Detect the "primary" anchor we'll rotate the rest of the palette around.
+// Order of preference:
+//   1. design.colors.primary.hex (extractor's classification)
+//   2. the most-used non-neutral colour in design.colors.all
+//   3. fall back to the first non-neutral entry
+function detectPrimary(design) {
+  const fromExtractor = design?.colors?.primary?.hex;
+  if (fromExtractor) {
+    const norm = normaliseHex(fromExtractor);
+    if (norm) return norm;
+  }
+  const all = (design?.colors?.all || []).filter(c => c?.hex && hexToOklch(c.hex));
+  // Most-used coloured (non-neutral) value.
+  const coloured = all
+    .filter(c => {
+      const o = hexToOklch(c.hex);
+      return o && o.C >= NEUTRAL_CHROMA_MAX;
+    })
+    .sort((a, b) => (b.count || 0) - (a.count || 0));
+  if (coloured.length) return normaliseHex(coloured[0].hex);
+  if (all.length) return normaliseHex(all[0].hex);
+  return null;
+}
+
+/**
+ * Recolour an extracted design around a new brand primary.
+ *
+ * @param {object} design — the full design returned by extractDesignLanguage()
+ * @param {object} opts
+ * @param {string} opts.primary — target primary colour as hex (#rrggbb)
+ * @param {boolean} [opts.preserveLightness=true]
+ *   When true, the rotation only changes hue (default). When false, the
+ *   target's lightness/chroma are also propagated to the rest of the
+ *   palette — leaves a heavier brand stamp, often too aggressive.
+ * @param {string|null} [opts.fromPrimary=null]
+ *   Override the auto-detected source primary. Useful when the extractor
+ *   misclassifies (e.g. a neutral got promoted by usage count).
+ * @returns {object} { design, summary } — recoloured design plus a small
+ *   summary of what changed (used by the formatter for the diff view).
+ */
+export function recolorDesign(design, opts = {}) {
+  if (!design) throw new Error('recolorDesign: design is required');
+  const targetHex = normaliseHex(opts.primary);
+  if (!targetHex) {
+    throw new Error(`recolorDesign: invalid --primary "${opts.primary}". Expected hex like "#ff4800".`);
+  }
+
+  const sourceHex = normaliseHex(opts.fromPrimary) || detectPrimary(design);
+  if (!sourceHex) {
+    throw new Error('recolorDesign: could not detect a source primary in the design (no coloured tokens found)');
+  }
+
+  const sourceOklch = hexToOklch(sourceHex);
+  const targetOklch = hexToOklch(targetHex);
+  if (!sourceOklch || !targetOklch) {
+    throw new Error('recolorDesign: failed to parse source/target hex into OKLCH');
+  }
+  const hueShift = hueDelta(sourceOklch.h, targetOklch.h);
+
+  // Walk the design and rebuild a recoloured copy. We mutate a deep clone
+  // so the caller's original stays intact.
+  const out = JSON.parse(JSON.stringify(design));
+  const changes = [];
+  const seen = new Set();
+  function swap(hex, opts2 = {}) {
+    const norm = normaliseHex(hex);
+    if (!norm) return hex;
+    const next = recolourHex(norm, { hueShift, ...opts2 });
+    if (next !== norm && !seen.has(norm + '→' + next)) {
+      seen.add(norm + '→' + next);
+      changes.push({ from: norm, to: next });
+    }
+    return next;
+  }
+
+  // 1) The primary itself — pin to the user's target hex.
+  if (out.colors?.primary?.hex) {
+    out.colors.primary.hex = swap(out.colors.primary.hex, { target: targetOklch });
+  }
+  // 2) Secondary / accent — rotate by the hue delta.
+  for (const k of ['secondary', 'accent']) {
+    if (out.colors?.[k]?.hex) out.colors[k].hex = swap(out.colors[k].hex);
+  }
+  // 3) Every entry in colors.all (the canonical palette).
+  if (Array.isArray(out.colors?.all)) {
+    out.colors.all = out.colors.all.map(c => {
+      if (!c?.hex) return c;
+      // Pin the source primary slot to the target exactly so it shows up
+      // verbatim in shadcn/Tailwind output.
+      const isSourcePrimary = normaliseHex(c.hex) === sourceHex;
+      return { ...c, hex: swap(c.hex, isSourcePrimary ? { target: targetOklch } : {}) };
+    });
+  }
+  // 4) Neutrals — explicitly *don't* rotate. Surfaces, text, rule lines
+  //    should stay readable. (We rely on neutralKeep inside swap().)
+  if (Array.isArray(out.colors?.neutrals)) {
+    out.colors.neutrals = out.colors.neutrals.map(c => c?.hex ? { ...c, hex: swap(c.hex) } : c);
+  }
+  // 5) Backgrounds + text — same neutral-preserving logic.
+  if (Array.isArray(out.colors?.backgrounds)) {
+    out.colors.backgrounds = out.colors.backgrounds.map(swap);
+  }
+  if (Array.isArray(out.colors?.text)) {
+    out.colors.text = out.colors.text.map(swap);
+  }
+  // 6) Gradients — rebuild every stop.
+  if (Array.isArray(out.colors?.gradients)) {
+    out.colors.gradients = out.colors.gradients.map(g => {
+      if (typeof g !== 'string') return g;
+      return g.replace(/#[0-9a-fA-F]{3,6}\b/g, swap);
+    });
+  }
+  if (out.gradients?.gradients && Array.isArray(out.gradients.gradients)) {
+    out.gradients.gradients = out.gradients.gradients.map(g => {
+      if (typeof g === 'string') return g.replace(/#[0-9a-fA-F]{3,6}\b/g, swap);
+      if (g?.raw) return { ...g, raw: g.raw.replace(/#[0-9a-fA-F]{3,6}\b/g, swap) };
+      return g;
+    });
+  }
+  // 7) CSS variables — rotate any value that looks like a hex.
+  if (out.variables && typeof out.variables === 'object') {
+    for (const cat of Object.keys(out.variables)) {
+      const obj = out.variables[cat];
+      if (obj && typeof obj === 'object') {
+        for (const k of Object.keys(obj)) {
+          if (typeof obj[k] === 'string') obj[k] = obj[k].replace(/#[0-9a-fA-F]{3,6}\b/g, swap);
+        }
+      }
+    }
+  }
+
+  out.meta = {
+    ...(out.meta || {}),
+    themeSwap: {
+      from: sourceHex,
+      to: targetHex,
+      hueShift: Math.round(hueShift * 100) / 100,
+      changedColors: changes.length,
+    },
+  };
+
+  return { design: out, summary: { from: sourceHex, to: targetHex, hueShift, changes } };
+}

package/src/utils/color-gamut.js

@@ -80,3 +80,67 @@ export function oklchLikeToHex(raw) {
     : oklabToSrgb(parsed.L, parsed.a, parsed.b);
   return rgbToHex(r, g, b);
 }
+
+// ── Inverse direction (sRGB → OKLab → OKLCH) ───────────────────
+// Forward Björn Ottosson formulas. Used by the recolor pipeline so we can
+// hue-rotate brand palettes while preserving perceptual lightness.
+
+function srgbToLinear(x) {
+  if (x <= 0.04045) return x / 12.92;
+  return Math.pow((x + 0.055) / 1.055, 2.4);
+}
+
+export function srgbToOklab(r, g, b) {
+  // sRGB inputs in 0..1, gamma-encoded.
+  const rl = srgbToLinear(r);
+  const gl = srgbToLinear(g);
+  const bl = srgbToLinear(b);
+
+  const l = 0.4122214708 * rl + 0.5363325363 * gl + 0.0514459929 * bl;
+  const m = 0.2119034982 * rl + 0.6806995451 * gl + 0.1073969566 * bl;
+  const s = 0.0883024619 * rl + 0.2817188376 * gl + 0.6299787005 * bl;
+
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+
+  return [
+    0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_,
+    1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_,
+    0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_,
+  ];
+}
+
+export function srgbToOklch(r, g, b) {
+  const [L, a, bx] = srgbToOklab(r, g, b);
+  const C = Math.sqrt(a * a + bx * bx);
+  let h = Math.atan2(bx, a) * 180 / Math.PI;
+  if (h < 0) h += 360;
+  return { L, C, h };
+}
+
+// Hex string → { L, C, h } in OKLCH. Returns null on parse failure.
+export function hexToOklch(hex) {
+  if (typeof hex !== 'string') return null;
+  const m = hex.replace(/^#/, '').match(/^([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (!m) return null;
+  let s = m[1];
+  if (s.length === 3) s = s.split('').map(c => c + c).join('');
+  const r = parseInt(s.slice(0, 2), 16) / 255;
+  const g = parseInt(s.slice(2, 4), 16) / 255;
+  const b = parseInt(s.slice(4, 6), 16) / 255;
+  return srgbToOklch(r, g, b);
+}
+
+// { L, C, h } → hex string. Clamps to sRGB gamut by reducing chroma if the
+// colour falls outside displayable range.
+export function oklchToHex({ L, C, h }) {
+  // Try the requested chroma, then back off if any channel goes out of range.
+  for (let factor = 1; factor >= 0; factor -= 0.05) {
+    const [r, g, b] = oklchToSrgb(L, C * factor, h);
+    if (r >= -1e-4 && r <= 1.0001 && g >= -1e-4 && g <= 1.0001 && b >= -1e-4 && b <= 1.0001) {
+      return rgbToHex(r, g, b);
+    }
+  }
+  return rgbToHex(...oklchToSrgb(L, 0, h));
+}