@kanzo-tech/theme 0.0.1-alpha

package/README.md

@@ -0,0 +1,130 @@
+# @kanzo-tech/theme
+
+The theme catalogue and the axes a user layers over it. **A theme is one flat block of CSS, and it
+carries one mode.**
+
+- **Theme** — `packages/theme/themes/<name>.css`, hand-written source. Twenty-one authored colours,
+  the shape knobs, the font stacks and its own `color-scheme`. Selected with `data-theme`.
+- **Radius** — `none` · `xs` · `sm` · `md` · `lg`, a user preference over the theme's own three
+  radius knobs.
+- **Font** / **Mono font** — `--font-sans` / `--font-heading` / `--font-mono`.
+- **Density** — the root font-size the whole `rem` scale resolves against.
+- **Appearance** — `light` / `dark`, and it chooses *which theme* is worn, because a theme is a side.
+
+This package ships **no components** and no colour maths. It is CSS, the declared axes and the value
+types.
+
+## A theme
+
+```css
+/* packages/theme/themes/acme.css */
+[data-theme="acme"] {
+  color-scheme: light;
+  --background: #fbfcfd;  --foreground: #10151c;
+  --primary: #1f6feb;     --primary-foreground: #ffffff;
+  /* …nineteen more, then the shape knobs and the fonts… */
+  --radius-box: 0.75rem;  --radius-field: 0.5rem;  --radius-selector: 0.25rem;
+  --stroke: 1px;          --depth: 0;
+}
+```
+
+That is the whole mechanism: a block somebody writes, an `@import` in `themes.css`, and an attribute
+on `<html>`. Adding a client touches no code and needs no deploy.
+
+**Twenty-one carry a value; everything else uses one.** `--card-foreground`, the sidebar tokens and
+`--popover` are *uses*, bridged once in `tokens.css` through `@theme inline` and never re-declared —
+which is also what makes a scoped `<div data-theme="…">` resolve correctly, since a custom property
+declared in `:root` would inherit already substituted.
+
+**Light and dark are two themes.** There is no second block and no `.dark` that flips a token; the
+class survives only as the selector for the `dark:` variant at the call sites that still ask for one.
+
+**There is no derivation.** A `@kanzo-tech/palette` package used to take two seeds through thirteen
+stages and publish 144 reference steps; components used eighteen of them, and all eighteen were
+tints that `color-mix` now computes at the point of use. It is deleted. What that costs is a contrast
+guarantee at authoring time — the author answers for AA, and a guard over the shipped themes is what
+catches a mistake.
+
+## How the other axes work
+
+Every axis is a `data-*` attribute **on `<html>`**, and the token values behind it live in
+`themes.css`. Change an attribute and every component re-skins, with no per-component work.
+
+| Axis | Attribute | Sets |
+|---|---|---|
+| radius | `data-radius` | `--radius` |
+| font | `data-font` | `--font-sans` |
+| monoFont | `data-mono-font` | `--font-mono` |
+| density | `data-font-size` | the root font-size |
+
+**The attributes must be on `<html>`, not a wrapper element.** Ark UI's overlays — Dialog,
+Popover, Menu, Select, Tooltip, Toast, HoverCard, Command — portal into `document.body`, outside
+any wrapper you render, so tokens set on a wrapper never reach them.
+Density is stricter still: it sets the root font-size, and every size in the system is `rem`.
+
+Writing them is `<KanzoThemeProvider>`'s job, from `@kanzo-tech/ui`:
+
+```tsx
+import { KanzoThemeProvider } from "@kanzo-tech/ui";
+import "@kanzo-tech/ui/styles.css"; // once, at the root
+
+<KanzoThemeProvider defaults={{ radius: "md", density: "compact" }}>
+  {children}
+</KanzoThemeProvider>;
+```
+
+Read or change the live preferences with `useKanzoTheme()`, or drop in the ready-made
+`<Preferences />` panel. Both come from `@kanzo-tech/ui`.
+
+## Dark mode
+
+Not owned here. The host toggles `.dark` on `<html>`, and the `.dark` block of the compiled
+document keys off it. If you already run a theme manager, hand it to the provider:
+
+```tsx
+import { useTheme } from "next-themes";
+
+const { resolvedTheme, setTheme } = useTheme();
+<KanzoThemeProvider appearance={{ resolvedTheme, setTheme }}>{children}</KanzoThemeProvider>;
+```
+
+Omit the prop and the provider's built-in fallback toggles `.dark` itself.
+
+## SSR
+
+Server-render the preferences with `themeScript()` from `@kanzo-tech/ui`, which writes the
+attributes before first paint so there is no flash of the wrong theme. Pair it with
+`cookieStorageAdapter()` so the server can read the same source from the request cookie:
+
+```tsx
+import { themeScript, cookieStorageAdapter } from "@kanzo-tech/ui";
+
+<head><script dangerouslySetInnerHTML={{ __html: themeScript() }} /></head>
+<KanzoThemeProvider storage={cookieStorageAdapter()}>{children}</KanzoThemeProvider>
+```
+
+## What's in the package
+
+The compiled styles ship with `@kanzo-tech/ui` (`import "@kanzo-tech/ui/styles.css"`), which
+already pulls in this package's `tokens.css` + `themes.css`. Subpath exports
+(`@kanzo-tech/theme/tokens.css`, `/themes.css`, `/themes/<name>.css`) are available for tooling —
+the last one so a consumer can import a subset of the catalogue instead of all of it.
+
+The non-colour axis tables — and the DECLARATION of every axis, `CORE_PREFS`, generated beside
+them — are exported from the JS entry as `themeData` / `CORE_PREFS`. Import those, **not**
+`@kanzo-tech/theme/theme-data.json`. A raw JSON subpath import is an ESM JSON import at
+runtime, which Node rejects without `with { type: "json" }`, and Rollup strips that attribute
+when bundling. `themeData.themes` is the catalogue, read off the `themes/` directory by the
+generator, so adding a theme is adding a file and nothing lists them twice.
+
+`CHART_SLOTS` is a fact about the **sheet** — how many `--chart-*` properties a theme publishes —
+and a chart resolving them off the cascade runs in a browser. It is checked against what actually
+ships rather than trusted: `packages/ui/src/lib/token-color.test.ts` reads every theme file and
+fails on one that declares a partial set.
+
+`themes.css` and `theme-data.json` are generated — **edit `scripts/gen-theme.mjs`, not those two.**
+`pnpm gen` runs it; CI regenerates and fails on any diff.
+
+**`tokens.css` and `themes/*.css` are NOT generated.** They are hand-written source, and a guard that
+regenerated them would have nothing to regenerate them from. That is the whole shape of the change:
+colour stopped being output.

