@motion-proto/live-tokens 0.39.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,26 @@
 # 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.39.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/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',

package/src/editor/docs/content/01-overview.md

@@ -18,8 +18,9 @@ style your site by editing tokens and components in a live editor. When it looks
 
 - **Tokens**: the design-system primitives, colour palettes, type, spacing,
   radius, shadow, and gradients, that apply across your whole site.
-- **Components**: the package ships about 25 editable components (Button, Card,
-  Dialog, Table, and more).You style components by changing the tokens assigned to each property.
+- **Components**: the package ships about 25 editable components (Button,
+  IconButton, Card, Dialog, Table, and more). You style components by changing
+  the tokens assigned to each property.
 
 ## Where to go next
 

package/src/editor/docs/content.generated.ts

@@ -2,7 +2,7 @@
 // Source of truth: src/editor/docs/content/*.md  ·  regenerate: npm run sync:docs
 
 export const docContent: Record<string, string> = {
-  "01-overview": "# Overview\n\nLive Tokens is a design system for building Svelte microsites quickly. You\nstyle your site by editing tokens and components in a live editor. When it looks right, you save the manifest and ship it.\n\n## How it works\n\n- The editor runs in your dev server, on top of your real pages. You style in\n  context, not in a separate sandbox.\n- Every change updates a CSS variable, so the page repaints instantly. No\n  reload, no build step.\n- Saving writes a small JSON file into your project. Shipping bakes your chosen\n  theme into a plain CSS file that the build bundles.\n- The editor is dev-only. Production ships plain CSS variables and the\n  components you used, nothing else.\n\n## What you can edit\n\n- **Tokens**: the design-system primitives, colour palettes, type, spacing,\n  radius, shadow, and gradients, that apply across your whole site.\n- **Components**: the package ships about 25 editable components (Button, Card,\n  Dialog, Table, and more).You style components by changing the tokens assigned to each property.\n\n## Where to go next\n\n- **[Getting started](getting-started.md)**: scaffold a project and make your\n  first edit.\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own components\n  editable.\n",
+  "01-overview": "# Overview\n\nLive Tokens is a design system for building Svelte microsites quickly. You\nstyle your site by editing tokens and components in a live editor. When it looks right, you save the manifest and ship it.\n\n## How it works\n\n- The editor runs in your dev server, on top of your real pages. You style in\n  context, not in a separate sandbox.\n- Every change updates a CSS variable, so the page repaints instantly. No\n  reload, no build step.\n- Saving writes a small JSON file into your project. Shipping bakes your chosen\n  theme into a plain CSS file that the build bundles.\n- The editor is dev-only. Production ships plain CSS variables and the\n  components you used, nothing else.\n\n## What you can edit\n\n- **Tokens**: the design-system primitives, colour palettes, type, spacing,\n  radius, shadow, and gradients, that apply across your whole site.\n- **Components**: the package ships about 25 editable components (Button,\n  IconButton, Card, Dialog, Table, and more). You style components by changing\n  the tokens assigned to each property.\n\n## Where to go next\n\n- **[Getting started](getting-started.md)**: scaffold a project and make your\n  first edit.\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own components\n  editable.\n",
   "creating-components": "# Creating components\n\nThe package ships about 25 editable components. When you need one it doesn't\nhave, you can make your own Svelte component editable, so anyone using the\neditor can re-point its colours, type, and spacing without touching code.\n\nThe simplest way is to ask Claude. The package bundles a Claude Code skill that\nknows the conventions, writes the files, and checks the result for you.\n\n## Install the skills\n\n```bash\nnpx @motion-proto/live-tokens setup-claude\n```\n\nThis copies the bundled skills into your project's `.claude/skills/`. Once\nthey're there, Claude Code picks them up automatically.\n\n## Ask for a component\n\nDescribe what you want in plain English. Phrases like these trigger the skill:\n\n- \"Add a Toggle component to live-tokens\"\n- \"Make this Svelte component editable in the live-tokens editor\"\n- \"Create a Stat component with a value and a label\"\n\nClaude asks any clarifying questions it needs (which variants, which states,\nwhich parts), then writes the component, registers it with the editor, and runs\nits verification checklist. When it finishes, open `/live-tokens/components` to see your new\ncomponent in the editor and confirm everything works.\n\n## What you get\n\n- A runtime component whose editable properties default to your theme tokens.\n- An editor entry that appears under **Custom** in the `/live-tokens/components` view.\n- The naming and wiring handled for you, so the component fits the system.\n\nAdvanced authors who want to write a component by hand can read the naming and\nstate-model conventions shipped in the package\n(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).\n",
   "editing-tokens": "# Editing tokens\n\nA tour of the editor. The page behind it repaints on every change; saving\nwrites a theme file you can reload later.\n\nThe editor has two views:\n\n- **Tokens**: the design-system primitives (colour, type, spacing, and so on).\n  They apply everywhere your site uses them.\n- **Components**: per-component editors. Re-Assign what tokens a component uses\n  without changing the underlying system.\n\nThis page covers **Tokens**. For components, see\n[Creating components](creating-components.md).\n\n## Palettes\n\nMost colour work happens here. Each palette (Brand, Accent, Neutral, Canvas,\nSuccess, Warning, Info, Danger, and a few more) has:\n\n- **Base colour.** Pick a hex; the palette derives an 11-step ramp (100 to 950)\n  from it.\n- **Curves.** Two curves shape how lightness and saturation fall off across the\n  ramp. Drag the handles to bias it darker, lighter, or more saturated.\n- **Overrides.** Lock a single step to a hand-picked hex when the curve doesn't\n  land where you want.\n\nEditing a palette base ripples through every colour that depends on it, in real\ntime. Colours use OKLCH, so the ramp stays perceptually even across hues\nwithout muddy mid-tones.\n\n## Type\n\n- **Fonts.** Add sources from Google Fonts, Adobe (Typekit), a CSS URL, or an\n  inline `@font-face`. The font loads in the page as soon as you add it.\n- **Stacks.** Named font cascades you reference by token, such as a display\n  stack and a body stack.\n- **Sizes and weights.** A t-shirt scale (xs, sm, md, lg, xl, 2xl…) for size and\n  a numeric scale (100 to 900) for weight.\n\n## Spacing, radius, shadow\n\nNumeric scales with a slider per step.\n\n- **Spacing**: the padding, gap, and margin scale.\n- **Radius**: none through full.\n- **Shadow**: colour, offset, blur, spread, and opacity per step, with stacked\n  shadows supported.\n\nChange a step and every element using it repaints.\n\n## Overlays and gradients\n\n- **Overlays** are translucent tints layered over surfaces, like the subtle\n  tint a card gets on hover. Set a colour and opacity per state.\n- **Gradients** are reusable gradient tokens with a stop list and direction, for\n  hero panels and accent backgrounds.\n\n## Columns\n\nThe page-grid overlay. Set column count, gutter, and outer margin, and toggle\nthe visual guide with `Cmd/Ctrl+G`. Pages built on the column system reflow\nlive.\n\n## Saving\n\nThe editor saves to your browser continuously, so work survives a reload\nmid-edit. **Save** is a separate step: it writes a named theme file under\n`src/live-tokens/data/themes/`.\n\nThe header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`) and a file\nmenu for New, Save, Save as, Switch, and Delete. You can keep many themes side\nby side; one is active at a time. See [Themes](themes-workflow.md) for the full\nlifecycle.\n",
   "getting-started": "# Getting started\n\nScaffold a live token site in a moments. You need Node 20 or later, a\npackage manager (npm, pnpm, or yarn), and a browser. Open claude code in your repo and start building.\n\n## Scaffold a new app\n\n```bash\nnpm create @motion-proto/live-tokens@latest my-app\ncd my-app\nnpm install\nnpm run dev\n```\n\nOpen the URL Vite prints (usually `http://localhost:5173`). You get a\none-page Svelte + Vite app that depends on the published package, with the\neditor wired up and the full component set ready to import.\n\n`npx @motion-proto/live-tokens create my-app` runs the same scaffold without\nthe initialiser package.\n\n### What the scaffold gives you\n\nEvery editable file lives under `src/` and is committed, so `npm install` and\nversion upgrades never touch your styles. The package code stays in\n`node_modules`.\n\n| Path | What it is |\n|------|------------|\n| `src/pages/Home.svelte` | The starter page. Replace it with your own content. |\n| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds dev-only routes under a reserved `/live-tokens/*` namespace: `/live-tokens/editor`, `/live-tokens/components`, and `/live-tokens/docs`. |\n| `src/system/styles/tokens.css` | Your base token vocabulary, hand-authored. |\n| `src/styles/site.css` | Themed page typography, yours to edit. |\n\n## Your first edit\n\n1. Run `npm run dev` and open the home page.\n2. Click **Open Token Editor**, or visit `/live-tokens/editor`. The editor opens beside\n   the page.\n3. Open **Palettes**, pick **Brand**, and change the base hex. The page\n   repaints as you type.\n4. Open the file menu and choose **Save as**. A theme appears as JSON under\n   `src/live-tokens/data/themes/`.\n5. Reload. Your saved theme is the active theme, so the page returns as you\n   left it.\n\n## What you just changed\n\nEvery edit sets a CSS custom property on `:root`. Your components read those\nproperties through `var(--...)`. There is no token build step and no\npreprocessor rewriting your code: the page renders against plain CSS variables\nthe editor swaps live.\n\nTo ship, promote a theme to production in the editor. That bakes the theme's\nvariables into `src/live-tokens/data/tokens.generated.css`, which your build\nbundles alongside `tokens.css`. The editor itself never reaches production.\n\nAlready have a Svelte 5 + Vite app? The\n[README](https://github.com/motionproto/live-tokens#readme) covers installing\ninto an existing project.\n\n## Where to go next\n\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own component\n  editable.\n",

package/src/system/components/IconButton.svelte

@@ -0,0 +1,322 @@
+<script lang="ts">
+   interface Props {
+      disabled?: boolean;
+      type?: 'button' | 'submit' | 'reset';
+      variant?: 'primary' | 'secondary' | 'outline' | 'success' | 'danger' | 'warning';
+      size?: 'default' | 'small';
+      icon: string;
+      /** Required: the button has no visible text, so it needs an accessible name. */
+      ariaLabel: string;
+      tooltip?: string | undefined;
+      buttonRef?: HTMLButtonElement | undefined;
+      class?: string;
+      onclick?: (event: MouseEvent) => void;
+   }
+
+   let {
+      disabled = false,
+      type = 'button',
+      variant = 'primary',
+      size = 'default',
+      icon,
+      ariaLabel,
+      tooltip = undefined,
+      buttonRef = $bindable(undefined),
+      class: className = '',
+      onclick
+   }: Props = $props();
+
+   function handleClick(event: MouseEvent) {
+      if (!disabled) onclick?.(event);
+   }
+</script>
+
+<button
+   bind:this={buttonRef}
+   {type}
+   class="icon-button {variant} {className}"
+   class:small={size === 'small'}
+   {disabled}
+   aria-label={ariaLabel}
+   data-tooltip={tooltip}
+   onclick={handleClick}
+>
+   <i class={icon}></i>
+</button>
+
+<style lang="scss">
+   @use '../styles/padding' as *;
+
+   :global(:root) {
+      /* Primary */
+      --iconbutton-primary-surface: var(--surface-brand-high);
+      --iconbutton-primary-icon: var(--text-primary);
+      --iconbutton-primary-border: var(--border-brand);
+      --iconbutton-primary-border-width: var(--border-width-1);
+      --iconbutton-primary-radius: var(--radius-xl);
+      --iconbutton-primary-padding: var(--space-8);
+      --iconbutton-primary-icon-size: var(--icon-size-md);
+      --iconbutton-primary-hover-surface: var(--surface-brand-higher);
+      --iconbutton-primary-hover-icon: var(--text-primary);
+      --iconbutton-primary-hover-border: var(--border-brand-strong);
+      --iconbutton-primary-disabled-surface: var(--color-neutral-700);
+      --iconbutton-primary-disabled-icon: var(--text-tertiary);
+      --iconbutton-primary-disabled-border: var(--border-neutral-faint);
+
+      /* Secondary */
+      --iconbutton-secondary-surface: var(--surface-neutral-high);
+      --iconbutton-secondary-icon: var(--text-primary);
+      --iconbutton-secondary-border: var(--border-neutral);
+      --iconbutton-secondary-border-width: var(--border-width-1);
+      --iconbutton-secondary-radius: var(--radius-xl);
+      --iconbutton-secondary-padding: var(--space-8);
+      --iconbutton-secondary-icon-size: var(--icon-size-md);
+      --iconbutton-secondary-hover-surface: var(--surface-neutral-higher);
+      --iconbutton-secondary-hover-icon: var(--text-primary);
+      --iconbutton-secondary-hover-border: var(--border-neutral-strong);
+      --iconbutton-secondary-disabled-surface: var(--color-neutral-700);
+      --iconbutton-secondary-disabled-icon: var(--text-tertiary);
+      --iconbutton-secondary-disabled-border: var(--border-neutral-faint);
+
+      /* Outline */
+      --iconbutton-outline-surface: var(--color-transparent);
+      --iconbutton-outline-icon: var(--text-primary);
+      --iconbutton-outline-border: var(--border-neutral);
+      --iconbutton-outline-border-width: var(--border-width-1);
+      --iconbutton-outline-radius: var(--radius-xl);
+      --iconbutton-outline-padding: var(--space-8);
+      --iconbutton-outline-icon-size: var(--icon-size-md);
+      --iconbutton-outline-hover-surface: var(--surface-neutral-lower);
+      --iconbutton-outline-hover-icon: var(--text-primary);
+      --iconbutton-outline-hover-border: var(--border-neutral-strong);
+      --iconbutton-outline-active-surface: var(--hover);
+      --iconbutton-outline-disabled-surface: var(--color-transparent);
+      --iconbutton-outline-disabled-icon: var(--text-tertiary);
+      --iconbutton-outline-disabled-border: var(--border-neutral-faint);
+
+      /* Success */
+      --iconbutton-success-surface: var(--surface-success-low);
+      --iconbutton-success-icon: var(--text-success);
+      --iconbutton-success-border: var(--border-success);
+      --iconbutton-success-border-width: var(--border-width-1);
+      --iconbutton-success-radius: var(--radius-xl);
+      --iconbutton-success-padding: var(--space-8);
+      --iconbutton-success-icon-size: var(--icon-size-md);
+      --iconbutton-success-hover-surface: var(--surface-success-higher);
+      --iconbutton-success-hover-icon: var(--text-primary);
+      --iconbutton-success-hover-border: var(--border-success-strong);
+      --iconbutton-success-disabled-surface: var(--color-neutral-700);
+      --iconbutton-success-disabled-icon: var(--text-tertiary);
+      --iconbutton-success-disabled-border: var(--border-neutral-faint);
+
+      /* Danger */
+      --iconbutton-danger-surface: var(--surface-danger-low);
+      --iconbutton-danger-icon: var(--text-danger);
+      --iconbutton-danger-border: var(--border-danger);
+      --iconbutton-danger-border-width: var(--border-width-1);
+      --iconbutton-danger-radius: var(--radius-xl);
+      --iconbutton-danger-padding: var(--space-8);
+      --iconbutton-danger-icon-size: var(--icon-size-md);
+      --iconbutton-danger-hover-surface: var(--surface-danger-high);
+      --iconbutton-danger-hover-icon: var(--text-primary);
+      --iconbutton-danger-hover-border: var(--border-danger-medium);
+      --iconbutton-danger-disabled-surface: var(--color-neutral-700);
+      --iconbutton-danger-disabled-icon: var(--text-tertiary);
+      --iconbutton-danger-disabled-border: var(--border-neutral-faint);
+
+      /* Warning */
+      --iconbutton-warning-surface: var(--surface-warning-low);
+      --iconbutton-warning-icon: var(--text-warning);
+      --iconbutton-warning-border: var(--border-warning);
+      --iconbutton-warning-border-width: var(--border-width-1);
+      --iconbutton-warning-radius: var(--radius-xl);
+      --iconbutton-warning-padding: var(--space-8);
+      --iconbutton-warning-icon-size: var(--icon-size-md);
+      --iconbutton-warning-hover-surface: var(--surface-warning-high);
+      --iconbutton-warning-hover-icon: var(--text-primary);
+      --iconbutton-warning-hover-border: var(--border-warning-medium);
+      --iconbutton-warning-disabled-surface: var(--color-neutral-700);
+      --iconbutton-warning-disabled-icon: var(--text-tertiary);
+      --iconbutton-warning-disabled-border: var(--border-neutral-faint);
+
+      /* Small size — shared across all variants, mirroring Button. */
+      --iconbutton-small-padding: var(--space-6);
+      --iconbutton-small-icon-size: var(--icon-size-sm);
+   }
+
+   .icon-button {
+      cursor: pointer;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      aspect-ratio: 1;
+      transition: all var(--duration-150);
+
+      &:hover:not(:disabled),
+      &.force-hover:not(:disabled) {
+         transform: translateY(-0.0625rem);
+         box-shadow: var(--shadow-md);
+      }
+
+      &:active:not(:disabled) {
+         transform: translateY(0);
+      }
+
+      &:disabled {
+         cursor: not-allowed;
+      }
+
+      &.primary {
+         --iconbutton-icon-size: var(--iconbutton-primary-icon-size);
+         background: var(--iconbutton-primary-surface);
+         color: var(--iconbutton-primary-icon);
+         border: var(--iconbutton-primary-border-width) solid var(--iconbutton-primary-border);
+         border-radius: var(--iconbutton-primary-radius);
+         @include themed-padding(--iconbutton-primary-padding);
+
+         &:hover:not(:disabled),
+         &.force-hover:not(:disabled) {
+            background: var(--iconbutton-primary-hover-surface);
+            border-color: var(--iconbutton-primary-hover-border);
+            color: var(--iconbutton-primary-hover-icon);
+         }
+
+         &:active:not(:disabled) {
+            box-shadow: var(--shadow-sm);
+         }
+
+         &:disabled {
+            background: var(--iconbutton-primary-disabled-surface);
+            border-color: var(--iconbutton-primary-disabled-border);
+            color: var(--iconbutton-primary-disabled-icon);
+         }
+      }
+
+      &.secondary {
+         --iconbutton-icon-size: var(--iconbutton-secondary-icon-size);
+         background: var(--iconbutton-secondary-surface);
+         color: var(--iconbutton-secondary-icon);
+         border: var(--iconbutton-secondary-border-width) solid var(--iconbutton-secondary-border);
+         border-radius: var(--iconbutton-secondary-radius);
+         @include themed-padding(--iconbutton-secondary-padding);
+
+         &:hover:not(:disabled),
+         &.force-hover:not(:disabled) {
+            background: var(--iconbutton-secondary-hover-surface);
+            border-color: var(--iconbutton-secondary-hover-border);
+            color: var(--iconbutton-secondary-hover-icon);
+         }
+
+         &:disabled {
+            background: var(--iconbutton-secondary-disabled-surface);
+            border-color: var(--iconbutton-secondary-disabled-border);
+            color: var(--iconbutton-secondary-disabled-icon);
+         }
+      }
+
+      &.outline {
+         --iconbutton-icon-size: var(--iconbutton-outline-icon-size);
+         background: var(--iconbutton-outline-surface);
+         color: var(--iconbutton-outline-icon);
+         border: var(--iconbutton-outline-border-width) solid var(--iconbutton-outline-border);
+         border-radius: var(--iconbutton-outline-radius);
+         @include themed-padding(--iconbutton-outline-padding);
+
+         &:hover:not(:disabled),
+         &.force-hover:not(:disabled) {
+            background: var(--iconbutton-outline-hover-surface);
+            border-color: var(--iconbutton-outline-hover-border);
+            color: var(--iconbutton-outline-hover-icon);
+         }
+
+         &:active:not(:disabled) {
+            background: var(--iconbutton-outline-active-surface);
+         }
+
+         &:disabled {
+            background: var(--iconbutton-outline-disabled-surface);
+            border-color: var(--iconbutton-outline-disabled-border);
+            color: var(--iconbutton-outline-disabled-icon);
+         }
+      }
+
+      &.success {
+         --iconbutton-icon-size: var(--iconbutton-success-icon-size);
+         background: var(--iconbutton-success-surface);
+         color: var(--iconbutton-success-icon);
+         border: var(--iconbutton-success-border-width) solid var(--iconbutton-success-border);
+         border-radius: var(--iconbutton-success-radius);
+         @include themed-padding(--iconbutton-success-padding);
+
+         &:hover:not(:disabled),
+         &.force-hover:not(:disabled) {
+            background: var(--iconbutton-success-hover-surface);
+            border-color: var(--iconbutton-success-hover-border);
+            color: var(--iconbutton-success-hover-icon);
+         }
+
+         &:disabled {
+            background: var(--iconbutton-success-disabled-surface);
+            border-color: var(--iconbutton-success-disabled-border);
+            color: var(--iconbutton-success-disabled-icon);
+         }
+      }
+
+      &.danger {
+         --iconbutton-icon-size: var(--iconbutton-danger-icon-size);
+         background: var(--iconbutton-danger-surface);
+         color: var(--iconbutton-danger-icon);
+         border: var(--iconbutton-danger-border-width) solid var(--iconbutton-danger-border);
+         border-radius: var(--iconbutton-danger-radius);
+         @include themed-padding(--iconbutton-danger-padding);
+
+         &:hover:not(:disabled),
+         &.force-hover:not(:disabled) {
+            background: var(--iconbutton-danger-hover-surface);
+            border-color: var(--iconbutton-danger-hover-border);
+            color: var(--iconbutton-danger-hover-icon);
+         }
+
+         &:disabled {
+            background: var(--iconbutton-danger-disabled-surface);
+            border-color: var(--iconbutton-danger-disabled-border);
+            color: var(--iconbutton-danger-disabled-icon);
+         }
+      }
+
+      &.warning {
+         --iconbutton-icon-size: var(--iconbutton-warning-icon-size);
+         background: var(--iconbutton-warning-surface);
+         color: var(--iconbutton-warning-icon);
+         border: var(--iconbutton-warning-border-width) solid var(--iconbutton-warning-border);
+         border-radius: var(--iconbutton-warning-radius);
+         @include themed-padding(--iconbutton-warning-padding);
+
+         &:hover:not(:disabled),
+         &.force-hover:not(:disabled) {
+            background: var(--iconbutton-warning-hover-surface);
+            border-color: var(--iconbutton-warning-hover-border);
+            color: var(--iconbutton-warning-hover-icon);
+         }
+
+         &:disabled {
+            background: var(--iconbutton-warning-disabled-surface);
+            border-color: var(--iconbutton-warning-disabled-border);
+            color: var(--iconbutton-warning-disabled-icon);
+         }
+      }
+
+      &.small {
+         @include themed-padding(--iconbutton-small-padding);
+      }
+
+      &.small :global(i) {
+         font-size: var(--iconbutton-small-icon-size);
+      }
+
+      :global(i) {
+         font-size: var(--iconbutton-icon-size, var(--icon-size-md));
+         line-height: 1;
+      }
+   }
+</style>