@geonosis/themekit 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,456 @@
+/**
+ * The tokens contract — the semantic surface a brand fills in.
+ *
+ * Generalised from dielime's `BrandTheme` (measured in `docs/themekit-inventory-2026-08-30.md`),
+ * with two deliberate widenings and one deliberate narrowing:
+ *
+ * - `fonts`, `radii` and `shadows` are OPEN maps, not fixed keys. dielime names its font roles
+ *   `body` and `display`; another repo names them `sans`/`serif`/`mono`; during.day has no radii at
+ *   all. Font roles are data (law 6), so the contract may not decide them — `font-roles-only` takes
+ *   the list as an option for the same reason.
+ * - `colors` stays a NAMED set, because the role names are the contract's whole value and they are
+ *   design-system vocabulary rather than any repo's: "primary" is not a dielime word. A brand with
+ *   a colour the set does not model puts it in `extra`, which is what `extra` is for.
+ * - `logo` and the brand's identity are NOT here. They live in `brand.json` beside the tokens: a
+ *   logo is an asset descriptor with no DTCG type and no CSS output, and mixing it into the token
+ *   file is what makes a token file un-exportable.
+ *
+ * Every value is a CSS value as authored — `#ffe849`, `oklch(0.91 0.17 102)`, `var(--mc-gray-c)`,
+ * `color-mix(in srgb, … )`, a whole font stack, a whole shadow. The kit never re-spells one.
+ */
+/** A CSS value, exactly as authored. Never parsed, never normalised, never rounded. */
+type TokenValue = string;
+/**
+ * Colour roles. Names express ROLE, not hue — a brand's `primary` can be any colour.
+ *
+ * Required roles are the ones a component library cannot render without. The optional ones are
+ * optional because dielime ships themes without them, and a contract that demanded them would
+ * refuse the themes it was extracted from.
+ */
+interface ThemeColors {
+    /** Decorative accent — highlights, ribbons, badges. */
+    accent?: TokenValue;
+    /** Default page surface. */
+    background: TokenValue;
+    /** Hairlines, dividers, input borders. */
+    border: TokenValue;
+    /** Destructive and error states. */
+    danger: TokenValue;
+    /** Focus rings and selection highlights. */
+    focusRing: TokenValue;
+    /** Default text and icon colour on `background`. */
+    foreground: TokenValue;
+    /** Inline link text. Falls back to `primary` when a brand omits it. */
+    link?: TokenValue;
+    /** Subdued text — captions, secondary copy. */
+    muted: TokenValue;
+    /** Text and icons on `accent`. */
+    onAccent?: TokenValue;
+    /** Text and icons on `primary`. Should clear WCAG AA against it. */
+    onPrimary: TokenValue;
+    /** Text and icons on `secondary`. */
+    onSecondary: TokenValue;
+    /** Text and icons on `surface`. */
+    onSurface: TokenValue;
+    /** Text and icons on `surfaceInverse`. */
+    onSurfaceInverse?: TokenValue;
+    /** Brand identity — primary CTAs, active states, brand chrome. */
+    primary: TokenValue;
+    /** Supportive identity — secondary CTAs, accents. */
+    secondary: TokenValue;
+    /** Positive and success states. */
+    success: TokenValue;
+    /** Elevated surface, one step above `background` — cards, popovers. */
+    surface: TokenValue;
+    /** Inverse surface — footers and dark sections under light content. */
+    surfaceInverse?: TokenValue;
+    /** Warning and caution states. */
+    warning: TokenValue;
+}
+/** One status's surface and the colour that reads on it. */
+interface StatusPair {
+    onSurface: TokenValue;
+    surface: TokenValue;
+}
+/**
+ * Per-status banner and alert pairs. Optional: a component library falls back to the core
+ * `success`/`warning`/`danger` roles when a brand omits them.
+ */
+interface ThemeStatusColors {
+    danger?: StatusPair;
+    info?: StatusPair;
+    success?: StatusPair;
+    warning?: StatusPair;
+}
+/** Font roles → family stacks. The role names are the repo's, never the kit's. */
+type ThemeFonts = Record<string, TokenValue>;
+/** Corner radii by step name. */
+type ThemeRadii = Record<string, TokenValue>;
+/** Elevation steps. Each value is a whole CSS `box-shadow`, kept as one string. */
+type ThemeShadows = Record<string, TokenValue>;
+/**
+ * A theme: the values, and nothing about where they are rendered.
+ *
+ * `id` and `name` identify it; everything else is tokens. What the tokens compile TO is the
+ * `Emission` map, which is a separate input — the same theme compiles to `--mc-*` for one repo and
+ * to `--color-*` for another without being touched.
+ */
+interface Theme {
+    colors: ThemeColors;
+    /**
+     * Brand-only tokens the semantic contract deliberately does not model — a seasonal pink, a
+     * gradient, a partner's blue. Keys are emitted VERBATIM, so `limeWilt` stays `limeWilt`; nothing
+     * kebab-cases them, because `--mc-limeWilt` is a valid custom property and the one a stylesheet
+     * that already exists is reading.
+     */
+    extra?: Record<string, TokenValue>;
+    fonts: ThemeFonts;
+    /** Stable identifier — what a `[data-brand="…"]` selector and a baseline name are keyed by. */
+    id: string;
+    /** Human-readable name, for a switcher's label. */
+    name: string;
+    radii: ThemeRadii;
+    shadows: ThemeShadows;
+    status?: ThemeStatusColors;
+}
+/**
+ * Typed authoring entry. Returns the theme unchanged — its only job is to pin the type so an editor
+ * completes the roles and rejects an invented one at the call site.
+ */
+declare const defineTheme: (theme: Theme) => Theme;
+
+/**
+ * The variable map: which CSS custom properties a theme compiles to, in what order, as DATA.
+ *
+ * dielime emits `--mc-primary`, `--theme-primary`, `--primary` and `--ring` from four different
+ * vocabularies at once — its own brand prefix, a legacy layer, shadcn's names, Tailwind's radius
+ * scale. Every one of those is a fact about dielime's stylesheet, not about theming, so none of
+ * them may be a default in this package (law 6). What ships instead is the SHAPE of a map plus a
+ * generic default that holds for a repo which has declared nothing.
+ *
+ * The order of the list is the emission order, and it is load-bearing twice over: a `:root { … }`
+ * block reads top to bottom, and a later entry that names an earlier variable overwrites its VALUE
+ * while keeping its POSITION — which is how a brand's `extra` overrides a derived colour.
+ */
+/**
+ * A dotted path into the theme: `colors.primary`, `radii.md`, `fonts.body`,
+ * `status.danger.surface`, `extra.limeWilt`. A path that resolves to nothing means the emission is
+ * skipped, which is how an optional role stays optional with no special case anywhere.
+ */
+type RolePath = string;
+/** `color-mix(in <space>, <role> <amount>, <with>)`, spelled exactly like that. */
+interface Mix {
+    /** The first colour's share — `'85%'`. */
+    amount: string;
+    /** The role mixed FROM. */
+    role: RolePath;
+    /** The interpolation space. Defaults to `srgb`. */
+    space?: string;
+    /** The colour mixed INTO — `'#000000'`. */
+    with: string;
+}
+/** Copy a role's value into a variable. */
+interface CopyEmission {
+    role: RolePath;
+    variable: string;
+}
+/** Compute a variable by mixing a role with another colour. */
+interface MixEmission {
+    mix: Mix;
+    variable: string;
+}
+/**
+ * One variable per key of an open map — `extra`, `radii`, `fonts` — named `<prefix><key>`.
+ *
+ * The key is used VERBATIM. Case-folding it is the obvious wrong normalisation: `--mc-limeWilt` is
+ * a valid custom property and, in a repo that already ships one, the name a stylesheet is reading.
+ */
+interface EachEmission {
+    each: 'extra' | 'fonts' | 'radii' | 'shadows';
+    prefix: string;
+}
+type Emission = CopyEmission | EachEmission | MixEmission;
+/**
+ * Read a dotted path off a theme, or nothing.
+ *
+ * Deliberately total and deliberately quiet: an emission naming a role the theme does not carry is
+ * how `--accent` stays conditional, so a miss cannot be an error here. What a miss must never do is
+ * emit an empty variable — `--accent: ;` is a parse error in the stylesheet and a silent one in the
+ * compiler, which is the class of failure this whole package exists downstream of.
+ */
+declare const valueAt: (theme: Theme, path: RolePath) => TokenValue | undefined;
+/**
+ * The variables an emission map writes for a theme, in order.
+ *
+ * Assignment rather than accumulation, so a repeated variable keeps its first position and takes
+ * its last value — JavaScript's own record semantics, which is what the stylesheet a consumer
+ * already ships was written against.
+ */
+declare const emitVariables: (theme: Theme, emit: readonly Emission[]) => Record<string, string>;
+/**
+ * The map a repo gets when it has declared none: one variable per role, `<prefix><kebab-role>`,
+ * nothing derived and nothing aliased.
+ *
+ * It is not dielime's map and is not meant to be. A repo with an existing stylesheet declares its
+ * own; a repo starting from zero gets a complete, predictable set and no opinions about shadcn.
+ */
+declare const defaultEmission: (prefix?: string) => Emission[];
+
+/**
+ * Compile a theme to the four shapes a consumer actually needs, from one pass over one map.
+ *
+ * Nothing here launches, renders or resolves anything: a theme in, strings out. That is what makes
+ * the extraction possible at all — the compiler it replaces was pure too, and a compiler that
+ * needed React would have taken a component library with it (D-010).
+ */
+interface CompileOptions {
+    /**
+     * A CSS-value expression per emitted variable, for the Tailwind v4 `@theme inline` block —
+     * `(variable) => `--color-brand${variable.slice(4)}``. Omitted, no block is generated.
+     */
+    readonly themeBlock?: (variable: string) => string | undefined;
+    /** The variable map. Defaults to {@link defaultEmission} — generic, not any repo's. */
+    readonly emit?: readonly Emission[];
+    /** The selector the `css` block targets. Defaults to `:root`. */
+    readonly selector?: string;
+}
+interface Compiled {
+    /** The custom properties, in emission order. Spreadable into a `style` prop as-is. */
+    readonly cssVariables: Record<string, string>;
+    /** `<selector> { … }`, one declaration per line, newline-terminated. */
+    readonly css: string;
+    /** The theme it was compiled from, unchanged. */
+    readonly object: Theme;
+    /**
+     * Role path → resolved value, flat: `plain['colors.primary']`, `plain['radii.md']`.
+     *
+     * For the consumers that cannot use custom properties at all — react-email inline styles, an
+     * `<svg fill>`, a canvas. It is deliberately NOT the variable record: a mail client that drops
+     * `var()` needs the value, and which variable a repo happens to call it by is not its business.
+     */
+    readonly plain: Record<string, TokenValue>;
+    /** The Tailwind v4 `@theme inline { … }` block, or `''` when no mapper was given. */
+    readonly themeBlock: string;
+}
+declare const compile: (theme: Theme, options?: CompileOptions) => Compiled;
+
+/**
+ * DTCG in and out — the interchange, and the one place the kit deviates from the draft on purpose.
+ *
+ * The Design Tokens Community Group draft types a colour as an OBJECT (`colorSpace`, `components`),
+ * a dimension as `{ value, unit }` and a shadow as five named fields. Every value in a real theme
+ * measured for this package is a CSS string instead, and three kinds of them cannot become those
+ * objects at all: `var(--mc-gray-c)` has no colour space, `color-mix(in srgb, … )` is a computation,
+ * and `0 1px 5px rgb(0 0 0 / 0.12)` is a spelling — parse it into five fields and print it back and
+ * you get the same colour and different bytes.
+ *
+ * Different bytes is the whole problem. The gate on this extraction is that a repo's stylesheet is
+ * unchanged afterwards, so a token file that re-spells a value on the way through is not an
+ * interchange format, it is a rewrite.
+ *
+ * **So this profile stores `$value` as the CSS string, exactly as authored.** Everything else is
+ * the draft: groups, `$value`, `$type`, `{alias}`-shaped names, `$extensions`. The deviation is
+ * declared in the document itself and measured by `validateDtcg(doc, { strict: true })`, which
+ * names the tokens the strict draft could not hold — the extension the draft would need, per token,
+ * rather than as a paragraph in a README nobody diffs.
+ */
+/** Reverse-domain key for the kit's own `$extensions` block, as the draft requires. */
+declare const GEONOSIS_EXTENSION = "com.microcompanies.geonosis";
+/** The profile name written into every document the kit produces. */
+declare const PROFILE = "css-values";
+type DtcgType = 'color' | 'dimension' | 'fontFamily' | 'gradient' | 'shadow';
+interface DtcgToken {
+    $description?: string;
+    $type: DtcgType;
+    $value: TokenValue;
+}
+interface BrandIdentity {
+    id: string;
+    name: string;
+    profile: string;
+}
+interface DtcgDocument {
+    [group: string]: unknown;
+    $extensions: Record<string, BrandIdentity | undefined>;
+}
+/**
+ * A theme as a DTCG document.
+ *
+ * A group the theme does not carry is left out entirely rather than written empty: an empty group
+ * is indistinguishable from a group whose tokens were lost, and `fromDtcg` would hand back
+ * `extra: {}` where the theme said nothing at all.
+ */
+declare const toDtcg: (theme: Theme) => DtcgDocument;
+/**
+ * A DTCG document as a theme.
+ *
+ * Deliberately lossy in exactly one direction and no other: `$description` has nowhere to go in the
+ * contract, so it is dropped. `validateDtcg` names every path where that will happen, because a
+ * conversion that quietly deletes half a file is the failure mode the whole package is downstream
+ * of.
+ */
+declare const fromDtcg: (document: Record<string, unknown>) => Theme;
+interface ValidateOptions {
+    /** Also report every value the DTCG draft's own `$value` shapes could not hold. */
+    readonly strict?: boolean;
+}
+interface DtcgReport {
+    /** Structural breaks. Non-empty means the document is not this profile. */
+    readonly errors: string[];
+    /** Paths whose data a round trip through the contract would drop. */
+    readonly lossy: string[];
+    readonly valid: boolean;
+}
+/**
+ * Judge a document against this profile, and — on request — against the strict draft.
+ *
+ * Structure first: a token without `$value`, a `$value` that is not a string, a `$type` the group
+ * cannot have, an identity block that is not there. Then `lossy`, which is not an error but is
+ * never silent. Then, under `strict`, the tokens whose value the draft's own shapes cannot express
+ * — the list of extensions the draft would need to hold this file, per token.
+ */
+declare const validateDtcg: (document: Record<string, unknown>, options?: ValidateOptions) => DtcgReport;
+
+/**
+ * Figma variables → DTCG, over the shape the REST API documents for
+ * `GET /v1/files/:key/variables/local`.
+ *
+ * Two things decide whether an importer is worth having, and both of them are about what it does
+ * with what it cannot handle.
+ *
+ * **Aliases.** A real Figma file is a `Primitives` collection nobody themes and a `Semantic`
+ * collection whose every variable is an ALIAS into it. An importer that did not resolve those would
+ * write `VariableID:1` where a colour goes, and — worse — every mode would come out identical,
+ * because the id does not change per mode. Resolution follows the chain in the mode being imported,
+ * falling back to a collection's own default mode when it does not have that mode (`Primitives` has
+ * never heard of `Dark`), and stops on a cycle with a report rather than a stack overflow.
+ *
+ * **Everything it will not guess.** A `BOOLEAN` is not a design token. A `FLOAT` is a bare number:
+ * Figma carries `8`, with nothing anywhere saying `px` or `rem`, and guessing `px` is right most of
+ * the time and produces, the rest of the time, a layout nobody can trace back to an import. A
+ * variable nobody mapped is a token a designer made and the contract does not model. None of the
+ * three is dropped: the first two are reported in `unsupported` with a reason, and the third is
+ * imported into `extra` — the escape hatch — and listed in `unmapped`.
+ */
+type FigmaColor = {
+    a?: number;
+    b: number;
+    g: number;
+    r: number;
+};
+type FigmaAlias = {
+    id: string;
+    type: 'VARIABLE_ALIAS';
+};
+type FigmaValue = boolean | FigmaAlias | FigmaColor | number | string;
+interface FigmaVariable {
+    name: string;
+    resolvedType: string;
+    valuesByMode: Record<string, FigmaValue>;
+    variableCollectionId: string;
+}
+interface FigmaCollection {
+    defaultModeId: string;
+    modes: {
+        modeId: string;
+        name: string;
+    }[];
+    name: string;
+}
+interface ImportedTheme {
+    id: string;
+    /** The mode's own name, as the designer typed it. */
+    name: string;
+    tokens: DtcgDocument;
+}
+interface FigmaImport {
+    themes: ImportedTheme[];
+    /** Variables the `map` did not name. Imported into `extra`, never dropped. */
+    unmapped: string[];
+    /** `name: reason` per variable that could not become a token at all. */
+    unsupported: string[];
+}
+interface FigmaOptions {
+    /**
+     * The name of the collection whose modes become themes. Defaults to the collection with the most
+     * modes — which is the semantic one in every file built the usual way.
+     */
+    readonly collection?: string;
+    /**
+     * The unit a `FLOAT` is in. Unset, every FLOAT is reported as unsupported: the payload does not
+     * carry a unit and this package does not invent one.
+     */
+    readonly floatUnit?: 'px' | 'rem';
+    /** Figma variable name → contract role path. The designer's vocabulary meeting the repo's. */
+    readonly map?: Record<string, string>;
+}
+declare const fromFigmaVariables: (payload: Record<string, unknown>, options?: FigmaOptions) => FigmaImport;
+
+/**
+ * A themekit read off disk.
+ *
+ * The registry is FILES — `themekits/<brand>/` in this repo, a directory vendored into a consumer,
+ * a directory inside `node_modules`. `loadThemekit` takes a path and does not care which, and that
+ * is deliberate: whose brand gets published, and where, is the brand owner's decision and not the
+ * kit's. Nothing here ships inside `@geonosis/themekit`'s tarball (`files: ["dist"]`), so installing
+ * the compiler never installs somebody else's colours.
+ */
+/** `themekit.json` — the manifest, which is what a version lives in. */
+interface ThemekitManifest {
+    /** Does the theme fill every required colour role? Checked, never taken on trust. */
+    complete: boolean;
+    description?: string;
+    /**
+     * Path to the emission map, relative to this directory. Two brands over one UI kit share one map,
+     * and one fact copied into two files is two facts that will disagree.
+     */
+    emit?: string;
+    name: string;
+    version: string;
+}
+/** `brand.json` — identity, which is not tokens: a name, a logo, whatever else a brand carries. */
+interface Brand {
+    [key: string]: unknown;
+    id: string;
+    name: string;
+}
+interface Themekit {
+    brand: Brand;
+    /** From `emit.json`, or the generic default when the directory checks none in. */
+    emit: Emission[];
+    manifest: ThemekitManifest;
+    /** Required colour roles the theme does not fill. Empty for a complete themekit. */
+    missingRoles: string[];
+    theme: Theme;
+    /** The DTCG document as read, before it became a theme. */
+    tokens: Record<string, unknown>;
+}
+interface LoadOptions {
+    /**
+     * The version the consumer expects. A directory whose version has moved is REFUSED rather than
+     * loaded, which is what makes "a bump is invisible until you pin it" true instead of hopeful —
+     * a pin nobody checks is a comment.
+     */
+    readonly pinned?: string;
+}
+/**
+ * The colour roles a theme must fill.
+ *
+ * The optional ones are optional because the real themes this was extracted from omit them, and a
+ * contract that demanded them would refuse the themes it came from.
+ */
+declare const REQUIRED_COLOR_ROLES: readonly ["background", "border", "danger", "focusRing", "foreground", "muted", "onPrimary", "onSecondary", "onSurface", "primary", "secondary", "success", "surface", "warning"];
+/** Which required roles a theme leaves empty, by role path. */
+declare const MISSING_ROLES: (theme: Theme) => string[];
+/**
+ * Read, validate and refuse. Never repair.
+ *
+ * Four things stop the load: the directory is not a themekit, the manifest carries no version, the
+ * tokens are not this profile (naming the token), or the manifest CLAIMS to be complete while a
+ * required role is empty. The last one is the one worth having: an incomplete themekit is honest
+ * and a consumer can plan around it, while a manifest that lies about being complete is a page that
+ * renders wrong on someone else's machine.
+ */
+declare const loadThemekit: (dir: string, options?: LoadOptions) => Themekit;
+
+export { type Brand, type BrandIdentity, type CompileOptions, type Compiled, type CopyEmission, type DtcgDocument, type DtcgReport, type DtcgToken, type DtcgType, type EachEmission, type Emission, type FigmaAlias, type FigmaCollection, type FigmaColor, type FigmaImport, type FigmaOptions, type FigmaValue, type FigmaVariable, GEONOSIS_EXTENSION, type ImportedTheme, type LoadOptions, MISSING_ROLES, type Mix, type MixEmission, PROFILE, REQUIRED_COLOR_ROLES, type RolePath, type StatusPair, type Theme, type ThemeColors, type ThemeFonts, type ThemeRadii, type ThemeShadows, type ThemeStatusColors, type Themekit, type ThemekitManifest, type TokenValue, type ValidateOptions, compile, defaultEmission, defineTheme, emitVariables, fromDtcg, fromFigmaVariables, loadThemekit, toDtcg, validateDtcg, valueAt };