@aurora-ds/theme 1.5.0 → 2.0.0
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.
- package/README.dev.md +84 -2
- package/README.md +382 -90
- package/dist/index.cjs +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +262 -464
- package/dist/index.d.ts +262 -464
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,12 +5,12 @@ A performant, type-safe, and **fully customizable** CSS-in-JS theme management l
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
7
7
|
- 🎨 **Modular Theming** - Customize colors, spacing, or any token independently
|
|
8
|
-
- 🎯 **Color Scales** - 20 color
|
|
8
|
+
- 🎯 **Color Scales** - 20 color scales with 12 shades each (25-950)
|
|
9
9
|
- ⚡ **Optimized Performance** - LRU caching, static style deduplication
|
|
10
10
|
- 🖥️ **SSR Support** - Server-side rendering compatible
|
|
11
11
|
- 📦 **Lightweight** - No runtime dependencies besides React
|
|
12
12
|
- 🔒 **Type-safe** - Full TypeScript support with generics
|
|
13
|
-
-
|
|
13
|
+
- 🎨 **Ready to Use** - Default palette with semantic color tokens
|
|
14
14
|
|
|
15
15
|
## Installation
|
|
16
16
|
|
|
@@ -64,21 +64,18 @@ Aurora provides **20 color scales** with **12 shades each** (25, 50, 100, 200, 3
|
|
|
64
64
|
### Usage
|
|
65
65
|
|
|
66
66
|
```tsx
|
|
67
|
-
import { colors
|
|
67
|
+
import { colors } from '@aurora-ds/theme'
|
|
68
68
|
|
|
69
|
-
//
|
|
69
|
+
// Access colors via the colors object
|
|
70
70
|
colors.indigo[500] // '#6366f1'
|
|
71
71
|
colors.emerald[400] // '#34d399'
|
|
72
72
|
colors.gray[900] // '#18181b'
|
|
73
73
|
|
|
74
|
-
//
|
|
75
|
-
indigo[600] // '#4f46e5'
|
|
76
|
-
emerald[50] // '#ecfdf5'
|
|
77
|
-
|
|
78
|
-
// Special values
|
|
74
|
+
// Special values (also via colors)
|
|
79
75
|
colors.white // '#ffffff'
|
|
80
76
|
colors.black // '#000000'
|
|
81
77
|
colors.transparent // 'transparent'
|
|
78
|
+
colors.current // 'currentColor'
|
|
82
79
|
```
|
|
83
80
|
|
|
84
81
|
### Build Custom Theme Colors
|
|
@@ -97,56 +94,58 @@ const myTheme = createTheme(defaultTheme, {
|
|
|
97
94
|
})
|
|
98
95
|
```
|
|
99
96
|
|
|
100
|
-
|
|
97
|
+
### Complete Color Scales Reference
|
|
101
98
|
|
|
102
|
-
|
|
99
|
+
All color scales with their hex values (25-950 shades):
|
|
103
100
|
|
|
104
|
-
|
|
101
|
+
#### Neutrals
|
|
105
102
|
|
|
106
|
-
|
|
103
|
+
| Scale | 25 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 |
|
|
104
|
+
|-------|----|----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|
|
|
105
|
+
| **gray** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
106
|
+
| **slate** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
107
|
+
| **stone** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
107
108
|
|
|
108
|
-
|
|
109
|
-
|---------|-------|----------|----------|
|
|
110
|
-
| `indigo` | Modern, professional | Purple | SaaS, business apps (default) |
|
|
111
|
-
| `blue` | Clean, trustworthy | Sky | Corporate, fintech |
|
|
112
|
-
| `rose` | Warm, friendly | Pink | Social, lifestyle |
|
|
113
|
-
| `emerald` | Fresh, natural | Teal | Health, eco-friendly |
|
|
114
|
-
| `teal` | Balanced, calming | Cyan | Healthcare, wellness |
|
|
115
|
-
| `violet` | Creative, bold | Purple | Creative, gaming |
|
|
116
|
-
| `amber` | Energetic, warm | Orange | Food, education |
|
|
117
|
-
| `cyan` | Tech, modern | Sky | Tech, startups |
|
|
118
|
-
| `slate` | Minimal, corporate | Slate | Enterprise, B2B |
|
|
119
|
-
| `gray` | Ultra minimal | Gray | Portfolios, luxury |
|
|
109
|
+
#### Warm Colors
|
|
120
110
|
|
|
121
|
-
|
|
111
|
+
| Scale | 25 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 |
|
|
112
|
+
|-------|----|----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|
|
|
113
|
+
| **red** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
114
|
+
| **orange** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
115
|
+
| **amber** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
116
|
+
| **yellow** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
122
117
|
|
|
123
|
-
|
|
124
|
-
import {
|
|
125
|
-
palettes,
|
|
126
|
-
blueLight,
|
|
127
|
-
blueDark,
|
|
128
|
-
createTheme,
|
|
129
|
-
defaultTheme
|
|
130
|
-
} from '@aurora-ds/theme'
|
|
118
|
+
#### Green Colors
|
|
131
119
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
120
|
+
| Scale | 25 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 |
|
|
121
|
+
|-------|----|----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|
|
|
122
|
+
| **lime** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
123
|
+
| **green** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
124
|
+
| **emerald** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
125
|
+
| **teal** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
135
126
|
|
|
136
|
-
|
|
137
|
-
const theme = createTheme(defaultTheme, {
|
|
138
|
-
colors: palettes.emerald.light
|
|
139
|
-
})
|
|
127
|
+
#### Blue Colors
|
|
140
128
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
129
|
+
| Scale | 25 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 |
|
|
130
|
+
|-------|----|----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|
|
|
131
|
+
| **cyan** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
132
|
+
| **sky** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
133
|
+
| **blue** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
134
|
+
| **indigo** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
135
|
+
| **violet** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
136
|
+
|
|
137
|
+
#### Purple & Pink Colors
|
|
138
|
+
|
|
139
|
+
| Scale | 25 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 |
|
|
140
|
+
|-------|----|----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|
|
|
141
|
+
| **purple** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
142
|
+
| **fuchsia** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
143
|
+
| **pink** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
144
|
+
| **rose** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
147
145
|
|
|
148
146
|
---
|
|
149
147
|
|
|
148
|
+
|
|
150
149
|
## Modular Customization
|
|
151
150
|
|
|
152
151
|
Customize only what you need - colors, spacing, or any individual token.
|
|
@@ -155,13 +154,11 @@ Customize only what you need - colors, spacing, or any individual token.
|
|
|
155
154
|
|
|
156
155
|
```tsx
|
|
157
156
|
import {
|
|
158
|
-
// Complete
|
|
157
|
+
// Complete theme
|
|
159
158
|
defaultTheme,
|
|
160
|
-
defaultDarkTheme,
|
|
161
159
|
|
|
162
160
|
// Individual presets
|
|
163
|
-
|
|
164
|
-
defaultDarkColors,
|
|
161
|
+
defaultPalette,
|
|
165
162
|
defaultSpacing,
|
|
166
163
|
defaultRadius,
|
|
167
164
|
defaultShadows,
|
|
@@ -170,17 +167,19 @@ import {
|
|
|
170
167
|
defaultLineHeight,
|
|
171
168
|
defaultZIndex,
|
|
172
169
|
defaultTransition,
|
|
170
|
+
defaultOpacity,
|
|
171
|
+
defaultBreakpoints,
|
|
173
172
|
} from '@aurora-ds/theme'
|
|
174
173
|
```
|
|
175
174
|
|
|
176
175
|
### Customize Only Colors
|
|
177
176
|
|
|
178
177
|
```tsx
|
|
179
|
-
import { defaultTheme,
|
|
178
|
+
import { defaultTheme, defaultPalette, createTheme } from '@aurora-ds/theme'
|
|
180
179
|
|
|
181
180
|
const myTheme = createTheme(defaultTheme, {
|
|
182
181
|
colors: {
|
|
183
|
-
...
|
|
182
|
+
...defaultPalette,
|
|
184
183
|
primary: '#your-brand-color',
|
|
185
184
|
primaryHover: '#your-brand-hover',
|
|
186
185
|
},
|
|
@@ -208,13 +207,18 @@ import {
|
|
|
208
207
|
defaultSpacing,
|
|
209
208
|
defaultRadius,
|
|
210
209
|
defaultShadows,
|
|
211
|
-
|
|
210
|
+
colors,
|
|
212
211
|
createTheme,
|
|
213
212
|
defaultTheme,
|
|
214
213
|
} from '@aurora-ds/theme'
|
|
215
214
|
|
|
216
215
|
const myTheme = createTheme(defaultTheme, {
|
|
217
|
-
colors:
|
|
216
|
+
colors: {
|
|
217
|
+
...defaultTheme.colors,
|
|
218
|
+
primary: colors.emerald[600], // Use emerald as primary
|
|
219
|
+
primaryHover: colors.emerald[700],
|
|
220
|
+
primaryActive: colors.emerald[800],
|
|
221
|
+
},
|
|
218
222
|
spacing: defaultSpacing, // Keep default spacing
|
|
219
223
|
radius: {
|
|
220
224
|
...defaultRadius,
|
|
@@ -225,21 +229,204 @@ const myTheme = createTheme(defaultTheme, {
|
|
|
225
229
|
|
|
226
230
|
---
|
|
227
231
|
|
|
232
|
+
## Custom Themes (Complete Token Replacement)
|
|
233
|
+
|
|
234
|
+
Need a completely different color token structure? Aurora supports **full customization** where you can define your own semantic tokens without inheriting `BaseColors`.
|
|
235
|
+
|
|
236
|
+
### Option 1: Replace Mode
|
|
237
|
+
|
|
238
|
+
Use `{ mode: 'replace' }` to completely replace a token category instead of deep-merging:
|
|
239
|
+
|
|
240
|
+
```tsx
|
|
241
|
+
import { createTheme, defaultTheme } from '@aurora-ds/theme'
|
|
242
|
+
|
|
243
|
+
// Replace the entire colors object (no merge with defaults)
|
|
244
|
+
const myTheme = createTheme(defaultTheme, {
|
|
245
|
+
colors: {
|
|
246
|
+
brand: '#007bff',
|
|
247
|
+
brandHover: '#0056b3',
|
|
248
|
+
surface: '#ffffff',
|
|
249
|
+
text: '#212529',
|
|
250
|
+
},
|
|
251
|
+
}, { mode: 'replace' })
|
|
252
|
+
|
|
253
|
+
// Result: theme.colors = { brand, brandHover, surface, text }
|
|
254
|
+
// Note: theme.colors.primary no longer exists!
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
### Option 2: Custom Theme Function
|
|
258
|
+
|
|
259
|
+
For full type safety with your own color tokens, use `createCustomTheme`:
|
|
260
|
+
|
|
261
|
+
```tsx
|
|
262
|
+
import { createCustomTheme } from '@aurora-ds/theme'
|
|
263
|
+
import type { CustomTheme } from '@aurora-ds/theme'
|
|
264
|
+
|
|
265
|
+
// 1. Define your own color token structure
|
|
266
|
+
type MyBrandColors = {
|
|
267
|
+
brand: string
|
|
268
|
+
brandHover: string
|
|
269
|
+
brandActive: string
|
|
270
|
+
surface: string
|
|
271
|
+
surfaceElevated: string
|
|
272
|
+
textPrimary: string
|
|
273
|
+
textSecondary: string
|
|
274
|
+
border: string
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
// 2. Create your theme with full type safety
|
|
278
|
+
const myTheme = createCustomTheme<MyBrandColors>({
|
|
279
|
+
colors: {
|
|
280
|
+
brand: '#007bff',
|
|
281
|
+
brandHover: '#0056b3',
|
|
282
|
+
brandActive: '#004085',
|
|
283
|
+
surface: '#ffffff',
|
|
284
|
+
surfaceElevated: '#f8f9fa',
|
|
285
|
+
textPrimary: '#212529',
|
|
286
|
+
textSecondary: '#6c757d',
|
|
287
|
+
border: '#dee2e6',
|
|
288
|
+
},
|
|
289
|
+
// Other tokens use defaults, or provide your own:
|
|
290
|
+
// spacing: { ... },
|
|
291
|
+
// radius: { ... },
|
|
292
|
+
})
|
|
293
|
+
|
|
294
|
+
// 3. TypeScript knows your exact token structure!
|
|
295
|
+
myTheme.colors.brand // ✅ OK - string
|
|
296
|
+
myTheme.colors.primary // ❌ Error - property doesn't exist
|
|
297
|
+
|
|
298
|
+
// 4. Type your theme for components
|
|
299
|
+
type MyTheme = typeof myTheme
|
|
300
|
+
// or: type MyTheme = CustomTheme<MyBrandColors>
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
### Use Custom Theme in Components
|
|
304
|
+
|
|
305
|
+
```tsx
|
|
306
|
+
import { ThemeProvider, createTypedStyles, useTheme } from '@aurora-ds/theme'
|
|
307
|
+
|
|
308
|
+
// ✨ Create a pre-typed createStyles function ONCE
|
|
309
|
+
export const createStyles = createTypedStyles<MyTheme>()
|
|
310
|
+
|
|
311
|
+
// Now use it everywhere WITHOUT specifying the type!
|
|
312
|
+
const STYLES = createStyles((theme) => ({
|
|
313
|
+
button: {
|
|
314
|
+
backgroundColor: theme.colors.brand, // ✅ TypeScript knows!
|
|
315
|
+
color: theme.colors.textPrimary, // ✅ Works
|
|
316
|
+
// backgroundColor: theme.colors.primary, // ❌ Would error
|
|
317
|
+
},
|
|
318
|
+
}))
|
|
319
|
+
|
|
320
|
+
// Access in components
|
|
321
|
+
function MyComponent() {
|
|
322
|
+
const theme = useTheme<MyTheme>()
|
|
323
|
+
return <div style={{ color: theme.colors.textSecondary }}>Hello</div>
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
// Wrap your app
|
|
327
|
+
<ThemeProvider theme={myTheme}>
|
|
328
|
+
<App />
|
|
329
|
+
</ThemeProvider>
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
### Project Setup (Recommended)
|
|
333
|
+
|
|
334
|
+
Create a `theme.ts` file in your project to centralize your custom theme:
|
|
335
|
+
|
|
336
|
+
```tsx
|
|
337
|
+
// src/theme.ts
|
|
338
|
+
import {
|
|
339
|
+
createCustomTheme,
|
|
340
|
+
createTypedStyles,
|
|
341
|
+
ThemeProvider as BaseThemeProvider,
|
|
342
|
+
useTheme as baseUseTheme,
|
|
343
|
+
} from '@aurora-ds/theme'
|
|
344
|
+
import type { CustomTheme } from '@aurora-ds/theme'
|
|
345
|
+
|
|
346
|
+
// 1. Define your color tokens
|
|
347
|
+
type MyColors = {
|
|
348
|
+
brand: string
|
|
349
|
+
brandHover: string
|
|
350
|
+
brandActive: string
|
|
351
|
+
surface: string
|
|
352
|
+
surfaceElevated: string
|
|
353
|
+
textPrimary: string
|
|
354
|
+
textSecondary: string
|
|
355
|
+
border: string
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
// 2. Create your theme
|
|
359
|
+
export const theme = createCustomTheme<MyColors>({
|
|
360
|
+
colors: {
|
|
361
|
+
brand: '#007bff',
|
|
362
|
+
brandHover: '#0056b3',
|
|
363
|
+
brandActive: '#004085',
|
|
364
|
+
surface: '#ffffff',
|
|
365
|
+
surfaceElevated: '#f8f9fa',
|
|
366
|
+
textPrimary: '#212529',
|
|
367
|
+
textSecondary: '#6c757d',
|
|
368
|
+
border: '#dee2e6',
|
|
369
|
+
},
|
|
370
|
+
})
|
|
371
|
+
|
|
372
|
+
// 3. Export typed utilities (use these throughout your app!)
|
|
373
|
+
export type MyTheme = typeof theme
|
|
374
|
+
export const createStyles = createTypedStyles<MyTheme>()
|
|
375
|
+
export const useTheme = () => baseUseTheme<MyTheme>()
|
|
376
|
+
export const ThemeProvider = BaseThemeProvider
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
Then use in your components:
|
|
380
|
+
|
|
381
|
+
```tsx
|
|
382
|
+
// src/components/Button.tsx
|
|
383
|
+
import { createStyles } from '../theme'
|
|
384
|
+
|
|
385
|
+
// No need to specify <MyTheme> - it's already typed!
|
|
386
|
+
const STYLES = createStyles((theme) => ({
|
|
387
|
+
root: {
|
|
388
|
+
backgroundColor: theme.colors.brand,
|
|
389
|
+
color: theme.colors.textPrimary,
|
|
390
|
+
padding: theme.spacing.md,
|
|
391
|
+
borderRadius: theme.radius.md,
|
|
392
|
+
':hover': {
|
|
393
|
+
backgroundColor: theme.colors.brandHover,
|
|
394
|
+
},
|
|
395
|
+
},
|
|
396
|
+
}))
|
|
397
|
+
|
|
398
|
+
export const Button = ({ children }) => (
|
|
399
|
+
<button className={STYLES.root}>{children}</button>
|
|
400
|
+
)
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
### When to Use Each Approach
|
|
404
|
+
|
|
405
|
+
| Approach | Use Case |
|
|
406
|
+
|----------|----------|
|
|
407
|
+
| `createTheme()` (default merge) | Extend default tokens, keep compatibility |
|
|
408
|
+
| `createTheme()` with `{ mode: 'replace' }` | Quick replacement without type safety |
|
|
409
|
+
| `createCustomTheme<T>()` | Full type safety with custom token structure |
|
|
410
|
+
| `createTypedStyles<T>()` | Pre-type your `createStyles` for DX (recommended with custom themes) |
|
|
411
|
+
|
|
412
|
+
---
|
|
413
|
+
|
|
228
414
|
## Theme Structure
|
|
229
415
|
|
|
230
416
|
### Colors
|
|
231
417
|
|
|
232
418
|
| Token | Description |
|
|
233
419
|
|-------|-------------|
|
|
234
|
-
| `primary`, `
|
|
235
|
-
| `secondary`, `
|
|
236
|
-
| `
|
|
237
|
-
| `
|
|
238
|
-
| `
|
|
239
|
-
| `
|
|
240
|
-
| `
|
|
241
|
-
| `
|
|
242
|
-
| `
|
|
420
|
+
| `primary`, `primaryHover`, `primaryActive`, `primarySubtle`, `primaryDisabled`, `onPrimary` | Primary brand color |
|
|
421
|
+
| `secondary`, `secondaryHover`, `secondaryActive`, `secondarySubtle`, `secondaryDisabled`, `onSecondary` | Secondary actions |
|
|
422
|
+
| `background`, `surface`, `surfaceHover`, `surfaceActive` | Surfaces |
|
|
423
|
+
| `text`, `textSecondary`, `textTertiary` | Text hierarchy |
|
|
424
|
+
| `border` | Borders |
|
|
425
|
+
| `success`, `successSubtle` | Success state |
|
|
426
|
+
| `warning`, `warningSubtle` | Warning state |
|
|
427
|
+
| `error`, `errorHover`, `errorSubtle`, `onError` | Error state |
|
|
428
|
+
| `info`, `infoSubtle` | Info state |
|
|
429
|
+
| `link`, `linkHover`, `linkActive`, `linkDisabled` | Links |
|
|
243
430
|
| `disabled`, `disabledText` | Disabled states |
|
|
244
431
|
|
|
245
432
|
### Spacing
|
|
@@ -247,11 +434,16 @@ const myTheme = createTheme(defaultTheme, {
|
|
|
247
434
|
```tsx
|
|
248
435
|
spacing: {
|
|
249
436
|
none: '0',
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
437
|
+
'2xs': '0.125rem', // 2px
|
|
438
|
+
xs: '0.25rem', // 4px
|
|
439
|
+
sm: '0.5rem', // 8px
|
|
440
|
+
md: '1rem', // 16px
|
|
441
|
+
lg: '1.5rem', // 24px
|
|
442
|
+
xl: '2rem', // 32px
|
|
443
|
+
'2xl': '3rem', // 48px
|
|
444
|
+
'3xl': '4rem', // 64px
|
|
445
|
+
'4xl': '6rem', // 96px
|
|
446
|
+
'5xl': '8rem', // 128px
|
|
255
447
|
}
|
|
256
448
|
```
|
|
257
449
|
|
|
@@ -281,6 +473,7 @@ opacity: {
|
|
|
281
473
|
| `zIndex` | `behind`, `base`, `dropdown`, `sticky`, `overlay`, `modal`, `popover`, `tooltip`, `toast` |
|
|
282
474
|
| `transition` | `fast`, `normal`, `slow` |
|
|
283
475
|
| `opacity` | `none`, `lowest`, `low`, `medium`, `high`, `higher`, `full` |
|
|
476
|
+
| `breakpoints` | `xs`, `sm`, `md`, `lg`, `xl`, `2xl` |
|
|
284
477
|
|
|
285
478
|
---
|
|
286
479
|
|
|
@@ -367,11 +560,14 @@ clearSSRRules() // Reset for next request
|
|
|
367
560
|
| `BaseColors` | Color token type |
|
|
368
561
|
| `BaseSpacing` | Spacing token type |
|
|
369
562
|
| `BaseOpacity` | Opacity token type |
|
|
563
|
+
| `BaseBreakpoints` | Breakpoints token type |
|
|
370
564
|
| `ColorScale` | Color scale type (25-950) |
|
|
371
565
|
| `ColorName` | Union of color scale names |
|
|
372
|
-
| `PaletteName` | Union of palette names |
|
|
373
566
|
| `ExtendTheme<T>` | Helper to extend theme |
|
|
374
567
|
| `DeepPartial<T>` | For partial overrides |
|
|
568
|
+
| `CustomTheme<TColors, ...>` | Generic type for fully custom themes |
|
|
569
|
+
| `CustomThemeBase<TColors>` | Base type for custom color themes |
|
|
570
|
+
| `CreateThemeOptions` | Options for `createTheme()` (`{ mode: 'merge' \| 'replace' }`) |
|
|
375
571
|
|
|
376
572
|
### Components & Hooks
|
|
377
573
|
|
|
@@ -380,44 +576,140 @@ clearSSRRules() // Reset for next request
|
|
|
380
576
|
| `ThemeProvider` | Theme context provider |
|
|
381
577
|
| `useTheme<T>()` | Access current theme |
|
|
382
578
|
|
|
579
|
+
### Theme Creation
|
|
580
|
+
|
|
581
|
+
| Export | Description |
|
|
582
|
+
|--------|-------------|
|
|
583
|
+
| `createTheme(base, overrides, options?)` | Create theme by merging/replacing base with overrides |
|
|
584
|
+
| `createCustomTheme<TColors>(config)` | Create theme with fully custom color tokens |
|
|
585
|
+
| `mergeThemes(base, ...overrides)` | Merge multiple theme overrides |
|
|
586
|
+
| `createThemeVariant(overrides)` | Create a reusable theme variant factory |
|
|
587
|
+
|
|
383
588
|
### Styling
|
|
384
589
|
|
|
385
590
|
| Export | Description |
|
|
386
591
|
|--------|-------------|
|
|
387
592
|
| `createStyles<T>()` | Create themed styles |
|
|
593
|
+
| `createTypedStyles<T>()` | Create a pre-typed `createStyles` function for custom themes |
|
|
388
594
|
| `keyframes()` | CSS keyframe animations |
|
|
389
595
|
| `fontFace()` | @font-face rules |
|
|
390
596
|
| `cssVariables()` | CSS custom properties |
|
|
391
597
|
|
|
392
|
-
|
|
598
|
+
---
|
|
393
599
|
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
600
|
+
## Migration Guide (v1 → v2)
|
|
601
|
+
|
|
602
|
+
Aurora v2 is a **major simplification** focused on flexibility and reduced bundle size. This guide helps you upgrade from v1.x to v2.0.
|
|
603
|
+
|
|
604
|
+
> 📖 **Full migration guide with all details:** [CHANGELOG.md - Migration Guide](./CHANGELOG.md#migration-guide-v1-to-v2)
|
|
605
|
+
|
|
606
|
+
### 🚨 Breaking Changes Summary
|
|
607
|
+
|
|
608
|
+
#### 1. Removed Pre-built Theme Palettes (~40% smaller bundle)
|
|
401
609
|
|
|
402
610
|
```tsx
|
|
403
|
-
|
|
611
|
+
// ❌ v1 - Pre-built palettes (removed)
|
|
612
|
+
import { indigoPalette, bluePalette, defaultDarkTheme } from '@aurora-ds/theme'
|
|
613
|
+
|
|
614
|
+
// ✅ v2 - Build your own with full control
|
|
615
|
+
import { colors, createTheme, defaultTheme } from '@aurora-ds/theme'
|
|
404
616
|
|
|
405
|
-
|
|
406
|
-
|
|
617
|
+
const myTheme = createTheme(defaultTheme, {
|
|
618
|
+
colors: {
|
|
619
|
+
primary: colors.indigo[600],
|
|
620
|
+
primaryHover: colors.indigo[700],
|
|
621
|
+
// ... full control over all tokens
|
|
622
|
+
}
|
|
623
|
+
})
|
|
624
|
+
```
|
|
407
625
|
|
|
408
|
-
|
|
409
|
-
meetsWCAG('#ffffff', '#6366f1', 'AA') // true
|
|
410
|
-
meetsWCAG('#ffffff', '#6366f1', 'AAA') // false
|
|
626
|
+
#### 2. Color Scales Import Restriction
|
|
411
627
|
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
628
|
+
```tsx
|
|
629
|
+
// ❌ v1 - Direct imports (removed for better tree-shaking)
|
|
630
|
+
import { indigo, blue } from '@aurora-ds/theme'
|
|
631
|
+
|
|
632
|
+
// ✅ v2 - Import via colors object only
|
|
633
|
+
import { colors } from '@aurora-ds/theme'
|
|
634
|
+
colors.indigo[500]
|
|
635
|
+
colors.blue[600]
|
|
417
636
|
```
|
|
418
637
|
|
|
419
|
-
|
|
638
|
+
#### 3. Removed WCAG Contrast Utilities
|
|
639
|
+
|
|
640
|
+
```tsx
|
|
641
|
+
// ❌ v1 - Contrast utilities (removed)
|
|
642
|
+
import { getContrastRatio, meetsWCAG } from '@aurora-ds/theme'
|
|
643
|
+
|
|
644
|
+
// ✅ v2 - Use dedicated accessibility tools
|
|
645
|
+
// - polished / color2k (libraries)
|
|
646
|
+
// - axe DevTools (browser extension)
|
|
647
|
+
// - Lighthouse (Chrome DevTools)
|
|
648
|
+
```
|
|
649
|
+
|
|
650
|
+
#### 4. Simplified Color Tokens (83 → 33 tokens, 60% reduction)
|
|
651
|
+
|
|
652
|
+
**Removed color tokens:**
|
|
653
|
+
- ❌ Accent colors (5 tokens): `accent`, `accentHover`, `accentActive`, `onAccent`, `accentSubtle`
|
|
654
|
+
- ❌ Tertiary colors (6 tokens): `tertiary`, `tertiaryHover`, `tertiaryActive`, `onTertiary`, `tertiarySubtle`, `tertiaryDisabled`
|
|
655
|
+
- ❌ Extra surface (2): `elevated`, `overlay`
|
|
656
|
+
- ❌ Extra text (1): `textInverse`
|
|
657
|
+
- ❌ Extra borders (3): `borderHover`, `borderFocus`, `borderSubtle`
|
|
658
|
+
- ❌ Extra semantic (6): `onSuccess`, `successHover`, `onWarning`, `warningHover`, `onInfo`, `infoHover`
|
|
659
|
+
- ❌ Extra interactive (3): `linkVisited`, `linkDisabled`, `focus`
|
|
660
|
+
|
|
661
|
+
**Migration:**
|
|
662
|
+
|
|
663
|
+
```tsx
|
|
664
|
+
// ❌ v1
|
|
665
|
+
theme.colors.accent
|
|
666
|
+
theme.colors.tertiary
|
|
667
|
+
theme.colors.elevated
|
|
668
|
+
|
|
669
|
+
// ✅ v2 - Use existing tokens or extend theme
|
|
670
|
+
theme.colors.primary // Use existing
|
|
671
|
+
theme.colors.secondary // Use existing
|
|
672
|
+
theme.colors.surface // Use existing
|
|
673
|
+
|
|
674
|
+
// OR extend if needed:
|
|
675
|
+
const myTheme = createTheme(defaultTheme, {
|
|
676
|
+
colors: {
|
|
677
|
+
...defaultTheme.colors,
|
|
678
|
+
accent: colors.cyan[500],
|
|
679
|
+
tertiary: colors.violet[500],
|
|
680
|
+
elevated: colors.slate[100],
|
|
681
|
+
}
|
|
682
|
+
})
|
|
683
|
+
```
|
|
684
|
+
|
|
685
|
+
### Quick Migration Steps
|
|
686
|
+
|
|
687
|
+
1. **Replace color scale imports**
|
|
688
|
+
```tsx
|
|
689
|
+
// Before: import { indigo } from '@aurora-ds/theme'
|
|
690
|
+
// After: import { colors } from '@aurora-ds/theme'
|
|
691
|
+
// colors.indigo[500]
|
|
692
|
+
```
|
|
693
|
+
|
|
694
|
+
2. **Replace palette imports** - Build your own theme (see [CHANGELOG](./CHANGELOG.md#3-pre-built-palettes-removed))
|
|
695
|
+
|
|
696
|
+
3. **Replace removed color tokens** - Use existing tokens or extend theme (see [CHANGELOG](./CHANGELOG.md#1-removed-color-tokens))
|
|
697
|
+
|
|
698
|
+
4. **Replace contrast utilities** - Use external tools
|
|
699
|
+
|
|
700
|
+
5. **Test thoroughly**
|
|
701
|
+
```bash
|
|
702
|
+
npm run typecheck # Catch type errors
|
|
703
|
+
npm run build # Ensure no import errors
|
|
704
|
+
npm test # Run tests
|
|
705
|
+
```
|
|
706
|
+
|
|
707
|
+
### Benefits of v2
|
|
420
708
|
|
|
709
|
+
- 📦 **~40% smaller bundle** - Only include what you use
|
|
710
|
+
- 🎯 **More flexible** - Full control over color tokens
|
|
711
|
+
- ⚡ **Better tree-shaking** - Optimized exports
|
|
712
|
+
- 🧩 **Simpler** - Fewer built-in tokens = less decision fatigue
|
|
421
713
|
|
|
422
714
|
## License
|
|
423
715
|
|