@apollion-dsi/tokens 5.2.0 → 5.4.0

package/lib/config-loader.esm.js

@@ -1,3 +1,3 @@
-var h=Object.defineProperty;var r=(n,i)=>h(n,"name",{value:i,configurable:!0});import{readFile as w}from"node:fs/promises";import{resolve as x}from"node:path";import{createContext as y,Script as C}from"node:vm";import{z as o}from"zod";var e=o.string().regex(/^#([0-9a-fA-F]{3}){1,2}$|^transparent$|^rgb\(.*\)$|^oklch\(.*\)$/,{message:'Must be hex, rgb(), oklch(), or "transparent"'}),b=o.object({baseDark:o.string().optional(),baseLight:o.string().optional(),deepDark:e,deepLight:e,transparent:o.string().optional(),main:e.optional(),opposite:e.optional(),complementary:e.optional(),information:e.optional(),success:e.optional(),danger:e.optional(),warning:e.optional(),primary:e.optional(),secondary:e.optional(),tertiary:e.optional()}).passthrough(),u=o.object({brands:o.record(o.string(),b).refine(n=>Object.keys(n).length>0,{message:"apollion.config.mjs: brands must contain at least 1 entry"}),modes:o.array(o.enum(["light","dark"])).optional(),surfaces:o.array(o.enum(["positive","negative"])).optional(),dimensions:o.array(o.enum(["compact","normal","spacious"])).optional(),output:o.object({runtime:o.boolean().optional(),css:o.boolean().optional(),json:o.boolean().optional(),ts:o.boolean().optional()}).passthrough().optional()}).passthrough();var _=[/\brequire\s*\(/,/\bimport\s*\(/,/^\s*import\s+/m],k=1e3;function v(n){return n}r(v,"defineConfig");var f=class f extends Error{constructor(s,p){super(s);this.configPath=p;this.name="ConfigLoadError"}};r(f,"ConfigLoadError");var a=f;async function I(n){let i=x(n.configPath),s=await w(i,"utf8");for(let t of _)if(t.test(s))throw new a(`apollion.config: dynamic require/import not allowed (matched ${t}). Declarative config only \u2014 see ADR-006 \xA73.8 B3.`,i);let p=s.replace(/(^|\n)\s*export\s+default\s+/,(t,l)=>`${l}__apollion_config_export = `);if(p===s)throw new a("apollion.config: missing `export default <object>;` \u2014 config must export a default object literal.",i);let g={__apollion_config_export:void 0,console:j(),Symbol,Number,String,Boolean,Array,Object,JSON,Math,defineConfig:r(t=>t,"defineConfig")},d=y(g);try{new C(p,{filename:i}).runInContext(d,{timeout:k})}catch(t){throw new a(`apollion.config: evaluation failed \u2014 ${t instanceof Error?t.message:String(t)}`,i)}let m=g.__apollion_config_export;if(m===void 0)throw new a("apollion.config: `export default` produced undefined.",i);let c=u.safeParse(m);if(!c.success){let t=c.error.issues.map(l=>`  ${l.path.join(".")||"(root)"}: ${l.message}`).join(`
+var h=Object.defineProperty;var r=(n,i)=>h(n,"name",{value:i,configurable:!0});import{readFile as w}from"node:fs/promises";import{resolve as x}from"node:path";import{createContext as y,Script as C}from"node:vm";import{z as o}from"zod";var e=o.string().regex(/^#([0-9a-fA-F]{3}){1,2}$|^transparent$|^rgb\(.*\)$|^oklch\(.*\)$/,{message:'Must be hex, rgb(), oklch(), or "transparent"'}),b=o.object({baseDark:o.string().optional(),baseLight:o.string().optional(),deepDark:e,deepLight:e,transparent:o.string().optional(),main:e.optional(),opposite:e.optional(),complementary:e.optional(),information:e.optional(),success:e.optional(),danger:e.optional(),warning:e.optional(),primary:e.optional(),secondary:e.optional(),tertiary:e.optional()}).passthrough(),u=o.object({brands:o.record(o.string(),b).refine(n=>Object.keys(n).length>0,{message:"apollion.config.mjs: brands must contain at least 1 entry"}),modes:o.array(o.enum(["light","dark"])).optional(),surfaces:o.array(o.enum(["positive","negative"])).optional(),dimensions:o.array(o.enum(["compact","normal","spacious"])).optional(),output:o.object({runtime:o.boolean().optional(),css:o.boolean().optional(),json:o.boolean().optional(),ts:o.boolean().optional(),designMd:o.boolean().optional(),tailwind:o.boolean().optional()}).passthrough().optional()}).passthrough();var _=[/\brequire\s*\(/,/\bimport\s*\(/,/^\s*import\s+/m],k=1e3;function v(n){return n}r(v,"defineConfig");var f=class f extends Error{constructor(s,p){super(s);this.configPath=p;this.name="ConfigLoadError"}};r(f,"ConfigLoadError");var a=f;async function I(n){let i=x(n.configPath),s=await w(i,"utf8");for(let t of _)if(t.test(s))throw new a(`apollion.config: dynamic require/import not allowed (matched ${t}). Declarative config only \u2014 see ADR-006 \xA73.8 B3.`,i);let p=s.replace(/(^|\n)\s*export\s+default\s+/,(t,l)=>`${l}__apollion_config_export = `);if(p===s)throw new a("apollion.config: missing `export default <object>;` \u2014 config must export a default object literal.",i);let g={__apollion_config_export:void 0,console:j(),Symbol,Number,String,Boolean,Array,Object,JSON,Math,defineConfig:r(t=>t,"defineConfig")},d=y(g);try{new C(p,{filename:i}).runInContext(d,{timeout:k})}catch(t){throw new a(`apollion.config: evaluation failed \u2014 ${t instanceof Error?t.message:String(t)}`,i)}let m=g.__apollion_config_export;if(m===void 0)throw new a("apollion.config: `export default` produced undefined.",i);let c=u.safeParse(m);if(!c.success){let t=c.error.issues.map(l=>`  ${l.path.join(".")||"(root)"}: ${l.message}`).join(`
 `);throw new a(`apollion.config: schema validation failed \u2014
 ${t}`,i)}return c.data}r(I,"loadConfig");function j(){return{log:r((...n)=>console.log("[apollion.config]",...n),"log"),warn:r((...n)=>console.warn("[apollion.config]",...n),"warn"),error:r((...n)=>console.error("[apollion.config]",...n),"error")}}r(j,"makeReadOnlyConsole");export{a as ConfigLoadError,v as defineConfig,I as loadConfig};

package/lib/config-schema.cjs

@@ -1 +1 @@
-"use strict";var t=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var b=Object.prototype.hasOwnProperty;var c=(o,n)=>t(o,"name",{value:n,configurable:!0});var D=(o,n)=>{for(var s in n)t(o,s,{get:n[s],enumerable:!0})},S=(o,n,s,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let e of f(n))!b.call(o,e)&&e!==s&&t(o,e,{get:()=>n[e],enumerable:!(r=u(n,e))||r.enumerable});return o};var g=o=>S(t({},"__esModule",{value:!0}),o);var F={};D(F,{expandVariants:()=>C,variantName:()=>E});module.exports=g(F);var x=["light","dark"],A=["positive","negative"],y=["compact","normal","spacious"];function C(o){let n=o.modes??x,s=o.surfaces??A,r=o.dimensions??y,e=Object.entries(o.brands).sort(([i],[a])=>i.localeCompare(a)),d=[];for(let[i,a]of e)for(let l of n)for(let p of s)for(let m of r)d.push({brand:i,colors:a,mode:l,surface:p,dimension:m});return d}c(C,"expandVariants");function E(o){return`${o.brand}.${o.mode}.${o.surface}.${o.dimension}`}c(E,"variantName");0&&(module.exports={expandVariants,variantName});
+"use strict";var t=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var b=Object.prototype.hasOwnProperty;var c=(o,n)=>t(o,"name",{value:n,configurable:!0});var g=(o,n)=>{for(var s in n)t(o,s,{get:n[s],enumerable:!0})},D=(o,n,s,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let e of f(n))!b.call(o,e)&&e!==s&&t(o,e,{get:()=>n[e],enumerable:!(r=u(n,e))||r.enumerable});return o};var S=o=>D(t({},"__esModule",{value:!0}),o);var M={};g(M,{expandVariants:()=>C,variantName:()=>E});module.exports=S(M);var x=["light","dark"],A=["positive","negative"],y=["compact","normal","spacious"];function C(o){let n=o.modes??x,s=o.surfaces??A,r=o.dimensions??y,e=Object.entries(o.brands).sort(([i],[a])=>i.localeCompare(a)),d=[];for(let[i,a]of e)for(let l of n)for(let p of s)for(let m of r)d.push({brand:i,colors:a,mode:l,surface:p,dimension:m});return d}c(C,"expandVariants");function E(o){return`${o.brand}.${o.mode}.${o.surface}.${o.dimension}`}c(E,"variantName");0&&(module.exports={expandVariants,variantName});

package/lib/config-schema.esm.js

@@ -1 +1 @@
-var m=Object.defineProperty;var r=(o,n)=>m(o,"name",{value:n,configurable:!0});var u=["light","dark"],f=["positive","negative"],b=["compact","normal","spacious"];function S(o){let n=o.modes??u,i=o.surfaces??f,a=o.dimensions??b,c=Object.entries(o.brands).sort(([e],[s])=>e.localeCompare(s)),t=[];for(let[e,s]of c)for(let d of n)for(let l of i)for(let p of a)t.push({brand:e,colors:s,mode:d,surface:l,dimension:p});return t}r(S,"expandVariants");function g(o){return`${o.brand}.${o.mode}.${o.surface}.${o.dimension}`}r(g,"variantName");export{S as expandVariants,g as variantName};
+var m=Object.defineProperty;var r=(o,n)=>m(o,"name",{value:n,configurable:!0});var u=["light","dark"],f=["positive","negative"],b=["compact","normal","spacious"];function D(o){let n=o.modes??u,i=o.surfaces??f,a=o.dimensions??b,c=Object.entries(o.brands).sort(([e],[s])=>e.localeCompare(s)),t=[];for(let[e,s]of c)for(let d of n)for(let l of i)for(let p of a)t.push({brand:e,colors:s,mode:d,surface:l,dimension:p});return t}r(D,"expandVariants");function S(o){return`${o.brand}.${o.mode}.${o.surface}.${o.dimension}`}r(S,"variantName");export{D as expandVariants,S as variantName};

package/lib/runtime/v1.cjs

@@ -1 +1 @@
-"use strict";var m=Object.defineProperty;var E=Object.getOwnPropertyDescriptor;var M=Object.getOwnPropertyNames;var P=Object.prototype.hasOwnProperty;var l=(t,e)=>m(t,"name",{value:e,configurable:!0});var D=(t,e)=>{for(var r in e)m(t,r,{get:e[r],enumerable:!0})},F=(t,e,r,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of M(e))!P.call(t,n)&&n!==r&&m(t,n,{get:()=>e[n],enumerable:!(o=E(e,n))||o.enumerable});return t};var R=t=>F(m({},"__esModule",{value:!0}),t);var H={};D(H,{TOKENS_RUNTIME_API_VERSION:()=>B,createFoundation:()=>y.createFoundation,createSpacing:()=>O,getOppositeColor:()=>b,invertForSurface:()=>C.invertForSurface,mountGreyscaleColors:()=>L,mountNeutralColors:()=>A,mountSingleColor:()=>v});module.exports=R(H);var a=require("culori");var h=(0,a.converter)("oklch");function i(t,e,r){let o=(0,a.parse)(t),n=(0,a.parse)(e);if(!o||!n)return t;let c=(0,a.interpolate)([o,n],"oklch");return(0,a.formatHex)(c(r))??t}l(i,"mixOklch");function k(t){return t?typeof t=="string"?t:t.base:"#000"}l(k,"coerceToHex");function b(t){let e=k(t),r=h((0,a.parse)(e));if(!r)return e;let o={...r,h:((r.h??0)+180)%360};return(0,a.formatHex)(o)??e}l(b,"getOppositeColor");var d=1.3,G=.05,S=.04,u=l((t,e)=>{let r=(0,a.parse)(t),o=(0,a.parse)(e);return!r||!o?1:(0,a.wcagContrast)(r,o)},"contrastRatio"),g=l(t=>{let e=h((0,a.parse)(t));return e?e.l??0:null},"oklchLightness"),T=l((t,e)=>{if(u(t,e)>=d)return!0;let r=g(t),o=g(e);return r!==null&&o!==null&&Math.abs(r-o)>=G},"isPerceptibleState"),j=l(t=>t?u("#fff",t)>u("#000",t):!1,"isDarkSurface");function I(t,e,r){let o=h((0,a.parse)(t));if(!o)return null;let n={...o,l:r??o.l??0},c=e?S:-S;for(let s=0;s<25;s+=1){let f=Math.min(1,Math.max(0,(n.l??0)+c));if(f===(n.l??0))break;n={...n,l:f};let p=(0,a.formatHex)(n);if(p&&u(t,p)>=d)return p}return(0,a.formatHex)(n)??null}l(I,"derivePerceptibleState");function x(t,e,r){let o=I(t,e,r);if(o&&u(t,o)>=d)return o;let n=I(t,!e);return n&&u(t,n)>=d?n:o??n}l(x,"perceptibleStateFor");function v(t,e){let r=typeof t=="object"&&t!==null?t:void 0,o=k(t),n=e.deepDark,c=e.deepLight,s={base:o,dark:i(o,n,.6),action:i(o,n,.2),active:i(o,c,.6),light:i(o,c,.9)};if((0,a.parse)(o)){let f=j(e.baseLight),p=T(o,s.action);if(p||(s.action=x(o,f)??s.action),!T(o,s.active)){let _=p?void 0:g(s.action)??void 0;s.active=x(o,f,_)??s.active}}return r?{base:o,dark:r.dark??s.dark,action:r.action??s.action,active:r.active??s.active,light:r.light??s.light}:s}l(v,"mountSingleColor");function L(t){let e=t.deepLight,r=t.deepDark;return{0:e,5:i(e,r,.05),10:i(e,r,.1),20:i(e,r,.2),30:i(e,r,.3),40:i(e,r,.4),50:i(e,r,.5),60:i(e,r,.6),70:i(e,r,.7),80:i(e,r,.8),90:i(e,r,.9),100:i(e,r,1)}}l(L,"mountGreyscaleColors");function A(t){let e=t.deepLight,r=t.deepDark,o=typeof t.primary=="object"&&t.primary?t.primary.base:t.primary,n=l(s=>1/17*(s-1),"interpolation"),c=i(o,r,.5);return{0:i(c,e,n(18)),5:i(c,e,n(17.5)),10:i(c,e,n(17)),20:i(c,e,n(16)),30:i(c,e,n(15)),40:i(c,e,n(14)),50:i(c,e,n(13)),60:i(c,e,n(12)),70:i(c,e,n(11)),80:i(c,e,n(10)),90:i(c,e,n(9)),100:i(c,e,n(8)),110:i(c,e,n(7)),120:i(c,e,n(6)),130:i(c,e,n(5)),140:i(c,e,n(4)),150:i(c,e,n(3)),160:i(c,e,n(2)),170:c,180:i(c,r,.25)}}l(A,"mountNeutralColors");var N=require("@apollion-dsi/core/themes/dimension");function O({multiplier:t=.25,alias:e},r){let o=r!==void 0?N.DIMENSION_MULTIPLIERS[r]:t;return(...n)=>n.map(c=>{let s=typeof c=="string"?e[c]:c;return`${o*s}rem`}).join(" ")}l(O,"createSpacing");var y=require("@apollion-dsi/core/themes/foundation");var C=require("@apollion-dsi/core/themes/surface");var B="v1";0&&(module.exports={TOKENS_RUNTIME_API_VERSION,createFoundation,createSpacing,getOppositeColor,invertForSurface,mountGreyscaleColors,mountNeutralColors,mountSingleColor});
+"use strict";var g=Object.defineProperty;var P=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var D=Object.prototype.hasOwnProperty;var l=(e,t)=>g(e,"name",{value:t,configurable:!0});var R=(e,t)=>{for(var r in t)g(e,r,{get:t[r],enumerable:!0})},F=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of E(t))!D.call(e,n)&&n!==r&&g(e,n,{get:()=>t[n],enumerable:!(o=P(t,n))||o.enumerable});return e};var G=e=>F(g({},"__esModule",{value:!0}),e);var V={};R(V,{TOKENS_RUNTIME_API_VERSION:()=>U,createFoundation:()=>C.createFoundation,createSpacing:()=>O,getOppositeColor:()=>A,invertForSurface:()=>S.invertForSurface,mountGreyscaleColors:()=>N,mountNeutralColors:()=>M,mountSingleColor:()=>v});module.exports=G(V);var a=require("culori");var h=(0,a.converter)("oklch");function i(e,t,r){let o=(0,a.parse)(e),n=(0,a.parse)(t);if(!o||!n)return e;let c=(0,a.interpolate)([o,n],"oklch");return(0,a.formatHex)(c(r))??e}l(i,"mixOklch");function L(e){return e?typeof e=="string"?e:e.base:"#000"}l(L,"coerceToHex");function A(e){let t=L(e),r=h((0,a.parse)(t));if(!r)return t;let o={...r,h:((r.h??0)+180)%360};return(0,a.formatHex)(o)??t}l(A,"getOppositeColor");var d=1.3,j=.05,T=.04,f=l((e,t)=>{let r=(0,a.parse)(e),o=(0,a.parse)(t);return!r||!o?1:(0,a.wcagContrast)(r,o)},"contrastRatio"),y=l(e=>{let t=h((0,a.parse)(e));return t?t.l??0:null},"oklchLightness"),B=4.5;function x(e,t,r=B){let o=(0,a.parse)(t),n=h((0,a.parse)(e));if(!o||!n)return e;let c=f("#fff",t)>=f("#000",t)?.04:-.04;for(let s=0;s<25;s+=1){let u=(0,a.formatHex)(n)??e,p=(0,a.parse)(u);if(p&&(0,a.wcagContrast)(p,o)>=r)return u;let m=Math.min(1,Math.max(0,(n.l??0)+c));if(m===(n.l??0))break;n={...n,l:m}}return(0,a.formatHex)(n)??e}l(x,"readableColor");var I=l((e,t)=>{if(f(e,t)>=d)return!0;let r=y(e),o=y(t);return r!==null&&o!==null&&Math.abs(r-o)>=j},"isPerceptibleState"),H=l(e=>e?f("#fff",e)>f("#000",e):!1,"isDarkSurface");function b(e,t,r){let o=h((0,a.parse)(e));if(!o)return null;let n={...o,l:r??o.l??0},c=t?T:-T;for(let s=0;s<25;s+=1){let u=Math.min(1,Math.max(0,(n.l??0)+c));if(u===(n.l??0))break;n={...n,l:u};let p=(0,a.formatHex)(n);if(p&&f(e,p)>=d)return p}return(0,a.formatHex)(n)??null}l(b,"derivePerceptibleState");function k(e,t,r){let o=b(e,t,r);if(o&&f(e,o)>=d)return o;let n=b(e,!t);return n&&f(e,n)>=d?n:o??n}l(k,"perceptibleStateFor");function v(e,t){let r=typeof e=="object"&&e!==null?e:void 0,o=L(e),n=t.deepDark,c=t.deepLight,s={base:o,dark:i(o,n,.6),action:i(o,n,.2),active:i(o,c,.6),light:i(o,c,.9),onLight:o};if((0,a.parse)(o)){let u=H(t.baseLight),p=I(o,s.action);if(p||(s.action=k(o,u)??s.action),!I(o,s.active)){let m=p?void 0:y(s.action)??void 0;s.active=k(o,u,m)??s.active}}if(s.onLight=x(s.action,s.light),r){let u=r.action??s.action,p=r.light??s.light;return{base:o,dark:r.dark??s.dark,action:u,active:r.active??s.active,light:p,onLight:r.onLight??x(u,p)}}return s}l(v,"mountSingleColor");function N(e){let t=e.deepLight,r=e.deepDark;return{0:t,5:i(t,r,.05),10:i(t,r,.1),20:i(t,r,.2),30:i(t,r,.3),40:i(t,r,.4),50:i(t,r,.5),60:i(t,r,.6),70:i(t,r,.7),80:i(t,r,.8),90:i(t,r,.9),100:i(t,r,1)}}l(N,"mountGreyscaleColors");function M(e){let t=e.deepLight,r=e.deepDark,o=typeof e.primary=="object"&&e.primary?e.primary.base:e.primary,n=l(s=>1/17*(s-1),"interpolation"),c=i(o,r,.5);return{0:i(c,t,n(18)),5:i(c,t,n(17.5)),10:i(c,t,n(17)),20:i(c,t,n(16)),30:i(c,t,n(15)),40:i(c,t,n(14)),50:i(c,t,n(13)),60:i(c,t,n(12)),70:i(c,t,n(11)),80:i(c,t,n(10)),90:i(c,t,n(9)),100:i(c,t,n(8)),110:i(c,t,n(7)),120:i(c,t,n(6)),130:i(c,t,n(5)),140:i(c,t,n(4)),150:i(c,t,n(3)),160:i(c,t,n(2)),170:c,180:i(c,r,.25)}}l(M,"mountNeutralColors");var _=require("@apollion-dsi/core/themes/dimension");function O({multiplier:e=.25,alias:t},r){let o=r!==void 0?_.DIMENSION_MULTIPLIERS[r]:e;return(...n)=>n.map(c=>{let s=typeof c=="string"?t[c]:c;return`${o*s}rem`}).join(" ")}l(O,"createSpacing");var C=require("@apollion-dsi/core/themes/foundation");var S=require("@apollion-dsi/core/themes/surface");var U="v1";0&&(module.exports={TOKENS_RUNTIME_API_VERSION,createFoundation,createSpacing,getOppositeColor,invertForSurface,mountGreyscaleColors,mountNeutralColors,mountSingleColor});

package/lib/runtime/v1.esm.js

@@ -1 +1 @@
-var k=Object.defineProperty;var s=(t,e)=>k(t,"name",{value:e,configurable:!0});import{converter as b,formatHex as m,interpolate as v,parse as l,wcagContrast as L}from"culori";var h=b("oklch");function i(t,e,r){let o=l(t),n=l(e);if(!o||!n)return t;let c=v([o,n],"oklch");return m(c(r))??t}s(i,"mixOklch");function I(t){return t?typeof t=="string"?t:t.base:"#000"}s(I,"coerceToHex");function A(t){let e=I(t),r=h(l(e));if(!r)return e;let o={...r,h:((r.h??0)+180)%360};return m(o)??e}s(A,"getOppositeColor");var d=1.3,N=.05,y=.04,u=s((t,e)=>{let r=l(t),o=l(e);return!r||!o?1:L(r,o)},"contrastRatio"),g=s(t=>{let e=h(l(t));return e?e.l??0:null},"oklchLightness"),C=s((t,e)=>{if(u(t,e)>=d)return!0;let r=g(t),o=g(e);return r!==null&&o!==null&&Math.abs(r-o)>=N},"isPerceptibleState"),O=s(t=>t?u("#fff",t)>u("#000",t):!1,"isDarkSurface");function S(t,e,r){let o=h(l(t));if(!o)return null;let n={...o,l:r??o.l??0},c=e?y:-y;for(let a=0;a<25;a+=1){let f=Math.min(1,Math.max(0,(n.l??0)+c));if(f===(n.l??0))break;n={...n,l:f};let p=m(n);if(p&&u(t,p)>=d)return p}return m(n)??null}s(S,"derivePerceptibleState");function T(t,e,r){let o=S(t,e,r);if(o&&u(t,o)>=d)return o;let n=S(t,!e);return n&&u(t,n)>=d?n:o??n}s(T,"perceptibleStateFor");function _(t,e){let r=typeof t=="object"&&t!==null?t:void 0,o=I(t),n=e.deepDark,c=e.deepLight,a={base:o,dark:i(o,n,.6),action:i(o,n,.2),active:i(o,c,.6),light:i(o,c,.9)};if(l(o)){let f=O(e.baseLight),p=C(o,a.action);if(p||(a.action=T(o,f)??a.action),!C(o,a.active)){let x=p?void 0:g(a.action)??void 0;a.active=T(o,f,x)??a.active}}return r?{base:o,dark:r.dark??a.dark,action:r.action??a.action,active:r.active??a.active,light:r.light??a.light}:a}s(_,"mountSingleColor");function E(t){let e=t.deepLight,r=t.deepDark;return{0:e,5:i(e,r,.05),10:i(e,r,.1),20:i(e,r,.2),30:i(e,r,.3),40:i(e,r,.4),50:i(e,r,.5),60:i(e,r,.6),70:i(e,r,.7),80:i(e,r,.8),90:i(e,r,.9),100:i(e,r,1)}}s(E,"mountGreyscaleColors");function M(t){let e=t.deepLight,r=t.deepDark,o=typeof t.primary=="object"&&t.primary?t.primary.base:t.primary,n=s(a=>1/17*(a-1),"interpolation"),c=i(o,r,.5);return{0:i(c,e,n(18)),5:i(c,e,n(17.5)),10:i(c,e,n(17)),20:i(c,e,n(16)),30:i(c,e,n(15)),40:i(c,e,n(14)),50:i(c,e,n(13)),60:i(c,e,n(12)),70:i(c,e,n(11)),80:i(c,e,n(10)),90:i(c,e,n(9)),100:i(c,e,n(8)),110:i(c,e,n(7)),120:i(c,e,n(6)),130:i(c,e,n(5)),140:i(c,e,n(4)),150:i(c,e,n(3)),160:i(c,e,n(2)),170:c,180:i(c,r,.25)}}s(M,"mountNeutralColors");import{DIMENSION_MULTIPLIERS as P}from"@apollion-dsi/core/themes/dimension";function D({multiplier:t=.25,alias:e},r){let o=r!==void 0?P[r]:t;return(...n)=>n.map(c=>{let a=typeof c=="string"?e[c]:c;return`${o*a}rem`}).join(" ")}s(D,"createSpacing");import{createFoundation as F}from"@apollion-dsi/core/themes/foundation";import{invertForSurface as R}from"@apollion-dsi/core/themes/surface";var z="v1";export{z as TOKENS_RUNTIME_API_VERSION,F as createFoundation,D as createSpacing,A as getOppositeColor,R as invertForSurface,E as mountGreyscaleColors,M as mountNeutralColors,_ as mountSingleColor};
+var L=Object.defineProperty;var s=(e,t)=>L(e,"name",{value:t,configurable:!0});import{converter as A,formatHex as m,interpolate as v,parse as u,wcagContrast as b}from"culori";var h=A("oklch");function i(e,t,r){let o=u(e),n=u(t);if(!o||!n)return e;let c=v([o,n],"oklch");return m(c(r))??e}s(i,"mixOklch");function k(e){return e?typeof e=="string"?e:e.base:"#000"}s(k,"coerceToHex");function N(e){let t=k(e),r=h(u(t));if(!r)return t;let o={...r,h:((r.h??0)+180)%360};return m(o)??t}s(N,"getOppositeColor");var d=1.3,M=.05,C=.04,f=s((e,t)=>{let r=u(e),o=u(t);return!r||!o?1:b(r,o)},"contrastRatio"),y=s(e=>{let t=h(u(e));return t?t.l??0:null},"oklchLightness"),_=4.5;function S(e,t,r=_){let o=u(t),n=h(u(e));if(!o||!n)return e;let c=f("#fff",t)>=f("#000",t)?.04:-.04;for(let a=0;a<25;a+=1){let p=m(n)??e,l=u(p);if(l&&b(l,o)>=r)return p;let g=Math.min(1,Math.max(0,(n.l??0)+c));if(g===(n.l??0))break;n={...n,l:g}}return m(n)??e}s(S,"readableColor");var T=s((e,t)=>{if(f(e,t)>=d)return!0;let r=y(e),o=y(t);return r!==null&&o!==null&&Math.abs(r-o)>=M},"isPerceptibleState"),O=s(e=>e?f("#fff",e)>f("#000",e):!1,"isDarkSurface");function x(e,t,r){let o=h(u(e));if(!o)return null;let n={...o,l:r??o.l??0},c=t?C:-C;for(let a=0;a<25;a+=1){let p=Math.min(1,Math.max(0,(n.l??0)+c));if(p===(n.l??0))break;n={...n,l:p};let l=m(n);if(l&&f(e,l)>=d)return l}return m(n)??null}s(x,"derivePerceptibleState");function I(e,t,r){let o=x(e,t,r);if(o&&f(e,o)>=d)return o;let n=x(e,!t);return n&&f(e,n)>=d?n:o??n}s(I,"perceptibleStateFor");function P(e,t){let r=typeof e=="object"&&e!==null?e:void 0,o=k(e),n=t.deepDark,c=t.deepLight,a={base:o,dark:i(o,n,.6),action:i(o,n,.2),active:i(o,c,.6),light:i(o,c,.9),onLight:o};if(u(o)){let p=O(t.baseLight),l=T(o,a.action);if(l||(a.action=I(o,p)??a.action),!T(o,a.active)){let g=l?void 0:y(a.action)??void 0;a.active=I(o,p,g)??a.active}}if(a.onLight=S(a.action,a.light),r){let p=r.action??a.action,l=r.light??a.light;return{base:o,dark:r.dark??a.dark,action:p,active:r.active??a.active,light:l,onLight:r.onLight??S(p,l)}}return a}s(P,"mountSingleColor");function E(e){let t=e.deepLight,r=e.deepDark;return{0:t,5:i(t,r,.05),10:i(t,r,.1),20:i(t,r,.2),30:i(t,r,.3),40:i(t,r,.4),50:i(t,r,.5),60:i(t,r,.6),70:i(t,r,.7),80:i(t,r,.8),90:i(t,r,.9),100:i(t,r,1)}}s(E,"mountGreyscaleColors");function D(e){let t=e.deepLight,r=e.deepDark,o=typeof e.primary=="object"&&e.primary?e.primary.base:e.primary,n=s(a=>1/17*(a-1),"interpolation"),c=i(o,r,.5);return{0:i(c,t,n(18)),5:i(c,t,n(17.5)),10:i(c,t,n(17)),20:i(c,t,n(16)),30:i(c,t,n(15)),40:i(c,t,n(14)),50:i(c,t,n(13)),60:i(c,t,n(12)),70:i(c,t,n(11)),80:i(c,t,n(10)),90:i(c,t,n(9)),100:i(c,t,n(8)),110:i(c,t,n(7)),120:i(c,t,n(6)),130:i(c,t,n(5)),140:i(c,t,n(4)),150:i(c,t,n(3)),160:i(c,t,n(2)),170:c,180:i(c,r,.25)}}s(D,"mountNeutralColors");import{DIMENSION_MULTIPLIERS as R}from"@apollion-dsi/core/themes/dimension";function F({multiplier:e=.25,alias:t},r){let o=r!==void 0?R[r]:e;return(...n)=>n.map(c=>{let a=typeof c=="string"?t[c]:c;return`${o*a}rem`}).join(" ")}s(F,"createSpacing");import{createFoundation as G}from"@apollion-dsi/core/themes/foundation";import{invertForSurface as j}from"@apollion-dsi/core/themes/surface";var W="v1";export{W as TOKENS_RUNTIME_API_VERSION,G as createFoundation,F as createSpacing,N as getOppositeColor,j as invertForSurface,E as mountGreyscaleColors,D as mountNeutralColors,P as mountSingleColor};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apollion-dsi/tokens",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "Apollion Design System — Framework-agnostic design tokens",
   "homepage": "https://www.apollion.com.br",
   "license": "MIT",
@@ -37,6 +37,7 @@
     "./dist/json/sets/*": "./dist/json/sets/*",
     "./dist/json/*": "./dist/json/*",
     "./dist/ts/*": "./dist/ts/*",
+    "./dist/tailwind/*": "./dist/tailwind/*",
     "./dist/manifest.json": "./dist/manifest.json"
   },
   "sideEffects": false,
@@ -66,7 +67,7 @@
   },
   "devDependencies": {
     "@apollion-dsi/core": "workspace:*",
-    "@apollion-dsi/eslint-config": "0.9.0",
+    "@apollion-dsi/eslint-config": "0.9.1",
     "@types/culori": "4.0.1",
     "@types/jest": "30.0.0",
     "@types/node": "25.7.0",

package/src/build.ts

@@ -19,8 +19,11 @@
  * Verified by `__tests__/build.test.ts`.
  *
  * **`--check` mode (CI gate):** read existing `manifest.json`, recompute
- * the expected manifest from current config, compare. Exit 1 on drift.
- * Never writes anything. Suitable for pre-push hook or local lint.
+ * `configHash` from current config, then re-hash every file the manifest
+ * lists and compare against its recorded sha256 — `configHash` alone only
+ * proves "the input didn't change", not "dist/ still reflects it" (a file
+ * can be hand-edited or corrupted without touching config). Exit 1 on
+ * drift. Never writes anything. Suitable for pre-push hook or local lint.
  *
  * @see ADR-006 §3.5 (atomic+idempotent build)
  * @see PRD-002 §S5 acceptance (rerun byte-identical, --check blocks drift)
@@ -31,7 +34,9 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 
 import { renderCss } from './renderers/css';
+import { renderDesignMd } from './renderers/design-md';
 import { renderBaseSet, renderColorSet, renderFontSet, renderResolver, renderSpacingSet } from './renderers/resolver';
+import { renderTailwindPreset, renderTwMergeExtension } from './renderers/tailwind';
 import { renderTs } from './renderers/ts';
 import type { ApollionConfig, Variant } from './config-schema';
 import { expandVariants, variantName } from './config-schema';
@@ -127,11 +132,37 @@ export async function build(opts: BuildOptions): Promise<BuildResult> {
         const ir = buildFullIR(foundation, colors, variant);
         const baseName = variantName(variant);
 
-        if (output.css) await emit(`css/${baseName}.css`, renderCss(ir));
+        if (output.css) await emit(`css/${baseName}.css`, renderCss(ir, { rgbCompanions: output.tailwind }));
         if (output.ts) await emit(`ts/${baseName}.d.ts`, renderTs(ir));
       }
     }
 
+    // ── Tailwind surface: preset + tw-merge extension (naming layer) ─────────
+    // Token *topology* is variant-invariant (same groups/keys across the axes),
+    // and every entry maps through `var(--apollion-*)` indirection — so one
+    // preset serves all variants. The first expanded variant is the
+    // representative (deterministic: `expandVariants` ordering is stable).
+    if (output.tailwind) {
+      const variant = variants[0];
+      const { foundation, colors } = buildVariantThemes(variant);
+      const ir = buildFullIR(foundation, colors, variant);
+      await emit('tailwind/preset.mjs', renderTailwindPreset(ir));
+      await emit('tailwind/tw-merge.mjs', renderTwMergeExtension(ir));
+    }
+
+    // ── Design.md surface: resolved-values AI context, one doc per brand ─────
+    if (output.designMd) {
+      const brands = [...new Set(variants.map((v) => v.brand))];
+      for (const brand of brands) {
+        const brandVariants = variants.filter((v) => v.brand === brand);
+        const irs = brandVariants.map((variant) => {
+          const { foundation, colors } = buildVariantThemes(variant);
+          return buildFullIR(foundation, colors, variant);
+        });
+        await emit(`design/${brand}.design.md`, renderDesignMd(brand, irs));
+      }
+    }
+
     const manifest: BuildManifest = {
       configHash: hashConfig(config),
       files,
@@ -170,7 +201,22 @@ export async function check(opts: { config: ApollionConfig; outDir: string }): P
   } catch {
     return false; // no manifest = needs build
   }
-  return current.configHash === hashConfig(config);
+  if (current.configHash !== hashConfig(config)) return false;
+
+  // configHash only proves the input didn't change — re-verify each emitted
+  // file's bytes still match what the manifest recorded, so a hand-edited or
+  // corrupted dist/ file (config untouched) is still caught as drift.
+  for (const entry of current.files) {
+    let content: Buffer;
+    try {
+      content = await readFile(join(outDir, entry.path));
+    } catch {
+      return false; // file missing
+    }
+    if (sha256(content) !== entry.sha256) return false;
+  }
+
+  return true;
 }
 
 async function writeAt(root: string, relativePath: string, content: string): Promise<void> {

package/src/builders/colors.ts

@@ -67,13 +67,13 @@ export function getOppositeColor(color: AcceptColorType): string {
   return formatHex(rotated) ?? hex;
 }
 
-/** Piso perceptual base↔estado de interação (razão WCAG) — espelho do core (ADR-012). */
+/** Perceptual state floor between base and interaction state (WCAG ratio) — mirror of the core (ADR-012). */
 const MIN_STATE_CONTRAST = 1.3;
 
-/** ΔL OKLch JND — critério alternativo onde a razão WCAG satura (quase-preto). */
+/** ΔL OKLch JND — alternative criterion where the WCAG ratio saturates (near-black). */
 const STATE_DELTA_L_JND = 0.05;
 
-/** Passo de L por iteração na correção de estado. */
+/** L step per iteration during state correction. */
 const STATE_L_STEP = 0.04;
 
 const contrastRatio = (a: string, b: string): number => {
@@ -88,6 +88,34 @@ const oklchLightness = (color: string): number | null => {
   return parsed ? (parsed.l ?? 0) : null;
 };
 
+/** WCAG AA contrast floor (normal text) — mirror of the core. */
+const MIN_CONTRAST_AA = 4.5;
+
+/**
+ * Adjusts the OKLch L of `color` until it passes `minRatio` against `background`,
+ * preserving hue/chroma — **byte-for-byte mirror** of the core's `readableColor`
+ * (`Colors.helpers.ts`; parity.test.ts). Used to derive the tonal ink
+ * `onLight` (APOLLION-CONTRAST-GUARANTEE).
+ */
+function readableColor(color: string, background: string, minRatio = MIN_CONTRAST_AA): string {
+  const bgParsed = parse(background);
+  let oklch = toOklch(parse(color));
+  if (!bgParsed || !oklch) return color;
+
+  const step = contrastRatio('#fff', background) >= contrastRatio('#000', background) ? 0.04 : -0.04;
+
+  for (let i = 0; i < 25; i += 1) {
+    const hex = formatHex(oklch) ?? color;
+    const parsed = parse(hex);
+    if (parsed && wcagContrast(parsed, bgParsed) >= minRatio) return hex;
+    const nextL = Math.min(1, Math.max(0, (oklch.l ?? 0) + step));
+    if (nextL === (oklch.l ?? 0)) break;
+    oklch = { ...oklch, l: nextL };
+  }
+
+  return formatHex(oklch) ?? color;
+}
+
 const isPerceptibleState = (base: string, candidate: string): boolean => {
   if (contrastRatio(base, candidate) >= MIN_STATE_CONTRAST) return true;
   const baseL = oklchLightness(base);
@@ -129,9 +157,9 @@ function perceptibleStateFor(base: string, surfaceIsDark: boolean, startL?: numb
 }
 
 /**
- * Derive `{ base, dark, action, active, light }` via OKLch lerp, com piso
- * perceptual mode-aware nos estados de interação — espelho byte-a-byte do
- * core (ADR-012; parity.test.ts). Overrides por slot passam verbatim.
+ * Derive `{ base, dark, action, active, light }` via OKLch lerp, with a
+ * mode-aware perceptual state floor on the interaction states — byte-for-byte
+ * mirror of the core (ADR-012; parity.test.ts). Per-slot overrides pass through verbatim.
  */
 export function mountSingleColor(
   color: AcceptColorType | ColorPalleteOverrideInterface,
@@ -148,6 +176,8 @@ export function mountSingleColor(
     action: mixOklch(base, darken!, 0.2),
     active: mixOklch(base, lighten!, 0.6),
     light: mixOklch(base, lighten!, 0.9),
+    // Placeholder — recomputed from the FINAL `action` below (mirror of the core).
+    onLight: base,
   };
 
   if (parse(base)) {
@@ -164,13 +194,19 @@ export function mountSingleColor(
     }
   }
 
+  // Tonal ink AA by construction (APOLLION-CONTRAST-GUARANTEE) — mirror of the core.
+  derived.onLight = readableColor(derived.action, derived.light);
+
   if (override) {
+    const finalAction = override.action ?? derived.action;
+    const finalLight = override.light ?? derived.light;
     return {
       base,
       dark: override.dark ?? derived.dark,
-      action: override.action ?? derived.action,
+      action: finalAction,
       active: override.active ?? derived.active,
-      light: override.light ?? derived.light,
+      light: finalLight,
+      onLight: override.onLight ?? readableColor(finalAction, finalLight),
     };
   }
 
@@ -202,7 +238,7 @@ export function mountGreyscaleColors(colors: ColorsInput): Record<GrayscaleColor
 export function mountNeutralColors(colors: ColorsInput): Record<NeutralColorsType, string> {
   const lighter = colors.deepLight!;
   const darker = colors.deepDark!;
-  // Slot pode ser override por slot (ADR-012) — a rampa ancora só no seed.
+  // The slot may be overridden per slot (ADR-012) — the ramp anchors on the seed only.
   const primary =
     typeof colors.primary === 'object' && colors.primary ? colors.primary.base : (colors.primary as string);
 

package/src/cli.ts

@@ -103,7 +103,7 @@ async function main(): Promise<void> {
     const ok = await check({ config, outDir: resolve(args.outDir) });
     if (!ok) {
       console.error(
-        `apollion-tokens: dist/ is stale or missing (configHash mismatch). Re-run \`apollion-tokens build\` without --check.`,
+        `apollion-tokens: dist/ is stale, missing, or has drifted from its manifest. Re-run \`apollion-tokens build\` without --check.`,
       );
       process.exit(1);
     }

