@motion-proto/live-tokens 0.38.0 → 0.40.0

package/.claude/skills/live-tokens-pick-component/SKILL.md

@@ -11,10 +11,18 @@ For composing a page once you've picked components, see [[live-tokens-build-page
 
 ## Catalogue
 
-Action: `Button`. Input: `Input`. Selection: `SegmentedControl`, `TabBar`, `RadioButton`, `MenuSelect`, `Toggle`. Containers: `Card`, `CollapsibleSection`, `Dialog`. Messaging: `Callout`, `Notification`, `Tooltip`, `Badge`, `CornerBadge`. Display: `Table`, `Image`, `ImageLightbox`, `ProgressBar`, `SectionDivider`, `SideNavigation`, `CodeSnippet`.
+Action: `Button`, `IconButton`. Input: `Input`. Selection: `SegmentedControl`, `TabBar`, `RadioButton`, `MenuSelect`, `Toggle`. Containers: `Card`, `CollapsibleSection`, `Dialog`. Messaging: `Callout`, `Notification`, `Tooltip`, `Badge`, `CornerBadge`. Display: `Table`, `Image`, `ImageLightbox`, `ProgressBar`, `SectionDivider`, `SideNavigation`, `CodeSnippet`.
 
 `CodeSnippet` is for a single-line command or value the user is meant to copy and paste back into a terminal (install commands, generated keys, ids). Click-to-copy with a brief "Copied" popover. Use it whenever your page asks the reader to *run* something, rather than just *read* it.
 
+## Action family: Button vs IconButton
+
+Both trigger an action and share the same six variants (primary, secondary, outline, success, danger, warning), three states (default, hover, disabled) and two sizes (default, small). They differ only in content.
+
+- `Button` carries a text label, optionally with a leading or trailing icon. Use it whenever the action needs a word to be unambiguous.
+- `IconButton` is icon-only and square. Use it for compact, space-constrained actions whose meaning is obvious from the glyph alone (toolbar controls, close/edit/delete affordances, card overflow menus). It has no text slot, so an `ariaLabel` is required for accessibility.
+- **Don't reach for `IconButton` when the icon's meaning isn't self-evident.** A labelled `Button` (or a `Button` with an icon) avoids the guessing game.
+
 ## Single-selection family: SegmentedControl vs TabBar vs RadioButton vs MenuSelect
 
 All four pick one option from a set. The right one depends on **option count**, **whether the selection changes what's rendered below**, and **how much visual weight** you want.

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 0.40.0 — New IconButton component
+
+### Added
+
+- **`IconButton`, an icon-only sibling of `Button`.** It shares Button's six
+  variants (primary, secondary, outline, success, danger, warning), three states
+  (default, hover, disabled), and two sizes (default, small), but renders a
+  single icon with no text. It is square (symmetric padding plus `aspect-ratio`),
+  exposes the icon colour as a first-class per-variant, per-state token, and
+  drops Button's text-typography properties. Its tokens live in their own
+  `--iconbutton-*` namespace, so styling it never affects Button. Because the
+  control has no visible text, `ariaLabel` is required. Editable in the editor
+  under Components, with the same linked base block (padding, radius, border
+  width, icon size) that links across variants.
+
+### Notes
+
+- Additive only. No token renames or `tokens.css` migration, so existing
+  consumers are unaffected; the new component ships its defaults in its
+  `:global(:root)` block like every other.
+
+## 0.39.0 — One unified palette model (no gray "mode")
+
+### Changed (breaking)
+
+- **The chromatic/gray palette split collapses into a single OKLCH (Lightness /
+  Chroma / Hue) model.** A neutral is no longer a special "mode"; it is an
+  ordinary low-chroma palette with calm defaults (a low but non-zero base chroma,
+  a wider neutral lightness ramp). One derivation path (`computePaletteColor`)
+  now serves every palette, and the Neutral / Alternate editors show the same
+  full L/C/H picker, lock-to-500 toggle, and derived-scale snapping as accents.
+  `PaletteConfig` drops its gray vocabulary (`tintHue`, `tintChroma`,
+  `grayLightnessCurve`, `graySaturationCurve`); `baseColor`, `lightnessCurve`,
+  and `saturationCurve` are now universal, and the internal `mode` prop is
+  removed from the palette editors.
+- **Token names are unchanged** — this is a theme-config schema change, not a
+  `tokens.css` migration, so no consumer CSS or token references are affected.
+  The shipped `default.json` was regenerated; the neutral shift is sub-1-LSB per
+  channel and every derived `--surface-*` / `--text-*` / `--color-*` token is
+  byte-identical.
+
+### Fixed
+
+- **A component's surface control no longer vanishes when its fill is a flat
+  colour.** `componentGradientSource` returned `undefined` for any non-gradient
+  alias and `GradientEditor` renders only `{#if gradient}`, so the surface editor
+  disappeared whenever a fill was a plain colour (e.g. SectionDivider's default
+  transparent). The editor now synthesizes a none/solid single-stop snapshot from
+  a flat (or absent) alias so the type picker always renders, and promotes the
+  flat alias to a real gradient on first edit. SectionDivider's section heading is
+  renamed "Background" → "Surface" to match Panel and disambiguate it from the
+  preview backdrop control.
+- **Palette colour overrides now apply live while you drag.** A new Text /
+  Surfaces / Borders override previously reached neither the live page nor the
+  preview swatch until commit — `handleColorChange` only wrote to the store when
+  the key was already an override. Every drag tick now writes (the open session
+  collapses to one undo entry; cancel/confirm clean up no-ops), and the per-step
+  hex text tracks the live colour too.
+
+### Migration
+
+- **Consumer themes migrate automatically on load.** `unifyGrayPalettes` (run in
+  `loadFromFile` after `renamePrimaryPaletteKey`) close-maps existing neutrals to
+  the unified form: `baseColor` snaps to the effective step-500 colour (preserving
+  the subtle tint and the neutral lightness ramp), the saturation curve becomes
+  flat-100, and the palette is locked to base. Every palette drops the four
+  vestigial gray fields, and the `gray-lightness` / `gray-saturation` curve-offset
+  keys fold into `lightness` / `saturation`. Default and flat-saturation neutrals
+  are visually identical; only a hand-shaped gray *saturation* curve migrates
+  approximately and may want a quick manual retune.
+
 ## 0.38.0 — Overridable scroll reset for smooth-scroll hosts
 
 ### Added

