@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/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. This package uses [Style Dictionary](https://styledictionary.com/) to transform design tokens into multiple formats.
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
- This repository manages design tokens that define the visual design language for Beam UI. Tokens are authored in JavaScript and transformed into CSS Variables, JavaScript ES6 modules, and JSON formats using Style Dictionary.
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
- # Install dependencies
15
- yarn install
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
- This will generate tokens in the following formats:
27
- - **CSS Variables** (`variables.css`)
28
- - **JavaScript ES6** (`tokens.es6.js`)
29
- - **JSON** (`tokens.json`)
17
+ ## Available Output Formats
30
18
 
31
- All generated files are located in the `build/` directory, organized by layer:
32
- - `build/globals/` - Global tokens (breakpoints, accessibility, etc.)
33
- - `build/base/` - Default base tokens (colors, fonts, spacing, etc.)
34
- - `build/semantic/` - Default semantic tokens (buttons, typography, etc.)
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 Structure
39
-
40
- ### Source Organization
24
+ ## Token Layers
41
25
 
42
26
  Tokens are organized in three layers:
43
27
 
44
- #### Global Tokens (`src/tokens/globals/`)
45
- Global tokens shared across all themes:
46
- - `breakpoints.js` - Responsive breakpoints
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
- #### Base Tokens (`src/tokens/base/`)
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
- #### Semantic Tokens (`src/tokens/semantic/`)
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
- #### Brand-Specific Tokens (`src/tokens/brands/{brand}/`)
63
- Optional brand overrides following the same base/semantic structure
36
+ ### Using CSS Variables
64
37
 
65
- ### Token Format
38
+ #### Important: Semantic Tokens Require Base and Global Tokens
66
39
 
67
- All tokens follow the W3C Design Token format and must include:
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
- **Example - Base Token:**
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
- **Example - Semantic Token (with references):**
90
- ```javascript
91
- export default {
92
- button: {
93
- primary: {
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
- **Important:** For colors with alpha channels, use comma-based syntax:
104
- ```javascript
105
- // Correct
106
- value: 'hsla(0, 0%, 0%, 0.3)'
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
- ## Adding New Tokens
113
-
114
- ### 1. Create or edit token files
58
+ #### Why All Three Files Are Required
115
59
 
116
- Add tokens to the appropriate file in `src/tokens/base/`, `src/tokens/semantic/`, or `src/tokens/globals/`:
60
+ Tokens use `var()` references to maintain relationships across all layers:
117
61
 
118
- ```javascript
119
- // Example: Adding a new spacing value to src/tokens/base/spacing.js
120
- export default {
121
- spacing: {
122
- 'xxxx-large': {
123
- value: '6.4rem',
124
- type: 'dimension'
125
- }
126
- }
127
- };
128
- ```
129
-
130
- ### 2. Build the tokens
131
-
132
- ```bash
133
- yarn build
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
- ### 3. Verify the output
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
- ### Semantic Tokens
157
- - Component and context-specific tokens
158
- - Reference base and global tokens for values
159
- - Output: `build/semantic/`
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
- ### Brand-Specific Tokens (Optional)
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
- ### Reference Behavior
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
- /* Semantic tokens reference base tokens */
173
- --button-primary-background: var(--color-gray-black);
174
- ```
175
-
176
- **JavaScript/JSON Output:**
177
- ```javascript
178
- // Semantic tokens contain resolved values
179
- export const buttonPrimaryBackground = "hsl(0, 0%, 0%)";
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
- ## Available Transforms
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
- ## Available Filters
112
+ ### Using JavaScript/TypeScript Tokens
200
113
 
201
- Custom filters control which tokens are included in each build:
114
+ JavaScript and JSON formats output resolved values, so semantic tokens can be used independently:
202
115
 
203
- ### brand-only
204
- Filters tokens to exclude global tokens from brand builds. This ensures:
205
- - Global tokens are available for references in brand tokens
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
- 1. Create a new brand directory:
222
- ```bash
223
- mkdir -p src/tokens/brands/{brand-name}
224
- mkdir -p src/tokens/brands/{brand-name}/semantic
120
+ const button = {
121
+ backgroundColor: buttonPrimaryBackground, // "hsl(0, 0%, 0%)"
122
+ color: buttonPrimaryText // "hsl(0, 0%, 100%)"
123
+ };
225
124
  ```
226
125
 
227
- 2. Add base token files (color.js, font.js, spacing.js, etc.) in the brand directory
126
+ #### Importing Base Tokens
228
127
 
229
- 3. Add semantic token files in the semantic subdirectory
128
+ ```javascript
129
+ import { colorGrayBlack, fontSizeMedium, spacingLarge } from '@beam-ui/design-tokens/build/base/tokens.es6.js';
230
130
 
231
- 4. Build the tokens (brands are automatically detected):
232
- ```bash
233
- yarn build
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
- The build system will automatically detect and build all brands in `src/tokens/brands/`, generating output at `build/{brand-name}/base/` and `build/{brand-name}/semantic/`.
138
+ #### Importing Global Tokens
237
139
 
238
- ## Project Structure
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
- - **style-dictionary** (^5.1.1) - Token transformation engine
316
- - **@changesets/cli** (^2.29.7) - Version management and changelog generation
149
+ ### Using JSON Tokens
317
150
 
318
- ## Release Management
151
+ JSON format provides a nested structure:
319
152
 
320
- This package uses [Changesets](https://github.com/changesets/changesets) to manage versions and changelogs.
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
- ```bash
327
- yarn changeset
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
- Select the change type (`patch`, `minor`, or `major`) and describe your changes. The changeset file will be created in `.changeset/` and should be committed with your changes.
331
-
332
- ### Versioning and Publishing
160
+ ## Token Reference
333
161
 
334
- For maintainers:
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
- ## Contributing
164
+ **Breakpoints**
165
+ - `breakpoint-small`, `breakpoint-medium`, `breakpoint-large`, `breakpoint-x-large`
345
166
 
346
- When adding or modifying tokens:
167
+ **Accessibility**
168
+ - `a11y-min-touch-target` - Minimum touch target size for interactive elements
347
169
 
348
- 1. **Use semantic naming** that describes the purpose, not the value
349
- - ✅ `button-primary-background`
350
- - ❌ `button-black-bg`
170
+ ### Base Tokens
351
171
 
352
- 2. **Follow the existing token structure** and format
353
- - Include both `value` and `type` properties
354
- - Use single quotes for consistency
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
- 3. **Use token references** in semantic tokens
357
- - Reference base tokens: `value: '{color.gray.black}'`
358
- - Don't duplicate values in semantic tokens
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
- 4. **Test the build output** before committing
361
- - Run `yarn build`
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
- 5. **Create a changeset** to document your changes
366
- - Run `yarn changeset`
367
- - Describe what changed and why
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
- 6. **Document new token categories** if adding new types
192
+ ### Semantic Tokens
370
193
 
371
- 7. **Color format requirements:**
372
- - Use comma-based syntax for colors with alpha: `hsla(0, 0%, 0%, 0.3)`
373
- - Space-separated syntax is fine for colors without alpha: `hsl(0 0% 0%)`
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
- ## Troubleshooting
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
- ### Issue: CSS variables show `undefined`
378
- **Solution:** Ensure you import files in the correct order (globals → base → semantic)
253
+ ### Complete Button Component (CSS)
379
254
 
380
- ### Issue: Alpha channel gets stripped from colors
381
- **Solution:** Use comma-based color syntax (`hsla(0, 0%, 0%, 0.3)`) not slash syntax
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
- ### Issue: Semantic tokens don't update when base tokens change
384
- **Solution:** Check that semantic tokens use references (`{color.gray.black}`) not literal values
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/)
@@ -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 fontFamilyNormal = "HelveticaNeueeTextPro-Roman";
77
- export const fontFamilyMedium = "HelveticaNeueeTextPro-Md";
78
- export const fontFamilyFavorit = "FavoritStd-MediumExtended";
79
- export const fontFamilyDisplay = "FavoritStd-MediumExtended";
80
- export const fontFamilyHeading = "HelveticaNeueeTextPro-Md";
81
- export const fontFamilyBody = "HelveticaNeueeTextPro-Roman";
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";