viberoom 0.7.0 → 0.9.0

package/ui/tokens.js

@@ -15,6 +15,7 @@
     const at = (u, v) => Math.round(u + (v - u) * t);
     return `#${[at(x, i), at(y, j), at(z, k)].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
   };
+  const NO_SHADOW = "0 0 0 0 transparent";
 
   const pop = {
     primary: "#5b5bf0",
@@ -111,7 +112,7 @@
     orchid: "#2a1a3a", orchidInk: "#c79bff", orchidMid: "#b58cf0",
     periwinkle: "#233126", periwinkleDeep: "#2f4234",
     deep: "#050705", deepGutter: "#0a0d0b", deepInk: "#d7e3d9", deepMuted: "#5b6f61", deepHead: "#c3d1c6", deepMeta: "#7c9282",
-    lavGrey: "#3a4a3e", lilac: "#7ee0ff", seafoam: "#3ddc84", azure: "#5ab0ff", salmon: "#ff8578", magenta: "#ff7ab8",
+    lavGrey: "#5f7a67", lilac: "#7ee0ff", seafoam: "#3ddc84", azure: "#5ab0ff", salmon: "#ff8578", magenta: "#ff7ab8",
   };
 
   const classicDark = {
@@ -133,7 +134,7 @@
     orchid: "#2e2140", orchidInk: "#c9a3ff", orchidMid: "#b48cf0",
     periwinkle: "#34365c", periwinkleDeep: "#40437a",
     deep: "#0f1020", deepGutter: "#0b0c1a", deepInk: "#f4f2ff", deepMuted: "#7c78ad", deepHead: "#e8e6ff", deepMeta: "#a9a5d8",
-    lavGrey: "#4a4b70", lilac: "#b9a7ff", seafoam: "#8fe3bd", azure: "#9cd2ff", salmon: "#ff9f9f", magenta: "#f2b8ff",
+    lavGrey: "#7c78ad", lilac: "#b9a7ff", seafoam: "#8fe3bd", azure: "#9cd2ff", salmon: "#ff9f9f", magenta: "#f2b8ff",
   };
 
   const clay = {
@@ -177,7 +178,7 @@
     orchid: "#e8e2ec", orchidInk: "#6b4f8c", orchidMid: "#8a6fa8",
     periwinkle: "#d9dbe6", periwinkleDeep: "#b9bdd0",
     deep: "#e9e3d6", deepGutter: "#e1dacb", deepInk: "#2b2a27", deepMuted: "#7a7468", deepHead: "#3a3833", deepMeta: "#6f6b62",
-    lavGrey: "#c9c2b3", lilac: "#5b4a9a", seafoam: "#1f6e5a", azure: "#2a5d8f", salmon: "#a3472f", magenta: "#8a3f7a",
+    lavGrey: "#7a7468", lilac: "#5b4a9a", seafoam: "#1f6e5a", azure: "#2a5d8f", salmon: "#a3472f", magenta: "#8a3f7a",
   };
 
   const plush = {
@@ -271,6 +272,7 @@
       shadow: edge,
       bevel: "none",
       shadowRoom: "0px",
+      bevelPressed: "none",
     };
   };
 
@@ -284,8 +286,40 @@
     sbThumbHover: alpha(p.primary, 0.45),
   });
 
+  const fonts = {
+    text: {
+      nunito: { label: "Nunito (default)", stack: '"Nunito", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      inter: { label: "Inter", stack: '"Inter", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      "noto-sans": { label: "Noto Sans", stack: '"Noto Sans", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      "open-sans": { label: "Open Sans", stack: '"Open Sans", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      "source-sans-3": { label: "Source Sans 3", stack: '"Source Sans 3", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      "ibm-plex-sans": { label: "IBM Plex Sans", stack: '"IBM Plex Sans", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      manrope: { label: "Manrope", stack: '"Manrope", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      rubik: { label: "Rubik", stack: '"Rubik", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      montserrat: { label: "Montserrat", stack: '"Montserrat", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      "golos-text": { label: "Golos Text", stack: '"Golos Text", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      "exo-2": { label: "Exo 2", stack: '"Exo 2", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      comfortaa: { label: "Comfortaa", stack: '"Comfortaa", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      "ubuntu-sans": { label: "Ubuntu Sans", stack: '"Ubuntu Sans", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif' },
+      arial: { label: "Arial / Helvetica (system)", stack: 'Arial, Helvetica, "Liberation Sans", sans-serif' },
+      system: { label: "System UI font", stack: 'system-ui, -apple-system, "Segoe UI", Roboto, Cantarell, sans-serif' },
+    },
+    mono: {
+      "jetbrains-mono": { label: "JetBrains Mono (default)", stack: '"JetBrains Mono", ui-monospace, Consolas, Menlo, "DejaVu Sans Mono", monospace' },
+      "fira-code": { label: "Fira Code", stack: '"Fira Code", ui-monospace, Consolas, Menlo, "DejaVu Sans Mono", monospace' },
+      "source-code-pro": { label: "Source Code Pro", stack: '"Source Code Pro", ui-monospace, Consolas, Menlo, "DejaVu Sans Mono", monospace' },
+      "ibm-plex-mono": { label: "IBM Plex Mono", stack: '"IBM Plex Mono", ui-monospace, Consolas, Menlo, "DejaVu Sans Mono", monospace' },
+      "pt-mono": { label: "PT Mono", stack: '"PT Mono", ui-monospace, Consolas, Menlo, "DejaVu Sans Mono", monospace' },
+      "victor-mono": { label: "Victor Mono", stack: '"Victor Mono", ui-monospace, Consolas, Menlo, "DejaVu Sans Mono", monospace' },
+      "anonymous-pro": { label: "Anonymous Pro", stack: '"Anonymous Pro", ui-monospace, Consolas, Menlo, "DejaVu Sans Mono", monospace' },
+      "cascadia-code": { label: "Cascadia Code", stack: '"Cascadia Code", ui-monospace, Consolas, Menlo, "DejaVu Sans Mono", monospace' },
+      system: { label: "System monospace", stack: 'ui-monospace, Consolas, Menlo, "DejaVu Sans Mono", "Courier New", monospace' },
+    },
+  };
+
   const shape = {
     rScale: "1",
+    rCtlMin: "0px",
     rXs: "calc(8px * var(--r-scale))", rSm: "calc(12px * var(--r-scale))", rMd: "calc(14px * var(--r-scale))", rLg: "calc(18px * var(--r-scale))", rXl: "calc(18px * var(--r-scale))", rPill: "calc(99px * var(--r-scale))",
   };
   const type = {
@@ -306,7 +340,9 @@
     easePop: "cubic-bezier(0.34, 1.56, 0.64, 1)",
   };
 
-  const elementsOf = (p) => ({
+  const elementsOf = (p) => {
+    const dangerSolid = `0 8px 18px -8px ${alpha(p.roseInk, 0.8)}`;
+    return {
     page: {
       bg: p.bg,
       ink: p.ink,
@@ -326,6 +362,7 @@
       hoverInk: p.primary,
       onPrimary: p.white,
       secondaryBg: p.white,
+      secondaryHoverBg: p.white,
       softBg: p.lav,
       softHoverBg: p.lav2,
       ghostInk: p.muted,
@@ -335,14 +372,14 @@
       dangerHoverBg: p.rose2,
       dangerSolidInk: p.white,
       dangerSolidHoverBg: p.roseDark,
-      dangerSolidShadow: `0 8px 18px -8px ${alpha(p.roseInk, 0.8)}`,
+      dangerSolidShadow: dangerSolid,
       spinnerTrack: alpha(p.white, 0.5),
       spinnerHead: p.white,
       spinnerTrackQuiet: p.lav2,
       spinnerHeadQuiet: p.primary,
       disabledOpacity: "0.45",
-      darkBg: alpha(p.white, 0.12),
-      darkInk: p.white,
+      darkBg: alpha(p.deepInk, 0.12),
+      darkInk: p.deepInk,
       darkHoverBg: p.primary,
       warnInk: p.warmInk,
       warnHoverBg: p.warm,
@@ -356,6 +393,23 @@
       paperBg: p.white,
       paperInk: p.ink3,
       paperHoverBg: p.soft,
+      border: "0",
+      case: "none",
+      tracking: "0px",
+      linkUnderline: "none",
+      ghostBg: "transparent",
+      shadow: "none",
+      hoverShadow: "none",
+      hoverLift: "0px",
+      activeShadow: "none",
+      primaryActiveShadow: "var(--shadow-primary)",
+      primaryHoverFilter: "brightness(1.05)",
+      secondaryHoverShadow: "var(--shadow-tile)",
+      secondaryActiveShadow: "var(--shadow-tile)",
+      dangerSolidHoverShadow: dangerSolid,
+      dangerSolidActiveShadow: dangerSolid,
+      okShadow: "none",
+      warnShadow: "none",
       h: "42px",
       hSm: "34px",
       hXs: "24px",
@@ -384,6 +438,14 @@
       inlineInk: p.ink3,
       inlineOnBg: alpha(p.primary, 0.1),
       inlineOnInk: p.primary,
+      ghostBg: "transparent",
+      shadow: "none",
+      hoverShadow: "none",
+      hoverLift: "0px",
+      activeShadow: "none",
+      primaryShadow: "var(--shadow-primary)",
+      primaryHoverShadow: "var(--shadow-primary)",
+      primaryActiveShadow: "var(--shadow-primary)",
     },
     badge: {
       bg: p.lav,
@@ -393,23 +455,37 @@
       mutedBg: p.softer,
       mutedInk: p.muted,
       outlineBorder: p.lav2,
+      outlineW: "2px",
       outlineInk: p.muted,
       fsXs: "calc(10px * var(--fs-scale))",
+      fill: "100%",
+      border: "0",
+      case: "none",
+      tracking: "0px",
+      shadow: "none",
     },
     chip: {
       bg: p.lav,
       ink: p.primary,
       hoverBg: p.lav2,
+      fill: "100%",
+      border: "0",
+      shadow: "none",
+      hoverShadow: "none",
+      hoverLift: "0px",
+      activeShadow: "none",
+      activeDrop: "0px",
     },
     fileCard: {
       bg: p.deep,
       ink: p.deepInk,
-      headBg: alpha(p.white, 0.06),
+      headBg: alpha(p.deepInk, 0.06),
       headInk: p.deepHead,
       headMeta: p.deepMeta,
       noteInk: p.roseInk,
-      imageBodyBg: alpha(p.white, 0.04),
+      imageBodyBg: alpha(p.deepInk, 0.04),
       imageBg: p.white,
+      shadow: "var(--edge)",
     },
     toolCall: {
       readyBg: p.mint,
@@ -435,6 +511,7 @@
       hoverInk: p.primary,
       failedInk: p.roseInk,
       fs: "calc(11px * var(--fs-scale))",
+      shadow: "none",
     },
     askCard: {
       bg: p.warm,
@@ -445,6 +522,7 @@
       kindFs: "calc(11px * var(--fs-scale))",
       inputFs: "calc(11px * var(--fs-scale))",
       outcomeFs: "calc(12px * var(--fs-scale))",
+      shadow: "none",
     },
     replyNote: {
       ink: p.muted,
@@ -461,6 +539,7 @@
       border: p.lav2,
       hoverBorder: p.periwinkleDeep,
       onBorder: p.primary,
+      shadow: "none",
     },
     choice: {
       bg: p.soft,
@@ -470,6 +549,13 @@
       onBorder: p.primary,
       quietInk: p.muted,
       h: "32px",
+      border: "transparent",
+      shadow: "none",
+      hoverShadow: "none",
+      hoverLift: "0px",
+      activeShadow: "none",
+      activeDrop: "0px",
+      onShadow: "none",
     },
     control: {
       knob: p.white,
@@ -487,6 +573,10 @@
       gradFrom: "72% 66%",
       gradTo: "68% 52%",
       emoji: "70% 93%",
+      shadow: "none",
+      radius: "calc(14px * var(--r-scale))",
+      radiusLg: "calc(16px * var(--r-scale))",
+      radiusRail: "calc(13px * var(--r-scale))",
     },
     pop: {
       bg: p.white,
@@ -573,21 +663,21 @@
       gutterInk: p.deepMuted,
       lineMarkInk: p.honey,
       lineMarkBg: alpha(p.honey, 0.16),
-      headBg: alpha(p.white, 0.06),
+      headBg: alpha(p.deepInk, 0.06),
       headInk: p.deepHead,
       headMeta: p.deepMeta,
-      headBtnBg: alpha(p.white, 0.12),
-      headBtnInk: p.white,
-      bodyBg: alpha(p.white, 0.04),
+      headBtnBg: alpha(p.deepInk, 0.12),
+      headBtnInk: p.deepInk,
+      bodyBg: alpha(p.deepInk, 0.04),
       sbTrack: alpha(p.black, 0.25),
-      sbThumb: alpha(p.white, 0.3),
-      sbThumbHover: alpha(p.white, 0.5),
-      sbFirefox: alpha(p.white, 0.35),
+      sbThumb: alpha(p.deepInk, 0.3),
+      sbThumbHover: alpha(p.deepInk, 0.5),
+      sbFirefox: alpha(p.deepInk, 0.35),
       findHitBg: p.honey,
       findHitInk: p.deep,
     },
     syntax: {
-      comment: p.muted,
+      comment: p.deepMuted,
       punctuation: p.lavGrey,
       keyword: p.lilac,
       string: p.seafoam,
@@ -624,6 +714,8 @@
       avatarDefault: p.primary,
       avatarGloss: p.white,
       avatarLabelInk: p.white,
+      shadow: NO_SHADOW,
+      cardShadow: "var(--shadow-pop)",
     },
     logoTile: {
       bg: p.white,
@@ -636,6 +728,11 @@
       sm: "30px",
       md: "36px",
       lg: "40px",
+      shadow: "var(--shadow-tile)",
+      radius: "calc(12px * var(--r-scale))",
+      radiusSm: "calc(10px * var(--r-scale))",
+      radiusLg: "calc(13px * var(--r-scale))",
+      radiusBadge: "calc(6px * var(--r-scale))",
     },
     unseenLine: {
       ink: p.pink,
@@ -643,6 +740,10 @@
       line: `url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='8' viewBox='0 0 16 8'><path d='M0 4 Q4 0 8 4 T16 4' fill='none' stroke='${p.pink.replace("#", "%23")}' stroke-width='1.6'/></svg>") repeat-x center / 16px 8px`,
       lineH: "8px",
       lineOpacity: "0.55",
