@vireo-ai/trellis-ui 0.1.61 → 0.1.63

package/packages/theme-engine/README.md

@@ -1,9 +1,8 @@
 # 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.
+The theme engine is a deterministic compiler from a materialized JSON `ThemeConfig` to Tailwind CSS. It encodes
+brand relationships once so components and custom Tailwind compositions stay in sync. A validated
+[DTCG 2025.10](https://www.designtokens.org/TR/2025.10/) document carries tokens between generation and serialization.
 
 ## Top-down model
 
@@ -26,7 +25,6 @@ flowchart TD
     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
@@ -35,18 +33,17 @@ flowchart TD
     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"]
+    tokens --> serialize["Tailwind serialization<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.
+`ResolvedThemeConfig` separates authored intent from computed relationships. The internal token document separates
+theme generation from Tailwind serialization. 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
@@ -59,7 +56,7 @@ configuration source.
 ### 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.
+document. It composes the stages below without exposing generated compiler internals to Tailwind serialization.
 
 `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
@@ -98,14 +95,14 @@ depth.
 
 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.
+colors, dimensions, numbers, font families, weights, and shadows. Namespaced `dev.trellis` extensions retain
+fluid relationships, unsupported CSS units, font resources, and Tailwind registration metadata without changing token values.
 
-### 6. Output serialization
+### 6. Tailwind 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`.
+palette, and runtime artifacts with Tailwind registrations and deterministic fingerprints. Theme Workspaces emit
+Tailwind CSS directly; each entry in `outputs` supplies only a `path`, with no output format selection.
 
 ### 7. Component consumption
 
@@ -144,6 +141,16 @@ Solid semantic roles also calibrate `separation.hover.{light,dark}` and `separat
 perceptual distances from rest. The generator follows the authored state direction when contrast permits, then favors
 the contrast-safe direction.
 
+Selection foregrounds use the family's existing ink contrast policy against both selected and selected-hover fills
+over every workspace and chrome level. Readable authored ink is preserved; otherwise the shared ink solver fits it.
+This proof uses browser sRGB alpha compositing, while perceptual overlay calibration retains its linear-light math.
+The compiler reports adjustments and rejects treatments that cannot meet the minimum under the pairing policy.
+
+Colored soft treatments share their family's step 9 at 10%, 15%, and 20% opacity for rest, hover, and pressed.
+Neutral soft treatments retain quiet alpha steps. `semantic.roles.intents.<intent>.soft.strength` can override each
+state with an opacity or the existing `minimum-delta-e` calibration; the same contrast proof fits readable soft inks
+across every generated surface. Components consume these shared treatments rather than mixing their own tints.
+
 ## Generated relationship tree
 
 | Branch | Generates | Downstream consumers |
@@ -157,7 +164,6 @@ the contrast-safe direction.
 | 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
 
@@ -185,7 +191,7 @@ while surface elevation and interaction layers do most of the structural work.
   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
+- Tailwind serialization consumes validated 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.
@@ -209,7 +215,7 @@ per-breakpoint configuration matrices. Fix systemic visual defects upstream so e
 | 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/` |
+| Axis math | `src/color/`, `src/edge/`, `src/radius/`, `src/spacing/`, `src/typography/`, `src/sizing/`, `src/composition/` |
 | Shared fluid primitive | `src/fluid/bounded.ts` |
 | DTCG token projection | `src/design-tokens/` |
 | CSS and Tailwind output | `src/serialize/` |
@@ -219,3 +225,77 @@ per-breakpoint configuration matrices. Fix systemic visual defects upstream so e
 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/`.
+
+## Text selection
+
+`semantic.roles.textSelection` controls the browser's `::selection` highlight independently of selected component
+states. The default uses accent step 9 at 25% opacity and uses the browser's `currentColor` text ink. Background and
+foreground references resolve through the active appearance's palette; opacity ranges from `0` to `1`.
+
+```json
+{
+  "semantic": {
+    "roles": {
+      "strategy": "functional-role-graph",
+      "version": 1,
+      "textSelection": {
+        "background": {"family": "neutral", "color": {"kind": "step", "step": 12}},
+        "opacity": 1,
+        "foreground": {"family": "neutral", "color": {"kind": "step", "step": 1}}
+      }
+    }
+  }
+}
+```
+
+This example uses opposing ends of the neutral palette for an opaque highlight. Set `foreground` to `"inherit"`
+to restore the surrounding text color. Explicit foregrounds are preserved as authored; choose a readable pair.
+The compiler emits `--background-text-selection` and, for an explicit foreground, `--color-text-selection-ink`.
+The single global rule in `theme-support.css` consumes these tokens, falling back to `currentColor` for inherited ink.
+The knob catalog exposes these controls in the Text selection group, including Text selection intensity for opacity.
+
+## Dismiss control radius
+
+`radius.dismiss` selects the shared shape of standalone Card, Modal, and Toast dismiss controls. It defaults to
+`"full"`; use `"none"` for square corners or a radius-scale step (`1`–`6`) to follow the generated curve. Badge removal
+retains its compact badge anatomy. The token `radius.role.dismiss` aliases the chosen primitive and emits
+`--radius-dismiss` (`rounded-dismiss` in Tailwind); ordinary control, surface, and overlay radius roles stay independent.
+
+```json
+{
+  "message": "Use the second radius step for dismiss controls",
+  "operations": [{"op": "add", "path": "/radius/dismiss", "value": 2}]
+}
+```
+
+## Fonts through theme commits
+
+Font selection is part of the Theme Config and JSONL commit history. The shipped default uses pinned Fontsource
+resources for Inter (weight and optical size) and Fira Code. No separate font command or manual face copying is needed.
+
+```json
+{
+  "message": "Use Inter locally",
+  "operations": [{
+    "op": "replace",
+    "path": "/typography/resources/brand",
+    "value": {"type": "fontsource", "id": "inter", "version": "5.3.0"}
+  }]
+}
+```
+
+Use `trellis theme apply <manifest> <commit>` as usual. Apply and build prepare missing font dependencies, preserve
+licenses and source hashes, validate available families and weights, and publish local stylesheets and font files
+under the workspace's `fonts/<id>/<version>/` directory. The compiler performs no network or file IO; its generated
+font references follow the same declarative resource identity. Font resource knobs are Primary authoring controls.
+
+Fontsource selection prefers variable fonts with all available axes and includes supported styles and language
+subsets. Static-only families use all catalog weights. An exact package version is required. When changing fonts,
+update the corresponding `typography.families` binding in the same commit. Custom application-owned fonts use `local`
+resources; `bunny` resources explicitly opt into CDN loading through the same theme workflow.
+
+The bundled defaults require no network. Other fonts download on first apply/build and are reused locally thereafter.
+Build planning and `theme check` never download or write; they report missing or stale assets. A failed acquisition
+leaves the commit log and generated outputs unchanged. Deploy the generated CSS and workspace fonts together; paths
+are calculated relative to each output, including nested output directories. Keep acquired assets under source control
+for offline builds. Older versions may remain for rollback; active references come only from the materialized theme.

package/packages/theme-engine/THEME_AUTHORING.md

@@ -3,6 +3,14 @@
 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`.
 
+Theme Workspaces produce Tailwind CSS. The manifest's `outputs` entries specify CSS paths directly:
+
+```json
+{"outputs": [{"path": "./generated/theme.css"}]}
+```
+
+Import the generated CSS into the application's Tailwind 4 stylesheet. There is no output format selection.
+
 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/`.
 
@@ -42,3 +50,29 @@ Theme Patch Commits should not add or remove `$schema` merely to express a desig
 
 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.
+
+## Font selection
+
+Discover `/typography/resources/**` in the font knob catalog and select fonts through an ordinary theme commit:
+
+```json
+{
+  "message": "Use Inter locally",
+  "operations": [{
+    "op": "replace",
+    "path": "/typography/resources/brand",
+    "value": {"type": "fontsource", "id": "inter", "version": "5.3.0"}
+  }]
+}
+```
+
+Apply it with `trellis theme apply <manifest> <commit>`. Fontsource resources use a catalog ID and exact package
+version, prefer variable fonts with their available axes, and are served locally. Update the matching
+`typography.families` binding in the same commit when selecting another family. Faces, filenames, licenses, hashes,
+and local stylesheets are prepared by apply/build; they are not authored into the JSONL history.
+
+The bundled Inter and Fira Code defaults work offline. Apply/build acquire missing fonts once and reuse cached assets;
+`theme check` and build planning never download or modify files. Download failures preserve the history and outputs.
+Commit acquired `fonts/` assets for reproducible offline builds and deploy them with the generated CSS. A `bunny`
+resource explicitly selects CDN loading; application-owned font files use a `local` resource. All selections follow
+the same theme commit workflow.