ID:SPEC-094Status:accepted
Theme system foundations for multi-theme development
Name:v0.23.0Status:planning
v0.23.0 — Surface axes & the skeleton/skin extraction
The second slice of the SPEC-094 theme-platform epic. Where v0.22.0 tokenized type and built the gallery safety net, v0.23.0 attacks the differentiation surface: it extracts skeleton from skin and replaces the last cross-rune rune-name lists with engine-emitted, theme-overridable config.
Its centerpiece is SPEC-107 — the surface-axis decomposition. It amends SPEC-094 §8: the single surface enum (card/banner/inline/inset) splits into three orthogonal, theme-defaulted axes — an ordered elevation depth ladder (sunken/flush/flat/raised/floating, folding in today's shadow-only elevation), width carrying the bleed, and a page-section-family prominence scale (quiet/normal/prominent/display). The motivating outcome: the same recipe reads as a bordered card in prose and a full-bleed, large-title hero at the top of a page.
Not enough history yet — burndown needs at least one completed day of activity.
Progress 8/10 work items
Relationships
Related 13
ID:SPEC-107Status:accepted
Elevation, prominence & the surface-axis decomposition
ID:WORK-423Status:done
elevation depth-ladder axis
Priority:highComplexity:complexMilestone:v0.23.0
ID:WORK-424Status:done
prominence axis (page-section family)
Priority:highComplexity:moderateMilestone:v0.23.0
ID:WORK-425Status:done
Lumina: map the axes + retire the static surface groups
Priority:highComplexity:complexMilestone:v0.23.0
ID:WORK-426Status:done
Migration + docs for the surface axes
Priority:mediumComplexity:moderateMilestone:v0.23.0
ID:WORK-427Status:done
Demonstrate the axes: full-bleed hero recipe / playlist
Priority:mediumComplexity:simpleMilestone:v0.23.0
ID:WORK-410Status:done
Skeleton/skin split — spike
Priority:highComplexity:moderateMilestone:v0.22.0
ID:WORK-435Status:done
Spacing token contract + Lumina refactor
Priority:highComplexity:complexMilestone:v0.23.0
ID:WORK-436Status:done
@refrakt-md/skeleton package + @layer infrastructure
Priority:highComplexity:moderateMilestone:v0.23.0
ID:WORK-437Status:done
Icon-from-config: lift embedded data-URI glyphs out of CSS
Priority:mediumComplexity:simpleMilestone:v0.23.0
ID:WORK-438Status:pending
Skeleton/skin re-bucketing of the Lumina CSS
Priority:highComplexity:complexMilestone:v0.23.0
ID:WORK-440Status:pending
Proof skin — validate the skeleton is theme-agnostic
Priority:highComplexity:moderateMilestone:v0.23.0
Work Items
Draft 2
WORK-438 changeset-release/main
Skeleton/skin re-bucketing of the Lumina CSS The wholesale pass the WORK-410 spike sized: re-bucket Lumina's CSS into the two @layers per the spike's cut-line rule, so structure ships in @refrakt-md/skeleton and aesthetics stay in Lumina's skin. Mechanical and low-risk per declaration, but large (~114 files / ~6,058 declarations; the spike estimates ≈40% skeleton / 55% skin / 5% content).
0/3 criteria
WORK-440 changeset-release/main
Proof skin — validate the skeleton is theme-agnostic The milestone's exit gate. The skeleton/skin extraction's goal is "theme #2 is a token file + layout + skin, not a fork" — but theme #2 is deferred (SPEC-094), so the extraction would otherwise ship with no consumer to prove it worked. The harness inert-proof only shows Lumina didn't regress; it does not show the skeleton is actually skin-agnostic. A thin proof skin closes that gap.
0/3 criteria
Done 8
WORK-423 changeset-release/main
elevation depth-ladder axis Turn elevation into the universal chrome/depth axis from SPEC-107: an ordered semantic ladder emitted as data-elevation, superseding both §8's surface enum and today's shadow-only none/sm/md/lg scale. The foundation the rest of the milestone builds on.
5/5 criteria
WORK-424 changeset-release/main
prominence axis (page-section family) Add the header-emphasis axis from SPEC-107: prominence scales a rune's page-section header (eyebrow / title / blurb / rhythm), selecting its typographic register. Unlike elevation it is not universal — it is available only to runes that carry the page-section header model.
3/3 criteria
WORK-425 changeset-release/main
Lumina: map the axes + retire the static surface groups Paint the SPEC-107 axes in Lumina and retire the rune-name lists in surfaces.css — the last cross-rune file that enumerates runes (SPEC-094 §8).
3/3 criteria
WORK-426 changeset-release/main
Migration + docs for the surface axes Land the breaking elevation rename safely and bring the site + docs onto the new vocabulary (SPEC-107 §5).
3/3 criteria
WORK-427 changeset-release/main
Demonstrate the axes: full-bleed hero recipe / playlist Close the loop on the use case that motivated SPEC-107: the same content rune reading as a contained card and as a full-width hero, by composing the axes — no rune fork.
2/2 criteria
WORK-435 changeset-release/main
Spacing token contract + Lumina refactor The prerequisite the WORK-410 spike surfaced: a clean skeleton/skin split needs spacing to be tokenized, exactly as the type split needed WORK-404/WORK-405. Skeleton references spacing tokens by name; skin owns their values — but today Lumina hardcodes magnitudes (0.5rem, 0.375rem, 0.8125em, …), so the skin layer can't retune them without restating structure. The gate for the re-bucketing.
3/3 criteria
WORK-436 main
@refrakt-md/skeleton package + @layer infrastructure Stand up the packaging + cascade-layer infrastructure the WORK-410 spike settled, so skeleton and skin can ship and version separately. The structural home the re-bucketing fills.
3/3 criteria
WORK-437 main
Icon-from-config: lift embedded data-URI glyphs out of CSS The "content, not CSS" finding from the WORK-410 spike (SPEC-094 §8's icon-from-config): rune CSS embeds glyph shapes as data:image/svg+xml mask-images. Move them to the theme icon registry so a theme swaps glyph sets without touching CSS.
2/2 criteria