package/dist-plugin/index.cjs

@@ -192,16 +192,16 @@ function sampleCurve(anchors, xPos) {
 
 // src/editor/core/palettes/paletteDerivation.ts
 var PALETTE_SPECS = [
-  { label: "Neutral", cssNamespace: "neutral", mode: "gray", initialColor: "#808080" },
-  { label: "Alternate", cssNamespace: "alternate", mode: "gray", initialColor: "#808080" },
-  { label: "Background", cssNamespace: "canvas", mode: "chromatic", emptySelector: true, initialColor: "#1a1a2e" },
-  { label: "Brand", cssNamespace: "brand", mode: "chromatic", initialColor: "#c93636" },
-  { label: "Accent", cssNamespace: "accent", mode: "chromatic", initialColor: "#f49e0b" },
-  { label: "Special", cssNamespace: "special", mode: "chromatic", initialColor: "#8b5cf6" },
-  { label: "Info", cssNamespace: "info", mode: "chromatic", initialColor: "#3077e8" },
-  { label: "Success", cssNamespace: "success", mode: "chromatic", initialColor: "#21c45d" },
-  { label: "Warning", cssNamespace: "warning", mode: "chromatic", initialColor: "#e66e1a" },
-  { label: "Danger", cssNamespace: "danger", mode: "chromatic", initialColor: "#e8304f" }
+  { label: "Neutral", cssNamespace: "neutral", neutral: true, initialColor: "#70787e" },
+  { label: "Alternate", cssNamespace: "alternate", neutral: true, initialColor: "#817b78" },
+  { label: "Background", cssNamespace: "canvas", emptySelector: true, initialColor: "#1a1a2e" },
+  { label: "Brand", cssNamespace: "brand", initialColor: "#c93636" },
+  { label: "Accent", cssNamespace: "accent", initialColor: "#f49e0b" },
+  { label: "Special", cssNamespace: "special", initialColor: "#8b5cf6" },
+  { label: "Info", cssNamespace: "info", initialColor: "#3077e8" },
+  { label: "Success", cssNamespace: "success", initialColor: "#21c45d" },
+  { label: "Warning", cssNamespace: "warning", initialColor: "#e66e1a" },
+  { label: "Danger", cssNamespace: "danger", initialColor: "#e8304f" }
 ];
 var PALETTE_STEPS = [
   { label: "100" },
@@ -216,19 +216,6 @@ var PALETTE_STEPS = [
   { label: "900" },
   { label: "950" }
 ];
-var GRAY_STEPS = [
-  { label: "100" },
-  { label: "200" },
-  { label: "300" },
-  { label: "400" },
-  { label: "500" },
-  { label: "600" },
-  { label: "700" },
-  { label: "800" },
-  { label: "850" },
-  { label: "900" },
-  { label: "950" }
-];
 var SCALES = [
   {
     title: "Surfaces",
@@ -268,9 +255,6 @@ var SCALES = [
 ];
 var DEFAULT_PALETTE_LIGHTNESS = () => [makeAnchor(0, 95, 5), makeAnchor(100, 8, 5)];
 var DEFAULT_PALETTE_SATURATION = () => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)];
-var DEFAULT_GRAY_LIGHTNESS = () => [makeAnchor(0, 92, 5), makeAnchor(100, 3, 5)];
-var DEFAULT_GRAY_SATURATION = () => [makeAnchor(0, 20, 30), makeAnchor(100, 20, 30)];
-var DEFAULT_TINT_CHROMA = 0.04;
 var defaultScaleCurves = {
   Surfaces: {
     lightness: () => [makeAnchor(0, 15, 5), makeAnchor(100, 47, 5)],
@@ -288,9 +272,6 @@ var defaultScaleCurves = {
 function paletteStepKey(label) {
   return `Palette-${label}`;
 }
-function grayStepKey(label) {
-  return `gray-${label}`;
-}
 function stepKey(scaleTitle, stepName) {
   return `${scaleTitle}-${stepName}`;
 }
@@ -306,16 +287,6 @@ function computePaletteColor(index, base, lightnessCurve, saturationCurve, curve
   const clamped = gamutClamp(targetL, targetC, h);
   return oklchToHex(clamped.l, clamped.c, clamped.h);
 }
-function computeGrayColor(index, hue, chroma, grayLightnessCurve, graySaturationCurve, curveOffset) {
-  const xPos = stepIndexToX(index, GRAY_STEPS.length);
-  const lOff = curveOffset["gray-lightness"] ?? 0;
-  const sOff = curveOffset["gray-saturation"] ?? 0;
-  const targetL = Math.max(0, Math.min(100, sampleCurve(grayLightnessCurve, xPos) + lOff)) / 100;
-  const satMul = Math.max(0, Math.min(2, (sampleCurve(graySaturationCurve, xPos) + sOff) / 100));
-  const targetC = chroma * satMul;
-  const clamped = gamutClamp(targetL, targetC, hue);
-  return oklchToHex(clamped.l, clamped.c, clamped.h);
-}
 function computeDerivedColor(step, base, scaleTitle, scaleCurves, curveOffset) {
   const scale = SCALES.find((s) => s.title === scaleTitle);
   const idx = scale.steps.indexOf(step);
@@ -361,36 +332,18 @@ function derivePaletteVars(spec, config) {
   const overrides = config.overrides ?? {};
   const curveOffset = config.curveOffset ?? {};
   const scaleCurves = config.scaleCurves ?? {};
-  let baseForScales;
-  if (spec.mode === "gray") {
-    const grayLightnessCurve = config.grayLightnessCurve ?? DEFAULT_GRAY_LIGHTNESS();
-    const graySaturationCurve = config.graySaturationCurve ?? DEFAULT_GRAY_SATURATION();
-    const tintHue = config.tintHue ?? 240;
-    const tintChroma = config.tintChroma ?? DEFAULT_TINT_CHROMA;
-    let gray500 = "#808080";
-    GRAY_STEPS.forEach((step, index) => {
-      const k = grayStepKey(step.label);
-      const hex = computeGrayColor(index, tintHue, tintChroma, grayLightnessCurve, graySaturationCurve, curveOffset);
-      const effective = k in overrides ? overrides[k] : hex;
-      out[`--color-${spec.cssNamespace}-${step.label}`] = effective;
-      if (step.label === "500") gray500 = hex;
-    });
-    baseForScales = gray500;
-  } else {
-    const lightnessCurve = config.lightnessCurve ?? DEFAULT_PALETTE_LIGHTNESS();
-    const saturationCurve = config.saturationCurve ?? DEFAULT_PALETTE_SATURATION();
-    PALETTE_STEPS.forEach((ps, index) => {
-      const k = paletteStepKey(ps.label);
-      const hex = computePaletteColor(index, baseColor, lightnessCurve, saturationCurve, curveOffset);
-      const effective = k in overrides ? overrides[k] : hex;
-      out[`--color-${spec.cssNamespace}-${ps.label}`] = effective;
-    });
-    baseForScales = baseColor;
-  }
+  const lightnessCurve = config.lightnessCurve ?? DEFAULT_PALETTE_LIGHTNESS();
+  const saturationCurve = config.saturationCurve ?? DEFAULT_PALETTE_SATURATION();
+  PALETTE_STEPS.forEach((ps, index) => {
+    const k = paletteStepKey(ps.label);
+    const hex = computePaletteColor(index, baseColor, lightnessCurve, saturationCurve, curveOffset);
+    const effective = k in overrides ? overrides[k] : hex;
+    out[`--color-${spec.cssNamespace}-${ps.label}`] = effective;
+  });
   for (const scale of SCALES) {
     for (const step of scale.steps) {
       const k = stepKey(scale.title, step.name);
-      const hex = k in overrides ? overrides[k] : computeDerivedColor(step, baseForScales, scale.title, scaleCurves, curveOffset);
+      const hex = k in overrides ? overrides[k] : computeDerivedColor(step, baseColor, scale.title, scaleCurves, curveOffset);
       const varName = scaleToCssVar(scale.title, step.name, spec.cssNamespace);
       if (varName) out[varName] = hex;
     }
@@ -451,12 +404,7 @@ function reconcilePalettesFromCssVars(palettes, cssVars) {
       const anchorHex = cssVars[`--color-${spec.cssNamespace}-500`];
       if (anchorHex && HEX_RE.test(anchorHex.trim())) {
         const hex = anchorHex.trim();
-        if (spec.mode === "gray") {
-          const { c, h } = hexToOklch(hex);
-          next[spec.label] = { ...current, tintHue: h, tintChroma: c, _imported: false };
-        } else {
-          next[spec.label] = { ...current, baseColor: hex, _imported: false };
-        }
+        next[spec.label] = { ...current, baseColor: hex, _imported: false };
         snapped.add(spec.label);
       } else {
         next[spec.label] = { ...current, _imported: false };

package/dist-plugin/index.js

@@ -151,16 +151,16 @@ function sampleCurve(anchors, xPos) {
 
 // src/editor/core/palettes/paletteDerivation.ts
 var PALETTE_SPECS = [
-  { label: "Neutral", cssNamespace: "neutral", mode: "gray", initialColor: "#808080" },
-  { label: "Alternate", cssNamespace: "alternate", mode: "gray", initialColor: "#808080" },
-  { label: "Background", cssNamespace: "canvas", mode: "chromatic", emptySelector: true, initialColor: "#1a1a2e" },
-  { label: "Brand", cssNamespace: "brand", mode: "chromatic", initialColor: "#c93636" },
-  { label: "Accent", cssNamespace: "accent", mode: "chromatic", initialColor: "#f49e0b" },
-  { label: "Special", cssNamespace: "special", mode: "chromatic", initialColor: "#8b5cf6" },
-  { label: "Info", cssNamespace: "info", mode: "chromatic", initialColor: "#3077e8" },
-  { label: "Success", cssNamespace: "success", mode: "chromatic", initialColor: "#21c45d" },
-  { label: "Warning", cssNamespace: "warning", mode: "chromatic", initialColor: "#e66e1a" },
-  { label: "Danger", cssNamespace: "danger", mode: "chromatic", initialColor: "#e8304f" }
+  { label: "Neutral", cssNamespace: "neutral", neutral: true, initialColor: "#70787e" },
+  { label: "Alternate", cssNamespace: "alternate", neutral: true, initialColor: "#817b78" },
+  { label: "Background", cssNamespace: "canvas", emptySelector: true, initialColor: "#1a1a2e" },
+  { label: "Brand", cssNamespace: "brand", initialColor: "#c93636" },
+  { label: "Accent", cssNamespace: "accent", initialColor: "#f49e0b" },
+  { label: "Special", cssNamespace: "special", initialColor: "#8b5cf6" },
+  { label: "Info", cssNamespace: "info", initialColor: "#3077e8" },
+  { label: "Success", cssNamespace: "success", initialColor: "#21c45d" },
+  { label: "Warning", cssNamespace: "warning", initialColor: "#e66e1a" },
+  { label: "Danger", cssNamespace: "danger", initialColor: "#e8304f" }
 ];
 var PALETTE_STEPS = [
   { label: "100" },
@@ -175,19 +175,6 @@ var PALETTE_STEPS = [
   { label: "900" },
   { label: "950" }
 ];
-var GRAY_STEPS = [
-  { label: "100" },
-  { label: "200" },
-  { label: "300" },
-  { label: "400" },
-  { label: "500" },
-  { label: "600" },
-  { label: "700" },
-  { label: "800" },
-  { label: "850" },
-  { label: "900" },
-  { label: "950" }
-];
 var SCALES = [
   {
     title: "Surfaces",
@@ -227,9 +214,6 @@ var SCALES = [
 ];
 var DEFAULT_PALETTE_LIGHTNESS = () => [makeAnchor(0, 95, 5), makeAnchor(100, 8, 5)];
 var DEFAULT_PALETTE_SATURATION = () => [makeAnchor(0, 100, 30), makeAnchor(100, 100, 30)];
-var DEFAULT_GRAY_LIGHTNESS = () => [makeAnchor(0, 92, 5), makeAnchor(100, 3, 5)];
-var DEFAULT_GRAY_SATURATION = () => [makeAnchor(0, 20, 30), makeAnchor(100, 20, 30)];
-var DEFAULT_TINT_CHROMA = 0.04;
 var defaultScaleCurves = {
   Surfaces: {
     lightness: () => [makeAnchor(0, 15, 5), makeAnchor(100, 47, 5)],
@@ -247,9 +231,6 @@ var defaultScaleCurves = {
 function paletteStepKey(label) {
   return `Palette-${label}`;
 }
-function grayStepKey(label) {
-  return `gray-${label}`;
-}
 function stepKey(scaleTitle, stepName) {
   return `${scaleTitle}-${stepName}`;
 }
@@ -265,16 +246,6 @@ function computePaletteColor(index, base, lightnessCurve, saturationCurve, curve
   const clamped = gamutClamp(targetL, targetC, h);
   return oklchToHex(clamped.l, clamped.c, clamped.h);
 }
-function computeGrayColor(index, hue, chroma, grayLightnessCurve, graySaturationCurve, curveOffset) {
-  const xPos = stepIndexToX(index, GRAY_STEPS.length);
-  const lOff = curveOffset["gray-lightness"] ?? 0;
-  const sOff = curveOffset["gray-saturation"] ?? 0;
-  const targetL = Math.max(0, Math.min(100, sampleCurve(grayLightnessCurve, xPos) + lOff)) / 100;
-  const satMul = Math.max(0, Math.min(2, (sampleCurve(graySaturationCurve, xPos) + sOff) / 100));
-  const targetC = chroma * satMul;
-  const clamped = gamutClamp(targetL, targetC, hue);
-  return oklchToHex(clamped.l, clamped.c, clamped.h);
-}
 function computeDerivedColor(step, base, scaleTitle, scaleCurves, curveOffset) {
   const scale = SCALES.find((s) => s.title === scaleTitle);
   const idx = scale.steps.indexOf(step);
@@ -320,36 +291,18 @@ function derivePaletteVars(spec, config) {
   const overrides = config.overrides ?? {};
   const curveOffset = config.curveOffset ?? {};
   const scaleCurves = config.scaleCurves ?? {};
-  let baseForScales;
-  if (spec.mode === "gray") {
-    const grayLightnessCurve = config.grayLightnessCurve ?? DEFAULT_GRAY_LIGHTNESS();
-    const graySaturationCurve = config.graySaturationCurve ?? DEFAULT_GRAY_SATURATION();
-    const tintHue = config.tintHue ?? 240;
-    const tintChroma = config.tintChroma ?? DEFAULT_TINT_CHROMA;
-    let gray500 = "#808080";
-    GRAY_STEPS.forEach((step, index) => {
-      const k = grayStepKey(step.label);
-      const hex = computeGrayColor(index, tintHue, tintChroma, grayLightnessCurve, graySaturationCurve, curveOffset);
-      const effective = k in overrides ? overrides[k] : hex;
-      out[`--color-${spec.cssNamespace}-${step.label}`] = effective;
-      if (step.label === "500") gray500 = hex;
-    });
-    baseForScales = gray500;
-  } else {
-    const lightnessCurve = config.lightnessCurve ?? DEFAULT_PALETTE_LIGHTNESS();
-    const saturationCurve = config.saturationCurve ?? DEFAULT_PALETTE_SATURATION();
-    PALETTE_STEPS.forEach((ps, index) => {
-      const k = paletteStepKey(ps.label);
-      const hex = computePaletteColor(index, baseColor, lightnessCurve, saturationCurve, curveOffset);
-      const effective = k in overrides ? overrides[k] : hex;
-      out[`--color-${spec.cssNamespace}-${ps.label}`] = effective;
-    });
-    baseForScales = baseColor;
-  }
+  const lightnessCurve = config.lightnessCurve ?? DEFAULT_PALETTE_LIGHTNESS();
+  const saturationCurve = config.saturationCurve ?? DEFAULT_PALETTE_SATURATION();
+  PALETTE_STEPS.forEach((ps, index) => {
+    const k = paletteStepKey(ps.label);
+    const hex = computePaletteColor(index, baseColor, lightnessCurve, saturationCurve, curveOffset);
+    const effective = k in overrides ? overrides[k] : hex;
+    out[`--color-${spec.cssNamespace}-${ps.label}`] = effective;
+  });
   for (const scale of SCALES) {
     for (const step of scale.steps) {
       const k = stepKey(scale.title, step.name);
-      const hex = k in overrides ? overrides[k] : computeDerivedColor(step, baseForScales, scale.title, scaleCurves, curveOffset);
+      const hex = k in overrides ? overrides[k] : computeDerivedColor(step, baseColor, scale.title, scaleCurves, curveOffset);
       const varName = scaleToCssVar(scale.title, step.name, spec.cssNamespace);
       if (varName) out[varName] = hex;
     }
@@ -410,12 +363,7 @@ function reconcilePalettesFromCssVars(palettes, cssVars) {
       const anchorHex = cssVars[`--color-${spec.cssNamespace}-500`];
       if (anchorHex && HEX_RE.test(anchorHex.trim())) {
         const hex = anchorHex.trim();
-        if (spec.mode === "gray") {
-          const { c, h } = hexToOklch(hex);
-          next[spec.label] = { ...current, tintHue: h, tintChroma: c, _imported: false };
-        } else {
-          next[spec.label] = { ...current, baseColor: hex, _imported: false };
-        }
+        next[spec.label] = { ...current, baseColor: hex, _imported: false };
         snapped.add(spec.label);
       } else {
         next[spec.label] = { ...current, _imported: false };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [

package/src/editor/component-editor/IconButtonEditor.svelte

@@ -0,0 +1,175 @@
+<script module lang="ts">
+  import { buildSiblings } from './scaffolding/siblings';
+  import type { Token } from './scaffolding/types';
+
+  export const component = 'iconbutton';
+
+  const variants = ['primary', 'secondary', 'outline', 'success', 'danger', 'warning'] as const;
+  type Variant = typeof variants[number];
+  const stateNames = ['default', 'hover', 'disabled'] as const;
+  type StateName = typeof stateNames[number];
+  function statePrefix(v: Variant, s: StateName): string {
+    return s === 'default' ? `--iconbutton-${v}` : `--iconbutton-${v}-${s}`;
+  }
+
+  // Shape. Icon-only, so unlike Button there is no text typography here — the
+  // base part carries only frame geometry, which links across variants.
+  function variantBaseTokens(v: Variant): Token[] {
+    return [
+      { label: 'padding', canBeLinked: true, groupKey: 'padding', variable: `--iconbutton-${v}-padding` },
+      { label: 'padding-top', canBeLinked: true, groupKey: 'padding-top', variable: `--iconbutton-${v}-padding-top`, hidden: true },
+      { label: 'padding-right', canBeLinked: true, groupKey: 'padding-right', variable: `--iconbutton-${v}-padding-right`, hidden: true },
+      { label: 'padding-bottom', canBeLinked: true, groupKey: 'padding-bottom', variable: `--iconbutton-${v}-padding-bottom`, hidden: true },
+      { label: 'padding-left', canBeLinked: true, groupKey: 'padding-left', variable: `--iconbutton-${v}-padding-left`, hidden: true },
+      { label: 'corner radius', canBeLinked: true, groupKey: 'radius', variable: `--iconbutton-${v}-radius` },
+      { label: 'border width', canBeLinked: true, groupKey: 'border-width', variable: `--iconbutton-${v}-border-width` },
+      { label: 'icon size', canBeLinked: true, groupKey: 'icon-size', variable: `--iconbutton-${v}-icon-size` },
+    ];
+  }
+
+  function variantStateTokens(v: Variant, s: StateName): Token[] {
+    const iconVar = s === 'default' ? `--iconbutton-${v}-icon` : `--iconbutton-${v}-${s}-icon`;
+    return [
+      { label: 'surface color', groupKey: 'surface', variable: `${statePrefix(v, s)}-surface` },
+      { label: 'border color', groupKey: 'border', variable: `${statePrefix(v, s)}-border` },
+      { label: 'icon color', groupKey: 'icon', variable: iconVar },
+    ];
+  }
+
+  // Outline is the only variant that paints a surface tint on :active.
+  const outlineActiveTokens: Token[] = [
+    { label: 'surface color', groupKey: 'surface', variable: '--iconbutton-outline-active-surface' },
+  ];
+
+  function variantStates(v: Variant): Record<string, Token[]> {
+    const out: Record<string, Token[]> = {};
+    out.base = variantBaseTokens(v);
+    out.default = variantStateTokens(v, 'default');
+    out.hover = variantStateTokens(v, 'hover');
+    if (v === 'outline') out.active = outlineActiveTokens;
+    out.disabled = variantStateTokens(v, 'disabled');
+    return out;
+  }
+
+  // Small-size schema. One shared spec across all variants (matches the runtime
+  // `.small` rule, which is variant-agnostic). Per-side padding rows are hidden
+  // and surface only when the editor splits the padding control.
+  const smallStates: Record<string, Token[]> = {
+    small: [
+      { label: 'padding', groupKey: 'small-padding', variable: '--iconbutton-small-padding' },
+      { label: 'padding-top', groupKey: 'small-padding-top', variable: '--iconbutton-small-padding-top', hidden: true },
+      { label: 'padding-right', groupKey: 'small-padding-right', variable: '--iconbutton-small-padding-right', hidden: true },
+      { label: 'padding-bottom', groupKey: 'small-padding-bottom', variable: '--iconbutton-small-padding-bottom', hidden: true },
+      { label: 'padding-left', groupKey: 'small-padding-left', variable: '--iconbutton-small-padding-left', hidden: true },
+      { label: 'icon size', groupKey: 'small-icon-size', variable: '--iconbutton-small-icon-size' },
+    ],
+  };
+  const smallTokensFlat: Token[] = Object.values(smallStates).flat();
+
+  export const allTokens: Token[] = [
+    ...variants.flatMap((v) => Object.values(variantStates(v)).flat()),
+    ...smallTokensFlat,
+  ];
+
+  // Frame geometry lives under each variant's "base" part and links across
+  // variants from there. Small tokens stay in their own namespace.
+  const linkableContexts = new Map<string, string>(
+    variants.flatMap((v) => [
+      [`--iconbutton-${v}-padding`, `${v} base`] as const,
+      [`--iconbutton-${v}-radius`, `${v} base`] as const,
+      [`--iconbutton-${v}-border-width`, `${v} base`] as const,
+      [`--iconbutton-${v}-icon-size`, `${v} base`] as const,
+    ]),
+  );
+
+  const variantOptions = variants.map((v) => ({ value: v, label: v.charAt(0).toUpperCase() + v.slice(1) }));
+
+  const previewIcons: Record<Variant, string> = {
+    primary: 'fas fa-star',
+    secondary: 'fas fa-gear',
+    outline: 'fas fa-pen',
+    success: 'fas fa-check',
+    danger: 'fas fa-trash',
+    warning: 'fas fa-triangle-exclamation',
+  };
+</script>
+
+<script lang="ts">
+  import IconButton from '../../system/components/IconButton.svelte';
+  import VariantGroup from './scaffolding/VariantGroup.svelte';
+  import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
+  import { editorState } from '../core/store/editorStore';
+  import { computeLinkedBlock, withLinkedDisabled } from './scaffolding/linkedBlock';
+
+  let previewSize = $state<'default' | 'small'>('default');
+
+  let linked = $derived(computeLinkedBlock(component, linkableContexts, allTokens, $editorState));
+
+  let visibleVariantStates = $derived((v: Variant) => Object.fromEntries(
+    Object.entries(variantStates(v)).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),
+  ) as Record<string, Token[]>);
+
+  let visibleSmallStates = $derived(Object.fromEntries(
+    Object.entries(smallStates).map(([name, list]) => [name, withLinkedDisabled(list, linked.varSet)]),
+  ) as Record<string, Token[]>);
+
+  // At small size, no variant strip — the small spec is shared across all
+  // variants, so the strip would have nothing to navigate between.
+  let baseVariantOptions = $derived(previewSize === 'small' ? [] : variantOptions);
+</script>
+
+{#snippet sizeAction()}
+  <label>
+    <span>Size</span>
+    <select bind:value={previewSize}>
+      <option value="default">Default</option>
+      <option value="small">Small</option>
+    </select>
+  </label>
+{/snippet}
+
+<ComponentEditorBase {component} title="Icon Button" description="Icon-only button with the same variants, states and sizes as Button." tokens={allTokens} {linked} variants={baseVariantOptions}>
+  {#if previewSize === 'default'}
+    {#each variants as v}
+      <VariantGroup
+        name={v}
+        title={v.charAt(0).toUpperCase() + v.slice(1)}
+        states={visibleVariantStates(v)}
+        {component}
+        siblings={buildSiblings(variants, v, variantStates)}
+        previewActions={sizeAction}
+      >
+        {#snippet children({ activeState })}
+          {@const forceClass = activeState === 'hover' ? 'force-hover' : ''}
+          {@const isDisabled = activeState === 'disabled'}
+          <IconButton variant={v} icon={previewIcons[v]} ariaLabel={`${v} action`} disabled={isDisabled} class={forceClass} />
+        {/snippet}
+      </VariantGroup>
+    {/each}
+  {:else}
+    <VariantGroup
+      name="small"
+      title="Small"
+      states={visibleSmallStates}
+      {component}
+      previewActions={sizeAction}
+    >
+      {#snippet children()}
+        <div class="small-preview">
+          {#each variants as v}
+            <IconButton variant={v} size="small" icon={previewIcons[v]} ariaLabel={`${v} action`} />
+          {/each}
+        </div>
+      {/snippet}
+    </VariantGroup>
+  {/if}
+</ComponentEditorBase>
+
+<style>
+  .small-preview {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-12);
+    align-items: center;
+  }
+</style>

package/src/editor/component-editor/SectionDividerEditor.svelte

@@ -428,7 +428,7 @@
       {#snippet compositeControls(_stateName)}
         <div class="gradient-bg-section">
           <GradientEditor
-            sectionLabel="Background"
+            sectionLabel="Surface"
             source={gradientSources[v.key]}
             stopIdPrefix={`sectiondivider-${v.key}`}
             familyFilter={getColorFamily(v.key)}

package/src/editor/component-editor/registry.ts

@@ -6,6 +6,7 @@ import BadgeEditor, { allTokens as badgeTokens } from './BadgeEditor.svelte';
 import CalloutEditor, { allTokens as calloutTokens } from './CalloutEditor.svelte';
 import CornerBadgeEditor, { allTokens as cornerBadgeTokens } from './CornerBadgeEditor.svelte';
 import ButtonEditor, { allTokens as buttonTokens } from './ButtonEditor.svelte';
+import IconButtonEditor, { allTokens as iconButtonTokens } from './IconButtonEditor.svelte';
 import CardEditor, { allTokens as cardTokens, intrinsics as cardIntrinsics } from './CardEditor.svelte';
 import CodeSnippetEditor, { allTokens as codeSnippetTokens } from './CodeSnippetEditor.svelte';
 import CollapsibleSectionEditor, { allTokens as collapsibleSectionTokens } from './CollapsibleSectionEditor.svelte';
@@ -31,6 +32,7 @@ import TooltipEditor, { allTokens as tooltipTokens } from './TooltipEditor.svelt
 type BuiltInComponentId =
   | 'segmentedcontrol'
   | 'button'
+  | 'iconbutton'
   | 'notification'
   | 'dialog'
   | 'radiobutton'
@@ -108,6 +110,15 @@ const builtInRegistry: Readonly<Record<BuiltInComponentId, RegistryEntry>> = Obj
     schema: buttonTokens,
     origin: 'system',
   },
+  iconbutton: {
+    id: 'iconbutton',
+    label: 'Icon Button',
+    icon: 'fas fa-square-plus',
+    sourceFile: 'src/system/components/IconButton.svelte',
+    editorComponent: IconButtonEditor,
+    schema: iconButtonTokens,
+    origin: 'system',
+  },
   notification: {
     id: 'notification',
     label: 'Notification',