synthesisui 0.16.217 → 0.16.220

package/dist/commands/component.js

@@ -6,7 +6,7 @@ import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-templates.js";
 import { body, section, snippet } from "../output.js";
-import { findCollision, reactMajorOf, readInstalledConvention, } from "../project-facts.js";
+import { findCollision, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchComponent, RegistryError } from "../registry.js";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
@@ -157,7 +157,7 @@ export async function component(slug, name, opts) {
              * it, so the TSX and the stylesheet in the same folder agree by
              * construction. Falling back to disk keeps an older registry working.
              */
-            res.classNames ?? (await readInstalledConvention(root, slug)));
+            res.classNames ?? (await readInstalledConvention(root, slug)), res.name, await readInstalledScheme(root, slug));
             for (const file of files) {
                 await writeFile(join(compDir, file.filename), file.code, "utf8");
             }

package/dist/commands/doctor.js

@@ -8,7 +8,7 @@ import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, }
 import { checkContracts } from "../doctor/contract-check.js";
 import { describeMissing, missingDependencies, summarizeMissing, } from "../doctor/dependencies.js";
 import { findFrozenBindings } from "../doctor/frozen.js";
-import { appendEvent, readEvents, suggestionsFrom, summarize, } from "../doctor/ledger.js";
+import { appendEvent, COVERAGE_RULE, readEvents, suggestionsFrom, summarize, } from "../doctor/ledger.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { checkableName, readRequests, verifyAndCloseRequests, } from "../doctor/requests.js";
 import { diagnose, scanSource, siblingTokens, } from "../doctor/scan.js";