+      labelBorder: "0",
+      labelCase: "none",
+      labelTracking: "0px",
+      labelShadow: "none",
     },
     numberField: {
       stepW: "22px",
@@ -661,12 +762,14 @@
     rowButton: {
       size: "24px",
       icon: "14px",
-      radius: "8px",
+      radius: "calc(8px * var(--r-scale))",
       bg: p.softer,
       ink: p.muted,
       hoverBg: p.primary,
       hoverInk: p.white,
       disabledOpacity: "0.4",
+      shadow: "none",
+      activeShadow: "none",
     },
     hubRow: {
       ink: p.muted,
@@ -676,6 +779,9 @@
       actionInk: p.mintInk,
       actionHoverBg: p.mint2,
       faceSize: "18px",
+      prefix: "none",
+      prefixGap: "0px",
+      actionShadow: "var(--edge)",
     },
     hero: {
       ink: p.white,
@@ -699,6 +805,13 @@
     feature: {
       emojiBg: alpha(p.white, 0.8),
       peachBg: p.peach2,
+      shadow: "var(--edge)",
+    },
+    composer: {
+      shadow: "none",
+      bg: "transparent",
+      radius: "0px",
+      padX: "0px",
     },
     step: {
       bg: p.white,
@@ -711,7 +824,8 @@
     browser: {
       themeColor: p.iris,
     },
-  });
+    };
+  };
 
   const popNodes = [
     { fill: "#e4e6fb", stroke: "#5b5bf0" },
@@ -749,6 +863,8 @@
       type: { ...type, ...(wants.type || {}) },
       motion: { ...motion, ...(wants.motion || {}) },
       elements,
+      wants,
+      custom: false,
     };
   };
 