package/src/config-schema-runtime.ts

@@ -57,6 +57,8 @@ export const ApollionConfigSchema = z
         css: z.boolean().optional(),
         json: z.boolean().optional(),
         ts: z.boolean().optional(),
+        designMd: z.boolean().optional(),
+        tailwind: z.boolean().optional(),
       })
       .passthrough()
       .optional(),

package/src/config-schema.ts

@@ -36,6 +36,15 @@ export interface ApollionOutputFlags {
   css?: boolean;
   json?: boolean;
   ts?: boolean;
+  /** `dist/design/<brand>.design.md` — resolved-values AI context per brand
+   * (YAML frontmatter + markdown body). See `renderers/design-md.ts`. */
+  designMd?: boolean;
+  /** `dist/tailwind/{preset,tw-merge}.mjs` — generated Tailwind preset mapping
+   * foundation tokens to theme keys (`var(--apollion-*)` indirection) plus a
+   * tailwind-merge extension derived from the same IR. Also adds `-rgb`
+   * channel-triplet companion vars to `dist/css/` so opaque colour tokens
+   * support Tailwind's alpha modifier. See `renderers/tailwind.ts`. */
+  tailwind?: boolean;
 }
 
 export interface ApollionConfig {
@@ -102,7 +111,7 @@ export function expandVariants(config: ApollionConfig): Variant[] {
 }
 
 /**
- * Stable variant filename (sem extension).
+ * Stable variant filename (without extension).
  * Format: `<brand>.<mode>.<surface>.<dimension>` — kebab where needed.
  */
 export function variantName(v: Variant): string {

package/src/ir.ts

@@ -258,6 +258,9 @@ function buildColorPrimitives(colors: ColorsThemeInterface): IRGroup {
       action: colorToken(palette.action),
       active: colorToken(palette.active),
       light: colorToken(palette.light),
+      // AA tonal pair (APOLLION-CONTRAST-GUARANTEE): ink legible over `light`,
+      // emitted as `--apollion-color-<palette>-on-light`.
+      onLight: colorToken(palette.onLight),
     };
   }
   out.grayscale = recordColorGroup(colors.grayscale);

package/src/manifest.ts

@@ -8,7 +8,7 @@
  *
  * **Threat-model fields (ADR-006 §3.9):** `gitCommit` and `buildEnv` give
  * provenance without requiring CI/SLSA-3 (decision Q-G9 — single-user org,
- * sem CI). `signedBy` slot reserved for sigstore in future PRD-003.
+ * no CI). `signedBy` slot reserved for sigstore in future PRD-003.
  *
  * @see ADR-006 §3.9 + §8.5 risk T1/R2
  * @see PRD-002 §S5