package/dist/index.d.ts

@@ -0,0 +1,427 @@
+import { default as themeDataJson } from '../theme-data.json';
+import { SectionPrefDecl } from './sections.js';
+/**
+ * The generated theme tables — the four non-colour axes — as a JS module.
+ *
+ * Consumers must read them through this export rather than importing
+ * `@kanzo-tech/theme/theme-data.json` directly. A raw JSON subpath import is an ESM JSON
+ * import at runtime, which Node rejects without `with { type: "json" }` — and Rollup strips
+ * that attribute when bundling, so there is no way to make the direct import survive a build.
+ * Bundling the data into this package's own JS entry is safe: it is the package that owns the
+ * data, so the copy can never skew from the CSS generated alongside it.
+ *
+ * There is no derivation any more, so there are no tables for one to read: a theme is
+ * `themes/<name>.css`, hand-written source, and `themes` below is the catalogue read off disk by
+ * the generator so no second list can drift from it.
+ */
+export declare const themeData: {
+    radii: {
+        none: string;
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+    };
+    fonts: {
+        system: string;
+        geist: string;
+        inter: string;
+    };
+    monoFonts: {
+        system: string;
+        "geist-mono": string;
+        "jetbrains-mono": string;
+    };
+    densities: {
+        default: string;
+        compact: string;
+        comfortable: string;
+    };
+    themes: {
+        name: string;
+        dark: boolean;
+    }[];
+    prefs: {
+        appearance: {
+            kind: string;
+            options: {
+                value: string;
+                label: string;
+            }[];
+            default: string;
+            label: string;
+            doc: string;
+        };
+        radius: {
+            kind: string;
+            options: {
+                value: string;
+                label: string;
+            }[];
+            default: string;
+            attr: string;
+            source: string;
+            label: string;
+            doc: string;
+        };
+        font: {
+            kind: string;
+            options: {
+                value: string;
+                label: string;
+            }[];
+            default: string;
+            attr: string;
+            source: string;
+            label: string;
+            doc: string;
+        };
+        monoFont: {
+            kind: string;
+            options: {
+                value: string;
+                label: string;
+            }[];
+            default: string;
+            attr: string;
+            source: string;
+            label: string;
+            doc: string;
+        };
+        density: {
+            kind: string;
+            options: {
+                value: string;
+                label: string;
+            }[];
+            default: string;
+            attr: string;
+            source: string;
+            label: string;
+            doc: string;
+        };
+        themeByAppearance: {
+            kind: string;
+            options: {
+                from: string;
+            };
+            default: string;
+            attr: string;
+            source: string;
+            byAppearance: boolean;
+            label: string;
+            doc: string;
+        };
+    };
+    fallbacks: {
+        "--secondary-foreground": string[];
+        "--accent-foreground": string[];
+        "--popover": string[];
+        "--input": string[];
+        "--field": string[];
+        "--faint": string[];
+        "--destructive-foreground": string[];
+        "--info-foreground": string[];
+        "--success-foreground": string[];
+        "--warning-foreground": string[];
+        "--sidebar": string[];
+        "--sidebar-foreground": string[];
+    };
+};
+export type ThemeData = typeof themeDataJson;
+/**
+ * The themes this package ships, as data a picker can render.
+ *
+ * daisyUI keeps two registries — `themeOrder` (the ordered names) and `theme/object` (name → the
+ * variable map) — precisely so a switcher can draw a theme without parsing its CSS. This is the
+ * first: an entry carries what a control needs to *offer* a theme and nothing a page needs to
+ * *paint* one, which is the theme's own stylesheet's job.
+ *
+ * **It replaces `paletteIndex`, and it is a flat list where that was a tree.** A palette used to
+ * contain identities, so an entry had `children` and a picker had two levels. A brand is a theme
+ * now, so `bank` and `bank-private` sit side by side and the second level is gone.
+ *
+ * Generated from the directory, not listed: `scripts/gen-theme.mjs` reads `themes/` and records
+ * each file's own `color-scheme`. Adding a theme is adding a file.
+ *
+ * Read through this export rather than importing `@kanzo-tech/theme/theme-data.json`, for the
+ * reason given on {@link themeData}: a raw JSON subpath import is an ESM JSON import at runtime, and
+ * Rollup strips the attribute that would make it legal.
+ */
+export declare const themeIndex: ThemeIndexEntry[];
+/**
+ * One theme, as a control sees it.
+ *
+ * **It carries no colours.** A theme travels in the page under its own `[data-theme]`, so a control
+ * depicts one by *setting the attribute* and letting the cascade answer — which is also why a
+ * preview is a `div` and not a strip of swatches. A handful of hexes could not depict a theme
+ * anyway; on the default's own, two of the four a picker used to publish were the same value.
+ *
+ * `dark` is the theme's own `color-scheme`, and it is the whole of what "a theme is one mode"
+ * means at this layer: it is a property of the theme, not a second axis crossed with it.
+ */
+export interface ThemeIndexEntry {
+    name: string;
+    dark: boolean;
+}
+/**
+ * How many `--chart-N` custom properties the stylesheet declares. A 9th series folds into "Other" —
+ * never cycle, or identity stops meaning anything. (`--chart-capacity` is declared beside them and
+ * is not one of them; `boundary.test.ts` counts `--chart-N` only.)
+ *
+ * A fact about the SHEET, which is why it is here and not with the derivation that emits it: a
+ * chart resolving `var(--chart-N)` off the cascade needs the count, and a chart runs in a browser
+ * and is checked against the shipped theme files rather than trusted. The count is a compile-time constant
+ * because a stylesheet cannot have a variable number of custom properties.
+ *
+ * How many of the slots carry a *real* category is the document's `capacity`, which can be lower;
+ * it travels down the cascade as `--chart-capacity`, and past it `compile()` writes
+ * `var(--muted-foreground)`.
+ *
+ * `packages/palette` declares the same number, because it is what emits the properties. Neither
+ * copy is trusted: `boundary.test.ts` counts the declarations in the shipped `tokens.css` and
+ * holds both against it.
+ */
+export declare const CHART_SLOTS = 8;
+/**
+ * `@kanzo-tech/theme` — design tokens, the theme axis table, and the value types. No React.
+ *
+ * **Colour IS an axis now, and it is the same kind of axis as the rest.** A theme is one flat block
+ * of CSS under `[data-theme="<name>"]` — about fifty-five declarations somebody writes, pastes and
+ * diffs — so applying one is writing an attribute, exactly like radius or density. It stopped being
+ * special when it stopped being the output of a thirteen-stage derivation.
+ *
+ * Everything is driven by `data-*` attributes on `<html>`, and the values live in `themes.css`:
+ * · `data-theme`      — selects a whole theme: its colours, its shape knobs and its fonts.
+ * · `data-radius`     — the three radius knobs, as a user preference over the theme's own.
+ * · `data-font`       — sets `--font-sans` / `--font-heading`.
+ * · `data-mono-font`  — sets `--font-mono`.
+ * · `data-font-size`  — sets the root font-size (the rem density scale).
+ *
+ * **`data-theme` is `data-palette` and `data-identity` collapsed, and the authority question they
+ * modelled has dissolved rather than been decided.** `data-palette` selected from a catalogue the
+ * LIBRARY shipped, so a user picking Dracula could overrule a client's branding; `data-identity`
+ * selected among brands the CLIENT authored, one level down. A tenant's brands are now themes
+ * beside every other theme, so what a user may choose is what the tenant's policy admits — the
+ * `pinned` / `hidden` chain that already governs every other section, rather than two attributes
+ * with different pedigrees.
+ *
+ * Writing the attributes is `<KanzoThemeProvider>`'s job, from `@kanzo-tech/ui`. It sets them on
+ * `document.documentElement` — see the AXES note below for why a wrapper element cannot work.
+ *
+ * Dark mode is not a token flip any more: a theme carries its own `color-scheme` and its own
+ * colours, so `.dark` survives only as the selector for the `dark:` VARIANT at the call sites that
+ * still ask for one.
+ *
+ * Requires `@kanzo-tech/ui/styles.css` (or the raw token/theme CSS) imported once at the root.
+ */
+/**
+ * A side of the compiled document. `compile()` always emits both blocks, so there are exactly two.
+ *
+ * **There is no `"system"`, and its absence is the design.** Following the OS is a real behaviour we
+ * keep — without it the first visit has to guess, and guessing wrong flashes white at every
+ * dark-mode user — but it is the state with *no* value, not a third value.
+ *
+ * That split is the reference systems', and they divide on which layer they are. The JS
+ * theme-switching libraries make it a value: next-themes ships `defaultTheme = "system"` and appends
+ * `"system"` to its `themes` array, MUI has `mode: "light" | "dark" | "system"`, Mantine `"auto"`.
+ * The *token* layers do not: daisyUI writes `themes: light --default, dark --prefersdark`, where the
+ * OS preference is a flag on a theme and `data-theme` overrides it; Tailwind has a media query or a
+ * class; Radix Themes declines to model it and delegates to next-themes. And CSS itself has no third
+ * keyword — `color-scheme: light dark` means "the OS decides", and an explicit side overrides.
+ *
+ * We are a token layer: a document with a `:root` block and a `.dark` block. `"system"` arrived here
+ * as next-themes vocabulary for a mechanism we do not use, and `themeScript` never believed in it —
+ * it has always resolved "anything that is not an explicit side" against `matchMedia`.
+ *
+ * A host next-themes IS still supported; `KanzoThemeProvider` translates its `"system"` to `null` in
+ * one place, the way every other foreign vocabulary enters this system.
+ */
+export type Appearance = "light" | "dark";
+/**
+ * The appearance PREFERENCE — an explicit side, or `""` for "ask the OS".
+ *
+ * A value and not an absent key: the read-time whitelist is built from `Object.keys(DEFAULT_PREFS)`,
+ * so a key missing from the default blob is dropped on every read. It also survives
+ * `JSON.stringify` into both storage adapters, which an `undefined` would not.
+ *
+ * **`""` and not `null`, which is what it was.** Unset is the same value here as everywhere else in
+ * this package: a theme key stores `""` for "defer to the tenant", and the write rule
+ * removes an attribute at the default. Two spellings of one idea is what kept appearance out of the
+ * declaration — a `SectionPrefDecl`'s values are strings — and therefore out of the one resolution
+ * chain, which is the whole of what {@link CORE_PREFS} exists to end. Declared, "follow the OS" is
+ * `{ value: "", label: "System" }`: a thing a control can offer, rather than something reachable
+ * only through the panel's Reset button.
+ */
+export type AppearancePref = Appearance | "";
+/** Radius steps (`md` = 0.5rem default). */
+export type KanzoRadius = "none" | "xs" | "sm" | "md" | "lg";
+/** Density (root font-size rem-scale); `default` omits the attribute. */
+export type KanzoDensity = "default" | "compact" | "comfortable";
+/** Sans font key — host-extensible; the DS ships `system`/`geist`/`inter` stacks. */
+export type KanzoFont = "system" | "geist" | "inter" | (string & {});
+/** Mono font key — host-extensible; the DS ships `system`/`geist-mono`/`jetbrains-mono`. */
+export type KanzoMonoFont = "system" | "geist-mono" | "jetbrains-mono" | (string & {});
+/**
+ * Theme key — host-extensible; `""` means "defer to the tenant's default".
+ *
+ * This is `KanzoFont`'s case, not `KanzoRadius`': a value is a *host's* string, unknown when this
+ * package is built. Where `KanzoFont` still names the three stacks the DS happens to ship, there is
+ * nothing to union here — a tenant authors their own themes, so a literal union would be a list
+ * that is wrong for every client.
+ *
+ * **It replaces `KanzoPalette`, `KanzoIdentity` and `KanzoIdentityMemory`, and the collapse is the
+ * point.** Those were three types because a palette CONTAINED identities: a document was a two-mode
+ * stylesheet, a brand was a partial block layered onto it, and a memory recorded which brand you
+ * last wore inside each document so switching away and back returned you to it. A theme is one flat
+ * block, so a brand is not inside anything — `bank` and `bank-private` are two themes — and there is
+ * no containment left for a memory to remember.
+ */
+export type KanzoThemeName = string;
+/**
+ * One published theme, as the runtime sees it — the contract between the catalogue and the panel.
+ *
+ * It carries no colours, and it has no `children`. A control depicts a theme by setting
+ * `data-theme` on an element and letting the cascade paint it: the theme is already in the page, so
+ * a depiction copied out of it is a second spelling that can only ever be the same colours or the
+ * wrong ones.
+ *
+ * **`children` went with the containment it modelled.** A palette used to hold brands, so an option
+ * held options and the panel flattened a tree into one list. There is no tree: a brand is a theme.
+ */
+export interface ThemeOption {
+    value: string;
+    label: string;
+}
+/**
+ * The user's preferences. Six, and only one of them is a colour.
+ *
+ * *Free* colour left this table entirely: `palette`, `base`, `accent`, `primary`, `baseTint`,
+ * `scheme` and `schemeColors` were seven ways to express *part* of a palette at runtime, and a
+ * document expresses all of it at once, before a byte is sent. `appearance` stays because it is
+ * the one colour-adjacent thing a user genuinely chooses, and it selects between two blocks of one
+ * document. `identity` is the same kind of choice one level up: between blocks the TENANT
+ * published, and never between a value they did not.
+ */
+export interface ThemePrefs {
+    appearance: AppearancePref;
+    radius: KanzoRadius;
+    font: KanzoFont;
+    monoFont: KanzoMonoFont;
+    density: KanzoDensity;
+    /**
+     * Which theme this user wears on each side — `{}` while they have chosen neither.
+     *
+     * A map rather than a string because the choice is per appearance, and with one-mode themes that
+     * is not a refinement but the only shape available: a theme IS a side, so "which theme" without
+     * "on which side" does not name a preference. It is also exactly what the per-appearance palette
+     * proposal asked for, arrived at from the other
+     * direction — that proposal invented a map over documents that each carried both modes, to say
+     * something the two-mode document made awkward and the one-mode theme makes trivial.
+     *
+     * The ordering that makes it possible: the pre-hydration script resolves appearance before it
+     * writes anything, so it can index this map. That is the thing to check first when touching it.
+     */
+    themeByAppearance: Partial<Record<Appearance, KanzoThemeName>>;
+    /**
+     * What the packages a host installed contribute, keyed by namespace then by preference.
+     *
+     * **One key, and that is what makes an absent package harmless.** The read-time whitelist is built
+     * from `Object.keys(DEFAULT_PREFS)` and drops everything else, which is right for the retired
+     * colour axes it was built for and exactly wrong for a contributed choice: a host that drops an
+     * optional peer for one release would lose the user's stored value on the next write. Riding on a
+     * single known key, an unrecognised namespace survives every read and save without the core
+     * knowing it exists — the same opacity {@link LookDocument}'s `sections` already has, which is the
+     * point: both halves of a section are stored the same way.
+     */
+    sections: Record<string, Record<string, string>>;
+}
+/**
+ * Every key of `ThemePrefs`, with no exception for the ones whose default is empty.
+ *
+ * `PREF_KEYS` in the provider is `Object.keys(DEFAULT_PREFS)`, and the read-time whitelist built
+ * from it drops anything not listed. A pref missing here therefore works for exactly one session
+ * and is gone on the next read, silently and with no type error — the retired-key hygiene rule
+ * turned on a live field.
+ */
+export declare const DEFAULT_PREFS: ThemePrefs;
+export declare const STORAGE_KEY = "kanzo_theme_prefs";
+/**
+ * The core's own preferences, declared — one entry per axis, in the shape a package contributes.
+ *
+ * **Generated, and that is the point.** `scripts/gen-theme.mjs` authors the values *and* the
+ * declaration, so the option list a control offers is the table the CSS was emitted from rather than
+ * a hand-copy beside it. `Preferences.tsx` held two such copies — `RADII` and `DENSITIES` — sitting
+ * next to the generated tables they duplicated, and `KanzoThemeProvider` held a third of the font
+ * stacks with a fallback string that had already drifted from the sheet's. Adding a font is now one
+ * line in the generator: the panel grows a card and the docs table grows a row.
+ *
+ * The rule this installs, and it is the same one the colour half follows: **a configuration is
+ * authored once, where its values live.** The declaration, the control, the default and the
+ * attribute are resolved from it.
+ *
+ * `source` is the one field a contributed preference has no use for. It says WHO emits the selectors
+ * the attribute matches: `"themes"` is our generator, so the drift guards in `index.test.ts` can
+ * hold the declaration against the sheet; `"document"` is `compile()`, from something a TENANT
+ * authored after this package was built, and asserting a generated table for it would fail for the
+ * right feature.
+ */
+export type CorePrefDecl = SectionPrefDecl & {
+    source?: "themes" | "document";
+};
+/**
+ * Cast, because JSON is data and TypeScript reads it as widened literals — `kind: string` will not
+ * narrow to the union however it is written. The check is therefore a runtime one, in
+ * `index.test.ts`: every key is a key of `DEFAULT_PREFS`, every declaration is well-formed, and
+ * `check:generated` regenerates the file and fails on a diff.
+ */
+export declare const CORE_PREFS: Readonly<Record<CorePrefKey, CorePrefDecl>>;
+/**
+ * Every preference the core declares — which is every key of {@link ThemePrefs} except the two that
+ * are not choices at all.
+ *
+ * Written as an exclusion rather than a list, so the two exceptions have to justify themselves:
+ * `identityByPalette` is a *memory* (what this user last wore in each document, consulted only when
+ * the palette changes), and `sections` is the opaque bag another package's preferences ride in. A
+ * new axis appears here by appearing in `ThemePrefs`, and the generator has to answer for it.
+ */
+export type CorePrefKey = Exclude<keyof ThemePrefs, "sections">;
+/**
+ * The namespace the core's own preferences answer to in a tenant's policy.
+ *
+ * **The core is a section like any other, and this is the whole of what that costs.** A policy is
+ * keyed by namespace — `{ theme: { radius: { pinned: "sm" } }, graph: { look: { hidden: true } } }`
+ * — so a client shipping *compact and square* uses the mechanism an optional package already uses,
+ * and one chain answers for colour, geometry and a contributed choice alike.
+ *
+ * That is daisyUI's insight, in the mechanism this repo already had: their theme carries the
+ * geometry (`--radius-box`, `--size-field`, `--depth`) in the same document as the colours, so a
+ * tenant ships a coherent whole rather than a panel of unrelated knobs. Ours went half-way there
+ * when a palette became a document; the half not taken was that radius, density and the fonts had no
+ * document-level default at all — only a user could move them.
+ */
+export declare const CORE_NAMESPACE = "theme";
+/**
+ * Each axis → its `<html>` attribute + default value (at the default the attribute is removed).
+ *
+ * A projection of {@link CORE_PREFS} and no longer a table of its own: three things must agree about
+ * an axis — the React provider, the SSR pre-hydration script, and the generator that decides which
+ * selectors exist at all — and they now agree because there is one place to disagree with.
+ *
+ * These attributes go on `<html>`, never a wrapper element. Ark overlays (Dialog, Popover,
+ * Menu, Select, Tooltip, Toast…) portal to `document.body`, outside any wrapper, so tokens set
+ * on a wrapper would not reach them. `density` additionally *must* be on the root: it sets the
+ * root font-size and every size in the system is `rem`.
+ */
+export declare const AXES: {
+    key: keyof ThemePrefs;
+    attr: string;
+    def: string;
+    source: "themes" | "document";
+    /** See {@link SectionPrefDecl}. The stored value is a map keyed by the resolved appearance. */
+    byAppearance?: true;
+}[];
+export { fallbackChain, resolvePref, prefBoolean, prefNumber, prefOptions, resolveSectionToken, sectionOf, validatePrefs, validateSection, withSection, type LookDocument, type PrefOption, type PrefOptions, type PrefOrigin, type PrefSource, type PrefSources, type Problem, type ResolvedPref, type SectionManifest, type SectionPolicy, type SectionPrefDecl, type SectionPrefPolicy, type SectionTokenDecl, } from './sections.js';
+export { check as checkDensity, OBLIGATIONS as DENSITY_OBLIGATIONS, type Check as DensityCheck, type Obligation as DensityObligation, } from './obligations.js';
+export { AA, contrast, hex, inkFor, oklch, pageInk, type Oklch, } from './ink.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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