feat(theme): create unified theme system with semantic tokens and migrate core layout
This commit is contained in:
zenchantlive
parent
b31e8ddade
commit
fcc1482967
10 changed files with 655 additions and 81 deletions
318
docs/plans/2025-02-26-theme-system-design.md
Normal file
318
docs/plans/2025-02-26-theme-system-design.md
Normal file
|
|
@ -0,0 +1,318 @@
|
|||
# Comprehensive Theme System Design
|
||||
|
||||
## The Problem
|
||||
We have colors scattered across 67+ files:
|
||||
- Hardcoded hex: `bg-[#0a111a]`, `bg-[#111f2b]`, `bg-[#14202e]`
|
||||
- Inline styles: `style={{ backgroundColor: '#1a2d3d' }}`
|
||||
- Arbitrary Tailwind: `bg-white/5`, `border-white/10`
|
||||
- Mixed variable systems: `--ui-bg-*`, `--color-bg-*`, etc.
|
||||
|
||||
## The Solution: Unified Theme System
|
||||
|
||||
### File Structure
|
||||
```
|
||||
src/styles/
|
||||
themes/
|
||||
index.css ← Theme definitions + data-attribute switching
|
||||
tokens.css ← Base CSS variable names (no values)
|
||||
components/
|
||||
surfaces.css ← Surface layer utilities
|
||||
interactions.css ← Hover, focus, active states
|
||||
```
|
||||
|
||||
### Token Architecture (12 Semantic Categories)
|
||||
|
||||
#### 1. SURFACE LAYERS (Backgrounds)
|
||||
```css
|
||||
--surface-backdrop: /* Page background */
|
||||
--surface-elevated: /* Header - sits on top */
|
||||
--surface-primary: /* Left sidebar */
|
||||
--surface-secondary: /* Main content area */
|
||||
--surface-tertiary: /* Panels/cards within sidebars */
|
||||
--surface-quaternary: /* Cards */
|
||||
--surface-overlay: /* Modals, dropdowns, drawers */
|
||||
--surface-input: /* Form fields, inputs */
|
||||
--surface-hover: /* Hover states */
|
||||
--surface-active: /* Active/selected states */
|
||||
--surface-tooltip: /* Tooltips, popovers */
|
||||
```
|
||||
|
||||
#### 2. BORDERS
|
||||
```css
|
||||
--border-subtle: /* Dividers between sections */
|
||||
--border-default: /* Card borders */
|
||||
--border-strong: /* Focus rings, selected states */
|
||||
--border-accent: /* Colored status borders */
|
||||
```
|
||||
|
||||
#### 3. TEXT
|
||||
```css
|
||||
--text-primary: /* Headlines, important text */
|
||||
--text-secondary: /* Body text */
|
||||
--text-tertiary: /* Muted, hints */
|
||||
--text-disabled: /* Disabled elements */
|
||||
--text-inverse: /* Text on colored backgrounds */
|
||||
```
|
||||
|
||||
#### 4. ACCENTS (Functional)
|
||||
```css
|
||||
--accent-info: /* Cyan - links, actions */
|
||||
--accent-success: /* Green - ready, done */
|
||||
--accent-warning: /* Amber - in progress */
|
||||
--accent-danger: /* Red - blocked, errors */
|
||||
```
|
||||
|
||||
#### 5. ACCENTS (Aurora Glow)
|
||||
```css
|
||||
--glow-info: /* Box-shadow glow for info */
|
||||
--glow-success: /* Box-shadow glow for success */
|
||||
--glow-warning: /* Box-shadow glow for warning */
|
||||
--glow-danger: /* Box-shadow glow for danger */
|
||||
```
|
||||
|
||||
#### 6. GRAPH COLORS
|
||||
```css
|
||||
--graph-node-default: /* Default node background */
|
||||
--graph-node-epic: /* Epic node accent */
|
||||
--graph-edge-default: /* Default edge color */
|
||||
--graph-edge-selected: /* Selected edge color */
|
||||
--graph-edge-cycle: /* Cycle warning color */
|
||||
```
|
||||
|
||||
#### 7. SEMANTIC ALPHAS
|
||||
Instead of `bg-white/5` and `bg-black/40`, use themeable alphas:
|
||||
```css
|
||||
--alpha-white-low: /* 5% white */
|
||||
--alpha-white-medium: /* 10% white */
|
||||
--alpha-white-high: /* 20% white */
|
||||
--alpha-black-low: /* 10% black */
|
||||
--alpha-black-medium: /* 40% black */
|
||||
--alpha-black-high: /* 80% black */
|
||||
```
|
||||
|
||||
#### 8. STATUS COLORS
|
||||
```css
|
||||
--status-ready: /* Ready/open status */
|
||||
--status-in-progress: /* In progress status */
|
||||
--status-blocked: /* Blocked status */
|
||||
--status-closed: /* Closed/done status */
|
||||
--status-deferred: /* Deferred status */
|
||||
```
|
||||
|
||||
#### 9. SHADOWS
|
||||
```css
|
||||
--shadow-sm: /* Subtle elevation */
|
||||
--shadow-md: /* Cards */
|
||||
--shadow-lg: /* Modals, drawers */
|
||||
--shadow-glow-info: /* Aurora glow */
|
||||
--shadow-glow-success: /* Aurora glow */
|
||||
--shadow-glow-warning: /* Aurora glow */
|
||||
--shadow-glow-danger: /* Aurora glow */
|
||||
```
|
||||
|
||||
#### 10. AGENT/ROLE COLORS
|
||||
```css
|
||||
--agent-role-ui: /* UI role color */
|
||||
--agent-role-graph: /* Graph role color */
|
||||
--agent-role-orchestrator: /* Orchestrator role */
|
||||
--agent-role-researcher: /* Researcher role */
|
||||
```
|
||||
|
||||
#### 11. SCROLLBARS
|
||||
```css
|
||||
--scrollbar-track: /* Scrollbar track */
|
||||
--scrollbar-thumb: /* Scrollbar thumb */
|
||||
--scrollbar-thumb-hover: /* Scrollbar thumb hover */
|
||||
```
|
||||
|
||||
#### 12. CODE/SYNTAX
|
||||
```css
|
||||
--code-background: /* Code block background */
|
||||
--code-text: /* Code text color */
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Theme Definitions (Example)
|
||||
|
||||
### Aurora Theme (Current)
|
||||
```css
|
||||
[data-theme="aurora"] {
|
||||
/* Surfaces - Warm Charcoal */
|
||||
--surface-backdrop: #181716;
|
||||
--surface-elevated: #131211;
|
||||
--surface-primary: #1f1e1d;
|
||||
--surface-secondary: #242322;
|
||||
--surface-tertiary: #282725;
|
||||
--surface-quaternary: #302e2c;
|
||||
--surface-overlay: #0d0c0b;
|
||||
|
||||
/* Borders */
|
||||
--border-subtle: rgba(180, 175, 165, 0.15);
|
||||
--border-default: rgba(180, 175, 165, 0.25);
|
||||
--border-strong: rgba(180, 175, 165, 0.4);
|
||||
|
||||
/* Text */
|
||||
--text-primary: #f0eeea;
|
||||
--text-secondary: #c9c5bc;
|
||||
--text-tertiary: #a8a49a;
|
||||
|
||||
/* Accents */
|
||||
--accent-info: #35c9ff;
|
||||
--accent-success: #35d98f;
|
||||
--accent-warning: #ffb24a;
|
||||
--accent-danger: #ff4c72;
|
||||
|
||||
/* Glows */
|
||||
--glow-info: 0 0 20px rgba(53, 201, 255, 0.3);
|
||||
--glow-success: 0 0 20px rgba(53, 217, 143, 0.3);
|
||||
|
||||
/* Graph */
|
||||
--graph-node-default: rgba(48, 46, 44, 0.8);
|
||||
--graph-node-epic: rgba(53, 201, 255, 0.15);
|
||||
--graph-edge-default: rgba(180, 175, 165, 0.3);
|
||||
--graph-edge-selected: #35c9ff;
|
||||
|
||||
/* Alphas */
|
||||
--alpha-white-low: rgba(240, 238, 234, 0.05);
|
||||
--alpha-white-medium: rgba(240, 238, 234, 0.1);
|
||||
--alpha-black-medium: rgba(0, 0, 0, 0.4);
|
||||
}
|
||||
```
|
||||
|
||||
### Midnight Theme (Future)
|
||||
```css
|
||||
[data-theme="midnight"] {
|
||||
--surface-backdrop: #0a0a0f;
|
||||
--surface-elevated: #050508;
|
||||
--surface-primary: #111118;
|
||||
--surface-secondary: #151520;
|
||||
--surface-quaternary: #1e1e2e;
|
||||
|
||||
--accent-info: #8b5cf6;
|
||||
--accent-success: #10b981;
|
||||
|
||||
/* Same structure, different values */
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Phase 1: Create Token System
|
||||
1. Create `src/styles/themes/index.css` with token definitions
|
||||
2. Create `src/styles/themes/tokens.css` with token names
|
||||
3. Add data-theme attribute to layout
|
||||
|
||||
### Phase 2: Component Audit & Migration
|
||||
For each component:
|
||||
1. Replace hardcoded colors with semantic tokens
|
||||
2. Replace `bg-white/5` with `bg-[var(--alpha-white-low)]`
|
||||
3. Replace `bg-[#0a111a]` with appropriate surface token
|
||||
|
||||
### Phase 3: Graph/Flow Colors
|
||||
1. Extract all graph colors to `--graph-*` tokens
|
||||
2. Update ReactFlow styles to use CSS variables
|
||||
|
||||
### Phase 4: Validation
|
||||
1. Create theme preview page showing all tokens
|
||||
2. Verify no hardcoded colors remain
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Before (Chaos):
|
||||
```tsx
|
||||
<div className="bg-[#0a111a] border border-white/10">
|
||||
<span className="text-[#a8a49a]">Text</span>
|
||||
</div>
|
||||
```
|
||||
|
||||
### After (Clean):
|
||||
```tsx
|
||||
<div className="bg-[var(--surface-tertiary)] border border-[var(--border-default)]">
|
||||
<span className="text-[var(--text-tertiary)]">Text</span>
|
||||
</div>
|
||||
```
|
||||
|
||||
### With Tailwind utilities (even cleaner):
|
||||
```tsx
|
||||
<div className="surface-tertiary border-default">
|
||||
<span className="text-tertiary">Text</span>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Mapping Guide
|
||||
|
||||
| Component | Current | New Token |
|
||||
|-----------|---------|-----------|
|
||||
| TopBar | `bg-[var(--ui-bg-header)]` | `bg-[var(--surface-elevated)]` |
|
||||
| LeftPanel | `bg-[var(--ui-bg-shell)]` | `bg-[var(--surface-primary)]` |
|
||||
| Main content | `bg-[var(--ui-bg-main)]` | `bg-[var(--surface-secondary)]` |
|
||||
| SocialCard | `bg-[var(--ui-bg-card)]` | `bg-[var(--surface-quaternary)]` |
|
||||
| AssignmentPanel | `bg-[#0a111a]` | `bg-[var(--surface-tertiary)]` |
|
||||
| Modal/Drawer | `bg-[#0d0c0b]` | `bg-[var(--surface-overlay)]` |
|
||||
| Input fields | `bg-[#0f1824]` | `bg-[var(--surface-input)]` |
|
||||
|
||||
---
|
||||
|
||||
## Files That Need Migration (Priority Order)
|
||||
|
||||
### HIGH (Core UI):
|
||||
1. `src/app/globals.css` - Define tokens
|
||||
2. `src/components/shared/unified-shell.tsx` - Main layout
|
||||
3. `src/components/shared/top-bar.tsx` - Header
|
||||
4. `src/components/shared/left-panel.tsx` - Sidebar
|
||||
5. `src/components/shared/right-panel.tsx` - Right panel
|
||||
6. `src/components/social/social-card.tsx` - Cards
|
||||
|
||||
### MEDIUM (Active Views):
|
||||
7. `src/components/graph/assignment-panel.tsx` - Heavy hardcoded colors
|
||||
8. `src/components/graph/graph-node-card.tsx` - Graph nodes
|
||||
9. `src/components/activity/swarm-command-feed.tsx` - Activity feed
|
||||
10. `src/components/graph/smart-dag.tsx` - Graph background
|
||||
|
||||
### LOWER (Secondary):
|
||||
11. All modal/dialog components
|
||||
12. All form/input components
|
||||
13. Kanban components (if still used)
|
||||
14. Swarm components
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Zero hardcoded hex colors in components (except for data viz)
|
||||
- [ ] Zero `bg-white/X` or `bg-black/X` - all use `--alpha-*` tokens
|
||||
- [ ] Theme switcher works instantly without reload
|
||||
- [ ] All 12 token categories have values for each theme
|
||||
- [ ] Visual regression test passes (no unintended changes)
|
||||
|
||||
---
|
||||
|
||||
## For You (The Human)
|
||||
|
||||
Once this is implemented, you can just say:
|
||||
> "Change the sidebar to be slightly lighter in the aurora theme"
|
||||
|
||||
And I'll know exactly where to go:
|
||||
```css
|
||||
[data-theme="aurora"] {
|
||||
--surface-primary: #252422; /* Changed from #1f1e1d */
|
||||
}
|
||||
```
|
||||
|
||||
Or:
|
||||
> "Make the aurora glow more subtle"
|
||||
|
||||
```css
|
||||
[data-theme="aurora"] {
|
||||
--glow-info: 0 0 12px rgba(53, 201, 255, 0.15); /* Reduced from 20px/0.3 */
|
||||
}
|
||||
```
|
||||
|
||||
Everything in one place. No hunting through 67 files.
|
||||
Loading…
Add table
Add a link
Reference in a new issue