T-0OG3-design-language-theme-authoring-guide

Status: open/ready · Impact: medium · Complexity: small

Goal

registerTheme() is the public seam for a solution to ship its own theme, proven by sdf — but the recipe exists only as code. Write the guide so the next theme doesn’t require reading tokens.css end to end.

Today

Location	Role today
packages/ts/ui/app/composables/useAppearance.ts	registerTheme() seam; built-in theme list.
solutions/ontological/desktop/src-nuxt/app/plugins/appearance.client.ts	sdf’s registration — the only worked example.
packages/ts/ui/docs/design-system.md	§10 lists built-in presets; no authoring path.

Proposed

packages/ts/ui/docs/theme-authoring.md: the seed contract (every Tier-1 token a theme must provide per mode, what Tier 2 derives, the AA-contrast pairs, rail treatments), a registration walkthrough built on the sdf example, and the verification recipe (lab page, light+dark screenshot pairs). design-system.md §10 links to it.

Approach

1. Extract the seed contract from the tokens.css structure (Tier-1 seed list per mode, derivation expectations).
2. Write the guide with the sdf plugin as the worked example.
3. Cross-link from design-system.md §10.

Files to touch

Location	Kind	Change
packages/ts/ui/docs/theme-authoring.md	new	the guide
packages/ts/ui/docs/design-system.md	modify	§10 link

Acceptance criteria

• AC-1: The guide names every required seed token; a theme can be registered without reading tokens.css.
• AC-2: The sdf registration is the worked example, verified against the live plugin.
• AC-3: design-system.md §10 links the guide.

Out of scope

• Changing the registerTheme API.

Dependencies

• Write after the built-in theme-set PR merges so the guide reflects the final registration surface.

Discovery context

• docs/planning/design-language/PLAN.md Phase 2; D-DLNG-design-language.

---

← Back to Tasks