@vireo-ai/trellis-ui 0.1.59 → 0.1.61

package/packages/theme-engine/README.md

@@ -0,0 +1,221 @@
+# Trellis Theme Engine
+
+The theme engine is a deterministic compiler from a materialized JSON `ThemeConfig` to a complete generated theme,
+a [DTCG 2025.10](https://www.designtokens.org/TR/2025.10/) design-token document, and output artifacts such as
+Tailwind-compatible CSS. It encodes brand
+relationships once so components and custom compositions stay in sync.
+
+## Top-down model
+
+```mermaid
+flowchart TD
+    base["Base ThemeConfig<br/>validated authored JSON"] --> materialize["materializeTheme<br/>apply ordered atomic commits"]
+    commits["Theme Patch Commits<br/>RFC 6902 add · remove · replace"] --> materialize
+    materialize --> config["Materialized ThemeConfig<br/>complete authored compiler input"]
+
+    config --> entry["generateTheme<br/>public compiler entry"]
+    config --> knobs["createThemeKnobCatalog<br/>generated authoring read model"]
+    entry --> resolve["generateColorTheme → resolveThemeConfig<br/>validate, merge baselines, parse, and record provenance"]
+    resolve --> resolved["ResolvedThemeConfig<br/>one explicit and internally consistent specification"]
+
+    resolved --> color["Color branch<br/>canvas, families, surfaces, depth, semantics"]
+    color --> colorTheme["GeneratedColorTheme<br/>color must succeed before the remaining axes run"]
+    colorTheme --> composition["Composition<br/>breakpoints, grids, shell"]
+    colorTheme --> edge["Edge<br/>line weights and anatomy roles"]
+    colorTheme --> radius["Radius<br/>scale and anatomy roles"]
+    colorTheme --> spacing["Spacing<br/>progressive fluid scale and anatomy aliases"]
+    colorTheme --> typography["Typography<br/>families, type scale, and text roles"]
+    colorTheme --> sizing["Sizing<br/>controls, icons, measures, and component anatomy"]
+    colorTheme --> motion["Motion<br/>durations, bounce, and displacement"]
+
+    colorTheme --> generated["GeneratedTheme<br/>values, dependencies, diagnostics, and fingerprint"]
+    composition --> generated
+    edge --> generated
+    radius --> generated
+    spacing --> generated
+    typography --> generated
+    sizing --> generated
+    motion --> generated
+
+    generated --> validate["validateGeneratedTheme<br/>reject broken generated relationships"]
+    validate --> tokens["generateDesignTokens<br/>DTCG 2025.10 resolver document"]
+    tokens --> serialize["Output adapters<br/>consume tokens, never compiler internals"]
+    serialize --> artifacts["CSS artifacts<br/>palette · runtime · fonts"]
+    artifacts --> recipes["theme.css recipes<br/>map semantic tokens onto component states"]
+    recipes --> components["Trellis components and custom Tailwind UI"]
+```
+
+`ResolvedThemeConfig` separates authored intent from computed relationships. The DTCG document separates the
+proprietary compiler from portable output adapters. CSS serialization only consumes that document.
+
+The Theme Knob Catalog is a separate generated read model of the authored configuration boundary. It derives paths,
+constraints, concrete authored/compiler defaults, required parents, and repeated-path parameters from
+`ThemeConfigSchema`, then layers semantic search metadata from one definition file. Human and agent interfaces
+consume the same versioned JSON catalog and produce ordinary Theme Patch Commits; the catalog is never another
+configuration source.
+
+## What each stage owns
+
+### 1. Revision materialization
+
+`compileTheme` is the hardened public path from a base plus patch history to a materialized config and validated token
+document. It composes the stages below without exposing generated compiler internals to output adapters.
+
+`materializeTheme` starts from a base `ThemeConfig` and applies ordered commits. A commit is an atomic batch of the
+RFC 6902 `add`, `remove`, and `replace` operations. Theme patches may replace existing array members but cannot change
+array membership. The result is validated against `ThemeConfigSchema`; storage, branches, heads, and snapshots remain
+outside the compiler.
+
+### 2. Authored configuration
+
+`ThemeConfig` is the language-agnostic authoring boundary. Each axis selects a named, versioned strategy and may
+override the baseline without requiring component-specific tokens.
+
+`createThemeKnobCatalog` walks that boundary and exposes every non-constant leaf as a Theme Knob. Fixed tuples and
+dynamic records use parameterized JSON Pointer paths so the catalog remains searchable without hiding low-level
+control or duplicating every possible instance. Repeated schema branches retain their concrete defaults as values
+keyed by parameter bindings. Generated files live under `generated/knobs/v1/`, split into semantic groups organized
+under each axis. A small `manifest.json` exposes axes, groups, escalation tiers, impact scopes, and counts without
+embedding knob records. `index.json` supports deterministic search without loading full group documents.
+
+Discovery is progressive: call `listThemeKnobGroups`, then `searchThemeKnobs`, then `getThemeKnobs` only for selected
+paths. Search includes Primary and Tuning knobs by default. Expert and Escape Hatch knobs require an explicit tier
+filter; exact authored palette steps are Escape Hatches rather than ordinary color controls. Interfaces should prefer
+the minimum sufficient leaf mutations, compile the result, and escalate only when broader controls are insufficient.
+
+### 3. Resolution
+
+`resolveThemeConfig` validates the schema, fills omitted values from `defaults.ts`, parses colors, and validates all
+references. It also records whether every resolved value came from authored config or a default.
+
+### 4. Generation
+
+`generateTheme` completes color first, then gives the remaining axes their resolved configuration and combines the
+results. Cross-axis work stays in the orchestrator; for example, surface shadows consume generated color and resolved
+depth.
+
+### 5. Validation and token projection
+
+Generated values are validated before `generateDesignTokens` projects them into a DTCG 2025.10 Resolver Document.
+Invariant tokens form one set and light/dark appearances form an `appearance` modifier. Standard DTCG types represent
+colors, dimensions, numbers, durations, font families, weights, and shadows. Namespaced `dev.trellis` extensions retain
+fluid relationships, unsupported CSS units, font resources, and CSS adapter metadata without changing token values.
+
+### 6. Output serialization
+
+`serializeThemeArtifacts` and `serializeThemeCss` consume only the DTCG document. They produce named resources,
+palette, and runtime artifacts with Tailwind registrations and deterministic fingerprints. Future adapters should
+consume the same token boundary rather than `GeneratedTheme`.
+
+### 7. Component consumption
+
+`packages/client/src/styles/theme.css` imports the generated artifacts and defines shared recipes such as actions,
+fields, options, and selections. Component code chooses semantic roles; it does not reproduce theme math.
+
+## Inside the color branch
+
+Each appearance and family follows the same ordered pipeline. Later steps are allowed to constrain earlier requests,
+but every adjustment is retained in diagnostics rather than silently hidden.
+
+```mermaid
+flowchart TD
+    source["Family source<br/>seed + anchor, or 12 authored steps"] --> ramp["Functional curve<br/>build the 12-step candidate ramp"]
+    canvas["Appearance canvas<br/>light or dark"] --> lighting["Canvas-relative lighting<br/>adapt quiet steps to their substrate"]
+    ramp --> lighting
+    lighting --> normalize["Constraint-priority normalization<br/>balance order, contrast, seed fidelity, and smoothness"]
+    normalize --> fit["Solid-ink fitting<br/>make solid backgrounds pairable"]
+    fit --> canonical["Canonical color<br/>retain one OKLCH value"]
+    canonical --> proof["sRGB proof<br/>delegate CSS gamut mapping to Color.js"]
+    proof --> ink["Accessible ink pairing<br/>attach regular, subtle, and muted inks"]
+    proof --> alpha["Substrate alpha fitting<br/>derive translucent steps across known substrates"]
+    ink --> family["Generated family<br/>opaque color + inks + alpha for every step"]
+    alpha --> family
+
+    family --> surfaces["Surface ladder<br/>canvas + neutral/accent influence + depth layers"]
+    canvas --> surfaces
+    surfaces --> semantics["Semantic graph<br/>structure, intents, interactions, selection, disabled, scrim"]
+    family --> semantics
+```
+
+The 12-step families are primitives, not component colors. Semantic roles select from those families, and surface
+levels provide the actual substrates against which alpha colors, inks, and shadows are evaluated.
+
+Solid semantic roles also calibrate `separation.hover.{light,dark}` and `separation.pressed.{light,dark}` as minimum
+perceptual distances from rest. The generator follows the authored state direction when contrast permits, then favors
+the contrast-safe direction.
+
+## Generated relationship tree
+
+| Branch | Generates | Downstream consumers |
+| --- | --- | --- |
+| Color families | Canonical OKLCH steps, alpha steps, accessible inks, sRGB proofs | Surfaces and semantic roles |
+| Surfaces + depth | Levels `0–8`, paired surface inks, calibrated local edges, elevation shadows | Panels, overlays, cards, app regions |
+| Semantic roles | Text, soft, solid, edge, focus, interaction, selection, disabled attenuation, scrim | Shared component recipes |
+| Edge | Width scale and perimeter/control/separator/divider aliases | Rings, dividers, shadow spreads |
+| Radius | Six-step curve and control/surface/overlay aliases | Component shape choices |
+| Spacing | Half-step `0–12` scale and anatomy dependencies | Gaps and padding |
+| Typography | Font resources, 13 type steps, weights, anatomy dependencies | Text and control typography |
+| Sizing | Bounded lengths for controls, icons, component anatomy, and measures | Component geometry |
+| Composition | Breakpoints, responsive column maps, shell breakpoint | Page and layout recipes |
+| Motion | Semantic durations, bounce strengths, and displacement scale | Component transitions and gestures |
+
+## Shipped default at a glance
+
+| Axis | Default relationship |
+| --- | --- |
+| Canvas | `#fafafa` light and `#171717` dark |
+| Core families | Neutral `#737373`; accent and information `#0090ff` |
+| Status families | Success `#30a46c`, warning `#ffc53d`, danger `#e5484d` |
+| Color output | Canonical OKLCH values with an sRGB proof for accessibility and compositing |
+| Surfaces | Nine levels from canvas through progressively stronger neutral depth, with very restrained accent influence |
+| Semantics | Crisp `1px` focus; quiet neutral selection and action layers; disabled controls preserve their treatment at `50%` opacity |
+| Edges | `0 / 1 / 2 / 4px`; every default anatomy role uses the `1px` step, while edge color is calibrated against the active substrate and surface |
+| Radius | `1 / 2.5 / 4 / 6 / 8 / 10.5px`; control `4px`, surface `6px`, overlay `8px` |
+| Spacing | `4px` foundation; compact through step `4`, then gently fluid from `320–1440px` |
+| Controls | Fixed `20 / 24 / 28 / 32 / 36px` heights from `xs` through `xlg` |
+| Typography | Inter for UI, Fira Code for code; body/control defaults are mostly `14px`, with a 13-step display scale |
+| Composition | `640 / 768 / 1024 / 1280 / 1536px` breakpoints; sidebars enter at `lg` |
+
+The default is deliberately neutral, compact, and low-chroma at rest. Blue carries selection and primary emphasis,
+while surface elevation and interaction layers do most of the structural work.
+
+## Principles
+
+- Patch history, authored config, resolved config, generated relationships, design tokens, output artifacts, and
+  component recipes are separate layers.
+- Axes such as color, surface, depth, edge, radius, spacing, typography, sizing, and composition remain independently
+  tunable. Presets may coordinate them.
+- Output adapters consume DTCG tokens; components consume serialized tokens and anatomy relationships. Neither reads
+  config nor repeats generation math.
+- Generated tokens extend familiar Tailwind syntax. Do not replace foundations such as the base `--spacing` value.
+- Shared bounded-fluid math may support several axes, but it does not create one universal public length scale.
+- The same resolved config must produce the same light/dark output, diagnostics, provenance, fingerprint, and CSS.
+
+Avoid personality or use-case god knobs, component-named tokens, downstream theme literals, silent coercion, and
+per-breakpoint configuration matrices. Fix systemic visual defects upstream so every composition benefits.
+
+## Where to look
+
+| Need | Location |
+| --- | --- |
+| Public compiler API | `src/compile-theme.ts`, `src/index.ts` |
+| Patch commits and materialization | `src/materialize-theme.ts` |
+| Authored schema | `src/schema/theme-config.ts` |
+| Packaged Theme Config schema | `generated/schemas/theme-config-v1.json` |
+| Packaged Theme Workspace schema | `generated/schemas/theme-manifest-v1.json` |
+| Theme knob factory and metadata | `src/knobs/` |
+| Generated knob JSON | `generated/knobs/v1/` |
+| Agent theme-authoring skill | `skills/create-trellis-theme/SKILL.md` |
+| Defaults and shipped preset | `src/defaults.ts`, `src/presets/trellis-default.ts` |
+| Resolution, validation, provenance | `src/resolve-theme-config.ts`, `src/validate-*.ts` |
+| Complete orchestration | `src/orchestrator.ts` |
+| Axis math | `src/color/`, `src/edge/`, `src/radius/`, `src/spacing/`, `src/typography/`, `src/sizing/`, `src/composition/`, `src/motion/` |
+| Shared fluid primitive | `src/fluid/bounded.ts` |
+| DTCG token projection | `src/design-tokens/` |
+| CSS and Tailwind output | `src/serialize/` |
+| Default CSS build | `scripts/generate-default-css.mjs` |
+| Boundary tests | `../../tests/client/theme-engine/` |
+
+When changing an axis, move its schema, defaults, resolution, focused generator, generated types, serialization, and
+boundary tests together. Add cross-axis coordination only in orchestration. Never hand-edit `dist/` or
+`packages/client/src/styles/generated/`.

package/packages/theme-engine/THEME_AUTHORING.md

@@ -0,0 +1,44 @@
+# Theme authoring
+
+A Theme Workspace is one source-controlled theme. Pass its `theme.json` explicitly; separate workspaces never share
+implicit state. Keep `base.json` complete and append one coherent `ThemePatchCommit` per line to `commits.jsonl`.
+
+Resource paths in this guide are relative to the authoring resource root: the directory containing this file and
+`generated/`. In the Trellis repository, that directory is `packages/theme-engine/`.
+
+The versioned Theme Config JSON Schema is at `generated/schemas/theme-config-v1.json` with the stable `$id`
+`https://trellis.build/schemas/theme-config-v1.json`. A config may use any string in its own `$schema` property as
+optional editor metadata. The compiler neither requires nor inserts that property, and it does not affect resolved
+theme semantics or fingerprints.
+
+For agent-assisted changes, inspect `generated/knobs/v1/manifest.json` or `index.json` before opening a semantic group.
+Search Primary and Tuning knobs first. Use Expert or Escape Hatch knobs only when broader controls cannot express the
+request, and prefer the smallest sufficient set of leaf operations. The catalog is a read model, not theme state.
+
+Write exactly one commit object to a normal JSON file, then run:
+
+```console
+npm exec --no -- trellis theme apply path/to/theme.json path/to/commit.json
+```
+
+This consumer command requires the packaged CLI to be installed locally. In the Trellis repository, use
+`pnpm trellis theme apply path/to/theme.json path/to/commit.json` instead.
+
+Inspect the generated artifact and Git diff. Use `theme build` to regenerate selected outputs and `theme check` for a
+read-only byte comparison. Git owns attribution, branches, merges, rollback, and review; Trellis does not maintain a
+second revision graph.
+
+## Enable the authoring skill
+
+The authoring resources include `skills/create-trellis-theme/SKILL.md`. Register that folder with your agent's skill
+discovery mechanism, or copy the `create-trellis-theme` folder into its configured skill directory. Installing the npm
+package alone does not enable the skill. Keep the Trellis package installed in the project: the skill reads its
+authoring guide, schemas, and knob catalog. A copied skill should be refreshed when upgrading Trellis.
+
+Invoke `create-trellis-theme` with the intended workspace and design direction, for example: “Use
+create-trellis-theme to make the application theme denser with a muted green accent.”
+
+Theme Patch Commits should not add or remove `$schema` merely to express a design change.
+
+If `apply` reports that the Theme Commit Log changed concurrently, reload the workspace source and retry the intended
+commit. Trellis preserves the external change rather than guessing an ordering or merging commits automatically.