@@ -772,48 +888,72 @@
         code: { headBg: alpha(p.ink, 0.04), headBtnBg: alpha(p.ink, 0.08), headBtnInk: p.ink, bodyBg: alpha(p.ink, 0.02), sbTrack: alpha(p.ink, 0.06), sbThumb: alpha(p.ink, 0.3) },
         bubble: { mineBg: `linear-gradient(135deg, ${p.primaryLight}, ${p.primaryDeep})`, shadow: `0 1px 2px ${alpha(p.ink, 0.06)}`, mineShadow: "none" },
         logoTile: { bg: p.white, ink: p.ink },
+        btn: { darkHoverBg: p.lav2 },
       }),
     }),
-    plush: look("plush", "3D clayful", "light", plush, {
-      shape: { rScale: "1.6" },
-      canvas: (p) => ({
-        gradCanvas: `radial-gradient(720px 480px at 100% 100%, ${alpha(p.ember, 0.14)}, transparent 70%), radial-gradient(640px 420px at 0% 0%, ${alpha(p.primaryLight, 0.16)}, transparent 70%), linear-gradient(165deg, ${p.canvasTop} 0%, ${p.canvasMid} 55%, ${p.canvasBottom} 100%)`,
-        canvasPattern: "none",
-        canvasPatternSize: "0 0",
-      }),
-      elevation: (() => {
-        const p = plush;
-        const warm = (a) => alpha(p.shadowInk, a);
-        const light = (a) => alpha(p.white, a);
-        const dark = (a) => alpha(p.black, a);
-        const puff = `inset 0 1.5px 2px ${light(0.95)}, inset 1px 0 1px ${light(0.5)}, inset 0 -4px 5px -2px ${warm(0.2)}, inset -1px 0 2px -1px ${warm(0.08)}, 0 0 0 1px ${warm(0.07)}, 0 1px 2px ${warm(0.14)}, 0 6px 12px -4px ${warm(0.3)}`;
-        const tinted = `inset 0 1.5px 2px ${light(0.6)}, inset 1px 0 1px ${light(0.35)}, inset 0 -4px 5px -2px ${dark(0.16)}, inset -1px 0 2px -1px ${dark(0.06)}, 0 0 0 1px ${warm(0.08)}, 0 1px 2px ${warm(0.16)}, 0 6px 12px -4px ${warm(0.32)}`;
-        const panel = `inset 0 2px 4px ${light(0.95)}, inset 0 -8px 12px -3px ${warm(0.18)}, inset 2px 0 3px -1px ${light(0.5)}, 0 3px 6px ${warm(0.1)}, 0 16px 32px -8px ${warm(0.28)}`;
-        const frame = `inset 0 2px 4px ${light(0.95)}, inset 0 -10px 14px -4px ${warm(0.2)}, 0 6px 10px ${warm(0.12)}, 0 30px 60px -16px ${warm(0.4)}`;
-        const sunk = `inset 0 3px 6px ${warm(0.18)}, inset 0 -1px 2px ${light(0.8)}`;
-        const lifted = `inset 0 1.5px 2px ${light(0.95)}, inset 1px 0 1px ${light(0.5)}, inset 0 -4px 5px -2px ${warm(0.2)}, inset -1px 0 2px -1px ${warm(0.08)}, 0 0 0 1px ${warm(0.07)}, 0 2px 4px ${warm(0.16)}, 0 10px 18px -5px ${warm(0.34)}`;
-        return {
+    plush: (() => {
+      const p = plush;
+      const warm = (a) => alpha(p.shadowInk, a);
+      const light = (a) => alpha(p.white, a);
+      const dark = (a) => alpha(p.black, a);
+      const puff = `inset 0 1.5px 2px ${light(0.95)}, inset 1px 0 1px ${light(0.5)}, inset 0 -4px 5px -2px ${warm(0.2)}, inset -1px 0 2px -1px ${warm(0.08)}, 0 0 0 1px ${warm(0.07)}, 0 1px 2px ${warm(0.14)}, 0 6px 12px -4px ${warm(0.3)}`;
+      const tinted = `inset 0 1.5px 2px ${light(0.6)}, inset 1px 0 1px ${light(0.35)}, inset 0 -4px 5px -2px ${dark(0.16)}, inset -1px 0 2px -1px ${dark(0.06)}, 0 0 0 1px ${warm(0.08)}, 0 1px 2px ${warm(0.16)}, 0 6px 12px -4px ${warm(0.32)}`;
+      const panel = `inset 0 2px 4px ${light(0.95)}, inset 0 -8px 12px -3px ${warm(0.18)}, inset 2px 0 3px -1px ${light(0.5)}, 0 3px 6px ${warm(0.1)}, 0 16px 32px -8px ${warm(0.28)}`;
+      const frame = `inset 0 2px 4px ${light(0.95)}, inset 0 -10px 14px -4px ${warm(0.2)}, 0 6px 10px ${warm(0.12)}, 0 30px 60px -16px ${warm(0.4)}`;
+      const sunk = `inset 0 3px 6px ${warm(0.18)}, inset 0 -1px 2px ${light(0.8)}`;
+      const lifted = `inset 0 1.5px 2px ${light(0.95)}, inset 1px 0 1px ${light(0.5)}, inset 0 -4px 5px -2px ${warm(0.2)}, inset -1px 0 2px -1px ${warm(0.08)}, 0 0 0 1px ${warm(0.07)}, 0 2px 4px ${warm(0.16)}, 0 10px 18px -5px ${warm(0.34)}`;
+      return look("plush", "3D clayful", "light", plush, {
+        shape: { rScale: "1.6", rCtlMin: "var(--r-pill)" },
+        canvas: (p) => ({
+          gradCanvas: `radial-gradient(720px 480px at 100% 100%, ${alpha(p.ember, 0.14)}, transparent 70%), radial-gradient(640px 420px at 0% 0%, ${alpha(p.primaryLight, 0.16)}, transparent 70%), linear-gradient(165deg, ${p.canvasTop} 0%, ${p.canvasMid} 55%, ${p.canvasBottom} 100%)`,
+          canvasPattern: "none",
+          canvasPatternSize: "0 0",
+        }),
+        elevation: {
           edge: panel, shadowTile: puff, shadowPop: panel, shadowPrimary: tinted, shadowDialog: frame,
           shadowInset: sunk, shadowCtl: sunk, shadowCtlHover: lifted, shadowCard: panel, shadowSoft: tinted,
           shadow: puff, shadow1: panel, shadow2: frame, shadowGlow: tinted,
           bevel: `linear-gradient(180deg, ${light(0.3)} 0%, ${light(0)} 45%)`,
           shadowRoom: "20px",
-        };
-      })(),
-      elements: (p) => ({
-        bubble: {
-          shadow: `inset 0 2px 3px ${alpha(p.white, 0.95)}, inset 2px 0 2px -1px ${alpha(p.white, 0.6)}, inset 0 -6px 8px -2px ${alpha(p.shadowInk, 0.2)}, inset -2px 0 4px -2px ${alpha(p.shadowInk, 0.1)}, 0 2px 4px ${alpha(p.shadowInk, 0.12)}, 0 10px 18px -4px ${alpha(p.shadowInk, 0.26)}`,
-          bg: p.soft,
-          mineBg: p.primary,
-          mineCtaInk: p.primaryDark,
-          mineShadow: `inset 0 2px 3px ${alpha(p.white, 0.6)}, inset 2px 0 2px -1px ${alpha(p.white, 0.35)}, inset 0 -6px 8px -2px ${alpha(p.black, 0.16)}, inset -2px 0 4px -2px ${alpha(p.black, 0.06)}, 0 2px 4px ${alpha(p.shadowInk, 0.14)}, 0 10px 18px -4px ${alpha(p.shadowInk, 0.3)}`,
         },
-        input: { shadow: `inset 0 3px 6px ${alpha(p.shadowInk, 0.18)}, inset 0 -1px 2px ${alpha(p.white, 0.8)}` },
-        logoTile: { bg: p.soft, badgeBg: p.soft },
-        face: { tint: "34%", corner: "0.2" },
-        btn: { hoverInk: p.primaryDark }, iconButton: { hoverInk: p.primaryDark }, badge: { ink: p.primaryDark }, chip: { ink: p.primaryDark }, toolCall: { pendingInk: p.primaryDark }, toolFold: { hoverInk: p.primaryDark }, numberField: { stepHoverInk: p.primaryDark },
-      }),
-    }),
+        elements: (p) => ({
+          bubble: {
+            shadow: `inset 0 2px 3px ${alpha(p.white, 0.95)}, inset 2px 0 2px -1px ${alpha(p.white, 0.6)}, inset 0 -6px 8px -2px ${alpha(p.shadowInk, 0.2)}, inset -2px 0 4px -2px ${alpha(p.shadowInk, 0.1)}, 0 2px 4px ${alpha(p.shadowInk, 0.12)}, 0 10px 18px -4px ${alpha(p.shadowInk, 0.26)}`,
+            bg: p.soft,
+            mineBg: `linear-gradient(${p.primary}, ${p.primary})`,
+            mineCtaInk: p.primaryDark,
+            mineShadow: `inset 0 2px 3px ${alpha(p.white, 0.6)}, inset 2px 0 2px -1px ${alpha(p.white, 0.35)}, inset 0 -6px 8px -2px ${alpha(p.black, 0.16)}, inset -2px 0 4px -2px ${alpha(p.black, 0.06)}, 0 2px 4px ${alpha(p.shadowInk, 0.14)}, 0 10px 18px -4px ${alpha(p.shadowInk, 0.3)}`,
+          },
+          input: { shadow: sunk },
+          composer: { shadow: sunk, bg: p.softer, radius: "calc(14px * var(--r-scale))", padX: "12px" },
+          logoTile: { bg: p.soft, badgeBg: p.soft, shadow: puff, radius: "calc(8px * var(--r-scale))", radiusSm: "calc(7px * var(--r-scale))", radiusLg: "calc(9px * var(--r-scale))", radiusBadge: "calc(8px * var(--r-scale))" },
+          face: { tint: "34%", corner: "0.2", shadow: tinted, cardShadow: tinted },
+          btn: {
+            hoverInk: p.primaryDark,
+            shadow: puff, hoverShadow: lifted, hoverLift: "-1px", activeShadow: sunk,
+            primaryActiveShadow: sunk, primaryHoverFilter: "none",
+            secondaryHoverShadow: lifted, secondaryActiveShadow: sunk,
+            dangerSolidShadow: tinted, dangerSolidHoverShadow: lifted, dangerSolidActiveShadow: sunk,
+            okShadow: tinted, warnShadow: tinted,
+            ghostBg: p.softer, softBg: p.softer, secondaryBg: p.softer, paperBg: p.softer,
+          },
+          iconButton: { hoverInk: p.primaryDark, ghostInk: p.muted, shadow: puff, hoverShadow: lifted, hoverLift: "-1px", activeShadow: sunk, primaryShadow: puff, primaryHoverShadow: lifted, primaryActiveShadow: sunk, ghostBg: p.softer },
+          rowButton: { shadow: puff, activeShadow: sunk, radius: "8px" },
+          badge: { ink: p.primaryDark, shadow: tinted },
+          chip: { ink: p.primaryDark, shadow: tinted, hoverShadow: lifted, hoverLift: "-1px", activeShadow: sunk, activeDrop: "1px" },
+          choice: { shadow: tinted, hoverShadow: lifted, hoverLift: "-1px", activeShadow: sunk, activeDrop: "1px", onShadow: sunk },
+          hubRow: { actionShadow: tinted },
+          unseenLine: { labelShadow: tinted },
+          lookCard: { shadow: puff },
+          fileCard: { shadow: puff },
+          askCard: { shadow: puff },
+          toolFold: { hoverInk: p.primaryDark, shadow: puff },
+          roomMark: { shadow: tinted, radius: "calc(10px * var(--r-scale))", radiusLg: "calc(12px * var(--r-scale))", radiusRail: "calc(10px * var(--r-scale))" },
+          feature: { shadow: panel },
+          toolCall: { pendingInk: p.primaryDark }, numberField: { stepHoverInk: p.primaryDark },
+        }),
+      });
+    })(),
     terminal: look("terminal", "Terminal", "dark", terminal, {
       shape: { rScale: "0" },
       type: { font: type.mono },
@@ -824,8 +964,13 @@
         roomMark: { ink: p.ink, gradFrom: "38% 24%", gradTo: "34% 18%", emoji: "35% 20%" },
         tile: { badgeBg: p.lav2 },
         logoTile: { bg: p.lav2, ink: p.primary, badgeBg: p.lav2, badgeBorder: p.lav2, badgeInk: p.primary },
-        bubble: { border: p.lav2, shadow: "none", mineShadow: "none" },
-        unseenLine: { ink: p.muted, bg: p.soft, line: `repeating-linear-gradient(90deg, ${p.lav2} 0 6px, transparent 6px 12px)`, lineH: "1px", lineOpacity: "1" },
+        bubble: { border: p.lav2, shadow: NO_SHADOW, mineShadow: NO_SHADOW },
+        btn: { border: "1px solid currentColor", case: "uppercase", tracking: "0.06em", linkUnderline: "underline" },
+        badge: { fill: "0%", border: "1px solid currentColor", case: "uppercase", tracking: "0.04em", outlineBorder: "currentColor", outlineW: "1px" },
+        chip: { fill: "0%", border: "1px solid currentColor" },
+        choice: { border: "currentColor", onBorder: "currentColor" },
+        hubRow: { prefix: '">"', prefixGap: "6px" },
+        unseenLine: { ink: p.muted, bg: "transparent", line: `repeating-linear-gradient(90deg, ${p.lav2} 0 6px, transparent 6px 12px)`, lineH: "1px", lineOpacity: "1", labelBorder: "1px solid currentColor", labelCase: "uppercase", labelTracking: "0.04em" },
       }),
     }),
   };
