@oneli8/tokens 1.0.0-beta.3 → 1.0.0-beta.4

package/fonts.css

@@ -0,0 +1,63 @@
+/* OneLi8 brand faces. Self hosted so the type system works offline and without
+ a third party request. Syne and AR One Sans are both SIL OFL 1.1; see
+ FONTS-LICENSE.txt. Both are variable: one file carries the whole weight range. */
+
+/* Syne · greek */
+@font-face {
+  font-family: "Syne";
+  font-style: normal;
+  font-weight: 400 800;
+  font-display: swap;
+  src: url("./fonts/syne-greek.woff2") format("woff2");
+  unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;
+}
+
+/* Syne · latin-ext */
+@font-face {
+  font-family: "Syne";
+  font-style: normal;
+  font-weight: 400 800;
+  font-display: swap;
+  src: url("./fonts/syne-latin-ext.woff2") format("woff2");
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+
+/* Syne · latin */
+@font-face {
+  font-family: "Syne";
+  font-style: normal;
+  font-weight: 400 800;
+  font-display: swap;
+  src: url("./fonts/syne-latin.woff2") format("woff2");
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+/* AR One Sans · vietnamese */
+@font-face {
+  font-family: "AR One Sans";
+  font-style: normal;
+  font-weight: 400 700;
+  font-display: swap;
+  src: url("./fonts/ar-one-sans-vietnamese.woff2") format("woff2");
+  unicode-range: U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;
+}
+
+/* AR One Sans · latin-ext */
+@font-face {
+  font-family: "AR One Sans";
+  font-style: normal;
+  font-weight: 400 700;
+  font-display: swap;
+  src: url("./fonts/ar-one-sans-latin-ext.woff2") format("woff2");
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+
+/* AR One Sans · latin */
+@font-face {
+  font-family: "AR One Sans";
+  font-style: normal;
+  font-weight: 400 700;
+  font-display: swap;
+  src: url("./fonts/ar-one-sans-latin.woff2") format("woff2");
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}

package/overrides.example.css

@@ -0,0 +1,53 @@
+/* OneLi8 override surface.
+   Copy what you need into your own stylesheet, after importing the tokens.
+   Nothing here is required. Every value below is already set by the system;
+   these are the supported places to change it. */
+
+:root {
+  /* ---- Type ------------------------------------------------------------
+     Two brand faces and one shared fallback. Replace a face and the fallback
+     still applies, because the fallback is referenced rather than inlined.
+     Drop the @oneli8/tokens/fonts.css import if you are supplying your own. */
+
+  /* --ol8-font-family-display: "Your Display Face", var(--ol8-font-family-fallback); */
+  /* --ol8-font-family-functional: "Your Text Face", var(--ol8-font-family-fallback); */
+  /* --ol8-font-family-fallback: ui-sans-serif, system-ui, sans-serif; */
+
+  /* ---- Colour ----------------------------------------------------------
+     data-ol8-primary switches between the three built families. For any other
+     hue, repoint the eleven primary steps here instead. 47 semantic roles read
+     this ramp, so buttons, links, focus, selection and the Gem material all
+     follow without touching a component.
+
+     Keep the tonal relationships: 030 lightest through 930 darkest, with 600
+     carrying the default action surface and 120 doing the same job in dark. */
+
+  /* --ol8-color-primary-030: #f6f2ff; */
+  /* --ol8-color-primary-060: #ece4ff; */
+  /* --ol8-color-primary-090: #d9c9ff; */
+  /* --ol8-color-primary-120: #c0a6ff; */
+  /* --ol8-color-primary-240: #a077f2; */
+  /* --ol8-color-primary-360: #8250d6; */
+  /* --ol8-color-primary-480: #6838b2; */
+  /* --ol8-color-primary-600: #542e8e; */
+  /* --ol8-color-primary-720: #452771; */
+  /* --ol8-color-primary-840: #38225b; */
+  /* --ol8-color-primary-930: #221238; */
+}
+
+/* Override at :root, not on a subtree.
+   A role such as --ol8-color-action-primary-default is declared as
+   var(--ol8-color-primary-600) on :root, so CSS substitutes it there and
+   descendants inherit an already resolved colour. Re-pointing the ramp deeper
+   in the tree changes the ramp but not the roles that read it.
+
+   Verified: overriding --ol8-color-primary-600 on :root repaints the primary
+   action surface. The same override on a wrapper element does nothing.
+
+   To theme one region, re-declare the roles you want on that region:
+
+   .marketing-section {
+     --ol8-color-action-primary-default: #0f766e;
+     --ol8-color-action-primary-hover: #115e59;
+   }
+*/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneli8/tokens",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.4",
   "description": "OneLi8 Design System \u2014 design tokens compiled from Figma. CSS custom properties and a flat JS object.",
   "keywords": [
     "design-tokens",
@@ -23,29 +23,43 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/tokens.d.ts",
-      "import": "./dist/tokens.js",
-      "default": "./dist/tokens.js"
+      "types": "./build/typescript/index.d.ts",
+      "import": "./build/typescript/index.js",
+      "default": "./build/typescript/index.js"
     },
-    "./css": "./dist/tokens.css",
-    "./tokens.css": "./dist/tokens.css",
-    "./tailwind": "./dist/tailwind/preset.mjs",
-    "./tailwind.css": "./dist/tailwind/theme.css",
-    "./figma": "./dist/figma/variables.json",
-    "./status": "./dist/status/components.json",
-    "./source": "./src/tokens.json",
-    "./package.json": "./package.json"
+    "./css": "./build/css/tokens.css",
+    "./fonts.css": "./fonts.css",
+    "./fonts/*": "./fonts/*",
+    "./overrides.example.css": "./overrides.example.css",
+    "./tailwind": "./build/tailwind/preset.mjs",
+    "./tailwind.css": "./build/tailwind/theme.css",
+    "./figma": "./build/figma/variables.json",
+    "./status": "./build/status/components.json",
+    "./source": "./src/semantic.json",
+    "./package.json": "./package.json",
+    "./ai-context.json": "./ai-context.json"
   },
-  "types": "./dist/tokens.d.ts",
+  "types": "./build/typescript/index.d.ts",
   "sideEffects": [
-    "./dist/tokens.css"
+    "./build/css/tokens.css",
+    "./fonts.css"
   ],
   "files": [
-    "dist",
+    "build",
     "src",
+    "status",
+    "schema",
+    "scripts",
+    "fonts",
+    "fonts.css",
+    "overrides.example.css",
+    "ai-context.json",
+    "PRINCIPLES.md",
+    "AGENTS.md",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "FONTS-LICENSE.txt"
   ],
   "engines": {
     "node": ">=20"

package/schema/component-status.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema":"https://json-schema.org/draft/2020-12/schema",
+  "$id":"https://oneli8.org/schema/component-status.schema.json",
+  "title":"Oneli8 component status registry",
+  "type":"object",
+  "required":["version","components"],
+  "properties":{
+    "$schema":{"type":"string"},
+    "generated":{"type":"boolean"},
+    "version":{"type":"string","minLength":1},
+    "components":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/record"}}
+  },
+  "additionalProperties":false,
+  "$defs":{
+    "record":{
+      "type":"object",
+      "required":["name","status","designerApproved","implementationCertified","contractPath","knownEvidence","missingEvidence"],
+      "properties":{
+        "name":{"type":"string","minLength":1},
+        "status":{"enum":["Stable","Candidate","Labs","Experimental","Deprecated"]},
+        "designerApproved":{"type":"boolean"},
+        "implementationCertified":{"type":"boolean"},
+        "contractPath":{"type":"string","minLength":1},
+        "implementationPath":{"type":["string","null"]},
+        "figmaComponentKey":{"type":["string","null"]},
+        "knownEvidence":{"type":"array","items":{"type":"string"}},
+        "missingEvidence":{"type":"array","items":{"type":"string"}}
+      },
+      "additionalProperties":true
+    }
+  }
+}

package/schema/token-file.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema":"https://json-schema.org/draft/2020-12/schema",
+  "$id":"https://oneli8.org/schema/token-file.schema.json",
+  "title":"Oneli8 DTCG-compatible token file",
+  "type":"object",
+  "properties":{
+    "$schema":{"type":"string"},
+    "$description":{"type":"string"},
+    "$extensions":{"type":"object"}
+  },
+  "additionalProperties":{"$ref":"#/$defs/node"},
+  "$defs":{
+    "node":{
+      "oneOf":[
+        {"$ref":"#/$defs/token"},
+        {"type":"object","additionalProperties":{"$ref":"#/$defs/node"}}
+      ]
+    },
+    "token":{
+      "type":"object",
+      "required":["$type","$value"],
+      "properties":{
+        "$type":{"type":"string","minLength":1},
+        "$value":{},
+        "$description":{"type":"string","minLength":1},
+        "$extensions":{"type":"object"}
+      },
+      "additionalProperties":false
+    }
+  }
+}

package/scripts/build.mjs

@@ -0,0 +1,246 @@
+import fs from "node:fs";
+import path from "node:path";
+import {fileURLToPath} from "node:url";
+
+const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),"..");
+const read=name=>JSON.parse(fs.readFileSync(path.join(root,"src",name),"utf8"));
+const primitive=read("primitive.json");
+const semantic=read("semantic.json");
+const component=read("component.json");
+const themes=read("themes.json");
+const status=JSON.parse(fs.readFileSync(path.join(root,"status/components.json"),"utf8"));
+const sources={primitive,semantic,component};
+
+const isToken=value=>value&&typeof value==="object"&&Object.hasOwn(value,"$value");
+const flatten=(node,prefix="",out={})=>{
+  for(const [key,value] of Object.entries(node)){
+    if(key.startsWith("$"))continue;
+    const tokenPath=prefix?`${prefix}.${key}`:key;
+    if(isToken(value))out[tokenPath]=value;
+    else if(value&&typeof value==="object"&&!Array.isArray(value))flatten(value,tokenPath,out);
+  }
+  return out;
+};
+const byTier={primitive:flatten(primitive),semantic:flatten(semantic),component:flatten(component)};
+const all={...byTier.primitive,...byTier.semantic,...byTier.component};
+const referencePattern=/^\{([^}]+)\}$/;
+
+const resolveValue=(value,stack=[])=>{
+  if(typeof value==="string"){
+    const match=value.match(referencePattern);
+    if(!match)return value;
+    const ref=match[1];
+    if(!all[ref])throw new Error(`Missing token reference {${ref}}`);
+    if(stack.includes(ref))throw new Error(`Circular token reference ${[...stack,ref].join(" -> ")}`);
+    return resolveValue(all[ref].$value,[...stack,ref]);
+  }
+  if(Array.isArray(value))return value.map(item=>resolveValue(item,stack));
+  if(value&&typeof value==="object")return Object.fromEntries(Object.entries(value).map(([key,item])=>[key,resolveValue(item,stack)]));
+  return value;
+};
+
+const approvedDimensions=new Set([0,3,6,9,12,15,18,24,30,36,42,48,60,72,84,96,108]);
+for(const [tokenPath,token] of Object.entries(byTier.primitive)){
+  if(JSON.stringify(token.$value).match(/#(?:000|000000|fff|ffffff)(?![0-9a-f])/i))throw new Error(`Pure black or white in ${tokenPath}`);
+  if(typeof token.$value==="string"&&referencePattern.test(token.$value))throw new Error(`Primitive token ${tokenPath} cannot reference another tier`);
+  if(tokenPath.startsWith("dimension.scale.")&&!approvedDimensions.has(token.$value.value))throw new Error(`Off-scale primitive ${tokenPath}`);
+}
+for(const [tokenPath,token] of Object.entries(byTier.semantic)){
+  if(!token.$description)throw new Error(`Public Semantic token ${tokenPath} needs a description`);
+  const refs=JSON.stringify(token.$value).match(/\{[a-zA-Z0-9.-]+\}/g)||[];
+  for(const raw of refs){const ref=raw.slice(1,-1);if(!byTier.primitive[ref]&&!byTier.semantic[ref])throw new Error(`Semantic token ${tokenPath} has invalid reference ${raw}`)}
+}
+for(const [tokenPath,token] of Object.entries(byTier.component)){
+  if(!token.$description)throw new Error(`Public Component token ${tokenPath} needs a description`);
+  const refs=JSON.stringify(token.$value).match(/\{[a-zA-Z0-9.-]+\}/g)||[];
+  for(const raw of refs){const ref=raw.slice(1,-1);if(!byTier.semantic[ref]&&!byTier.component[ref])throw new Error(`Component token ${tokenPath} has invalid reference ${raw}`)}
+  if(token.$type==="color"&&refs.length===0)throw new Error(`Component color token ${tokenPath} must resolve through Semantic color`);
+  if(token.$type==="dimension"&&token.$value&&typeof token.$value==="object"&&typeof token.$value.value==="number"&&token.$value.unit&&!token.$extensions?.["oneli8.geometry"]&&!token.$extensions?.["oneli8.exception"])throw new Error(`Literal Component geometry ${tokenPath} needs an approval record`);
+}
+const allowedStatuses=new Set(["Stable","Candidate","Labs","Experimental","Deprecated"]);
+if(!Array.isArray(status.components)||status.components.length===0)throw new Error("Component status registry must contain public records");
+const statusNames=new Set();
+for(const record of status.components){
+  for(const field of ["name","status","designerApproved","implementationCertified","contractPath"])if(!Object.hasOwn(record,field))throw new Error(`Component status record is missing ${field}`);
+  if(statusNames.has(record.name))throw new Error(`Duplicate component status ${record.name}`);
+  statusNames.add(record.name);
+  if(!allowedStatuses.has(record.status))throw new Error(`Unsupported component status ${record.status}`);
+  if(typeof record.designerApproved!=="boolean"||typeof record.implementationCertified!=="boolean")throw new Error(`Invalid approval flags for ${record.name}`);
+  if(!Array.isArray(record.knownEvidence)||!Array.isArray(record.missingEvidence))throw new Error(`Evidence arrays required for ${record.name}`);
+  if(record.designerApproved&&record.knownEvidence.length===0)throw new Error(`Designer approval for ${record.name} requires evidence`);
+  if(record.implementationCertified&&!record.implementationPath)throw new Error(`Certified implementation for ${record.name} requires a path`);
+  const contractFile=path.resolve(root,"..","..",record.contractPath);
+  // Standalone token consumers do not receive the full development documentation.
+  // Keep repository contract validation on by default; this flag changes no tokens.
+  if(!process.argv.includes("--standalone")&&!fs.existsSync(contractFile))throw new Error(`Missing component contract for ${record.name}: ${record.contractPath}`);
+}
+for(const tokenPath of Object.keys(all))resolveValue(all[tokenPath].$value,[tokenPath]);
+for(const axis of ["colorScheme","primaryFamily","typographyViewport"]){
+  for(const [modeName,mode] of Object.entries(themes[axis]||{})){
+    for(const [tokenPath,token] of Object.entries(mode.overrides||{})){
+      if(!all[tokenPath])throw new Error(`Unknown ${axis}/${modeName} override target ${tokenPath}`);
+      const refs=JSON.stringify(token.$value).match(/\{[a-zA-Z0-9.-]+\}/g)||[];
+      for(const raw of refs){const ref=raw.slice(1,-1);if(!all[ref])throw new Error(`Invalid ${axis}/${modeName} reference ${raw}`)}
+      resolveValue(token.$value,[`${axis}.${modeName}.${tokenPath}`]);
+    }
+  }
+}
+
+// Figma is the naming authority. Its variables run compound words together
+// (cutedge, innerwidth, actionprimary), so a camelCase source key must NOT be
+// split on the capital. Only the path separator becomes a hyphen. The authored
+// JSON keeps camelCase for readability; the emitted name matches Figma exactly.
+const kebab=value=>value.replace(/\./g,"-").toLowerCase();
+// Figma is the naming authority, and it says so explicitly: every variable
+// carries a codeSyntax.WEB field. src/figma-code-syntax.txt records that field
+// verbatim. Nothing here infers a name, because Figma is not internally regular
+// enough to infer from — it writes color-icon-button-quiet-hover-surface
+// hyphenated and component-iconbutton-box-compact joined.
+const CONTRACT=new Map(
+  fs.readFileSync(path.join(root,"src/figma-code-syntax.txt"),"utf8")
+    .split("\n").filter(l=>l && !l.startsWith("#"))
+    .map(l=>{const i=l.indexOf("|");return [l.slice(0,i), l.slice(i+1)];})
+);
+const uncontracted=new Set();
+const figmaVarName=tokenPath=>{
+  const contracted=CONTRACT.get(tokenPath);
+  if(contracted)return contracted.replace(/^--ol8-/,"");
+  uncontracted.add(tokenPath);
+  return kebab(tokenPath);
+};
+const cssName=tokenPath=>`--ol8-${figmaVarName(tokenPath)}`;
+// A composite role's sub key is a CSS property, not a Figma variable, so it
+// keeps the hyphen: font-weight, line-height, letter-spacing.
+const cssProperty=key=>key.replace(/([a-z0-9])([A-Z])/g,"$1-$2").toLowerCase();
+const cssCompositeName=(tokenPath,key)=>`--ol8-${figmaVarName(tokenPath)}-${cssProperty(key)}`;
+const unitValue=value=>value&&typeof value==="object"&&typeof value.value==="number"&&value.unit?`${value.value}${value.unit}`:null;
+const hexRgb=value=>{
+  const match=typeof value==="string"&&value.match(/^#([0-9a-f]{6})$/i);
+  return match?[0,2,4].map(offset=>Number.parseInt(match[1].slice(offset,offset+2),16)):null;
+};
+const alphaColor=value=>{
+  if(!value||typeof value!=="object"||typeof value.alpha!=="number")return null;
+  const channels=hexRgb(value.color);
+  return channels?`rgb(${channels.join(" ")} / ${value.alpha})`:null;
+};
+const shadowValue=value=>{
+  if(!Array.isArray(value))return null;
+  if(value.length===0)return "none";
+  const layers=value.map(layer=>{
+    const color=alphaColor({color:layer.color,alpha:layer.alpha});
+    const geometry=[layer.offsetX,layer.offsetY,layer.blur,layer.spread].map(unitValue);
+    return color&&geometry.every(Boolean)?`${geometry.join(" ")} ${color}`:null;
+  });
+  return layers.every(Boolean)?layers.join(", "):null;
+};
+const cssScalar=(value,token)=>{
+  const unit=unitValue(value);if(unit)return unit;
+  // A bare family name is not usable CSS on its own. Quote anything with a
+  // space, and resolve brand faces through the shared fallback so a face that
+  // is missing, still loading, or deliberately replaced lands somewhere sane.
+  if(token?.$type==="fontFamily"){
+    const name=String(value);
+    const quoted=/[^A-Za-z0-9_-]/.test(name)?`"${name}"`:name;
+    return token?.$extensions?.["oneli8.role"]==="brand-face"
+      ?`${quoted}, var(--ol8-font-family-fallback)`:name;
+  }
+  if(token?.$extensions?.["oneli8.unit"]==="em")return `${value}em`;
+  if(token?.$type==="color"){const color=alphaColor(value);if(color)return color}
+  if(token?.$type==="shadow"){const shadow=shadowValue(value);if(shadow!==null)return shadow}
+  if(Array.isArray(value)&&value.length===4&&value.every(item=>typeof item==="number"))return `cubic-bezier(${value.join(", ")})`;
+  if(typeof value==="string"||typeof value==="number")return String(value);
+  return null;
+};
+const cssLinesFor=(tokenPath,token,{preserveColorReference=false}={})=>{
+  const reference=typeof token.$value==="string"?token.$value.match(referencePattern):null;
+  if(preserveColorReference&&token.$type==="color"&&reference)return [`  ${cssName(tokenPath)}: var(${cssName(reference[1])});`];
+  const compositeReference=token.$type==="color"&&token.$value&&typeof token.$value==="object"&&typeof token.$value.color==="string"?token.$value.color.match(referencePattern):null;
+  if(preserveColorReference&&compositeReference&&typeof token.$value.alpha==="number")return [`  ${cssName(tokenPath)}: color-mix(in srgb, var(${cssName(compositeReference[1])}) ${token.$value.alpha*100}%, transparent);`];
+  const value=resolveValue(token.$value,[tokenPath]);
+  const scalar=cssScalar(value,token);
+  if(scalar!==null)return [`  ${cssName(tokenPath)}: ${scalar};`];
+  if(value&&typeof value==="object")return Object.entries(value).flatMap(([key,item])=>{
+    const rawReference=String(token.$value?.[key]||"").match(referencePattern);
+    // Keep the family as a reference rather than baking the resolved name.
+    // A composite role that inlines "AR One Sans" cannot follow a replaced
+    // brand face; one that points at the family token can.
+    if(preserveColorReference&&rawReference&&rawReference[1].startsWith("font.family."))
+      return [`  ${cssCompositeName(tokenPath,key)}: var(${cssName(rawReference[1])});`];
+    const itemScalar=cssScalar(item,all[(rawReference||[])[1]]||token);
+    return itemScalar===null?[]:[`  ${cssCompositeName(tokenPath,key)}: ${itemScalar};`];
+  });
+  return [];
+};
+const cssTokens={...byTier.primitive,...byTier.semantic,...byTier.component};
+const css=["/* @generated by @oneli8/tokens — do not edit */",":root {",...Object.entries(cssTokens).flatMap(([p,t])=>cssLinesFor(p,t,{preserveColorReference:true})),"}"];
+for(const [modeName,mode] of Object.entries(themes.colorScheme)){
+  if(!Object.keys(mode.overrides).length)continue;
+  css.push(``, `[data-ol8-color-scheme="${modeName}"] {`);
+  for(const [tokenPath,token] of Object.entries(mode.overrides))css.push(...cssLinesFor(tokenPath,token,{preserveColorReference:true}));
+  css.push("}");
+}
+for(const [modeName,mode] of Object.entries(themes.primaryFamily)){
+  css.push(``, `[data-ol8-primary="${modeName}"] {`);
+  for(const [tokenPath,token] of Object.entries(mode.overrides))css.push(...cssLinesFor(tokenPath,token,{preserveColorReference:true}));
+  css.push("}");
+}
+for(const mode of ["medium","expanded"]){
+  css.push(``, `[data-ol8-type-mode="${mode}"] {`);
+  for(const [tokenPath,token] of Object.entries(themes.typographyViewport[mode].overrides))css.push(...cssLinesFor(tokenPath,token));
+  css.push("}");
+}
+
+const resolved=Object.fromEntries(Object.entries(all).map(([tokenPath,token])=>[tokenPath,{type:token.$type,value:resolveValue(token.$value,[tokenPath]),description:token.$description||"",tier:byTier.primitive[tokenPath]?"primitive":byTier.semantic[tokenPath]?"semantic":"component"}]));
+const tokenPaths=Object.keys(resolved).sort();
+
+const dimensionScale=Object.fromEntries(Object.entries(byTier.primitive).filter(([p])=>p.startsWith("dimension.scale.")).map(([,t])=>{const value=resolveValue(t.$value);return [String(value.value/3),cssScalar(value,t)]}));
+const radii=Object.fromEntries(Object.entries(byTier.semantic).filter(([p])=>p.startsWith("shape.radius.")).map(([p,t])=>[p.split(".").at(-1),cssScalar(resolveValue(t.$value),t)]));
+const borderWidth=Object.fromEntries(Object.entries(byTier.semantic).filter(([p])=>p.startsWith("border.width.")).map(([p,t])=>[p.split(".").at(-1),cssScalar(resolveValue(t.$value),t)]));
+const fontSize=Object.fromEntries(Object.entries(byTier.semantic).filter(([p])=>/^typography\.(display|title|body)\./.test(p)).map(([p,t])=>{const v=resolveValue(t.$value);return [p.replace("typography.","").replace(".","-"),[cssScalar(v.fontSize,t),{lineHeight:cssScalar(v.lineHeight,t),letterSpacing:`${v.letterSpacing}em`,fontWeight:String(v.fontWeight),fontFamily:v.fontFamily}]]}));
+const duration=Object.fromEntries(Object.entries(byTier.primitive).filter(([p])=>p.startsWith("motion.duration.")).map(([p,t])=>[p.split(".").at(-1),cssScalar(resolveValue(t.$value),t)]));
+const easing=Object.fromEntries(Object.entries(byTier.primitive).filter(([p])=>p.startsWith("motion.easing.")).map(([p,t])=>[p.split(".").at(-1),cssScalar(resolveValue(t.$value),t)]));
+const boxShadow=Object.fromEntries(Object.keys(byTier.semantic).filter(p=>p.startsWith("elevation.surface.")).map(p=>[p.split(".").at(-1),`var(${cssName(p)})`]));
+const zIndex=Object.fromEntries(Object.entries(byTier.semantic).filter(([p])=>p.startsWith("layer.stack.")).map(([p,t])=>[p.split(".").at(-1),String(resolveValue(t.$value))]));
+// A Tailwind utility is something a person types, so it stays readable and
+// hyphenated: bg-ol8-action-primary-default. The variable it points at follows
+// Figma. Readable surface, exact underlying name.
+const utilityName=path=>path.replace(/([a-z0-9])([A-Z])/g,"$1-$2").replace(/\./g,"-").toLowerCase();
+const semanticColors=Object.fromEntries(Object.keys(byTier.semantic).filter(p=>p.startsWith("color.")&&!p.startsWith("color.primary.")).map(p=>[utilityName(p.slice(6)),`var(${cssName(p)})`]));
+const tailwind={theme:{extend:{colors:{ol8:semanticColors},spacing:dimensionScale,borderRadius:radii,borderWidth,boxShadow,zIndex,fontFamily:{display:["Syne","system-ui","sans-serif"],functional:["AR One Sans","system-ui","sans-serif"]},fontWeight:{regular:"450",semibold:"600",bold:"690"},fontSize,transitionDuration:duration,transitionTimingFunction:easing}}};
+
+const title=value=>value.replace(/([a-z0-9])([A-Z])/g,"$1 $2").replace(/^./,char=>char.toUpperCase());
+const figmaName=tokenPath=>tokenPath.split(".").map(title).join(" / ");
+const modeData=Object.fromEntries(["colorScheme","primaryFamily","typographyViewport"].map(axis=>[axis,Object.fromEntries(Object.entries(themes[axis]).map(([modeName,mode])=>[modeName,Object.entries(mode.overrides).map(([tokenPath,token])=>({path:tokenPath,name:figmaName(tokenPath),type:token.$type,value:resolveValue(token.$value,[`${axis}.${modeName}.${tokenPath}`]),reference:(typeof token.$value==="string"&&token.$value.match(referencePattern)?.[1])||null,description:token.$description||""}))]))]));
+const figma={generated:true,source:"@oneli8/tokens",collections:{primitive:[],semantic:[],component:[]},typographyStyles:[],elevationStyles:[],modeAxes:themes.$extensions["oneli8.axes"],modes:modeData};
+for(const [tokenPath,record] of Object.entries(resolved)){
+  const sourceToken=all[tokenPath];
+  const entry={path:tokenPath,name:figmaName(tokenPath),type:record.type,value:record.value,reference:(typeof sourceToken.$value==="string"&&sourceToken.$value.match(referencePattern)?.[1])||null,description:record.description};
+  if(record.type==="typography")figma.typographyStyles.push(entry);
+  else if(record.type==="shadow")figma.elevationStyles.push(entry);
+  else figma.collections[record.tier].push(entry);
+}
+
+const ensure=relative=>fs.mkdirSync(path.dirname(path.join(root,relative)),{recursive:true});
+const write=(relative,content)=>{ensure(relative);fs.writeFileSync(path.join(root,relative),content)};
+write("build/css/tokens.css",`${css.join("\n")}\n`);
+write("build/typescript/index.js",`// @generated by @oneli8/tokens — do not edit\nexport const tokens = ${JSON.stringify(resolved,null,2)};\nexport const tokenPaths = ${JSON.stringify(tokenPaths,null,2)};\nexport const themeAxes = ${JSON.stringify(themes.$extensions["oneli8.axes"],null,2)};\nexport const themeModes = ${JSON.stringify(modeData,null,2)};\nexport default tokens;\n`);
+write("build/typescript/index.d.ts",`// @generated by @oneli8/tokens — do not edit\nexport type TokenPath = ${tokenPaths.map(p=>JSON.stringify(p)).join(" | ")};\nexport type ColorScheme = "light" | "dark";\nexport type PrimaryFamily = "blue" | "orange" | "green";\nexport type TypographyViewport = "compact" | "medium" | "expanded";\nexport declare const tokens: Readonly<Record<TokenPath,{readonly type:string;readonly value:unknown;readonly description:string;readonly tier:"primitive"|"semantic"|"component"}>>;\nexport declare const tokenPaths: readonly TokenPath[];\nexport declare const themeAxes: Readonly<Record<string,readonly string[]>>;\nexport declare const themeModes: Readonly<Record<string,unknown>>;\nexport default tokens;\n`);
+write("build/tailwind/preset.mjs",`// @generated by @oneli8/tokens — do not edit\nexport default ${JSON.stringify(tailwind,null,2)};\n`);
+const tw4=["/* @generated Tailwind CSS v4 theme bridge — do not edit */","@theme {",...Object.entries(semanticColors).map(([k,v])=>`  --color-ol8-${k}: ${v};`),...Object.entries(dimensionScale).map(([k,v])=>`  --spacing-${k}: ${v};`),...Object.entries(radii).map(([k,v])=>`  --radius-${k}: ${v};`),...Object.entries(boxShadow).map(([k,v])=>`  --shadow-ol8-${k}: ${v};`),...Object.entries(zIndex).map(([k,v])=>`  --z-ol8-${k}: ${v};`),`  --font-display: "Syne", system-ui, sans-serif;`,`  --font-functional: "AR One Sans", system-ui, sans-serif;`,`  --font-weight-regular: 450;`,`  --font-weight-semibold: 600;`,`  --font-weight-bold: 690;`,"}"];
+write("build/tailwind/theme.css",`${tw4.join("\n")}\n`);
+write("build/figma/variables.json",`${JSON.stringify(figma,null,2)}\n`);
+write("build/status/components.json",`${JSON.stringify({...status,$schema:"https://oneli8.org/schema/component-status.schema.json",generated:true},null,2)}\n`);
+write("build/manifest.json",`${JSON.stringify({generated:true,version:"1.0.0-beta.1",counts:{primitive:Object.keys(byTier.primitive).length,semantic:Object.keys(byTier.semantic).length,component:Object.keys(byTier.component).length,componentStatuses:status.components.length,figmaVariables:figma.collections.primitive.length+figma.collections.semantic.length+figma.collections.component.length,figmaTypographyStyles:figma.typographyStyles.length,figmaElevationStyles:figma.elevationStyles.length},outputs:["css/tokens.css","typescript/index.js","typescript/index.d.ts","tailwind/preset.mjs","tailwind/theme.css","figma/variables.json","status/components.json"]},null,2)}\n`);
+
+// Drift report, both directions. A token with no contract entry means the name
+// was invented here rather than agreed in Figma. A contract entry with no token
+// means Figma is ahead, which is a reference for what to build next.
+const contractPaths=new Set(CONTRACT.keys());
+const authoredPaths=new Set(Object.keys(all));
+const figmaAhead=[...contractPaths].filter(p=>!authoredPaths.has(p));
+if(uncontracted.size>0){
+  console.log(`\u26a0 ${uncontracted.size} token(s) have no Figma codeSyntax; their names are inferred, not agreed:`);
+  for(const p of [...uncontracted].sort().slice(0,10))console.log(`  \u00b7 ${p}`);
+}
+if(figmaAhead.length>0)console.log(`\u2139 Figma defines ${figmaAhead.length} variables this build does not emit yet (see src/figma-code-syntax.txt)`);
+console.log(`Built ${tokenPaths.length} Oneli8 tokens for CSS, TypeScript, Tailwind, and Figma.`);

package/scripts/test.mjs

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import assert from "node:assert/strict";
+import {pathToFileURL,fileURLToPath} from "node:url";
+import path from "node:path";
+
+const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),"..");
+await import(pathToFileURL(path.join(root,"scripts/build.mjs")));
+const read=relative=>fs.readFileSync(path.join(root,relative),"utf8");
+const json=relative=>JSON.parse(read(relative));
+let checks=0;
+const ok=(condition,message)=>{assert(condition,message);checks++};
+const primitive=json("src/primitive.json");
+const semantic=json("src/semantic.json");
+const themes=json("src/themes.json");
+const component=json("src/component.json");
+const status=json("status/components.json");
+const builtStatus=json("build/status/components.json");
+const manifest=json("build/manifest.json");
+const css=read("build/css/tokens.css");
+const tw=read("build/tailwind/preset.mjs");
+const tw4=read("build/tailwind/theme.css");
+const figma=json("build/figma/variables.json");
+const indices=["030","060","090","120","240","360","480","600","720","840","930"];
+const families=["blue","cyan","green","yellow","orange","pink","violet","red","neutral"];
+
+ok(primitive.dimension.scale["108"].$value.value===108,"108px primitive must ship");
+ok(semantic.spacing.section.expansive.$value==="{dimension.scale.108}","Expansive section must reference 108px primitive");
+ok(semantic.size.target.minimum.$value==="{dimension.scale.048}","Minimum target must reference 48px");
+ok(Object.values(semantic.size.icon).map(token=>token.$value).join(",")==="{dimension.scale.009},{dimension.scale.012},{dimension.scale.018},{dimension.scale.024},{dimension.scale.030},{dimension.scale.036},{dimension.scale.048},{dimension.scale.060},{dimension.scale.072},{dimension.scale.096},{dimension.scale.108}","Icon Frame semantic scale must expose all eleven approved presentations");
+ok(semantic.shape.radius.full.$extensions["oneli8.exception"]==="categorical-full-radius","Full radius exception must be explicit");
+ok(semantic.border.width.standard.$extensions["oneli8.exception"]==="essential-optical-boundary","2px essential border exception must be explicit");
+ok(semantic.typography.body.medium.$value.fontWeight==="{font.weight.regular}","Body Medium must resolve through Regular 450");
+ok(primitive.motion.easing.standard.$value[0]===0.39,"Standard easing must retain 0.39 first control point");
+ok(primitive.motion.easing.exit.$value[0]===0.48,"Exit easing must retain 0.48 first control point");
+ok(semantic.material.gem.opacity.environmental.$value===0.48,"Gem Environmental tint floor must be encoded");
+ok(css.includes("--ol8-spacing-section-expansive: 108px"),"CSS must contain resolved Semantic spacing");
+ok(css.includes("--ol8-typography-body-medium-font-weight: 450"),"CSS must resolve typography composition");
+ok(css.includes('[data-ol8-type-mode="expanded"]'),"CSS must contain independent expanded typography mode");
+ok(tw.includes('"1": "3px"')&&tw.includes('"36": "108px"')&&tw.includes('"regular": "450"'),"Tailwind v3 preset must expose the familiar 3px-indexed scale and weights");
+ok(tw4.includes("@theme")&&tw4.includes("--spacing-1: 3px")&&tw4.includes("--spacing-36: 108px"),"Tailwind v4 theme bridge must expose the 3px-indexed scale");
+ok(figma.modeAxes.typographyViewport.join(",")==="compact,medium,expanded","Figma data must retain viewport modes");
+ok(figma.typographyStyles.length===9,"Figma data must emit exactly nine default typography styles");
+ok(manifest.outputs.length===7,"Build manifest must list all seven generated outputs");
+ok(manifest.counts.primitive>50&&manifest.counts.semantic>70,"Initial canonical slice must contain substantial approved coverage");
+ok(!/#(?:000|000000|fff|ffffff)(?![0-9a-f])/i.test([read("src/primitive.json"),read("src/semantic.json"),css].join("\n")),"Authored and generated tokens cannot contain pure black or pure white");
+ok(families.every(family=>indices.every(index=>primitive.color[family][index]?.$type==="color")),"Candidate 03 must contain nine complete eleven-step color families");
+ok(new Set(families.flatMap(family=>indices.map(index=>primitive.color[family][index].$value.toUpperCase()))).size===99,"Candidate 03 must retain 99 unique approved values");
+ok(primitive.color.blue["600"].$value==="#2C438B"&&primitive.color.neutral["930"].$value==="#151817"&&primitive.color.cyan["840"].$value==="#163F4B","Canonical color anchors must remain exact");
+ok(semantic.color.actionPrimary.default.$value==="{color.primary.600}"&&semantic.color.text.link.default.$value==="{color.primary.600}","Light Primary semantics must resolve through family aliases");
+ok(semantic.color.text.link.hover.$value==="{color.primary.720}"&&semantic.color.text.link.pressed.$value==="{color.primary.840}"&&semantic.color.text.link.visited.$value==="{color.violet.600}","Light Link states must resolve through qualified semantic aliases");
+ok(themes.colorScheme.dark.overrides["color.text.link.default"].$value==="{color.primary.120}"&&themes.colorScheme.dark.overrides["color.text.link.hover"].$value==="{color.primary.090}"&&themes.colorScheme.dark.overrides["color.text.link.pressed"].$value==="{color.primary.060}"&&themes.colorScheme.dark.overrides["color.text.link.visited"].$value==="{color.violet.120}","Dark Link states must retain the approved accessible family mapping");
+ok(semantic.color.focus.inner.$value==="{color.primary.030}"&&semantic.color.focus.outer.$value==="{color.primary.930}","Light Focus must use the active family's 030 highlight and 930 shadow");
+ok(themes.colorScheme.dark.overrides["color.focus.inner"].$value==="{color.primary.930}"&&themes.colorScheme.dark.overrides["color.focus.outer"].$value==="{color.primary.030}","Dark Focus must reverse the active family's 930 shadow and 030 highlight");
+ok(semantic.color.icon.onGem.$value==="{color.neutral.030}"&&!themes.colorScheme.dark.overrides["color.icon.onGem"],"On Gem icon artwork must remain near-white across Light and Dark appearances");
+ok(css.includes('[data-ol8-color-scheme="dark"]')&&css.includes('[data-ol8-primary="orange"]')&&css.includes('[data-ol8-primary="green"]'),"CSS must emit independent scheme and Primary-family axes");
+ok(css.includes("--ol8-color-actionprimary-default: var(--ol8-color-primary-600)")&&css.includes("--ol8-color-primary-600: var(--ol8-color-orange-600)"),"CSS color aliases must remain reference-preserving and composable");
+ok(tw.includes('"background-canvas": "var(--ol8-color-background-canvas)"')&&tw.includes('"action-primary-default": "var(--ol8-color-actionprimary-default)"'),"Tailwind v3 must expose Semantic colors rather than raw palette meaning");
+ok(tw4.includes("--color-ol8-background-canvas: var(--ol8-color-background-canvas)")&&tw4.includes("--color-ol8-action-primary-default: var(--ol8-color-actionprimary-default)"),"Tailwind v4 must expose Semantic color utilities");
+ok(figma.modes.colorScheme.dark.length>60&&figma.modes.primaryFamily.orange.length===11&&figma.modes.primaryFamily.green.length===11,"Figma data must preserve independent color modes");
+ok(semantic.elevation.surface.floating.$value.length===2&&semantic.elevation.surface.floating.$value[0].alpha===0.18,"Light Floating elevation must retain its approved two-shadow recipe");
+ok(themes.colorScheme.dark.overrides["elevation.surface.blocking"].$value[0].alpha===0.72,"Dark Blocking elevation must retain its 72% Cyan 840 cue");
+ok(Object.values(semantic.layer.stack).map(token=>token.$value).join(",")==="0,300,600,900,1200","Stacking tiers must retain the approved 300-step progression");
+ok(css.includes("--ol8-elevation-surface-overlay: 0px 12px 36px -6px rgb(22 63 75 / 0.24), 0px 6px 12px 0px rgb(22 63 75 / 0.18)"),"CSS must serialize approved multi-layer Elevation");
+ok(semantic.material.gem.color.quiet.environmentalFace.$value.alpha===0.48&&themes.colorScheme.dark.overrides["material.gem.color.quiet.environmentalFace"].$value.alpha===0.48&&semantic.material.gem.color.family.emerald.environmentalFace.$value.alpha===0.48&&semantic.material.gem.color.family.sapphire.stabilizedFace.$value.alpha===0.30,"Gem environmental and stabilized alpha values must remain approved");
+ok(semantic.material.gem.color.family.sapphire.innerHigh.$value.alpha===0.39,"Sapphire Thin-Cut highlight must retain its 39% cap");
+ok(semantic.material.control.gem.primary.start.$value==="{color.primary.480}"&&themes.colorScheme.dark.overrides["material.control.gem.primary.start"].$value==="{color.primary.600}","Gem controls must keep Light and Dark theme-aware leading stops");
+ok(semantic.material.control.gem.secondary.high.$value.alpha===0.22&&semantic.material.control.gem.rim.default.$value.alpha===0.24,"Gem Secondary transparency and inset rim must retain the approved quiet material recipe");
+ok(semantic.material.control.gem.primary.loadingStart.$value==="{color.primary.720}"&&semantic.material.control.gem.primary.loadingEnd.$value==="{color.primary.930}","Gem Loading must use a distinct shared deep tonal state");
+ok(semantic.material.control.gem.secondary.loadingHigh.$value.alpha===0.39&&semantic.material.control.gem.secondary.loadingLow.$value.alpha===0.24,"Gem Secondary Loading must remain transparent but visibly distinct");
+ok(css.includes("--ol8-material-gem-color-family-amethyst-environmentalface: color-mix(in srgb, var(--ol8-color-violet-930) 48%, transparent)"),"Gem CSS colors must preserve Primitive references and approved alpha");
+ok(tw.includes('"overlay": "var(--ol8-elevation-surface-overlay)"')&&tw.includes('"notification": "1200"'),"Tailwind v3 must expose Elevation and stacking roles");
+ok(tw4.includes("--shadow-ol8-blocking: var(--ol8-elevation-surface-blocking)")&&tw4.includes("--z-ol8-modal: 900"),"Tailwind v4 must expose Elevation and stacking roles");
+ok(figma.elevationStyles.length===5,"Figma data must emit five Elevation styles");
+ok(component.component.button.paddingInline.standard.$value.value===15&&component.component.button.gap.comfortable.$value.value===9,"Button component geometry must retain the approved 15px inset and 9px gap");
+ok(component.component.opticalStroke.$value.value===1.8&&component.component.opticalStroke.$extensions["oneli8.exception"]==="universal-optical-stroke","The universal canonical-source optical stroke must remain 1.8 units");
+ok(component.component.icon.stroke.$value==="{component.opticalStroke}","Icon Frame source must alias the universal optical stroke");
+ok(component.component.choice.opticalStroke.$value==="{component.opticalStroke}","Choice controls must alias the universal optical stroke");
+ok(component.component.checkbox.boundary.$value==="{component.choice.opticalStroke}"&&component.component.checkbox.mark.stroke.$value==="{component.choice.opticalStroke}"&&component.component.radio.boundary.$value==="{component.choice.opticalStroke}","Checkbox boundary, Checkbox mark, and Radio boundary must share the Choice optical stroke");
+ok(semantic.color.selection.surface.$value==="{color.primary.060}"&&themes.colorScheme.dark.overrides["color.selection.surface"].$value==="{color.primary.120}","Checkbox and Radio selected controls must share Selection Surface through the configurable Primary family");
+ok(component.component.radio.dot.compact.$value.value===9&&component.component.radio.dot.comfortable.$value.value===12,"Radio selected dots must retain the approved 9px and 12px geometry");
+ok(component.component.switch.travel.compact.$value==="{size.indicator.standard}"&&component.component.switch.travel.comfortable.$value==="{size.indicator.large}","Switch travel must resolve to approved 18px and 24px geometry");
+ok(semantic.color.control.thumb.$value==="{color.neutral.030}","Switch thumb must remain near-white across Light and Dark appearances");
+ok(component.component.selectionPopup.maximumBlock.standard.$value.value===288&&component.component.selectionPopup.maximumBlock.large.$value.value===360,"Selection popup maximum block sizes must retain the approved recipes");
+ok(component.component.selectionPopup.paddingInline.$value==="{spacing.inline.minimal}"&&component.component.selectionPopup.railInsetInline.$value==="{spacing.inline.minimal}"&&component.component.selectionPopup.paddingBlock.$value==="{spacing.inline.related}","Selection popup must retain the approved 3px + 3px visible edge and 6px block inset");
+ok(status.components.length===10&&new Set(status.components.map(record=>record.name)).size===10,"Status registry must contain ten unique public component records");
+ok(status.components.filter(record=>record.status==="Candidate").length===10&&status.components.filter(record=>record.status==="Labs").length===0,"All ten approved families must now have Candidate production implementations");
+ok(status.components.every(record=>record.designerApproved&&!record.implementationCertified&&record.knownEvidence.length>0&&record.missingEvidence.length>0),"Visual approval must remain separate from implementation certification");
+ok(builtStatus.generated===true&&builtStatus.components.length===status.components.length,"Generated status registry must preserve every authored record");
+ok(component.component.choiceChip.height.compact.$value.value===30&&component.component.choiceChip.height.standard.$value==="{size.control.compact}"&&component.component.choiceChip.height.comfortable.$value==="{size.control.standard}","Soft Hexagon visible heights must retain the approved 30px, 36px, and 42px geometry");
+ok(component.component.choiceChip.terminal.$value==="{spacing.inline.standard}"&&component.component.choiceChip.innerTerminal.$value.value===11,"Soft Hexagon terminal geometry must remain fixed rather than scaling with label length");
+ok(component.component.choiceChip.inset.compact.$value.value===21&&component.component.choiceChip.inset.standard.$value==="{spacing.inset.comfortable}"&&component.component.choiceChip.inset.comfortable.$value.value===27,"Soft Hexagon insets must retain the approved 21px, 24px, and 27px progression");
+ok(component.component.suggestionRail.gap.$value==="{component.choiceChip.gap}"&&component.component.suggestionRail.fieldSeparation.$value==="{spacing.stack.tight}","Suggested Values rail must reuse Choice Chip and structural spacing roles");
+ok(component.component.tabBar.gap.$value==="{spacing.none}"&&component.component.tabBar.inlineInset.$value==="{spacing.inline.minimal}","Tab Bar spacing must map to canonical zero gap and 3px Inline protection");
+ok(manifest.counts.primitive===170&&manifest.counts.semantic===270&&manifest.counts.component===152&&manifest.counts.componentStatuses===10&&manifest.counts.figmaVariables===578&&manifest.counts.figmaElevationStyles===5,"Navigation spacing and contextual token output counts must remain deterministic");
+
+console.log(`PASS ${checks}/${checks} canonical token package checks.`);