Introduce a structured theming system in which each site defines a theme object composed of customizable design tokens, paired with a visual UI editor.
Themes operate at two levels:
Global (site-wide theme)
Local (per-document overrides)
This enables both consistency across a site and flexibility per page.
Theming UI (User-Facing Layer)
Users customize themes through a sidebar settings panel inside the editor.
Key UI Controls
Color Picker → primary colors (light / dark)
Header Layout → dropdown selection
Content Width → layout density
Images → logo, cover
Toggles → activity visibility
Metadata fields → document-specific settings
Theme Scope Model
Site Theme (Global Default)
Each site defines a default theme:
{
"theme": {
"colors": {
"light": { "primary": "#FF5733" }
}
}
}
This applies to:
all documents
navigation
shared UI elements
Document Theme (Override Layer)
Each document can define its own theme:
{
"theme": {
"headerLayout": "center",
"colors": {
"light": { "primary": "#0000FF" }
}
}
}
This overrides the site theme partially or fully.
Merge Strategy (Critical)
Final theme = deep merge:
Final Theme =
defaults
+ site theme
+ document overrides
Rules:
Only defined fields override
Undefined fields fall back to parent
No duplication required
Core Concept
The UI edits a layered theme object, not styles.
theme: {
headerLayout?: 'center' | ''
colors?: {
light?: { primary: string }
dark?: { primary: string }
}
}Key Principles
Layered Theming (New)
Themes are composable:
Global consistency (site)
Local expression (document)
This avoids:
duplication
rigid global styling
messy overrides
UI → Tokens (Not CSS)
The UI modifies structured data:
Color picker → theme.colors.light.primary
Layout dropdown → theme.headerLayout
Real-Time Feedback
Changes instantly re-render
Users see overrides in context
Safe Customization
Schema validation ensures correctness
No arbitrary CSS or breakage
System Architecture
Flow
User Interaction (UI)
↓
Document Theme (partial)
↓
Merge with Site Theme
↓
Merge with Defaults
↓
Validation + Normalization
↓
Render UI
Example: Layered Result
Site Theme
{
"colors": {
"light": { "primary": "red" }
}
}
Document Override
{
"colors": {
"light": { "primary": "blue" }
}
}Final Result
{
"colors": {
"light": { "primary": "blue" }
}
}UX Implications
Clear Mental Model
Users understand:
“This page looks different because I changed it here”
Visual Feedback Opportunity (Future)
Indicate when a value is:
inherited (from site)
overridden (in document)
Why This Matters
For Users
Flexibility without losing consistency
Ability to create special pages (landing, blog, etc.)
For Engineers
Clean override model
No cascading CSS complexity
Predictable rendering
Future Extensions
“Reset to site theme” button
Visual diff: site vs document theme
Theme inheritance across nested documents
Theme presets at site level
AI-generated per-page themes
References
Do you like what you are reading?. Subscribe to receive updates.
Unsubscribe anytime