Advanced Theming & Theme Store
An expansion of the current ShellApps theming system from "pick a colour palette + light/dark" to full granular customisation. Users can create their own themes and share them on a theme store.
Current State vs Expanded Model
Before
- 11 preset themes (shell, indigo, emerald, rose, amber, sky, violet, teal, slate, fuchsia, crimson)
- Each theme: primary + accent colour scale, neutral scale, semantic tokens, radius, shadow
- Light / Dark / System mode toggle
- Per-app theme override
- CSS custom properties applied by ThemeProvider
After — Full Customisation
| Category | What You Can Customise |
|---|---|
| Colours | Primary scale, accent scale, neutral scale, semantic tokens (bg, text, border, etc.) — editable per-shade |
| Typography | Font family (body, heading, mono), font sizes (xs through 4xl), weights, line heights, letter spacing |
| Backgrounds | Page, elevated (cards), muted, hover, input, sidebar, header, overlay — each independently |
| Text | Primary, secondary, muted, placeholder, inverse, link, link hover |
| Borders | Default colour, strong colour, focus colour, error colour, widths (thin/default/thick) |
| Spacing | Scale: compact / comfortable / spacious (affects all padding/margins proportionally) |
| Radius | sm, md, lg, xl, full (editable) |
| Shadows | sm, md, lg (editable) |
| Animations | Speed: none / reduced / normal / playful. Transition duration, easing curve. |
Everything has sensible defaults from the base theme — users only override what they want to change.
Theme Builder
A visual editor in the Experience dashboard (/themes/builder):
┌─────────────────────────────────────────────────────────────────┐
│ Theme Builder [Save] [Publish]│
│ │
│ ┌──────────────────────┐ ┌──────────────────────────────────┐ │
│ │ CONTROLS │ │ LIVE PREVIEW │ │
│ │ │ │ │ │
│ │ Base: Shell ▼ │ │ ┌─────────────────────────────┐ │ │
│ │ │ │ │ Sample App │ │ │
│ │ ▸ Colours │ │ │ │ │ │
│ │ ▸ Typography │ │ │ Welcome back, Alex │ │ │
│ │ ▸ Backgrounds │ │ │ │ │ │
│ │ ▸ Text │ │ │ ┌─────┐ ┌─────┐ ┌─────┐ │ │ │
│ │ ▸ Borders │ │ │ │Card │ │Card │ │Card │ │ │ │
│ │ ▸ Spacing │ │ │ │ 1 │ │ 2 │ │ 3 │ │ │ │
│ │ ▸ Radius │ │ │ └─────┘ └─────┘ └─────┘ │ │ │
│ │ ▸ Shadows │ │ │ │ │ │
│ │ ▸ Animations │ │ │ [Primary Button] [Ghost] │ │ │
│ │ │ │ │ │ │ │
│ │ Import JSON ↑ │ │ │ Input: [placeholder text] │ │ │
│ │ Export JSON ↓ │ │ │ │ │ │
│ └──────────────────────┘ │ └─────────────────────────────┘ │ │
│ │ │ │
│ │ [Desktop] [Mobile] [Dark] [Light]│ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘Live Preview
- Updates in real-time as controls change
- Shows a sample app layout with all common components (cards, buttons, inputs, nav, text)
- Toggle desktop/mobile viewport
- Toggle dark/light mode
- Preview different pages (form, dashboard, list, detail)
Theme Store
┌─────────────────────────────────────────────────────────────────┐
│ Theme Store [Create Theme] │
│ │
│ [Popular] [New] [Dark] [Minimal] [Vibrant] [Professional] │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ████████ │ │ ████████ │ │ ████████ │ │
│ │ Nord │ │ Dracula │ │ Solarized │ │
│ │ by @alex │ │ by @sarah │ │ by @james │ │
│ │ ⭐ 4.8 (142)│ │ ⭐ 4.6 (89) │ │ ⭐ 4.9 (201)│ │
│ │ [Preview] │ │ [Preview] │ │ [Preview] │ │
│ │ [Install] │ │ [Install] │ │ [Install] │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘Store Features
- Browse themes by category, popularity, recency
- Preview before installing (live preview in modal)
- One-click install (adds to your theme collection)
- Rate themes
- "Official" badge for built-in themes (shell, indigo, etc.)
- Fork: use any theme as a starting point for your own
Migration from Current System
- The 11 built-in themes become "official" entries in the theme store
- ThemeProvider updated to fetch theme definitions from Experience API
- Falls back to built-in themes if API unavailable (offline resilience)
- Existing user preferences (theme ID + mode) continue to work
- New granular overrides are optional — existing simple theme selection still works
API Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
POST | /api/v1/themes | Bearer | Create theme |
GET | /api/v1/themes | Bearer | List user's themes |
GET | /api/v1/themes/store | Bearer | Browse public theme store |
GET | /api/v1/themes/:id | API Key/Bearer | Get theme definition |
PUT | /api/v1/themes/:id | Bearer | Update theme |
POST | /api/v1/themes/:id/publish | Bearer | Publish to store |
POST | /api/v1/themes/:id/install | Bearer | Install theme |
POST | /api/v1/themes/:id/rate | Bearer | Rate theme |
See the full API Reference and Data Models for schemas.