@beam-ui/design-tokens 1.0.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/CHANGELOG.md +13 -1
- package/LICENSE +21 -0
- package/README.md +240 -319
- package/build/base/tokens.es6.js +9 -6
- package/build/base/tokens.json +9 -6
- package/build/base/variables.css +7 -6
- package/build/semantic/tokens.es6.js +46 -16
- package/build/semantic/tokens.json +39 -16
- package/build/semantic/variables.css +29 -8
- package/package.json +10 -7
- package/USAGE.md +0 -286
package/README.md
CHANGED
|
@@ -1,394 +1,315 @@
|
|
|
1
1
|
# Beam UI Design Tokens
|
|
2
2
|
|
|
3
|
-
A centralized collection of design decisions and other artifacts for the Beam UI Design System.
|
|
4
|
-
|
|
5
|
-
> **For usage and consumption documentation**, see [USAGE.md](./USAGE.md) (included in the npm package).
|
|
3
|
+
A centralized collection of design decisions and other artifacts for the Beam UI Design System.
|
|
6
4
|
|
|
7
5
|
## Overview
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
Design tokens are the visual design atoms — specifically, they are named entities that store various design decisions. This package provides these tokens in multiple formats for consistent use across applications.
|
|
10
8
|
|
|
11
9
|
## Installation
|
|
12
10
|
|
|
13
11
|
```bash
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
## Building Tokens
|
|
19
|
-
|
|
20
|
-
To build the design tokens into all output formats:
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
yarn build
|
|
12
|
+
npm install @beam-ui/design-tokens
|
|
13
|
+
# or
|
|
14
|
+
yarn add @beam-ui/design-tokens
|
|
24
15
|
```
|
|
25
16
|
|
|
26
|
-
|
|
27
|
-
- **CSS Variables** (`variables.css`)
|
|
28
|
-
- **JavaScript ES6** (`tokens.es6.js`)
|
|
29
|
-
- **JSON** (`tokens.json`)
|
|
17
|
+
## Available Output Formats
|
|
30
18
|
|
|
31
|
-
All
|
|
32
|
-
- `
|
|
33
|
-
-
|
|
34
|
-
- `
|
|
35
|
-
- `build/{brand}/base/` - Brand-specific base tokens (if custom brands exist)
|
|
36
|
-
- `build/{brand}/semantic/` - Brand-specific semantic tokens (if custom brands exist)
|
|
19
|
+
All tokens are available in three formats:
|
|
20
|
+
- **CSS Variables** (`variables.css`) - CSS custom properties
|
|
21
|
+
- **JavaScript ES6** (`tokens.es6.js`) - ES6 module exports
|
|
22
|
+
- **JSON** (`tokens.json`) - Nested JSON structure
|
|
37
23
|
|
|
38
|
-
## Token
|
|
39
|
-
|
|
40
|
-
### Source Organization
|
|
24
|
+
## Token Layers
|
|
41
25
|
|
|
42
26
|
Tokens are organized in three layers:
|
|
43
27
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
- `a11y.js` - Accessibility-related tokens (touch target sizes, etc.)
|
|
28
|
+
- **`build/globals/`** - Global tokens (breakpoints, accessibility, etc.)
|
|
29
|
+
- **`build/base/`** - Default base tokens (colors, fonts, spacing, etc.)
|
|
30
|
+
- **`build/semantic/`** - Default semantic tokens (buttons, typography, etc.)
|
|
48
31
|
|
|
49
|
-
|
|
50
|
-
Default foundation design values:
|
|
51
|
-
- `color.js` - Color palette including brand colors, color scales, and utility colors
|
|
52
|
-
- `font.js` - Font families, sizes, line heights, letter spacing
|
|
53
|
-
- `spacing.js` - Spacing scale
|
|
54
|
-
- `border.js` - Border radius and width values
|
|
32
|
+
Brand-specific tokens can be found at `build/{brand}/base/` and `build/{brand}/semantic/` if custom brands exist.
|
|
55
33
|
|
|
56
|
-
|
|
57
|
-
Default component-specific tokens that reference base tokens:
|
|
58
|
-
- `color.js` - Semantic color assignments (text, background, border, icon, status, etc.)
|
|
59
|
-
- `typography.js` - Typography styles (headings, body text, captions, etc.)
|
|
60
|
-
- `button.js` - Button component tokens (variants, states, sizes, etc.)
|
|
34
|
+
## Usage
|
|
61
35
|
|
|
62
|
-
|
|
63
|
-
Optional brand overrides following the same base/semantic structure
|
|
36
|
+
### Using CSS Variables
|
|
64
37
|
|
|
65
|
-
|
|
38
|
+
#### Important: Semantic Tokens Require Base and Global Tokens
|
|
66
39
|
|
|
67
|
-
|
|
68
|
-
- `value` - The token value (can be a literal value or reference to another token)
|
|
69
|
-
- `type` - The token type (color, dimension, fontSize, fontFamily, etc.)
|
|
40
|
+
**Semantic CSS tokens reference base and global tokens using CSS custom properties (`var()`)**, which means you must import all token files in the correct order for semantic tokens to work correctly.
|
|
70
41
|
|
|
71
|
-
|
|
72
|
-
```javascript
|
|
73
|
-
export default {
|
|
74
|
-
color: {
|
|
75
|
-
'tatari-red': {
|
|
76
|
-
value: 'hsl(2, 72%, 46%)',
|
|
77
|
-
type: 'color'
|
|
78
|
-
},
|
|
79
|
-
gray: {
|
|
80
|
-
black: {
|
|
81
|
-
value: 'hsl(0, 0%, 0%)',
|
|
82
|
-
type: 'color'
|
|
83
|
-
}
|
|
84
|
-
}
|
|
85
|
-
}
|
|
86
|
-
};
|
|
87
|
-
```
|
|
42
|
+
#### Recommended Import Order
|
|
88
43
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
background: {
|
|
95
|
-
value: '{color.gray.black}', // References base token
|
|
96
|
-
type: 'color'
|
|
97
|
-
}
|
|
98
|
-
}
|
|
99
|
-
}
|
|
100
|
-
};
|
|
44
|
+
```css
|
|
45
|
+
/* Import in this order: */
|
|
46
|
+
@import '@beam-ui/design-tokens/build/globals/variables.css';
|
|
47
|
+
@import '@beam-ui/design-tokens/build/base/variables.css';
|
|
48
|
+
@import '@beam-ui/design-tokens/build/semantic/variables.css';
|
|
101
49
|
```
|
|
102
50
|
|
|
103
|
-
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
// ❌ Incorrect (CSS Color Level 4 slash syntax not supported)
|
|
109
|
-
value: 'hsl(0 0% 0% / 0.3)'
|
|
51
|
+
Or in your HTML:
|
|
52
|
+
```html
|
|
53
|
+
<link rel="stylesheet" href="node_modules/@beam-ui/design-tokens/build/globals/variables.css">
|
|
54
|
+
<link rel="stylesheet" href="node_modules/@beam-ui/design-tokens/build/base/variables.css">
|
|
55
|
+
<link rel="stylesheet" href="node_modules/@beam-ui/design-tokens/build/semantic/variables.css">
|
|
110
56
|
```
|
|
111
57
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
### 1. Create or edit token files
|
|
58
|
+
#### Why All Three Files Are Required
|
|
115
59
|
|
|
116
|
-
|
|
60
|
+
Tokens use `var()` references to maintain relationships across all layers:
|
|
117
61
|
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
62
|
+
```css
|
|
63
|
+
/* 1. Global tokens define shared values */
|
|
64
|
+
:root {
|
|
65
|
+
--breakpoint-medium: 768px;
|
|
66
|
+
--a11y-min-touch-target: 40px;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/* 2. Base tokens define the actual brand values */
|
|
70
|
+
:root {
|
|
71
|
+
--color-gray-black: hsl(0, 0%, 0%);
|
|
72
|
+
--color-gray-white: hsl(0, 0%, 100%);
|
|
73
|
+
--color-transparent: hsla(0, 0%, 0%, 0);
|
|
74
|
+
--font-size-medium: 1.6rem;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/* 3. Semantic tokens reference base and global tokens */
|
|
78
|
+
:root {
|
|
79
|
+
--button-primary-background: var(--color-gray-black);
|
|
80
|
+
--button-primary-text: var(--color-gray-white);
|
|
81
|
+
--button-tertiary-border: var(--color-transparent);
|
|
82
|
+
--button-primary-font-size: var(--font-size-medium);
|
|
83
|
+
--button-size-sm-min-width: var(--a11y-min-touch-target);
|
|
84
|
+
}
|
|
134
85
|
```
|
|
135
86
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
Check the generated files in `build/base/` and `build/semantic/` to ensure your tokens are correctly transformed.
|
|
139
|
-
|
|
140
|
-
## Build Architecture
|
|
141
|
-
|
|
142
|
-
The build system separates tokens into three categories:
|
|
143
|
-
|
|
144
|
-
### Global Tokens
|
|
145
|
-
- Shared across all brands
|
|
146
|
-
- Responsive breakpoints, accessibility values
|
|
147
|
-
- Output: `build/globals/`
|
|
148
|
-
- Available for reference by brand tokens
|
|
149
|
-
|
|
150
|
-
### Base Tokens
|
|
151
|
-
- Default foundation values (colors, spacing, fonts, borders)
|
|
152
|
-
- No component-specific tokens
|
|
153
|
-
- Output: `build/base/`
|
|
154
|
-
- Used as references by semantic tokens
|
|
87
|
+
#### Benefits of This Approach
|
|
155
88
|
|
|
156
|
-
|
|
157
|
-
-
|
|
158
|
-
-
|
|
159
|
-
-
|
|
160
|
-
- **CSS format uses `var()` references** - maintains relationships with base tokens
|
|
161
|
-
- **JS/JSON formats use resolved values** - self-contained for programmatic use
|
|
89
|
+
- **Single source of truth** - Update base token values and all semantic tokens automatically reflect the change
|
|
90
|
+
- **Smaller file sizes** - References are more efficient than duplicated values
|
|
91
|
+
- **Runtime flexibility** - Override base tokens to theme entire components
|
|
92
|
+
- **Maintainability** - Clear relationships between foundation and application layers
|
|
162
93
|
|
|
163
|
-
|
|
164
|
-
- Custom brand overrides can be added to `src/tokens/brands/{brand}/`
|
|
165
|
-
- Automatically detected and built to `build/{brand}/base/` and `build/{brand}/semantic/`
|
|
166
|
-
- Follow the same structure as default tokens
|
|
94
|
+
#### Using Only Base Tokens
|
|
167
95
|
|
|
168
|
-
|
|
96
|
+
If you only need base tokens (colors, spacing, fonts) without semantic tokens, you can import just the base and global files:
|
|
169
97
|
|
|
170
|
-
**CSS Output:**
|
|
171
98
|
```css
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
99
|
+
@import '@beam-ui/design-tokens/build/globals/variables.css';
|
|
100
|
+
@import '@beam-ui/design-tokens/build/base/variables.css';
|
|
101
|
+
|
|
102
|
+
.custom-button {
|
|
103
|
+
background-color: var(--color-gray-black);
|
|
104
|
+
padding: var(--spacing-medium);
|
|
105
|
+
font-size: var(--font-size-medium);
|
|
106
|
+
min-height: var(--a11y-min-touch-target);
|
|
107
|
+
}
|
|
180
108
|
```
|
|
181
109
|
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
The build system uses transforms that:
|
|
185
|
-
- **Remove the 'brand' keyword** from token paths for cleaner names
|
|
186
|
-
- **Convert colors** - Uses `color/hsl` for CSS and JS/JSON
|
|
187
|
-
- **Maintain sizes in rem units** - Using the `size/rem` transform
|
|
188
|
-
- **Apply naming conventions** per platform:
|
|
189
|
-
- **CSS:** kebab-case (`--color-tatari-red`)
|
|
190
|
-
- **JavaScript:** camelCase (`colorTatariRed`)
|
|
191
|
-
- **JSON:** kebab-case nested structure
|
|
192
|
-
|
|
193
|
-
### Custom Transforms
|
|
194
|
-
|
|
195
|
-
Located in `src/transforms/`:
|
|
196
|
-
- `name-kebab-no-brand.js` - Converts names to kebab-case and removes 'brand' from path
|
|
197
|
-
- `name-camel-no-brand.js` - Converts names to camelCase and removes 'brand' from path
|
|
110
|
+
**Note:** Base tokens may reference global tokens (like accessibility values), so it's recommended to include globals even when not using semantic tokens.
|
|
198
111
|
|
|
199
|
-
|
|
112
|
+
### Using JavaScript/TypeScript Tokens
|
|
200
113
|
|
|
201
|
-
|
|
114
|
+
JavaScript and JSON formats output resolved values, so semantic tokens can be used independently:
|
|
202
115
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
- Brand builds contain only brand-specific tokens
|
|
207
|
-
- Clean separation between global and brand-specific layers
|
|
208
|
-
|
|
209
|
-
### semantic-only
|
|
210
|
-
Filters tokens to include only those defined in the `semantic/` directory. This ensures:
|
|
211
|
-
- Base tokens are available for references (CSS uses `var()`, JS/JSON resolve values)
|
|
212
|
-
- Semantic build contains only component-specific tokens
|
|
213
|
-
- Clean separation between foundation and application layers
|
|
214
|
-
|
|
215
|
-
Located in `src/filters/`:
|
|
216
|
-
- `brand-only.js`
|
|
217
|
-
- `semantic-only.js`
|
|
218
|
-
|
|
219
|
-
## Adding a New Brand
|
|
116
|
+
```javascript
|
|
117
|
+
// Semantic tokens contain resolved values
|
|
118
|
+
import { buttonPrimaryBackground, buttonPrimaryText } from '@beam-ui/design-tokens/build/semantic/tokens.es6.js';
|
|
220
119
|
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
120
|
+
const button = {
|
|
121
|
+
backgroundColor: buttonPrimaryBackground, // "hsl(0, 0%, 0%)"
|
|
122
|
+
color: buttonPrimaryText // "hsl(0, 0%, 100%)"
|
|
123
|
+
};
|
|
225
124
|
```
|
|
226
125
|
|
|
227
|
-
|
|
126
|
+
#### Importing Base Tokens
|
|
228
127
|
|
|
229
|
-
|
|
128
|
+
```javascript
|
|
129
|
+
import { colorGrayBlack, fontSizeMedium, spacingLarge } from '@beam-ui/design-tokens/build/base/tokens.es6.js';
|
|
230
130
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
131
|
+
const styles = {
|
|
132
|
+
color: colorGrayBlack, // "hsl(0, 0%, 0%)"
|
|
133
|
+
fontSize: fontSizeMedium, // "1.6rem"
|
|
134
|
+
padding: spacingLarge // "2.4rem"
|
|
135
|
+
};
|
|
234
136
|
```
|
|
235
137
|
|
|
236
|
-
|
|
138
|
+
#### Importing Global Tokens
|
|
237
139
|
|
|
238
|
-
|
|
140
|
+
```javascript
|
|
141
|
+
import { breakpointMedium, a11yMinTouchTarget } from '@beam-ui/design-tokens/build/globals/tokens.es6.js';
|
|
239
142
|
|
|
143
|
+
const config = {
|
|
144
|
+
breakpoint: breakpointMedium, // "768px"
|
|
145
|
+
minTouchSize: a11yMinTouchTarget // "40px"
|
|
146
|
+
};
|
|
240
147
|
```
|
|
241
|
-
design-tokens/
|
|
242
|
-
├── .changeset/ # Changeset files for version management
|
|
243
|
-
├── build/ # Generated output files (git-ignored)
|
|
244
|
-
│ ├── globals/ # Global tokens output
|
|
245
|
-
│ │ ├── variables.css
|
|
246
|
-
│ │ ├── tokens.es6.js
|
|
247
|
-
│ │ └── tokens.json
|
|
248
|
-
│ ├── base/ # Default base tokens output
|
|
249
|
-
│ │ ├── variables.css
|
|
250
|
-
│ │ ├── tokens.es6.js
|
|
251
|
-
│ │ └── tokens.json
|
|
252
|
-
│ └── semantic/ # Default semantic tokens output
|
|
253
|
-
│ ├── variables.css
|
|
254
|
-
│ ├── tokens.es6.js
|
|
255
|
-
│ └── tokens.json
|
|
256
|
-
├── src/ # Source files
|
|
257
|
-
│ ├── tokens/ # Token definitions
|
|
258
|
-
│ │ ├── base/ # Default base tokens
|
|
259
|
-
│ │ │ ├── color.js
|
|
260
|
-
│ │ │ ├── font.js
|
|
261
|
-
│ │ │ ├── spacing.js
|
|
262
|
-
│ │ │ └── border.js
|
|
263
|
-
│ │ ├── semantic/ # Default semantic tokens
|
|
264
|
-
│ │ │ ├── color.js
|
|
265
|
-
│ │ │ ├── typography.js
|
|
266
|
-
│ │ │ └── button.js
|
|
267
|
-
│ │ ├── brands/ # Optional brand overrides (empty by default)
|
|
268
|
-
│ │ └── globals/ # Global tokens
|
|
269
|
-
│ │ ├── breakpoints.js
|
|
270
|
-
│ │ └── a11y.js
|
|
271
|
-
│ ├── transforms/ # Custom transforms
|
|
272
|
-
│ │ ├── name-kebab-no-brand.js
|
|
273
|
-
│ │ ├── name-camel-no-brand.js
|
|
274
|
-
│ │ └── index.js
|
|
275
|
-
│ └── filters/ # Custom filters
|
|
276
|
-
│ ├── brand-only.js
|
|
277
|
-
│ ├── semantic-only.js
|
|
278
|
-
│ └── index.js
|
|
279
|
-
├── build.js # Style Dictionary configuration
|
|
280
|
-
├── package.json
|
|
281
|
-
├── CHANGELOG.md # Auto-generated changelog
|
|
282
|
-
├── USAGE.md # Usage documentation (included in npm package)
|
|
283
|
-
└── README.md # This file (development documentation)
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
## Scripts
|
|
287
|
-
|
|
288
|
-
- `yarn build` - Build all design tokens
|
|
289
|
-
- `yarn clean` - Remove all generated files
|
|
290
|
-
- `yarn prepublishOnly` - Clean and rebuild before publishing to npm
|
|
291
|
-
- `yarn changeset` - Create a new changeset to document your changes
|
|
292
|
-
- `yarn version` - Apply changesets and update version/changelog
|
|
293
|
-
- `yarn release` - Publish updated packages to npm
|
|
294
|
-
|
|
295
|
-
## Configuration
|
|
296
|
-
|
|
297
|
-
### build.js
|
|
298
|
-
|
|
299
|
-
The build configuration defines:
|
|
300
|
-
- **Transform groups** - Collections of transforms for each output format (CSS, JS, JSON)
|
|
301
|
-
- **Platform configs** - Output format specifications and file destinations
|
|
302
|
-
- **Filter application** - Which tokens to include in each build
|
|
303
|
-
- **Reference handling** - CSS uses `outputReferences: true` to preserve token relationships
|
|
304
|
-
|
|
305
|
-
Key functions:
|
|
306
|
-
- `getGlobalsTokensConfig()` - Builds global tokens
|
|
307
|
-
- `getDefaultBaseTokensConfig()` - Builds default base tokens
|
|
308
|
-
- `getDefaultSemanticTokensConfig()` - Builds default semantic tokens
|
|
309
|
-
- `getBaseTokensConfig(brand)` - Builds brand-specific base tokens
|
|
310
|
-
- `getSemanticTokensConfig(brand)` - Builds brand-specific semantic tokens
|
|
311
|
-
- `getBrands()` - Automatically detects brands in `src/tokens/brands/`
|
|
312
|
-
|
|
313
|
-
## Dependencies
|
|
314
148
|
|
|
315
|
-
|
|
316
|
-
- **@changesets/cli** (^2.29.7) - Version management and changelog generation
|
|
149
|
+
### Using JSON Tokens
|
|
317
150
|
|
|
318
|
-
|
|
151
|
+
JSON format provides a nested structure:
|
|
319
152
|
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
### Creating a Changeset
|
|
323
|
-
|
|
324
|
-
When making changes, create a changeset to document them:
|
|
153
|
+
```javascript
|
|
154
|
+
import tokens from '@beam-ui/design-tokens/build/semantic/tokens.json';
|
|
325
155
|
|
|
326
|
-
|
|
327
|
-
|
|
156
|
+
console.log(tokens.button.primary.background); // "hsl(0, 0%, 0%)"
|
|
157
|
+
console.log(tokens.color.background.primary); // "hsl(0, 0%, 100%)"
|
|
328
158
|
```
|
|
329
159
|
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
### Versioning and Publishing
|
|
160
|
+
## Token Reference
|
|
333
161
|
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
```bash
|
|
337
|
-
# Update version and changelog
|
|
338
|
-
yarn version
|
|
339
|
-
|
|
340
|
-
# Publish to npm
|
|
341
|
-
yarn release
|
|
342
|
-
```
|
|
162
|
+
### Global Tokens
|
|
343
163
|
|
|
344
|
-
|
|
164
|
+
**Breakpoints**
|
|
165
|
+
- `breakpoint-small`, `breakpoint-medium`, `breakpoint-large`, `breakpoint-x-large`
|
|
345
166
|
|
|
346
|
-
|
|
167
|
+
**Accessibility**
|
|
168
|
+
- `a11y-min-touch-target` - Minimum touch target size for interactive elements
|
|
347
169
|
|
|
348
|
-
|
|
349
|
-
- ✅ `button-primary-background`
|
|
350
|
-
- ❌ `button-black-bg`
|
|
170
|
+
### Base Tokens
|
|
351
171
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
172
|
+
**Colors**
|
|
173
|
+
- Brand colors: `color-tatari-red`, `color-tatari-blue`, etc.
|
|
174
|
+
- Gray scale: `color-gray-black`, `color-gray-800` through `color-gray-50`, `color-gray-white`
|
|
175
|
+
- Color palettes: `color-red-*`, `color-blue-*`, `color-green-*`, etc. (100-700 scales)
|
|
176
|
+
- Special: `color-transparent`, `color-overlay-dark`, `color-overlay-light`
|
|
355
177
|
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
178
|
+
**Typography**
|
|
179
|
+
- Font families: `font-family-inter`, `font-family-favorit`, `font-family-body`, `font-family-display`
|
|
180
|
+
- Font weights: `font-weight-normal` (400), `font-weight-medium` (500)
|
|
181
|
+
- Font sizes: `font-size-x-small` through `font-size-xxxx-large`
|
|
182
|
+
- Line heights: `font-line-height-tight` through `font-line-height-loose`
|
|
183
|
+
- Letter spacing: `font-letter-spacing-x-small` through `font-letter-spacing-x-large`
|
|
359
184
|
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
- Verify CSS, JS, and JSON outputs
|
|
363
|
-
- Check that references work correctly in CSS
|
|
185
|
+
**Spacing**
|
|
186
|
+
- `spacing-xx-small` through `spacing-xxx-large`
|
|
364
187
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
188
|
+
**Borders**
|
|
189
|
+
- Border radius: `border-radius-xx-small` through `border-radius-xxx-large`, `border-radius-circle`
|
|
190
|
+
- Border width: `border-width-thin`, `border-width-regular`, `border-width-thick`
|
|
368
191
|
|
|
369
|
-
|
|
192
|
+
### Semantic Tokens
|
|
370
193
|
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
194
|
+
**Button Tokens**
|
|
195
|
+
- Variants: `button-primary-*`, `button-secondary-*`, `button-tertiary-*`
|
|
196
|
+
- Danger states: `button-danger-primary-*`, `button-danger-secondary-*`
|
|
197
|
+
- States: `-background`, `-background-hover`, `-background-active`, `-background-disabled`
|
|
198
|
+
- Text: `-text`, `-text-hover`, `-text-active`, `-text-disabled`
|
|
199
|
+
- Border: `-border`, `-border-hover`, `-border-active`, `-border-disabled`
|
|
200
|
+
- Sizes: `button-size-sm-*`, `button-size-md-*`, `button-size-lg-*`
|
|
201
|
+
|
|
202
|
+
**Color Tokens**
|
|
203
|
+
- Background: `color-background-primary`, `color-background-secondary`, etc.
|
|
204
|
+
- Surface: `color-surface-primary`, `color-surface-hover`, etc.
|
|
205
|
+
- Border: `color-border-primary`, `color-border-focus`, etc.
|
|
206
|
+
- Text: `color-text-primary`, `color-text-link`, etc.
|
|
207
|
+
- Icon: `color-icon-primary`, `color-icon-interactive`, etc.
|
|
208
|
+
- Interactive states: `color-interactive-primary-default`, etc.
|
|
209
|
+
- Status colors: `color-status-success-base`, `color-status-error-base`, etc.
|
|
210
|
+
- Brand colors: `color-brand-primary-base`, `color-brand-secondary-base`, etc.
|
|
211
|
+
|
|
212
|
+
**Typography Tokens**
|
|
213
|
+
- Display: `typography-display-100-*` through `typography-display-500-*`
|
|
214
|
+
- Headings: `typography-heading-100-*` through `typography-heading-500-*`
|
|
215
|
+
- Body text: `typography-body-large-*`, `typography-body-base-*`, `typography-body-small-*` (each with `default` and `medium` variants)
|
|
216
|
+
- Label: `typography-label-base-*`
|
|
217
|
+
- Caption: `typography-caption-*`
|
|
218
|
+
- Overline: `typography-overline-*`
|
|
219
|
+
- Properties: `-font-family`, `-font-weight`, `-font-size`, `-line-height`, `-letter-spacing`, `-color`, `-inverse`
|
|
220
|
+
|
|
221
|
+
**Focus Ring Tokens**
|
|
222
|
+
- `focus-ring-width` - Width of the focus ring outline
|
|
223
|
+
- `focus-ring-offset` - Distance between element and focus ring
|
|
224
|
+
- `focus-ring-color` - Color of the focus ring
|
|
225
|
+
- `focus-ring-transition` - Animation for focus ring appearance
|
|
226
|
+
|
|
227
|
+
## Examples
|
|
228
|
+
|
|
229
|
+
### Using Focus Ring Tokens for Accessibility (CSS)
|
|
374
230
|
|
|
375
|
-
|
|
231
|
+
```css
|
|
232
|
+
/* Import all required token files */
|
|
233
|
+
@import '@beam-ui/design-tokens/build/globals/variables.css';
|
|
234
|
+
@import '@beam-ui/design-tokens/build/base/variables.css';
|
|
235
|
+
@import '@beam-ui/design-tokens/build/semantic/variables.css';
|
|
236
|
+
|
|
237
|
+
.interactive-element {
|
|
238
|
+
/* Remove default browser focus outline */
|
|
239
|
+
outline: none;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
.interactive-element:focus-visible {
|
|
243
|
+
/* Apply design system focus ring */
|
|
244
|
+
outline: var(--focus-ring-width) solid var(--focus-ring-color);
|
|
245
|
+
outline-offset: var(--focus-ring-offset);
|
|
246
|
+
|
|
247
|
+
@media (prefers-reduced-motion: no-preference) {
|
|
248
|
+
transition: var(--focus-ring-transition);
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
```
|
|
376
252
|
|
|
377
|
-
###
|
|
378
|
-
**Solution:** Ensure you import files in the correct order (globals → base → semantic)
|
|
253
|
+
### Complete Button Component (CSS)
|
|
379
254
|
|
|
380
|
-
|
|
381
|
-
|
|
255
|
+
```css
|
|
256
|
+
/* Import all required token files */
|
|
257
|
+
@import '@beam-ui/design-tokens/build/globals/variables.css';
|
|
258
|
+
@import '@beam-ui/design-tokens/build/base/variables.css';
|
|
259
|
+
@import '@beam-ui/design-tokens/build/semantic/variables.css';
|
|
260
|
+
|
|
261
|
+
.button-primary {
|
|
262
|
+
background-color: var(--button-primary-background);
|
|
263
|
+
color: var(--button-primary-text);
|
|
264
|
+
border: var(--button-primary-border-width) solid var(--button-primary-border);
|
|
265
|
+
border-radius: var(--button-primary-border-radius);
|
|
266
|
+
font-size: var(--button-primary-font-size);
|
|
267
|
+
line-height: var(--button-primary-line-height);
|
|
268
|
+
padding-inline: var(--button-size-md-padding-inline);
|
|
269
|
+
padding-block: var(--button-size-md-padding-block);
|
|
270
|
+
min-width: var(--button-size-md-min-width);
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
.button-primary:hover {
|
|
274
|
+
background-color: var(--button-primary-background-hover);
|
|
275
|
+
color: var(--button-primary-text-hover);
|
|
276
|
+
border-color: var(--button-primary-border-hover);
|
|
277
|
+
}
|
|
278
|
+
```
|
|
382
279
|
|
|
383
|
-
###
|
|
384
|
-
|
|
280
|
+
### React Component with TypeScript
|
|
281
|
+
|
|
282
|
+
```typescript
|
|
283
|
+
import {
|
|
284
|
+
buttonPrimaryBackground,
|
|
285
|
+
buttonPrimaryText,
|
|
286
|
+
buttonPrimaryBorderRadius,
|
|
287
|
+
buttonSizeMdPaddingInline,
|
|
288
|
+
buttonSizeMdPaddingBlock
|
|
289
|
+
} from '@beam-ui/design-tokens/build/semantic/tokens.es6.js';
|
|
290
|
+
|
|
291
|
+
interface ButtonProps {
|
|
292
|
+
children: React.ReactNode;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
export const Button: React.FC<ButtonProps> = ({ children }) => {
|
|
296
|
+
return (
|
|
297
|
+
<button
|
|
298
|
+
style={{
|
|
299
|
+
backgroundColor: buttonPrimaryBackground,
|
|
300
|
+
color: buttonPrimaryText,
|
|
301
|
+
borderRadius: buttonPrimaryBorderRadius,
|
|
302
|
+
paddingInline: buttonSizeMdPaddingInline,
|
|
303
|
+
paddingBlock: buttonSizeMdPaddingBlock
|
|
304
|
+
}}
|
|
305
|
+
>
|
|
306
|
+
{children}
|
|
307
|
+
</button>
|
|
308
|
+
);
|
|
309
|
+
};
|
|
310
|
+
```
|
|
385
311
|
|
|
386
312
|
## License
|
|
387
313
|
|
|
388
|
-
MIT
|
|
389
|
-
|
|
390
|
-
## Related Documentation
|
|
314
|
+
MIT License - see [LICENSE](./LICENSE) file for details
|
|
391
315
|
|
|
392
|
-
- [USAGE.md](./USAGE.md) - Package usage and consumption guide
|
|
393
|
-
- [Style Dictionary Documentation](https://styledictionary.com/)
|
|
394
|
-
- [Design Tokens W3C Community Group](https://www.w3.org/community/design-tokens/)
|
package/build/base/tokens.es6.js
CHANGED
|
@@ -73,12 +73,15 @@ export const colorGrayWhite = "hsl(0, 0%, 100%)";
|
|
|
73
73
|
export const colorOverlayDark = "hsla(0, 0%, 0%, 0.3)";
|
|
74
74
|
export const colorOverlayLight = "hsla(0, 0%, 0%, 0.05)";
|
|
75
75
|
export const colorTransparent = "hsla(0, 0%, 0%, 0)";
|
|
76
|
-
export const
|
|
77
|
-
export const
|
|
78
|
-
export const fontFamilyFavorit =
|
|
79
|
-
|
|
80
|
-
export const
|
|
81
|
-
|
|
76
|
+
export const fontFamilySystemUI = "system-ui, sans-serif";
|
|
77
|
+
export const fontFamilyInter = "Inter, system-ui, sans-serif";
|
|
78
|
+
export const fontFamilyFavorit =
|
|
79
|
+
"FavoritStd-MediumExtended, system-ui, sans-serif";
|
|
80
|
+
export const fontFamilyDisplay =
|
|
81
|
+
"FavoritStd-MediumExtended, system-ui, sans-serif";
|
|
82
|
+
export const fontFamilyBody = "Inter, system-ui, sans-serif";
|
|
83
|
+
export const fontWeightNormal = 400;
|
|
84
|
+
export const fontWeightMedium = 500;
|
|
82
85
|
export const fontSizeXSmall = "1.2rem";
|
|
83
86
|
export const fontSizeSmall = "1.4rem";
|
|
84
87
|
export const fontSizeMedium = "1.6rem";
|