@@ -891,7 +1036,7 @@
     { key: "canvas", group: "Paper", label: "Chat paper", hint: "behind the messages", kind: "colour", of: (l) => l.palette.bg, vars: (v) => ({ "--grad-canvas": v, "--grad-page": v, "--canvas-pattern": "none" }) },
     { key: "panel", group: "Paper", label: "Panels", hint: "the rooms, the roster, the chat's frame, a vibemate's panel", kind: "colour", of: (l) => l.aliases.panel, vars: (v) => ({ "--panel": v }) },
     { key: "bubble", group: "Bubbles", label: "Reply bubble", kind: "colour", of: (l) => l.elements.bubble.bg, vars: (v) => ({ "--bubble-bg": v }) },
-    { key: "mine", group: "Bubbles", label: "Your bubble", kind: "colour", of: (l) => l.palette.primary, vars: (v) => ({ "--bubble-mine-bg": v }) },
+    { key: "mine", group: "Bubbles", label: "Your bubble", kind: "colour", of: (l) => l.palette.primary, vars: (v) => ({ "--bubble-mine-bg": `linear-gradient(${v}, ${v})` }) },
     { key: "ring", group: "Bubbles", label: "Bubble outline", hint: "a hairline around a reply; the bubble's own colour hides it", kind: "colour", of: (l) => hexOr(l.elements.bubble.border, l.elements.bubble.bg), vars: (v) => ({ "--bubble-border": v }) },
     { key: "ink", group: "Ink", label: "Words", kind: "colour", of: (l) => l.palette.ink, vars: (v) => ({ "--ink": v, "--ink-2": v, "--bubble-ink": v }) },
     { key: "muted", group: "Ink", label: "Quiet words", hint: "times, hints, labels", kind: "colour", of: (l) => l.palette.muted, vars: (v) => ({ "--muted": v, "--faint": v }) },
