Token-driven UI — skins as data

Platform-UI CSS reads every visual decision — colour, radius, spacing, motion — from CSS custom properties prefixed --ui-*. A primitive never hard-codes a colour or a border-radius; it references a token. Those tokens are defined by the active skin at runtime (/assets/skins/<slug>/tokens.css), chosen by semitexa/theme from the (tenant, domain, locale) tuple and loaded last so it wins the cascade.

The consequence is the whole point of this pillar: visual identity is a data concern, not a code concern. Components stay portable; the palette is guaranteed consistent across light and dark mode because both modes are emitted by the same token contract.

This showcase is the living proof

The page you are reading is rendered by the moss skin. The very same templates, the same primitives, and the same components also serve framework.semitexa.test, where they render in terracotta. Nothing in the markup changes between the two — there is no per-site override, no theme prop threaded through components, no conditional CSS. One site swaps a tokens.css file for another and the entire surface re-skins itself.

That is what "skins as data" means concretely: the difference between this site and the framework site is a 41-token JSON manifest, not a fork of the components.

The token contract

Every skin emits the same 41 design tokens, in both light and dark modes. Missing a token would break any primitive that resolves var(--ui-X), so the contract is total: an algorithm that cannot emit all 41 tokens in both modes is not a valid algorithm. A skin.json manifest looks, in excerpt, like this:

1{2  "slug": "moss",3  "algorithm": "balanced",4  "seed": "#4f6b3a",5  "knobs": { "radius_scale": "default", "shadow_intensity": "default", "motion_speed": "default" },6  "modes": {7    "light": {8      "ui-surface-page":   "oklch(98% 0.01 130)",9      "ui-surface-panel":  "oklch(96% 0.02 130)",10      "ui-accent-brand":   "oklch(52% 0.10 135)",11      "ui-text-body":      "oklch(28% 0.02 130)",12      "ui-border-subtle":  "oklch(88% 0.02 130)"13    },14    "dark": { "…": "… same 41 keys, dark values …" }15  }16}

Because the contract is fixed, the same sx-surface="panel" resolves to the right background and border in any skin and either mode — the primitive references --ui-surface-panel and --ui-border-subtle, and the active tokens.css decides what those mean today.

Three algorithms

A skin is generated by one of three shipped algorithms (each a SkinAlgorithm implementation registered in SkinAlgorithmRegistry). They differ in character, not in the token contract they must satisfy:

• balanced — corporate-readable. Soft drop shadows, conservative radii, smooth transitions, WCAG-AA contrast on brand. The default when prose is ambiguous. (This site's moss skin is balanced.) Knobs: radius_scale, shadow_intensity, motion_speed.
• glass — translucent frosted panels, larger radii, diffuse shadows, emphasised motion. Modern SaaS / mac-style. Knobs: blur_amount, surface_transparency, shadow_softness.
• brutalist — bold and structural. Zero radius (except pill), hard offset shadows, instant motion, saturated accents. Neo-brutalist / zine. Knobs: shadow_offset, contrast_boost, shadow_color_mode.

Each algorithm is deterministic: given the same SkinParams it always returns the same SkinPalette — no clocks, no randomness, no environment. That determinism is what lets a skin be checked into a project and reproduced byte-for-byte.

Generating and refining skins from the CLI

The generation tooling ships in the sibling semitexa/skins-base package; platform-ui owns the algorithms, the token contract, and the LLM library. Skins are generated into a project's own src/skins/ directory and served via SkinDiscovery in semitexa/theme.

Deterministic generation from a seed colour:

1# moss-style: balanced algorithm, mossy green seed, default knobs2bin/semitexa skins:generate balanced "#4f6b3a" --name=moss --mode=light --write34# tune the character with repeatable --knob flags5bin/semitexa skins:generate balanced "#2f6fed" \6  --knob=radius_scale:rounded --knob=shadow_intensity:pronounced --write

Refining an existing skin — structured edits via --set, or fork it under a new slug:

1bin/semitexa skins:refine moss --set=shadow_intensity:pronounced --as=moss-deep --write

Introspection costs nothing and emits no CSS:

1bin/semitexa skins:generate --describe   # all algorithms + their knob schemas

LLM-assisted generation (optional)

Both skins:generate --prompt="…" and skins:refine <slug> --prompt="…" accept natural-language descriptions and let a model pick an algorithm, seed, and knobs for you. This path is optional — it requires an external LLM key. The deterministic seed-mode path above needs no model at all and is the reliable default; the LLM is a convenience for translating prose like "a calm forest theme with soft corners" into a starting point you then refine. You can preview the model's resolution without emitting any CSS via skins:explain-prompt "<text>".

Why it matters

When the palette lives in code, re-skinning means a refactor and visual identity becomes a permanent maintenance tax. When the palette lives in 41 tokens, re-skinning is swapping a file, light/dark is two value sets of the same contract, and multi-tenant theming is a (tenant, domain, locale) lookup. The components never learn about the brand — they only ever speak --ui-*.