T-DUEF-design-language-starlight-skin
State: closed/done · Impact: medium · Complexity: medium
The doc sites should wear the family face. Express the DEFAULT seed tokens
(light + dark) as a Starlight customCss file, shipped through the
deterministic site-assembly seam so sites/df-docs and the library doc
sites all pick it up. Phase 4 of D-DLNG-design-language.
The projection reads the un-attributed :root / .dark blocks — whichever
theme currently holds the default — not a named [data-theme='…'] block. It
follows the default rather than pinning a theme.
| Location | Role today |
|---|---|
sites/df-docs/ | Starlight site on the stock theme. |
solutions/ontological/site-template/ | The D-0010 site-assembly seam; every doc site materializes from it. |
packages/ts/ui/app/assets/css/tokens.css | The seed values to project (the default theme’s light/dark Tier-1 seeds). |
Proposed
Section titled “Proposed”A customCss file in the site template mapping the default seeds onto
Starlight’s CSS custom properties (both modes), so a regenerated site
carries the skin with no per-site work.
Approach
Section titled “Approach”- Build the reusable projection machinery — a reader for a CSS file’s default seed blocks, and a projector onto a target vocabulary.
- Map Starlight’s theming properties to the closest
--d-*seeds (static values — doc sites don’t load the layer). - Add the generated file + wiring to
solutions/ontological/site-template/, with a repo-level script that regenerates it and drift-checks it in CI. - Regenerate
sites/df-docs; before/after light+dark screenshots. - Note the projection (and its static nature) in
design-system.md.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
solutions/ontological/lib/services/design-tokens/ | add | the reusable seed reader + projector |
scripts/seed-projection.ts | add | this repo’s paths + the --check guard |
solutions/ontological/site-template/ | modify | the generated skin + customCss wiring |
justfile | modify | the drift check joins ci-guards |
packages/ts/ui/docs/design-system.md | modify | projection note |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: df-docs renders the default seed palette in light and dark.
- AC-2: The skin arrives via site-template (a fresh materialization carries it), not hand-edits to one site.
- AC-3: Before/after screenshot pairs in the PR.
Out of scope
Section titled “Out of scope”- Non-Starlight static surfaces (
augmented_dot_com), report templates (T-J8MT-design-language-report-palette).
Dependencies
Section titled “Dependencies”- none
Discovery context
Section titled “Discovery context”docs/planning/notes/N-R926-design-language-plan.mdPhase 4; D-0010 site assembly.