@@ -902,5 +1047,329 @@
     { key: "corners", group: "Shape", label: "Corners", hint: "0 is square; every corner in the window scales with it", kind: "scale", min: 0, max: 1.5, step: 0.05, of: (l) => l.shape.rScale, vars: (v) => ({ "--r-scale": v }) },
   ];
 
-  globalThis.VIBEROOM_TOKENS = { looks, current: looks.classic, active, diagrams, adjustables, cssGroups, cssVars, alpha, mix, kebab };
+
+  const SPEC_ID = /^[a-z][a-z0-9-]{0,30}$/;
+  const HEX6 = /^#[0-9a-f]{6}$/i;
+  const COLOUR_VALUE = /^(#[0-9a-f]{6}|#[0-9a-f]{8}|rgba?\([\d\s.,%]+\)|transparent|currentColor)$/i;
+  const UNSAFE = /url\(|expression\(|javascript:|[<>{};\\@]/i;
+  const FONT_STACK = /^[\w\s"',.-]+$/;
+  const isColourDefault = (v) => COLOUR_VALUE.test(String(v).trim());
+
+  const hueOf = (token, palette, where) => {
+    const t = String(token).trim();
+    if (t.startsWith("$")) {
+      const name = t.slice(1);
+      if (!(name in palette)) throw new Error(`${where}: no hue "${name}" in the palette`);
+      return palette[name];
+    }
+    if (HEX6.test(t)) return t.toLowerCase();
+    throw new Error(`${where}: "${t}" is neither a hue of the palette ($name) nor a colour (#rrggbb)`);
+  };
+  const numberIn = (token, where, min, max) => {
+    const n = Number(String(token).trim());
+    if (!Number.isFinite(n) || n < min || n > max) throw new Error(`${where}: "${token}" is not a number between ${min} and ${max}`);
+    return n;
+  };
+  const resolveValue = (raw, palette, where) => {
+    if (typeof raw !== "string") throw new Error(`${where}: a value is a string`);
+    const v = raw.trim();
+    if (!v) throw new Error(`${where}: an empty value`);
+    if (v.length > 400) throw new Error(`${where}: a value is at most 400 characters`);
+    if (UNSAFE.test(v)) throw new Error(`${where}: a value may not carry url(), expression(), javascript: or < > { } ; \\ @`);
+    const out = v
+      .replace(/\b(alpha|mix)\(([^()]*)\)/g, (m, fn, args) => {
+        const parts = args.split(",").map((s) => s.trim());
+        if (fn === "alpha") {
+          if (parts.length !== 2) throw new Error(`${where}: alpha takes a hue and a number: alpha($ink, 0.2)`);
+          return alpha(hueOf(parts[0], palette, where), numberIn(parts[1], where, 0, 1));
+        }
+        if (parts.length !== 3) throw new Error(`${where}: mix takes two hues and a number: mix($white, $ink, 0.5)`);
+        return mix(hueOf(parts[0], palette, where), hueOf(parts[1], palette, where), numberIn(parts[2], where, 0, 1));
+      })
+      .replace(/\$([a-zA-Z][a-zA-Z0-9]*)/g, (m, name) => hueOf(`$${name}`, palette, where));
+    if (/\$/.test(out)) throw new Error(`${where}: a stray $ (a hue is $name)`);
+    return out;
+  };
+  const checked = (defaultValue, value, where) => {
+    if (isColourDefault(defaultValue) && !COLOUR_VALUE.test(value)) throw new Error(`${where}: a colour (the look has ${defaultValue}), not "${value}"`);
+    return value;
+  };
+  const flatSection = (spec, section, defaults, baseWants, palette) => {
+    const out = { ...(baseWants || {}) };
+    for (const [key, raw] of Object.entries(spec || {})) {
+      if (!(key in defaults)) throw new Error(`${section}.${key}: no such token (${Object.keys(defaults).join(", ")})`);
+      out[key] = checked(defaults[key], resolveValue(raw, palette, `${section}.${key}`), `${section}.${key}`);
+    }
+    return out;
+  };
+
+  function make(spec) {
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) throw new Error("a look spec is an object");
+    const id = String(spec.id ?? "").trim();
+    if (!SPEC_ID.test(id)) throw new Error("id: a short lower-case id of letters, digits and hyphens (1-31), starting with a letter");
+    if (looks[id] && !looks[id].custom) throw new Error(`id "${id}" belongs to a look viberoom ships; pick another`);
+    const label = String(spec.label ?? "").trim();
+    if (!label || label.length > 40) throw new Error("label: 1-40 characters, the name the picker shows");
+    const baseId = spec.extends === undefined || spec.extends === null || spec.extends === "" ? "classic" : String(spec.extends);
+    const base = looks[baseId];
+    if (!base) throw new Error(`extends: no look "${baseId}" (${Object.keys(looks).filter((k) => !looks[k].custom).join(", ")})`);
+    if (base.custom) throw new Error(`extends: "${baseId}" is a look of the human's own; a look extends one viberoom ships`);
+    const scheme = spec.scheme === undefined || spec.scheme === null || spec.scheme === "" ? base.scheme : String(spec.scheme);
+    if (scheme !== "light" && scheme !== "dark") throw new Error('scheme: "light" or "dark"');
+    for (const key of Object.keys(spec)) {
+      if (!["id", "label", "scheme", "extends", "author", "created", "updatedAt", "palette", "shape", "type", "motion", "elevation", "canvas", "elements"].includes(key)) throw new Error(`${key}: not a part of a look spec`);
+    }
+    const section = (name) => {
+      const v = spec[name];
+      if (v === undefined || v === null) return {};
+      if (typeof v !== "object" || Array.isArray(v)) throw new Error(`${name}: an object of keys and values`);
+      return v;
+    };
+    const palette = { ...base.palette };
+    for (const [name, raw] of Object.entries(section("palette"))) {
+      if (!(name in palette)) throw new Error(`palette.${name}: no such hue (${Object.keys(palette).join(", ")})`);
+      const v = resolveValue(raw, palette, `palette.${name}`);
+      if (!HEX6.test(v)) throw new Error(`palette.${name}: a hue is a flat colour #rrggbb, not "${v}"`);
+      palette[name] = v.toLowerCase();
+    }
+    const baseWants = base.wants || {};
+    const typeWants = { ...(baseWants.type || {}) };
+    for (const [key, raw] of Object.entries(section("type"))) {
+      if (!(key in type)) throw new Error(`type.${key}: no such token (${Object.keys(type).join(", ")})`);
+      const v = resolveValue(raw, palette, `type.${key}`);
+      if (key === "font" || key === "mono") {
+        const table = key === "font" ? fonts.text : fonts.mono;
+        if (table[v]) typeWants[key] = table[v].stack;
+        else if (FONT_STACK.test(v)) typeWants[key] = v;
+        else throw new Error(`type.${key}: a font id (${Object.keys(table).join(", ")}) or a family stack`);
+      } else typeWants[key] = v;
+    }
+    const specCanvas = section("canvas");
+    const specElements = section("elements");
+    const wants = {
+      shape: flatSection(section("shape"), "shape", shape, baseWants.shape, palette),
+      type: typeWants,
+      motion: flatSection(section("motion"), "motion", motion, baseWants.motion, palette),
+      elevation: flatSection(section("elevation"), "elevation", elevationOf(palette), baseWants.elevation, palette),
+      canvas: (p) => flatSection(specCanvas, "canvas", canvasOf(p), baseWants.canvas ? baseWants.canvas(p) : {}, p),
+      elements: (p) => {
+        const defaults = elementsOf(p);
+        const out = {};
+        const fromBase = baseWants.elements ? baseWants.elements(p) : {};
+        for (const [group, parts] of Object.entries(fromBase)) out[group] = { ...parts };
+        for (const [group, parts] of Object.entries(specElements)) {
+          if (!(group in defaults)) throw new Error(`elements.${group}: no such element (${Object.keys(defaults).join(", ")})`);
+          if (!parts || typeof parts !== "object" || Array.isArray(parts)) throw new Error(`elements.${group}: an object of keys and values`);
+          out[group] = { ...(out[group] || {}) };
+          for (const [key, raw] of Object.entries(parts)) {
+            if (!(key in defaults[group])) throw new Error(`elements.${group}.${key}: no such token (${Object.keys(defaults[group]).join(", ")})`);
+            out[group][key] = checked(defaults[group][key], resolveValue(raw, p, `elements.${group}.${key}`), `elements.${group}.${key}`);
+          }
+        }
+        return out;
+      },
+    };
+    const made = look(id, label, scheme, palette, wants);
+    made.custom = true;
+    made.extends = base.id;
+    made.author = spec.author === undefined || spec.author === null ? "" : String(spec.author).slice(0, 40);
+    return made;
+  }
+
+  const docs = {
+    sections: {
+      palette: "the hues of the look, named after what they look like, never after what they are for; every element is derived from them, so a hue changed here reaches every place that wears it",
+      shape: "corners: rScale multiplies every radius in the window (0 square, 1 as designed, 1.6 very round); rCtlMin is the least radius of a button, an icon button or a chip (0px keeps each one's own, 99px makes every control a pill); rXs…rPill are the named radii, each ONE length or calc() (they are used inside calc() and max(), so a multi-corner value breaks every corner)",
+      type: "text: font and mono are the family stacks (in a spec: an id from fonts, or a stack), lineHeight the running text's, fsScale multiplies every text size, fsXs…fs2xl are the named sizes",
+      motion: "the durations (tFast, tBase, tSlow; 0ms for none) and easings of the transitions",
+      elevation: "the shadows and the light: edge (a hair under a panel), shadowTile (a raised tile), shadowPop (a floating balloon), shadowPrimary (the glow under the accent), shadowDialog, shadowCard, shadowCtl and shadowCtlHover (a control at rest and under the pointer), shadowInset (a sunken thing), shadowSoft (a small raised thing), shadow / shadow1 / shadow2 (older names), bevel (a light laid over a raised surface: a gradient, or none), bevelPressed (the same when pressed), shadowRoom (room around a message for its shadow, 0px unless the shadows reach out)",
+      canvas: "the chat's paper: gradCanvas (the paint behind the messages: a colour, or gradients), canvasPattern and canvasPatternSize (a pattern over it, or none / 0 0), gradPage (the paper behind the panels), sbW / sbThumb / sbThumbHover (the scrollbar)",
+      elements: "every UI element and what it wears: the group is the element, the key the part (bg, ink, hoverBg, border, shadow, radius…); a key ending in Ink is written on the key of the same stem ending in Bg (or on bg), and the pair must read at 3:1 or better; a key whose value is none / 0px / transparent is structure a look may switch on (a border, a shadow, a lift, capitals)",
+    },
+    palette: {
+      primary: "the one accent: buttons, links, your bubble, the ring on your face",
+      primaryLight: "the accent a step lighter (the start of its gradient)",
+      primaryDeep: "the accent a step deeper (the end of its gradient)",
+      primaryDark: "the accent's darkest step: the accent as an ink on its own tint",
+      violet: "the far end of the welcome hero's sweep",
+      iris: "the colour the browser paints its own window frame with",
+      ink: "the words",
+      ink2: "the words in a bubble",
+      ink3: "quieter words: a button's, labels",
+      indigo: "the human's initials on their face; a vendor's mark",
+      muted: "quiet words: times, hints",
+      faint: "the faintest words and dots",
+      placeholder: "a field's placeholder",
+      grey: "a face with no colour of its own",
+      white: "the paper of panels, cards and bubbles (on a dark look: the dark paper)",
+      black: "black, for shadows cast in black",
+      bg: "the paper behind everything",
+      soft: "the paper a step off the panel's: fields, tiles",
+      softer: "the paper two steps off: buttons at rest",
+      lav: "the accent's tint: tiles, chips, hover",
+      lav2: "the accent's deeper tint: borders, a pressed chip",
+      canvasTop: "the chat paper's sweep, top",
+      canvasMid: "the chat paper's sweep, middle",
+      canvasBottom: "the chat paper's sweep, bottom",
+      shadowInk: "the colour shadows are cast in",
+      mint: "green, pale: done, ready",
+      mint2: "green, pale, a step deeper: hover on a green thing",
+      mintTint: "green, the faintest tint",
+      mintInk: "green as an ink on the pale green",
+      forest: "green, dark: words on the hero's green bubble",
+      green: "green, bright: the ready dot",
+      warm: "yellow, pale: thinking, attention, a note",
+      warm2: "yellow, pale, a step deeper: hover on a note",
+      warmInk: "yellow as an ink on the pale yellow",
+      bronze: "yellow, dark: words on the hero's yellow bubble",
+      amber: "amber, bright: the thinking dot, a warning",
+      honey: "honey: the number and the found line in code",
+      spark: "the spark on the hero",
+      peach: "peach, pale: a welcome tile",
+      peach2: "peach, pale, a step deeper",
+      orange: "orange: attention",
+      orangeLight: "orange, light: the attention gradient's start",
+      orangeDeep: "orange, deep: the attention gradient's end",
+      orangeDark: "orange, dark: the attention ink",
+      ember: "ember: unread, a glow",
+      emberDeep: "ember, deep: the unread gradient's end",
+      rose: "red, pale: an error, a danger button",
+      rose2: "red, pale, a step deeper: hover on a danger button",
+      roseInk: "red as an ink: errors, the danger ink, a failed call",
+      roseDark: "red, dark: a solid danger button pressed",
+      pink: "pink: the unseen line",
+      pinkTint: "pink, the faintest tint: the unseen line's label",
+      sky: "blue, pale: waiting, info",
+      blue: "blue: info",
+      blueDeep: "blue, deep: the waiting ink",
+      blueSoft: "blue, soft: the waiting dot",
+      orchid: "violet, pale: writing",
+      orchidInk: "violet as an ink: the writing ink",
+      orchidMid: "violet, mid: the writing dot",
+      periwinkle: "periwinkle: your ticks on the timeline",
+      periwinkleDeep: "periwinkle, deep: your ticks in view",
+      deep: "the dark surface of code blocks and the file viewer",
+      deepGutter: "the gutter of the dark surface",
+      deepInk: "the words on the dark surface",
+      deepMuted: "the quiet words on the dark surface",
+      deepHead: "the head of the dark surface",
+      deepMeta: "the meta words in that head",
+      lavGrey: "code: punctuation",
+      lilac: "code: keywords",
+      seafoam: "code: strings",
+      azure: "code: functions",
+      salmon: "code: tags",
+      magenta: "code: attributes",
+    },
+    elements: {
+      page: "the page itself: its paper, its ink, the selection",
+      focus: "the ring around whatever the keyboard is on",
+      link: "a path or a link inside a message",
+      btn: "button: a button with words; the colours of every kind (primary, secondary, soft, ghost, danger, danger-solid, dark, warn, inverse, link, ok, paper), its sizes, and its structure (border: width style colour; case; tracking; ghostBg; the shadows at rest / on hover / pressed; hoverLift: negative lifts)",
+      iconButton: "icon-button: a button that is only a glyph; kinds primary, danger, ghost, inline; its sizes and structure (ghostBg, shadows, hoverLift)",
+      badge: "badge: a small label that states a fact; the state tones come from the room's meaning colours; fill (100% filled, 0% an outline in its ink), border, case, tracking, shadow",
+      chip: "chip: a small tag that names a thing; fill, border, shadow, hoverLift, activeDrop",
+      fileCard: "file-card: a fragment of a file or a picture under the message that names it (the dark card)",
+      toolCall: "tool-call: a chip that opens to the call; the status colours",
+      toolFold: "tool-fold: the calls of a finished reply, in one line",
+      askCard: "ask-card: a decision the room puts in front of you (a permission, a proposal)",
+      replyNote: "reply-note: a line the hub attaches to a reply, inside its bubble",
+      lookCard: "look-card: a look as a small picture of itself (the picker)",
+      choice: "choice: one option of a few, as a pill; border, shadows, hoverLift, activeDrop",
+      control: "switches and checkboxes",
+      tile: "the small marks that are not types yet: the ? badge of the life ring, the count pills",
+      roomMark: "room-mark: a room's square mark in its own hue (ink, the recipe of the gradient, shadow, radius / radiusLg / radiusRail)",
+      pop: "the little speech balloons the rail and the participants raise",
+      dialog: "the glass behind a dialog",
+      scrim: "the dark glass behind a picture or a diagram",
+      toast: "a toast: the ink with the paper's colour on it",
+      rail: "the main menu",
+      timeline: "the strips beside the chat",
+      bubble: "the message balloon: everyone else's (bg, ink, border, shadow) and your own (mineBg: always an image, a flat colour as linear-gradient(c, c); mineInk, mineShadow and the parts inside it)",
+      quote: "a quoted message inside a balloon",
+      attach: "pictures and file chips in a message",
+      table: "a table in a message",
+      code: "the file viewer and every code block",
+      syntax: "the colours of the code itself",
+      diagram: "a mermaid diagram opened full screen",
+      input: "text fields (bg, focusBorder, shadow: none, or a sunken recipe)",
+      profile: "the human's own card",
+      face: "face: a participant's face (paper and tint of the tile, corner, rings, shadow, cardShadow)",
+      logoTile: "logo-tile: a vendor's mark on a tile (bg, ink, the badge in a face's corner, shadow, radius / radiusSm / radiusLg / radiusBadge)",
+      unseenLine: "unseen-line: the line above which a vibemate has seen nothing (ink, bg, the line's drawing, the label's border / case / tracking / shadow)",
+      numberField: "number-field: a number with its own steps",
+      adjustRow: "adjust-row: one thing the human may adjust in a look, in Settings",
+      rowButton: "row-button: a small action on a vibemate's row",
+      hubRow: "hub-row: a line the hub writes (ink, tones, the one that leads somewhere: actionBg / actionShadow; prefix / prefixGap: what stands before the line, none or a prompt)",
+      hero: "the welcome screen's hero",
+      feature: "the welcome screen's feature tiles (emojiBg, shadow)",
+      composer: "the box you write in (shadow, bg, radius, padX: flat and bare, or sunk into the paper)",
+      step: "the welcome screen's numbered steps",
+      tpl: "the template list in Open a room",
+      browser: "the colour the browser paints its window frame with",
+    },
+  };
+
+  const KIND_SYNTAX = {
+    border: 'a CSS border: width, style and colour, e.g. "2px solid $ink" (a width alone draws nothing); 0 for none',
+    shadow: 'a CSS box-shadow list, e.g. "3px 4px 0 $ink" or "0 2px 6px alpha($ink, 0.2)", or none',
+    radius: "ONE length or calc(), e.g. \"calc(14px * var(--r-scale))\": the named radii are used inside calc() and max(), so a multi-corner value (four lengths, or a slash) breaks every corner",
+    lift: 'a length the thing moves on hover: NEGATIVE lifts it ("-2px"), positive pushes it down; 0px for none',
+    drop: 'a length the thing sinks when pressed ("1px"); 0px for none',
+    fill: 'a percentage of the tone\'s colour: "100%" filled, "0%" an outline in the ink',
+    prefix: 'a quoted string written before the line, e.g. "\">\"", or none',
+    case: "none, uppercase, lowercase or capitalize",
+    tracking: 'a letter-spacing length, e.g. "0.06em" or 0px',
+    scale: 'a number as a string ("1", "0.5", "1.6")',
+    length: 'a CSS length, e.g. "12px"',
+    gradient: "a CSS gradient image (linear-gradient / radial-gradient), a flat colour, or none",
+    bevel: "a gradient image laid over a raised face, or none",
+    font: "a font id from fonts (text or mono), or a family stack",
+  };
+  const kindOf = (section, key, value) => {
+    const v = String(value);
+    if (COLOUR_VALUE.test(v)) return "colour";
+    if (section === "shape") return key === "rScale" ? "scale" : "radius";
+    if (section === "type") return key === "font" || key === "mono" ? "font" : /^fs/.test(key) ? "length" : "scale";
+    if (section === "elevation") return /^bevel/.test(key) ? "bevel" : key === "shadowRoom" ? "length" : "shadow";
+    if (section === "canvas") return /^grad|Pattern$/.test(key) ? "gradient" : "length";
+    if (/[Rr]adius/.test(key)) return "radius";
+    if (/[Ss]hadow$/.test(key)) return "shadow";
+    if (key === "border" || /Border$/.test(key)) return "border";
+    if (/Lift$/.test(key)) return "lift";
+    if (/Drop$/.test(key)) return "drop";
+    if (key === "fill") return "fill";
+    if (key === "prefix") return "prefix";
+    if (key === "case" || /Case$/.test(key)) return "case";
+    if (/[Tt]racking$/.test(key)) return "tracking";
+    if (/Bg$|^bg$|Ink$|^ink$|Color$/.test(key) || /gradient\(/.test(v)) return "gradient";
+    return null;
+  };
+
+  function describe() {
+    const l = looks.classic;
+    const keysOf = (obj) => Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, String(v)]));
+    const kinds = {};
+    const structural = (kind) => kind && kind !== "colour" && kind !== "gradient";
+    for (const section of ["shape", "type", "elevation", "canvas"]) for (const [k, v] of Object.entries(l[section])) { const kind = kindOf(section, k, v); if (structural(kind)) kinds[`${section}.${k}`] = kind; }
+    for (const [g, parts] of Object.entries(l.elements)) for (const [k, v] of Object.entries(parts)) { const kind = kindOf("elements", k, v); if (structural(kind)) kinds[`elements.${g}.${k}`] = kind; }
+    return {
+      syntax: "A look spec is { id, label, scheme?, extends?, palette?, shape?, type?, motion?, elevation?, canvas?, elements? }. It extends one of the looks viberoom ships (VibeClassic unless said) and changes only the keys it gives. A value is a string: a colour \"#1a2b3c\"; \"$name\" for a hue of the palette; \"alpha($ink, 0.14)\" for a hue at an alpha; \"mix($white, $ink, 0.5)\" for a blend; anything else (a shadow, a size, a gradient, a font) as CSS, with those forms inside it. A key the look does not have is refused; a colour key takes only a colour; no url(), no braces.",
+      sections: docs.sections,
+      palette: Object.fromEntries(Object.keys(l.palette).map((n) => [n, { doc: docs.palette[n] || "", classic: l.palette[n] }])),
+      shape: keysOf(l.shape),
+      type: keysOf(l.type),
+      motion: keysOf(l.motion),
+      elevation: keysOf(l.elevation),
+      canvas: keysOf(l.canvas),
+      elements: Object.fromEntries(Object.entries(l.elements).map(([g, parts]) => [g, { doc: docs.elements[g] || "", keys: keysOf(parts) }])),
+      kinds,
+      kindSyntax: KIND_SYNTAX,
+      fonts: { text: Object.keys(fonts.text), mono: Object.keys(fonts.mono) },
+      looks: Object.values(looks).map((x) => ({ id: x.id, label: x.label, scheme: x.scheme, custom: !!x.custom, extends: x.extends || null })),
+      adjustables: adjustables.map((a) => ({ key: a.key, group: a.group, label: a.label, hint: a.hint || "", kind: a.kind, min: a.min, max: a.max, step: a.step })),
+    };
+  }
+
+  globalThis.VIBEROOM_TOKENS = { looks, current: looks.classic, active, diagrams, adjustables, cssGroups, cssVars, alpha, mix, kebab, fonts, make, describe, docs, kindOf };
 })();