refactor: simplify tokens exposure#1161
Conversation
|
There was a problem hiding this comment.
Pull request overview
This PR refactors the Sass token system by removing “extras”/remapping support from tokens.create() and migrating previously-derived token aliases into explicit component-level CSS custom properties.
Changes:
- Simplifies
tokens.create()to accept only(prefix, tokens)by removing the$extrasand$innerparameters. - Updates many components/utilities to define derived/alias tokens as
--{component}--*custom properties in their selectors and switches usages tovar(--{component}--*). - Updates documentation and adds an internal automation skill doc for performing this migration.
Reviewed changes
Copilot reviewed 42 out of 42 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| source/utilities/preloader/style.scss | Moves shimmer-related “extras” to component-scoped CSS variables. |
| source/sass/object/_minimal-slider.scss | Moves slides-visible extra to a component-scoped CSS variable. |
| source/sass/mixin/_tokens.scss | Removes $extras and $inner support from tokens.create(). |
| source/components/typography/style.scss | Replaces extras-derived typography aliases with component-scoped CSS variables and updates consumers to var(). |
| source/components/tooltip/style.scss | Moves tooltip alias tokens (color/border-width) into component-scoped CSS variables. |
| source/components/table/style.scss | Moves computed border token into component-scoped CSS variable. |
| source/components/slider/style.scss | Moves multiple computed slider tokens into component-scoped CSS variables. |
| source/components/sidebar/style.scss | Moves width/base extras into component-scoped CSS variables. |
| source/components/select/style.scss | Moves button font-size extras into component-scoped CSS variables. |
| source/components/segment/style.scss | Moves image border-radius/min-height extras into component-scoped CSS variables. |
| source/components/paper/style.scss | Moves border/padding/bg/color extras into component-scoped CSS variables. |
| source/components/option/style.scss | Moves option sizing/disabled color extras into component-scoped CSS variables. |
| source/components/notice/style.scss | Moves shadow/border extras into component-scoped CSS variables. |
| source/components/newsitem/style.scss | Moves border extra into component-scoped CSS variable. |
| source/components/nav/style.scss | Moves nav sizing/colors/shadow extras into component-scoped CSS variables. |
| source/components/modal/style.scss | Moves modal padding/multiplier extras into component-scoped CSS variables. |
| source/components/megamenu/style.scss | Moves title font-size extra into component-scoped CSS variable. |
| source/components/image/style.scss | Moves image typography/border extras into component-scoped CSS variables. |
| source/components/iconsection/style.scss | Moves shadow extra into component-scoped CSS variable. |
| source/components/icon/style.scss | Moves icon sizes into component-scoped CSS variables and updates size resolution. |
| source/components/hero/style.scss | Moves hero overlay/sizing/shadow extras into component-scoped CSS variables. |
| source/components/header/style.scss | Moves header sizing/colors/border color extras into component-scoped CSS variables. |
| source/components/group/style.scss | Moves group gap/fluid width extras into component-scoped CSS variables. |
| source/components/gallery/style.scss | Moves gallery gap/column-min extras into component-scoped CSS variables. |
| source/components/gallery--modal/style.scss | Moves alpha-solid derived token into component-scoped CSS variable. |
| source/components/footer/style.scss | Moves footer layout/color config extras into component-scoped CSS variables. |
| source/components/fileinput/style.scss | Moves border/shadow extras into component-scoped CSS variables. |
| source/components/field/style.scss | Moves field sizing/border/bg/shadow extras into component-scoped CSS variables. |
| source/components/fab/style.scss | Moves fab border extra into component-scoped CSS variable. |
| source/components/drawer/style.scss | Moves drawer shadow/transition-ms extras into component-scoped CSS variables; adds overlay transition var. |
| source/components/datebadge/style.scss | Moves datebadge border extra into component-scoped CSS variable. |
| source/components/collection/style.scss | Moves collection padding extras into component-scoped CSS variables. |
| source/components/code/style.scss | Moves code border extra into component-scoped CSS variable. |
| source/components/card/style.scss | Moves card shadow/border/image-bg extras into component-scoped CSS variables. |
| source/components/button/style.scss | Moves button typography/colors/shadow extras into component-scoped CSS variables and uses them in size map. |
| source/components/brand/style.scss | Moves brand sizing/color extras into component-scoped CSS variables. |
| source/components/box/style.scss | Moves box shadow extras into component-scoped CSS variables. |
| source/components/block/style.scss | Moves block shadow/radius/overlay color extras into component-scoped CSS variables. |
| source/components/accordion/style.scss | Moves accordion border extra into component-scoped CSS variable. |
| source/components/acceptance/style.scss | Moves acceptance shadow/map-image extras into component-scoped CSS variables. |
| README.md | Removes documentation claiming tokens.create() supports extras/remapping. |
| .claude/skills/remove-tokens-extras/SKILL.md | Adds an internal skill doc describing how to perform the migration. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| --#{$_}--shadow: tokens.use($_, "shadow", 1); | ||
| --#{$_}--shadow-hover: tokens.use($_, "shadow", 2); | ||
| --#{$_}--radius: tokens.use($_, "border-radius", 1); | ||
| --#{$_}--color-text: tokens.get($_, "color--alpha-contrast"); | ||
| --#{$_}--color-background: tokens.get($_, "color--alpha"); | ||
| --#{$_}--color-overlay: rgb(from tokens.get($_, "color--alpha") r g b / 1); | ||
| --#{$_}--color-overlay-middle: rgba(from tokens.get($_, "color--alpha") r g b / .5); | ||
| --#{$_}--color-overlay-end: rgba(from tokens.get($_, "color--alpha") r g b / 0); | ||
| --#{$_}--color-secondary: tokens.get($_, "color--secondary"); | ||
| --#{$_}--color-hover-background: tokens.get($_, "color--alpha-border"); | ||
| --#{$_}--color-hover-overlay: tokens.get($_, "color--alpha-border"); |
There was a problem hiding this comment.
The values assigned to these new component-scoped custom properties use Sass functions (tokens.use/tokens.get) but aren’t interpolated. In Sass, custom property values are treated as plain CSS, so these tokens.* calls can be emitted literally instead of being evaluated, which would break the generated CSS. Interpolate the function results (and any nested tokens.get calls inside rgb/rgba) when assigning to --c-block--* variables.
| --#{$_}--shadow: tokens.use($_, "shadow", 1); | |
| --#{$_}--shadow-hover: tokens.use($_, "shadow", 2); | |
| --#{$_}--radius: tokens.use($_, "border-radius", 1); | |
| --#{$_}--color-text: tokens.get($_, "color--alpha-contrast"); | |
| --#{$_}--color-background: tokens.get($_, "color--alpha"); | |
| --#{$_}--color-overlay: rgb(from tokens.get($_, "color--alpha") r g b / 1); | |
| --#{$_}--color-overlay-middle: rgba(from tokens.get($_, "color--alpha") r g b / .5); | |
| --#{$_}--color-overlay-end: rgba(from tokens.get($_, "color--alpha") r g b / 0); | |
| --#{$_}--color-secondary: tokens.get($_, "color--secondary"); | |
| --#{$_}--color-hover-background: tokens.get($_, "color--alpha-border"); | |
| --#{$_}--color-hover-overlay: tokens.get($_, "color--alpha-border"); | |
| --#{$_}--shadow: #{tokens.use($_, "shadow", 1)}; | |
| --#{$_}--shadow-hover: #{tokens.use($_, "shadow", 2)}; | |
| --#{$_}--radius: #{tokens.use($_, "border-radius", 1)}; | |
| --#{$_}--color-text: #{tokens.get($_, "color--alpha-contrast")}; | |
| --#{$_}--color-background: #{tokens.get($_, "color--alpha")}; | |
| --#{$_}--color-overlay: rgb(from #{tokens.get($_, "color--alpha")} r g b / 1); | |
| --#{$_}--color-overlay-middle: rgba(from #{tokens.get($_, "color--alpha")} r g b / .5); | |
| --#{$_}--color-overlay-end: rgba(from #{tokens.get($_, "color--alpha")} r g b / 0); | |
| --#{$_}--color-secondary: #{tokens.get($_, "color--secondary")}; | |
| --#{$_}--color-hover-background: #{tokens.get($_, "color--alpha-border")}; | |
| --#{$_}--color-hover-overlay: #{tokens.get($_, "color--alpha-border")}; |
| --#{$_}--shadow: tokens.use($_, "shadow", 1); | ||
| --#{$_}--shadow-hover: tokens.use($_, "shadow", 1.5); |
There was a problem hiding this comment.
These new CSS custom properties assign Sass function calls (tokens.use) without interpolation. To ensure Sass evaluates the tokens.* calls rather than outputting them literally, interpolate the values when setting --c-acceptance--shadow and --c-acceptance--shadow-hover.
| --#{$_}--shadow: tokens.use($_, "shadow", 1); | |
| --#{$_}--shadow-hover: tokens.use($_, "shadow", 1.5); | |
| --#{$_}--shadow: #{tokens.use($_, "shadow", 1)}; | |
| --#{$_}--shadow-hover: #{tokens.use($_, "shadow", 1.5)}; |
|
|
||
| /* Component */ | ||
| .#{$_} { | ||
| --#{$_}--border: tokens.use($_, "border-width", 1) solid tokens.get($_, "color--surface-border"); |
There was a problem hiding this comment.
The new --c-accordion--border custom property value contains Sass function calls (tokens.use/tokens.get) but isn’t interpolated. Sass may treat custom property values as plain CSS and emit the tokens.* calls literally; interpolate the value so it compiles to a valid CSS expression.
| --#{$_}--border: tokens.use($_, "border-width", 1) solid tokens.get($_, "color--surface-border"); | |
| --#{$_}--border: #{tokens.use($_, "border-width", 1)} solid #{tokens.get($_, "color--surface-border")}; |
|
|
||
| /* Component */ | ||
| .#{$_} { | ||
| --#{$_}--logotype-height: tokens.use($_, "base", 6); |
There was a problem hiding this comment.
--c-header--logotype-height is being assigned the result of tokens.use(...) without interpolation. Interpolate this value so Sass evaluates tokens.use(...) and the computed height isn’t emitted as a literal function call in the final CSS.
| --#{$_}--logotype-height: tokens.use($_, "base", 6); | |
| --#{$_}--logotype-height: #{tokens.use($_, "base", 6)}; |
| --#{$_}--border: #{tokens.use($_, "border-width", 1)} solid #{tokens.get($_, "color--surface-border")}; | ||
| --#{$_}--background-color: #{tokens.get($_, "color--surface-alt")}; | ||
| --#{$_}--contrast-color: #{tokens.get($_, "color--surface-contrast")}; | ||
| --#{$_}--height: tokens.use($_, "base", 6); |
There was a problem hiding this comment.
--c-field--height is assigned using tokens.use(...) without interpolation. Since this value feeds into var(--c-field--height) and --c-field--height-computed, ensure tokens.use(...) is interpolated so it compiles to a valid CSS calc() rather than being output literally.
| --#{$_}--height: tokens.use($_, "base", 6); | |
| --#{$_}--height: #{tokens.use($_, "base", 6)}; |
| @include tokens.create($_, getComponentTokens($_)); | ||
|
|
||
| .#{$_} { | ||
| --#{$_}--border: 1px solid tokens.get($_, "color--surface-border"); |
There was a problem hiding this comment.
--c-code--border currently includes a literal tokens.get(...) call without interpolation, which can be emitted as-is into CSS. Interpolate the tokens.get(...) result so the custom property resolves to the intended var(--c-code--color--surface-border) reference.
| --#{$_}--border: 1px solid tokens.get($_, "color--surface-border"); | |
| --#{$_}--border: 1px solid #{tokens.get($_, "color--surface-border")}; |
| --#{$_}--line-height-caption: tokens.get($_, "line-height-base"); | ||
| --#{$_}--font-weight-bold: tokens.get($_, "font-weight-bold"); | ||
| --#{$_}--font-family-bold: tokens.get($_, "font-family-bold"); |
There was a problem hiding this comment.
These new custom properties use tokens.get(...) without interpolation (unlike the other token-based custom properties in this block). Interpolate tokens.get(...) here as well so Sass evaluates the function calls when generating the CSS for --c-image--line-height-caption / --c-image--font-weight-bold / --c-image--font-family-bold.
| --#{$_}--line-height-caption: tokens.get($_, "line-height-base"); | |
| --#{$_}--font-weight-bold: tokens.get($_, "font-weight-bold"); | |
| --#{$_}--font-family-bold: tokens.get($_, "font-family-bold"); | |
| --#{$_}--line-height-caption: #{tokens.get($_, "line-height-base")}; | |
| --#{$_}--font-weight-bold: #{tokens.get($_, "font-weight-bold")}; | |
| --#{$_}--font-family-bold: #{tokens.get($_, "font-family-bold")}; |
| @each $size in $sizes { | ||
| &.#{$_}--size-#{$size} { | ||
| $icon-size: var(--c-icon-size, #{tokens.get($_, "size-#{$size}")}); | ||
| $icon-size: var(--c-icon-size, var(--#{$_}--size-#{$size})); | ||
| font-size: $icon-size; | ||
|
|
||
| &::after { |
There was a problem hiding this comment.
Indentation inside the size modifier block is inconsistent (e.g., font-size: $icon-size; and the following &::after block are misaligned relative to the surrounding nesting). This makes the nesting structure hard to read and easy to mis-edit; please re-indent this block to match the rest of the file’s formatting.
| .#{$_} { | ||
| --#{$_}--font-size-caption: #{calc(tokens.get($_, "base-font-size")*pow(tokens.get($_, "font-size-scale-ratio"), -1))}; | ||
| --#{$_}--font-size-meta: #{tokens.get($_, "font-size-90")}; | ||
| --#{$_}--font-size-subtitle: #{tokens.get($_, "font-size-400")}; | ||
| --#{$_}--font-size-title: #{tokens.get($_, "font-size-500")}; |
There was a problem hiding this comment.
These derived --c-typography--* custom properties are declared only on .c-typography, but the file also styles plain h1–h6 elements using var(--c-typography--… ) with no fallback. Any heading that doesn’t carry (or inherit from an ancestor with) the .c-typography class will end up with invalid font-size/weight/line-height. Consider emitting these derived vars at :root (or add a :root block in addition to .c-typography) or add explicit fallbacks in the var(--c-typography--…) references; there are existing headings without .c-typography in the repo (e.g. source/components/code/examples/html.blade.php:4).
No description provided.