opsfuse-ui 0.1.24 → 0.1.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,257 +1,257 @@
1
- # Color Theme & Typography Guide — OpsFuse UI
2
-
3
- You are an expert on the OpsFuse UI design token system. When invoked, answer questions about which color token, typography class, or theme variable to use — and when and why.
4
-
5
- ---
6
-
7
- ## Token Philosophy
8
-
9
- Every token has **one name and one purpose**. Color names follow **shadcn/ui** conventions in `brands.css` (`--background`, `--foreground`, `--destructive`, …). Never use arbitrary colors or Tailwind palette classes (e.g. `blue-500`). Always reach for the semantic token that describes the *role*, not the appearance.
10
-
11
- **File locations:**
12
- - Color tokens → `src/brands.css`
13
- - Non-color tokens (spacing, radius, motion, z-index) → `src/index.css`
14
-
15
- ---
16
-
17
- ## Surface Tokens — Elevation Ladder (shadcn-aligned)
18
-
19
- Use the surface that matches the element's visual elevation. Names match shadcn/ui (`--background`, `--card`, `--muted`, …). Light mode uses borders to define depth; dark mode uses surface tones.
20
-
21
- | Level | When to use | Token |
22
- |-------|-------------|-------|
23
- | 0 — Page canvas | Root background, app shell | `--background` |
24
- | 1 — Cards & panels | Card bodies, sidebars, list items | `--card` + `--border` |
25
- | 2 — Inset / recessed | Input backgrounds, code blocks, inset sections | `--muted` |
26
- | 2.5 — Overlays | Hover highlights, selected rows, subtle overlays | `--accent` |
27
- | 3 — Dropdowns / popovers | Dropdown menus, command palette, tooltip panels | `--popover` + `--shadow-md` |
28
- | 4 — Modals | Dialog overlays, drawer contents | `--popover` + `--shadow-lg` |
29
-
30
- **Rules:**
31
- - Never skip levels (e.g. don't put a modal on `--background` alone when you need popover elevation)
32
- - Never use `white` or `black` directly — they break dark mode
33
- - `--card` is for things that "float" above the page canvas
34
-
35
- ---
36
-
37
- ## Text Tokens
38
-
39
- | Token | Role | Examples |
40
- |-------|------|---------|
41
- | `--foreground` | Headings, critical labels, active states | `<h1>` – `<h4>`, selected nav items |
42
- | `--subtle-foreground` | Body copy, descriptions, general text | `<p>`, card descriptions, list items |
43
- | `--muted-foreground` | Meta, timestamps, placeholder-adjacent hints | Captions, helper text, subtitles (also shadcn `muted-foreground`) |
44
- | `--disabled-foreground` | Disabled state labels | Disabled form fields, dimmed text |
45
-
46
- **Rule:** Never use `--muted-foreground` for interactive text. It fails contrast in some brand themes.
47
-
48
- ---
49
-
50
- ## Primary Action Tokens
51
-
52
- | Token | Use |
53
- |-------|-----|
54
- | `--primary` | Button bg, active underlines, accent dots |
55
- | `--primary-foreground` | Text/icon on top of `--primary` bg (shadcn name) |
56
- | `--primary-hover` | Hover state for primary bg |
57
- | `--primary-active` | Pressed/active state |
58
- | `--primary-muted` | Tinted bg for selected/highlighted items (not buttons) |
59
- | `--primary-muted-hover` | Hover on a primary-tinted surface |
60
- | `--primary-border` | Border on primary-tinted surfaces |
61
- | `--primary-muted-foreground` | Text inside primary-tinted surfaces (NOT on filled primary bg) |
62
-
63
- **Rule:** Use `--primary-foreground` when text sits on `--primary` itself. Use `--primary-muted-foreground` when text sits on `--primary-muted`.
64
-
65
- ---
66
-
67
- ## AI Identity Tokens
68
-
69
- The AI system is visually distinct — cool teal, separate from the warm indigo primary. Keep AI surfaces limited to AI-generated content.
70
-
71
- | Token | Use |
72
- |-------|-----|
73
- | `--ai` | AI accent dot, pulsing indicator |
74
- | `--ai-foreground` | Icon/text directly on `--ai` bg |
75
- | `--ai-muted` | Background of AI response panels |
76
- | `--ai-muted-hover` | Hover on AI surfaces |
77
- | `--ai-border` | Border around AI panels / `.strip-ai` |
78
- | `--ai-muted-foreground` | Text inside AI surfaces |
79
-
80
- **CSS utilities available:**
81
- - `.badge-ai` — animated pulsing badge with "AI" label
82
- - `.strip-ai` — left-bordered AI response panel
83
- - `.pill-ai` — small AI status pill
84
- - `.score-fill-ai` — teal score bar fill
85
- - `.prose-ai` — open-tracked text style for AI output
86
-
87
- ---
88
-
89
- ## Semantic State Tokens
90
-
91
- Each semantic state uses a **muted + foreground** pattern (aligned with destructive naming in shadcn). **Destructive** replaces the old `danger` prefix.
92
-
93
- | State | Solid / indicator | On-solid text | Tinted bg | Border on tint | Text on tint |
94
- |-------|---------------------|---------------|-----------|----------------|---------------|
95
- | `success` | `--success` | `--success-foreground` | `--success-muted` | `--success-border` | `--success-muted-foreground` |
96
- | `warning` | `--warning` | `--warning-foreground` | `--warning-muted` | `--warning-border` | `--warning-muted-foreground` |
97
- | `destructive` | `--destructive` | `--destructive-foreground` | `--destructive-muted` | `--destructive-border` | `--destructive-muted-foreground` |
98
- | `info` | `--info` | `--info-foreground` | `--info-muted` | `--info-border` | `--info-muted-foreground` |
99
-
100
- **CSS pill utilities:** `.pill-success`, `.pill-warning`, `.pill-danger` (class name unchanged; tokens are `--destructive*`)
101
- **Score bar fills:** `.score-fill-good`, `.score-fill-warn`, `.score-fill-danger`
102
-
103
- **When to use which state:**
104
- - `success` → completed actions, passing scores, confirmations
105
- - `warning` → partial, below-threshold, user attention needed
106
- - `destructive` → errors, deletion, destructive consequences
107
- - `info` → neutral callouts, help text, tips
108
-
109
- ---
110
-
111
- ## Border Tokens
112
-
113
- | Token | Use |
114
- |-------|-----|
115
- | `--border-subtle` | Very faint dividers, zebra rows, barely-there separators |
116
- | `--border` | Standard card/input borders (Level 1 elevation; shadcn default border token) |
117
- | `--border-strong` | Hover states on cards, active inputs, emphasized separators |
118
-
119
- ---
120
-
121
- ## Shadow Tokens
122
-
123
- | Token | When |
124
- |-------|------|
125
- | `--shadow-focus` | Focus rings (3px ring on interactive elements) |
126
- | `--shadow-sm` | Subtle card lift, Level 1 hover |
127
- | `--shadow-md` | Dropdowns, popovers (Level 3) |
128
- | `--shadow-lg` | Modals, drawers (Level 4) |
129
-
130
- ---
131
-
132
- ## Brand Themes
133
-
134
- Apply via CSS class on the `.opsfuse-ui` root or the `OpsfuseThemeProvider` `brand` prop.
135
-
136
- | Class | Brand | Personality | Primary color |
137
- |-------|-------|-------------|---------------|
138
- | *(none)* | **OpsFuse Default** | Warm Minimal · Deep · Intelligent | Indigo `oklch(0.56 0.19 278)` |
139
- | `brand-skillready` | **SkillReady** | Warm · Confident · Growth-Oriented | Burnt Orange `#c2561a` |
140
- | `brand-lms` | **LMS** (Leave Management) | Calm · Clear · Dependable | Emerald Green `#00966b` |
141
- | *(other brand classes defined in brands.css)* | ... | ... | ... |
142
-
143
- **How to apply:** `<OpsfuseThemeProvider brand="skillready">` or add `brand-skillready` class.
144
-
145
- ---
146
-
147
- ## Gradient Tokens
148
-
149
- | Token | Use |
150
- |-------|-----|
151
- | `--brand-gradient` | Hero sections, logo backgrounds, marquee CTAs |
152
- | `--brand-gradient-subtle` | Gentle page headers, section tints |
153
-
154
- **Rule:** Limit `--brand-gradient` to 1–2 elements per page. It's a premium accent, not a background fill.
155
-
156
- ---
157
-
158
- ## Chart Tokens
159
-
160
- Use in order: `--chart-1` through `--chart-6` for multi-series data. Then `--chart-grid` for gridlines and `--chart-axis` for axis labels.
161
-
162
- **Score display tokens** (ordered worst → best):
163
- `--score-poor` → `--score-below` → `--score-average` → `--score-good` → `--score-excellent`
164
-
165
- ---
166
-
167
- ## Typography Classes
168
-
169
- Defined in `index.css` `@layer components`. Use these instead of manual font/size/color combos.
170
-
171
- | Class | Size | Color | Line-height | Use |
172
- |-------|------|-------|-------------|-----|
173
- | `.prose-body` | 1rem | `--subtle-foreground` | 1.75 | Long-form paragraphs, articles |
174
- | `.prose-ui` | 0.9rem | `--subtle-foreground` | 1.6 | Interface text, descriptions, form help |
175
- | `.prose-ai` | 0.925rem | `--subtle-foreground` | 1.8 | AI-generated text (open letter-spacing signals machine output) |
176
- | `.prose-mono` | 0.82rem | `--subtle-foreground` | 1.6 | Code snippets, scores, statistics |
177
- | `.caption` | 0.75rem | `--muted-foreground` | 1.5 | Timestamps, meta, helper text |
178
- | `.label-sm` | 0.7rem | `--muted-foreground` | 1 | Uppercase section labels (uppercase + tracked) |
179
-
180
- **Heading elements** (`h1`–`h4`) are styled globally via element selectors — no extra class needed. They all use `--foreground`.
181
-
182
- ---
183
-
184
- ## Motion / Transition Classes
185
-
186
- | Class | Use |
187
- |-------|-----|
188
- | `.transition-micro` | Buttons, chips, icons, hover color flips. Includes `scale(0.97)` on `:active` |
189
- | `.transition-smooth` | Inputs, panels, dropdowns, tabs |
190
- | `.transition-data` | Score bars, progress reveals, animated widths |
191
-
192
- **Motion tokens:**
193
- - `--duration-fast`: 120ms — hover colors, focus rings
194
- - `--duration-base`: 200ms — inputs, buttons, dropdowns
195
- - `--duration-slow`: 500ms — charts, score bars, page transitions
196
- - `--ease-standard`: `cubic-bezier(0.16, 1, 0.3, 1)` — most transitions
197
- - `--ease-spring`: `cubic-bezier(0.34, 1.56, 0.64, 1)` — snappy button presses
198
-
199
- ---
200
-
201
- ## Spacing Tokens
202
-
203
- | Token | Value | Use |
204
- |-------|-------|-----|
205
- | `--space-1` | 4px | Tight: icon↔text, inline gaps |
206
- | `--space-2` | 8px | Compact: badge padding, small gaps |
207
- | `--space-3` | 12px | Standard: input padding-x, list gaps |
208
- | `--space-4` | 16px | Default: card padding, section gaps |
209
- | `--space-5` | 24px | Comfortable: between card sections |
210
- | `--space-6` | 32px | Major: between groups of content |
211
- | `--space-8` | 48px | Large: page-level vertical rhythm |
212
- | `--space-10` | 64px | Hero: top-level, hero sections |
213
-
214
- ---
215
-
216
- ## Radius Tokens
217
-
218
- | Token | Value | `rounded-*` | Use |
219
- |-------|-------|-------------|-----|
220
- | `--radius-xs` | 4px | `rounded-xs` | Tiny chips, tags, inline tokens |
221
- | `--radius-sm` | 6px | `rounded-sm` | Badges, chips, small inline elements |
222
- | `--radius` | 10px | `rounded-md` | Inputs, buttons, standard components |
223
- | `--radius-lg` | 14px | `rounded-lg` | Cards, panels, modals |
224
- | `--radius-xl` | 20px | `rounded-xl` | Hero cards, featured containers |
225
- | `--radius-2xl` | 28px | `rounded-2xl` | Large surfaces, sheets, marketing blocks |
226
- | `--radius-3xl` | 36px | `rounded-3xl` | Oversized hero / showcase containers |
227
-
228
- Every `rounded-*` variant (all sizes above + `rounded-full` / `rounded-none`, across all corners and sides — `rounded-t-*`, `rounded-tl-*`, logical `rounded-s-*`/`rounded-ss-*`, etc.) is force-emitted into the bundle via `@source inline(...)`, so they're always available even if no component uses them yet.
229
-
230
- ---
231
-
232
- ## Do / Don't
233
-
234
- | ✅ Do | ❌ Don't |
235
- |-------|---------|
236
- | `color: var(--subtle-foreground)` | `color: #6b7280` |
237
- | `background: var(--card)` | `background: white` |
238
- | `border-color: var(--border)` | Hardcoded gray border hex |
239
- | `var(--primary-muted-foreground)` on primary-tinted surfaces | `var(--primary-foreground)` on those surfaces (wrong pairing) |
240
- | `.caption` class for meta text | `text-xs text-gray-400` |
241
- | `var(--destructive)` for error icons / destructive actions | Raw `red-600` / hex reds |
242
-
243
- **Shadcn alignment:** Canonical color variables in `brands.css` use the same names shadcn/ui expects (`--background`, `--foreground`, `--card`, `--muted`, `--destructive`, `-*-foreground`, semantic `-*-muted` / `-*-muted-foreground`). Tailwind utilities (`bg-background`, `text-foreground`, …) are wired in `src/index.css` `@theme inline` to those variables. Use **`--subtle-foreground`** and **`--disabled-foreground`** for the extra text steps beyond shadcn's single `muted-foreground`.
244
-
245
- ---
246
-
247
- ## Z-Index Scale
248
-
249
- | Token | Value | Layer |
250
- |-------|-------|-------|
251
- | `--z-base` | 0 | Normal flow |
252
- | `--z-raised` | 10 | Sticky elements, floating buttons |
253
- | `--z-dropdown` | 100 | Dropdown menus |
254
- | `--z-sticky` | 200 | Sticky headers |
255
- | `--z-modal` | 300 | Modals, dialogs |
256
- | `--z-popover` | 400 | Popovers, tooltips |
257
- | `--z-toast` | 500 | Toast notifications |
1
+ # Color Theme & Typography Guide — OpsFuse UI
2
+
3
+ You are an expert on the OpsFuse UI design token system. When invoked, answer questions about which color token, typography class, or theme variable to use — and when and why.
4
+
5
+ ---
6
+
7
+ ## Token Philosophy
8
+
9
+ Every token has **one name and one purpose**. Color names follow **shadcn/ui** conventions in `brands.css` (`--background`, `--foreground`, `--destructive`, …). Never use arbitrary colors or Tailwind palette classes (e.g. `blue-500`). Always reach for the semantic token that describes the *role*, not the appearance.
10
+
11
+ **File locations:**
12
+ - Color tokens → `src/brands.css`
13
+ - Non-color tokens (spacing, radius, motion, z-index) → `src/index.css`
14
+
15
+ ---
16
+
17
+ ## Surface Tokens — Elevation Ladder (shadcn-aligned)
18
+
19
+ Use the surface that matches the element's visual elevation. Names match shadcn/ui (`--background`, `--card`, `--muted`, …). Light mode uses borders to define depth; dark mode uses surface tones.
20
+
21
+ | Level | When to use | Token |
22
+ |-------|-------------|-------|
23
+ | 0 — Page canvas | Root background, app shell | `--background` |
24
+ | 1 — Cards & panels | Card bodies, sidebars, list items | `--card` + `--border` |
25
+ | 2 — Inset / recessed | Input backgrounds, code blocks, inset sections | `--muted` |
26
+ | 2.5 — Overlays | Hover highlights, selected rows, subtle overlays | `--accent` |
27
+ | 3 — Dropdowns / popovers | Dropdown menus, command palette, tooltip panels | `--popover` + `--shadow-md` |
28
+ | 4 — Modals | Dialog overlays, drawer contents | `--popover` + `--shadow-lg` |
29
+
30
+ **Rules:**
31
+ - Never skip levels (e.g. don't put a modal on `--background` alone when you need popover elevation)
32
+ - Never use `white` or `black` directly — they break dark mode
33
+ - `--card` is for things that "float" above the page canvas
34
+
35
+ ---
36
+
37
+ ## Text Tokens
38
+
39
+ | Token | Role | Examples |
40
+ |-------|------|---------|
41
+ | `--foreground` | Headings, critical labels, active states | `<h1>` – `<h4>`, selected nav items |
42
+ | `--subtle-foreground` | Body copy, descriptions, general text | `<p>`, card descriptions, list items |
43
+ | `--muted-foreground` | Meta, timestamps, placeholder-adjacent hints | Captions, helper text, subtitles (also shadcn `muted-foreground`) |
44
+ | `--disabled-foreground` | Disabled state labels | Disabled form fields, dimmed text |
45
+
46
+ **Rule:** Never use `--muted-foreground` for interactive text. It fails contrast in some brand themes.
47
+
48
+ ---
49
+
50
+ ## Primary Action Tokens
51
+
52
+ | Token | Use |
53
+ |-------|-----|
54
+ | `--primary` | Button bg, active underlines, accent dots |
55
+ | `--primary-foreground` | Text/icon on top of `--primary` bg (shadcn name) |
56
+ | `--primary-hover` | Hover state for primary bg |
57
+ | `--primary-active` | Pressed/active state |
58
+ | `--primary-muted` | Tinted bg for selected/highlighted items (not buttons) |
59
+ | `--primary-muted-hover` | Hover on a primary-tinted surface |
60
+ | `--primary-border` | Border on primary-tinted surfaces |
61
+ | `--primary-muted-foreground` | Text inside primary-tinted surfaces (NOT on filled primary bg) |
62
+
63
+ **Rule:** Use `--primary-foreground` when text sits on `--primary` itself. Use `--primary-muted-foreground` when text sits on `--primary-muted`.
64
+
65
+ ---
66
+
67
+ ## AI Identity Tokens
68
+
69
+ The AI system is visually distinct — cool teal, separate from the warm indigo primary. Keep AI surfaces limited to AI-generated content.
70
+
71
+ | Token | Use |
72
+ |-------|-----|
73
+ | `--ai` | AI accent dot, pulsing indicator |
74
+ | `--ai-foreground` | Icon/text directly on `--ai` bg |
75
+ | `--ai-muted` | Background of AI response panels |
76
+ | `--ai-muted-hover` | Hover on AI surfaces |
77
+ | `--ai-border` | Border around AI panels / `.strip-ai` |
78
+ | `--ai-muted-foreground` | Text inside AI surfaces |
79
+
80
+ **CSS utilities available:**
81
+ - `.badge-ai` — animated pulsing badge with "AI" label
82
+ - `.strip-ai` — left-bordered AI response panel
83
+ - `.pill-ai` — small AI status pill
84
+ - `.score-fill-ai` — teal score bar fill
85
+ - `.prose-ai` — open-tracked text style for AI output
86
+
87
+ ---
88
+
89
+ ## Semantic State Tokens
90
+
91
+ Each semantic state uses a **muted + foreground** pattern (aligned with destructive naming in shadcn). **Destructive** replaces the old `danger` prefix.
92
+
93
+ | State | Solid / indicator | On-solid text | Tinted bg | Border on tint | Text on tint |
94
+ |-------|---------------------|---------------|-----------|----------------|---------------|
95
+ | `success` | `--success` | `--success-foreground` | `--success-muted` | `--success-border` | `--success-muted-foreground` |
96
+ | `warning` | `--warning` | `--warning-foreground` | `--warning-muted` | `--warning-border` | `--warning-muted-foreground` |
97
+ | `destructive` | `--destructive` | `--destructive-foreground` | `--destructive-muted` | `--destructive-border` | `--destructive-muted-foreground` |
98
+ | `info` | `--info` | `--info-foreground` | `--info-muted` | `--info-border` | `--info-muted-foreground` |
99
+
100
+ **CSS pill utilities:** `.pill-success`, `.pill-warning`, `.pill-danger` (class name unchanged; tokens are `--destructive*`)
101
+ **Score bar fills:** `.score-fill-good`, `.score-fill-warn`, `.score-fill-danger`
102
+
103
+ **When to use which state:**
104
+ - `success` → completed actions, passing scores, confirmations
105
+ - `warning` → partial, below-threshold, user attention needed
106
+ - `destructive` → errors, deletion, destructive consequences
107
+ - `info` → neutral callouts, help text, tips
108
+
109
+ ---
110
+
111
+ ## Border Tokens
112
+
113
+ | Token | Use |
114
+ |-------|-----|
115
+ | `--border-subtle` | Very faint dividers, zebra rows, barely-there separators |
116
+ | `--border` | Standard card/input borders (Level 1 elevation; shadcn default border token) |
117
+ | `--border-strong` | Hover states on cards, active inputs, emphasized separators |
118
+
119
+ ---
120
+
121
+ ## Shadow Tokens
122
+
123
+ | Token | When |
124
+ |-------|------|
125
+ | `--shadow-focus` | Focus rings (3px ring on interactive elements) |
126
+ | `--shadow-sm` | Subtle card lift, Level 1 hover |
127
+ | `--shadow-md` | Dropdowns, popovers (Level 3) |
128
+ | `--shadow-lg` | Modals, drawers (Level 4) |
129
+
130
+ ---
131
+
132
+ ## Brand Themes
133
+
134
+ Apply via CSS class on the `.opsfuse-ui` root or the `OpsfuseThemeProvider` `brand` prop.
135
+
136
+ | Class | Brand | Personality | Primary color |
137
+ |-------|-------|-------------|---------------|
138
+ | *(none)* | **OpsFuse Default** | Warm Minimal · Deep · Intelligent | Indigo `oklch(0.56 0.19 278)` |
139
+ | `brand-skillready` | **SkillReady** | Warm · Confident · Growth-Oriented | Burnt Orange `#c2561a` |
140
+ | `brand-lms` | **LMS** (Leave Management) | Calm · Clear · Dependable | Emerald Green `#00966b` |
141
+ | *(other brand classes defined in brands.css)* | ... | ... | ... |
142
+
143
+ **How to apply:** `<OpsfuseThemeProvider brand="skillready">` or add `brand-skillready` class.
144
+
145
+ ---
146
+
147
+ ## Gradient Tokens
148
+
149
+ | Token | Use |
150
+ |-------|-----|
151
+ | `--brand-gradient` | Hero sections, logo backgrounds, marquee CTAs |
152
+ | `--brand-gradient-subtle` | Gentle page headers, section tints |
153
+
154
+ **Rule:** Limit `--brand-gradient` to 1–2 elements per page. It's a premium accent, not a background fill.
155
+
156
+ ---
157
+
158
+ ## Chart Tokens
159
+
160
+ Use in order: `--chart-1` through `--chart-6` for multi-series data. Then `--chart-grid` for gridlines and `--chart-axis` for axis labels.
161
+
162
+ **Score display tokens** (ordered worst → best):
163
+ `--score-poor` → `--score-below` → `--score-average` → `--score-good` → `--score-excellent`
164
+
165
+ ---
166
+
167
+ ## Typography Classes
168
+
169
+ Defined in `index.css` `@layer components`. Use these instead of manual font/size/color combos.
170
+
171
+ | Class | Size | Color | Line-height | Use |
172
+ |-------|------|-------|-------------|-----|
173
+ | `.prose-body` | 1rem | `--subtle-foreground` | 1.75 | Long-form paragraphs, articles |
174
+ | `.prose-ui` | 0.9rem | `--subtle-foreground` | 1.6 | Interface text, descriptions, form help |
175
+ | `.prose-ai` | 0.925rem | `--subtle-foreground` | 1.8 | AI-generated text (open letter-spacing signals machine output) |
176
+ | `.prose-mono` | 0.82rem | `--subtle-foreground` | 1.6 | Code snippets, scores, statistics |
177
+ | `.caption` | 0.75rem | `--muted-foreground` | 1.5 | Timestamps, meta, helper text |
178
+ | `.label-sm` | 0.7rem | `--muted-foreground` | 1 | Uppercase section labels (uppercase + tracked) |
179
+
180
+ **Heading elements** (`h1`–`h4`) are styled globally via element selectors — no extra class needed. They all use `--foreground`.
181
+
182
+ ---
183
+
184
+ ## Motion / Transition Classes
185
+
186
+ | Class | Use |
187
+ |-------|-----|
188
+ | `.transition-micro` | Buttons, chips, icons, hover color flips. Includes `scale(0.97)` on `:active` |
189
+ | `.transition-smooth` | Inputs, panels, dropdowns, tabs |
190
+ | `.transition-data` | Score bars, progress reveals, animated widths |
191
+
192
+ **Motion tokens:**
193
+ - `--duration-fast`: 120ms — hover colors, focus rings
194
+ - `--duration-base`: 200ms — inputs, buttons, dropdowns
195
+ - `--duration-slow`: 500ms — charts, score bars, page transitions
196
+ - `--ease-standard`: `cubic-bezier(0.16, 1, 0.3, 1)` — most transitions
197
+ - `--ease-spring`: `cubic-bezier(0.34, 1.56, 0.64, 1)` — snappy button presses
198
+
199
+ ---
200
+
201
+ ## Spacing Tokens
202
+
203
+ | Token | Value | Use |
204
+ |-------|-------|-----|
205
+ | `--space-1` | 4px | Tight: icon↔text, inline gaps |
206
+ | `--space-2` | 8px | Compact: badge padding, small gaps |
207
+ | `--space-3` | 12px | Standard: input padding-x, list gaps |
208
+ | `--space-4` | 16px | Default: card padding, section gaps |
209
+ | `--space-5` | 24px | Comfortable: between card sections |
210
+ | `--space-6` | 32px | Major: between groups of content |
211
+ | `--space-8` | 48px | Large: page-level vertical rhythm |
212
+ | `--space-10` | 64px | Hero: top-level, hero sections |
213
+
214
+ ---
215
+
216
+ ## Radius Tokens
217
+
218
+ | Token | Value | `rounded-*` | Use |
219
+ |-------|-------|-------------|-----|
220
+ | `--radius-xs` | 4px | `rounded-xs` | Tiny chips, tags, inline tokens |
221
+ | `--radius-sm` | 6px | `rounded-sm` | Badges, chips, small inline elements |
222
+ | `--radius` | 10px | `rounded-md` | Inputs, buttons, standard components |
223
+ | `--radius-lg` | 14px | `rounded-lg` | Cards, panels, modals |
224
+ | `--radius-xl` | 20px | `rounded-xl` | Hero cards, featured containers |
225
+ | `--radius-2xl` | 28px | `rounded-2xl` | Large surfaces, sheets, marketing blocks |
226
+ | `--radius-3xl` | 36px | `rounded-3xl` | Oversized hero / showcase containers |
227
+
228
+ Every `rounded-*` variant (all sizes above + `rounded-full` / `rounded-none`, across all corners and sides — `rounded-t-*`, `rounded-tl-*`, logical `rounded-s-*`/`rounded-ss-*`, etc.) is force-emitted into the bundle via `@source inline(...)`, so they're always available even if no component uses them yet.
229
+
230
+ ---
231
+
232
+ ## Do / Don't
233
+
234
+ | ✅ Do | ❌ Don't |
235
+ |-------|---------|
236
+ | `color: var(--subtle-foreground)` | `color: #6b7280` |
237
+ | `background: var(--card)` | `background: white` |
238
+ | `border-color: var(--border)` | Hardcoded gray border hex |
239
+ | `var(--primary-muted-foreground)` on primary-tinted surfaces | `var(--primary-foreground)` on those surfaces (wrong pairing) |
240
+ | `.caption` class for meta text | `text-xs text-gray-400` |
241
+ | `var(--destructive)` for error icons / destructive actions | Raw `red-600` / hex reds |
242
+
243
+ **Shadcn alignment:** Canonical color variables in `brands.css` use the same names shadcn/ui expects (`--background`, `--foreground`, `--card`, `--muted`, `--destructive`, `-*-foreground`, semantic `-*-muted` / `-*-muted-foreground`). Tailwind utilities (`bg-background`, `text-foreground`, …) are wired in `src/index.css` `@theme inline` to those variables. Use **`--subtle-foreground`** and **`--disabled-foreground`** for the extra text steps beyond shadcn's single `muted-foreground`.
244
+
245
+ ---
246
+
247
+ ## Z-Index Scale
248
+
249
+ | Token | Value | Layer |
250
+ |-------|-------|-------|
251
+ | `--z-base` | 0 | Normal flow |
252
+ | `--z-raised` | 10 | Sticky elements, floating buttons |
253
+ | `--z-dropdown` | 100 | Dropdown menus |
254
+ | `--z-sticky` | 200 | Sticky headers |
255
+ | `--z-modal` | 300 | Modals, dialogs |
256
+ | `--z-popover` | 400 | Popovers, tooltips |
257
+ | `--z-toast` | 500 | Toast notifications |