Skip to content

Commit 346cf01

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

File tree

99 files changed

+30623
-18222
lines changed

Some content is hidden

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

99 files changed

+30623
-18222
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/dist/metadata.json

Lines changed: 3 additions & 167 deletions
Original file line numberDiff line numberDiff line change
@@ -36,201 +36,37 @@
3636
".spectrum-Accordion:lang(zh)",
3737
"[dir=\"rtl\"] .spectrum-Accordion"
3838
],
39-
"modifiers": [
40-
"--mod-accordion-animation-duration",
41-
"--mod-accordion-background-color-default",
42-
"--mod-accordion-background-color-down",
43-
"--mod-accordion-background-color-hover",
44-
"--mod-accordion-background-color-key-focus",
45-
"--mod-accordion-content-padding-inline",
46-
"--mod-accordion-corner-radius",
47-
"--mod-accordion-disclosure-indicator-height",
48-
"--mod-accordion-disclosure-indicator-to-text-space",
49-
"--mod-accordion-divider-color",
50-
"--mod-accordion-divider-thickness",
51-
"--mod-accordion-edge-to-content-area",
52-
"--mod-accordion-edge-to-disclosure-indicator-space",
53-
"--mod-accordion-edge-to-text-space",
54-
"--mod-accordion-item-content-area-bottom-to-content",
55-
"--mod-accordion-item-content-area-top-to-content",
56-
"--mod-accordion-item-content-color",
57-
"--mod-accordion-item-content-disabled-color",
58-
"--mod-accordion-item-content-font",
59-
"--mod-accordion-item-content-font-size",
60-
"--mod-accordion-item-content-font-style",
61-
"--mod-accordion-item-content-font-weight",
62-
"--mod-accordion-item-content-line-height",
63-
"--mod-accordion-item-focus-indicator-color",
64-
"--mod-accordion-item-focus-indicator-gap",
65-
"--mod-accordion-item-focus-indicator-thickness",
66-
"--mod-accordion-item-header-bottom-to-text-space",
67-
"--mod-accordion-item-header-color-default",
68-
"--mod-accordion-item-header-color-down",
69-
"--mod-accordion-item-header-color-hover",
70-
"--mod-accordion-item-header-color-key-focus",
71-
"--mod-accordion-item-header-disabled-color",
72-
"--mod-accordion-item-header-font",
73-
"--mod-accordion-item-header-font-size",
74-
"--mod-accordion-item-header-font-style",
75-
"--mod-accordion-item-header-font-weight",
76-
"--mod-accordion-item-header-line-height",
77-
"--mod-accordion-item-header-top-to-text-space",
78-
"--mod-accordion-item-min-block-size",
79-
"--mod-accordion-item-minimum-height",
80-
"--mod-accordion-item-minimum-width",
81-
"--mod-accordion-item-width",
82-
"--mod-accordion-top-to-disclosure-indicator"
83-
],
39+
"modifiers": [],
8440
"component": [
85-
"--spectrum-accordion-animation-duration",
8641
"--spectrum-accordion-background-color-default",
8742
"--spectrum-accordion-background-color-down",
8843
"--spectrum-accordion-background-color-hover",
8944
"--spectrum-accordion-background-color-key-focus",
90-
"--spectrum-accordion-bottom-to-text-compact-extra-large",
91-
"--spectrum-accordion-bottom-to-text-compact-large",
92-
"--spectrum-accordion-bottom-to-text-compact-medium",
93-
"--spectrum-accordion-bottom-to-text-compact-small",
94-
"--spectrum-accordion-bottom-to-text-extra-large",
95-
"--spectrum-accordion-bottom-to-text-large",
96-
"--spectrum-accordion-bottom-to-text-medium",
97-
"--spectrum-accordion-bottom-to-text-small",
98-
"--spectrum-accordion-bottom-to-text-spacious-extra-large",
99-
"--spectrum-accordion-bottom-to-text-spacious-large",
100-
"--spectrum-accordion-bottom-to-text-spacious-medium",
101-
"--spectrum-accordion-bottom-to-text-spacious-small",
102-
"--spectrum-accordion-content-area-bottom-to-content",
103-
"--spectrum-accordion-content-area-edge-to-content-extra-large",
104-
"--spectrum-accordion-content-area-edge-to-content-large",
105-
"--spectrum-accordion-content-area-edge-to-content-medium",
106-
"--spectrum-accordion-content-area-edge-to-content-small",
107-
"--spectrum-accordion-content-area-top-to-content",
10845
"--spectrum-accordion-content-padding-inline",
10946
"--spectrum-accordion-corner-radius",
11047
"--spectrum-accordion-disclosure-indicator-height",
111-
"--spectrum-accordion-disclosure-indicator-to-text-extra-large",
112-
"--spectrum-accordion-disclosure-indicator-to-text-large",
113-
"--spectrum-accordion-disclosure-indicator-to-text-medium",
114-
"--spectrum-accordion-disclosure-indicator-to-text-small",
11548
"--spectrum-accordion-disclosure-indicator-to-text-space",
116-
"--spectrum-accordion-divider-color",
11749
"--spectrum-accordion-divider-thickness",
11850
"--spectrum-accordion-edge-to-content-area",
119-
"--spectrum-accordion-edge-to-content-area-extra-large",
120-
"--spectrum-accordion-edge-to-content-area-large",
121-
"--spectrum-accordion-edge-to-content-area-medium",
122-
"--spectrum-accordion-edge-to-content-area-small",
12351
"--spectrum-accordion-edge-to-disclosure-indicator-space",
124-
"--spectrum-accordion-edge-to-text",
125-
"--spectrum-accordion-edge-to-text-space",
126-
"--spectrum-accordion-item-content-area-bottom-to-content",
127-
"--spectrum-accordion-item-content-area-top-to-content",
12852
"--spectrum-accordion-item-content-color",
129-
"--spectrum-accordion-item-content-font",
13053
"--spectrum-accordion-item-content-font-size",
131-
"--spectrum-accordion-item-content-font-style",
132-
"--spectrum-accordion-item-content-font-weight",
13354
"--spectrum-accordion-item-content-line-height",
13455
"--spectrum-accordion-item-focus-indicator-color",
135-
"--spectrum-accordion-item-focus-indicator-gap",
136-
"--spectrum-accordion-item-focus-indicator-thickness",
13756
"--spectrum-accordion-item-header-bottom-to-text-space",
13857
"--spectrum-accordion-item-header-color-default",
13958
"--spectrum-accordion-item-header-color-down",
14059
"--spectrum-accordion-item-header-color-hover",
14160
"--spectrum-accordion-item-header-color-key-focus",
14261
"--spectrum-accordion-item-header-cursor",
143-
"--spectrum-accordion-item-header-font",
14462
"--spectrum-accordion-item-header-font-size",
145-
"--spectrum-accordion-item-header-font-style",
146-
"--spectrum-accordion-item-header-font-weight",
14763
"--spectrum-accordion-item-header-line-height",
14864
"--spectrum-accordion-item-header-top-to-text-space",
149-
"--spectrum-accordion-item-min-block-size",
15065
"--spectrum-accordion-item-minimum-height",
151-
"--spectrum-accordion-item-minimum-width",
15266
"--spectrum-accordion-item-width",
153-
"--spectrum-accordion-minimum-width",
154-
"--spectrum-accordion-top-to-disclosure-indicator",
155-
"--spectrum-accordion-top-to-text-compact-extra-large",
156-
"--spectrum-accordion-top-to-text-compact-large",
157-
"--spectrum-accordion-top-to-text-compact-medium",
158-
"--spectrum-accordion-top-to-text-compact-small",
159-
"--spectrum-accordion-top-to-text-extra-large",
160-
"--spectrum-accordion-top-to-text-large",
161-
"--spectrum-accordion-top-to-text-medium",
162-
"--spectrum-accordion-top-to-text-small",
163-
"--spectrum-accordion-top-to-text-spacious-extra-large",
164-
"--spectrum-accordion-top-to-text-spacious-large",
165-
"--spectrum-accordion-top-to-text-spacious-medium",
166-
"--spectrum-accordion-top-to-text-spacious-small"
167-
],
168-
"global": [
169-
"--spectrum-animation-duration-100",
170-
"--spectrum-body-color",
171-
"--spectrum-body-sans-serif-font-style",
172-
"--spectrum-body-sans-serif-font-weight",
173-
"--spectrum-body-size-l",
174-
"--spectrum-body-size-m",
175-
"--spectrum-body-size-s",
176-
"--spectrum-body-size-xs",
177-
"--spectrum-bold-font-weight",
178-
"--spectrum-chevron-icon-size-100",
179-
"--spectrum-chevron-icon-size-200",
180-
"--spectrum-chevron-icon-size-300",
181-
"--spectrum-chevron-icon-size-75",
182-
"--spectrum-cjk-line-height-100",
183-
"--spectrum-component-height-100",
184-
"--spectrum-component-height-200",
185-
"--spectrum-component-height-300",
186-
"--spectrum-component-height-400",
187-
"--spectrum-component-height-50",
188-
"--spectrum-component-height-75",
189-
"--spectrum-corner-radius-medium-size-extra-large",
190-
"--spectrum-corner-radius-medium-size-large",
191-
"--spectrum-corner-radius-medium-size-medium",
192-
"--spectrum-corner-radius-medium-size-small",
193-
"--spectrum-default-font-style",
194-
"--spectrum-disabled-content-color",
195-
"--spectrum-divider-thickness-small",
196-
"--spectrum-field-default-width-extra-large",
197-
"--spectrum-field-default-width-large",
198-
"--spectrum-field-default-width-medium",
199-
"--spectrum-field-edge-to-disclosure-icon-100",
200-
"--spectrum-field-edge-to-disclosure-icon-200",
201-
"--spectrum-field-edge-to-disclosure-icon-300",
202-
"--spectrum-field-edge-to-disclosure-icon-75",
203-
"--spectrum-field-top-to-disclosure-icon-compact-extra-large",
204-
"--spectrum-field-top-to-disclosure-icon-compact-large",
205-
"--spectrum-field-top-to-disclosure-icon-compact-medium",
206-
"--spectrum-field-top-to-disclosure-icon-compact-small",
207-
"--spectrum-field-top-to-disclosure-icon-extra-large",
208-
"--spectrum-field-top-to-disclosure-icon-large",
209-
"--spectrum-field-top-to-disclosure-icon-medium",
210-
"--spectrum-field-top-to-disclosure-icon-small",
211-
"--spectrum-field-top-to-disclosure-icon-spacious-extra-large",
212-
"--spectrum-field-top-to-disclosure-icon-spacious-large",
213-
"--spectrum-field-top-to-disclosure-icon-spacious-medium",
214-
"--spectrum-field-top-to-disclosure-icon-spacious-small",
215-
"--spectrum-focus-indicator-color",
216-
"--spectrum-focus-indicator-gap",
217-
"--spectrum-focus-indicator-thickness",
218-
"--spectrum-font-size-100",
219-
"--spectrum-font-size-200",
220-
"--spectrum-font-size-300",
221-
"--spectrum-font-size-400",
222-
"--spectrum-gray-200",
223-
"--spectrum-line-height-100",
224-
"--spectrum-logical-rotation",
225-
"--spectrum-neutral-content-color-default",
226-
"--spectrum-neutral-content-color-down",
227-
"--spectrum-neutral-content-color-hover",
228-
"--spectrum-neutral-content-color-key-focus",
229-
"--spectrum-sans-font-family-stack",
230-
"--spectrum-transparent-black-100",
231-
"--spectrum-transparent-black-25",
232-
"--spectrum-transparent-black-300"
67+
"--spectrum-accordion-top-to-disclosure-indicator"
23368
],
69+
"global": ["--spectrum-logical-rotation"],
23470
"passthroughs": [],
23571
"high-contrast": []
23672
}

0 commit comments

Comments
 (0)