@@ -352,7 +352,15 @@ function verdict(d, hasSystem, overruled, conflicts) {
     }
     const lines = [
         ...head,
-        body(`${d.named} of ${d.findings.length} already have a name in your system.`),
+        /**
+         * "JÁ TÊM NOME" LEU COMO "JÁ ESTÃO NOMEADOS" - e o dono fez essa leitura em voz alta em 13/08:
+         * *"aqui diz que eu já tenho 243 nomeados no projeto, certo?"*. Não: os 243 estão DENTRO dos
+         * escritos à mão. O nome existe no sistema dele e o código continua escrevendo o literal.
+         *
+         * A frase estava tecnicamente correta e induziu a leitura errada em quem construiu a ferramenta.
+         * O verbo agora é do SISTEMA, não do valor: um nome ESPERA por eles.
+         */
+        body(`${d.named} of ${d.findings.length} have a name waiting in your system - still written as literals.`),
         body("Those are the cheap ones: swap the literal for the token."),
     ];
     if (d.findings.length > d.named) {
@@ -702,6 +710,7 @@ export async function doctor(opts) {
                 kind: "doctor",
                 at: new Date().toISOString(),
                 coverage: d.coverage,
+                rule: COVERAGE_RULE,
                 named: d.named,
                 ...(d.findings.some((f) => f.crossFamily)
                     ? { crossFamily: d.findings.filter((f) => f.crossFamily).length }
@@ -718,7 +727,7 @@ export async function doctor(opts) {
             console.log(body("and the page would change. Wire the two lines first."));
         }
         else {
-            console.log(body(`${d.named} of the ${d.findings.length} hand-written values found already have a name in`));
+            console.log(body(`${d.named} of the ${d.findings.length} hand-written values found have a name waiting in`));
             console.log(body("your system, and that number becomes actionable the moment both are true."));
         }
         return;
@@ -757,7 +766,46 @@ export async function doctor(opts) {
     if (hasSystem && measurable) {
         console.log("");
         console.log(body(`Token coverage  ${meter(d.coverage)}  ${paint.strong(`${String(d.coverage).padStart(3)}%`)}`));
-        console.log(body(paint.dim(`                ${d.tokenUses} from the system, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`)));
+        console.log(body(paint.dim(`                ${d.tokenUses} from the system${d.ownUses > 0 ? `, ${d.ownUses} from your own tokens` : ""}, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`)));
+        /**
+         * A CAMADA DE TOKEN DELE, CONTADA - e a decisão é do dono, em 13/08.
+         *
+         * `--ds-*` é normalização NOSSA, para poder governar. Um projeto que declara
+         * `--color-ocean-500: #059aed` no CSS global tem um design system de verdade, escrito antes de a
+         * gente existir. A régua tratava aquilo como se não existisse - não era cobertura e não era
+         * deriva -, e a tela dizia "1 do sistema" sobre um repositório com 93 variáveis próprias usadas
+         * 122 vezes: *"não está fazendo sentido ter apenas 1 token no sistema"*.
+         *
+         * E a linha seguinte é a que torna a adoção barata: 89 daquelas 93 seguram um valor que um
+         * `--ds-*` também segura. Apontar uma para a outra é uma linha por variável, num arquivo só - e
+         * os 122 usos seguem o sistema sem tocar em um componente sequer.
+         */
+        if (d.ownTokens > 0) {
+            console.log(body(paint.dim(`                ${d.ownTokens} token${d.ownTokens === 1 ? "" : "s"} of your own, used ${d.ownUses}x${d.ownMirrored > 0 ? ` - ${d.ownMirrored} hold a value this system also names` : ""}`)));
+            if (d.ownMirrored > 0)
+                console.log(body(paint.dim(`                point those at the \`--ds-*\` that holds it: ${d.ownMirrored} lines, one file`)));
+        }
+        /**
+         * O QUE UM COMANDO ALCANÇA, ao lado do que é verdade hoje - e são DUAS contas de propósito.
+         *
+         * O dono propôs em 13/08 usar os "já têm nome" como a porcentagem do medidor. A metade certa da
+         * proposta é que um `0%` sozinho não é acionável: ele descreve e não diz o que fazer. A metade
+         * que não pode acontecer é o medidor passar a mostrar a segunda conta - a barra andaria de 0 para
+         * 5 sem uma linha do app dele mudar, prometendo uma adoção que não aconteceu.
+         *
+         * Então o medidor segue medindo o que o código APONTA hoje, e o alcance vira uma linha ao lado,
+         * com o comando. O número já era impresso duas seções abaixo, solto: o que faltava era dizer que
+         * ele está a um comando de distância.
+         *
+         * Medido no repo do dono: 1 uso do sistema, 4 433 à mão, 243 com nome - o medidor diz 0% e a
+         * linha diz 5%.
+         */
+        const nameable = d.findings.filter((f) => f.token).length;
+        if (nameable > 0) {
+            const reach = Math.round(((d.tokenUses + nameable) / (d.tokenUses + d.findings.length)) * 100);
+            console.log(body(paint.dim(`                ${reach}% is one command away - ${nameable} of those have a name waiting`)));
+            console.log(body(paint.dim("                npx synthesisui doctor --fix")));
+        }
         /**
          * ZERO NUM REPO QUE ORIGINOU O SISTEMA É O ESTADO CERTO, e sem esta linha ele lê como falha
          * NOSSA.
@@ -773,7 +821,18 @@ export async function doctor(opts) {
          *
          * A lei 14 em uma linha: um zero pelado lê como falha nossa, um zero com motivo lê como fato.
          */
-        if (d.tokenUses === 0 && measured.system) {
+        /**
+         * A CONDIÇÃO É O QUE A TELA MOSTRA - e um único uso calava o parágrafo inteiro.
+         *
+         * Ela perguntava `tokenUses === 0`, e o medidor mostra a PORCENTAGEM: com 1 uso em 4 434
+         * valores, a barra diz `0%` e a explicação não sai. Foi exatamente o que o dono viu em 13/08 -
+         * *"Token coverage 0% · 1 from the system, 4433 by hand"*, sem uma linha dizendo por quê, que é
+         * o zero pelado que o comentário logo acima existe para impedir.
+         *
+         * O `1` não muda nada do que a frase afirma: os valores escritos à mão continuam sendo a FONTE
+         * de onde os tokens saíram, e não um desvio deles.
+         */
+        if (d.coverage === 0 && measured.system) {
             console.log(body(paint.dim(`                zero is the expected start here - this system was measured FROM`)));
             console.log(body(paint.dim(`                \`${measured.system}\`, so these values are its source, not a drift`)));
             console.log(body(paint.dim(`                from it. They count once the code points at the names they became.`)));
@@ -785,7 +844,7 @@ export async function doctor(opts) {
             const named = d.findings.filter((f) => f.token).length;
             if (named > 0) {
                 console.log("");
-                console.log(body(`${paint.strong(String(named))} of the ${d.findings.length} hand-written values already have a name in YOUR system.`));
+                console.log(body(`${paint.strong(String(named))} of the ${d.findings.length} hand-written values have a name waiting in YOUR system - they are still literals.`));
                 console.log(body(paint.dim("Your agent has no way to know: the tokens exist, the contract does not.")));
             }
         }
@@ -817,6 +876,8 @@ export async function doctor(opts) {
             kind: "doctor",
             at: new Date().toISOString(),
             coverage: d.coverage,
+            /** Qual régua mediu - ver `COVERAGE_RULE`. Sem isto a tendência compara duas réguas. */
+            rule: COVERAGE_RULE,
             named: d.named,
             ...(crossFamily > 0 ? { crossFamily } : {}),
             /** E os pares em si, para a plataforma reavaliar sem esperar outra medição - ver `matched`. */
@@ -842,6 +903,15 @@ export async function doctor(opts) {
             if (record.coverage && record.coverage.from !== record.coverage.to) {
                 console.log(body(`  coverage ${record.coverage.from}% → ${record.coverage.to}% since the first run.`));
             }
+            /**
+             * A RÉGUA MUDOU, DITO - em vez de um salto que ninguém fez.
+             *
+             * Quando a cobertura passou a contar a camada de token dele, o mesmo repositório saltou de 0%
+             * para 37% sem uma linha de código mudada. Somar as duas fotos anunciaria um progresso
+             * inventado; calar a mudança deixaria alguém procurar o que fez o número pular.
+             */
+            if (record.ruleChanged)
+                console.log(body("  the coverage ruler changed in 0.16.219 - your own tokens now count, so the trend restarts here."));
         }
     }
     /**
@@ -1077,8 +1147,8 @@ export async function doctor(opts) {
     if (frozen.length > 0) {
         say(section("These will not follow your other scheme"));
         say(body(frozen.length === 1
-            ? "One recipe names a primitive where a role holds the same value."
-            : `${frozen.length} recipes name a primitive where a role holds the same value.`));
+            ? "One recipe names a primitive where a SURFACE role of yours holds the same value."
+            : `${frozen.length} recipes name a primitive where a SURFACE role of yours holds the same value.`));
         say("");
         for (const f of frozen) {
             say(body(`ds-${f.component} · ${f.where}`));

package/dist/commands/generate.js

@@ -2,7 +2,7 @@ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
-import { reactMajorOf, readInstalledConvention } from "../project-facts.js";
+import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { postGenerate, RegistryError } from "../registry.js";
 /** PascalCase para o hint de import (course-card → CourseCard). */
 function pascalName(name) {
@@ -74,7 +74,7 @@ export async function generate(description, opts) {
         const files = generateComponentFiles(slug, res.name, res.recipe, res.css, version, config.styles, await reactMajorOf(root), 
         // Read off the installed document: a generated component lands in the same
         // project as the stylesheet it has to match.
-        await readInstalledConvention(root, slug));
+        await readInstalledConvention(root, slug), res.name, await readInstalledScheme(root, slug));
         for (const file of files) {
             await writeFile(join(compDir, file.filename), file.code, "utf8");
         }

package/dist/commands/refit.js

@@ -3,7 +3,7 @@ import { basename, join } from "node:path";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { body, section, snippet } from "../output.js";
-import { reactMajorOf, readInstalledConvention } from "../project-facts.js";
+import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchComponent, postRefit, postSaveComponent, RegistryError, } from "../registry.js";
 /** Slugs INSTALLED under `_synthesisui/ds/` (a `.lock` marks a real install -
  *  a folder holding only refit artifacts doesn't count). */
@@ -133,7 +133,7 @@ export async function refit(file, opts) {
     if (config.target === "next") {
         const compDir = join(root, config.componentsDir, res.name);
         await mkdir(compDir, { recursive: true });
-        const files = generateComponentFiles(slug, res.name, res.recipe, res.css, saved.version, config.styles, await reactMajorOf(root), await readInstalledConvention(root, slug));
+        const files = generateComponentFiles(slug, res.name, res.recipe, res.css, saved.version, config.styles, await reactMajorOf(root), await readInstalledConvention(root, slug), res.name, await readInstalledScheme(root, slug));
         for (const f of files) {
             await writeFile(join(compDir, f.filename), f.code, "utf8");
         }

package/dist/commands/upgrade.js

@@ -7,7 +7,7 @@ import { readProjectConfig, resolveRegistry } from "../config.js";
 import { diffLocalDocuments, localChangelogMarkdown, } from "../document-diff.js";
 import { installedBehind, MATERIALISER_SINCE } from "../install-marks.js";
 import { body, section, snippet } from "../output.js";
-import { reactMajorOf, readInstalledConvention } from "../project-facts.js";
+import { reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
 import { fetchChangelog, fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { add } from "./add.js";
 import { reportWhatIsLeft } from "./align.js";
@@ -300,7 +300,7 @@ export async function upgrade(asked, opts) {
                 // Both were missing here, and `upgrade` is the command that REWRITES
                 // components somebody already has: without the convention it would have
                 // taken a working component and stripped its styles.
-                await reactMajorOf(root), res.classNames ?? (await readInstalledConvention(root, slug)));
+                await reactMajorOf(root), res.classNames ?? (await readInstalledConvention(root, slug)), res.name, await readInstalledScheme(root, slug));
                 for (const file of files) {
                     await writeFile(join(componentsRoot, entry, file.filename), file.code, "utf8");
                 }

package/dist/component-codegen.js

@@ -192,12 +192,50 @@ function layerAxes(part, variants) {
     }
     return out;
 }
-/** The axes of a part: the ones it declares, plus the ones its layers read. */
+/**
+ * The axes of a NODE - root or part: the ones it declares, plus the ones its layers
+ * read. Both callers use this; a node that reads only `variants` is the reader that
+ * dropped 15 of his 19 components.
+ */
 function partAxesOf(part, variants) {
     const own = axesOf(part.variants ?? {});
     const keys = new Set(own.map((a) => a.key));
     return [...own, ...layerAxes(part, variants).filter((a) => !keys.has(a.key))];
 }
+/**
+ * THE AXES OF THE COMPONENT ITSELF - and an axis nothing styles is still his API.
+ *
+ * `axesOf` drops an axis whose every option block is empty, which is right for a
+ * recipe we generated: there the option IS the styles, so an empty one is noise we
+ * invented. On a recipe we READ it is the opposite. His `Card` declares
+ * `variant: default | full-border | left-border` and this document carries no
+ * declarations for any of the three - the axis is a fact about HIS component that
+ * we failed to read the look for, and dropping the prop would silently narrow the
+ * API his own call sites already use.
+ *
+ * So the prop and the `data-variant` ship. The missing look is a reading gap, and
+ * it is already counted as one - `gaps` and the ledger say so with a number, which
+ * is the honest place for it. Ten of his components sat in exactly this state.
+ */
+function rootAxes(recipe) {
+    const fromLayers = partAxesOf(recipe, recipe.variants);
+    const seen = new Set(fromLayers.map((a) => a.key));
+    const declared = [];
+    for (const [axis, options] of Object.entries(recipe.variants ?? {})) {
+        const keys = Object.keys(options);
+        if (keys.length === 0 || seen.has(axis))
+            continue;
+        declared.push({
+            key: axis,
+            prop: camel(axis),
+            attr: kebab(axis),
+            boolean: keys.every((k) => k === "true" || k === "false"),
+            styledFalse: keys.includes("false"),
+            options: keys,
+        });
+    }
+    return [...fromLayers, ...declared];
+}
 function axesOf(variants) {
     const axes = [];
     for (const [axis, options] of Object.entries(variants ?? {})) {
@@ -489,17 +527,196 @@ function declToTailwind(prop, value) {
     }
     return [arbitrary(prop, value)];
 }
-const STATE_PREFIX = {
-    hover: "hover:",
-    focus: "focus:",
-    focusVisible: "focus-visible:",
-    active: "active:",
-    disabled: "disabled:",
+/**
+ * TAILWIND'S OWN WORD FOR A STATE, WHEN IT HAS ONE - and a mechanical rule when it
+ * does not, because a hand-written table would be a table of LIBRARIES.
+ *
+ * The contract's `STATE_SELECTORS` is a closed vocabulary of about thirty states,
+ * and most of them are attribute-shaped on purpose: `pressed` is how @base-ui
+ * spells it, `highlighted` is the option the arrow keys are on, `startingStyle` is
+ * an enter animation. Naming each one here by hand would rot the moment the
+ * contract grows a thirty-first, and the CLI cannot import the contract (it ships
+ * standalone), so a mirror would be a second copy to keep in step.
+ *
+ * The rule instead: a state Tailwind already has a variant for uses that word;
+ * everything else becomes `data-[<kebab>]:`, which is exactly the selector the
+ * compiler emits for it. New state in the contract, no edit here.
+ */
+const TW_NATIVE = new Set([
+    "hover",
+    "active",
+    "checked",
+    "disabled",
+    "empty",
+    "even",
+    "first",
+    "indeterminate",
+    "invalid",
+    "last",
+    "odd",
+    "open",
+    "placeholder",
+    "read-only",
+    "required",
+    "target",
+    "visited",
+    "after",
+    "before",
+]);
+/**
+ * WHERE ONE STATE HAS MORE THAN ONE SPELLING, ALL OF THEM SHIP.
+ *
+ * `disabled` is `:disabled` on a real control, `[aria-disabled]` on an accessible
+ * div and `[data-disabled]` in every headless kit - the compiler matches all three
+ * with one comma-joined rule, and picking one here would be picking a library. In
+ * utilities that costs one extra class per declaration, on the handful of states
+ * that actually have two grammars.
+ */
+const TW_ALSO = {
+    disabled: ["aria-disabled:", "data-[disabled]:"],
+    checked: ["aria-checked:", "data-[checked]:"],
+    open: ["aria-expanded:", "data-[open]:"],
+    selected: ["aria-selected:", "data-[selected]:"],
 };
+/** A state name → every Tailwind variant that expresses it. */
+function twStateVariants(state) {
+    // The compiler maps both to `:focus-visible` - a focus ring that also shows on
+    // a mouse click is the one thing nobody wants back.
+    if (state === "focus" || state === "focusVisible")
+        return ["focus-visible:"];
+    const word = kebab(state);
+    const native = TW_NATIVE.has(word) ? [`${word}:`] : [`data-[${word}]:`];
+    return [...native, ...(TW_ALSO[state] ?? [])];
+}
 function blockToTailwind(block, prefix = "") {
     return Object.entries(block).flatMap(([prop, value]) => declToTailwind(prop, value).map((cls) => `${prefix}${cls}`));
 }
+/** Every prefix combination one layer needs. A condition that cannot be
+ *  expressed returns no combination, and the layer is dropped rather than
+ *  emitted wrong - the same choice the compiler makes for an unknown state. */
+function twPrefixes(when, at, scheme, 
+/** On the ROOT, `within` IS its own state - the compiler says so explicitly. */
+asRoot) {
+    const groups = [];
+    /**
+     * THE SCHEME THE DOCUMENT OPENS IN IS THE RESTING LOOK, and getting this
+     * backwards is the one mistake here that inverts light and dark. His document
+     * opens DARK, so its 79 `scheme: dark` layers are what the component looks like
+     * at rest and they take no prefix at all; `light` is the one that needs the
+     * ancestor. `compile-css.ts` decides it the same way, off `docScheme`.
+     */
+    if (when.scheme && when.scheme !== scheme) {
+        // Both attributes, because that is what the compiled stylesheet matches and a
+        // real project puts one or the other on <html>.
+        groups.push([
+            `[[data-scheme=${when.scheme}]_&]:`,
+            `[[data-theme=${when.scheme}]_&]:`,
+        ]);
+    }
+    if (when.within) {
+        const own = twStateVariants(when.within);
+        if (own.length === 0)
+            return [];
+        groups.push(asRoot ? own : own.map((v) => `group-${v}`));
+    }
+    if (when.state) {
+        const own = twStateVariants(when.state);
+        if (own.length === 0)
+            return [];
+        groups.push(own);
+    }
+    for (const [axis, option] of Object.entries(when.variant ?? {})) {
+        // `!option` is every OTHER option - `not-data-[…]` is the utility for the
+        // `:not()` the compiler writes.
+        groups.push(option.startsWith("!")
+            ? [`not-data-[${kebab(axis)}=${option.slice(1)}]:`]
+            : [`data-[${kebab(axis)}=${option}]:`]);
+    }
+    if (at)
+        groups.push([`${at}:`]);
+    return groups.reduce((acc, group) => acc.flatMap((prefix) => group.map((g) => `${prefix}${g}`)), [""]);
+}
+function resolveNode(node, scheme, asRoot) {
+    const variants = {};
+    for (const [axis, options] of Object.entries(node.variants ?? {})) {
+        variants[axis] = {};
+        for (const [option, block] of Object.entries(options))
+            variants[axis][option] = { ...block };
+    }
+    const states = {};
+    for (const [state, block] of Object.entries(node.states ?? {}))
+        states[state] = { ...block };
+    const conditional = [];
+    for (const layer of node.layers ?? []) {
+        if (!layer.style || Object.keys(layer.style).length === 0)
+            continue;
+        const when = { ...(layer.when ?? {}) };
+        /**
+         * A LAYER FOR THE DOCUMENT'S OWN SCHEME CARRIES NO CONDITION - dropping the key
+         * here is what lets `{scheme: dark, variant: ocean}` land in the variant map as
+         * plain `ocean`, instead of being pushed into a compound prefix nobody needs.
+         */
+        if (when.scheme === scheme)
+            delete when.scheme;
+        const axes = Object.entries(when.variant ?? {});
+        const simpleVariant = !layer.at &&
+            !when.state &&
+            !when.within &&
+            !when.scheme &&
+            axes.length === 1 &&
+            !axes[0][1].startsWith("!");
+        const simpleState = !layer.at &&
+            !when.within &&
+            !when.scheme &&
+            axes.length === 0 &&
+            Boolean(when.state);
+        if (simpleVariant) {
+            const [axis, option] = axes[0];
+            variants[axis] = variants[axis] ?? {};
+            variants[axis][option] = { ...variants[axis][option], ...layer.style };
+            continue;
+        }
+        if (simpleState && when.state) {
+            states[when.state] = { ...states[when.state], ...layer.style };
+            continue;
+        }
+        for (const prefix of twPrefixes(when, layer.at, scheme, asRoot))
+            conditional.push({ prefix, style: layer.style });
+    }
+    /**
+     * AND THE TOGGLE HAS TO BE ABLE TO UNDO THE RESTING LOOK.
+     *
+     * A part reads as `base: bg-white` + a `dark` layer; on a dark document that
+     * layer is correct bare, but bare it also wins when somebody flips to light. So
+     * every property a resting-scheme layer overrides gets its BASE value back under
+     * the other scheme's ancestor - the same rule `compile-css.ts` applies, and
+     * without it the flip is one-way.
+     */
+    const alt = scheme === "dark" ? "light" : "dark";
+    for (const layer of node.layers ?? []) {
+        if (layer.when?.scheme !== scheme)
+            continue;
+        if (layer.when?.state || layer.when?.within)
+            continue;
+        const restore = {};
+        for (const prop of Object.keys(layer.style ?? {}))
+            if (node.base?.[prop] != null)
+                restore[prop] = node.base[prop];
+        if (Object.keys(restore).length === 0)
+            continue;
+        for (const prefix of [
+            `[[data-scheme=${alt}]_&]:`,
+            `[[data-theme=${alt}]_&]:`,
+        ])
+            conditional.push({ prefix, style: restore });
+    }
+    return { variants, states, conditional };
+}
+/** The classes every compound condition contributes, in layer order. */
+const conditionalClasses = (resolved) => resolved.conditional.flatMap((c) => blockToTailwind(c.style, c.prefix));
 function tailwindClassList(recipe, 
+/** The node's states and compound conditions, already read off its layers. */
+resolved, 
 /** CSS properties a variant axis owns - see `variantOwnedProps`. */
 exclude) {
     const base = exclude
@@ -509,7 +726,10 @@ exclude) {
         ...blockToTailwind(base),
         // States keep everything: `hover:` and `disabled:` cannot collide with an
         // unprefixed variant class, so there is nothing to resolve.
-        ...Object.entries(recipe.states ?? {}).flatMap(([state, block]) => STATE_PREFIX[state] ? blockToTailwind(block, STATE_PREFIX[state]) : []),
+        ...Object.entries(resolved.states).flatMap(([state, block]) => twStateVariants(state).flatMap((prefix) => blockToTailwind(block, prefix))),
+        // Compound conditions last: they are the most specific thing the recipe says,
+        // and in utilities the later class is the one a reader expects to win.
+        ...conditionalClasses(resolved),
     ];
     return classes.join(" ");
 }
@@ -771,7 +991,16 @@ function emitCssMode(slug, name, recipe, version, props, convention,
 localName = name) {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const el = asElement(tag, attrs, voidEl);
-    const axes = axesOf(recipe.variants);
+    /**
+     * THE ROOT READS ITS AXES THE SAME WAY ITS PARTS DO, which is the whole fix.
+     *
+     * `axesOf` alone keeps an axis only when the option's own block carries
+     * declarations - true for a recipe we generated, and false for every recipe we
+     * READ, where the block is empty and the look is in `layers`. The parts learned
+     * this on 04/08; the root was left on the old reader and 15 of his 19 components
+     * with an axis shipped with no prop for it.
+     */
+    const axes = rootAxes(recipe);
     const comp = pascal(localName);
     const propNames = axes.map((a) => a.prop);
     const tree = recipe.preview?.parts ?? [];
@@ -857,28 +1086,56 @@ ${parts.filter(Boolean).join("\n")}`;
 }
 function emitTailwindMode(slug, name, recipe, version, props, 
 /** The name it takes in THEIR project. The utilities stay the system's. */
-localName = name) {
+localName = name, 
+/** The scheme the document opens in - see `generateComponentFiles`. */
+scheme = "dark") {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const el = asElement(tag, attrs, voidEl);
-    const axes = axesOf(recipe.variants);
+    const axes = rootAxes(recipe);
     const comp = pascal(localName);
+    const resolved = resolveNode(recipe, scheme, true);
     const variantConsts = axes
         .filter((a) => !a.boolean)
         .map((a) => {
         const entries = a.options
-            .map((o) => `  ${JSON.stringify(o)}: ${JSON.stringify(blockToTailwind(recipe.variants[a.key]?.[o] ?? {}).join(" "))},`)
+            .map((o) => `  ${JSON.stringify(o)}: ${JSON.stringify(blockToTailwind(resolved.variants[a.key]?.[o] ?? {}).join(" "))},`)
             .join("\n");
         return `const ${a.prop.toUpperCase()}: Record<string, string> = {\n${entries}\n};`;
     });
     const booleanConsts = axes
         .filter((a) => a.boolean)
-        .map((a) => `const ${a.prop.toUpperCase()} = ${JSON.stringify(blockToTailwind(recipe.variants[a.key]?.true ?? {}).join(" "))};`);
+        .map((a) => `const ${a.prop.toUpperCase()} = ${JSON.stringify(blockToTailwind(resolved.variants[a.key]?.true ?? {}).join(" "))};`);
     // Every property some axis controls leaves BASE, and the base value becomes
     // that axis's default - so exactly one class ever sets it and the prop
     // actually wins.
-    const owned = new Map(axes.map((a) => [a.prop, variantOwnedProps(recipe.variants, a)]));
+    const owned = new Map(axes.map((a) => [a.prop, variantOwnedProps(resolved.variants, a)]));
     const excluded = new Set([...owned.values()].flat());
-    const fallbackFor = (a) => JSON.stringify(blockToTailwind(Object.fromEntries(Object.entries(recipe.base).filter(([prop]) => (owned.get(a.prop) ?? []).includes(prop)))).join(" "));
+    /**
+     * `group-hover:` NEEDS A GROUP, and the root is the only node that can carry it.
+     *
+     * `within` is a state of the ROOT read from a PART - the idiom a real table row
+     * is built on, and the contract names the utility outright. Emitting
+     * `group-hover:` on the part while nothing marks the group is a class that
+     * matches nothing, which is the same silent nothing this whole file is about.
+     */
+    const needsGroup = Object.values(recipe.parts ?? {}).some((part) => (part.layers ?? []).some((layer) => layer.when?.within));
+    /**
+     * THE DEFAULT OPTION IS THE RESTING LOOK - which the destructuring already says.
+     *
+     * `{ variant }` undefined means the component IS its default, and on a READ
+     * recipe the base has no value for the property at all (his Button declares no
+     * `backgroundColor` in base - every one of the nine lives in a layer). Falling
+     * back to base alone therefore rendered the default variant as nothing. The
+     * compiler emits the default's layer bare for exactly this reason.
+     */
+    const fallbackFor = (a) => {
+        const fromBase = Object.fromEntries(Object.entries(recipe.base).filter(([prop]) => (owned.get(a.prop) ?? []).includes(prop)));
+        const preset = recipe.defaults?.[a.key];
+        const fromDefault = preset
+            ? (resolved.variants[a.key]?.[preset] ?? {})
+            : {};
+        return JSON.stringify(blockToTailwind({ ...fromBase, ...fromDefault }).join(" "));
+    };
     const clsParts = [
         "BASE",
         ...axes.map((a) => a.boolean
@@ -922,7 +1179,7 @@ ${dataAttrLines(axes)}${axes.length ? "\n" : ""}    `;
 import type { ${needsElementType ? `ElementType, ${props}` : props} } from "react";
 import { cn } from "../cn";
 
-const BASE = ${JSON.stringify(tailwindClassList(recipe, excluded))};
+const BASE = ${JSON.stringify([needsGroup ? "group" : "", tailwindClassList(recipe, resolved, excluded)].filter(Boolean).join(" "))};
 ${[...variantConsts, ...booleanConsts].join("\n")}
 
 type ${comp}Props = ${propsType(axes, tag, props, el.offersAs)};
@@ -965,8 +1222,19 @@ ${orderedParts
          * toggles data-active from its own state, which is how the GUIDE
          * documents the contract.
          */
-        const partVariantClasses = partAxes.flatMap((a) => a.options.flatMap((o) => blockToTailwind(part.variants?.[a.key]?.[o] ?? {}, `data-[${a.attr}=${o}]:`)));
-        const partCls = [tailwindClassList(part), ...partVariantClasses]
+        /**
+         * AND THE OPTION'S LOOK COMES OFF THE LAYERS TOO - the half of 04/08 that was
+         * left behind. The part got its prop and its `data-status` attribute, and the
+         * classes were read from `part.variants[axis][option]`, which on a read recipe
+         * is the empty block: the attribute shipped, nothing answered it, and the
+         * status colours of his card were still nowhere.
+         */
+        const partResolved = resolveNode(part, scheme, false);
+        const partVariantClasses = partAxes.flatMap((a) => a.options.flatMap((o) => blockToTailwind(partResolved.variants[a.key]?.[o] ?? {}, `data-[${a.attr}=${o}]:`)));
+        const partCls = [
+            tailwindClassList(part, partResolved),
+            ...partVariantClasses,
+        ]
             .filter(Boolean)
             .join(" ");
         /**
@@ -1020,7 +1288,24 @@ convention = DEFAULT_CONVENTION,
  *
  * Absent means the component keeps its own name, which is every caller today.
  */
-localName = name) {
+localName = name, 
+/**
+ * WHICH SCHEME THE DOCUMENT OPENS IN - `meta.scheme`, and the one input here that
+ * cannot be guessed without inverting light and dark.
+ *
+ * A layer for the document's own scheme is the RESTING look and takes no prefix;
+ * the other one hangs off a `[data-scheme]` ancestor. Read it backwards on a
+ * dark-native system and every dark value moves behind an attribute nothing sets,
+ * so the component arrives unpainted. `readInstalledScheme` answers it off the
+ * document on disk - the same one the stylesheet next to it came from, so the two
+ * can never disagree.
+ *
+ * REQUIRED, with no default, deliberately. `compile-css.ts` defaults to `"dark"`
+ * and a default here would agree with it - but it would also let a new caller ship
+ * without ever deciding, and an optional argument that can be forgotten is the
+ * shape this file has already been bitten by. `tsc` refuses the half-call instead.
+ */
+scheme) {
     const files = [];
     const props = propsTypeName(reactMajor);
     if (styles === "css") {
@@ -1033,7 +1318,7 @@ localName = name) {
     else {
         files.push({
             filename: `${localName}.tsx`,
-            code: `${emitTailwindMode(slug, name, recipe, version, props, localName)}\n`,
+            code: `${emitTailwindMode(slug, name, recipe, version, props, localName, scheme)}\n`,
         });
     }
     files.push({

package/dist/doctor/frozen.js

@@ -64,9 +64,23 @@ export function findFrozenBindings(document) {
     // Several roles can hold one primitive (Vesper's navy-700 is raised, overlay
     // AND border). Surfaces are preferred, because this only ever reports a
     // background - naming "border" for a background reads like a bug in the tool.
+    /**
+     * SÓ PAPEL DE SUPERFÍCIE, e agora é uma LISTA FECHADA em vez de uma preferência.
+     *
+     * Ela nasceu como ranking com fallback - "prefira superfície, e na falta use qualquer um" -, e o
+     * fallback é que produziu conselho perigoso no sistema real (13/08): o fundo do `card` apontando
+     * para `foreground`, o papel do TEXTO, e o do `text-editor` para `loader`, que vira azul no
+     * escuro. O comentário acima já dizia que nomear `border` para um fundo *"lê como um bug na
+     * ferramenta"*; nomear `foreground` é a mesma frase, um degrau pior.
+     *
+     * Um valor que só um papel de texto segura não ganha sugestão nenhuma - e o fato de o fundo não
+     * acompanhar o esquema continua sendo dito.
+     */
     const RANK = ["surface", "raised", "canvas", "overlay", "border"];
     const roleOf = new Map();
     for (const [role, ref] of Object.entries(semantic)) {
+        if (!RANK.includes(role))
+            continue;
         const other = alt[role];
         if (typeof ref !== "string" || typeof other !== "string")
             continue;
@@ -77,11 +91,7 @@ export function findFrozenBindings(document) {
             continue;
         const key = `${m[1]}.${m[2]}`.toLowerCase();
         const held = roleOf.get(key);
-        const better = !held ||
-            (RANK.indexOf(role) !== -1 &&
-                (RANK.indexOf(held.role) === -1 ||
-                    RANK.indexOf(role) < RANK.indexOf(held.role)));
-        if (better)
+        if (!held || RANK.indexOf(role) < RANK.indexOf(held.role))
             roleOf.set(key, { role, becomes: other });
     }
     if (roleOf.size === 0)

package/dist/doctor/ledger.js

@@ -140,6 +140,18 @@ export async function readEvents(root) {
     }
     return out;
 }
+/**
+ * An INCIDENT is a file going dirty until it is next seen clean. Consecutive
+ * dirty checks of the same file are the same incident - an agent that edits a
+ * file four times before the fix did not have four problems.
+ */
+/**
+ * A VERSÃO DA RÉGUA DA COBERTURA - sobe quando o mesmo repositório passa a dar outro número.
+ *
+ * A 2 é a camada de token DELE entrando na conta (13/08): `var(--color-ocean-500)`, que ele declara
+ * no CSS global, deixou de ser invisível e passou a contar como valor governado.
+ */
+export const COVERAGE_RULE = 2;
 export function summarize(events) {
     const hooks = events.filter((e) => e.kind === "hook" && e.file);
     const byFile = new Map();
@@ -170,11 +182,25 @@ export function summarize(events) {
         }
     }
     const snaps = events.filter((e) => e.kind === "doctor" && typeof e.coverage === "number");
-    const coverage = snaps.length >= 2
+    /**
+     * SÓ O QUE FOI MEDIDO PELA MESMA RÉGUA - ver `LedgerEntry.rule`.
+     *
+     * A régua da última foto é a que vale; as anteriores viram "a régua mudou". Sem isto, o dia em
+     * que a cobertura passou a contar a camada dele viraria um salto de 0% para 37% que ninguém fez.
+     */
+    const rule = snaps.length > 0 ? (snaps[snaps.length - 1].rule ?? 0) : 0;
+    const same = snaps.filter((e) => (e.rule ?? 0) === rule);
+    const coverage = same.length >= 2
         ? {
-            from: snaps[0].coverage,
-            to: snaps[snaps.length - 1].coverage,
+            from: same[0].coverage,
+            to: same[same.length - 1].coverage,
         }
         : null;
-    return { checks: hooks.length, resolved, open, coverage };
+    return {
+        checks: hooks.length,
+        resolved,
+        open,
+        coverage,
+        ...(same.length !== snaps.length ? { ruleChanged: true } : {}),
+    };
 }

package/dist/doctor/scan.js

@@ -9,7 +9,7 @@
  * Text in, findings out. No filesystem, no AST, no network - a diagnosis that
  * takes eight seconds and needs a build step is a diagnosis nobody runs.
  */
-import { tokenMatch } from "./tokens.js";
+import { normalizeValue, tokenMatch } from "./tokens.js";
 /**
  * `next/og` renders JSX to a PNG on the server. There is no document, so there
  * is no `var(--ds-*)` to read: every colour in such a file MUST be a literal.
@@ -269,9 +269,13 @@ export function scanSource(file, source, table) {
     }
     return scanCore(file, source, table);
 }
+/** `--color-ocean-500: #059aed;` - uma declaração de custom property no CSS dele. */
+const DECLARES = /^\s*(--[a-z0-9-]+)\s*:\s*([^;]+);/i;
 function scanCore(file, source, table) {
     const findings = [];
     const phantoms = [];
+    const ownDeclared = [];
+    const ownCandidates = new Map();
     let tokenUses = 0;
     // Reason by reason. Rolling two into "A or B" was the one place the report
     // still lumped things it had told apart everywhere else.
@@ -295,6 +299,34 @@ function scanCore(file, source, table) {
         const line = raw.trim();
         const at = i + 1;
         tokenUses += countTokenUses(line, table);
+        /**
+         * O QUE ESTE ARQUIVO DECLARA E O QUE ELE USA DE FORA DO SISTEMA - ver `FileReport.ownDeclared`.
+         *
+         * Os dois são coletados aqui e cruzados no fim: uma variável pode ser usada num arquivo e
+         * declarada em outro, então a resposta não existe enquanto a varredura não terminar.
+         */
+        const declaredHere = DECLARES.exec(line);
+        if (declaredHere && !declaredHere[1].toLowerCase().startsWith("--ds-")) {
+            const value = declaredHere[2].trim();
+            ownDeclared.push({
+                name: declaredHere[1].toLowerCase(),
+                value,
+                /**
+                 * O SISTEMA TAMBÉM SEGURA ESTE VALOR? A comparação é aqui porque é aqui que a tabela existe -
+                 * e é por VALOR, não por nome: `--color-ocean-500` e `--ds-color-ocean-500` só são a mesma
+                 * decisão porque os dois seguram `#059aed`.
+                 */
+                ...(table.byValue.has(normalizeValue(value))
+                    ? { mirrored: true }
+                    : null),
+            });
+        }
+        for (const m of line.matchAll(ANY_VAR_USE)) {
+            const name = m[1].toLowerCase();
+            if (isKnownToken(name, table))
+                continue;
+            ownCandidates.set(name, (ownCandidates.get(name) ?? 0) + 1);
+        }
         for (const name of findPhantoms(line, table))
             phantoms.push({ name, line: at });
         // Depth at the START of this line, carried before the early return so a
@@ -451,6 +483,15 @@ function scanCore(file, source, table) {
         findings,
         tokenUses,
         ...(phantoms.length > 0 ? { phantoms } : null),
+        ...(ownDeclared.length > 0 ? { ownDeclared } : null),
+        ...(ownCandidates.size > 0
+            ? {
+                ownCandidates: [...ownCandidates].map(([name, count]) => ({
+                    name,
+                    count,
+                })),
+            }
+            : null),
         ...(aside.size > 0
             ? {
                 setAside: [...aside].map(([reason, count]) => ({ reason, count })),
@@ -474,7 +515,41 @@ export function diagnose(files) {
     // sit outside the fraction. Reporting 100% directly above "2 names your
     // system never declares" is the report contradicting itself in six lines.
     const phantomUses = files.reduce((n, f) => n + (f.phantoms?.length ?? 0), 0);
-    const total = tokenUses + flat.length + phantomUses;
+    /**
+     * A CAMADA DELE, CRUZADA NO FIM - ver `FileReport.ownDeclared`.
+     *
+     * Uma variável é declarada num arquivo e usada em vinte, então a resposta só existe depois da
+     * varredura inteira. `ownUses` conta só o que aponta para um nome que ESTE repositório declara: um
+     * `var(--algo)` que ninguém declara continua fora da conta, porque ele não pinta nada.
+     */
+    const ownDeclared = new Map();
+    for (const f of files)
+        for (const d of f.ownDeclared ?? [])
+            if (!ownDeclared.has(d.name))
+                ownDeclared.set(d.name, d.value);
+    const ownUses = files.reduce((n, f) => n +
+        (f.ownCandidates ?? []).reduce((m, c) => m + (ownDeclared.has(c.name) ? c.count : 0), 0), 0);
+    /**
+     * E QUANTAS DELAS O SISTEMA TAMBÉM NOMEIA - pelo VALOR, que é o que torna a adoção barata.
+     *
+     * A comparação é sobre o valor declarado e não sobre o nome: `--color-ocean-500` e
+     * `--ds-color-ocean-500` só são a mesma decisão porque os dois seguram `#059aed`.
+     */
+    const mirrored = new Set();
+    for (const f of files)
+        for (const d of f.ownDeclared ?? [])
+            if (d.mirrored)
+                mirrored.add(d.name);
+    const ownMirrored = mirrored.size;
+    /**
+     * A COBERTURA PASSA A CONTAR A CAMADA DELE - e a decisão é do dono, em 13/08.
+     *
+     * O `--ds-*` é normalização NOSSA, para governar. Um projeto que declara o próprio vocabulário
+     * tem um design system de verdade, e medir isso como não-cobertura é dizer que o trabalho dele é
+     * deriva. A pergunta que separa governança de bagunça é literal-versus-NOME; de quem é o nome vira
+     * a linha de baixo, que diz quantos daqueles nomes o sistema também tem.
+     */
+    const total = tokenUses + ownUses + flat.length + phantomUses;
     const byLiteral = new Map();
     for (const f of flat) {
         const key = `${f.kind}:${f.literal.toLowerCase()}`;
@@ -513,7 +588,10 @@ export function diagnose(files) {
         named: flat.filter((f) => f.token).length,
         tokenUses,
         phantomUses,
-        coverage: total === 0 ? 100 : Math.round((tokenUses / total) * 100),
+        coverage: total === 0 ? 100 : Math.round(((tokenUses + ownUses) / total) * 100),
+        ownTokens: ownDeclared.size,
+        ownUses,
+        ownMirrored,
         scanned: files.length,
         repeats,
     };

package/dist/doctor/transcribe.js

@@ -16,13 +16,24 @@
  * chance of a value nobody wrote: every declaration it emits either points at a
  * token they declared or carries a literal they typed.
  *
- * WHY NOT `refit`. That endpoint already turns arbitrary component code into a
- * token-only recipe, and it is the right tool for its own job - bringing in
- * code from OUTSIDE and dressing it in a system. But it maps every value to the
- * NEAREST allowed token and never emits a raw one, which is normalisation, and
- * v1 is a mirror. It also costs credits and has a daily quota, and a first
- * import would spend 23 of them before anybody has seen value. It stays where
- * it is; this runs first, for free, on what is already theirs.
+ * WHY NOT `refit`, AND WHERE IT DOES BELONG.
+ *
+ * That endpoint already turns arbitrary component code into a token-only
+ * recipe. It maps every value to the NEAREST allowed token and never emits a raw
+ * one - which is NORMALISATION, and v1 is a mirror. That is the whole reason it
+ * is not here, and it is a reason about meaning rather than about cost: a v1
+ * that arrived already interpreted would leave the v2 with nothing to propose.
+ *
+ * Its place is exactly there, in the v2 (dono, 01/08). v1 carries their
+ * `RadioCard` with the `#ffffff` they actually typed; v2 offers the same
+ * component expressed entirely in their tokens, and they approve it. Same
+ * division as the colour collapse: mirror first, proposal second, and the person
+ * decides.
+ *
+ * An earlier version of this comment also argued that refit costs credits and
+ * carries a daily quota. That argument is retired: quotas are becoming an
+ * internal control rather than a product surface, under a 30-day-free-then-paid
+ * plan. Cost was never the real reason and should not be recorded as one.
  *
  * THE MODIFIER SAYS WHERE THE VALUE GOES, which is what makes this tractable:
  *

package/dist/install-marks.js

@@ -64,8 +64,14 @@
  * carrega - as regras de elemento da folha global dele. Elas viajavam no `design-system.json` desde
  * sempre e o arquivo que o agente é mandado ler não as citava, então seis regras adotadas no sistema
  * real eram invisíveis para quem ia escrever a próxima tela.
+ *
+ * 0.16.217 -> 0.16.220 em 13/08, e o SIM mais forte que esta marca já teve: o COMPONENTE que cai na
+ * pasta dele mudou. O codegen lia o estilo condicional só onde uma receita NOSSA o guarda, e uma
+ * receita LIDA guarda em `layers` - então 15 dos 19 componentes dele com eixo eram materializados sem
+ * a prop, e 104 das 207 condições sem expressão nenhuma. Um `upgrade` anterior a esta versão reescreve
+ * os componentes dele com a perda intacta.
  */
-export const MATERIALISER_SINCE = "0.16.217";
+export const MATERIALISER_SINCE = "0.16.220";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -74,7 +80,17 @@ export const MATERIALISER_SINCE = "0.16.217";
  *
  * Os arquivos que decidem: `doctor/` inteiro e `commands/hook.ts`.
  */
-export const CHECKER_SINCE = "0.16.202";
+/**
+ * 0.16.202 -> 0.16.218 em 13/08, e o passo 1 foi SIM: a lente `frozen` parou de aconselhar um fundo
+ * a apontar para um papel que não é superfície.
+ *
+ * 0.16.218 -> 0.16.219 no mesmo dia, SIM de novo: a cobertura passou a contar a CAMADA DE TOKEN
+ * DELE. Um hook pinado antes disso mede o mesmo repositório e devolve outro número - e o número é o
+ * que a pessoa lê para decidir se adotou ou não. Um hook pinado numa versão anterior segue dizendo ao
+ * agente dele que o fundo do `card` deveria apontar para `foreground` - o papel do TEXTO -, e é
+ * exatamente uma verificação que o pinado faz diferente.
+ */
+export const CHECKER_SINCE = "0.16.219";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/dist/project-facts.js

@@ -143,3 +143,31 @@ export async function readInstalledConvention(root, slug) {
         return DEFAULT_CONVENTION;
     }
 }
+/**
+ * WHICH SCHEME THE INSTALLED SYSTEM OPENS IN, read off the same document on disk.
+ *
+ * The twin of `readInstalledConvention`, and for the same reason: the document is
+ * the one the compiled stylesheet came from, so this can never disagree with the
+ * CSS sitting next to it.
+ *
+ * It decides whether a `scheme: dark` layer is the RESTING look or the alternative
+ * one - the whole difference between a component that arrives painted and one whose
+ * every dark value hides behind an attribute nothing sets. `"dark"` when the
+ * document cannot be read, which is what the compiler assumes when nobody says.
+ */
+export async function readInstalledScheme(root, slug) {
+    const dir = join(root, "_synthesisui", "ds", slug);
+    const version = await pinnedVersion(dir);
+    const raw = version
+        ? await readFile(join(dir, `v${version}`, "design-system.json"), "utf8").catch(() => "")
+        : "";
+    if (!raw)
+        return "dark";
+    try {
+        const doc = JSON.parse(raw);
+        return doc.meta?.scheme === "light" ? "light" : "dark";
+    }
+    catch {
+        return "dark";
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.217",
+  "version": "0.16.220",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {