@aurora-ds/theme 2.0.1 → 3.1.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.md +117 -642
- package/dist/index.cjs +1 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +56 -720
- package/dist/index.d.ts +56 -720
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,16 +1,14 @@
|
|
|
1
1
|
# Aurora Theme
|
|
2
2
|
|
|
3
|
-
A performant, type-safe, and **fully customizable** CSS-in-JS theme
|
|
3
|
+
A performant, type-safe, and **fully customizable** CSS-in-JS theme library for React.
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
7
|
-
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
- 🖥️ **SSR Support** - Server-side rendering compatible
|
|
7
|
+
- ⚡ **Performant** - LRU caching, static style deduplication
|
|
8
|
+
- 🔒 **Type-safe** - Full TypeScript support with module augmentation
|
|
9
|
+
- 🎨 **Flexible** - Define your own theme structure
|
|
11
10
|
- 📦 **Lightweight** - No runtime dependencies besides React
|
|
12
|
-
|
|
13
|
-
- 🎨 **Ready to Use** - Default palette with semantic color tokens
|
|
11
|
+
|
|
14
12
|
|
|
15
13
|
## Installation
|
|
16
14
|
|
|
@@ -20,78 +18,142 @@ npm install @aurora-ds/theme
|
|
|
20
18
|
|
|
21
19
|
## Quick Start
|
|
22
20
|
|
|
23
|
-
```
|
|
24
|
-
|
|
21
|
+
```typescript
|
|
22
|
+
// theme.ts
|
|
23
|
+
import { createTheme } from '@aurora-ds/theme'
|
|
25
24
|
|
|
26
|
-
// 1.
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
25
|
+
// 1. Define your theme type
|
|
26
|
+
type MyTheme = {
|
|
27
|
+
colors: {
|
|
28
|
+
primary: string
|
|
29
|
+
secondary: string
|
|
30
|
+
background: string
|
|
31
|
+
text: string
|
|
32
|
+
}
|
|
33
|
+
spacing: {
|
|
34
|
+
sm: string
|
|
35
|
+
md: string
|
|
36
|
+
lg: string
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
```typescript
|
|
41
|
+
// 2. Module augmentation (required for autocomplete)
|
|
42
|
+
declare module '@aurora-ds/theme' {
|
|
43
|
+
interface ThemeRegistry {
|
|
44
|
+
theme: MyTheme
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
```typescript
|
|
50
|
+
// 3. Create your themes (type is inferred automatically!)
|
|
51
|
+
export const lightTheme = createTheme({
|
|
52
|
+
colors: {
|
|
53
|
+
primary: '#6366f1',
|
|
54
|
+
secondary: '#64748b',
|
|
55
|
+
background: '#ffffff',
|
|
56
|
+
text: '#09090b',
|
|
57
|
+
},
|
|
58
|
+
spacing: {
|
|
59
|
+
sm: '0.5rem',
|
|
60
|
+
md: '1rem',
|
|
61
|
+
lg: '1.5rem',
|
|
62
|
+
},
|
|
63
|
+
})
|
|
64
|
+
```
|
|
30
65
|
|
|
31
|
-
|
|
32
|
-
|
|
66
|
+
```tsx
|
|
67
|
+
// App.tsx
|
|
68
|
+
import { ThemeProvider, createStyles } from '@aurora-ds/theme'
|
|
69
|
+
import { lightTheme } from './theme'
|
|
70
|
+
|
|
71
|
+
const styles = createStyles((theme) => ({
|
|
33
72
|
container: {
|
|
34
|
-
padding: theme.spacing.md,
|
|
35
|
-
backgroundColor: theme.colors.
|
|
36
|
-
|
|
73
|
+
padding: theme.spacing.md, // ✅ Autocomplete!
|
|
74
|
+
backgroundColor: theme.colors.background,
|
|
75
|
+
color: theme.colors.text,
|
|
37
76
|
},
|
|
77
|
+
button: {
|
|
78
|
+
backgroundColor: theme.colors.primary,
|
|
79
|
+
padding: theme.spacing.sm,
|
|
80
|
+
':hover': {
|
|
81
|
+
opacity: 0.9
|
|
82
|
+
}
|
|
83
|
+
}
|
|
38
84
|
}))
|
|
39
85
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
86
|
+
function App() {
|
|
87
|
+
return (
|
|
88
|
+
<ThemeProvider theme={lightTheme}>
|
|
89
|
+
<div className={styles.container}>
|
|
90
|
+
<button className={styles.button}>Click me</button>
|
|
91
|
+
</div>
|
|
92
|
+
</ThemeProvider>
|
|
93
|
+
)
|
|
43
94
|
}
|
|
44
95
|
```
|
|
45
96
|
|
|
46
|
-
|
|
97
|
+
## API
|
|
47
98
|
|
|
48
|
-
|
|
99
|
+
### `createTheme(values)`
|
|
100
|
+
|
|
101
|
+
Creates a theme. Type is inferred from `ThemeRegistry`.
|
|
49
102
|
|
|
50
|
-
|
|
103
|
+
```typescript
|
|
104
|
+
const theme = createTheme({
|
|
105
|
+
colors: { primary: '#007bff' },
|
|
106
|
+
spacing: { sm: '8px' }
|
|
107
|
+
})
|
|
108
|
+
```
|
|
51
109
|
|
|
52
|
-
###
|
|
110
|
+
### `createStyles((theme) => styles)`
|
|
53
111
|
|
|
54
|
-
|
|
55
|
-
- `gray` - Pure neutral, universal default
|
|
56
|
-
- `slate` - Cool/blue undertone, tech & corporate
|
|
57
|
-
- `stone` - Warm undertone, lifestyle & natural
|
|
112
|
+
Creates CSS classes from a style object.
|
|
58
113
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
114
|
+
```typescript
|
|
115
|
+
const styles = createStyles((theme) => ({
|
|
116
|
+
root: { color: theme.colors.primary }
|
|
117
|
+
}))
|
|
118
|
+
// styles.root → "root-abc123"
|
|
119
|
+
```
|
|
63
120
|
|
|
64
|
-
###
|
|
121
|
+
### `useTheme()`
|
|
122
|
+
|
|
123
|
+
Hook to access the current theme in components.
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
function Component() {
|
|
127
|
+
const theme = useTheme()
|
|
128
|
+
return <div style={{ color: theme.colors.primary }} />
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### `ThemeProvider`
|
|
133
|
+
|
|
134
|
+
Provides the theme to your app.
|
|
65
135
|
|
|
66
136
|
```tsx
|
|
137
|
+
<ThemeProvider theme={myTheme}>
|
|
138
|
+
<App />
|
|
139
|
+
</ThemeProvider>
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
## Color Scales
|
|
146
|
+
|
|
147
|
+
Aurora provides **color scales** with **12 shades each** (25, 50, 100-900, 950).
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
67
150
|
import { colors } from '@aurora-ds/theme'
|
|
68
151
|
|
|
69
|
-
// Access colors via the colors object
|
|
70
152
|
colors.indigo[500] // '#6366f1'
|
|
71
153
|
colors.emerald[400] // '#34d399'
|
|
72
154
|
colors.gray[900] // '#18181b'
|
|
73
|
-
|
|
74
|
-
// Special values (also via colors)
|
|
75
155
|
colors.white // '#ffffff'
|
|
76
156
|
colors.black // '#000000'
|
|
77
|
-
colors.transparent // 'transparent'
|
|
78
|
-
colors.current // 'currentColor'
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
### Build Custom Theme Colors
|
|
82
|
-
|
|
83
|
-
```tsx
|
|
84
|
-
import { colors, defaultTheme, createTheme } from '@aurora-ds/theme'
|
|
85
|
-
|
|
86
|
-
const myTheme = createTheme(defaultTheme, {
|
|
87
|
-
colors: {
|
|
88
|
-
primary: colors.purple[500],
|
|
89
|
-
primaryHover: colors.purple[600],
|
|
90
|
-
primaryActive: colors.purple[700],
|
|
91
|
-
primarySubtle: colors.purple[50],
|
|
92
|
-
// ... other colors
|
|
93
|
-
}
|
|
94
|
-
})
|
|
95
157
|
```
|
|
96
158
|
|
|
97
159
|
### Complete Color Scales Reference
|
|
@@ -105,615 +167,28 @@ All color scales with their hex values (25-950 shades):
|
|
|
105
167
|
| **gray** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
106
168
|
| **slate** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
107
169
|
| **stone** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
108
|
-
|
|
109
|
-
#### Warm Colors
|
|
110
|
-
|
|
111
|
-
| Scale | 25 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 |
|
|
112
|
-
|-------|----|----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|
|
|
113
170
|
| **red** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
114
171
|
| **orange** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
115
172
|
| **amber** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
116
173
|
| **yellow** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
117
|
-
|
|
118
|
-
#### Green Colors
|
|
119
|
-
|
|
120
|
-
| Scale | 25 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 |
|
|
121
|
-
|-------|----|----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|
|
|
122
174
|
| **lime** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
123
175
|
| **green** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
124
176
|
| **emerald** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
125
177
|
| **teal** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
126
|
-
|
|
127
|
-
#### Blue Colors
|
|
128
|
-
|
|
129
|
-
| Scale | 25 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 |
|
|
130
|
-
|-------|----|----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|
|
|
131
178
|
| **cyan** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
132
|
-
| **sky** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
133
179
|
| **blue** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
134
180
|
| **indigo** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
135
181
|
| **violet** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
136
|
-
|
|
137
|
-
#### Purple & Pink Colors
|
|
138
|
-
|
|
139
|
-
| Scale | 25 | 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950 |
|
|
140
|
-
|-------|----|----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|
|
|
141
182
|
| **purple** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
142
183
|
| **fuchsia** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
143
184
|
| **pink** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
144
185
|
| **rose** |  |  |  |  |  |  |  |  |  |  |  |  |
|
|
145
186
|
|
|
146
|
-
---
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
## Modular Customization
|
|
150
|
-
|
|
151
|
-
Customize only what you need - colors, spacing, or any individual token.
|
|
152
|
-
|
|
153
|
-
### Available Presets
|
|
154
|
-
|
|
155
|
-
```tsx
|
|
156
|
-
import {
|
|
157
|
-
// Complete theme
|
|
158
|
-
defaultTheme,
|
|
159
|
-
|
|
160
|
-
// Individual presets
|
|
161
|
-
defaultPalette,
|
|
162
|
-
defaultSpacing,
|
|
163
|
-
defaultRadius,
|
|
164
|
-
defaultShadows,
|
|
165
|
-
defaultFontSize,
|
|
166
|
-
defaultFontWeight,
|
|
167
|
-
defaultLineHeight,
|
|
168
|
-
defaultZIndex,
|
|
169
|
-
defaultTransition,
|
|
170
|
-
defaultOpacity,
|
|
171
|
-
defaultBreakpoints,
|
|
172
|
-
} from '@aurora-ds/theme'
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
### Customize Only Colors
|
|
176
|
-
|
|
177
|
-
```tsx
|
|
178
|
-
import { defaultTheme, defaultPalette, createTheme } from '@aurora-ds/theme'
|
|
179
|
-
|
|
180
|
-
const myTheme = createTheme(defaultTheme, {
|
|
181
|
-
colors: {
|
|
182
|
-
...defaultPalette,
|
|
183
|
-
primary: '#your-brand-color',
|
|
184
|
-
primaryHover: '#your-brand-hover',
|
|
185
|
-
},
|
|
186
|
-
})
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
### Customize Only Spacing
|
|
190
|
-
|
|
191
|
-
```tsx
|
|
192
|
-
import { defaultTheme, defaultSpacing, createTheme } from '@aurora-ds/theme'
|
|
193
|
-
|
|
194
|
-
const myTheme = createTheme(defaultTheme, {
|
|
195
|
-
spacing: {
|
|
196
|
-
...defaultSpacing,
|
|
197
|
-
md: '1.25rem', // Override medium
|
|
198
|
-
lg: '2rem', // Override large
|
|
199
|
-
},
|
|
200
|
-
})
|
|
201
|
-
```
|
|
202
|
-
|
|
203
|
-
### Mix and Match
|
|
204
|
-
|
|
205
|
-
```tsx
|
|
206
|
-
import {
|
|
207
|
-
defaultSpacing,
|
|
208
|
-
defaultRadius,
|
|
209
|
-
defaultShadows,
|
|
210
|
-
colors,
|
|
211
|
-
createTheme,
|
|
212
|
-
defaultTheme,
|
|
213
|
-
} from '@aurora-ds/theme'
|
|
214
|
-
|
|
215
|
-
const myTheme = createTheme(defaultTheme, {
|
|
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
|
-
},
|
|
222
|
-
spacing: defaultSpacing, // Keep default spacing
|
|
223
|
-
radius: {
|
|
224
|
-
...defaultRadius,
|
|
225
|
-
md: '8px', // More rounded
|
|
226
|
-
},
|
|
227
|
-
})
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
---
|
|
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
|
-
|
|
414
|
-
## Theme Structure
|
|
415
|
-
|
|
416
|
-
### Colors
|
|
417
|
-
|
|
418
|
-
| Token | Description |
|
|
419
|
-
|-------|-------------|
|
|
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 |
|
|
430
|
-
| `disabled`, `disabledText` | Disabled states |
|
|
431
|
-
|
|
432
|
-
### Spacing
|
|
433
|
-
|
|
434
|
-
```tsx
|
|
435
|
-
spacing: {
|
|
436
|
-
none: '0',
|
|
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
|
|
447
|
-
}
|
|
448
|
-
```
|
|
449
|
-
|
|
450
|
-
### Opacity
|
|
451
|
-
|
|
452
|
-
```tsx
|
|
453
|
-
opacity: {
|
|
454
|
-
none: 0, // Fully transparent
|
|
455
|
-
lowest: 0.05, // Very subtle
|
|
456
|
-
low: 0.1, // Subtle
|
|
457
|
-
medium: 0.25, // Noticeable
|
|
458
|
-
high: 0.5, // Semi-transparent
|
|
459
|
-
higher: 0.75, // Mostly opaque
|
|
460
|
-
full: 1, // Fully opaque
|
|
461
|
-
}
|
|
462
|
-
```
|
|
463
|
-
|
|
464
|
-
### Other Tokens
|
|
465
|
-
|
|
466
|
-
| Token | Values |
|
|
467
|
-
|-------|--------|
|
|
468
|
-
| `radius` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `full` |
|
|
469
|
-
| `shadows` | `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `inner`, `focus` |
|
|
470
|
-
| `fontSize` | `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl` |
|
|
471
|
-
| `fontWeight` | `light`, `regular`, `medium`, `semibold`, `bold` |
|
|
472
|
-
| `lineHeight` | `none`, `tight`, `normal`, `relaxed`, `loose` |
|
|
473
|
-
| `zIndex` | `behind`, `base`, `dropdown`, `sticky`, `overlay`, `modal`, `popover`, `tooltip`, `toast` |
|
|
474
|
-
| `transition` | `fast`, `normal`, `slow` |
|
|
475
|
-
| `opacity` | `none`, `lowest`, `low`, `medium`, `high`, `higher`, `full` |
|
|
476
|
-
| `breakpoints` | `xs`, `sm`, `md`, `lg`, `xl`, `2xl` |
|
|
477
|
-
|
|
478
|
-
---
|
|
479
|
-
|
|
480
|
-
## Extending Types
|
|
481
|
-
|
|
482
|
-
Add custom tokens with full TypeScript support:
|
|
483
|
-
|
|
484
|
-
```tsx
|
|
485
|
-
import type { BaseColors, ExtendTheme } from '@aurora-ds/theme'
|
|
486
|
-
|
|
487
|
-
// Extend colors
|
|
488
|
-
type MyColors = BaseColors & {
|
|
489
|
-
brand: string
|
|
490
|
-
brandHover: string
|
|
491
|
-
}
|
|
492
|
-
|
|
493
|
-
// Create extended theme type
|
|
494
|
-
type MyTheme = ExtendTheme<{
|
|
495
|
-
colors: MyColors
|
|
496
|
-
}>
|
|
497
|
-
|
|
498
|
-
// Use with type safety
|
|
499
|
-
const STYLES = createStyles<MyTheme>((theme) => ({
|
|
500
|
-
button: {
|
|
501
|
-
backgroundColor: theme.colors.brand, // ✅ TypeScript knows this!
|
|
502
|
-
},
|
|
503
|
-
}))
|
|
504
|
-
|
|
505
|
-
// Access in components
|
|
506
|
-
const theme = useTheme<MyTheme>()
|
|
507
|
-
```
|
|
508
|
-
|
|
509
|
-
---
|
|
510
|
-
|
|
511
|
-
## Dynamic Styles
|
|
512
|
-
|
|
513
|
-
```tsx
|
|
514
|
-
const STYLES = createStyles((theme) => ({
|
|
515
|
-
button: (variant: 'primary' | 'secondary', size: 'sm' | 'md' | 'lg') => ({
|
|
516
|
-
backgroundColor: theme.colors[variant],
|
|
517
|
-
padding: theme.spacing[size],
|
|
518
|
-
borderRadius: theme.radius.md,
|
|
519
|
-
transition: theme.transition.fast,
|
|
520
|
-
}),
|
|
521
|
-
}))
|
|
522
|
-
|
|
523
|
-
// Usage
|
|
524
|
-
<button className={STYLES.button('primary', 'md')}>Click me</button>
|
|
525
187
|
```
|
|
526
|
-
|
|
527
|
-
---
|
|
528
|
-
|
|
529
|
-
## SSR Support
|
|
530
|
-
|
|
531
|
-
```tsx
|
|
532
|
-
import { getSSRStyles, clearSSRRules } from '@aurora-ds/theme'
|
|
533
|
-
|
|
534
|
-
// Server-side
|
|
535
|
-
const html = renderToString(<App />)
|
|
536
|
-
const styles = getSSRStyles()
|
|
537
|
-
|
|
538
|
-
const fullHtml = `
|
|
539
|
-
<!DOCTYPE html>
|
|
540
|
-
<html>
|
|
541
|
-
<head>
|
|
542
|
-
<style id="aurora-styles">${styles}</style>
|
|
543
|
-
</head>
|
|
544
|
-
<body>${html}</body>
|
|
545
|
-
</html>
|
|
546
|
-
`
|
|
547
|
-
|
|
548
|
-
clearSSRRules() // Reset for next request
|
|
549
188
|
```
|
|
550
189
|
|
|
551
190
|
---
|
|
552
191
|
|
|
553
|
-
## API Reference
|
|
554
|
-
|
|
555
|
-
### Types
|
|
556
|
-
|
|
557
|
-
| Type | Description |
|
|
558
|
-
|------|-------------|
|
|
559
|
-
| `Theme` | Complete theme structure |
|
|
560
|
-
| `BaseColors` | Color token type |
|
|
561
|
-
| `BaseSpacing` | Spacing token type |
|
|
562
|
-
| `BaseOpacity` | Opacity token type |
|
|
563
|
-
| `BaseBreakpoints` | Breakpoints token type |
|
|
564
|
-
| `ColorScale` | Color scale type (25-950) |
|
|
565
|
-
| `ColorName` | Union of color scale names |
|
|
566
|
-
| `ExtendTheme<T>` | Helper to extend theme |
|
|
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' }`) |
|
|
571
|
-
|
|
572
|
-
### Components & Hooks
|
|
573
|
-
|
|
574
|
-
| Export | Description |
|
|
575
|
-
|--------|-------------|
|
|
576
|
-
| `ThemeProvider` | Theme context provider |
|
|
577
|
-
| `useTheme<T>()` | Access current theme |
|
|
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
|
-
|
|
588
|
-
### Styling
|
|
589
|
-
|
|
590
|
-
| Export | Description |
|
|
591
|
-
|--------|-------------|
|
|
592
|
-
| `createStyles<T>()` | Create themed styles |
|
|
593
|
-
| `createTypedStyles<T>()` | Create a pre-typed `createStyles` function for custom themes |
|
|
594
|
-
| `keyframes()` | CSS keyframe animations |
|
|
595
|
-
| `fontFace()` | @font-face rules |
|
|
596
|
-
| `cssVariables()` | CSS custom properties |
|
|
597
|
-
|
|
598
|
-
---
|
|
599
|
-
|
|
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)
|
|
609
|
-
|
|
610
|
-
```tsx
|
|
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'
|
|
616
|
-
|
|
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
|
-
```
|
|
625
|
-
|
|
626
|
-
#### 2. Color Scales Import Restriction
|
|
627
|
-
|
|
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]
|
|
636
|
-
```
|
|
637
|
-
|
|
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
|
|
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
|
|
713
|
-
|
|
714
192
|
## License
|
|
715
193
|
|
|
716
194
|
MIT
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|