package/src/renderers/css.ts

@@ -13,6 +13,8 @@
  * @see ../ir.ts (source of truth) · ADR-006 §3.3 + §3.10 · tech-radar R3
  */
 
+import { colorPayload, isOpaqueColor, rgbTriplet } from './tailwind';
+
 import type { IRDocument, IRGroup } from '../ir';
 import { isToken, kebab, rawValue } from '../ir';
 
@@ -26,6 +28,28 @@ function emitVars(group: IRGroup, prefix: string[], lines: string[]): void {
   }
 }
 
+/**
+ * `-rgb` channel-triplet companions for opaque colour tokens (Tailwind
+ * `<alpha-value>` support — `output.tailwind` only). Projection rule shared
+ * with the preset renderer ({@link colorPayload}/{@link isOpaqueColor}/
+ * {@link rgbTriplet}) so preset entries and companions cannot drift.
+ *
+ * NEVER mirrored into the `@property` blocks — `syntax: '<color>'` is invalid
+ * for a channel triplet (`emitProperties` walks tokens, companions are not
+ * tokens, so the exclusion is structural).
+ */
+function emitRgbVars(group: IRGroup, prefix: string[], lines: string[]): void {
+  for (const [key, node] of Object.entries(group)) {
+    const path = [...prefix, kebab(key)];
+    if (!isToken(node)) {
+      emitRgbVars(node, path, lines);
+      continue;
+    }
+    const color = colorPayload(node);
+    if (color && isOpaqueColor(color)) lines.push(`  --apollion-${path.join('-')}-rgb: ${rgbTriplet(color)};`);
+  }
+}
+
 function emitProperties(group: IRGroup, prefix: string[], lines: string[]): void {
   for (const [key, node] of Object.entries(group)) {
     const path = [...prefix, kebab(key)];
@@ -39,13 +63,24 @@ function emitProperties(group: IRGroup, prefix: string[], lines: string[]): void
   }
 }
 
