@texuli/spec 0.9.0 → 0.10.0

package/README.md

@@ -14,11 +14,19 @@ by Texuli's Kotlin Multiplatform twin. The package is framework-free: no
 DOM, no Svelte, no Node APIs and no runtime dependencies.
 
 > **Status: 0.x release.** Texuli is in development. The packages are
-> published to npm as `0.9.0`, a pre-1.0 release (1.0.0 will be the first
-> stable release). Under 0.x, a new minor (`0.10.0`) may contain breaking
-> changes, so pin the exact version or use `^0.9.0`, which accepts only 0.9.x.
-
-> **New in `0.9.0`.** `@texuli/spec@0.9.0` carries **spec 0.9.0**, a
+> published to npm as `0.10.0`, a pre-1.0 release (1.0.0 will be the first
+> stable release). Under 0.x, a new minor (`0.11.0`) may contain breaking
+> changes, so pin the exact version or use `^0.10.0`, which accepts only 0.10.x.
+
+> **New in `0.10.0`.** `@texuli/spec@0.10.0` carries **spec 0.10.0**: the
+> design-system document (`schemas/design-system.schema.json`, format
+> `texuli/design-system`) with its new `@texuli/spec/design-system`
+> subpath, and the optional `designSystem` on the envelope and on a
+> `document` (`$defs.designSystemReference`: `{ ref: "id@x.y.z" }` or
+> `{ inline: <document> }`). Every `0.9.0` envelope migrates by stamping
+> `spec`.
+
+> **New in `0.9.0`.** `@texuli/spec@0.9.0` carried **spec 0.9.0**, a
 > stamp-only catalog projection refresh (the Button pending note and the
 > cartesian charts' `xKind` and `locale`, from the Protoyard gaps G94 and
 > G97): the envelope, the `$defs` and the diagnostic codes are unchanged,
@@ -81,7 +89,7 @@ import {
   validateInstance,
 } from '@texuli/spec';
 
-SPEC_VERSION;                         // the spec version: '0.9.0' in @texuli/spec@0.9.0
+SPEC_VERSION;                         // the spec version: '0.10.0' in @texuli/spec@0.10.0
 SPEC_COMPONENT_IDS.includes('alert'); // true: the closed component vocabulary
 
 // The dialect validator: a closed subset of JSON Schema 2020-12.
@@ -113,7 +121,7 @@ import { type Schema, type SpecCatalog, validateBlueprint } from '@texuli/spec';
 import { migrateBlueprint } from '@texuli/spec/migrate';
 import { validateWorkflowGraph } from '@texuli/spec/workflow';
 
