Skip to content

Commit d0d1c50

Browse files
castastrophecastastrophe
committed
chore: integrating detailed tokens; direct-token use for accordion
1 parent 0ef4c52 commit d0d1c50

File tree

97 files changed

+12350
-573
lines changed

Some content is hidden

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

97 files changed

+12350
-573
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 & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,6 @@
22
"sourceFile": "index.css",
33
"selectors": [
44
".spectrum-Accordion",
5-
".spectrum-Accordion--compact",
6-
".spectrum-Accordion--compact.spectrum-Accordion--sizeL",
7-
".spectrum-Accordion--compact.spectrum-Accordion--sizeS",
8-
".spectrum-Accordion--compact.spectrum-Accordion--sizeXL",
9-
".spectrum-Accordion--sizeL",
10-
".spectrum-Accordion--sizeS",
11-
".spectrum-Accordion--sizeXL",
12-
".spectrum-Accordion--spacious",
13-
".spectrum-Accordion--spacious.spectrum-Accordion--sizeL",
14-
".spectrum-Accordion--spacious.spectrum-Accordion--sizeS",
15-
".spectrum-Accordion--spacious.spectrum-Accordion--sizeXL",
165
".spectrum-Accordion-item",
176
".spectrum-Accordion-item.is-disabled .spectrum-Accordion-itemContent",
187
".spectrum-Accordion-item.is-disabled .spectrum-Accordion-itemHeader",
@@ -36,168 +25,11 @@
3625
".spectrum-Accordion-itemHeading",
3726
".spectrum-Accordion-itemIconContainer",
3827
".spectrum-Accordion-itemIconContainer:dir(rtl)",
39-
".spectrum-Accordion:dir(rtl)",
40-
".spectrum-Accordion:lang(ja)",
41-
".spectrum-Accordion:lang(ko)",
42-
".spectrum-Accordion:lang(zh)",
43-
"[dir=\"rtl\"] .spectrum-Accordion",
4428
"[dir=\"rtl\"] .spectrum-Accordion-itemIconContainer"
4529
],
46-
"modifiers": [
47-
"--mod-accordion-background-color-default",
48-
"--mod-accordion-background-color-down",
49-
"--mod-accordion-background-color-hover",
50-
"--mod-accordion-background-color-key-focus",
51-
"--mod-accordion-component-edge-to-text",
52-
"--mod-accordion-corner-radius",
53-
"--mod-accordion-disclosure-indicator-height",
54-
"--mod-accordion-disclosure-indicator-to-text-space",
55-
"--mod-accordion-divider-color",
56-
"--mod-accordion-divider-thickness",
57-
"--mod-accordion-edge-to-disclosure-indicator-space",
58-
"--mod-accordion-edge-to-text-space",
59-
"--mod-accordion-focus-indicator-color",
60-
"--mod-accordion-focus-indicator-gap",
61-
"--mod-accordion-focus-indicator-thickness",
62-
"--mod-accordion-item-content-area-bottom-to-content",
63-
"--mod-accordion-item-content-area-top-to-content",
64-
"--mod-accordion-item-content-color",
65-
"--mod-accordion-item-content-disabled-color",
66-
"--mod-accordion-item-content-font",
67-
"--mod-accordion-item-content-font-size",
68-
"--mod-accordion-item-content-font-style",
69-
"--mod-accordion-item-content-font-weight",
70-
"--mod-accordion-item-content-line-height",
71-
"--mod-accordion-item-header-bottom-to-text-space",
72-
"--mod-accordion-item-header-color-default",
73-
"--mod-accordion-item-header-color-down",
74-
"--mod-accordion-item-header-color-hover",
75-
"--mod-accordion-item-header-color-key-focus",
76-
"--mod-accordion-item-header-disabled-color",
77-
"--mod-accordion-item-header-font",
78-
"--mod-accordion-item-header-font-size",
79-
"--mod-accordion-item-header-font-style",
80-
"--mod-accordion-item-header-font-weight",
81-
"--mod-accordion-item-header-line-height",
82-
"--mod-accordion-item-header-top-to-text-space",
83-
"--mod-accordion-item-height",
84-
"--mod-accordion-item-width",
85-
"--mod-accordion-min-block-size"
86-
],
87-
"component": [
88-
"--spectrum-accordion-background-color-default",
89-
"--spectrum-accordion-background-color-down",
90-
"--spectrum-accordion-background-color-hover",
91-
"--spectrum-accordion-background-color-key-focus",
92-
"--spectrum-accordion-bottom-to-text-compact-extra-large",
93-
"--spectrum-accordion-bottom-to-text-compact-large",
94-
"--spectrum-accordion-bottom-to-text-compact-medium",
95-
"--spectrum-accordion-bottom-to-text-compact-small",
96-
"--spectrum-accordion-bottom-to-text-regular-extra-large",
97-
"--spectrum-accordion-bottom-to-text-regular-large",
98-
"--spectrum-accordion-bottom-to-text-regular-medium",
99-
"--spectrum-accordion-bottom-to-text-regular-small",
100-
"--spectrum-accordion-bottom-to-text-spacious-extra-large",
101-
"--spectrum-accordion-bottom-to-text-spacious-large",
102-
"--spectrum-accordion-bottom-to-text-spacious-medium",
103-
"--spectrum-accordion-bottom-to-text-spacious-small",
104-
"--spectrum-accordion-component-edge-to-text",
105-
"--spectrum-accordion-content-area-bottom-to-content",
106-
"--spectrum-accordion-content-area-top-to-content",
107-
"--spectrum-accordion-corner-radius",
108-
"--spectrum-accordion-disclosure-indicator-height",
109-
"--spectrum-accordion-disclosure-indicator-to-text",
110-
"--spectrum-accordion-disclosure-indicator-to-text-space",
111-
"--spectrum-accordion-divider-color",
112-
"--spectrum-accordion-edge-to-disclosure-indicator",
113-
"--spectrum-accordion-edge-to-disclosure-indicator-space",
114-
"--spectrum-accordion-edge-to-text",
115-
"--spectrum-accordion-edge-to-text-space",
116-
"--spectrum-accordion-focus-indicator-color",
117-
"--spectrum-accordion-focus-indicator-gap",
118-
"--spectrum-accordion-focus-indicator-thickness",
119-
"--spectrum-accordion-item-content-area-bottom-to-content",
120-
"--spectrum-accordion-item-content-area-top-to-content",
121-
"--spectrum-accordion-item-content-color",
122-
"--spectrum-accordion-item-content-disabled-color",
123-
"--spectrum-accordion-item-content-font",
124-
"--spectrum-accordion-item-content-font-size",
125-
"--spectrum-accordion-item-content-font-style",
126-
"--spectrum-accordion-item-content-font-weight",
127-
"--spectrum-accordion-item-content-line-height",
128-
"--spectrum-accordion-item-header-bottom-to-text-space",
129-
"--spectrum-accordion-item-header-color-default",
130-
"--spectrum-accordion-item-header-color-down",
131-
"--spectrum-accordion-item-header-color-hover",
132-
"--spectrum-accordion-item-header-color-key-focus",
133-
"--spectrum-accordion-item-header-disabled-color",
134-
"--spectrum-accordion-item-header-font",
135-
"--spectrum-accordion-item-header-font-size",
136-
"--spectrum-accordion-item-header-font-style",
137-
"--spectrum-accordion-item-header-font-weight",
138-
"--spectrum-accordion-item-header-line-height",
139-
"--spectrum-accordion-item-header-top-to-text-space",
140-
"--spectrum-accordion-item-height",
141-
"--spectrum-accordion-item-width",
142-
"--spectrum-accordion-min-block-size",
143-
"--spectrum-accordion-minimum-width",
144-
"--spectrum-accordion-small-top-to-text-spacious",
145-
"--spectrum-accordion-top-to-text-compact-extra-large",
146-
"--spectrum-accordion-top-to-text-compact-large",
147-
"--spectrum-accordion-top-to-text-compact-medium",
148-
"--spectrum-accordion-top-to-text-compact-small",
149-
"--spectrum-accordion-top-to-text-regular-extra-large",
150-
"--spectrum-accordion-top-to-text-regular-large",
151-
"--spectrum-accordion-top-to-text-regular-medium",
152-
"--spectrum-accordion-top-to-text-regular-small",
153-
"--spectrum-accordion-top-to-text-spacious-extra-large",
154-
"--spectrum-accordion-top-to-text-spacious-large",
155-
"--spectrum-accordion-top-to-text-spacious-medium"
156-
],
157-
"global": [
158-
"--spectrum-background-opacity-default",
159-
"--spectrum-background-opacity-down",
160-
"--spectrum-background-opacity-hover",
161-
"--spectrum-background-opacity-key-focus",
162-
"--spectrum-body-color",
163-
"--spectrum-body-sans-serif-font-style",
164-
"--spectrum-body-sans-serif-font-weight",
165-
"--spectrum-body-size-l",
166-
"--spectrum-body-size-m",
167-
"--spectrum-body-size-s",
168-
"--spectrum-body-size-xs",
169-
"--spectrum-bold-font-weight",
170-
"--spectrum-cjk-line-height-100",
171-
"--spectrum-component-edge-to-text-100",
172-
"--spectrum-component-edge-to-text-200",
173-
"--spectrum-component-edge-to-text-50",
174-
"--spectrum-component-edge-to-text-75",
175-
"--spectrum-component-height-100",
176-
"--spectrum-component-height-200",
177-
"--spectrum-component-height-300",
178-
"--spectrum-component-height-400",
179-
"--spectrum-component-height-75",
180-
"--spectrum-corner-radius-100",
181-
"--spectrum-default-font-style",
182-
"--spectrum-disabled-content-color",
183-
"--spectrum-divider-thickness-small",
184-
"--spectrum-focus-indicator-color",
185-
"--spectrum-focus-indicator-gap",
186-
"--spectrum-focus-indicator-thickness",
187-
"--spectrum-font-size-200",
188-
"--spectrum-font-size-300",
189-
"--spectrum-font-size-500",
190-
"--spectrum-font-size-700",
191-
"--spectrum-gray-200",
192-
"--spectrum-gray-900",
193-
"--spectrum-line-height-100",
194-
"--spectrum-logical-rotation",
195-
"--spectrum-neutral-content-color-default",
196-
"--spectrum-neutral-content-color-down",
197-
"--spectrum-neutral-content-color-hover",
198-
"--spectrum-neutral-content-color-key-focus",
199-
"--spectrum-sans-font-family-stack"
200-
],
30+
"modifiers": [],
31+
"component": [],
32+
"global": ["--spectrum-logical-rotation"],
20133
"passthroughs": [],
20234
"high-contrast": []
20335
}

0 commit comments

Comments
 (0)