-export function renderCss(ir: IRDocument): string {
+export interface RenderCssOptions {
+  /** Emit `-rgb` channel-triplet companions for opaque colour tokens
+   * (`output.tailwind` — see {@link emitRgbVars}). Default false: the byte
+   * output without the flag is unchanged. */
+  rgbCompanions?: boolean;
+}
+
+export function renderCss(ir: IRDocument, options: RenderCssOptions = {}): string {
   const { brand, mode, surface, dimension } = ir.meta;
   const lines: string[] = [HEADER_LINE, ''];
 
   // Variant marker as a comment (NOT a var — keep cascade clean).
   lines.push(`/* Variant: brand=${brand} mode=${mode} surface=${surface} dimension=${dimension} */`, '', ':root {');
   emitVars(ir.groups, [], lines);
+  if (options.rgbCompanions) {
+    lines.push('', '  /* -rgb channel triplets — Tailwind <alpha-value> companions (opaque colour tokens only). */');
+    emitRgbVars(ir.groups, [], lines);
+  }
   lines.push('}', '');
 
   // @property declarations for color tokens — opt-in via @supports.

package/src/renderers/design-md.ts

@@ -0,0 +1,107 @@
+/**
+ * Design.md renderer — resolved-values AI context per brand.
+ *
+ * The rules layer (`llms.txt`) teaches *which* token to reach
+ * for; this emission supplies the *resolved values* those rules reference,
+ * generated from the consumer's own build so it can never drift from the
+ * shipped theme. YAML frontmatter for machines + a markdown body for humans.
+ *
+ * One document per brand, covering every (mode × surface × dimension) variant
+ * of that brand. Pure projection over per-variant `IRDocument`s — no value is
+ * computed here; a missing value is an IR gap by contract.
+ *
+ * @see ../../../../docs/references/design-md-decision.md (adoption decision)
+ * @see ../ir.ts (source of truth) · ./ts.ts (sibling resolved-surface renderer)
+ */
+
+import type { IRDocument, IRGroup } from '../ir';
+import { isToken, rawValue } from '../ir';
+
+const HEADER_LINE = '<!-- Generated by apollion-tokens build — DO NOT EDIT. See apollion.config.mjs. -->';
+
+/** Flatten a resolved IR group into dot-path → raw value pairs. */
+function flatten(group: IRGroup, prefix: string, out: Array<[string, string | number]>): void {
+  for (const [key, node] of Object.entries(group)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (isToken(node)) {
+      out.push([path, rawValue(node.value) as string | number]);
+    } else {
+      flatten(node, path, out);
+    }
+  }
+}
+
+function yamlEscape(value: string | number): string {
+  if (typeof value === 'number') return String(value);
+  // hex colors and px/rem strings are safe unquoted except when starting with
+  // YAML-significant characters — quote everything for uniformity/safety.
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function variantKey(ir: IRDocument): string {
+  const { mode, surface, dimension } = ir.meta;
+  return `${mode}.${surface}.${dimension}`;
+}
+
+/**
+ * Render one Design.md for a brand from its variant IRDocuments.
+ * Deterministic: variant order is the caller's (build order), path order is
+ * IR insertion order — both stable for a given config.
+ */
+export function renderDesignMd(brand: string, variants: readonly IRDocument[]): string {
+  if (variants.length === 0) {
+    throw new Error(`renderDesignMd: no variants for brand "${brand}"`);
+  }
+
+  // ── YAML frontmatter (machine surface) ────────────────────────────────────
+  const fm: string[] = ['---', `brand: '${brand}'`, 'generator: apollion-tokens', 'variants:'];
+  for (const ir of variants) {
+    const flat: Array<[string, string | number]> = [];
+    flatten(ir.groups, '', flat);
+    fm.push(`  ${variantKey(ir)}:`);
+    for (const [path, value] of flat) {
+      fm.push(`    ${path}: ${yamlEscape(value)}`);
+    }
+  }
+  fm.push('---');
+
+  // ── Markdown body (human surface) ─────────────────────────────────────────
+  const body: string[] = [
+    '',
+    HEADER_LINE,
+    '',
+    `# Design.md — ${brand}`,
+    '',
+    'Resolved design-token values for this brand, one section per variant.',
+    'Consumption rules (which token to reach for, layer boundaries) live in the',
+    'package `llms.txt`; this file carries the values those rules reference.',
+    'Regenerate with `apollion-tokens build` — never edit.',
+    '',
+  ];
+
+  for (const ir of variants) {
+    const { mode, surface, dimension } = ir.meta;
+    body.push(`## Variant \`${mode} · ${surface} · ${dimension}\``, '');
+    const flat: Array<[string, string | number]> = [];
+    flatten(ir.groups, '', flat);
+
+    // group rows by top-level namespace for readable tables
+    const byNs = new Map<string, Array<[string, string | number]>>();
+    for (const [path, value] of flat) {
+      const ns = path.split('.')[0] ?? path;
+      const rows = byNs.get(ns) ?? [];
+      rows.push([path, value]);
+      byNs.set(ns, rows);
+    }
+
+    for (const [ns, rows] of byNs) {
+      body.push(`### ${ns}`, '', '| Token | Value |', '| --- | --- |');
+      for (const [path, value] of rows) {
+        body.push(`| \`${path}\` | \`${value}\` |`);
+      }
+      body.push('');
+    }
+  }
+
+  return `${fm.join('\n')}\n${body.join('\n')}`;
+}

package/src/renderers/resolver.ts

@@ -10,9 +10,10 @@
  * manifest + O(brand·mode·surface + 2·dimension + 1) sets (spacing + font per
  * dimension).
  *
- * **S5 mode caveat:** `mode` is emitted as a real modifier (values + default)
- * even though palette generation is currently mode-agnostic (dark == light).
- * The topology is therefore correct ahead of S6 wiring real dark-mode logic.
+ * **Mode modifier:** `mode` is emitted as a real modifier (values + default),
+ * and since ADR-019 the dark contexts carry real values — palette generation
+ * derives dark through the canonical seed swap in `theme-factory.ts` (the S5
+ * dark == light placeholder is retired).
  *
  * Set documents are projected from `IRSlice`s via the shared `dtcg-project`
  * mapping, so a composed (base + color + spacing + font) tree is byte-equivalent