-const migrated = migrateBlueprint(blueprint); // 0.2.0 → … → 0.8.0 → 0.9.0; never throws
+const migrated = migrateBlueprint(blueprint); // 0.2.0 → … → 0.9.0 → 0.10.0; never throws
 const result = validateBlueprint(migrated.blueprint, {
   blueprintSchema: blueprintSchemaJson as Schema,
   catalog: componentsJson as SpecCatalog,
@@ -152,6 +160,7 @@ warning without failing.
 | `@texuli/spec/motion` | Runtime (new in `0.6.0`, spec `0.6.0`): the closed motion vocabulary and its check, shared by the catalog and the player ([motion.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/motion.md)) | `SPEC_MOTION_PRESETS`, `SPEC_MOTION_DURATIONS`, `SPEC_MOTION_STAGGERS`, `SPEC_MOTION_LEVELS`, `checkNodeMotion`, `checkEnvelopeMotion` |
 | `@texuli/spec/stream` | Runtime, opt-in (new in `0.6.0`): streamed blueprints ([stream.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/stream.md)) | `createJsonTokenizer`, `createBlueprintAssembler`, `createBlueprintStream`, `STREAM_NODE_ORDER` |
 | `@texuli/spec/source` | Runtime (new in `0.8.0`, spec `0.8.0`): data-source bindings, shared by the spec validator, `@texuli/catalog` and the player ([source.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/source.md)) | `checkSourceBinding`, `isSourceBinding`, `SOURCE_BINDING_KEY`, `SPEC_SOURCE_LIMITS`, `SPEC_SOURCE_FILTER_OPERATORS`, `SpecSourceDescriptor` |
+| `@texuli/spec/design-system` | Runtime, opt-in (new in `0.10.0`, spec `0.10.0`): the design-system document contract (ADR-021) ([design-system.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/design-system.md)) | `validateDesignSystem`, `validateDesignSystemPatch`, `applyDesignSystemPatch`, `migrateDesignSystem`, `checkDesignSystemReference`, `DesignSystem`, `DesignSystemPatch`, `DESIGN_SYSTEM_CODES`, `DESIGN_SYSTEM_LIMITS` |
 | `@texuli/spec/codegen` | Build time: generation and conformance | `buildSpec`, `projectCatalog`, `checkConformance`, `checkCatalogContract`, `formatJson`, `nextSpecVersion`, `checkVersionHistory` |
 
 ## Key guarantees
@@ -222,7 +231,9 @@ warning without failing.
   ([source.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/source.md)).
 - **Forms as data, never patterns or code (spec 0.8.0, new in `0.8.0`).** The
   agent-emittable `schema-form` id carries a closed form schema
-  (`$defs.formSchema`): fields of 15 closed types in sections or steps,
+  (`$defs.formSchema`): fields of 15 closed types in sections or steps (20
+  from `0.10.0`, which adds password, otp, color, datetime and the
+  host-painted custom type),
   named formats and host validator names (never a regular expression),
   and conditions and cross-field rules in the closed expression AST of
   `@texuli/core/expression` (`$defs.expression`, the `numberFormula` and
@@ -280,9 +291,18 @@ written for (`spec`; omitted means 0.2.0). `migrateBlueprint`
 (`@texuli/spec/migrate`) brings an
 envelope up to the current spec with pure, per-version steps
 (`src/migrations/`: `0.2.0 → 0.3.0`, `0.3.0 → 0.4.0`, `0.4.0 → 0.5.0`,
-`0.5.0 → 0.6.0`, `0.6.0 → 0.7.0`, `0.7.0 → 0.8.0` and `0.8.0 → 0.9.0`,
-each of which only stamps `spec`); a compatible version range is planned,
-not built. `@texuli/spec@0.9.0` carries spec `0.9.0` (digest
+`0.5.0 → 0.6.0`, `0.6.0 → 0.7.0`, `0.7.0 → 0.8.0`, `0.8.0 → 0.9.0` and
+`0.9.0 → 0.10.0`, each of which only stamps `spec`); a compatible version
+range is planned, not built. `@texuli/spec@0.10.0` carries spec `0.10.0` (digest
+`afcb9e3ed6b74b833a0f7477a657168621785ee98602ff582aa047e2d86aef17`), which adds the
+design-system document (PLAN_011 T-ds-spec) and the envelope's
+`designSystem` (T-ds-blueprint), plus a catalog projection refresh
+(`data-filter-builder` gains the optional `issues` prop and
+`fields[].optionLabels`, T-gaps-100-104) and an additive forms field
+vocabulary (`$defs.formField` gains the `password`, `otp`, `color`,
+`datetime` and `custom` types and the `kind`, `config`, `length`,
+`protocols` and `clearable` members, T-gaps-113-121; `command-palette` lists
+`searchLabel`, T-gaps-107-110). `@texuli/spec@0.9.0` carried spec `0.9.0` (digest
 `497df4d3b0c67d53483163ebd9bd73733b52caf5f8e2966478f1cf860e6f9d9d`), an
 additive catalog projection refresh (PLAN_011 T-gaps-87-95 and
 T-gaps-96-98); `@texuli/spec@0.8.0` carried spec `0.8.0` (digest
@@ -318,6 +338,8 @@ conformance harness) are in
   node shells; new in `0.6.0`): [stream.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/stream.md)
 - Data-source bindings (spec 0.8.0; new in `0.8.0`):
   [source.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/source.md)
+- The design-system document (spec 0.10.0; new in `0.10.0`):
+  [design-system.md](https://github.com/DailybotHQ/texuli/blob/main/packages/spec/docs/design-system.md)
 - The Kotlin Multiplatform twin that consumes the generated models:
   [native/README.md](https://github.com/DailybotHQ/texuli/blob/main/native/README.md)
 - Architecture: [ARCHITECTURE.md](https://github.com/DailybotHQ/texuli/blob/main/docs/ARCHITECTURE.md)

package/dist/build.d.ts

@@ -38,6 +38,11 @@ export declare const SCHEMA_UNITS: readonly [{
     readonly prefix: "";
     readonly ts: "workflow.ts";
     readonly kt: "Workflow.kt";
+}, {
+    readonly name: "design-system";
+    readonly prefix: "DesignSystem";
+    readonly ts: "design-system.ts";
+    readonly kt: "DesignSystem.kt";
 }];
 export declare const TS_OUT = "generated/typescript/";
 export declare const KOTLIN_OUT = "generated/kotlin/com/texuli/spec/";

package/dist/build.js

@@ -26,6 +26,7 @@ export const SCHEMA_UNITS = [
     { name: 'diagnostics', prefix: 'Spec', ts: 'diagnostics.ts', kt: 'Diagnostics.kt' },
     { name: 'manifest', prefix: 'Spec', ts: 'manifest.ts', kt: 'Manifest.kt' },
     { name: 'workflow', prefix: '', ts: 'workflow.ts', kt: 'Workflow.kt' },
+    { name: 'design-system', prefix: 'DesignSystem', ts: 'design-system.ts', kt: 'DesignSystem.kt' },
 ];
 export const TS_OUT = 'generated/typescript/';
 export const KOTLIN_OUT = 'generated/kotlin/com/texuli/spec/';

package/dist/codegen/kotlin-tokens.d.ts

@@ -0,0 +1,38 @@
+/** The color roles a token set carries, in output order (camelCase of `--tx-<role>`). */
+export declare const KOTLIN_TOKEN_ROLES: readonly ["background", "foreground", "surface", "surfaceForeground", "muted", "mutedForeground", "border", "borderStrong", "ring", "primary", "primaryForeground", "primarySoft", "primarySoftForeground", "secondary", "secondaryForeground", "accent", "accentForeground", "link", "destructive", "destructiveForeground", "destructiveSoft", "destructiveSoftForeground", "success", "successForeground", "warning", "warningForeground", "info", "infoForeground", "scrim"];
+export type KotlinTokenRole = (typeof KOTLIN_TOKEN_ROLES)[number];
+/** The web variable a role reads (`primarySoft` → `--tx-primary-soft`). */
+export declare function tokenVarName(role: string): string;
+/** One design system, resolved. Colors are `#rrggbb` or `#rrggbbaa`. */
+export interface KotlinTokenSystem {
+    /** The Kotlin property name (`Default`, `Acme`). */
+    name: string;
+    id: string;
+    version: string;
+    /** The compiled design system's hash. */
+    hash: string;
+    fonts: {
+        sans: string;
+        heading: string;
+        mono: string;
+    };
+    /** `--tx-radius` and `--tx-space-1`, in pixels (dp on native). */
+    radius: number;
+    space: number;
+    light: Readonly<Record<KotlinTokenRole, string>>;
+    dark?: Readonly<Record<KotlinTokenRole, string>> | null;
+}
+export interface KotlinTokenOptions {
+    /** Default `com.texuli.spec.tokens`. */
+    packageName?: string;
+    /** What produced the input, for the header comment. */
+    source?: string;
+}
+/** `#rrggbb` or `#rrggbbaa` as a Kotlin `0xAARRGGBBL` literal. */
+export declare function argbLiteral(color: string): string;
+/**
+ * The Kotlin source of `DesignTokenColors`, `DesignTokenSet` and an object
+ * holding each system. Throws on input it cannot express (a bad name, a
+ * color that is not sRGB hex, a negative length).
+ */
+export declare function designTokensToKotlin(systems: readonly KotlinTokenSystem[], options?: KotlinTokenOptions): string;

package/dist/codegen/kotlin-tokens.js

@@ -0,0 +1,138 @@
+/**
+ * Kotlin design tokens (ADR-024): a compiled design system's values as a
+ * Kotlin source file, so the native twin paints with the same colors,
+ * fonts, radius and spacing as the web. The input is plain resolved data
+ * (colors already sRGB hex, lengths in pixels), which a build step makes
+ * from `compileDesignSystem` in `@texuli/tokens`; this module never
+ * imports the compiler, so `@texuli/spec` stays at L0. Deterministic: the
+ * same input gives byte-identical output. Internal for now: only
+ * `scripts/design-tokens.ts` uses it, and it is not exported from
+ * `@texuli/spec/codegen` (that entry is at its size budget; a public
+ * subpath is planned).
+ */
+import { kotlinString } from "./kotlin.js";
+/** The color roles a token set carries, in output order (camelCase of `--tx-<role>`). */
+export const KOTLIN_TOKEN_ROLES = Object.freeze([
+    'background',
+    'foreground',
+    'surface',
+    'surfaceForeground',
+    'muted',
+    'mutedForeground',
+    'border',
+    'borderStrong',
+    'ring',
+    'primary',
+    'primaryForeground',
+    'primarySoft',
+    'primarySoftForeground',
+    'secondary',
+    'secondaryForeground',
+    'accent',
+    'accentForeground',
+    'link',
+    'destructive',
+    'destructiveForeground',
+    'destructiveSoft',
+    'destructiveSoftForeground',
+    'success',
+    'successForeground',
+    'warning',
+    'warningForeground',
+    'info',
+    'infoForeground',
+    'scrim',
+]);
+/** The web variable a role reads (`primarySoft` → `--tx-primary-soft`). */
+export function tokenVarName(role) {
+    return `--tx-${role.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`;
+}
+const I = '    ';
+const NAME = /^[A-Z][A-Za-z0-9]{0,63}$/;
+const PACKAGE = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$/;
+/** `#rrggbb` or `#rrggbbaa` as a Kotlin `0xAARRGGBBL` literal. */
+export function argbLiteral(color) {
+    const match = /^#([0-9a-fA-F]{6})([0-9a-fA-F]{2})?$/.exec(color);
+    if (!match)
+        throw new TypeError(`Not an sRGB hex color: ${JSON.stringify(color)}`);
+    return `0x${(match[2] ?? 'ff').toUpperCase()}${match[1].toUpperCase()}L`;
+}
+function number(value, what) {
+    if (!Number.isFinite(value) || value < 0 || value > 10_000) {
+        throw new TypeError(`${what} is not a length in pixels: ${value}`);
+    }
+    const text = String(Math.round(value * 1000) / 1000);
+    return text.includes('.') ? text : `${text}.0`;
+}
+function colors(values, depth) {
+    return [
+        'DesignTokenColors(',
+        ...KOTLIN_TOKEN_ROLES.map((role) => `${depth}${I}${role} = ${argbLiteral(values[role])},`),
+        `${depth})`,
+    ];
+}
+/**
+ * The Kotlin source of `DesignTokenColors`, `DesignTokenSet` and an object
+ * holding each system. Throws on input it cannot express (a bad name, a
+ * color that is not sRGB hex, a negative length).
+ */
+export function designTokensToKotlin(systems, options = {}) {
+    const packageName = options.packageName ?? 'com.texuli.spec.tokens';
+    if (!PACKAGE.test(packageName))
+        throw new TypeError(`Bad package name: ${packageName}`);
+    const names = new Set();
+    for (const system of systems) {
+        if (!NAME.test(system.name) || names.has(system.name)) {
+            throw new TypeError(`Bad or repeated token set name: ${JSON.stringify(system.name)}`);
+        }
+        names.add(system.name);
+    }
+    const lines = [
+        `// Generated from compiled design systems${options.source ? ` by ${options.source}` : ''}. Do not edit.`,
+        '',
+        `package ${packageName}`,
+        '',
+        '/** One mode of a design system: every color as `0xAARRGGBB` sRGB. */',
+        'class DesignTokenColors(',
+        ...KOTLIN_TOKEN_ROLES.map((role) => `${I}val ${role}: Long,`),
+        ') {',
+        `${I}/** Each color by the web variable it mirrors (\`--tx-background\` …). */`,
+        `${I}val byVar: Map<String, Long>`,
+        `${I}${I}get() = mapOf(`,
+        ...KOTLIN_TOKEN_ROLES.map((role) => `${I}${I}${I}${kotlinString(tokenVarName(role))} to ${role},`),
+        `${I}${I})`,
+        '}',
+        '',
+        '/** A compiled design system: fonts as CSS stacks, lengths in px (dp), colors per mode. */',
+        'class DesignTokenSet(',
+        `${I}val id: String,`,
+        `${I}val version: String,`,
+        `${I}val hash: String,`,
+        `${I}val fontSans: String,`,
+        `${I}val fontHeading: String,`,
+        `${I}val fontMono: String,`,
+        `${I}val radius: Double,`,
+        `${I}val space: Double,`,
+        `${I}val light: DesignTokenColors,`,
+        `${I}val dark: DesignTokenColors?,`,
+        ')',
+        '',
+        '/** The generated token sets. */',
+        'object DesignTokens {',
+    ];
+    for (const system of systems) {
+        const d = `${I}${I}`;
+        lines.push(`${I}val ${system.name}: DesignTokenSet = DesignTokenSet(`, `${d}id = ${kotlinString(system.id)},`, `${d}version = ${kotlinString(system.version)},`, `${d}hash = ${kotlinString(system.hash)},`, `${d}fontSans = ${kotlinString(system.fonts.sans)},`, `${d}fontHeading = ${kotlinString(system.fonts.heading)},`, `${d}fontMono = ${kotlinString(system.fonts.mono)},`, `${d}radius = ${number(system.radius, 'radius')},`, `${d}space = ${number(system.space, 'space')},`);
+        const light = colors(system.light, d);
+        lines.push(`${d}light = ${light[0]}`, ...light.slice(1, -1), `${light.at(-1)},`);
+        if (system.dark) {
+            const dark = colors(system.dark, d);
+            lines.push(`${d}dark = ${dark[0]}`, ...dark.slice(1, -1), `${dark.at(-1)},`);
+        }
+        else
+            lines.push(`${d}dark = null,`);
+        lines.push(`${I})`, '');
+    }
+    lines.push(`${I}/** Every set, in generation order. */`, `${I}val all: List<DesignTokenSet>`, `${I}${I}get() = listOf(${systems.map((system) => system.name).join(', ')})`, '}', '');
+    return lines.join('\n');
+}

package/dist/codegen/kotlin.d.ts

@@ -12,7 +12,9 @@ export declare const KOTLIN_PACKAGE = "com.texuli.spec";
 export declare function kotlinString(value: string): string;
 /**
  * The Kotlin property for a wire name: a leading `$` is stripped (`$state` →
- * `state`), because `$` starts a string template in Kotlin. The wire name
+ * `state`), because `$` starts a string template in Kotlin, and a hyphen
+ * joins camelCase (`height-md` → `heightMd`), because kebab-case keys (the
+ * design-system component registry) are not Kotlin names. The wire name
  * itself is always emitted through {@link kotlinString}.
  */
 export declare function kotlinProperty(name: string): string;

package/dist/codegen/kotlin.js

@@ -66,11 +66,14 @@ function field(name) {
 }
 /**
  * The Kotlin property for a wire name: a leading `$` is stripped (`$state` →
- * `state`), because `$` starts a string template in Kotlin. The wire name
+ * `state`), because `$` starts a string template in Kotlin, and a hyphen
+ * joins camelCase (`height-md` → `heightMd`), because kebab-case keys (the
+ * design-system component registry) are not Kotlin names. The wire name
  * itself is always emitted through {@link kotlinString}.
  */
 export function kotlinProperty(name) {
-    return name.startsWith('$') ? name.slice(1) : name;
+    const bare = name.startsWith('$') ? name.slice(1) : name;
+    return bare.replace(/-([A-Za-z0-9])/g, (_, char) => char.toUpperCase());
 }
 /** `$` escaped for a Kotlin string template (`\$state`). */
 function templateText(name) {

package/dist/design-system/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@texuli/spec/design-system` — the design-system document contract
+ * (ADR-021): the generated types, the closed vocabulary's codes and caps,
+ * `validateDesignSystem` with JSON paths, `DesignSystemPatch` with its check
+ * and pure merge, `migrateDesignSystem` and the blueprint reference check.
+ * Framework-free and dependency-free; the compiler lives in
+ * `@texuli/tokens/design-system/compile`.
+ */
+export type * from '../generated/typescript/design-system.js';
+export { applyDesignSystemPatch, checkDesignSystemReference, DESIGN_SYSTEM_MIGRATIONS, type DesignSystemMigration, type DesignSystemMigrationResult, type DesignSystemPatch, type DesignSystemValidateOptions, type DesignSystemValidation, migrateDesignSystem, validateDesignSystem, validateDesignSystemPatch, } from './validate.js';
+export { DESIGN_SYSTEM_CODES, DESIGN_SYSTEM_COMPILER_CODES, DESIGN_SYSTEM_FORMAT, DESIGN_SYSTEM_FORMAT_VERSION, DESIGN_SYSTEM_LIMITS, type DesignSystemCode, } from './vocabulary.js';

package/dist/design-system/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@texuli/spec/design-system` — the design-system document contract
+ * (ADR-021): the generated types, the closed vocabulary's codes and caps,
+ * `validateDesignSystem` with JSON paths, `DesignSystemPatch` with its check
+ * and pure merge, `migrateDesignSystem` and the blueprint reference check.
+ * Framework-free and dependency-free; the compiler lives in
+ * `@texuli/tokens/design-system/compile`.
+ */
+export { applyDesignSystemPatch, checkDesignSystemReference, DESIGN_SYSTEM_MIGRATIONS, migrateDesignSystem, validateDesignSystem, validateDesignSystemPatch, } from "./validate.js";
+export { DESIGN_SYSTEM_CODES, DESIGN_SYSTEM_COMPILER_CODES, DESIGN_SYSTEM_FORMAT, DESIGN_SYSTEM_FORMAT_VERSION, DESIGN_SYSTEM_LIMITS, } from "./vocabulary.js";

package/dist/design-system/schema.d.ts

@@ -0,0 +1,3 @@
+import type { Schema } from '../dialect.js';
+/** The design-system document schema, projected from the vocabulary table. */
+export declare function designSystemSchema(): Schema;

package/dist/design-system/schema.js

@@ -0,0 +1,164 @@
+import { pascal } from "../codegen/shared.js";
+import { DIALECT_URI } from "../dialect.js";
+import { DESIGN_SYSTEM_CODES, DESIGN_SYSTEM_COMPILER_CODES, DESIGN_SYSTEM_LIMITS, DS_DEFS, DS_PATTERNS, DS_ROOT, } from "./vocabulary.js";
+/**
+ * Build-time projection of the design-system vocabulary table into a
+ * dialect schema (`schemas/design-system.schema.json`), from which the spec
+ * generator writes the TypeScript and Kotlin types. Every object becomes a
+ * named `$defs` entry (named definitions keep their name; anonymous ones are
+ * named after their path), so both generators can project it. Rules the
+ * dialect cannot express (map key patterns, unique items, trust-dependent
+ * data URLs, inline byte caps, the `extends` chain) are described here and
+ * enforced by `validateDesignSystem`.
+ */
+const DESCRIPTIONS = {
+    colorValue: 'A color: #rgb, #rrggbb, #rrggbbaa or a numeric oklch(L C H[ / A]).',
+    roleName: 'A semantic color role of the token contract.',
+    roleMap: 'Explicit role pins for one mode: checked by the compiler, never moved (ADR-022).',
+    dataVizPalette: 'One mode’s chart palette: 8 categorical, 9 sequential and 9 diverging colors.',
+    fontFile: `A self-hosted font file: a same-origin relative path (.woff2, .woff, .ttf, .otf), or at developer trust a base64 data:font URL of at most ${DESIGN_SYSTEM_LIMITS.font} bytes.`,
+    fontFamily: 'A family stack (1 to 8 names, quoted by the compiler) and its font files.',
+    typeRole: 'A type role: family, size (px), weight, line height and tracking (em).',
+    typeRoleName: 'A type role name.',
+    radiusStep: 'A shape radius step.',
+    spaceStep: 'A space step.',
+    dimension: 'A space, control, icon or target size step.',
+    borderStep: 'A border width step.',
+    elevationLevel: 'An elevation level.',
+    opacityStep: 'An opacity step.',
+    strokeWidth: 'A stroke width in px.',
+    asset: `An image: a same-origin relative path (png, jpg, gif, webp, avif, svg, ico; never .., \\, %, ?, # or //), or at developer trust a base64 data:image (png, jpeg, gif, webp, avif) of at most ${DESIGN_SYSTEM_LIMITS.logo} bytes. SVG renders only as <img>.`,
+    color: 'Color: brand seeds, exact pins, explicit role pins per mode, modes, data viz per mode and status colors.',
+    typography: 'Typography: family stacks with font files, the scale and the type roles.',
+    shape: 'Shape: radius (px), radius scale and border width (px).',
+    space: 'Space: the base unit (px) and the density multiplier.',
+    elevation: 'Elevation style.',
+    surface: 'Surface style and glass settings.',
+    motion: 'Motion personality, durations (ms) and a named easing.',
+    layout: 'Layout widths, breakpoints and the grid (px).',
+    icons: 'Icon style, stroke and sizes (px).',
+    components: `Component tokens (the token registry, z-index left out) and defaults (variant and size), per component.`,
+    assets: 'Brand assets: logos and the favicon.',
+    voice: 'Voice data: tone words, a lexicon (at most 200 entries) and guidelines.',
+    accessibility: 'Accessibility targets: contrast, minimum target size and the focus style.',
+    variant: 'A named variant (high-contrast, compact, seasonal): a closed partial document of sections, orthogonal to mode.',
+    issueCode: 'Every stable design-system code; aa-text, aa-focus and target-size are raised by the compiler.',
+    issue: 'One design-system issue: a stable code, a JSON path from $, a message and an optional hint.',
+};
+function source(node) {
+    const path = (node[1] === 'i' ? DS_PATTERNS.image : DS_PATTERNS.font).source.slice(1, -1);
+    const data = node[1] === 'i' ? 'data:image\\/(?:png|jpeg|gif|webp|avif)' : 'data:font\\/(?:woff2?|ttf|otf)';
+    return {
+        description: `At most ${node[2]} bytes inline; data URLs need developer trust.`,
+        type: 'string',
+        pattern: `^(?:${path}|${data};base64,[A-Za-z0-9+/]+={0,2})$`,
+    };
+}
+/** The design-system document schema, projected from the vocabulary table. */
+export function designSystemSchema() {
+    const defs = {};
+    const toSchema = (node, name) => {
+        if (typeof node === 'string')
+            return { $ref: `#/$defs/${node}` };
+        if (!Array.isArray(node)) {
+            if (!Object.hasOwn(defs, name))
+                defs[name] = objectSchema(node, name);
+            return { $ref: `#/$defs/${name}` };
+        }
+        const n = node;
+        switch (n[0]) {
+            case 'e':
+                return { type: 'string', enum: n[1].split(' ') };
+            case 'n':
+            case 'i':
+                return { type: n[0] === 'i' ? 'integer' : 'number', minimum: n[1], maximum: n[2] };
+            case 's':
+                return { type: 'string', maxLength: n[2], pattern: n[1].source };
+            case 't':
+                return { type: 'string', maxLength: n[1], pattern: DS_PATTERNS.text.source };
+            case 'l':
+                return {
+                    ...(n[4] ? { description: 'Unique items.' } : {}),
+                    type: 'array',
+                    items: toSchema(n[1], `${name}Item`),
+                    ...(n[2] > 0 ? { minItems: n[2] } : {}),
+                    maxItems: n[3],
+                };
+            case 'm':
+                return {
+                    description: `At most ${n[2]} entries; keys match ${n[3].source} and are never __proto__, constructor or prototype.`,
+                    type: 'object',
+                    additionalProperties: toSchema(n[1], `${name}Value`),
+                };
+            case 'b':
+                return { type: 'boolean' };
+            case 'k':
+                return { const: n[1] };
+            case 'u':
+                return source(n);
+            case 'x':
+                return {
+                    description: 'texuli:<theme> or an exact id@x.y.z; never a range, a URL or a path. Cycles and chains deeper than 4 are refused.',
+                    type: 'string',
+                    pattern: DS_PATTERNS.ref.source,
+                };
+        }
+    };
+    function objectSchema(shape, name) {
+        const properties = {};
+        const required = [];
+        for (const [raw, child] of Object.entries(shape)) {
+            const key = raw.replace(/!$/, '');
+            if (raw.endsWith('!'))
+                required.push(key);
+            properties[key] = toSchema(child, `${name}${pascal(key)}`);
+        }
+        return {
+            ...(DESCRIPTIONS[name] ? { description: DESCRIPTIONS[name] } : {}),
+            type: 'object',
+            properties,
+            ...(required.length > 0 ? { required } : {}),
+            additionalProperties: false,
+        };
+    }
+    for (const [name, node] of Object.entries(DS_DEFS)) {
+        if (typeof node !== 'string' && !Array.isArray(node))
+            toSchema(node, name);
+        else {
+            const schema = toSchema(node, name);
+            defs[name] = DESCRIPTIONS[name] ? { description: DESCRIPTIONS[name], ...schema } : schema;
+        }
+    }
+    defs.issueCode = {
+        description: DESCRIPTIONS.issueCode,
+        type: 'string',
+        enum: [...DESIGN_SYSTEM_CODES, ...DESIGN_SYSTEM_COMPILER_CODES],
+    };
+    defs.issue = {
+        description: DESCRIPTIONS.issue,
+        type: 'object',
+        properties: {
+            code: { $ref: '#/$defs/issueCode' },
+            path: { type: 'string' },
+            message: { type: 'string' },
+            hint: { type: 'string' },
+        },
+        required: ['code', 'path', 'message'],
+        additionalProperties: false,
+    };
+    const root = objectSchema(DS_ROOT, 'designSystem');
+    const ordered = {};
+    for (const key of Object.keys(defs).sort())
+        ordered[key] = defs[key];
+    return {
+        $schema: DIALECT_URI,
+        $id: 'https://texuli.example/spec/schemas/design-system.schema.json',
+        title: 'DesignSystem',
+        description: 'A Texuli design system (ADR-021, formatVersion 1): one closed JSON document a company or an agent writes once and every Texuli surface follows. Data only: colors are hex or numeric oklch, lengths are numbers in px, fonts and assets are same-origin relative paths or capped data URLs, and nothing reaches CSS that the token contract’s css-safe checks would refuse. Generated from @texuli/spec/design-system’s vocabulary by scripts/design-system-schema.ts; validateDesignSystem enforces the rules the dialect cannot express.',
+        type: 'object',
+        properties: root.properties,
+        required: root.required,
+        additionalProperties: false,
+        $defs: ordered,
+    };
+}

package/dist/design-system/validate.d.ts

@@ -0,0 +1,69 @@
+import type { DesignSystem, DesignSystemIssue, DesignSystemVariant } from '../generated/typescript/design-system.js';
+/** The result of every design-system check: issues with JSON paths from `$`. */
+export interface DesignSystemValidation {
+    ok: boolean;
+    errors: readonly DesignSystemIssue[];
+}
+export interface DesignSystemValidateOptions {
+    /**
+     * `untrusted` (the default: agent or user documents) refuses every `data:`
+     * URL; `developer` (documents the host supplies) accepts base64 raster
+     * images and fonts within their caps. SVG is a relative path only.
+     */
+    trust?: 'developer' | 'untrusted';
+    /** Resolve `id@version` for the `extends` chain (cycles and depth); synchronous. */
+    resolve?: (ref: string) => unknown;
+    /** Stop after this many issues (default and ceiling 64). */
+    maxErrors?: number;
+}
+/**
+ * Check a design-system document against the closed vocabulary. Never
+ * throws on a JSON value; returns every issue (up to `maxErrors`) with a
+ * stable code and a JSON path. A future `formatVersion` stops at
+ * `format-version`.
+ */
+export declare function validateDesignSystem(doc: unknown, options?: DesignSystemValidateOptions): DesignSystemValidation;
+/** A typed partial document: objects merge, arrays replace, `null` removes. */
+export type DesignSystemPatch = PatchOf<DesignSystemVariant>;
+type PatchOf<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: PatchOf<T[K]> | null;
+} : T;
+/** Check a patch: the sections only, every field optional, `null` to remove. */
+export declare function validateDesignSystemPatch(patch: unknown, options?: DesignSystemValidateOptions): DesignSystemValidation;
+/**
+ * Merge a patch into a document, purely: objects merge, arrays and scalars
+ * replace, `null` removes, and `__proto__`, `constructor` and `prototype`
+ * are skipped. Validate the result again.
+ */
+export declare function applyDesignSystemPatch(base: DesignSystem, patch: DesignSystemPatch): DesignSystem;
+/** One `formatVersion` step. */
+export interface DesignSystemMigration {
+    from: number;
+    to: number;
+    migrate(doc: Readonly<Record<string, unknown>>): Record<string, unknown>;
+}
+/** Every step, in order (none yet: formatVersion 1 is the first). */
+export declare const DESIGN_SYSTEM_MIGRATIONS: readonly DesignSystemMigration[];
+export type DesignSystemMigrationResult = {
+    ok: true;
+    document: DesignSystem;
+    from: number;
+    to: number;
+    applied: string[];
+} | {
+    ok: false;
+    errors: [DesignSystemIssue];
+};
+/**
+ * Bring a document up to the current `formatVersion`. Pure and total: never
+ * throws on a JSON value and never mutates it; an unknown or future version
+ * is a `format-version` result. Validate the migrated document.
+ */
+export declare function migrateDesignSystem(doc: unknown): DesignSystemMigrationResult;
+/**
+ * Check a blueprint's design-system reference: exactly one of `ref`
+ * (`id@x.y.z` or `texuli:<theme>`) and `inline` (a whole document, checked
+ * by {@link validateDesignSystem} at `options.trust`).
+ */
+export declare function checkDesignSystemReference(value: unknown, options?: DesignSystemValidateOptions): DesignSystemValidation;
+export {};