@kanzo-tech/theme 0.0.1-alpha

package/dist/sections.d.ts

@@ -0,0 +1,304 @@
+/**
+ * Sections: appearance vocabulary contributed by the package that owns it.
+ *
+ * The core never learns that a section exists. It stores sections **opaquely**, resolves a token by
+ * hierarchical fallback, and validates against a manifest the owning package hands it. Contributing
+ * is *using* a name, not registering a type here — which is what keeps the one-way door shut
+ * structurally rather than by discipline: `@kanzo-tech/theme` gains no reference to
+ * `@kanzo-tech/graph`, and `boundary.test.ts` keeps passing because there is nothing to import.
+ *
+ * ## Resolution is Neovim's, validation is not
+ *
+ * A dotted name falls back to its parent: `--graph-point-size-min` → `--point-size-min` → the
+ * default the manifest declared. Neovim's highlight groups work exactly this way
+ * (`@foo.bar.lang → @foo.bar → @foo`) and it is why a section costs the core nothing.
+ *
+ * **Neovim pays a price we do not: there, a typo degrades silently to the parent.** Here the
+ * manifest *declares* its tokens, so resolution goes by fallback and validation goes against the
+ * declaration. That combination — contribute *and* validate — is the part no surveyed system does:
+ * VS Code's `contributes.colors` and Emacs contribute without validating the namespace, Vanilla
+ * Extract validates completely and therefore cannot have optional sections at all, and StyleX
+ * retracted that shape. This is unmapped ground, and `sections.test.ts` says what it cannot prove.
+ *
+ * ## A default may be derived, and that is what makes white-label flow
+ *
+ * VS Code spells derived defaults as imperative transforms (`darken`, `transparent`, `oneOf`). Ours
+ * is a **CSS value**, which is the same idea with nothing between it and the browser:
+ * `var(--primary)` points at what the theme publishes, and `color-mix(in oklab, var(--primary) 20%,
+ * transparent)` derives from it. A bank changing its theme moves both — **without the core knowing
+ * what a graph is**, and without anyone copying a hex.
+ *
+ * **It was an object with three shapes** — `{kind:"step"|"alpha", ramp, step}` and
+ * `{kind:"role", token}` — declarative against the tenant's *ramps*. Two of the three named a
+ * reference tier that no longer exists, and the third was `var()` wearing a wrapper. Collapsing them
+ * removed a type that had to be declared structurally in two packages at once, so it also removed
+ * the drift between the two declarations.
+ *
+ * That is why this is not the thing that was refused earlier. Minting a *role* in the core's
+ * vocabulary for one consumer is how seventeen level-names happened. A section token lives in the
+ * owner's namespace, is declared by the owner, and costs nothing to whoever never installs it.
+ */
+export interface SectionTokenDecl {
+    /**
+     * A CSS value. A literal, a `var()` at what the theme publishes, or a `color-mix()` derived from
+     * one — and nothing needs to resolve it but the browser.
+     */
+    default: string;
+    /** What the token is for, in one line. Shown by a panel that lists a section's vocabulary. */
+    doc: string;
+}
+/** What every declaration carries, whatever its kind. */
+interface PrefCommon {
+    /** The value when nothing else answers. Always a string — see {@link SectionPrefDecl}. */
+    default: string;
+    /** What the preference does, in one line. Shown by a surface beside the control. */
+    doc: string;
+    /**
+     * What a surface CALLS it. Falls back to the key, which is what every surface used to draw.
+     *
+     * The options carried labels and the preference did not, so a generic control had a key for a
+     * legend: a dock offering the force coefficients announced `link-spring`. A name is authored where
+     * the values are, like everything else here — and it is not the `doc`, which is a sentence about
+     * what the thing does rather than the two words a control is titled with.
+     */
+    label?: string;
+    /**
+     * The stored value is a map keyed by the resolved appearance, not a plain string.
+     *
+     * One field on the declaration rather than a second table beside it. It is only expressible
+     * because appearance resolves *first* — the pre-hydration script has to resolve it to write
+     * `.dark` — so by the time anything reads this, the side to index by is known.
+     */
+    byAppearance?: true;
+    /**
+     * The attribute to write on `<html>` — **only where CSS has to react.**
+     *
+     * Most contributed preferences have none. The graph's look is read by JS and pushed into a
+     * renderer's config; an editor's font size would want one. Leaving it out is what keeps the
+     * pre-hydration script from growing by a line for every optional package a host installs, which is
+     * the cost the four core axes pay for having attributes at all.
+     */
+    attr?: string;
+}
+/** One thing a `choice` may offer. `value` is what is stored; `label` is what a person reads. */
+export interface PrefOption {
+    value: string;
+    label: string;
+}
+/**
+ * Where a choice's options come from, when an author cannot list them.
+ *
+ * The one thing a TENANT publishes that nobody can know at authoring time: the themes they wrote.
+ * Closed on purpose — a source is something the provider already receives and can hand to a
+ * resolver, not a hook for a package to fetch from.
+ *
+ * It was two, `"palettes"` and `"identities"`, while a palette contained brands and a control had to
+ * ask which level it was filling. A brand is a theme, so there is one level and one list.
+ */
+export type PrefSource = "themes";
+/**
+ * A list, or the name of the list's owner.
+ *
+ * This is the same move {@link SectionTokenDecl} already makes for colour — a **binding** instead of
+ * a value — so the vocabulary stays one. It is what `theme` needs: its options are
+ * a client's brands, and an author who typed them would be authoring the client's product.
+ */
+export type PrefOptions = readonly PrefOption[] | {
+    from: PrefSource;
+};
+/** What the host publishes, for the declarations that name a source. */
+export type PrefSources = Partial<Record<PrefSource, readonly PrefOption[]>>;
+/**
+ * The options a declaration offers — `null` when it names a source nobody has answered yet.
+ *
+ * `null` rather than `[]`, and the distinction is load-bearing: "this tenant published nothing",
+ * "the host has not wired the prop" and "the document is still being fetched" are indistinguishable
+ * from here, and every one of them must leave a stored value alone. An empty list would read as
+ * *nothing is legal* and quietly reset a user's brand on the first render before the fetch lands —
+ * which is the failure `useRetirement` guards with `options.length > 0` one layer up.
+ */
+export declare function prefOptions(decl: SectionPrefDecl, sources?: PrefSources): readonly PrefOption[] | null;
+/**
+ * One preference a section offers its user — the half of a manifest the person on the screen decides.
+ *
+ * **Three kinds, and the set is closed.** A section may offer a value it has measured; it may not
+ * offer a text field, and there is deliberately no `custom` escape. That is the same line the colour
+ * layer holds one level up — choose among what somebody validated, never author — and it is what
+ * lets any surface render any section without knowing which package wrote it.
+ *
+ * The three arrived together with their call sites rather than ahead of them. `choice` shipped
+ * alone and covered the graph's look; the eleven controls it could not express are what asked for
+ * the other two — three toggles and two scalars in the graph's Display, six coefficients in its
+ * simulation dock, every one of them hand-rolled with its own wiring.
+ *
+ * **"Follow the system" is an option and not a fourth kind.** It is the option whose value is `""`,
+ * and the convention is already load-bearing here: `identity` and `palette` default to `""`, and the
+ * write rule removes the attribute at the default — which is exactly what *the OS decides* means in
+ * CSS, where there is no third keyword either. Declared as `{ value: "", label: "System" }` it is a
+ * thing a control can offer, so getting back to it stops being the panel's `Reset` button's private
+ * power.
+ *
+ * **A value is a string in all three**, and that is a decision rather than an oversight. One storage
+ * shape means an unrecognised namespace rides through a write untouched without the core parsing
+ * it; and a value that can be written to a `data-*` attribute needs no second spelling on its way
+ * out. A renderer parses what its own kind means — `"true"`, `"0.42"` — and the parsing is one
+ * place, {@link prefNumber} and {@link prefBoolean}.
+ */
+export type SectionPrefDecl = 
+/** Pick one of a closed list — or of a list only the tenant can write. */
+(PrefCommon & {
+    kind: "choice";
+    /** Everything a control may offer, in order. Order is the section's, and a surface keeps it. */
+    options: PrefOptions;
+})
+/** On or off. Stored as `"true"` / `"false"`. */
+ | (PrefCommon & {
+    kind: "toggle";
+})
+/**
+ * A number within declared bounds.
+ *
+ * The bounds are the section's own claim about what it will honour, so a stored value outside them
+ * is declined the same way a retired option is: a slider that used to run to 5 and now stops at 3
+ * must not paint 5 because storage remembers it.
+ */
+ | (PrefCommon & {
+    kind: "range";
+    min: number;
+    max: number;
+    step: number;
+});
+/** Read a `toggle`'s value. Anything that is not exactly `"true"` is off. */
+export declare const prefBoolean: (value: string) => boolean;
+/** Read a `range`'s value. `NaN` never escapes: a corrupt string answers the declared minimum. */
+export declare function prefNumber(value: string, decl: {
+    min: number;
+}): number;
+/**
+ * What a tenant may say about a section's choice — **selection, never authorship.**
+ *
+ * A document may fix a choice or withhold it; it may not invent a value for it. The options are the
+ * ones the owning package declared and measured, and a policy picks among them or removes the
+ * control. That is the same line the colour half holds — a user chooses among colours somebody
+ * validated and never authors one — and it is what stops this field becoming the runtime palette
+ * authoring the retired axes exist to prevent.
+ */
+export interface SectionPrefPolicy {
+    /** Fixed to this value. No control is offered and a stored preference does not apply. */
+    pinned?: string;
+    /** Not offered. The default applies, and a stored preference is kept but does not apply. */
+    hidden?: boolean;
+    /** Offered, but starting somewhere other than the manifest says. */
+    default?: string;
+}
+/**
+ * What a package publishes to contribute a section. Reached by subpath, never imported here.
+ *
+ * **One manifest carries both halves**, and they are both optional. A package may contribute tokens
+ * without preferences (a vocabulary a document decides), preferences without tokens (a choice that
+ * paints nothing of its own), or both. Two exports would let a namespace and a version drift apart
+ * while describing the same section, and the namespace is the whole of the contract.
+ */
+export interface SectionManifest {
+    /** The namespace segment. `"graph"` produces `--graph-*`. */
+    namespace: string;
+    version: number;
+    /** Keys are token names **without** the namespace: `"marquee"`, `"point-size-min"`. */
+    tokens?: Readonly<Record<string, SectionTokenDecl>>;
+    /** Keys are preference names, unqualified: `"look"`. */
+    prefs?: Readonly<Record<string, SectionPrefDecl>>;
+}
+/** A tenant's policy for one section, keyed by preference name. */
+export type SectionPolicy = Readonly<Record<string, SectionPrefPolicy>>;
+/** Where a resolved preference came from — a panel says so, and a test asserts on it. */
+export type PrefOrigin = "pinned" | "stored" | "policy" | "default";
+export interface ResolvedPref {
+    value: string;
+    via: PrefOrigin;
+    /** Whether a control should be drawn at all. `false` for pinned and for withheld. */
+    offered: boolean;
+}
+/**
+ * One chain, most specific first — the sibling of {@link resolveSectionToken}.
+ *
+ * Writing it as a chain is not decoration: the token half already answers *the first member that
+ * answers, and says which one it used*, and a preference resolved by some other order would be a
+ * second mechanism wearing the first one's vocabulary.
+ *
+ * A stored value that is not in `options` is ignored rather than applied. A section's options are
+ * the values it has measured; a stale one from a version the package no longer ships is exactly the
+ * case where falling back beats honouring what storage happens to hold.
+ */
+export declare function resolvePref(decl: SectionPrefDecl, stored: string | undefined, policy?: SectionPrefPolicy, 
+/** What the tenant published, for a choice whose options name a source rather than listing them. */
+sources?: PrefSources): ResolvedPref;
+/**
+ * Check a section's stored preferences against the manifest that owns it.
+ *
+ * The preference sibling of {@link validateSection}, and the same argument: a name the manifest
+ * never declared is reported rather than resolving to something plausible. What differs is that a
+ * preference also has a closed set of legal *values*, so a stored value outside `options` is
+ * reported too — `resolvePref` already refuses to apply it, and this is what says so out loud.
+ */
+export declare function validatePrefs(manifest: SectionManifest, stored: Readonly<Record<string, string>>, 
+/** As {@link resolvePref}'s. A choice whose source is unanswered is not judged, and not reported. */
+sources?: PrefSources): Problem[];
+/** A stored appearance document. `sections` is opaque: the core never parses a section's payload. */
+export interface LookDocument {
+    id: string;
+    label: string;
+    version: number;
+    /**
+     * Keyed by namespace. **Unknown sections are legal and are preserved**, which is a product
+     * requirement rather than politeness: a client signs their document before they buy the graph,
+     * and the section a later package adds must survive every load and save in between.
+     */
+    sections: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+/**
+ * The fallback chain for a dotted token, most specific first.
+ *
+ * `--graph-point-size-min` → `--point-size-min`. One segment is dropped at a time from the left,
+ * because the namespace is the qualifier: a section asks for its own value and inherits the shared
+ * one when it has none of its own.
+ */
+export declare function fallbackChain(token: string): string[];
+/**
+ * Resolve a section token against a document, then against the manifest's default.
+ *
+ * `declared` is what the cascade or the document already provides, keyed by full token name. The
+ * first member of the chain it answers wins; if none does, the manifest's default is returned —
+ * and a default is returned as written, because it is already a CSS value: the browser is what
+ * resolves it, on the element that uses it.
+ */
+export declare function resolveSectionToken(token: string, declared: Readonly<Record<string, string>>, manifest: SectionManifest): {
+    value: string;
+    via: string;
+} | null;
+export interface Problem {
+    token: string;
+    /** `unknown` — not declared by the manifest. `shadowed` — would silently fall back to a parent. */
+    kind: "unknown" | "shadowed";
+    detail: string;
+}
+/**
+ * Check a section's stored payload against the manifest that owns it.
+ *
+ * This is the half Neovim does not have, and it is why a typo cannot degrade in silence: a name the
+ * manifest never declared is reported rather than quietly resolving to whatever parent happens to
+ * exist. Validation is **per section**, so a document carrying a section for an absent package is
+ * simply not validated — it is not an error, and `sections.test.ts` pins that.
+ */
+export declare function validateSection(manifest: SectionManifest, stored: Readonly<Record<string, string>>): Problem[];
+/** Read a section's payload. Absent, or a package you do not have, answers an empty record. */
+export declare function sectionOf(doc: LookDocument, namespace: string): Readonly<Record<string, string>>;
+/**
+ * Write a section back, preserving every other section byte for byte.
+ *
+ * The preservation is the point: a host that never installed `@kanzo-tech/graph` still round-trips
+ * a document containing a graph section, because the core treats the payload as opaque data rather
+ * than as something to parse into a type it knows.
+ */
+export declare function withSection(doc: LookDocument, namespace: string, tokens: Readonly<Record<string, string>>): LookDocument;
+export {};
+//# sourceMappingURL=sections.d.ts.map

package/dist/sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sections.d.ts","sourceRoot":"","sources":["../src/sections.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@kanzo-tech/theme",
+  "version": "0.0.1-alpha",
+  "description": "Kanzo design tokens — a catalogue of themes, each one flat block of CSS, plus the non-colour axes (radius / font / mono font / density) a user layers over them, driven by data-* attributes on <html>.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist",
+    "themes",
+    "tokens.css",
+    "themes.css",
+    "theme-data.json",
+    "README.md"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tokens.css": "./tokens.css",
+    "./themes.css": "./themes.css",
+    "./theme-data.json": "./theme-data.json",
+    "./package.json": "./package.json",
+    "./themes/*.css": "./themes/*.css"
+  },
+  "//deps": "No React peer and no derivation dependency: this package ships CSS, the axis table and types. The provider that consumes them lives in @kanzo-tech/ui. A theme is source, not output — there is nothing to derive it from.",
+  "devDependencies": {
+    "tailwindcss": "4"
+  },
+  "//gen": "One step now: the non-colour axes and the theme catalogue. There is no colour generation — a theme is themes/<name>.css, hand-written source. scripts/extract-themes.mjs was the one-way migration that produced the first sixteen and does not run again.",
+  "scripts": {
+    "build": "vite build",
+    "//gen": "Three steps, in this order: the derivation made runnable from plain Node (its own tables, then its build), the four non-colour axes, and the default tenant's document compiled into tokens.css.",
+    "gen": "node scripts/gen-theme.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/theme-data.json

@@ -0,0 +1,311 @@
+{
+  "radii": {
+    "none": "0rem",
+    "xs": "0.125rem",
+    "sm": "0.25rem",
+    "md": "0.5rem",
+    "lg": "0.625rem"
+  },
+  "fonts": {
+    "system": "ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif",
+    "geist": "var(--font-geist-sans, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif)",
+    "inter": "var(--font-inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", Arial, sans-serif)"
+  },
+  "monoFonts": {
+    "system": "ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace",
+    "geist-mono": "var(--font-geist-mono, ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace)",
+    "jetbrains-mono": "var(--font-jetbrains-mono, ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, \"Liberation Mono\", monospace)"
+  },
+  "densities": {
+    "default": "16px",
+    "compact": "14px",
+    "comfortable": "18px"
+  },
+  "themes": [
+    {
+      "name": "acid",
+      "dark": false
+    },
+    {
+      "name": "bank-dark",
+      "dark": true
+    },
+    {
+      "name": "bank-private-dark",
+      "dark": true
+    },
+    {
+      "name": "bank-private",
+      "dark": false
+    },
+    {
+      "name": "bank",
+      "dark": false
+    },
+    {
+      "name": "catppuccin-latte-dark",
+      "dark": true
+    },
+    {
+      "name": "catppuccin-latte",
+      "dark": false
+    },
+    {
+      "name": "catppuccin-mocha-dark",
+      "dark": true
+    },
+    {
+      "name": "catppuccin-mocha",
+      "dark": false
+    },
+    {
+      "name": "cmyk",
+      "dark": false
+    },
+    {
+      "name": "coffee",
+      "dark": true
+    },
+    {
+      "name": "cyberpunk",
+      "dark": false
+    },
+    {
+      "name": "dim",
+      "dark": true
+    },
+    {
+      "name": "dracula-dark",
+      "dark": true
+    },
+    {
+      "name": "dracula",
+      "dark": false
+    },
+    {
+      "name": "forest",
+      "dark": true
+    },
+    {
+      "name": "kanzo-dark",
+      "dark": true
+    },
+    {
+      "name": "kanzo",
+      "dark": false
+    },
+    {
+      "name": "lemonade",
+      "dark": false
+    },
+    {
+      "name": "lofi",
+      "dark": false
+    },
+    {
+      "name": "luxury",
+      "dark": true
+    },
+    {
+      "name": "monochrome-dark",
+      "dark": true
+    },
+    {
+      "name": "monochrome",
+      "dark": false
+    },
+    {
+      "name": "night",
+      "dark": true
+    },
+    {
+      "name": "nord-dark",
+      "dark": true
+    },
+    {
+      "name": "nord",
+      "dark": false
+    },
+    {
+      "name": "sunset",
+      "dark": true
+    },
+    {
+      "name": "synthwave",
+      "dark": true
+    },
+    {
+      "name": "wireframe",
+      "dark": false
+    }
+  ],
+  "prefs": {
+    "appearance": {
+      "kind": "choice",
+      "options": [
+        {
+          "value": "",
+          "label": "System"
+        },
+        {
+          "value": "light",
+          "label": "Light"
+        },
+        {
+          "value": "dark",
+          "label": "Dark"
+        }
+      ],
+      "default": "",
+      "label": "Appearance",
+      "doc": "which side of the document is worn"
+    },
+    "radius": {
+      "kind": "choice",
+      "options": [
+        {
+          "value": "none",
+          "label": "none"
+        },
+        {
+          "value": "xs",
+          "label": "xs"
+        },
+        {
+          "value": "sm",
+          "label": "sm"
+        },
+        {
+          "value": "md",
+          "label": "md"
+        },
+        {
+          "value": "lg",
+          "label": "lg"
+        }
+      ],
+      "default": "md",
+      "attr": "data-radius",
+      "source": "themes",
+      "label": "Radius",
+      "doc": "how round a corner is"
+    },
+    "font": {
+      "kind": "choice",
+      "options": [
+        {
+          "value": "system",
+          "label": "System"
+        },
+        {
+          "value": "geist",
+          "label": "Geist"
+        },
+        {
+          "value": "inter",
+          "label": "Inter"
+        }
+      ],
+      "default": "system",
+      "attr": "data-font",
+      "source": "themes",
+      "label": "Font",
+      "doc": "the face body text is set in"
+    },
+    "monoFont": {
+      "kind": "choice",
+      "options": [
+        {
+          "value": "system",
+          "label": "System"
+        },
+        {
+          "value": "geist-mono",
+          "label": "Geist Mono"
+        },
+        {
+          "value": "jetbrains-mono",
+          "label": "JetBrains"
+        }
+      ],
+      "default": "system",
+      "attr": "data-mono-font",
+      "source": "themes",
+      "label": "Mono font",
+      "doc": "the face code is set in"
+    },
+    "density": {
+      "kind": "choice",
+      "options": [
+        {
+          "value": "default",
+          "label": "Default"
+        },
+        {
+          "value": "compact",
+          "label": "Compact"
+        },
+        {
+          "value": "comfortable",
+          "label": "Cozy"
+        }
+      ],
+      "default": "default",
+      "attr": "data-font-size",
+      "source": "themes",
+      "label": "Density",
+      "doc": "the root size everything scales from"
+    },
+    "themeByAppearance": {
+      "kind": "choice",
+      "options": {
+        "from": "themes"
+      },
+      "default": "",
+      "attr": "data-theme",
+      "source": "document",
+      "byAppearance": true,
+      "label": "Theme",
+      "doc": "which theme is worn on this side"
+    }
+  },
+  "fallbacks": {
+    "--secondary-foreground": [
+      "--foreground"
+    ],
+    "--accent-foreground": [
+      "--foreground"
+    ],
+    "--popover": [
+      "--card"
+    ],
+    "--input": [
+      "--border"
+    ],
+    "--field": [
+      "--muted"
+    ],
+    "--faint": [
+      "--muted-foreground"
+    ],
+    "--destructive-foreground": [
+      "--destructive"
+    ],
+    "--info-foreground": [
+      "--info"
+    ],
+    "--success-foreground": [
+      "--success"
+    ],
+    "--warning-foreground": [
+      "--warning"
+    ],
+    "--sidebar": [
+      "--popover",
+      "--card"
+    ],
+    "--sidebar-foreground": [
+      "--muted-foreground"
+    ]
+  }
+}