refactor: simplify tokens exposure

.claude/skills/remove-tokens-extras/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: remove-tokens-extras
+description: Remove the $extras parameter from tokens.create() in a component SCSS file, moving the extra tokens into the component selector as CSS custom properties. Usage: /remove-tokens-extras {ComponentPath}
+argument-hint: <ComponentPath>
+allowed-tools: Read, Edit, Bash
+---
+
+Remove the `$extras` (third argument) from a `tokens.create()` call in a component SCSS file, and move those extra tokens into the component selector as CSS custom properties.
+
+## Arguments
+
+Parse `$ARGUMENTS` as: `{ComponentPath}`
+
+- `ComponentPath` — path to the component SCSS file relative to the repo root (e.g. `source/components/button/style.scss` or `source/components/card/style.scss`).
+
+## Background: what you are fixing
+
+The `tokens.create` mixin previously accepted a third `$extras` map argument — a Sass map of custom key-value token pairs that were emitted as CSS custom properties. This third argument has been removed from the mixin. All extra tokens must now be declared as CSS custom properties directly inside the component selector.
+
+**Before:**
+```scss
+@include tokens.create($_, getComponentTokens($_), (
+    "border": tokens.use($_, "border-width", 1) solid tokens.get($_, "color--surface-border"),
+    "shadow": tokens.use($_, "shadow", 1),
+));
+
+.#{$_} {
+    border-top: tokens.get($_, "border");
+    filter: tokens.get($_, "shadow");
+}
+```
+
+**After:**
+```scss
+@include tokens.create($_, getComponentTokens($_));
+
+.#{$_} {
+    --#{$_}--border: tokens.use($_, "border-width", 1) solid tokens.get($_, "color--surface-border");
+    --#{$_}--shadow: tokens.use($_, "shadow", 1);
+    border-top: var(--#{$_}--border);
+    filter: var(--#{$_}--shadow);
+}
+```
+
+Key rules:
+- The extra tokens move to the **top** of the component selector block as `--#{$_}--key: value;`
+- Any `tokens.get($_, "key")` call that referenced an extras key becomes `var(--#{$_}--key)`
+- Global token references (`tokens.get($_, "color--surface")`) and `tokens.use(...)` calls that were NOT in extras remain unchanged
+
+## Step 1 — Read the file
+
+Read the full file at `{ComponentPath}`.
+
+## Step 2 — Identify the extras map
+
+Find the `tokens.create(...)` call and extract every key-value pair from the third argument (the Sass map). Note each key and its value expression exactly.
+
+## Step 3 — Find usages of extras keys
+
+Search the file for any `tokens.get($_, "{key}")` calls where `{key}` is one of the extras keys. These must be replaced with `var(--#{$_}--{key})`.
+
+Note: only `tokens.get` references to extras keys are affected. `tokens.use` calls that happen to use the same name are not extras references — leave them untouched.
+
+## Step 4 — Apply the changes
+
+Make these edits using the Edit tool:
+
+1. **Remove the extras map** from the `tokens.create(...)` call, leaving just:
+   ```scss
+   @include tokens.create($_, getComponentTokens($_));
+   ```
+
+2. **Add CSS custom properties** at the top of the component selector block (`.#{$_} {`):
+   ```scss
+   .#{$_} {
+       --#{$_}--key: value;
+       // ... rest of existing styles
+   ```
+
+3. **Replace each** `tokens.get($_, "{key}")` that referenced an extras key with `var(--#{$_}--{key})`.
+
+## Step 5 — Verify
+
+Run a quick grep to confirm no extras argument remains in `tokens.create` and no `tokens.get` references to the old extras keys remain:
+
+```sh
+grep -n 'tokens\.create' {ComponentPath}
+grep -n 'tokens\.get' {ComponentPath}
+```
+
+## Step 6 — Report
+
+Tell the user:
+- Which extras keys were moved and their values
+- Which `tokens.get` calls were replaced with `var(...)` references
+- Confirmation that `tokens.create` now has no third argument

README.md

