@carbon/themes 12.0.0-alpha.1 → 12.0.0-alpha.3

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.
Files changed (57) hide show
  1. package/es/index.js +5572 -0
  2. package/lib/__tests__/themes-test.d.ts +1 -0
  3. package/lib/__tests__/tools-test.d.ts +1 -0
  4. package/lib/tokens/__tests__/Token-test.d.ts +1 -0
  5. package/lib/tokens/__tests__/TokenFormat-test.d.ts +1 -0
  6. package/lib/tokens/__tests__/TokenGroup-test.d.ts +1 -0
  7. package/lib/tokens/__tests__/TokenSet-test.d.ts +1 -0
  8. package/lib/tokens/__tests__/metadata-test.d.ts +1 -0
  9. package/lib/tokens/__tests__/v11-test.d.ts +1 -0
  10. package/lib/v10/__tests__/themes-test.d.ts +1 -0
  11. package/lib/v10/__tests__/tokens-test.d.ts +1 -0
  12. package/package.json +13 -4
  13. package/umd/index.js +6322 -0
  14. package/docs/sass.md +0 -189
  15. package/src/dtcg/README.md +0 -336
  16. package/src/dtcg/color-palette.json +0 -4424
  17. package/src/dtcg/components/button.json +0 -193
  18. package/src/dtcg/components/content-switcher.json +0 -60
  19. package/src/dtcg/components/notification.json +0 -130
  20. package/src/dtcg/components/status.json +0 -122
  21. package/src/dtcg/components/tag.json +0 -486
  22. package/src/dtcg/themes.json +0 -3356
  23. package/src/index.ts +0 -129
  24. package/src/tokens/Token.ts +0 -41
  25. package/src/tokens/TokenFormat.ts +0 -93
  26. package/src/tokens/TokenGroup.ts +0 -185
  27. package/src/tokens/TokenSet.ts +0 -91
  28. package/src/tokens/components.ts +0 -120
  29. package/src/tokens/index.ts +0 -59
  30. package/src/tokens/layout.ts +0 -39
  31. package/src/tokens/type.ts +0 -49
  32. package/src/tokens/types.ts +0 -28
  33. package/src/tokens/v10.ts +0 -188
  34. package/src/tokens/v11TokenGroup.ts +0 -546
  35. package/src/tokens/v11TokenSet.ts +0 -93
  36. package/src/tools.ts +0 -69
  37. package/src/v10/g10.ts +0 -349
  38. package/src/v10/g100.ts +0 -348
  39. package/src/v10/g90.ts +0 -350
  40. package/src/v10/index.ts +0 -22
  41. package/src/v10/metadata.yml +0 -217
  42. package/src/v10/tokens.ts +0 -397
  43. package/src/v10/white.ts +0 -352
  44. package/style-dictionary/formats/js-component-tokens.js +0 -128
  45. package/style-dictionary/formats/js-themes.js +0 -84
  46. package/style-dictionary/formats/scss-component-tokens.js +0 -149
  47. package/style-dictionary/formats/scss-themes.js +0 -127
  48. package/style-dictionary/formats/scss-tokens.js +0 -91
  49. package/style-dictionary/preprocessors/component-tokens.js +0 -172
  50. package/style-dictionary/preprocessors/dual-role.js +0 -157
  51. package/style-dictionary/preprocessors/theme-metadata.js +0 -46
  52. package/style-dictionary/sd.config.js +0 -449
  53. package/style-dictionary/transforms/alpha-modifier.js +0 -68
  54. package/style-dictionary/transforms/color-flatten.js +0 -79
  55. package/test-dtcg.scss +0 -28
  56. package/tsconfig.json +0 -8
  57. package/tsconfig.types.json +0 -10
