Skip to content

Commit 5ac4ec6

Browse files
5t3ph5t3ph
authored
feat(tokens): upgrade @adobe/spectrum-tokens to 14.13.1 with automated token CSS fix tooling (#6451)
* feat(tokens): enhance token upgrade workflow to capture deleted tokens * feat(tokens): add `tokens:fix` script to correct existing token usage * feat(tokens): update token data to 14.13.1 * feat(*): run tokens:fix, minor refactor to status light, update extension * feat(docs): document text-based adjustment per design guidelines * chore(status-light): cleanup cssProps * feat(tokens): derive zero-value entries * fix(tokens): use correct tokens in typography generator * fix(test): resolve prettier lint error
1 parent 9a9ddbe commit 5ac4ec6

44 files changed

Lines changed: 7384 additions & 8382 deletions

File tree

Some content is hidden

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

‎.ai/skills/migration-styling/SKILL.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,25 @@ If no fragment exists yet but the shared pattern is real, create a new file in `
8181

8282
**Step 4 — Execute the phase.** Follow **[Phase 5: Styling](../../../CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md#phase-5-styling)** in the washing machine workflow doc — it covers what to do, what to check, common problems, and the quality gate for this phase.
8383

84+
Before finalizing the CSS, check for a Spectrum 2 design guideline that is not visible from token diffs: **text-based components must have no block padding.** If the component has no visible bounding box (no background color, no border on its outer container — status light, checkbox, radio, and field label are the canonical cases), remove any `min-block-size` and `padding-block` rules. The block height must derive from `font-size` and `line-height` alone. Keeping those rules is a migration artifact, not a valid override. See [anti-pattern 12](../../../CONTRIBUTOR-DOCS/02_style-guide/01_css/05_anti-patterns.md#12-block-padding-on-text-based-components) for the full rationale and correct approach.
85+
86+
When converting `--spectrum-*` properties to `token()` calls (by stripping the `--spectrum-` prefix), verify each resulting token name against the known-valid set. If a `token()` call produces an error in the VS Code extension, run the `fix:tokens` script first before doing any manual correction:
87+
88+
```bash
89+
# From 2nd-gen/packages/tools/swc-tokens/:
90+
node scripts/fix-token-refs.js --dry-run # preview changes
91+
node scripts/fix-token-refs.js # apply
92+
```
93+
94+
The script reads `renamed` and `deleted` maps from the installed token data and handles all mechanical cases automatically:
95+
96+
- **Renamed token**: `token("old")` → `token("new")` (authoritative, no review needed)
97+
- **Deleted, `"0"` replacement**: `token("zero-val")` → `0` (zero-pixel spacing; do not use `token("0")`)
98+
- **Deleted, named replacement**: `token("old")` → `token("suggestion")` (curated; verify semantics)
99+
- **Deleted, `null` replacement**: adds a `/* TODO */` inline comment for manual review
100+
101+
Only address `/* TODO */` comments manually — those are tokens with no known replacement where you must decide whether to drop the property, restructure, or hardcode a specific value.
102+
84103
**Step 5 — Document exposed custom properties.** After writing the CSS, add a `@cssprop` JSDoc tag to the SWC component class (`2nd-gen/packages/swc/components/[component]/[Component].ts`) for every exposed `--swc-*` property. Place all `@cssprop` tags on the primary SWC class export (not the core base class). Each tag should name the property and give a one-line description of what it controls, including its default token where relevant.
85104

86105
```ts

‎2nd-gen/packages/swc/.storybook/preview.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -489,6 +489,8 @@ const preview = {
489489
['Rendering and styling migration analysis'],
490490
'Search',
491491
['Rendering and styling migration analysis'],
492+
'Sidenav',
493+
['Accessibility migration analysis'],
492494
'Slider',
493495
['Rendering and styling migration analysis'],
494496
'Status light',

‎2nd-gen/packages/swc/components/accordion/accordion-item.css‎

Lines changed: 31 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,10 @@
5454
/* ── Header button ──────────────────────────────────────────────────── */
5555

5656
.swc-AccordionItem-header {
57-
--_swc-accordion-item-padding-top: var(--swc-accordion-item-padding-top, token("accordion-top-to-text-medium"));
58-
--_swc-accordion-item-padding-bottom: var(--swc-accordion-item-padding-bottom, token("accordion-bottom-to-text-medium"));
59-
--_swc-accordion-item-disclosure-indicator-gap: var(--swc-accordion-item-disclosure-indicator-gap, token("accordion-disclosure-indicator-to-text-medium"));
60-
--_swc-accordion-item-edge-to-content-area: var(--swc-accordion-item-edge-to-content-area, token("accordion-edge-to-content-area-medium"));
57+
--_swc-accordion-item-padding-top: var(--swc-accordion-item-padding-top, token("base-padding-vertical-large"));
58+
--_swc-accordion-item-padding-bottom: var(--swc-accordion-item-padding-bottom, token("base-padding-vertical-large"));
59+
--_swc-accordion-item-disclosure-indicator-gap: var(--swc-accordion-item-disclosure-indicator-gap, token("base-gap-large"));
60+
--_swc-accordion-item-edge-to-content-area: var(--swc-accordion-item-edge-to-content-area, token("container-padding-extra-small"));
6161
--_swc-accordion-item-header-font-size: var(--swc-accordion-item-header-font-size, token("font-size-200"));
6262

6363
display: flex;
@@ -89,7 +89,7 @@
8989
.swc-AccordionItem-header:focus-visible {
9090
border-radius: var(--swc-accordion-item-focus-indicator-corner-radius, token("corner-radius-medium-size-medium"));
9191
outline: token("focus-indicator-thickness") solid token("focus-indicator-color");
92-
outline-offset: calc(token("accordion-focus-indicator-gap") * -1);
92+
outline-offset: calc(token("focus-ring-gap") * -1);
9393
}
9494

9595
.swc-AccordionItem:has(.swc-AccordionItem-header:hover) {
@@ -112,8 +112,8 @@
112112

113113
/* Default size (m): Chevron100 */
114114
.swc-AccordionItem-indicator {
115-
--swc-icon-inline-size: token("chevron-icon-size-100");
116-
--swc-icon-block-size: token("chevron-icon-size-100");
115+
--swc-icon-inline-size: token("ui-icon-medium");
116+
--swc-icon-block-size: token("ui-icon-medium");
117117

118118
flex-shrink: 0;
119119
rotate: 0deg;
@@ -127,20 +127,20 @@
127127

128128
/* Size: small, Chevron75 */
129129
:host([size="s"]) .swc-AccordionItem-indicator {
130-
--swc-icon-inline-size: token("chevron-icon-size-75");
131-
--swc-icon-block-size: token("chevron-icon-size-75");
130+
--swc-icon-inline-size: token("ui-icon-small");
131+
--swc-icon-block-size: token("ui-icon-small");
132132
}
133133

134134
/* Size: large, Chevron200 */
135135
:host([size="l"]) .swc-AccordionItem-indicator {
136-
--swc-icon-inline-size: token("chevron-icon-size-200");
137-
--swc-icon-block-size: token("chevron-icon-size-200");
136+
--swc-icon-inline-size: token("ui-icon-large");
137+
--swc-icon-block-size: token("ui-icon-large");
138138
}
139139

140140
/* Size: extra-large, Chevron300 */
141141
:host([size="xl"]) .swc-AccordionItem-indicator {
142-
--swc-icon-inline-size: token("chevron-icon-size-300");
143-
--swc-icon-block-size: token("chevron-icon-size-300");
142+
--swc-icon-inline-size: token("ui-icon-extra-large");
143+
--swc-icon-block-size: token("ui-icon-extra-large");
144144
}
145145

146146
:host([open]) .swc-AccordionItem-indicator {
@@ -178,7 +178,7 @@
178178
flex: 0 0 auto;
179179
gap: token("spacing-100");
180180
align-items: center;
181-
margin-inline-end: var(--swc-accordion-item-edge-to-content-area, token("accordion-edge-to-content-area-medium"));
181+
margin-inline-end: var(--swc-accordion-item-edge-to-content-area, token("container-padding-extra-small"));
182182
}
183183

184184
/* ── Content panel ──────────────────────────────────────────────────── */
@@ -194,9 +194,9 @@
194194
/* Inner wrapper holds padding and typography. The outer container (.swc-AccordionItem-content)
195195
is padding-free so height: 0 collapses it cleanly in the @supports animation block. */
196196
.swc-AccordionItem-contentBody {
197-
--_swc-accordion-item-content-padding-inline: var(--swc-accordion-item-content-padding-inline, token("accordion-content-area-edge-to-content-medium"));
197+
--_swc-accordion-item-content-padding-inline: var(--swc-accordion-item-content-padding-inline, token("container-padding-extra-small"));
198198

199-
padding-block: token("accordion-content-area-top-to-content") token("accordion-content-area-bottom-to-content");
199+
padding-block: token("container-padding-extra-small") token("container-padding-medium");
200200
padding-inline: var(--_swc-accordion-item-content-padding-inline);
201201
font-size: token("font-size-100");
202202
font-weight: token("regular-font-weight");
@@ -219,36 +219,36 @@
219219

220220
:host([size="s"]) {
221221
--swc-accordion-item-focus-indicator-corner-radius: token("corner-radius-medium-size-small");
222-
--swc-accordion-item-padding-top: token("accordion-top-to-text-small");
223-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-small");
224-
--swc-accordion-item-disclosure-indicator-gap: token("accordion-disclosure-indicator-to-text-small");
225-
--swc-accordion-item-edge-to-content-area: token("accordion-edge-to-content-area-small");
222+
--swc-accordion-item-padding-top: token("base-padding-vertical-medium");
223+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-medium");
224+
--swc-accordion-item-disclosure-indicator-gap: token("base-gap-medium");
225+
--swc-accordion-item-edge-to-content-area: token("container-padding-extra-small");
226226
--swc-accordion-item-header-font-size: token("font-size-100");
227-
--swc-accordion-item-content-padding-inline: token("accordion-content-area-edge-to-content-small");
227+
--swc-accordion-item-content-padding-inline: token("container-padding-extra-small");
228228
}
229229

230230
/* ── Size: large ────────────────────────────────────────────────────── */
231231

232232
:host([size="l"]) {
233233
--swc-accordion-item-focus-indicator-corner-radius: token("corner-radius-medium-size-large");
234-
--swc-accordion-item-padding-top: token("accordion-top-to-text-large");
235-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-large");
236-
--swc-accordion-item-disclosure-indicator-gap: token("accordion-disclosure-indicator-to-text-large");
237-
--swc-accordion-item-edge-to-content-area: token("accordion-edge-to-content-area-large");
234+
--swc-accordion-item-padding-top: token("base-padding-vertical-extra-large");
235+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-extra-large");
236+
--swc-accordion-item-disclosure-indicator-gap: token("base-gap-extra-large");
237+
--swc-accordion-item-edge-to-content-area: token("container-padding-small");
238238
--swc-accordion-item-header-font-size: token("font-size-300");
239-
--swc-accordion-item-content-padding-inline: token("accordion-content-area-edge-to-content-large");
239+
--swc-accordion-item-content-padding-inline: token("container-padding-small");
240240
}
241241

242242
/* ── Size: extra-large ──────────────────────────────────────────────── */
243243

244244
:host([size="xl"]) {
245245
--swc-accordion-item-focus-indicator-corner-radius: token("corner-radius-medium-size-extra-large");
246-
--swc-accordion-item-padding-top: token("accordion-top-to-text-extra-large");
247-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-extra-large");
248-
--swc-accordion-item-disclosure-indicator-gap: token("accordion-disclosure-indicator-to-text-extra-large");
249-
--swc-accordion-item-edge-to-content-area: token("accordion-edge-to-content-area-extra-large");
246+
--swc-accordion-item-padding-top: token("base-padding-vertical-2x-large");
247+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-2x-large");
248+
--swc-accordion-item-disclosure-indicator-gap: token("base-gap-2x-large");
249+
--swc-accordion-item-edge-to-content-area: token("container-padding-medium");
250250
--swc-accordion-item-header-font-size: token("font-size-400");
251-
--swc-accordion-item-content-padding-inline: token("accordion-content-area-edge-to-content-extra-large");
251+
--swc-accordion-item-content-padding-inline: token("container-padding-medium");
252252
}
253253

254254
/* ── Progressive enhancement: height animation ───────────────────────

‎2nd-gen/packages/swc/components/accordion/accordion.css‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -40,41 +40,41 @@
4040

4141
/* Compact & spacious density: overrides cascade to slotted items */
4242
:host([density="compact"]) ::slotted(swc-accordion-item) {
43-
--swc-accordion-item-padding-top: token("accordion-top-to-text-compact-medium");
44-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-compact-medium");
43+
--swc-accordion-item-padding-top: token("base-padding-vertical-medium");
44+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-medium");
4545
}
4646

4747
:host([density="spacious"]) ::slotted(swc-accordion-item) {
48-
--swc-accordion-item-padding-top: token("accordion-top-to-text-spacious-medium");
49-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-spacious-medium");
48+
--swc-accordion-item-padding-top: token("base-padding-vertical-extra-large");
49+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-extra-large");
5050
}
5151

5252
:host([density="compact"][size="s"]) ::slotted(swc-accordion-item) {
53-
--swc-accordion-item-padding-top: token("accordion-top-to-text-compact-small");
54-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-compact-small");
53+
--swc-accordion-item-padding-top: token("base-padding-vertical-small");
54+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-small");
5555
}
5656

5757
:host([density="compact"][size="l"]) ::slotted(swc-accordion-item) {
58-
--swc-accordion-item-padding-top: token("accordion-top-to-text-compact-large");
59-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-compact-large");
58+
--swc-accordion-item-padding-top: token("base-padding-vertical-large");
59+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-large");
6060
}
6161

6262
:host([density="compact"][size="xl"]) ::slotted(swc-accordion-item) {
63-
--swc-accordion-item-padding-top: token("accordion-top-to-text-compact-extra-large");
64-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-compact-extra-large");
63+
--swc-accordion-item-padding-top: token("base-padding-vertical-extra-large");
64+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-extra-large");
6565
}
6666

6767
:host([density="spacious"][size="s"]) ::slotted(swc-accordion-item) {
68-
--swc-accordion-item-padding-top: token("accordion-top-to-text-spacious-small");
69-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-spacious-small");
68+
--swc-accordion-item-padding-top: token("base-padding-vertical-large");
69+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-large");
7070
}
7171

7272
:host([density="spacious"][size="l"]) ::slotted(swc-accordion-item) {
73-
--swc-accordion-item-padding-top: token("accordion-top-to-text-spacious-large");
74-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-spacious-large");
73+
--swc-accordion-item-padding-top: token("base-padding-vertical-2x-large");
74+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-2x-large");
7575
}
7676

7777
:host([density="spacious"][size="xl"]) ::slotted(swc-accordion-item) {
78-
--swc-accordion-item-padding-top: token("accordion-top-to-text-spacious-extra-large");
79-
--swc-accordion-item-padding-bottom: token("accordion-bottom-to-text-spacious-extra-large");
78+
--swc-accordion-item-padding-top: token("base-padding-vertical-3x-large");
79+
--swc-accordion-item-padding-bottom: token("base-padding-vertical-3x-large");
8080
}

0 commit comments

Comments
 (0)