[adm 13] Rebuild full Theme administration with global tokens and component/pattern recipes

[artiphishle]

Roadmap: #115

Respect the roadmap first and the AGENTS.md file of every repository touched.

Previous roadmap step

[adm 12] (#127) establishes one canonical active light/dark mode across the app and /ankh/*. Combined with [adm 2] (#117), this issue can build full Theme administration on canonical authoring-authority and theme-recipe metadata.

Repository impact

Likely:

• ankhorage/studio
• ankhorage/zora
• ankhorage/surface
• ankhorage/contracts where canonical serializable theme configuration must evolve
• module repositories such as Google Fonts only where typography/font selection is module-owned

Pause at package release boundaries per roadmap rule #6.

Goal

Build production-quality Theme administration with a scalable hierarchy for global design tokens and component/pattern recipes, with immediate live updates to the actual app and no per-instance style explosion.

Target information architecture

Conceptually:

/ankh/theme
/ankh/theme/colors
/ankh/theme/typography
/ankh/theme/typography/fonts
/ankh/theme/spacing
/ankh/theme/radii
/ankh/theme/components/{component}
/ankh/theme/patterns/{pattern}

Exact route set should be derived from the final canonical token/recipe model. Do not place every component directly under /ankh/theme/{component}.

Core ownership model

Global theme tokens
  -> colors
  -> typography
  -> spacing
  -> radii
  -> other shared design foundations

Component/pattern recipes
  -> map global tokens into component-specific design behavior

Instance Properties
  -> only minimal node-specific content/behavior

Use the ZORA theme-recipe metadata registry from [adm 2] to generate/drive component/pattern Theme administration. Do not hardcode a second recipe schema in Studio.

Requirements

Canonical persisted theme

Theme changes must update the canonical project/theme configuration and immediately propagate through the real ZORA/Surface theme provider used by the app.

Do not create:

• a separate Studio theme;
• an unsaved preview theme model;
• an admin-only theme mode;
• duplicated light/dark theme state.

Active mode editing

Use [adm 12]'s canonical active light/dark mode. Theme administration edits/previews the active mode while preserving the canonical paired light/dark theme configuration.

Global tokens

Provide intuitive authoring for supported global foundations such as:

• color/harmony/semantic color configuration;
• typography foundations;
• font selection/weights where canonical ownership supports it;
• spacing scale/tokens;
• radii and other canonical token families.

Do not implement the planned future linear/modular/Fibonacci/golden scale-algorithm feature here. This roadmap should establish clean token inputs/contracts that the after-roadmap issue can later generate.

Component/pattern recipes

Render configuration from canonical ZORA recipe metadata.

Examples may include Card padding/content gap/radius or Button control recipes, but only fields explicitly exposed by the owning recipe metadata.

Global semantic tokens must feed component-specific recipes rather than treating a semantic size as one universal pixel value for every component.

Typography/fonts and modules

If Google Fonts remains module-owned, integrate through the [adm 10] module strategy rather than putting special-case Google Fonts lifecycle/config code into Studio Theme pages.

Theme may consume the active font result/config through canonical contracts, while the module remains responsible for installation/configuration behavior.

Likely files

Studio, non-exhaustive:

src/ui/admin/pages/ThemeAdminPage.tsx
src/ui/admin/pages/adminThemeModel.ts
src/studioAdminRouteModel.ts
src/core/StudioProvider.ts
src/manifestState.ts

ZORA/Surface/contracts files must be determined from current theme/token/recipe ownership.

Historical reference: old Theme admin/ThemeComposer behavior and PR #349 mode scoping in ankhorage4; preserve useful capability but implement the new hierarchy and canonical live propagation.

Phases

Phase 1 — canonical theme contract/runtime propagation

Audit and evolve serializable ThemeConfig/token/recipe overrides and ensure one live provider consumes canonical state.

Phase 2 — global Theme administration

Build /ankh/theme hierarchy for colors, typography, fonts, spacing, radii and other approved global token families.

Phase 3 — component/pattern recipe administration

Generate/drive recipe pages from ZORA recipe metadata registry and persist canonical recipe overrides.

Phase 4 — hardening

Validate light/dark behavior, module-owned font integration, docs and migration/cleanup of obsolete theme paths.

Tests

Cover at minimum:

• canonical theme mutation/persistence round-trip;
• immediate live app propagation;
• active light/dark mode editing without duplicate state;
• global token updates;
• recipe registry -> admin field resolution;
• component/pattern recipe override persistence and runtime resolution;
• instance Properties remain unaffected by theme-only fields;
• Google Fonts/module boundary where relevant;
• unknown/unsupported recipe metadata behavior.

Acceptance criteria

1. Theme administration has a scalable nested route hierarchy.
2. Global tokens and component/pattern recipes are clearly separated.
3. ZORA recipe metadata is the canonical recipe-authoring schema.
4. Changes persist through canonical project/theme configuration.
5. The actual app updates immediately through the real theme provider.
6. App and /ankh/* share [adm 12]'s active mode.
7. No arbitrary theme-owned controls leak into instance Properties.
8. Semantic tokens feed component-specific recipes rather than universal geometry assumptions.
9. Google Fonts or other module-owned behavior is not hardcoded into Studio.
10. Future scale algorithms remain out of scope but can plug into the token foundation without redesign.
11. Behavior-focused tests and full validation pass.
12. No legacy/compatibility/ankhorage4 dependency is introduced.