package/docs/sass.md DELETED
@@ -1,189 +0,0 @@
1
- # `@carbon/themes`
2
-
3
- > Sass documentation for `@carbon/themes`
4
-
5
- ## Usage
6
-
7
- There are several entrypoints that you can use with `@carbon/themes`, including:
8
-
9
- | Filename | Description |
10
- | ------------------------------------------- | ------------------------------------------------------ |
11
- | `@use '@carbon/themes';` | Package entrypoint |
12
- | `@use '@carbon/themes/scss/config';` | Specify config options for the package |
13
- | `@use '@carbon/themes/scss/themes';` | Theme definitions for white, g10, g90, and g100 |
14
- | `@use '@carbon/themes/scss/theme';` | Set the current theme, get token values from the theme |
15
- | `@use '@carbon/themes/scss/tokens';` | Access theme tokens |
16
- | `@use '@carbon/themes/scss/compat/themes';` | v10 Theme definitions for white, g10, g90, and g100 |
17
- | `@use '@carbon/themes/scss/compat/tokens';` | v10 theme tokens |
18
-
19
- _Note: the white, g10, g90, and g100 themes are only available in the
20
- `scss/themes` file and are not re-exported in `@carbon/themes`. To learn more,
21
- checkout our [FAQ](#why-are-the-themes-not-exported-in-carbonthemes)._
22
-
23
- You can bring in `@carbon/themes` by using `@use`:
24
-
25
- ```scss
26
- @use '@carbon/themes';
27
-
28
- .my-component {
29
- // Use tokens from the theme, this will map to a CSS Custom Property
30
- color: themes.$token-01;
31
- }
32
-
33
- :root {
34
- // Emit CSS Custom Properties for the current theme
35
- @include themes.theme();
36
- }
37
-
38
- // Get the value of a specific token
39
- $custom-variable: rgba(themes.get('token-01'), 0.25);
40
- ```
41
-
42
- You can configure the current theme with the `$theme` option:
43
-
44
- ```scss
45
- @use '@carbon/themes/scss/themes' as *;
46
- @use '@carbon/themes' with (
47
- $theme: $g100
48
- );
49
- ```
50
-
51
- You can also extend the theme with your own custom tokens:
52
-
53
- ```scss
54
- @use '@carbon/themes/scss/themes';
55
- @use '@carbon/themes' with (
56
- $fallback: themes.$g100,
57
- $theme: (
58
- token-01: #000000,
59
- )
60
- );
61
- ```
62
-
63
- ## API
64
-
65
- | Import | Export | Description | !default |
66
- | :--------------------------- | :--------------------------- | :------------------------------------------------------------------------------------ | :------- |
67
- | `@carbon/themes/scss/themes` | | | |
68
- | | `$white` | | ✅ |
69
- | | `$g10` | | ✅ |
70
- | | `$g90` | | ✅ |
71
- | | `$g100` | | ✅ |
72
- | `@carbon/themes` | | The default entrypoint which re-exports values from all other modules in this package | |
73
- | | `$fallback` | | ✅ |
74
- | | `$theme` | | ✅ |
75
- | | `$background` | | ✅ |
76
- | | `$background-active` | | ✅ |
77
- | | `$background-selected` | | ✅ |
78
- | | `$background-selected-hover` | | ✅ |
79
- | | `$background-hover` | | ✅ |
80
- | | `$background-brand` | | ✅ |
81
- | | `$background-inverse` | | ✅ |
82
- | | `$background-inverse-hover` | | ✅ |
83
- | | `$layer-01` | | ✅ |
84
- | | `$layer-active-01` | | ✅ |
85
- | | `$layer-hover-01` | | ✅ |
86
- | | `$layer-selected-01` | | ✅ |
87
- | | `$layer-selected-hover-01` | | ✅ |
88
- | | `$layer-02` | | ✅ |
89
- | | `$layer-active-02` | | ✅ |
90
- | | `$layer-hover-02` | | ✅ |
91
- | | `$layer-selected-02` | | ✅ |
92
- | | `$layer-selected-hover-02` | | ✅ |
93
- | | `$layer-03` | | ✅ |
94
- | | `$layer-active-03` | | ✅ |
95
- | | `$layer-hover-03` | | ✅ |
96
- | | `$layer-selected-03` | | ✅ |
97
- | | `$layer-selected-hover-03` | | ✅ |
98
- | | `$layer-selected-inverse` | | ✅ |
99
- | | `$layer-selected-disabled` | | ✅ |
100
- | | `$layer-accent-01` | | ✅ |
101
- | | `$layer-accent-active-01` | | ✅ |
102
- | | `$layer-accent-hover-01` | | ✅ |
103
- | | `$layer-accent-02` | | ✅ |
104
- | | `$layer-accent-active-02` | | ✅ |
105
- | | `$layer-accent-hover-02` | | ✅ |
106
- | | `$layer-accent-03` | | ✅ |
107
- | | `$layer-accent-active-03` | | ✅ |
108
- | | `$layer-accent-hover-03` | | ✅ |
109
- | | `$field-01` | | ✅ |
110
- | | `$field-hover-01` | | ✅ |
111
- | | `$field-02` | | ✅ |
112
- | | `$field-hover-02` | | ✅ |
113
- | | `$field-03` | | ✅ |
114
- | | `$field-hover-03` | | ✅ |
115
- | | `$interactive` | | ✅ |
116
- | | `$border-subtle-00` | | ✅ |
117
- | | `$border-subtle-01` | | ✅ |
118
- | | `$border-subtle-selected-01` | | ✅ |
119
- | | `$border-subtle-02` | | ✅ |
120
- | | `$border-subtle-selected-02` | | ✅ |
121
- | | `$border-subtle-03` | | ✅ |
122
- | | `$border-subtle-selected-03` | | ✅ |
123
- | | `$border-strong-01` | | ✅ |
124
- | | `$border-strong-02` | | ✅ |
125
- | | `$border-strong-03` | | ✅ |
126
- | | `$border-inverse` | | ✅ |
127
- | | `$border-interactive` | | ✅ |
128
- | | `$border-disabled` | | ✅ |
129
- | | `$text-primary` | | ✅ |
130
- | | `$text-secondary` | | ✅ |
131
- | | `$text-placeholder` | | ✅ |
132
- | | `$text-helper` | | ✅ |
133
- | | `$text-error` | | ✅ |
134
- | | `$text-inverse` | | ✅ |
135
- | | `$text-on-color` | | ✅ |
136
- | | `$text-on-color-disabled` | | ✅ |
137
- | | `$text-disabled` | | ✅ |
138
- | | `$link-primary` | | ✅ |
139
- | | `$link-primary-hover` | | ✅ |
140
- | | `$link-secondary` | | ✅ |
141
- | | `$link-inverse` | | ✅ |
142
- | | `$link-visited` | | ✅ |
143
- | | `$icon-primary` | | ✅ |
144
- | | `$icon-secondary` | | ✅ |
145
- | | `$icon-inverse` | | ✅ |
146
- | | `$icon-on-color` | | ✅ |
147
- | | `$icon-on-color-disabled` | | ✅ |
148
- | | `$icon-disabled` | | ✅ |
149
- | | `$support-error` | | ✅ |
150
- | | `$support-success` | | ✅ |
151
- | | `$support-warning` | | ✅ |
152
- | | `$support-info` | | ✅ |
153
- | | `$support-error-inverse` | | ✅ |
154
- | | `$support-success-inverse` | | ✅ |
155
- | | `$support-warning-inverse` | | ✅ |
156
- | | `$support-info-inverse` | | ✅ |
157
- | | `$support-caution-major` | | ✅ |
158
- | | `$support-caution-minor` | | ✅ |
159
- | | `$support-caution-undefined` | | ✅ |
160
- | | `$highlight` | | ✅ |
161
- | | `$overlay` | | ✅ |
162
- | | `$toggle-off` | | ✅ |
163
- | | `$shadow` | | ✅ |
164
- | | `$focus` | | ✅ |
165
- | | `$focus-inset` | | ✅ |
166
- | | `$focus-inverse` | | ✅ |
167
- | | `$skeleton-background` | | ✅ |
168
- | | `$skeleton-element` | | ✅ |
169
-
170
- ### Configuration
171
-
172
- ## FAQ
173
-
174
- ### Why are the themes not exported in `@carbon/themes`?
175
-
176
- In order to support `@use '@carbon/themes' with` in Sass Modules, unfortunately
177
- we cannot re-export the themes available in `scss/modules/themes`. If we
178
- implemented the entrypoint at `@carbon/themes` to re-export that module, then
179
- Sass would not compile when doing the following:
180
-
181
- ```scss
182
- @use '@carbon/themes/scss/modules/themes';
183
- @use '@carbon/themes' with (
184
- $theme: themes.$g100
185
- );
186
- ```
187
-
188
- This is because the `scss/modules/themes` file will have been initialized twice
189
- which is not allowed in the Sass Module system.
package/src/dtcg/README.md DELETED
@@ -1,336 +0,0 @@
1
- # Carbon Design Tokens (DTCG Format)
2
-
3
- This directory contains Carbon Design System tokens in the
4
- [Design Tokens Community Group (DTCG)](https://tr.designtokens.org/format/)
5
- format. All Carbon themes and component tokens have been migrated to this
6
- industry-standard format.
7
-
8
- ## Structure
9
-
10
- ```
11
- dtcg/
12
- ├── themes.json # All four themes in one file (white, g10, g90, g100)
13
- ├── color-palette.json # Color palette aliases (generated from @carbon/colors)
14
- └── components/
15
- ├── button.json # Button component tokens
16
- ├── tag.json # Tag component tokens
17
- ├── notification.json # Notification component tokens
18
- ├── status.json # Status indicator tokens
19
- └── content-switcher.json # Content switcher tokens
20
- ```
21
-
22
- ## Token categories in each theme file
23
-
24
- `themes.json` is organised into top-level groups. When searching for a token,
25
- start with the group that matches the first segment of its name:
26
-
27
- | Top-level key | Token name prefix examples |
28
- | ------------- | ----------------------------------------------------------- |
29
- | `ai` | `ai-aura-*`, `ai-popover-*`, `ai-skeleton-*` |
30
- | `background` | `background`, `background-active`, `background-hover` |
31
- | `border` | `border-subtle-*`, `border-strong-*`, `border-tile-*` |
32
- | `button` | _(component tokens — see `components/button.json` instead)_ |
33
- | `field` | `field-01`, `field-02`, `field-hover-01` |
34
- | `focus` | `focus`, `focus-inset`, `focus-inverse` |
35
- | `icon` | `icon-primary`, `icon-on-color`, `icon-disabled` |
36
- | `layer` | `layer-01`, `layer-active-01`, `layer-hover-01` |
37
- | `link` | `link-primary`, `link-visited`, `link-inverse` |
38
- | `overlay` | `overlay` |
39
- | `skeleton` | `skeleton-background`, `skeleton-element` |
40
- | `support` | `support-error`, `support-warning`, `support-success` |
41
- | `text` | `text-primary`, `text-on-color`, `text-disabled` |
42
-
43
- > **Note:** Component tokens (`button`, `tag`, etc.) live in
44
- > `components/<name>.json`, **not** in `themes.json`.
45
-
46
- ## Nested key → flat token name mapping
47
-
48
- Token names in Carbon use a hyphenated convention (e.g. `border-subtle-02`,
49
- `text-on-color-disabled`). In the DTCG JSON files these are represented as
50
- **nested objects**, where each hyphen-separated segment becomes a JSON key
51
- level:
52
-
53
- | Flat token name | JSON path |
54
- | ------------------------ | ------------------------------------ |
55
- | `border-subtle-02` | `border` → `subtle` → `02` |
56
- | `text-on-color-disabled` | `text` → `on-color` → `disabled` |
57
- | `layer-accent-active-03` | `layer` → `accent` → `active` → `03` |
58
-
59
- > **Tip for agents:** Do not `grep` for the full hyphenated name — it will not
60
- > match. Instead grep for the last segment (`"02"`, `"disabled"`) and navigate
61
- > up the JSON hierarchy to confirm the full path, or read the surrounding
62
- > context to resolve ambiguity when short keys like `"01"` or `"02"` appear in
63
- > multiple token groups.
64
-
65
- ## Contextual layer tokens (`$layer-*` without numbers)
66
-
67
- In component styles (e.g. `$layer-accent`, `$layer-hover`, `$field`,
68
- `$border-subtle`), you will often see unnumbered tokens used. These are
69
- **dynamic layer-set tokens** defined in
70
- `packages/styles/scss/layer/_layer-sets.scss`.
71
-
72
- In DTCG JSON, tokens only exist as explicit numbered levels (`01`, `02`, `03`):
73
-
74
- - `layer.01` / `layer.02` / `layer.03`
75
- - `layer.accent.01` / `layer.accent.02` / `layer.accent.03`
76
- - `layer.accent.active.01` / `layer.accent.active.02` / `layer.accent.active.03`
77
-
78
- At runtime or inside a `<Layer>` component context, Carbon automatically
79
- resolves the unnumbered token (e.g. `$layer-accent`) to its corresponding
80
- numbered tier (`01`, `02`, or `03`) based on container nesting depth.
81
-
82
- ## Dual-role nodes (tokens that are also groups)
83
-
84
- Some tokens are simultaneously a value **and** a group of related tokens. For
85
- example, `background` has its own per-theme value but also has children like
86
- `background-active` and `background-hover`. In `themes.json` these look like:
87
-
88
- ```json
89
- "background": {
90
- "$type": "color",
91
- "$description": "…",
92
- "$extensions": {
93
- "carbon.themes": {
94
- "white": "{white.default}", "g10": "{gray.10}",
95
- "g90": "{gray.90}", "g100": "{gray.100}"
96
- }
97
- },
98
- "active": {
99
- "$type": "color",
100
- "$extensions": { "carbon.themes": { "white": { "value": "{gray.50}", "alpha": 0.5 }, … } }
101
- },
102
- "hover": {
103
- "$type": "color",
104
- "$extensions": { "carbon.themes": { "white": { "value": "{gray.50}", "alpha": 0.12 }, … } }
105
- }
106
- }
107
- ```
108
-
109
- The flat names generated are `background`, `background-active`,
110
- `background-hover` — all siblings in the output even though they are
111
- parent/child in the source JSON.
112
-
113
- > **Tip for agents:** If you read a node and it has both a
114
- > `$extensions["carbon.themes"]` entry and non-`$` children, both the node
115
- > itself **and** every child are valid tokens. Do not assume a node with
116
- > children is only a group.
117
-
118
- ## `carbon.themes` value aliases and `color-palette.json`
119
-
120
- The `value` field inside each `carbon.themes` entry uses curly-brace alias
121
- syntax referencing the color palette, e.g. `"{blue.60}"` or `"{gray.20}"`. These
122
- references are resolved during the build against
123
- `packages/themes/src/dtcg/color-palette.json`, which contains the full Carbon
124
- color ramp (`gray.10` … `gray.100`, `blue.10` … `blue.100`, etc.) with their hex
125
- values. If you need the actual hex for an alias, look it up in that file.
126
-
127
- ## Token Format
128
-
129
- All tokens follow the DTCG specification with a structured format using specific
130
- keys:
131
-
132
- ### DTCG Format Keys
133
-
134
- #### Required Keys
135
-
136
- - **`$schema`** - References the DTCG specification version. Always set to
137
- `"https://tr.designtokens.org/format/"` at the root level.
138
-
139
- - **`$type`** - Defines the token type (e.g., `"color"`, `"dimension"`,
140
- `"fontFamily"`). This enables proper validation and tooling support.
141
-
142
- - **`$value`** - The actual token value. Can be:
143
-
144
- - A reference to another token: `"{blue.60}"`, `"{gray.80}"`
145
- - References use curly brace syntax and resolve during build
146
-
147
- - **`$description`** - Human-readable description explaining the token's purpose
148
- and usage. Should be clear and actionable for designers and developers.
149
-
150
- #### Optional Keys
151
-
152
- - **`$extensions`** - Custom metadata and vendor-specific information. Carbon
153
- uses two namespaces — see the dedicated sections below for full details.
154
-
155
- ## Semi-transparent tokens — the `alpha` field
156
-
157
- Some tokens are a base color with an opacity applied. In `themes.json` the
158
- opacity is expressed as an `alpha` field co-located with `value` inside the
159
- per-theme entry:
160
-
161
- ```json
162
- "background": {
163
- "hover": {
164
- "$type": "color",
165
- "$description": "Background color for hover state.",
166
- "$extensions": {
167
- "carbon.themes": {
168
- "white": { "value": "{gray.50}", "alpha": 0.12 },
169
- "g10": { "value": "{gray.50}", "alpha": 0.12 },
170
- "g90": { "value": "{gray.50}", "alpha": 0.16 },
171
- "g100": { "value": "{gray.50}", "alpha": 0.16 }
172
- }
173
- }
174
- }
175
- }
176
- ```
177
-
178
- During the build the `carbon/alpha-modifier` Style Dictionary transform resolves
179
- `{gray.50}` to its hex (`#8d8d8d`) and then emits `rgba(141, 141, 141, 0.12)`.
180
-
181
- > **Reading the source:** When a `carbon.themes` entry is an object, the `value`
182
- > field alone does **not** tell you the final color. The real output is
183
- > `rgba(<palette hex at value>, <alpha>)`. Check `color-palette.json` for the
184
- > hex, then apply `alpha` mentally.
185
-
186
- > **`alpha: 0`** means fully transparent (`rgba(…, 0)`). Used for gradient "fade
187
- > to transparent" endpoints (e.g. `ai-aura-end`).
188
-
189
- > **Note for component token files:** `components/*.json` still use the legacy
190
- > `$extensions["org.carbon"].alphaModifiers` map (plural, keyed by theme) rather
191
- > than the co-located `alpha` field. The build preprocessor accepts both forms.
192
-
193
- ## `$extensions["carbon.themes"]` — the unified per-theme format
194
-
195
- Both theme tokens (`themes.json`) and component tokens (`components/*.json`)
196
- store per-theme values under the same `$extensions["carbon.themes"]` key. Each
197
- entry for a theme is either:
198
-
199
- - **A bare string** (palette alias or hex) when there is no alpha modifier:
200
- ```json
201
- "white": "{gray.10}"
202
- ```
203
- - **An object `{ value, alpha }`** when an opacity modifier is needed:
204
- ```json
205
- "white": { "value": "{gray.50}", "alpha": 0.12 }
206
- ```
207
-
208
- Example token from `themes.json`:
209
-
210
- ```json
211
- "background": {
212
- "hover": {
213
- "$type": "color",
214
- "$description": "Background color for hover state.",
215
- "$extensions": {
216
- "carbon.themes": {
217
- "white": { "value": "{gray.50}", "alpha": 0.12 },
218
- "g10": { "value": "{gray.50}", "alpha": 0.12 },
219
- "g90": { "value": "{gray.50}", "alpha": 0.16 },
220
- "g100": { "value": "{gray.50}", "alpha": 0.16 }
221
- }
222
- }
223
- }
224
- }
225
- ```
226
-
227
- The `carbon/component-tokens` preprocessor understands both entry shapes and
228
- expands them into per-theme leaf tokens before Style Dictionary processes them.
229
-
230
- ### Comparison: theme tokens vs. component tokens
231
-
232
- | | Theme token (`themes.json`) | Component token (`components/button.json`) |
233
- | ------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
234
- | File scope | All four themes | All four themes |
235
- | Value field | `$extensions["carbon.themes"]["<theme>"]` (string or `{value,alpha}`) | `$extensions["carbon.themes"]["<theme>"]` (string) |
236
- | Alpha opacity | Co-located: `{ "value": "…", "alpha": 0.12 }` | Separate: `$extensions["org.carbon"].alphaModifiers.<theme>` (note plural) |
237
- | Grepping | Navigate nested keys | Same nesting rules apply |
238
-
239
- > **Note:** Component files still use the legacy `org.carbon.alphaModifiers` map
240
- > for backwards compatibility. Both forms are accepted by the preprocessor.
241
-
242
- > **Reading theme token values:** Navigate to the nested key in `themes.json`,
243
- > then read the value for the theme you care about from `carbon.themes`.
244
-
245
- ## Theme Tokens
246
-
247
- All four Carbon themes are consolidated into `themes.json`:
248
-
249
- - **white** — Light theme, high contrast for optimal readability
250
- - **g10** — Gray 10 light theme, subtle contrast for data-dense interfaces
251
- - **g90** — Gray 90 dark theme
252
- - **g100** — Gray 100 dark theme, high contrast
253
-
254
- The file contains 250+ tokens organised into categories:
255
-
256
- - **Color tokens**: Background, layer, field, border, text, link, icon, support
257
- colors
258
- - **Semantic tokens**: Focus, interactive, highlight, overlay, skeleton
259
- - **AI tokens**: AI-specific colors for popover, chat, and skeleton states
260
-
261
- ## Using These Tokens
262
-
263
- ### Build Process
264
-
265
- The DTCG tokens are automatically processed during the build:
266
-
267
- ```bash
268
- cd packages/themes
269
- yarn build
270
- ```
271
-
272
- This generates SCSS files in `scss/generated/`:
273
-
274
- - `_themes.scss` - All four theme token maps
275
- - `_button-tokens.scss` - Button component tokens
276
- - `_tag-tokens.scss` - Tag component tokens
277
- - `_notification-tokens.scss` - Notification component tokens
278
- - `_status-tokens.scss` - Status indicator tokens
279
- - `_content-switcher-tokens.scss` - Content switcher tokens
280
-
281
- These generated files are automatically forwarded by:
282
-
283
- - `scss/_themes.scss` - Forwards theme tokens
284
- - `scss/_component-tokens.scss` - Forwards component tokens
285
-
286
- ## Validation
287
-
288
- All DTCG token files are validated against the official DTCG JSON Schema during
289
- the build process. The validation ensures:
290
-
291
- - Correct `$schema` reference
292
- - Valid `$type` values (color, dimension, etc.)
293
- - Proper token structure
294
- - Required fields are present
295
-
296
- Manual validation can be performed using any JSON Schema validator:
297
-
298
- ```bash
299
- # Using ajv-cli
300
- ajv validate -s https://tr.designtokens.org/format/schema.json -d themes.json
301
- ```
302
-
303
- ## Contributing
304
-
305
- When adding or modifying tokens:
306
-
307
- 1. **Follow the DTCG specification** - Ensure all tokens conform to the official
308
- spec
309
- 2. **Include meaningful descriptions** - Every token should have a clear
310
- `$description`
311
- 3. **Use appropriate types** - Set correct `$type` values (color, dimension,
312
- etc.)
313
- 4. **Add theme-specific values** - Edit `themes.json` for theme tokens; use
314
- `$extensions["carbon.themes"]` in `components/<name>.json` for component
315
- tokens
316
- 5. **Validate your changes** - Run `yarn build` to validate against DTCG schema
317
- 6. **Test generated output** - Verify SCSS generation works correctly
318
- 7. **Update documentation** - Update this README if adding new token categories
319
- or components
320
-
321
- ### Adding a New Component Token File
322
-
323
- 1. Create `src/dtcg/components/your-component.json`
324
- 2. Follow the structure of existing component token files
325
- 3. Use `$extensions.carbon.themes` for theme-specific values
326
- 4. Add the component to the build process in `tasks/build.js`
327
- 5. Update this README to document the new component tokens
328
-
329
- ## Resources
330
-
331
- - [DTCG Specification](https://tr.designtokens.org/format/) - Official Design
332
- Tokens Community Group format specification
333
- - [DTCG JSON Schema](https://tr.designtokens.org/format/schema.json) - JSON
334
- Schema for validation
335
- - [Design Tokens Community Group](https://www.w3.org/community/design-tokens/) -
336
- W3C Community Group