@@ -231,8 +231,6 @@ card?.style.setProperty('--c-card--color--surface', '#1f2937');
   - Every consumed token must be listed in the component token manifest.
   - Companion tokens such as `-border` and `-alt` must be declared in global tokens and referenced explicitly.
   - Shadow internals (`shadow-color`, `shadow-amount`) must be listed directly.
-- **Extras/remapping support**:
-  - `tokens.create($prefix, $tokens, $extras, $inner)` supports computed extras and child-token remapping when needed.
 
 ### Architectural Limitations (important)
 

source/components/acceptance/style.scss

@@ -2,11 +2,13 @@
 
 $_: "c-acceptance";
 
-@include tokens.create($_, getComponentTokens($_), ("shadow": tokens.use($_, "shadow", 1),
-        "shadow-hover": tokens.use($_, "shadow", 1.5),
-        "map-image": url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iMjRweCIgdmlld0JveD0iMCAtOTYwIDk2MCA5NjAiIHdpZHRoPSIyNHB4IiBmaWxsPSIjZThlYWVkIj48cGF0aCBkPSJtNjAwLTEyMC0yNDAtODQtMTg2IDcycS0yMCA4LTM3LTQuNVQxMjAtMTcwdi01NjBxMC0xMyA3LjUtMjN0MjAuNS0xNWwyMTItNzIgMjQwIDg0IDE4Ni03MnEyMC04IDM3IDQuNXQxNyAzMy41djU2MHEwIDEzLTcuNSAyM1Q4MTItMTkybC0yMTIgNzJabS00MC05OHYtNDY4bC0xNjAtNTZ2NDY4bDE2MCA1NlptODAgMCAxMjAtNDB2LTQ3NGwtMTIwIDQ2djQ2OFptLTQ0MC0xMCAxMjAtNDZ2LTQ2OGwtMTIwIDQwdjQ3NFptNDQwLTQ1OHY0NjgtNDY4Wm0tMzIwLTU2djQ2OC00NjhaIi8+PC9zdmc+")));
+@include tokens.create($_, getComponentTokens($_));
 
 .#{$_} {
+    --#{$_}--shadow: tokens.use($_, "shadow", 1);
+    --#{$_}--shadow-hover: tokens.use($_, "shadow", 1.5);
+    --#{$_}--map-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGhlaWdodD0iMjRweCIgdmlld0JveD0iMCAtOTYwIDk2MCA5NjAiIHdpZHRoPSIyNHB4IiBmaWxsPSIjZThlYWVkIj48cGF0aCBkPSJtNjAwLTEyMC0yNDAtODQtMTg2IDcycS0yMCA4LTM3LTQuNVQxMjAtMTcwdi01NjBxMC0xMyA3LjUtMjN0MjAuNS0xNWwyMTItNzIgMjQwIDg0IDE4Ni03MnEyMC04IDM3IDQuNXQxNyAzMy41djU2MHEwIDEzLTcuNSAyM1Q4MTItMTkybC0yMTIgNzJabS00MC05OHYtNDY4bC0xNjAtNTZ2NDY4bDE2MCA1NlptODAgMCAxMjAtNDB2LTQ3NGwtMTIwIDQ2djQ2OFptLTQ0MC0xMCAxMjAtNDZ2LTQ2OGwtMTIwIDQwdjQ3NFptNDQwLTQ1OHY0NjgtNDY4Wm0tMzIwLTU2djQ2OC00NjhaIi8+PC9zdmc+");
+
     background-color: tokens.get($_, "color--surface");
     background-position: center;
     border-radius: tokens.use($_, "border-radius");
@@ -65,7 +67,7 @@ $_: "c-acceptance";
             background-size: contain;
             content: "";
             inset: 0;
-            mask-image: tokens.get($_, "map-image");
+            mask-image: var(--#{$_}--map-image);
             mask-position: center;
             mask-repeat: no-repeat;
             mask-size: contain;
@@ -105,7 +107,7 @@ $_: "c-acceptance";
         .#{$_}__modal-icon-play {
             color: tokens.get($_, "color--alpha-contrast");
             cursor: pointer;
-            filter: tokens.get($_, "shadow");
+            filter: var(--#{$_}--shadow);
             font-size: clamp(tokens.use($_, "base", 8), 10vw, tokens.use($_, "base", 10));
             left: 50%;
             position: absolute;
@@ -114,7 +116,7 @@ $_: "c-acceptance";
             transition: filter 100ms linear;
 
             &:hover {
-                filter: tokens.get($_, "shadow-hover");
+                filter: var(--#{$_}--shadow-hover);
                 color: tokens.get($_, "color--alpha-contrast-alt");
             }
 

source/components/accordion/style.scss

@@ -5,12 +5,11 @@
 $_: "c-accordion";
 
 /* Design tokens */
-@include tokens.create($_, getComponentTokens($_),
-    ("border": tokens.use($_, "border-width", 1) solid tokens.get($_, "color--surface-border"),
-    ));
+@include tokens.create($_, getComponentTokens($_));
 
 /* Component */
 .#{$_} {
+    --#{$_}--border: tokens.use($_, "border-width", 1) solid tokens.get($_, "color--surface-border");
     border-radius: inherit;
     corner-shape: inherit;
     contain: paint;
@@ -54,7 +53,7 @@ $_: "c-accordion";
     }
 
     .#{$_}__section+.#{$_}__section {
-        border-top: tokens.get($_, "border");
+        border-top: var(--#{$_}--border);
     }
 
     .#{$_}__button-wrapper {
@@ -107,12 +106,12 @@ $_: "c-accordion";
             border-radius: tokens.use($_, "border-radius");
             corner-shape: tokens.get($_, "corner-shape");
             filter: tokens.use($_, "shadow");
-            border: tokens.get($_, "border");
+            border: var(--#{$_}--border);
             width: 100%;
         }
 
         .#{$_}__content {
-            border-top: tokens.get($_, "border");
+            border-top: var(--#{$_}--border);
         }
     }
 

source/components/block/style.scss

@@ -3,49 +3,48 @@
 
 $_: "c-block";
 
-@include tokens.create($_, getComponentTokens($_),
-    ("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"),
-    ));
+@include tokens.create($_, getComponentTokens($_));
 
 .#{$_} {
+    --#{$_}--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");
     position: relative;
-    border-radius: tokens.get($_, "radius");
+    border-radius: var(--#{$_}--radius);
     corner-shape: tokens.get($_, "corner-shape");
-    filter: tokens.get($_, "shadow");
+    filter: var(--#{$_}--shadow);
     display: flex;
     justify-content: flex-end;
     flex-direction: row;
     background-position: center;
     background-size: cover;
-    background-color: tokens.get($_, "color-background");
+    background-color: var(--#{$_}--color-background);
     text-decoration: none;
 
     .#{$_}__heading {
         --inherit-font-size: tokens.get($_, "font-size-400");
     }
 
     .#{$_}__image {
-        border-radius: tokens.get($_, "radius");
+        border-radius: var(--#{$_}--radius);
         corner-shape: tokens.get($_, "corner-shape");
 
         .c-image__image {
-            border-radius: tokens.get($_, "radius");
+            border-radius: var(--#{$_}--radius);
             corner-shape: tokens.get($_, "corner-shape");
         }
     }
 
     .#{$_}__body {
-        background: linear-gradient(0deg, tokens.get($_, "color-overlay") 0%, tokens.get($_, "color-overlay-middle") 80%, tokens.get($_, "color-overlay-end") 100%);
+        background: linear-gradient(0deg, var(--#{$_}--color-overlay) 0%, var(--#{$_}--color-overlay-middle) 80%, var(--#{$_}--color-overlay-end) 100%);
         border-radius: inherit;
         corner-shape: inherit;
         padding: tokens.use($_, "base", 8) tokens.use($_, "base", 3) tokens.use($_, "base", 3) tokens.use($_, "base", 3);
@@ -78,12 +77,12 @@ $_: "c-block";
     .#{$_}__content,
     .#{$_}__secondarymeta {
         margin: 0;
-        color: tokens.get($_, "color-text");
+        color: var(--#{$_}--color-text);
         display: block;
     }
 
     .#{$_}__body {
-        color: tokens.get($_, "color-text");
+        color: var(--#{$_}--color-text);
     }
 
     &.#{$_}--ratio-1-1 {
@@ -121,7 +120,7 @@ $_: "c-block";
     &--svg-background {
         background-size: clamp(tokens.use($_, "base", 3), 50%, tokens.use($_, "base", 8));
         background-repeat: no-repeat;
-        background-color: tokens.get($_, "color-secondary");
+        background-color: var(--#{$_}--color-secondary);
     }
 }
 
@@ -134,14 +133,14 @@ a.#{$_} {
         inset: 0;
         content: "";
         transition: opacity 200ms;
-        background: tokens.get($_, "color-hover-overlay");
+        background: var(--#{$_}--color-hover-overlay);
         opacity: 0;
         z-index: 1000;
     }
 
     &:hover {
-        filter: tokens.get($_, "shadow-hover");
-        background-color: tokens.get($_, "color-hover-background");
+        filter: var(--#{$_}--shadow-hover);
+        background-color: var(--#{$_}--color-hover-background);
         color: inherit;
         transform: translateY(calc(0px - tokens.use($_, "base", 0.25)));
 

source/components/box/style.scss

@@ -4,17 +4,16 @@
 $_: "c-box";
 
 /* Design tokens */
-@include tokens.create($_, getComponentTokens($_),
-    ("shadow": tokens.use($_, "shadow", 1),
-        "shadow-hover": tokens.use($_, "shadow", 1.5),
-    ));
+@include tokens.create($_, getComponentTokens($_));
 
 /* Component */
 .#{$_} {
+    --#{$_}--shadow: #{tokens.use($_, "shadow", 1)};
+    --#{$_}--shadow-hover: #{tokens.use($_, "shadow", 1.5)};
     contain: layout;
     border-radius: tokens.use($_, "border-radius");
     corner-shape: tokens.get($_, "corner-shape");
-    filter: tokens.get($_, "shadow");
+    filter: var(--#{$_}--shadow);
     background-color: tokens.get($_, "color--primary");
     color: tokens.get($_, "color--primary-contrast");
     display: flex;
@@ -117,7 +116,7 @@ a.#{$_} {
 
     &:hover {
         transform: translateY(tokens.use($_, "space", -0.25));
-        filter: brightness(0.9) tokens.get($_, "shadow-hover");
+        filter: brightness(0.9) var(--#{$_}--shadow-hover);
 
         .#{$_}__heading {
             text-decoration: underline;

source/components/brand/style.scss

@@ -8,26 +8,25 @@
 $_: "c-brand";
 
 /* Design tokens */
-@include tokens.create($_, getComponentTokens($_), (
-    "height": tokens.use($_, "base", 12),
-    "gap": tokens.use($_, "space", 3),
-    "contrast-color": tokens.get($_, "color--primary"),
-    "font-size": tokens.use($_, "base", 4)
-));
+@include tokens.create($_, getComponentTokens($_));
 
 .c-brand {
+    --#{$_}--height: #{tokens.use($_, "base", 12)};
+    --#{$_}--gap: #{tokens.use($_, "space", 3)};
+    --#{$_}--contrast-color: #{tokens.get($_, "color--primary")};
+    --#{$_}--font-size: #{tokens.use($_, "base", 4)};
   .c-brand__logotype {
-    height: tokens.get($_, "height");
+    height: var(--#{$_}--height);
   }
 
   .c-brand__viewbox {
-    height: tokens.get($_, "height");
+    height: var(--#{$_}--height);
   }
 
   .c-brand__container {
-    height: tokens.get($_, "height");
+    height: var(--#{$_}--height);
     display: flex;
-    gap: tokens.get($_, "gap");
+    gap: var(--#{$_}--gap);
     align-items: center;
   }
 
@@ -36,8 +35,8 @@ $_: "c-brand";
     flex-direction: column;
     align-items: flex-start;
     height: 100%;
-    font-size: tokens.get($_, "font-size");
-    color: tokens.get($_, "contrast-color");
+    font-size: var(--#{$_}--font-size);
+    color: var(--#{$_}--contrast-color);
     line-height: 1.2;
     justify-content: center;
   }