Skip to content

Commit 53c078e

Browse files
castastrophecastastrophe
committed
chore: integrating detailed tokens; direct-token use for accordion
1 parent 7444355 commit 53c078e

File tree

98 files changed

+30501
-17876
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

98 files changed

+30501
-17876
lines changed

‎.storybook/guides/converting-css-properties-to-tokens.mdx

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Converting CSS custom properties to Spectrum tokens
2+
3+
This document explains how to convert CSS custom properties (CSS variables) that start with `--spectrum-` into entries in the `tokens.json` file for Spectrum CSS components.
4+
5+
## Overview
6+
7+
Spectrum CSS components use custom properties for theming and styling. These properties are defined in the component's CSS file and should be converted to structured tokens in the `tokens.json` file for better maintainability and consistency.
8+
9+
## Process
10+
11+
### Identify custom properties
12+
13+
Look for all custom properties in the component's CSS file that start with `--spectrum-{component-name}-`. For example, in `components/alertdialog/index.css`:
14+
15+
```css
16+
.spectrum-AlertDialog {
17+
--spectrum-alert-dialog-min-width: var(--spectrum-alert-dialog-minimum-width);
18+
--spectrum-alert-dialog-max-width: var(--spectrum-alert-dialog-maximum-width);
19+
--spectrum-alert-dialog-icon-size: var(--spectrum-workflow-icon-size-100);
20+
/* ... more properties */
21+
}
22+
```
23+
24+
### Convert property names
25+
26+
Remove the `--spectrum-` prefix and convert the property name to kebab-case:
27+
28+
| CSS Property | Token Key |
29+
| ----------------------------------- | ------------------------ |
30+
| `--spectrum-alert-dialog-min-width` | `alert-dialog-min-width` |
31+
| `--spectrum-alert-dialog-max-width` | `alert-dialog-max-width` |
32+
| `--spectrum-alert-dialog-icon-size` | `alert-dialog-icon-size` |
33+
34+
### Determine token schema
35+
36+
Choose the appropriate schema based on the token type:
37+
38+
- **alias.json**: For simple value references to another token.
39+
```json
40+
{
41+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/alias.json",
42+
"value": "{spacing-300}"
43+
}
44+
```
45+
- **scale-set.json**: For responsive values (e.g., desktop/mobile variants).
46+
```json
47+
{
48+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/scale-set.json",
49+
"sets": {
50+
"desktop": {
51+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/alias.json",
52+
"value": "{spacing-700}"
53+
},
54+
"mobile": {
55+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/alias.json",
56+
"value": "{spacing-600}"
57+
}
58+
}
59+
}
60+
```
61+
- **color-set.json**: For color sets, often used for theming or stateful colors.
62+
```json
63+
{
64+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/color-set.json",
65+
"value": {
66+
"light": "#FFFFFF",
67+
"dark": "#000000"
68+
}
69+
}
70+
```
71+
- **color.json**: For direct color values (RGB/RGBA format).
72+
```json
73+
{
74+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/color.json",
75+
"value": "rgb(255, 255, 255)"
76+
}
77+
```
78+
- **dimension.json**: For explicit dimension values (e.g., px, em, rem) that are not references to other tokens.
79+
```json
80+
{
81+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/dimension.json",
82+
"value": "16px"
83+
}
84+
```
85+
86+
### Map values
87+
88+
Convert CSS custom property values to token references:
89+
90+
| CSS value | Token value |
91+
| ------------------------------------------ | ---------------------------- |
92+
| `var(--spectrum-spacing-300)` | `{spacing-300}` |
93+
| `var(--spectrum-heading-color)` | `{heading-color}` |
94+
| `var(--spectrum-background-layer-2-color)` | `{background-layer-2-color}` |
95+
96+
## Token structure
97+
98+
### Basic alias token
99+
100+
```json
101+
{
102+
"alert-dialog-min-width": {
103+
"component": "alert-dialog",
104+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/alias.json",
105+
"value": "{alert-dialog-minimum-width}"
106+
}
107+
}
108+
```
109+
110+
### Scale set token (responsive)
111+
112+
```json
113+
{
114+
"alert-dialog-description-to-buttons": {
115+
"component": "alert-dialog",
116+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/scale-set.json",
117+
"sets": {
118+
"desktop": {
119+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/alias.json",
120+
"value": "{spacing-700}"
121+
},
122+
"mobile": {
123+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/alias.json",
124+
"value": "{spacing-600}"
125+
}
126+
}
127+
}
128+
}
129+
```
130+
131+
## Example: Alert Dialog
132+
133+
### Token data
134+
135+
```json
136+
{
137+
"alert-dialog-min-width": {
138+
"component": "alert-dialog",
139+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/alias.json",
140+
"value": "{alert-dialog-minimum-width}"
141+
},
142+
"alert-dialog-max-width": {
143+
"component": "alert-dialog",
144+
"$schema": "https://opensource.adobe.com/spectrum-tokens/schemas/token-types/alias.json",
145+
"value": "{alert-dialog-maximum-width}"
146+
}
147+
}
148+
```
149+
150+
### Converted to custom properties
151+
152+
```css
153+
.spectrum-AlertDialog {
154+
--spectrum-alert-dialog-min-width: var(--spectrum-alert-dialog-minimum-width);
155+
--spectrum-alert-dialog-max-width: var(--spectrum-alert-dialog-maximum-width);
156+
/* ... more properties */
157+
}
158+
```
159+
160+
## Best practices
161+
162+
1. **Consistent naming**: Always use kebab-case for token keys
163+
2. **Component assignment**: Assign all tokens to the appropriate component
164+
3. **Schema selection**: Use `alias.json` for simple references, `scale-set.json` for responsive values
165+
4. **Value mapping**: Convert CSS custom property references to token references
166+
5. **Preserve existing tokens**: Don't overwrite existing tokens that already have the correct structure
167+
6. **Documentation**: Update component documentation to reflect the new token structure
168+
169+
## Common value mappings
170+
171+
| CSS reference | Token reference |
172+
| ----------------------------------- | -------------------------- |
173+
| `--spectrum-spacing-{n}` | `{spacing-{n}}` |
174+
| `--spectrum-color-{name}` | `{color-{name}}` |
175+
| `--spectrum-font-{property}` | `{font-{property}}` |
176+
| `--spectrum-corner-radius-{size}` | `{corner-radius-{size}}` |
177+
| `--spectrum-{component}-{property}` | `{{component}-{property}}` |
178+
179+
## Validation
180+
181+
After converting, ensure:
182+
183+
1. All custom properties from the CSS file are represented in the tokens.json
184+
2. Token keys follow the naming convention
185+
3. Schema references are correct
186+
4. Component assignments are accurate
187+
5. Value references point to valid tokens
188+
189+
This conversion process ensures better maintainability, consistency, and enables the Spectrum design system to properly manage component theming and styling.

‎components/accordion/index.css

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@
1111
* governing permissions and limitations under the License.
1212
*/
1313

14+
@design-tokens url("../../tokens/dist/json/tokens.json") format("style-dictionary3");
15+
@design-tokens url("./tokens.json") format("style-dictionary3");
16+
1417
.spectrum-Accordion {
1518
/* Layout and spacing */
1619
--spectrum-accordion-item-minimum-height: var(--spectrum-component-height-100);

0 commit comments

Comments
 (0)