From 7d832bff6812e0980e140ca7b5d775486e02cef9 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Thu, 23 Jul 2026 13:46:02 -0500
Subject: [PATCH 1/8] Collapse craft-button to a single variant axis

Replace the two-axis (variant + appearance) button API with one `variant`
property: primary, danger, solid, fill (default), outline, dashed, plain,
link, none. `primary`/`danger` are the colored, stable variants; the rest use
the neutral palette.

Add a boolean `inherit` property (orthogonal to variant) so neutral variants
adopt the ambient colorable palette in a [data-color]/callout context, while
primary/danger keep their own colors.

Rewrites button.styles.ts around the single axis, and updates the stories and
docs (combined the variant/appearance stories, added an Inherit demo).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/components/button/Docs.mdx            |  40 +--
 .../src/components/button/button.stories.ts   | 134 ++++----
 .../src/components/button/button.styles.ts    | 306 ++++++++++--------
 .../src/components/button/button.ts           |  35 +-
 4 files changed, 278 insertions(+), 237 deletions(-)

diff --git a/packages/craftcms-ui/src/components/button/Docs.mdx b/packages/craftcms-ui/src/components/button/Docs.mdx
index aba2d6ced23..72697740939 100644
--- a/packages/craftcms-ui/src/components/button/Docs.mdx
+++ b/packages/craftcms-ui/src/components/button/Docs.mdx
@@ -9,38 +9,42 @@ A button represents a clickable element that performs an action when activated.
 
 <Canvas of={ButtonStories.Default} />
 
-## Appearance
-
-`appearance` controls how visually prominent the button is. Use it to signal importance relative to other buttons on the page.
-
-- `solid` — Solid colored background. The highest-emphasis style. Use for the single most important action in a given context.
-- `outline` — Transparent background with a colored border. Medium emphasis. Use for secondary actions alongside a solid button.
-- `plain` — No background or border. Lowest emphasis. Use for tertiary or destructive actions that shouldn't draw attention on their own.
-
 ## Variant
 
-`variant` controls the button's color, which communicates the _intent_ of the action — not how prominent it is. Appearance and variant are independent: any appearance can be combined with any variant.
+`variant` is the single axis that sets a button's color and appearance together — communicating both the intent of the action and how prominent it is.
 
-- `accent` — Blue. Use for the primary action on a page, such as Save or Confirm.
-- `neutral` — Gray. The default. Use for everyday actions that don't carry a strong positive or negative meaning.
-- `danger` — Red. Use for actions that delete, remove, or permanently change data.
+- `primary` — Solid accent color. The highest-emphasis style; use for the single most important action in a context, such as Save or Confirm.
+- `danger` — Solid red. Use for actions that delete, remove, or permanently change data.
+- `solid` — Solid neutral (gray). A prominent action without a strong positive or negative meaning.
+- `fill` — Soft neutral fill. The default; use for everyday actions.
+- `outline` — Transparent background with a neutral border. Medium emphasis; use for secondary actions alongside a `primary` or `solid` button.
+- `dashed` — Like `outline`, with a dashed border.
+- `plain` — No background or border. Lowest emphasis; use for tertiary actions that shouldn't draw attention on their own.
+- `link` — Renders as an inline text hyperlink.
+- `none` — Completely unstyled; provides behavior only.
 
-<Canvas of={ButtonStories.Accent} />
+`primary` and `danger` are colored and stay stable in any context; every other variant uses the neutral palette.
 
-### Inherit
+## Inherit
 
-`variant="inherit"` is a special case for buttons placed inside [Colorable](?path=/docs/concepts-colorable--docs) containers. Instead of applying its own color, the button picks up the color from its parent container.
+Add the boolean `inherit` property to a button placed inside a [Colorable](?path=/docs/concepts-colorable--docs) container (such as a `craft-callout` or any `[data-color]` element). Its neutral variants then adopt the container's color instead of the neutral palette, while still honoring the chosen appearance (`solid`, `fill`, `outline`, and so on).
 
-Avoid using the standard color variants (`accent`, `neutral`, `danger`) inside Colorable components — the two color systems can conflict and produce unexpected results.
+`primary` and `danger` ignore `inherit` and keep their own colors, so they remain stable inside colorable containers.
+
+<Canvas of={ButtonStories.Inherit} />
 
 ## Sizes
 
 <Canvas of={ButtonStories.Sizes} />
 
-## Icon buttons
+## Icons
 
-<Canvas of={ButtonStories.Icon} />
+<Canvas of={ButtonStories.Icons} />
 
 ## Loading state
 
 <Canvas of={ButtonStories.Loading} />
+
+## Links
+
+<Canvas of={ButtonStories.Links} />
diff --git a/packages/craftcms-ui/src/components/button/button.stories.ts b/packages/craftcms-ui/src/components/button/button.stories.ts
index e102011313c..143db30510b 100644
--- a/packages/craftcms-ui/src/components/button/button.stories.ts
+++ b/packages/craftcms-ui/src/components/button/button.stories.ts
@@ -5,10 +5,9 @@ import {html} from 'lit';
 import './button.js';
 import '../icon/icon.js';
 import '../chip/chip.js';
-import {ButtonVariant, ButtonAppearance} from '@src/components/button/button';
+import {ButtonVariant} from '@src/components/button/button';
 
 const buttonVariants = Object.values(ButtonVariant);
-const appearance = Object.values(ButtonAppearance);
 
 // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
 const meta = {
@@ -19,76 +18,79 @@ const meta = {
   },
   args: {
     label: 'Button',
-    appearance: 'solid',
     loading: false,
-    variant: 'neutral',
+    variant: ButtonVariant.Fill,
   },
   argTypes: {
-    appearance: {
+    variant: {
       control: {type: 'select'},
-      options: appearance,
+      options: buttonVariants,
     },
     loading: {
       control: {type: 'boolean'},
     },
   },
-  render: (args) => html`
-    <div class="grid gap-4">
+} satisfies Meta<any>;
+
+export default meta;
+type Story = StoryObj<any>;
+
+/**
+ * Every variant. `primary` and `danger` are solid and colored; the rest are the
+ * neutral palette in their named appearance.
+ */
+export const Default: Story = {
+  render: () => html`
+    <div class="flex gap-2 items-center flex-wrap">
       ${buttonVariants.map(
         (variant) => html`
-          <div class="flex gap-2">
-            <craft-button variant="${variant}"
-              >${variant ?? 'None'} solid</craft-button
-            >
-            <craft-button appearance="outline" variant="${variant}"
-              >${variant} outline</craft-button
+          <craft-button variant="${variant}">${variant}</craft-button>
+        `
+      )}
+    </div>
+  `,
+};
+
+/**
+ * With the `inherit` property, the neutral variants adopt the ambient colorable
+ * palette (any `[data-color]` / colorable ancestor, e.g. a callout). `primary`
+ * and `danger` keep their own colors regardless.
+ */
+export const Inherit: Story = {
+  render: () => html`
+    <div class="grid gap-4">
+      ${['accent', 'violet', 'success'].map(
+        (color) => html`
+          <div
+            data-color="${color}"
+            class="flex gap-2 items-center flex-wrap"
+            style="padding: 0.75rem; border-radius: 8px; background: var(--c-color-fill-quiet);"
+          >
+            ${[
+              ButtonVariant.Solid,
+              ButtonVariant.Fill,
+              ButtonVariant.Outline,
+              ButtonVariant.Dashed,
+              ButtonVariant.Plain,
+              ButtonVariant.Link,
+            ].map(
+              (variant) => html`
+                <craft-button variant="${variant}" inherit
+                  >${variant}</craft-button
+                >
+              `
+            )}
+            <craft-button variant="${ButtonVariant.Primary}"
+              >primary</craft-button
             >
-            <craft-button appearance="plain" variant="${variant}"
-              >${variant} plain</craft-button
+            <craft-button variant="${ButtonVariant.Danger}"
+              >danger</craft-button
             >
           </div>
         `
       )}
-
-      <craft-chip data-color="violet">
-        <div class="flex gap-2">
-          <craft-button variant="inherit">Chip Buttons</craft-button>
-          <craft-button appearance="outline" variant="inherit"
-            >Outline</craft-button
-          >
-          <craft-button appearance="plain" variant="inherit"
-            >Plain</craft-button
-          >
-        </div>
-      </craft-chip>
     </div>
   `,
-} satisfies Meta<any>;
-
-export default meta;
-type Story = StoryObj<any>;
-
-// More on writing stories with args: https://storybook.js.org/docs/writing-stories/args
-export const Default: Story = {
-  args: {},
-};
-
-export const Variants: Story = {
-  args: {
-    variant: 'accent',
-  },
-  argTypes: {
-    variant: {
-      control: {type: 'select'},
-      options: buttonVariants,
-    },
-  },
-  render: () =>
-    html`${buttonVariants.map(
-      (variant) => html`
-        <craft-button variant="${variant}">${variant}</craft-button>
-      `
-    )}`,
 };
 
 export const Sizes: Story = {
@@ -102,10 +104,18 @@ export const Sizes: Story = {
   `,
 };
 
-export const Icon: Story = {
-  args: {},
-  render: (args) => html`
-    <div class="flex gap-2 items-center">
+export const Icons: Story = {
+  render: () => html`
+    <div class="flex gap-2 items-center flex-wrap">
+      <craft-button icon="location">Prefix icon</craft-button>
+      <craft-button icon="chevron-down" icon-position="suffix"
+        >Suffix icon</craft-button
+      >
+      <craft-button>
+        <craft-icon slot="prefix" name="location"></craft-icon>
+        Slotted prefix
+        <craft-icon slot="suffix" name="chevron-down"></craft-icon>
+      </craft-button>
       <craft-button icon>
         <craft-icon name="location" label="Location"></craft-icon>
       </craft-button>
@@ -130,10 +140,10 @@ export const Links: Story = {
   render: () => html`
     <div class="grid gap-4">
       <div class="flex gap-2 items-center">
-        ${appearance.map(
-          (a) => html`
-            <craft-button appearance="${a}" href="#" variant="accent"
-              >${a} link</craft-button
+        ${buttonVariants.map(
+          (variant) => html`
+            <craft-button variant="${variant}" href="#"
+              >${variant} link</craft-button
             >
           `
         )}
diff --git a/packages/craftcms-ui/src/components/button/button.styles.ts b/packages/craftcms-ui/src/components/button/button.styles.ts
index 98bcc723bb2..513cce176ca 100644
--- a/packages/craftcms-ui/src/components/button/button.styles.ts
+++ b/packages/craftcms-ui/src/components/button/button.styles.ts
@@ -40,6 +40,61 @@ export default css`
     );
   }
 
+  /*
+  Color palette per variant.
+  The single 'variant' axis picks both a palette and an appearance. Here we map
+  the generic --c-color-* props to a palette; 'primary' uses accent, 'danger'
+  uses danger, everything else uses neutral, and 'inherit' sets nothing so it
+  adopts the parent's theme.
+  */
+  /*
+    Neutral variants use the neutral palette by default. With [inherit] we skip
+    this override so the ambient --c-color-* (set by a colorable ancestor) flows
+    through instead. primary/danger set their palettes unconditionally below, so
+    they are unaffected by [inherit].
+  */
+  :host([variant='solid']:not([inherit])),
+  :host([variant='fill']:not([inherit])),
+  :host([variant='outline']:not([inherit])),
+  :host([variant='dashed']:not([inherit])),
+  :host([variant='plain']:not([inherit])),
+  :host([variant='link']:not([inherit])),
+  :host([variant='none']:not([inherit])) {
+    --c-color-fill-loud: var(--c-color-neutral-fill-loud);
+    --c-color-fill-normal: var(--c-color-neutral-fill-normal);
+    --c-color-fill-quiet: var(--c-color-neutral-fill-quiet);
+    --c-color-border-loud: var(--c-color-neutral-border-loud);
+    --c-color-border-normal: var(--c-color-neutral-border-normal);
+    --c-color-border-quiet: var(--c-color-neutral-border-quiet);
+    --c-color-on-loud: var(--c-color-neutral-on-loud);
+    --c-color-on-normal: var(--c-color-neutral-on-normal);
+    --c-color-on-quiet: var(--c-color-neutral-on-quiet);
+  }
+
+  :host([variant='primary']) {
+    --c-color-fill-loud: var(--c-color-accent-fill-loud);
+    --c-color-fill-normal: var(--c-color-accent-fill-normal);
+    --c-color-fill-quiet: var(--c-color-accent-fill-quiet);
+    --c-color-border-loud: var(--c-color-accent-border-loud);
+    --c-color-border-normal: var(--c-color-accent-border-normal);
+    --c-color-border-quiet: var(--c-color-accent-border-quiet);
+    --c-color-on-loud: var(--c-color-accent-on-loud);
+    --c-color-on-normal: var(--c-color-accent-on-normal);
+    --c-color-on-quiet: var(--c-color-accent-on-quiet);
+  }
+
+  :host([variant='danger']) {
+    --c-color-fill-loud: var(--c-color-danger-fill-loud);
+    --c-color-fill-normal: var(--c-color-danger-fill-normal);
+    --c-color-fill-quiet: var(--c-color-danger-fill-quiet);
+    --c-color-border-loud: var(--c-color-danger-border-loud);
+    --c-color-border-normal: var(--c-color-danger-border-normal);
+    --c-color-border-quiet: var(--c-color-danger-border-quiet);
+    --c-color-on-loud: var(--c-color-danger-on-loud);
+    --c-color-on-normal: var(--c-color-danger-on-normal);
+    --c-color-on-quiet: var(--c-color-danger-on-quiet);
+  }
+
   :host(:focus:not([disabled])),
   :host(:focus-visible) {
     outline: var(--c-focus-outline-width) solid var(--_focus-outline-color);
@@ -50,16 +105,6 @@ export default css`
     --_focus-outline-color: var(--c-color-focus-outline);
   }
 
-  @media (hover: hover) {
-    :host(:hover) {
-      background-color: hsl(
-        from var(--c-color-fill-loud, var(--c-button-default-fill)) h s
-          calc(l - 5)
-      );
-      color: var(--c-color-on-loud);
-    }
-  }
-
   :host(:not(:disabled):not(.loading):active),
   :host(.is-active:not(:disabled):not(.loading)) {
     color: var(--_active-color);
@@ -67,10 +112,11 @@ export default css`
     box-shadow: inset 0 1px 3px var(--c-color-mix-active);
   }
 
+  /* Selected state (e.g. inside a radio button-group): show the loud fill. */
   :host(:not(:disabled):not(.loading)[active]),
   :host(.is-active:not(:disabled):not(.loading)) {
-    color: var(--c-color-on-loud);
     background-color: var(--c-color-fill-loud);
+    color: var(--c-color-on-loud);
     border-color: var(--c-color-border-loud);
   }
 
@@ -132,185 +178,177 @@ export default css`
   }
 
   /*
-  Appearances
+  Variants (appearance × palette)
    */
 
-  /* Inline */
-  :host([appearance~='inline']) {
-    display: inline;
-    appearance: none;
-    background-color: transparent;
-    border-color: currentColor;
-    color: inherit;
-    font: inherit;
-    padding: 0;
-    min-height: auto;
-    min-width: auto;
-
-    &::before {
-      /* remove the sizer added by lion */
-      display: none;
-    }
-
-    .button-content {
-      padding: 0;
-    }
+  /* Solid — primary, danger, and solid are filled with the loud color. */
+  :host([variant='primary']),
+  :host([variant='danger']),
+  :host([variant='solid']) {
+    background-color: var(
+      --c-color-fill-loud,
+      var(--c-color-neutral-fill-loud)
+    );
+    border-color: transparent;
+    color: var(--c-color-on-loud, var(--c-color-neutral-on-loud));
   }
 
-  :host([appearance='inline']:not(:disabled):not(.loading):hover) {
-    background-color: color-mix(
-      in oklab,
-      var(--c-color-fill-quiet, var(--c-button-default-fill)),
-      var(--c-color-mix-hover)
+  :host([variant='primary']:hover),
+  :host([variant='danger']:hover),
+  :host([variant='solid']:hover) {
+    background-color: hsl(
+      from var(--c-color-fill-loud, var(--c-color-neutral-fill-loud)) h s
+        calc(l - 5)
     );
-    color: var(--c-color-on-quiet);
+    color: var(--c-color-on-loud, var(--c-color-neutral-on-loud));
   }
 
-  :host([appearance='inline']:not(:disabled):not(.loading):active) {
-    color: var(--c-color-on-quiet, var(--c-color-neutral-on-quiet));
-    background-color: color-mix(
-      in oklab,
-      var(--c-color-fill-quiet, var(--c-color-neutral-fill-quiet)),
-      var(--c-color-mix-active)
+  :host([variant='primary']:active),
+  :host([variant='danger']:active),
+  :host([variant='solid']:active) {
+    --_active-background-color: hsl(
+      from var(--c-color-fill-loud, var(--c-color-neutral-fill-loud)) h s
+        calc(l - 10)
     );
+    --_active-color: var(--c-color-on-loud, var(--c-color-neutral-on-loud));
   }
 
-  :host([appearance='inline'][active]) {
+  /* Fill (default) — neutral normal fill. */
+  :host([variant='fill']) {
+    border-color: transparent;
     background-color: var(
       --c-color-fill-normal,
       var(--c-color-neutral-fill-normal)
     );
-    border-color: var(
-      --c-color-border-normal,
-      var(--c-color-neutral-border-normal)
-    );
     color: var(--c-color-on-normal, var(--c-color-neutral-on-normal));
-    box-shadow: none;
   }
 
-  /* Plain & Outline (Shared) */
-  :host([appearance~='plain']),
-  :host([appearance~='outline']) {
-    background-color: transparent;
-    color: var(--c-color-on-quiet);
-  }
-
-  :host([appearance~='plain']:hover),
-  :host([appearance~='outline']:hover) {
+  :host([variant='fill']:hover) {
     background-color: hsl(
-      from var(--c-color-fill-quiet, var(--c-color-neutral-fill-quiet)) h s
+      from var(--c-color-fill-normal, var(--c-color-neutral-fill-normal)) h s
         calc(l - 5)
     );
+    color: var(--c-color-on-normal, var(--c-color-neutral-on-normal));
   }
 
-  :host([appearance~='plain']:active),
-  :host([appearance~='outline']:active) {
+  :host([variant='fill']:active) {
     --_active-background-color: hsl(
-      from var(--c-color-fill-quiet, var(--c-color-neutral-fill-quiet)) h s
-        calc(l - 8)
+      from var(--c-color-fill-normal, var(--c-color-neutral-fill-normal)) h s
+        calc(l - 10)
     );
-    --_active-color: var(--c-color-on-quiet, var(--c-color-neutral-on-quiet));
-  }
-
-  :host([appearance~='plain'][active]),
-  :host([appearance~='outline'][active]) {
-    background-color: var(--c-color-fill-loud);
-    color: var(--c-color-on-loud);
-    border-color: var(--c-color-border-loud);
+    --_active-color: var(--c-color-on-normal, var(--c-color-neutral-on-normal));
   }
 
-  /* Plain */
-  :host([appearance~='plain']) {
-    border-color: transparent;
-    color: inherit;
-
-    &:before {
-      display: none;
-    }
+  /* Outline, Dashed & Plain — transparent fill. */
+  :host([variant='outline']),
+  :host([variant='dashed']),
+  :host([variant='plain']) {
+    background-color: transparent;
+    color: var(--c-color-on-quiet);
   }
 
-  :host([appearance='plain']:not(:disabled):not(.loading):hover) {
+  :host([variant='outline']:not(:disabled):not(.loading):hover),
+  :host([variant='dashed']:not(:disabled):not(.loading):hover),
+  :host([variant='plain']:not(:disabled):not(.loading):hover) {
     background-color: color-mix(
       in oklab,
-      var(--c-color-fill-quiet, var(--c-button-default-fill)),
+      var(--c-color-fill-quiet, var(--c-color-neutral-fill-quiet)),
       var(--c-color-mix-hover)
     );
     color: var(--c-color-on-quiet);
   }
 
-  :host([appearance='plain']:not(:disabled):not(.loading):active) {
-    color: var(--c-color-on-quiet, var(--c-color-neutral-on-quiet));
-    background-color: color-mix(
+  :host([variant='outline']:not(:disabled):not(.loading):active),
+  :host([variant='dashed']:not(:disabled):not(.loading):active),
+  :host([variant='plain']:not(:disabled):not(.loading):active) {
+    --_active-background-color: color-mix(
       in oklab,
       var(--c-color-fill-quiet, var(--c-color-neutral-fill-quiet)),
       var(--c-color-mix-active)
     );
+    --_active-color: var(--c-color-on-quiet, var(--c-color-neutral-on-quiet));
   }
 
-  :host([appearance='plain'][active]) {
-    background-color: var(--c-color-fill-normal);
-    border-color: var(--c-color-border-normal);
-    color: var(--c-color-on-normal);
-    box-shadow: none;
+  /* Outline & Dashed — visible border. */
+  :host([variant='outline']),
+  :host([variant='dashed']) {
+    border-color: var(--c-color-border-loud);
   }
 
-  /* Outline */
-  :host([appearance='outline']) {
-    border-color: var(--c-color-border-loud);
+  :host([variant='dashed']) {
+    border-style: dashed;
   }
 
-  /* Solid */
-  :host([appearance~='solid']) {
-    background-color: var(
-      --c-color-fill-loud,
-      var(--c-color-neutral-fill-loud)
-    );
+  /* Plain — no border. */
+  :host([variant='plain']) {
     border-color: transparent;
-    color: var(--c-color-on-loud, var(--c-color-neutral-on-loud));
+
+    &::before {
+      display: none;
+    }
   }
 
-  :host([appearance='solid']:hover) {
-    background-color: hsl(
-      from var(--c-color-fill-loud, var(--c-color-neutral-fill-loud)) h s
-        calc(l - 5)
-    );
-    color: var(--c-color-on-loud, var(--c-color-neutral-on-loud));
+  /* Link — renders as a text hyperlink: no fill or border, underlined. */
+  :host([variant='link']) {
+    display: inline;
+    appearance: none;
+    background-color: transparent;
+    border-color: transparent;
+    color: var(--c-color-fill-loud, var(--c-color-neutral-fill-loud));
+    font: inherit;
+    padding: 0;
+    min-height: auto;
+    min-width: auto;
+    text-decoration: underline;
+
+    &::before {
+      /* remove the sizer added by lion */
+      display: none;
+    }
+
+    .button-content {
+      padding: 0;
+    }
   }
 
-  :host([appearance='solid']:active) {
-    --_active-background-color: hsl(
+  :host([variant='link']:not(:disabled):not(.loading):hover) {
+    background-color: transparent;
+    color: hsl(
       from var(--c-color-fill-loud, var(--c-color-neutral-fill-loud)) h s
         calc(l - 10)
     );
-    --_active-color: var(--c-color-on-loud, var(--c-color-neutral-on-loud));
+    text-decoration: none;
   }
 
-  /* Fill */
-  :host([appearance~='fill']) {
-    border-color: transparent;
-    background-color: var(
-      --c-color-fill-normal,
-      var(--c-color-neutral-fill-normal)
-    );
-    border-color: transparent;
-    color: var(--c-color-on-normal, var(--c-color-neutral-on-normal));
+  :host([variant='link']:not(:disabled):not(.loading):active) {
+    background-color: transparent;
   }
 
-  :host([appearance='fill']:hover) {
-    background-color: hsl(
-      from var(--c-color-fill-normal, var(--c-color-neutral-fill-normal)) h s
-        calc(l - 5)
-    );
-    color: var(--c-color-on-normal, var(--c-color-neutral-on-normal));
+  /* None — completely unstyled; provides behavior only. */
+  :host([variant='none']) {
+    appearance: none;
+    background-color: transparent;
+    border-color: transparent;
+    border-width: 0;
+    color: inherit;
+    font: inherit;
+    padding: 0;
+    min-height: auto;
+    min-width: auto;
+
+    &::before {
+      display: none;
+    }
+
+    .button-content {
+      padding: 0;
+    }
   }
 
-  :host([appearance='fill'][active]),
-  :host([appearance='fill']:active) {
-    --_active-background-color: hsl(
-      from var(--c-color-fill-normal, var(--c-color-neutral-fill-normal)) h s
-        calc(l - 10)
-    );
-    --_active-color: var(--c-color-on-normal, var(--c-color-neutral-on-normal));
+  :host([variant='none']:hover),
+  :host([variant='none']:active) {
+    background-color: transparent;
+    color: inherit;
   }
 
   .button-content {
@@ -340,12 +378,6 @@ export default css`
     border-radius: 0;
   }
 
-  craft-button-reset,
-  craft-button-submit {
-    /* Temporarily make it very obvious when these are used */
-    outline: 10px solid var(--c-button-danger-border);
-  }
-
   .a11y-error {
     position: relative;
     outline: 2px solid var(--c-color-danger-border-normal) !important;
diff --git a/packages/craftcms-ui/src/components/button/button.ts b/packages/craftcms-ui/src/components/button/button.ts
index 856d022a2eb..8631147053b 100644
--- a/packages/craftcms-ui/src/components/button/button.ts
+++ b/packages/craftcms-ui/src/components/button/button.ts
@@ -6,24 +6,20 @@ import '../spinner/spinner.js';
 import '../icon/icon.js';
 import {computeAccessibleName} from 'dom-accessibility-api';
 import {classMap} from 'lit/directives/class-map.js';
-import variantsStyles from '@src/styles/variants.styles';
 
-export const ButtonAppearance = {
+export const ButtonVariant = {
+  Primary: 'primary',
+  Danger: 'danger',
   Solid: 'solid',
   Fill: 'fill',
   Outline: 'outline',
+  Dashed: 'dashed',
   Plain: 'plain',
-} as const;
-
-export const ButtonVariant = {
-  Accent: 'accent',
-  Neutral: 'neutral',
-  Danger: 'danger',
+  Link: 'link',
+  None: 'none',
 } as const;
 
 export type ButtonVariant = (typeof ButtonVariant)[keyof typeof ButtonVariant];
-export type ButtonAppearance =
-  (typeof ButtonAppearance)[keyof typeof ButtonAppearance];
 
 /**
  * @summary Interactive element that triggers an action or event.
@@ -44,7 +40,7 @@ export type ButtonAppearance =
  */
 export default class CraftButton extends LionButtonSubmit {
   static override get styles() {
-    return [...super.styles, variantsStyles, styles];
+    return [...super.styles, styles];
   }
 
   override connectedCallback() {
@@ -108,18 +104,17 @@ export default class CraftButton extends LionButtonSubmit {
   /** The computed accessible name */
   @property({attribute: 'accessible-name'}) accessibleName: string;
 
-  /** Visual appearance of the button */
-  @property({reflect: true}) appearance: ButtonAppearance = 'solid';
+  /**
+   * The button's visual style. Defaults to "fill" (neutral fill).
+   */
+  @property({reflect: true}) variant: ButtonVariant = ButtonVariant.Fill;
 
   /**
-   * Theme variant of the button. Defaults to "neutral"
-   *
-   * Accent: The primary action on a page
-   * Neutral: Used in most cases
-   * Danger: Indicates a dangerous action, when data will be removed or deleted
-   * Inherit: Useful for colorable elements, button will reflect the parent theme
+   * Adopt the ambient colorable palette (from a `[data-color]` / colorable
+   * ancestor) instead of the neutral palette. Only
+   * affects the neutral variants; `primary` and `danger` stay stable.
    */
-  @property({reflect: true}) variant: ButtonVariant = 'neutral';
+  @property({reflect: true, type: Boolean}) inherit: boolean = false;
 
   /** Size of the button. Defaults to "medium" */
   @property({reflect: true}) size: 'zero' | 'small' | 'medium' | 'large' =

From 1361fce9c28db0f35749c642688729b6cbf393c3 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Thu, 23 Jul 2026 13:46:19 -0500
Subject: [PATCH 2/8] Replace previous button variant/appearance references

Adapt the package to the collapsed button API:
- index.ts stops re-exporting the removed ButtonAppearance.
- variants.styles.ts swaps the [variant='default'] block for [variant='accent']
  and [variant='neutral'] (used by callout/indicator/action-item).
- The tokens "Button Matrix" story and FilterHud now use the single variant axis
  (e.g. ButtonVariant.Fill / ButtonVariant.Primary).

Note: the broader app consumer migration (variant/appearance usages across
resources/js) is still pending and tracked separately.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/craftcms-ui/src/index.ts             |  1 -
 .../src/stories/tokens/variants.stories.ts    | 43 +++++--------------
 .../craftcms-ui/src/styles/variants.styles.ts | 14 +++++-
 .../modules/elements/components/FilterHud.vue |  6 +--
 4 files changed, 25 insertions(+), 39 deletions(-)

diff --git a/packages/craftcms-ui/src/index.ts b/packages/craftcms-ui/src/index.ts
index dd43dfd4354..e175abf655a 100644
--- a/packages/craftcms-ui/src/index.ts
+++ b/packages/craftcms-ui/src/index.ts
@@ -14,7 +14,6 @@ export {default as CraftBreadcrumbs} from './components/breadcrumbs/breadcrumbs.
 export {default as CraftButtonGroup} from './components/button-group/button-group.js';
 export {
   default as CraftButton,
-  ButtonAppearance,
   ButtonVariant,
 } from './components/button/button.js';
 export {default as CraftCallout} from './components/callout/callout.js';
diff --git a/packages/craftcms-ui/src/stories/tokens/variants.stories.ts b/packages/craftcms-ui/src/stories/tokens/variants.stories.ts
index 17e67e0b0a0..909b6efd29c 100644
--- a/packages/craftcms-ui/src/stories/tokens/variants.stories.ts
+++ b/packages/craftcms-ui/src/stories/tokens/variants.stories.ts
@@ -8,10 +8,9 @@ import '../../components/indicator/indicator.js';
 
 import {appearances} from '@src/constants/appearances';
 import {variants} from '@src/constants/variants';
-import {ButtonVariant, ButtonAppearance} from '@src/components/button/button';
+import {ButtonVariant} from '@src/components/button/button';
 
 const buttonVariants = Object.values(ButtonVariant);
-const buttonAppearances = Object.values(ButtonAppearance);
 
 const meta: Meta = {
   title: 'Tokens/Variants & Appearances',
@@ -64,42 +63,20 @@ export const CalloutMatrix: Story = {
 };
 
 /**
- * Buttons use their own variant subset (accent, neutral, danger)
- * and appearance subset (solid, outline, plain).
+ * Buttons use a single `variant` axis (primary, danger, solid, fill, outline,
+ * dashed, plain, link, none — plus inherit).
  */
 export const ButtonMatrix: Story = {
   name: 'Button Matrix',
   render: () => html`
     <div class="stage">
-      <table class="cp-table cp-table--padded">
-        <thead>
-          <tr>
-            <th>variant</th>
-            ${buttonAppearances.map((a) => html`<th>${a}</th>`)}
-          </tr>
-        </thead>
-        <tbody>
-          ${buttonVariants.map(
-            (variant) => html`
-              <tr>
-                <td><strong>${variant}</strong></td>
-                ${buttonAppearances.map(
-                  (appearance) => html`
-                    <td>
-                      <craft-button
-                        variant="${variant}"
-                        appearance="${appearance}"
-                      >
-                        ${variant}
-                      </craft-button>
-                    </td>
-                  `
-                )}
-              </tr>
-            `
-          )}
-        </tbody>
-      </table>
+      <div style="display: flex; gap: 0.5rem; flex-wrap: wrap;">
+        ${buttonVariants.map(
+          (variant) => html`
+            <craft-button variant="${variant}">${variant}</craft-button>
+          `
+        )}
+      </div>
     </div>
   `,
 };
diff --git a/packages/craftcms-ui/src/styles/variants.styles.ts b/packages/craftcms-ui/src/styles/variants.styles.ts
index 906db69267b..fec9c94b451 100644
--- a/packages/craftcms-ui/src/styles/variants.styles.ts
+++ b/packages/craftcms-ui/src/styles/variants.styles.ts
@@ -1,7 +1,19 @@
 import {css} from 'lit';
 
 export default css`
-  :host([variant='default']) {
+  :host([variant='accent']) {
+    --c-color-fill-loud: var(--c-color-accent-fill-loud);
+    --c-color-fill-normal: var(--c-color-accent-fill-normal);
+    --c-color-fill-quiet: var(--c-color-accent-fill-quiet);
+    --c-color-border-loud: var(--c-color-accent-border-loud);
+    --c-color-border-normal: var(--c-color-accent-border-normal);
+    --c-color-border-quiet: var(--c-color-accent-border-quiet);
+    --c-color-on-loud: var(--c-color-accent-on-loud);
+    --c-color-on-normal: var(--c-color-accent-on-normal);
+    --c-color-on-quiet: var(--c-color-accent-on-quiet);
+  }
+
+  :host([variant='neutral']) {
     --c-color-fill-loud: var(--c-color-neutral-fill-loud);
     --c-color-fill-normal: var(--c-color-neutral-fill-normal);
     --c-color-fill-quiet: var(--c-color-neutral-fill-quiet);
diff --git a/resources/js/modules/elements/components/FilterHud.vue b/resources/js/modules/elements/components/FilterHud.vue
index c664a33fdb1..412e3390298 100644
--- a/resources/js/modules/elements/components/FilterHud.vue
+++ b/resources/js/modules/elements/components/FilterHud.vue
@@ -3,7 +3,6 @@
     t,
     appendBodyHtml,
     appendHeadHtml,
-    ButtonAppearance,
     ButtonVariant,
   } from '@craftcms/ui';
   import {useHttp, usePage} from '@inertiajs/vue3';
@@ -108,14 +107,13 @@
           <div class="mt-4 flex justify-end gap-2">
             <craft-button
               type="button"
-              :appearance="ButtonAppearance.Fill"
+              :variant="ButtonVariant.Fill"
               @click="() => emit('close')"
               >{{ t('Cancel') }}</craft-button
             >
             <craft-button
               type="submit"
-              :variant="ButtonVariant.Accent"
-              :appearance="ButtonAppearance.Solid"
+              :variant="ButtonVariant.Primary"
               >{{ t('Apply') }}</craft-button
             >
           </div>

From 0de4b1142c00d5b5195e57b5c3a2cedb111afe88 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Thu, 23 Jul 2026 13:46:31 -0500
Subject: [PATCH 3/8] Consolidate color definitions into a single source
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

constants/colors.ts and scripts/generate-colors.js each hard-coded the color
palette and semantic map, and had drifted (info: blue vs sky, warning: orange
vs yellow; accent: red vs blue).

Introduce constants/colors.data.ts as the single source of truth. colors.ts
builds its Color map + ColorValue/ColorKey from it; generate-colors.js loads
it via esbuild (it can't import TS directly). Regenerate colorable.css — the
token output is unchanged except accent is corrected from a stale red to blue.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/craftcms-ui/scripts/build.js         |  2 +-
 .../craftcms-ui/scripts/generate-colors.js    | 77 ++++++++----------
 .../craftcms-ui/src/constants/colors.data.ts  | 57 ++++++++++++++
 packages/craftcms-ui/src/constants/colors.ts  | 78 +++++++++----------
 .../src/styles/shared/colorable.css           | 36 ++++-----
 5 files changed, 146 insertions(+), 104 deletions(-)
 create mode 100644 packages/craftcms-ui/src/constants/colors.data.ts

diff --git a/packages/craftcms-ui/scripts/build.js b/packages/craftcms-ui/scripts/build.js
index 680cb1f3244..b21c760b1dd 100755
--- a/packages/craftcms-ui/scripts/build.js
+++ b/packages/craftcms-ui/scripts/build.js
@@ -106,7 +106,7 @@ async function generateVueWrappers() {
 
 async function generateColors() {
   spinner.start('Generating Colors');
-  createColors();
+  await createColors();
   spinner.succeed();
   return Promise.resolve();
 }
diff --git a/packages/craftcms-ui/scripts/generate-colors.js b/packages/craftcms-ui/scripts/generate-colors.js
index 006f9f1dd8b..aa8df54f4cf 100644
--- a/packages/craftcms-ui/scripts/generate-colors.js
+++ b/packages/craftcms-ui/scripts/generate-colors.js
@@ -1,47 +1,27 @@
-import {writeFileSync} from 'fs';
+import {writeFileSync, readFileSync} from 'fs';
 import {dirname, resolve} from 'path';
 import {fileURLToPath} from 'url';
+import {transformSync} from 'esbuild';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, '..');
 const OUT_FILE = resolve(ROOT, 'src/styles/shared/colorable.css');
+const DATA_FILE = resolve(ROOT, 'src/constants/colors.data.ts');
 
 /*
-This is the same as the colors in constants/colors but we can't import
-typescript into this JS file so we had to duplicate for now.
+The canonical color data lives in src/constants/colors.data.ts (shared with
+constants/colors.ts). This script can't import TypeScript directly, so we
+transpile it with esbuild and import the result.
  */
-const availableColors = [
-  'red',
-  'orange',
-  'amber',
-  'yellow',
-  'lime',
-  'green',
-  'emerald',
-  'teal',
-  'cyan',
-  'sky',
-  'blue',
-  'indigo',
-  'violet',
-  'purple',
-  'fuchsia',
-  'pink',
-  'rose',
-  'white',
-  'gray',
-  'black',
-  'slate',
-];
-
-const semanticColors = {
-  neutral: 'slate',
-  accent: 'red',
-  info: 'blue',
-  success: 'emerald',
-  warning: 'yellow',
-  danger: 'red',
-};
+async function loadColorData() {
+  const {code} = transformSync(readFileSync(DATA_FILE, 'utf8'), {
+    loader: 'ts',
+    format: 'esm',
+  });
+  return import(
+    `data:text/javascript;base64,${Buffer.from(code).toString('base64')}`
+  );
+}
 
 const colorIncrements = {
   fill: {
@@ -103,8 +83,8 @@ function colorScale(color) {
   }
 }
 
-function buildColorableTokens() {
-  return availableColors
+function buildColorableTokens(paletteColors) {
+  return paletteColors
     .map((color) => {
       const s = colorScale(color);
       return [
@@ -123,7 +103,7 @@ function buildColorableTokens() {
     .join('\n\n');
 }
 
-function buildSemanticTokens() {
+function buildSemanticTokens(semanticColors) {
   let declarations = [];
   for (const [meaning, color] of Object.entries(semanticColors)) {
     const s = colorScale(color);
@@ -161,22 +141,29 @@ function buildStyleBlock(color) {
 }`;
 }
 
-function generateStyles(colors) {
+function generateStyles(paletteColors, semanticColors) {
   return `/* Auto-generated by scripts/generate-colors.js — do not edit manually */
 
 :root {
-${buildColorableTokens()}
-${buildSemanticTokens()}
+${buildColorableTokens(paletteColors)}
+${buildSemanticTokens(semanticColors)}
 }
 
-${[...availableColors, ...Object.keys(semanticColors)].map((c) => buildStyleBlock(c)).join('\n')}
+${[...paletteColors, ...Object.keys(semanticColors)]
+  .map((c) => buildStyleBlock(c))
+  .join('\n')}
 `;
 }
 
-export default function main() {
-  const css = generateStyles(availableColors);
+export default async function main() {
+  const {paletteColors, semanticColors} = await loadColorData();
+  const css = generateStyles(paletteColors, semanticColors);
   writeFileSync(OUT_FILE, css);
   console.log(`Generated ${OUT_FILE}`);
 }
 
-main();
+// Run when invoked directly (node scripts/generate-colors.js), but not when
+// imported by build.js (which awaits the default export instead).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
diff --git a/packages/craftcms-ui/src/constants/colors.data.ts b/packages/craftcms-ui/src/constants/colors.data.ts
new file mode 100644
index 00000000000..63b88ab4e5d
--- /dev/null
+++ b/packages/craftcms-ui/src/constants/colors.data.ts
@@ -0,0 +1,57 @@
+/**
+ * Canonical color data — the single source of truth for colors in the design
+ * system.
+ *
+ * Consumed by:
+ * - `constants/colors.ts` (runtime `Color` map + types), and
+ * - `scripts/generate-colors.js` (generates `styles/shared/colorable.css`),
+ *   which transpiles this file with esbuild since it can't import TS directly.
+ *
+ * Keep it dependency-free so it stays trivially transpilable.
+ */
+
+/** The raw color palette (each has a full `--color-<name>-*` scale). */
+export const paletteColors = [
+  'red',
+  'orange',
+  'amber',
+  'yellow',
+  'lime',
+  'green',
+  'emerald',
+  'teal',
+  'cyan',
+  'sky',
+  'blue',
+  'indigo',
+  'violet',
+  'purple',
+  'fuchsia',
+  'pink',
+  'rose',
+  'white',
+  'gray',
+  'black',
+  'slate',
+] as const;
+
+/** Semantic meaning → palette color. */
+export const semanticColors = {
+  neutral: 'slate',
+  accent: 'blue',
+  info: 'sky',
+  success: 'emerald',
+  warning: 'yellow',
+  danger: 'red',
+} as const;
+
+/** Status name → palette color. */
+export const statusColors = {
+  pending: 'orange',
+  off: 'red',
+  suspended: 'red',
+  expired: 'red',
+  disabled: 'gray',
+  inactive: 'gray',
+  on: 'emerald',
+} as const;
diff --git a/packages/craftcms-ui/src/constants/colors.ts b/packages/craftcms-ui/src/constants/colors.ts
index 30ecdc51187..813a01c22e1 100644
--- a/packages/craftcms-ui/src/constants/colors.ts
+++ b/packages/craftcms-ui/src/constants/colors.ts
@@ -1,44 +1,42 @@
-export const Color = {
-  Red: 'red',
-  Orange: 'orange',
-  Amber: 'amber',
-  Yellow: 'yellow',
-  Lime: 'lime',
-  Green: 'green',
-  Emerald: 'emerald',
-  Teal: 'teal',
-  Cyan: 'cyan',
-  Sky: 'sky',
-  Blue: 'blue',
-  Indigo: 'indigo',
-  Violet: 'violet',
-  Purple: 'purple',
-  Fuchsia: 'fuchsia',
-  Pink: 'pink',
-  Rose: 'rose',
-  White: 'white',
-  Gray: 'gray',
-  Black: 'black',
+import {paletteColors, semanticColors, statusColors} from './colors.data';
+
+type PaletteColor = (typeof paletteColors)[number];
 
-  // Semantic
-  Neutral: 'slate',
-  Accent: 'red',
-  Success: 'emerald',
-  Warning: 'orange',
-  Danger: 'red',
-  Info: 'blue',
+/**
+ * Named color map (label → palette color), combining the raw palette, semantic
+ * meanings, and status names from the shared {@link ./colors.data} source.
+ */
+type NamedColors = {
+  readonly [K in PaletteColor as Capitalize<K>]: K;
+} & {
+  readonly [K in keyof typeof semanticColors as Capitalize<K>]: (typeof semanticColors)[K];
+} & {
+  readonly [K in keyof typeof statusColors as Capitalize<K>]: (typeof statusColors)[K];
+};
 
-  // Status
-  Pending: 'orange',
-  Off: 'red',
-  Suspended: 'red',
-  Expired: 'red',
-  Disabled: 'gray',
-  Inactive: 'gray',
-  On: 'emerald',
-} as const;
+const capitalize = (value: string): string =>
+  value.charAt(0).toUpperCase() + value.slice(1);
+
+export const Color = {
+  ...Object.fromEntries(
+    paletteColors.map((color) => [capitalize(color), color])
+  ),
+  ...Object.fromEntries(
+    Object.entries(semanticColors).map(([name, color]) => [
+      capitalize(name),
+      color,
+    ])
+  ),
+  ...Object.fromEntries(
+    Object.entries(statusColors).map(([name, color]) => [
+      capitalize(name),
+      color,
+    ])
+  ),
+} as NamedColors;
 
-export const colors = Object.values(Color);
+/** All valid color values (the palette). */
+export const colors: PaletteColor[] = [...paletteColors];
 
-export type ColorKey = keyof typeof Color;
-export type ColorValue = (typeof Color)[keyof typeof Color];
+export type ColorKey = keyof NamedColors;
+export type ColorValue = PaletteColor;
diff --git a/packages/craftcms-ui/src/styles/shared/colorable.css b/packages/craftcms-ui/src/styles/shared/colorable.css
index f3a9073c8d0..c97c886df11 100644
--- a/packages/craftcms-ui/src/styles/shared/colorable.css
+++ b/packages/craftcms-ui/src/styles/shared/colorable.css
@@ -243,26 +243,26 @@
   --c-color-neutral-on-loud: var(--color-slate-50);
 
   /* Semantics colors - accent */
-  --c-color-accent-fill-quiet: var(--color-red-50);
-  --c-color-accent-fill-normal: var(--color-red-100);
-  --c-color-accent-fill-loud: var(--color-red-600);
-  --c-color-accent-border-quiet: var(--color-red-400);
-  --c-color-accent-border-normal: var(--color-red-600);
-  --c-color-accent-border-loud: var(--color-red-800);
-  --c-color-accent-on-quiet: var(--color-red-800);
-  --c-color-accent-on-normal: var(--color-red-950);
-  --c-color-accent-on-loud: var(--color-red-50);
+  --c-color-accent-fill-quiet: var(--color-blue-50);
+  --c-color-accent-fill-normal: var(--color-blue-100);
+  --c-color-accent-fill-loud: var(--color-blue-600);
+  --c-color-accent-border-quiet: var(--color-blue-400);
+  --c-color-accent-border-normal: var(--color-blue-600);
+  --c-color-accent-border-loud: var(--color-blue-800);
+  --c-color-accent-on-quiet: var(--color-blue-800);
+  --c-color-accent-on-normal: var(--color-blue-950);
+  --c-color-accent-on-loud: var(--color-blue-50);
 
   /* Semantics colors - info */
-  --c-color-info-fill-quiet: var(--color-blue-50);
-  --c-color-info-fill-normal: var(--color-blue-100);
-  --c-color-info-fill-loud: var(--color-blue-600);
-  --c-color-info-border-quiet: var(--color-blue-400);
-  --c-color-info-border-normal: var(--color-blue-600);
-  --c-color-info-border-loud: var(--color-blue-800);
-  --c-color-info-on-quiet: var(--color-blue-800);
-  --c-color-info-on-normal: var(--color-blue-950);
-  --c-color-info-on-loud: var(--color-blue-50);
+  --c-color-info-fill-quiet: var(--color-sky-50);
+  --c-color-info-fill-normal: var(--color-sky-100);
+  --c-color-info-fill-loud: var(--color-sky-600);
+  --c-color-info-border-quiet: var(--color-sky-400);
+  --c-color-info-border-normal: var(--color-sky-600);
+  --c-color-info-border-loud: var(--color-sky-800);
+  --c-color-info-on-quiet: var(--color-sky-800);
+  --c-color-info-on-normal: var(--color-sky-950);
+  --c-color-info-on-loud: var(--color-sky-50);
 
   /* Semantics colors - success */
   --c-color-success-fill-quiet: var(--color-emerald-50);

From 842c21021b56a2d183320ec2320aba47fba686b2 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Thu, 23 Jul 2026 16:26:18 -0500
Subject: [PATCH 4/8] Update button instance to new variants

---
 .../src/components/button/button.styles.ts    | 92 ++++++++++---------
 .../src/components/button/button.ts           |  1 +
 .../js/common/components/FormActions.vue      | 10 +-
 .../js/common/components/SlideoutButton.vue   |  3 +-
 resources/js/common/components/Tooltip.vue    |  4 +-
 resources/js/common/components/UserMenu.vue   |  2 +-
 resources/js/common/layouts/AppLayout.vue     |  5 +-
 .../admin-table/components/DeleteButton.vue   |  3 +-
 .../auth/components/login/login-form.ts       |  2 +-
 .../modules/editable-table/editable-table.ts  |  3 +-
 .../components/EntryTypeSelect.vue            |  3 +-
 .../field-layout-designer.ts                  |  4 +-
 .../js/modules/link-field/craft-link-field.ts |  2 +-
 .../permissions/components/PermissionList.vue |  4 +-
 .../components/PluginLicenseInput.vue         |  4 +-
 .../components/PluginLicenseIssues.vue        |  3 +-
 .../components/DeleteSectionButton.vue        |  3 +-
 .../sites/components/DeleteSiteButton.vue     |  3 +-
 .../user/components/UserGroupSelect.vue       | 13 ++-
 resources/js/pages/settings/Email.vue         |  4 +-
 resources/js/pages/settings/routes/Index.vue  |  8 +-
 .../templates/_includes/disclosuremenu.twig   |  4 +-
 .../_includes/forms/editableTable.twig        |  3 +-
 src/Condition/BaseCondition.php               |  5 +-
 src/Cp/Components/Button.php                  | 44 ++++++++-
 src/Cp/Enums/ButtonVariant.php                | 27 ++++++
 src/Cp/FormFields.php                         |  6 +-
 src/Cp/Html/ElementHtml.php                   |  4 +-
 src/Cp/Html/PreviewHtml.php                   |  2 +-
 src/Field/ButtonGroup.php                     |  2 +-
 src/Field/Icon.php                            |  3 +-
 src/Field/Link.php                            |  4 +-
 src/Support/Facades/HtmlSanitizers.php        |  2 +-
 src/Support/Facades/Template.php              |  2 +-
 tests/Unit/Cp/Components/ButtonTest.php       | 17 ++--
 .../Twig/Templates/ButtonTemplateTest.php     |  4 +-
 36 files changed, 184 insertions(+), 121 deletions(-)
 create mode 100644 src/Cp/Enums/ButtonVariant.php

diff --git a/packages/craftcms-ui/src/components/button/button.styles.ts b/packages/craftcms-ui/src/components/button/button.styles.ts
index 513cce176ca..99eccc64031 100644
--- a/packages/craftcms-ui/src/components/button/button.styles.ts
+++ b/packages/craftcms-ui/src/components/button/button.styles.ts
@@ -1,4 +1,5 @@
 import {css} from 'lit';
+
 export default css`
   :host {
     /* Necessary to use variables here to override the default active style specificity */
@@ -53,13 +54,13 @@ export default css`
     through instead. primary/danger set their palettes unconditionally below, so
     they are unaffected by [inherit].
   */
-  :host([variant='solid']:not([inherit])),
-  :host([variant='fill']:not([inherit])),
-  :host([variant='outline']:not([inherit])),
-  :host([variant='dashed']:not([inherit])),
-  :host([variant='plain']:not([inherit])),
-  :host([variant='link']:not([inherit])),
-  :host([variant='none']:not([inherit])) {
+  :host([variant~='solid']:not([inherit])),
+  :host([variant~='fill']:not([inherit])),
+  :host([variant~='outline']:not([inherit])),
+  :host([variant~='dashed']:not([inherit])),
+  :host([variant~='plain']:not([inherit])),
+  :host([variant~='link']:not([inherit])),
+  :host([variant~='none']:not([inherit])) {
     --c-color-fill-loud: var(--c-color-neutral-fill-loud);
     --c-color-fill-normal: var(--c-color-neutral-fill-normal);
     --c-color-fill-quiet: var(--c-color-neutral-fill-quiet);
@@ -71,7 +72,7 @@ export default css`
     --c-color-on-quiet: var(--c-color-neutral-on-quiet);
   }
 
-  :host([variant='primary']) {
+  :host([variant~='primary']) {
     --c-color-fill-loud: var(--c-color-accent-fill-loud);
     --c-color-fill-normal: var(--c-color-accent-fill-normal);
     --c-color-fill-quiet: var(--c-color-accent-fill-quiet);
@@ -83,7 +84,8 @@ export default css`
     --c-color-on-quiet: var(--c-color-accent-on-quiet);
   }
 
-  :host([variant='danger']) {
+  :host([variant~='danger-plain']),
+  :host([variant~='danger']) {
     --c-color-fill-loud: var(--c-color-danger-fill-loud);
     --c-color-fill-normal: var(--c-color-danger-fill-normal);
     --c-color-fill-quiet: var(--c-color-danger-fill-quiet);
@@ -182,9 +184,9 @@ export default css`
    */
 
   /* Solid — primary, danger, and solid are filled with the loud color. */
-  :host([variant='primary']),
-  :host([variant='danger']),
-  :host([variant='solid']) {
+  :host([variant~='primary']),
+  :host([variant~='danger']),
+  :host([variant~='solid']) {
     background-color: var(
       --c-color-fill-loud,
       var(--c-color-neutral-fill-loud)
@@ -193,9 +195,9 @@ export default css`
     color: var(--c-color-on-loud, var(--c-color-neutral-on-loud));
   }
 
-  :host([variant='primary']:hover),
-  :host([variant='danger']:hover),
-  :host([variant='solid']:hover) {
+  :host([variant~='primary']:hover),
+  :host([variant~='danger']:hover),
+  :host([variant~='solid']:hover) {
     background-color: hsl(
       from var(--c-color-fill-loud, var(--c-color-neutral-fill-loud)) h s
         calc(l - 5)
@@ -203,9 +205,9 @@ export default css`
     color: var(--c-color-on-loud, var(--c-color-neutral-on-loud));
   }
 
-  :host([variant='primary']:active),
-  :host([variant='danger']:active),
-  :host([variant='solid']:active) {
+  :host([variant~='primary']:active),
+  :host([variant~='danger']:active),
+  :host([variant~='solid']:active) {
     --_active-background-color: hsl(
       from var(--c-color-fill-loud, var(--c-color-neutral-fill-loud)) h s
         calc(l - 10)
@@ -214,7 +216,7 @@ export default css`
   }
 
   /* Fill (default) — neutral normal fill. */
-  :host([variant='fill']) {
+  :host([variant~='fill']) {
     border-color: transparent;
     background-color: var(
       --c-color-fill-normal,
@@ -223,7 +225,7 @@ export default css`
     color: var(--c-color-on-normal, var(--c-color-neutral-on-normal));
   }
 
-  :host([variant='fill']:hover) {
+  :host([variant~='fill']:hover) {
     background-color: hsl(
       from var(--c-color-fill-normal, var(--c-color-neutral-fill-normal)) h s
         calc(l - 5)
@@ -231,7 +233,7 @@ export default css`
     color: var(--c-color-on-normal, var(--c-color-neutral-on-normal));
   }
 
-  :host([variant='fill']:active) {
+  :host([variant~='fill']:active) {
     --_active-background-color: hsl(
       from var(--c-color-fill-normal, var(--c-color-neutral-fill-normal)) h s
         calc(l - 10)
@@ -240,16 +242,18 @@ export default css`
   }
 
   /* Outline, Dashed & Plain — transparent fill. */
-  :host([variant='outline']),
-  :host([variant='dashed']),
-  :host([variant='plain']) {
+  :host([variant~='outline']),
+  :host([variant~='dashed']),
+  :host([variant~='danger-plain']),
+  :host([variant~='plain']) {
     background-color: transparent;
     color: var(--c-color-on-quiet);
   }
 
-  :host([variant='outline']:not(:disabled):not(.loading):hover),
-  :host([variant='dashed']:not(:disabled):not(.loading):hover),
-  :host([variant='plain']:not(:disabled):not(.loading):hover) {
+  :host([variant~='outline']:not(:disabled):not(.loading):hover),
+  :host([variant~='dashed']:not(:disabled):not(.loading):hover),
+  :host([variant~='danger-plain']:not(:disabled):not(.loading):hover),
+  :host([variant~='plain']:not(:disabled):not(.loading):hover) {
     background-color: color-mix(
       in oklab,
       var(--c-color-fill-quiet, var(--c-color-neutral-fill-quiet)),
@@ -258,9 +262,10 @@ export default css`
     color: var(--c-color-on-quiet);
   }
 
-  :host([variant='outline']:not(:disabled):not(.loading):active),
-  :host([variant='dashed']:not(:disabled):not(.loading):active),
-  :host([variant='plain']:not(:disabled):not(.loading):active) {
+  :host([variant~='outline']:not(:disabled):not(.loading):active),
+  :host([variant~='dashed']:not(:disabled):not(.loading):active),
+  :host([variant~='danger-plain']:not(:disabled):not(.loading):active),
+  :host([variant~='plain']:not(:disabled):not(.loading):active) {
     --_active-background-color: color-mix(
       in oklab,
       var(--c-color-fill-quiet, var(--c-color-neutral-fill-quiet)),
@@ -270,17 +275,18 @@ export default css`
   }
 
   /* Outline & Dashed — visible border. */
-  :host([variant='outline']),
-  :host([variant='dashed']) {
+  :host([variant~='outline']),
+  :host([variant~='dashed']) {
     border-color: var(--c-color-border-loud);
   }
 
-  :host([variant='dashed']) {
-    border-style: dashed;
+  :host([variant~='dashed']) {
+    --c-button-border-style: dashed;
   }
 
   /* Plain — no border. */
-  :host([variant='plain']) {
+  :host([variant~='danger-plain']),
+  :host([variant~='plain']) {
     border-color: transparent;
 
     &::before {
@@ -289,7 +295,7 @@ export default css`
   }
 
   /* Link — renders as a text hyperlink: no fill or border, underlined. */
-  :host([variant='link']) {
+  :host([variant~='link']) {
     display: inline;
     appearance: none;
     background-color: transparent;
@@ -311,7 +317,7 @@ export default css`
     }
   }
 
-  :host([variant='link']:not(:disabled):not(.loading):hover) {
+  :host([variant~='link']:not(:disabled):not(.loading):hover) {
     background-color: transparent;
     color: hsl(
       from var(--c-color-fill-loud, var(--c-color-neutral-fill-loud)) h s
@@ -320,12 +326,12 @@ export default css`
     text-decoration: none;
   }
 
-  :host([variant='link']:not(:disabled):not(.loading):active) {
+  :host([variant~='link']:not(:disabled):not(.loading):active) {
     background-color: transparent;
   }
 
   /* None — completely unstyled; provides behavior only. */
-  :host([variant='none']) {
+  :host([variant~='none']) {
     appearance: none;
     background-color: transparent;
     border-color: transparent;
@@ -345,8 +351,8 @@ export default css`
     }
   }
 
-  :host([variant='none']:hover),
-  :host([variant='none']:active) {
+  :host([variant~='none']:hover),
+  :host([variant~='none']:active) {
     background-color: transparent;
     color: inherit;
   }
@@ -374,10 +380,6 @@ export default css`
     justify-content: end;
   }
 
-  craft-button-group craft-button {
-    border-radius: 0;
-  }
-
   .a11y-error {
     position: relative;
     outline: 2px solid var(--c-color-danger-border-normal) !important;
diff --git a/packages/craftcms-ui/src/components/button/button.ts b/packages/craftcms-ui/src/components/button/button.ts
index 8631147053b..101b1c5ac1f 100644
--- a/packages/craftcms-ui/src/components/button/button.ts
+++ b/packages/craftcms-ui/src/components/button/button.ts
@@ -10,6 +10,7 @@ import {classMap} from 'lit/directives/class-map.js';
 export const ButtonVariant = {
   Primary: 'primary',
   Danger: 'danger',
+  DangerPlain: 'danger-plain',
   Solid: 'solid',
   Fill: 'fill',
   Outline: 'outline',
diff --git a/resources/js/common/components/FormActions.vue b/resources/js/common/components/FormActions.vue
index 59c4fbe5027..5941ff502c4 100644
--- a/resources/js/common/components/FormActions.vue
+++ b/resources/js/common/components/FormActions.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import {t} from '@craftcms/ui';
+  import {ButtonVariant, t} from '@craftcms/ui';
   import type {InertiaForm} from '@inertiajs/vue3';
   import {ref, watch} from 'vue';
   import ActionMenu from '@/common/components/ActionMenu.vue';
@@ -61,7 +61,7 @@
       v-for="button in additionalButtons"
       :key="button.label"
       type="button"
-      :variant="button.variant ?? 'neutral'"
+      :variant="button.variant ?? ButtonVariant.Solid"
       :loading="isButtonProcessing(button.label)"
       :disabled="form.processing || button.disabled"
       @click="handleAdditionalButtonClick(button, $event)"
@@ -78,7 +78,7 @@
       <slot name="submit-button">
         <craft-button
           type="submit"
-          variant="accent"
+          :variant="ButtonVariant.Solid"
           :loading="isButtonProcessing(primaryButton)"
           :disabled="form.processing"
         >
@@ -87,7 +87,7 @@
       </slot>
       <ActionMenu icon="chevron-down" :actions="actionItems">
         <template #invoker="{label}">
-          <craft-button slot="invoker" variant="accent" type="button" icon>
+          <craft-button slot="invoker" :variant="ButtonVariant.Solid" type="button" icon>
             <craft-icon name="chevron-down" :label="label"></craft-icon>
           </craft-button>
         </template>
@@ -97,7 +97,7 @@
     <slot v-else name="submit-button">
       <craft-button
         type="submit"
-        variant="accent"
+        :variant="ButtonVariant.Primary"
         :loading="isButtonProcessing(primaryButton)"
         :disabled="form.processing"
       >
diff --git a/resources/js/common/components/SlideoutButton.vue b/resources/js/common/components/SlideoutButton.vue
index b65922feedd..72352dffa05 100644
--- a/resources/js/common/components/SlideoutButton.vue
+++ b/resources/js/common/components/SlideoutButton.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
   import {useTemplateRef} from 'vue';
+  import {ButtonVariant} from '@craftcms/ui';
 
   defineProps<{
     url: string;
@@ -27,7 +28,7 @@
 <template>
   <craft-button
     type="button"
-    appearance="filled"
+    :variant="ButtonVariant.Dashed"
     @click="openSlideout(url)"
     ref="invoker"
   >
diff --git a/resources/js/common/components/Tooltip.vue b/resources/js/common/components/Tooltip.vue
index 83411d9f4bb..5fb76e7aefa 100644
--- a/resources/js/common/components/Tooltip.vue
+++ b/resources/js/common/components/Tooltip.vue
@@ -17,10 +17,10 @@
   <craft-button
     type="button"
     :id="id"
-    appearance="plain"
+    variant="plain"
     size="zero"
     icon
-    variant="inherit"
+    inherit
   >
     <slot name="icon">
       <craft-icon :name="icon"></craft-icon>
diff --git a/resources/js/common/components/UserMenu.vue b/resources/js/common/components/UserMenu.vue
index 645dd6bf7df..8adbd6f3505 100644
--- a/resources/js/common/components/UserMenu.vue
+++ b/resources/js/common/components/UserMenu.vue
@@ -52,7 +52,7 @@
 </script>
 
 <template>
-  <form :action="LoginController.logout().url" method="post" ref="logoutForm">
+  <form :action="LoginController.logout['/{cpTrigger?}/logout']().url" method="post" ref="logoutForm">
     <input
       v-if="csrfTokenName && csrfTokenValue"
       type="hidden"
diff --git a/resources/js/common/layouts/AppLayout.vue b/resources/js/common/layouts/AppLayout.vue
index 0a00cef18fd..67064c4e1c9 100644
--- a/resources/js/common/layouts/AppLayout.vue
+++ b/resources/js/common/layouts/AppLayout.vue
@@ -27,6 +27,7 @@
     ActionItemButton,
     FormSaveOptions,
   } from '@/common/types';
+  import {ButtonVariant} from '@craftcms/ui';
 
   type DefaultFormAction = 'saveAndContinueEditing';
 
@@ -208,7 +209,7 @@
         <craft-button
           icon
           type="button"
-          appearance="plain"
+          :variant="ButtonVariant.Plain"
           @click="toggleSidebar"
           v-if="!isLargeScreen"
           ref="sidebarToggle"
@@ -221,7 +222,7 @@
         <SystemInfo v-if="isLargeScreen" />
 
         <div class="ml-auto"></div>
-        <craft-button icon appearance="plain" type="button">
+        <craft-button icon :variant="ButtonVariant.Plain" type="button">
           <craft-icon name="search" :label="t('Search')"></craft-icon>
         </craft-button>
         <UserMenu />
diff --git a/resources/js/modules/admin-table/components/DeleteButton.vue b/resources/js/modules/admin-table/components/DeleteButton.vue
index 80dfbc32a26..3f7f7448666 100644
--- a/resources/js/modules/admin-table/components/DeleteButton.vue
+++ b/resources/js/modules/admin-table/components/DeleteButton.vue
@@ -18,8 +18,7 @@
     type="button"
     @click="emit('click')"
     size="small"
-    appearance="plain"
-    variant="danger"
+    variant="danger-plain"
     v-bind="$attrs"
   >
     <craft-icon :name="icon" :label="label"></craft-icon>
diff --git a/resources/js/modules/auth/components/login/login-form.ts b/resources/js/modules/auth/components/login/login-form.ts
index 3713c24794e..e7cff171f71 100644
--- a/resources/js/modules/auth/components/login/login-form.ts
+++ b/resources/js/modules/auth/components/login/login-form.ts
@@ -358,7 +358,7 @@ export default class CraftLoginForm extends LitElement {
                 ? html`
                     <craft-button
                       type="button"
-                      appearance="filled"
+                      variant="fill"
                       ?loading="${this._passkeyBusy}"
                       @click="${this.#loginWithPasskey}"
                       style="width: 100%"
diff --git a/resources/js/modules/editable-table/editable-table.ts b/resources/js/modules/editable-table/editable-table.ts
index 48bb7853d44..6a1daa1aa06 100644
--- a/resources/js/modules/editable-table/editable-table.ts
+++ b/resources/js/modules/editable-table/editable-table.ts
@@ -747,8 +747,7 @@ export class EditableTable extends Base<EditableTableSettings> {
             type: 'button',
             icon: 'x',
             size: 'small',
-            variant: 'danger',
-            appearance: 'plain',
+            variant: 'danger-plain',
             'aria-label': Craft.t('app', 'Delete'),
             command: '--delete-row',
           })
diff --git a/resources/js/modules/entry-types/components/EntryTypeSelect.vue b/resources/js/modules/entry-types/components/EntryTypeSelect.vue
index dfa4aa50296..0081f1df172 100644
--- a/resources/js/modules/entry-types/components/EntryTypeSelect.vue
+++ b/resources/js/modules/entry-types/components/EntryTypeSelect.vue
@@ -4,6 +4,7 @@
   import {
     appendBodyHtml,
     appendHeadHtml,
+    ButtonVariant,
     serializeFormInputs,
     t,
   } from '@craftcms/ui';
@@ -315,7 +316,7 @@
       <craft-button
         type="button"
         slot="invoker"
-        appearance="filled"
+        :variant="ButtonVariant.Dashed"
         v-if="!readOnly"
       >
         <craft-icon name="chevron-down" slot="prefix"></craft-icon>
diff --git a/resources/js/modules/field-layout-designer/field-layout-designer.ts b/resources/js/modules/field-layout-designer/field-layout-designer.ts
index 9cec964a9a8..200a7a429d0 100644
--- a/resources/js/modules/field-layout-designer/field-layout-designer.ts
+++ b/resources/js/modules/field-layout-designer/field-layout-designer.ts
@@ -13,7 +13,7 @@ import {CardViewDesigner} from './card-view-designer';
 import {ElementDrag, TabDrag} from './drags';
 import {fldElementData, fldTabData, htmlToElement, hudData} from './support';
 import type {FieldLayoutConfig, FieldLayoutDesignerSettings} from './types';
-import {Appearance, t} from '@craftcms/ui';
+import {ButtonVariant, t} from '@craftcms/ui';
 
 // `Craft` and jQuery (`$`) are still globals on the page. FLD is native; `$` is
 // used ONLY at the Craft-interop seams (Craft.ui/Grid/listbox/Slideout return or
@@ -191,7 +191,7 @@ export class FieldLayoutDesigner extends Base<FieldLayoutDesignerSettings> {
 
     // Add the “New Field” button — Craft.ui returns jQuery; unwrap to native.
     const createFieldBtn = document.createElement('craft-button');
-    createFieldBtn.appearance = Appearance.Outline;
+    createFieldBtn.variant = ButtonVariant.Dashed;
     createFieldBtn.size = 'small';
     createFieldBtn.classList.add('w-full');
     createFieldBtn.innerText = t('New field');
diff --git a/resources/js/modules/link-field/craft-link-field.ts b/resources/js/modules/link-field/craft-link-field.ts
index 0a6fc74e961..3a9975fb670 100644
--- a/resources/js/modules/link-field/craft-link-field.ts
+++ b/resources/js/modules/link-field/craft-link-field.ts
@@ -354,7 +354,7 @@ class CraftLinkField extends LitElement {
           <div class="input ltr">
             <craft-button
               type="button"
-              appearance="filled"
+              variant="fill"
               aria-describedby=${this.valueError ? this.valueErrorId : nothing}
               aria-invalid=${this.valueError ? 'true' : nothing}
               @click=${this.chooseElement}
diff --git a/resources/js/modules/permissions/components/PermissionList.vue b/resources/js/modules/permissions/components/PermissionList.vue
index ce3906e053f..d99c900808a 100644
--- a/resources/js/modules/permissions/components/PermissionList.vue
+++ b/resources/js/modules/permissions/components/PermissionList.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import {t} from '@craftcms/ui';
+  import {ButtonVariant, t} from '@craftcms/ui';
   import {
     getNestedKeys,
     hasNested,
@@ -110,7 +110,7 @@
     <craft-button
       type="button"
       size="small"
-      appearance="plain"
+      :variant="ButtonVariant.Plain"
       :disabled="disabled"
       @click="toggleAll"
     >
diff --git a/resources/js/modules/plugin-manager/components/PluginLicenseInput.vue b/resources/js/modules/plugin-manager/components/PluginLicenseInput.vue
index a9d47f19b43..5e3711b2e60 100644
--- a/resources/js/modules/plugin-manager/components/PluginLicenseInput.vue
+++ b/resources/js/modules/plugin-manager/components/PluginLicenseInput.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import {t} from '@craftcms/ui';
+  import {t, ButtonVariant} from '@craftcms/ui';
   import CpLink from '@/common/components/CpLink.vue';
   import type {PluginInfo} from '@/modules/plugin-manager/types/plugins';
   import {useForm, usePage} from '@inertiajs/vue3';
@@ -104,7 +104,7 @@
         <craft-button
           type="submit"
           :loading="form.processing"
-          variant="primary"
+          :variant="ButtonVariant.Fill"
         >
           {{ t('Update') }}
         </craft-button>
diff --git a/resources/js/modules/plugin-manager/components/PluginLicenseIssues.vue b/resources/js/modules/plugin-manager/components/PluginLicenseIssues.vue
index 697a771df97..0d414708904 100644
--- a/resources/js/modules/plugin-manager/components/PluginLicenseIssues.vue
+++ b/resources/js/modules/plugin-manager/components/PluginLicenseIssues.vue
@@ -35,8 +35,7 @@
         <input type="hidden" name="edition" :value="plugin.licensedEdition" />
         <craft-button
           type="submit"
-          appearance="inline"
-          variant="inherit"
+          inherit
           :loading="processing"
           >Switch</craft-button
         >
diff --git a/resources/js/modules/sections/components/DeleteSectionButton.vue b/resources/js/modules/sections/components/DeleteSectionButton.vue
index a490212b9f0..f522683ba3a 100644
--- a/resources/js/modules/sections/components/DeleteSectionButton.vue
+++ b/resources/js/modules/sections/components/DeleteSectionButton.vue
@@ -30,11 +30,10 @@
 <template>
   <form @submit.prevent="handleDelete" method="post">
     <craft-button
-      variant="danger"
+      variant="danger-plain"
       type="submit"
       size="small"
       icon
-      appearance="plain"
       :loading="form.processing"
     >
       <craft-icon :label="t('Delete section')" name="x"></craft-icon>
diff --git a/resources/js/modules/sites/components/DeleteSiteButton.vue b/resources/js/modules/sites/components/DeleteSiteButton.vue
index 88c00a72c0d..18e6cc305f4 100644
--- a/resources/js/modules/sites/components/DeleteSiteButton.vue
+++ b/resources/js/modules/sites/components/DeleteSiteButton.vue
@@ -19,8 +19,7 @@
       size="small"
       icon
       type="button"
-      variant="danger"
-      appearance="plain"
+      variant="danger-plain"
       :disabled="site.primary"
       @click="modalActive = true"
     >
diff --git a/resources/js/modules/user/components/UserGroupSelect.vue b/resources/js/modules/user/components/UserGroupSelect.vue
index b5066577a8e..8e143953002 100644
--- a/resources/js/modules/user/components/UserGroupSelect.vue
+++ b/resources/js/modules/user/components/UserGroupSelect.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
   import {computed, ref} from 'vue';
   import {router} from '@inertiajs/vue3';
-  import {t} from '@craftcms/ui';
+  import {ButtonVariant, t} from '@craftcms/ui';
   import CraftInput from '@craftcms/ui/vue/CraftInput.vue';
   import SlideoutButton from '@/common/components/SlideoutButton.vue';
   import Text from '@/common/components/Text.vue';
@@ -89,11 +89,10 @@
           slot="suffix"
           icon="x"
           type="button"
-          appearance="plain"
           size="small"
           @click="removeGroup(group.id)"
           aria-label="t('Remove {name}', {name: groupLabel(group)})"
-          variant="danger"
+          variant="danger-plain"
         >
         </craft-button>
       </craft-chip>
@@ -101,8 +100,12 @@
 
     <div class="flex gap-2 items-center">
       <craft-action-menu v-if="groups.length">
-        <craft-button type="button" slot="invoker" appearance="filled">
-          <craft-icon name="chevron-down" slot="prefix"></craft-icon>
+        <craft-button
+          type="button"
+          slot="invoker"
+          :variant="ButtonVariant.Dashed"
+          icon="chevron-down"
+        >
           {{ t('Choose') }}
         </craft-button>
 
diff --git a/resources/js/pages/settings/Email.vue b/resources/js/pages/settings/Email.vue
index a3467c175fb..d8f801862b7 100644
--- a/resources/js/pages/settings/Email.vue
+++ b/resources/js/pages/settings/Email.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import {t} from '@craftcms/ui';
+  import {ButtonVariant, t} from '@craftcms/ui';
   import {useForm} from '@inertiajs/vue3';
   import {computed} from 'vue';
   import type {SelectItem, SuggestionGroup} from '@/common/types';
@@ -224,7 +224,7 @@
         <div class="flex gap-2 items-center">
           <craft-button
             type="button"
-            variant="primary"
+            :variant="ButtonVariant.Solid"
             :loading="testForm.processing"
             @click="sendTest"
           >
diff --git a/resources/js/pages/settings/routes/Index.vue b/resources/js/pages/settings/routes/Index.vue
index 84d795d4542..06e3597f2d6 100644
--- a/resources/js/pages/settings/routes/Index.vue
+++ b/resources/js/pages/settings/routes/Index.vue
@@ -9,7 +9,7 @@
     reorder,
   } from '@actions/Settings/RoutesController';
   import {Link, router} from '@inertiajs/vue3';
-  import {t} from '@craftcms/ui';
+  import {ButtonVariant, t} from '@craftcms/ui';
   import type {Edge} from '@atlaskit/pragmatic-drag-and-drop-hitbox/types';
   import Empty from '@/common/components/Empty.vue';
   import Pane from '@/common/components/Pane.vue';
@@ -83,8 +83,7 @@
 <template>
   <LayoutSlot name="actions">
     <Link :href="create()">
-      <craft-button v-if="!readOnly" type="button" variant="primary">
-        <craft-icon name="plus" slot="prefix"></craft-icon>
+      <craft-button v-if="!readOnly" type="button" icon="plus" :variant="ButtonVariant.Primary">
         {{ t('New route') }}
       </craft-button>
     </Link>
@@ -155,9 +154,8 @@
         ></craft-reorder-button>
         <craft-button
           @click="deleteRoute(route)"
-          variant="danger"
+          variant="danger-plain"
           size="small"
-          appearance="plain"
           icon
         >
           <craft-icon name="trash" :label="t('Delete')"></craft-icon>
diff --git a/resources/templates/_includes/disclosuremenu.twig b/resources/templates/_includes/disclosuremenu.twig
index d93e4fc1138..90a0f0120fb 100644
--- a/resources/templates/_includes/disclosuremenu.twig
+++ b/resources/templates/_includes/disclosuremenu.twig
@@ -110,8 +110,8 @@
 
   {% tag 'craft-button' with {
     type: 'button',
-    appearance: 'plain',
-    variant: 'inherit',
+    variant: 'plain',
+    inherit: true,
     icon: 'craft-icon' in (buttonHtml ?? ''),
     size: 'small',
     aria: {
diff --git a/resources/templates/_includes/forms/editableTable.twig b/resources/templates/_includes/forms/editableTable.twig
index 388fb4d63c1..0820d3c85ec 100644
--- a/resources/templates/_includes/forms/editableTable.twig
+++ b/resources/templates/_includes/forms/editableTable.twig
@@ -268,11 +268,10 @@
               <craft-button
                 icon="x"
                 size="small"
-                appearance="plain"
                 aria-label="{{ 'Delete row {index}'|t('app', {
                   index: rowNumber,
                 }) }}"
-                variant="danger"
+                variant="danger-plain"
                 command="--delete-row"
                 {% if minRows and totalRows <= minRows %}disabled{% endif %}
               >
diff --git a/src/Condition/BaseCondition.php b/src/Condition/BaseCondition.php
index 19de2b2dd24..42953e17d03 100644
--- a/src/Condition/BaseCondition.php
+++ b/src/Condition/BaseCondition.php
@@ -350,8 +350,7 @@ public function getBuilderInnerHtml(bool $autofocusAddButton = false): string
                                 'type' => 'button',
                                 'icon' => 'x',
                                 'aria-label' => t('Remove'),
-                                'appearance' => 'plain',
-                                'variant' => 'danger',
+                                'variant' => 'danger-plain',
                                 'size' => 'small',
                                 'hx' => [
                                     'vals' => ['uid' => $rule->uid],
@@ -546,7 +545,7 @@ private function _ruleTypeMenu(
             'buttonAttributes' => Arr::merge([
                 'id' => $buttonId,
                 'type' => 'button',
-                'appearance' => 'fill',
+                'variant' => 'fill',
                 'autofocus' => $rule?->getAutofocus(),
             ], $buttonAttributes),
             'inputName' => $rule ? 'type' : 'new-rule-type',
diff --git a/src/Cp/Components/Button.php b/src/Cp/Components/Button.php
index e91a07172e7..30271e196c5 100644
--- a/src/Cp/Components/Button.php
+++ b/src/Cp/Components/Button.php
@@ -5,11 +5,10 @@
 namespace CraftCms\Cms\Cp\Components;
 
 use Closure;
-use CraftCms\Cms\Cp\Concerns\HasAppearance;
 use CraftCms\Cms\Cp\Concerns\HasDisabled;
 use CraftCms\Cms\Cp\Concerns\HasId;
 use CraftCms\Cms\Cp\Concerns\HasSize;
-use CraftCms\Cms\Cp\Concerns\HasVariant;
+use CraftCms\Cms\Cp\Enums\ButtonVariant;
 use Illuminate\Contracts\Support\Htmlable;
 use Illuminate\Support\HtmlString;
 use Stringable;
@@ -29,11 +28,13 @@
  */
 class Button extends ViewComponent
 {
-    use HasAppearance;
     use HasDisabled;
     use HasId;
     use HasSize;
-    use HasVariant;
+
+    protected ButtonVariant|string|Closure|null $variant = null;
+
+    protected bool|Closure $inherit = false;
 
     protected string|Closure $type = 'button';
 
@@ -70,6 +71,39 @@ public function type(string|Closure $type): static
         return $this;
     }
 
+    /** The button's visual style (the single variant axis). */
+    public function variant(ButtonVariant|string|Closure|null $variant): static
+    {
+        $this->variant = $variant;
+
+        return $this;
+    }
+
+    public function getVariant(): ?string
+    {
+        $variant = $this->evaluate($this->variant);
+
+        if ($variant === null) {
+            return null;
+        }
+
+        return $variant instanceof ButtonVariant
+            ? $variant->value
+            : ButtonVariant::from($variant)->value;
+    }
+
+    /**
+     * Adopt the ambient colorable palette (from a colorable ancestor, e.g. a
+     * callout) instead of the neutral palette. Only affects the neutral
+     * variants; `primary` and `danger` stay stable.
+     */
+    public function inherit(bool|Closure $inherit = true): static
+    {
+        $this->inherit = $inherit;
+
+        return $this;
+    }
+
     /** The button label (default slot). Plain strings are HTML-encoded. */
     public function label(string|Htmlable|Stringable|ViewComponent|Closure|null $label): static
     {
@@ -178,7 +212,7 @@ protected function hostAttributes(): array
             'id' => $this->getId(),
             'type' => $this->evaluate($this->href) === null ? $type : null,
             'variant' => $this->getVariant(),
-            'appearance' => $this->getAppearance(),
+            'inherit' => (bool) $this->evaluate($this->inherit),
             'size' => $this->getSize(),
             'icon' => $this->evaluate($this->icon),
             'icon-position' => $this->evaluate($this->iconPosition),
diff --git a/src/Cp/Enums/ButtonVariant.php b/src/Cp/Enums/ButtonVariant.php
new file mode 100644
index 00000000000..9d92be94d8d
--- /dev/null
+++ b/src/Cp/Enums/ButtonVariant.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CraftCms\Cms\Cp\Enums;
+
+/**
+ * The single visual axis for a button, combining color and appearance. Mirrors
+ * `ButtonVariant` in `@craftcms/cp` (src/components/button/button.ts).
+ *
+ * `Primary` and `Danger` are colored (accent / danger) and stable; every other
+ * value uses the neutral palette in the named appearance. The button's separate
+ * `inherit` flag makes the neutral variants adopt an ambient colorable palette.
+ */
+enum ButtonVariant: string
+{
+    case Primary = 'primary';
+    case Danger = 'danger';
+    case DangerPlain = 'danger-plain';
+    case Solid = 'solid';
+    case Fill = 'fill';
+    case Outline = 'outline';
+    case Dashed = 'dashed';
+    case Plain = 'plain';
+    case Link = 'link';
+    case None = 'none';
+}
diff --git a/src/Cp/FormFields.php b/src/Cp/FormFields.php
index bfef0a700ec..d2eebcb54fc 100644
--- a/src/Cp/FormFields.php
+++ b/src/Cp/FormFields.php
@@ -223,7 +223,7 @@ public static function buttonFromConfig(array $config): Button
             ->prefix(! isset($config['icon']) ? ($config['iconHtml'] ?? null) : null)
             ->disabled((bool) ($config['disabled'] ?? $readOnly))
             ->size($size)
-            ->appearance($config['appearance'] ?? null)
+            ->variant($config['variant'] ?? $config['appearance'] ?? null)
             ->command($config['command'] ?? null)
             ->attributes(Arr::merge(
                 [
@@ -261,7 +261,7 @@ public static function buttonGroupFieldHtml(array $config): string
     public static function buttonGroupFromConfig(array $config): ButtonGroup
     {
         $value = $config['value'] ?? null;
-        $appearance = $config['appearance'] ?? 'outline';
+        $variant = $config['variant'] ?? $config['appearance'] ?? 'outline';
         $size = $config['size'] ?? null;
         $disabled = ($config['disabled'] ?? false) || ($config['static'] ?? false);
 
@@ -280,7 +280,7 @@ public static function buttonGroupFromConfig(array $config): ButtonGroup
                     ? new HtmlString((string) $option['labelHtml'])
                     : ($option['label'] ?? null))
                 ->icon($option['icon'] ?? null)
-                ->appearance($option['appearance'] ?? $appearance)
+                ->variant($option['variant'] ?? $option['appearance'] ?? $variant)
                 ->size($option['size'] ?? $size)
                 ->active($selected)
                 ->disabled($disabled)
diff --git a/src/Cp/Html/ElementHtml.php b/src/Cp/Html/ElementHtml.php
index 0b36aa7be0b..4326c60f464 100644
--- a/src/Cp/Html/ElementHtml.php
+++ b/src/Cp/Html/ElementHtml.php
@@ -839,8 +839,8 @@ function () use ($component, $withEdit): string {
                 ]), [
                     'type' => 'button',
                     'slot' => 'invoker',
-                    'appearance' => 'plain',
-                    'variant' => 'inherit',
+                    'variant' => 'plain',
+                    'inherit' => true,
                     'size' => 'small',
                     // Bare `icon` attribute triggers the icon-only button styling
                     // (the icon itself is slotted content, not the `icon` prop —
diff --git a/src/Cp/Html/PreviewHtml.php b/src/Cp/Html/PreviewHtml.php
index c0997526b49..feb51f5ba81 100644
--- a/src/Cp/Html/PreviewHtml.php
+++ b/src/Cp/Html/PreviewHtml.php
@@ -94,7 +94,7 @@ public function componentPreviewHtml(array $components, array $chipConfig = []):
                 'type' => 'button',
                 'label' => implode(', ', array_map(fn (Chippable $component) => $component->getId(), $components)),
                 'size' => 'small',
-                'appearance' => 'filled',
+                'variant' => 'fill',
                 'data' => [
                     'other' => Json::encode($otherHtml),
                 ],
diff --git a/src/Field/ButtonGroup.php b/src/Field/ButtonGroup.php
index 786c8b622f7..dbf2a13cf99 100644
--- a/src/Field/ButtonGroup.php
+++ b/src/Field/ButtonGroup.php
@@ -103,7 +103,7 @@ private function _inputHtml(SingleOptionFieldData $value, ?ElementInterface $ele
             $buttons[] = Button::make()
                 ->label($option['label'] ?? null)
                 ->icon($option['icon'] ?? null)
-                ->appearance('outline')
+                ->variant('outline')
                 ->active($selected)
                 ->disabled($static)
                 ->attributes(Arr::merge([
diff --git a/src/Field/Icon.php b/src/Field/Icon.php
index 8a587fc4487..18abebd3b66 100644
--- a/src/Field/Icon.php
+++ b/src/Field/Icon.php
@@ -7,7 +7,6 @@
 use CraftCms\Aliases\Aliases;
 use CraftCms\Cms\Cms;
 use CraftCms\Cms\Cp\Components\Button;
-use CraftCms\Cms\Cp\Enums\Appearance;
 use CraftCms\Cms\Cp\FormFields;
 use CraftCms\Cms\Cp\Icons;
 use CraftCms\Cms\Element\Contracts\ElementInterface;
@@ -135,7 +134,7 @@ private function settingsHtml(bool $readOnly): string
                 Html::beginTag('craft-disclosure').
                 Button::make()
                     ->label(t('Advanced'))
-                    ->appearance(Appearance::Plain)
+                    ->variant('plain')
                     ->icon('chevron-down')
                     ->slot('invoker')
                     ->attributes([
diff --git a/src/Field/Link.php b/src/Field/Link.php
index dc09343ddf1..81ab92dbe97 100644
--- a/src/Field/Link.php
+++ b/src/Field/Link.php
@@ -8,7 +8,7 @@
 use CraftCms\Cms\Cms;
 use CraftCms\Cms\Component\ComponentHelper;
 use CraftCms\Cms\Cp\Components\Button;
-use CraftCms\Cms\Cp\Enums\Appearance;
+use CraftCms\Cms\Cp\Enums\ButtonVariant;
 use CraftCms\Cms\Cp\FormFields;
 use CraftCms\Cms\Element\Contracts\ElementInterface;
 use CraftCms\Cms\Element\Queries\Contracts\ElementQueryInterface;
@@ -272,7 +272,7 @@ private function settingsHtml(bool $readOnly): string
             Button::make()
                 ->label(t('Advanced'))
                 ->icon('chevron-down')
-                ->appearance(Appearance::Plain)
+                ->variant(ButtonVariant::Plain)
                 ->attributes([
                     'slot' => 'invoker',
                     'class' => 'justify-self-start',
diff --git a/src/Support/Facades/HtmlSanitizers.php b/src/Support/Facades/HtmlSanitizers.php
index 87015512475..1a447e7561c 100644
--- a/src/Support/Facades/HtmlSanitizers.php
+++ b/src/Support/Facades/HtmlSanitizers.php
@@ -24,7 +24,7 @@
  * @method static \CraftCms\Cms\Support\HtmlSanitizer\HtmlSanitizerManager setContainer(\Illuminate\Contracts\Container\Container $container)
  * @method static \CraftCms\Cms\Support\HtmlSanitizer\HtmlSanitizerManager forgetDrivers()
  *
- * @see \CraftCms\Cms\Support\HtmlSanitizer\HtmlSanitizerManager
+ * @see HtmlSanitizerManager
  */
 class HtmlSanitizers extends Facade
 {
diff --git a/src/Support/Facades/Template.php b/src/Support/Facades/Template.php
index 65669fd5ed7..db70830d8e4 100644
--- a/src/Support/Facades/Template.php
+++ b/src/Support/Facades/Template.php
@@ -30,7 +30,7 @@
  * @method static \CraftCms\Cms\View\TemplateManager setContainer(\Illuminate\Contracts\Container\Container $container)
  * @method static \CraftCms\Cms\View\TemplateManager forgetDrivers()
  *
- * @see \CraftCms\Cms\View\TemplateManager
+ * @see TemplateManager
  */
 class Template extends Facade
 {
diff --git a/tests/Unit/Cp/Components/ButtonTest.php b/tests/Unit/Cp/Components/ButtonTest.php
index a7b9fada729..74f50cc70a1 100644
--- a/tests/Unit/Cp/Components/ButtonTest.php
+++ b/tests/Unit/Cp/Components/ButtonTest.php
@@ -3,27 +3,30 @@
 declare(strict_types=1);
 
 use CraftCms\Cms\Cp\Components\Button;
-use CraftCms\Cms\Cp\Enums\Appearance;
+use CraftCms\Cms\Cp\Enums\ButtonVariant;
 use CraftCms\Cms\Cp\Enums\Size;
-use CraftCms\Cms\Cp\Enums\Variant;
 use Illuminate\Support\HtmlString;
 
 describe('attributes', function () {
-    it('renders variant, appearance, size, and icon', function () {
+    it('renders variant, size, and icon', function () {
         $html = Button::make()
-            ->variant(Variant::Danger)
-            ->appearance(Appearance::Outline)
+            ->variant(ButtonVariant::Outline)
             ->size(Size::Small)
             ->icon('trash')
             ->toHtml();
 
         expect($html)->toStartWith('<craft-button')
-            ->and($html)->toContain('variant="danger"')
-            ->and($html)->toContain('appearance="outline"')
+            ->and($html)->toContain('variant="outline"')
+            ->and($html)->not->toContain('appearance=')
             ->and($html)->toContain('size="small"')
             ->and($html)->toContain('icon="trash"');
     });
 
+    it('renders the inherit flag when set', function () {
+        expect(Button::make()->toHtml())->not->toContain('inherit');
+        expect(Button::make()->inherit()->toHtml())->toContain('inherit');
+    });
+
     it('always renders an explicit type, since the web component defaults to submit', function () {
         expect(Button::make()->toHtml())->toContain('type="button"');
 
diff --git a/tests/Unit/Twig/Templates/ButtonTemplateTest.php b/tests/Unit/Twig/Templates/ButtonTemplateTest.php
index 5a05337c9e4..0d9b7945b95 100644
--- a/tests/Unit/Twig/Templates/ButtonTemplateTest.php
+++ b/tests/Unit/Twig/Templates/ButtonTemplateTest.php
@@ -49,14 +49,14 @@
         ->toContainTag('craft-button', [
             'data-value' => 'left',
             'type' => 'button',
-            'appearance' => 'outline',
+            'variant' => 'outline',
             'active' => 'true',
             'aria-pressed' => 'true',
         ])
         ->toContainTag('craft-button', [
             'data-value' => 'right',
             'type' => 'button',
-            'appearance' => 'outline',
+            'variant' => 'outline',
             'aria-pressed' => 'false',
         ])
         ->and($html)->not->toContainTag('input', ['type' => 'hidden']);

From 67dce1e0acd62c52a2142d8ad39edaf06ea25946 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Thu, 23 Jul 2026 16:41:12 -0500
Subject: [PATCH 5/8] Default buttons to type=button

---
 .../src/components/button/button.test.ts      | 16 +++++++++++++
 .../src/components/button/button.ts           | 24 ++++++++++++++++++-
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/packages/craftcms-ui/src/components/button/button.test.ts b/packages/craftcms-ui/src/components/button/button.test.ts
index 83c66ed4e2f..f8d6c8962fc 100644
--- a/packages/craftcms-ui/src/components/button/button.test.ts
+++ b/packages/craftcms-ui/src/components/button/button.test.ts
@@ -91,6 +91,22 @@ describe('craft-button link semantics', () => {
     const element = await createButton();
     expect(element.getAttribute('role')).toBe('button');
     expect(element.tabIndex).toBe(0);
+    // Defaults to "button" even though we extend LionButtonSubmit.
+    expect(element.type).toBe('button');
+  });
+
+  it('honors an explicit type="submit"', async () => {
+    const element = await createButton({type: 'submit'});
+    expect(element.type).toBe('submit');
+  });
+
+  it('restores an explicit type="submit" when href is removed', async () => {
+    const element = await createButton({type: 'submit', href: '/x'});
+    expect(element.type).toBe('button');
+
+    element.href = null;
+    await element.updateComplete;
+
     expect(element.type).toBe('submit');
   });
 
diff --git a/packages/craftcms-ui/src/components/button/button.ts b/packages/craftcms-ui/src/components/button/button.ts
index 101b1c5ac1f..3f914953539 100644
--- a/packages/craftcms-ui/src/components/button/button.ts
+++ b/packages/craftcms-ui/src/components/button/button.ts
@@ -44,12 +44,26 @@ export default class CraftButton extends LionButtonSubmit {
     return [...super.styles, styles];
   }
 
+  constructor() {
+    super();
+    // We extend LionButtonSubmit so `type="submit"`/`"reset"` Just Work inside
+    // forms, but a plain action button is the far more common case — and Lion
+    // gates all of its submit/reset helper wiring behind `type`, so defaulting
+    // to "button" also skips that runtime cost. (LionButtonSubmit's constructor
+    // sets this to "submit"; we override it after super().)
+    this.type = 'button';
+  }
+
   override connectedCallback() {
     // Set link-appropriate host state *before* Lion runs, so it skips its
     // role="button" assignment and (via type) its submit-helper wiring.
     if (this.href && !this.disabled) {
+      this.originalType = this.type;
       this.type = 'button';
       this.setAttribute('role', 'presentation');
+      // Mark link state as applied so syncLinkHostState() below re-applies the
+      // rest (tabindex) without re-capturing the (now-overwritten) type.
+      this.linkHostStateApplied = true;
     }
     super.connectedCallback();
     this.syncLinkHostState();
@@ -64,13 +78,18 @@ export default class CraftButton extends LionButtonSubmit {
 
   private syncLinkHostState() {
     if (this.isLink) {
+      if (!this.linkHostStateApplied) {
+        // Capture the caller's intended type before we force "button" for the
+        // link, so we can restore it if `href` is later removed.
+        this.originalType = this.type;
+      }
       this.setAttribute('role', 'presentation');
       this.tabIndex = -1;
       this.type = 'button';
       this.linkHostStateApplied = true;
     } else if (this.linkHostStateApplied) {
       this.setAttribute('role', 'button');
-      this.type = 'submit';
+      this.type = this.originalType ?? 'button';
       if (!this.disabled) {
         this.tabIndex = 0;
       }
@@ -157,6 +176,9 @@ export default class CraftButton extends LionButtonSubmit {
 
   private linkHostStateApplied = false;
 
+  /** The caller's `type` before link mode forced it to "button". */
+  private originalType: string | null = null;
+
   private get isLink(): boolean {
     return !!this.href && !this.disabled;
   }

From fcba26ede2fe7206e56fc311f47025f299815da6 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 09:44:22 -0500
Subject: [PATCH 6/8] Replace appearance with variant

---
 .../action-menu/action-menu.stories.ts        |  8 ++---
 .../src/components/chip/chip.stories.ts       | 10 +++---
 .../src/components/disclosure/disclosure.ts   |  2 +-
 .../src/components/info-icon/info-icon.ts     |  2 +-
 .../input-password/input-password.ts          |  1 -
 .../src/components/nav-item/nav-item.ts       |  2 +-
 .../reorder-button/reorder-button.ts          |  2 +-
 resources/images/craftcms.svg                 |  3 ++
 resources/js/common/components/ActionMenu.vue | 32 +++++++++----------
 resources/js/common/components/ModalForm.vue  |  2 +-
 resources/js/common/components/UserMenu.vue   |  2 +-
 resources/js/common/form/InputCombobox.vue    |  2 +-
 resources/js/common/layouts/AuthBase.vue      |  2 +-
 .../auth/components/login/login-challenge.ts  |  2 +-
 .../auth/components/login/login-form.ts       |  2 +-
 .../components/login/login-reset-password.ts  |  2 +-
 .../elements/components/BaseElementIndex.vue  |  6 ++--
 .../elements/components/BulkActionsBar.vue    |  2 +-
 .../components/ElementIndexToolbar.vue        |  6 ++--
 .../elements/components/IndexViewSettings.vue | 10 +++---
 .../elements/components/NewEntryButton.vue    |  5 ++-
 .../field-layout-designer.ts                  |  2 +-
 .../js/modules/link-field/craft-link-field.ts |  2 +-
 .../components/PreviewTargetsTable.vue        |  2 +-
 resources/js/pages/graphql/tokens/Edit.vue    |  2 +-
 resources/js/pages/install/Install.vue        |  2 +-
 resources/js/pages/users/Preferences.vue      |  4 +--
 .../fieldtypes/Markdown/settings.twig         |  2 +-
 .../_includes/forms/componentSelect.twig      |  2 +-
 .../_includes/forms/editableTable.twig        |  2 +-
 resources/views/forms/fld/designer.blade.php  |  4 +--
 resources/views/forms/fld/tab.blade.php       |  2 +-
 32 files changed, 66 insertions(+), 65 deletions(-)
 create mode 100644 resources/images/craftcms.svg

diff --git a/packages/craftcms-ui/src/components/action-menu/action-menu.stories.ts b/packages/craftcms-ui/src/components/action-menu/action-menu.stories.ts
index 71cdb1cb091..cc659624a5f 100644
--- a/packages/craftcms-ui/src/components/action-menu/action-menu.stories.ts
+++ b/packages/craftcms-ui/src/components/action-menu/action-menu.stories.ts
@@ -124,7 +124,7 @@ export const DataDrivenDisabled: Story = {
 export const SlotBasedDisabled: Story = {
   render: () =>
     html`<craft-action-menu disabled>
-      <craft-button type="button" slot="invoker" appearance="secondary">
+      <craft-button type="button" slot="invoker" variant="fill">
         Custom invoker
       </craft-button>
       <div slot="content">
@@ -140,7 +140,7 @@ export const SlotBasedDisabled: Story = {
 export const DataDrivenWithCustomInvoker: Story = {
   render: () =>
     html`<craft-action-menu .actions="${dataDrivenActions}">
-      <craft-button type="button" slot="invoker" appearance="secondary">
+      <craft-button type="button" slot="invoker" variant="fill">
         Custom invoker
       </craft-button>
     </craft-action-menu>`,
@@ -156,7 +156,7 @@ export const DataDrivenWithCustomInvoker: Story = {
 export const Searchable: Story = {
   render: () =>
     html`<craft-action-menu searchable>
-      <craft-button type="button" slot="invoker" appearance="secondary">
+      <craft-button type="button" slot="invoker" variant="fill">
         Add a field
       </craft-button>
 
@@ -218,7 +218,7 @@ export const SearchableDataDriven: Story = {
 export const SearchableWithHiddenItems: Story = {
   render: () =>
     html`<craft-action-menu searchable>
-      <craft-button type="button" slot="invoker" appearance="secondary">
+      <craft-button type="button" slot="invoker" variant="fill">
         Add a field
       </craft-button>
 
diff --git a/packages/craftcms-ui/src/components/chip/chip.stories.ts b/packages/craftcms-ui/src/components/chip/chip.stories.ts
index 27fdd32c427..3e72930a569 100644
--- a/packages/craftcms-ui/src/components/chip/chip.stories.ts
+++ b/packages/craftcms-ui/src/components/chip/chip.stories.ts
@@ -29,7 +29,7 @@ export const PrefixAndSuffix: Story = {
     <craft-chip>
       <craft-status slot="prefix" status="live"></craft-status>
       This is a chip
-      <craft-button icon size="small" appearance="plain" slot="suffix">
+      <craft-button icon size="small" variant="plain" slot="suffix">
         <craft-icon name="ellipsis" label="Actions"></craft-icon>
       </craft-button>
     </craft-chip>
@@ -42,7 +42,7 @@ export const Thumbnail: Story = {
     <craft-chip>
       <img slot="thumbnail" src="https://picsum.photos/300/300" alt="" />
       This is a chip
-      <craft-button icon size="small" appearance="plain" slot="suffix">
+      <craft-button icon size="small" variant="plain" slot="suffix">
         <craft-icon name="ellipsis" label="Actions"></craft-icon>
       </craft-button>
     </craft-chip>
@@ -63,7 +63,7 @@ export const SuffixOnly: Story = {
   args: {},
   render: (args) => html`
     <craft-chip>
-      <craft-button icon size="small" appearance="plain" slot="suffix">
+      <craft-button icon size="small" variant="plain" slot="suffix">
         <craft-icon name="ellipsis" label="Actions"></craft-icon>
       </craft-button>
       This is a chip
@@ -84,8 +84,8 @@ export const Colors: Story = {
               <craft-button
                 size="small"
                 slot="suffix"
-                variant="inherit"
-                appearance="plain"
+                inherit
+                variant="plain"
                 >Button</craft-button
               >
             </craft-chip>`
diff --git a/packages/craftcms-ui/src/components/disclosure/disclosure.ts b/packages/craftcms-ui/src/components/disclosure/disclosure.ts
index 81fedec2cd7..2e2aa95af73 100644
--- a/packages/craftcms-ui/src/components/disclosure/disclosure.ts
+++ b/packages/craftcms-ui/src/components/disclosure/disclosure.ts
@@ -11,7 +11,7 @@ import '../button/button.js';
  * `slot="invoker"` trigger and `slot="content"` collapsible content. Without a
  * slotted invoker, renders a default one from the `label` attribute:
  *
- *     <craft-button type="button" appearance="plain" icon="chevron-down">${label}</craft-button>
+ *     <craft-button type="button" variant="plain" icon="chevron-down">${label}</craft-button>
  *
  * **External-target mode** — wraps a bare `button[type="button"]` whose
  * `aria-controls` names an element elsewhere in the document; toggling flips
diff --git a/packages/craftcms-ui/src/components/info-icon/info-icon.ts b/packages/craftcms-ui/src/components/info-icon/info-icon.ts
index 55e2653024e..1619fc0e4d8 100644
--- a/packages/craftcms-ui/src/components/info-icon/info-icon.ts
+++ b/packages/craftcms-ui/src/components/info-icon/info-icon.ts
@@ -105,7 +105,7 @@ export default class CraftInfoIcon extends LitElement {
           type="button"
           icon
           size="zero"
-          appearance="plain"
+          variant="plain"
           id="${this.id}"
         >
           <craft-icon name="${this.icon}" label="${this.label}"></craft-icon>
diff --git a/packages/craftcms-ui/src/components/input-password/input-password.ts b/packages/craftcms-ui/src/components/input-password/input-password.ts
index 44db35cca88..5b509218278 100644
--- a/packages/craftcms-ui/src/components/input-password/input-password.ts
+++ b/packages/craftcms-ui/src/components/input-password/input-password.ts
@@ -47,7 +47,6 @@ export default class CraftInputPassword extends LionInput {
         size="small"
         variant="plain"
         @click="${this.reveal}"
-        appearance="plain"
       >
         <span class="icon"
           >${this._visible
diff --git a/packages/craftcms-ui/src/components/nav-item/nav-item.ts b/packages/craftcms-ui/src/components/nav-item/nav-item.ts
index 12e1ca40955..b3b177b37cf 100644
--- a/packages/craftcms-ui/src/components/nav-item/nav-item.ts
+++ b/packages/craftcms-ui/src/components/nav-item/nav-item.ts
@@ -113,7 +113,7 @@ export default class CraftNavItem extends LitElement {
     return html`
       <craft-button
         @click="${this.toggleSubnav}"
-        appearance="${Appearance.Plain}"
+        variant="${Appearance.Plain}"
         icon
         size="small"
         aria-controls="${this.id}-subnav"
diff --git a/packages/craftcms-ui/src/components/reorder-button/reorder-button.ts b/packages/craftcms-ui/src/components/reorder-button/reorder-button.ts
index a56cc7d998d..ae42ec806ec 100644
--- a/packages/craftcms-ui/src/components/reorder-button/reorder-button.ts
+++ b/packages/craftcms-ui/src/components/reorder-button/reorder-button.ts
@@ -123,7 +123,7 @@ export default class CraftReorderButton extends LitElement {
           type="button"
           icon
           size="small"
-          appearance="plain"
+          variant="plain"
           variant="${this.variant}"
           ?disabled="${this.disabled}"
         >
diff --git a/resources/images/craftcms.svg b/resources/images/craftcms.svg
new file mode 100644
index 00000000000..ce6010dfff0
--- /dev/null
+++ b/resources/images/craftcms.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="104" height="26" viewBox="0 0 104 26">
+  <path fill="#596673" d="M36.0159091 15.3931818C34.3022727 15.3931818 33.3568182 14.3 33.5931818 12.7340909 33.8590909 11.1386364 35.1590909 10.075 36.8431818 10.075 37.7295455 10.075 38.5272727 10.4886364 39 11.1090909L40.6545455 9.75C39.7681818 8.74545455 38.4977273 8.24318182 37.1386364 8.24318182 34.3613636 8.24318182 31.9386364 10.1045455 31.525 12.7340909 31.1113636 15.3931818 32.8840909 17.225 35.6909091 17.225 37.1090909 17.225 38.5272727 16.6340909 39.7681818 15.6590909L38.5863636 14.3C37.7295455 15.0681818 36.8431818 15.3931818 36.0159091 15.3931818M47.125 8.33181818C47.125 8.33181818 46.7704545 8.27272727 46.7409091 8.27272727 46.3568182 8.21363636 45.9431818 8.24318182 45.5590909 8.27272727 45.2045455 8.30227273 44.85 8.36136364 44.4954545 8.47954545 44.2 8.56818182 43.875 8.68636364 43.6090909 8.86363636L43.6681818 8.45 41.6590909 8.45 40.3 17.0181818 42.3090909 17.0181818 43.1068182 12.025C43.1363636 11.7295455 43.2545455 11.4636364 43.4022727 11.2272727 43.55 10.9909091 43.7568182 10.7840909 43.9931818 10.6363636 44.2295455 10.4590909 44.4659091 10.3409091 44.7318182 10.2522727 44.9977273 10.1636364 45.2636364 10.1045455 45.5590909 10.075 45.9431818 10.0454545 46.3568182 10.075 46.7409091 10.1636364 46.7409091 10.1636364 46.7704545 10.1636364 46.7704545 10.1636364 46.8295455 10.1636364 47.125 8.33181818 47.125 8.33181818M54.1568182 8.98181818C53.5954545 8.50909091 52.7386364 8.24318182 51.7340909 8.24318182 49.2227273 8.24318182 46.9477273 10.0454545 46.5045455 12.7045455 46.0909091 15.3636364 47.8340909 17.1659091 50.2568182 17.1659091 51.35 17.1659091 52.2659091 17.0181818 53.0340909 16.4863636L52.975 16.9590909 54.8068182 16.9590909 56.1363636 8.45 54.2454545 8.45 54.1568182 8.98181818zM53.7431818 12.7045455L53.7431818 12.7045455C53.4772727 14.3295455 52.2659091 15.4522727 50.7 15.4522727 49.1045455 15.4522727 48.1886364 14.2704545 48.4545455 12.675 48.7204545 11.0795455 49.9909091 9.95681818 51.5568182 9.95681818 53.1227273 9.98636364 53.9795455 11.0795455 53.7431818 12.7045455L53.7431818 12.7045455zM65.4136364 8.45L65.7977273 6.02727273 63.4931818 7.68181818 63.375 8.47954545 60.775 8.47954545 61.0409091 6.85454545C61.1886364 6.08636364 62.0159091 6.11590909 62.0159091 6.11590909L62.9909091 6.11590909 63.2863636 4.34318182 62.1636364 4.34318182 61.8977273 4.34318182C59.15 4.34318182 59.0613636 6.47045455 59.0613636 6.47045455L58.8840909 7.475 58.7363636 8.47954545 58.5590909 8.47954545 56.3136364 10.2522727 58.4409091 10.2522727 57.0818182 18.9090909 59.15 18.9090909 60.5090909 10.2227273 63.1090909 10.2227273 62.0454545 17.0181818 64.0840909 17.0181818 65.1477273 10.2227273 67.6886364 10.2227273 67.9840909 8.45 65.4136364 8.45zM70.8795455 12.7340909C71.2931818 10.1045455 73.6863636 8.24318182 76.4931818 8.24318182 77.8522727 8.24318182 79.1227273 8.775 80.0090909 9.75L78.3545455 11.1090909C77.8818182 10.4886364 77.0840909 10.075 76.1977273 10.075 74.5136364 10.075 73.2136364 11.1681818 72.9477273 12.7340909 72.7113636 14.3 73.6568182 15.3931818 75.3704545 15.3931818 76.1977273 15.3931818 77.0840909 15.0681818 77.9409091 14.3L79.1227273 15.6590909C77.8818182 16.6636364 76.4636364 17.225 75.0454545 17.225 72.2386364 17.225 70.4659091 15.3931818 70.8795455 12.7340909M94.8113636 11.8181818L94.0136364 17.0181818 92.0045455 17.0181818 92.8022727 11.9659091C93.0090909 10.7840909 92.3590909 10.075 91.2068182 10.075 89.9954545 10.075 88.7840909 10.8136364 88.6068182 12.025L87.8090909 17.0181818 85.8 17.0181818 86.5977273 11.9659091C86.775 10.8136364 86.0954545 10.1045455 85.0022727 10.075 83.8795455 10.1340909 82.5795455 10.8431818 82.4022727 12.025L81.6045455 17.0181818 79.5954545 17.0181818 80.9545455 8.45 82.9636364 8.45 82.9045455 8.86363636C83.5840909 8.45 84.3522727 8.27272727 85.3272727 8.24318182L85.5045455 8.24318182C86.7454545 8.24318182 87.75 8.74545455 88.2818182 9.60227273 89.1090909 8.74545455 90.3795455 8.24318182 91.65 8.24318182 93.8363636 8.24318182 95.1659091 9.69090909 94.8113636 11.8181818M94.7227273 15.9840909L95.9636364 14.4477273C96.6431818 14.9795455 97.9431818 15.3931818 99.0363636 15.3931818 100.040909 15.3931818 101.045455 15.1863636 101.163636 14.5068182 101.252273 13.975 100.277273 13.7977273 99.1840909 13.6204545 96.9090909 13.2363636 95.7568182 12.7636364 95.9931818 11.05 96.3477273 8.89318182 98.5636364 8.27272727 100.395455 8.27272727 101.695455 8.27272727 103.054545 8.71590909 103.970455 9.33636364L102.729545 10.8727273C102.020455 10.4295455 101.104545 10.1045455 100.070455 10.1045455 98.8590909 10.1045455 98.15 10.4590909 98.0613636 11.0204545 98.0022727 11.4045455 98.3272727 11.5522727 99.7454545 11.7886364 101.813636 12.1431818 103.527273 12.4681818 103.202273 14.4477273 102.936364 16.25 101.104545 17.2545455 98.7113636 17.2545455 97.3818182 17.225 95.6681818 16.7522727 94.7227273 15.9840909M22.6022727 0L2.65909091 0C1.18181818 0 0 1.18181818 0 2.65909091L0 22.6022727C0 24.0795455 1.18181818 25.2613636 2.65909091 25.2613636L22.6022727 25.2613636C24.05 25.2613636 25.2613636 24.0795455 25.2613636 22.6022727L25.2613636 2.65909091C25.2613636 1.18181818 24.0795455 0 22.6022727 0M12.5863636 15.3931818C13.4136364 15.3931818 14.3 15.0681818 15.1568182 14.3L16.3386364 15.6590909C15.0977273 16.6636364 13.6795455 17.225 12.2613636 17.225 9.45454545 17.225 7.68181818 15.3636364 8.09545455 12.7340909 8.50909091 10.1045455 10.9022727 8.24318182 13.7090909 8.24318182 15.0681818 8.24318182 16.3386364 8.775 17.225 9.75L15.5704545 11.1090909C15.0977273 10.4886364 14.3 10.075 13.4136364 10.075 11.7295455 10.075 10.4295455 11.1681818 10.1636364 12.7340909 9.92727273 14.3 10.8727273 15.3931818 12.5863636 15.3931818"/>
+</svg>
diff --git a/resources/js/common/components/ActionMenu.vue b/resources/js/common/components/ActionMenu.vue
index c45815150d8..188d141190f 100644
--- a/resources/js/common/components/ActionMenu.vue
+++ b/resources/js/common/components/ActionMenu.vue
@@ -1,6 +1,5 @@
 <script setup lang="ts">
-  import type {ActionMenuItem} from '@craftcms/ui';
-  import {Appearance, t} from '@craftcms/ui';
+  import {type ActionMenuItem, ButtonVariant, t} from '@craftcms/ui';
   import {
     type Component,
     computed,
@@ -82,6 +81,20 @@
   onBeforeUnmount(() => {
     clearDisplayContainers();
   });
+
+  /**
+   `v-once` is load-bearing, not an optimization. `craft-action-menu` (Lion
+   `OverlayMixin`) imperatively relocates/restructures its own light DOM. If Vue
+   keeps the invoker in its reactive patch path, a later re-render patches the
+   invoker's slot fragment against DOM the element moved and throws "Cannot read
+   properties of null (reading 'insertBefore')". A passive wrapper isn't enough:
+   Vue's block optimization flattens dynamic descendants and patches them with
+   `craft-action-menu` as the container, bypassing the wrapper. `v-once` renders
+   the invoker exactly once and removes it from the block's dynamic children, so
+   Vue never re-patches the overlay-managed DOM. Invokers are static triggers
+   (an icon / avatar), so freezing them is safe. `inline-flex` keeps the wrapper
+   sized to the invoker so the overlay positions against a real box.
+   */
 </script>
 
 <template>
@@ -90,19 +103,6 @@
     :icon="icon"
     :label="label ?? undefined"
   >
-    <!--
-      `v-once` is load-bearing, not an optimization. `craft-action-menu` (Lion
-      `OverlayMixin`) imperatively relocates/restructures its own light DOM. If Vue
-      keeps the invoker in its reactive patch path, a later re-render patches the
-      invoker's slot fragment against DOM the element moved and throws "Cannot read
-      properties of null (reading 'insertBefore')". A passive wrapper isn't enough:
-      Vue's block optimization flattens dynamic descendants and patches them with
-      `craft-action-menu` as the container, bypassing the wrapper. `v-once` renders
-      the invoker exactly once and removes it from the block's dynamic children, so
-      Vue never re-patches the overlay-managed DOM. Invokers are static triggers
-      (an icon / avatar), so freezing them is safe. `inline-flex` keeps the wrapper
-      sized to the invoker so the overlay positions against a real box.
-    -->
     <span slot="invoker" style="display: inline-flex" v-once>
       <slot name="invoker" :label="label" :attributes="{slot: 'invoker'}">
         <craft-button
@@ -110,7 +110,7 @@
           size="small"
           icon="ellipsis"
           :aria-label="label"
-          :appearance="Appearance.Outline"
+          :variant="ButtonVariant.Plain"
         >
         </craft-button>
       </slot>
diff --git a/resources/js/common/components/ModalForm.vue b/resources/js/common/components/ModalForm.vue
index c64043baf63..642a79145bb 100644
--- a/resources/js/common/components/ModalForm.vue
+++ b/resources/js/common/components/ModalForm.vue
@@ -48,7 +48,7 @@
 
         <slot></slot>
         <template #secondary-action>
-          <craft-button type="reset" @click="emit('close')" appearance="plain">
+          <craft-button type="reset" @click="emit('close')" variant="plain">
             {{ resetLabel }}
           </craft-button>
         </template>
diff --git a/resources/js/common/components/UserMenu.vue b/resources/js/common/components/UserMenu.vue
index 8adbd6f3505..8488a8ec91e 100644
--- a/resources/js/common/components/UserMenu.vue
+++ b/resources/js/common/components/UserMenu.vue
@@ -66,7 +66,7 @@
         slot="invoker"
         type="button"
         aria-label="User menu"
-        appearance="none"
+        variant="none"
       >
         <UserThumbnail />
       </craft-button>
diff --git a/resources/js/common/form/InputCombobox.vue b/resources/js/common/form/InputCombobox.vue
index e70cfba96ef..8fbf5cdff84 100644
--- a/resources/js/common/form/InputCombobox.vue
+++ b/resources/js/common/form/InputCombobox.vue
@@ -212,7 +212,7 @@
         v-if="canClear"
         class="absolute inset-y-1 right-7 flex items-center"
         type="button"
-        appearance="plain"
+        variant="plain"
         size="small"
         icon
         :aria-label="`Clear ${label}`"
diff --git a/resources/js/common/layouts/AuthBase.vue b/resources/js/common/layouts/AuthBase.vue
index 97ab5cbb056..c44be4de359 100644
--- a/resources/js/common/layouts/AuthBase.vue
+++ b/resources/js/common/layouts/AuthBase.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
   import {Head} from '@inertiajs/vue3';
   import useCraftData from '@/common/composables/useCraftData';
-  import craftCmsLogoUrl from '@public/images/craftcms.svg';
+  import craftCmsLogoUrl from '../../../images/craftcms.svg';
   import {t} from '@craftcms/ui';
 
   const props = withDefaults(
diff --git a/resources/js/modules/auth/components/login/login-challenge.ts b/resources/js/modules/auth/components/login/login-challenge.ts
index b3502cb06f7..b578246b888 100644
--- a/resources/js/modules/auth/components/login/login-challenge.ts
+++ b/resources/js/modules/auth/components/login/login-challenge.ts
@@ -144,7 +144,7 @@ export default class CraftLoginChallenge extends LitElement {
           ? html`
               <hr />
               <craft-action-menu>
-                <craft-button slot="invoker" appearance="plain" size="zero">
+                <craft-button slot="invoker" variant="plain" size="zero">
                   <craft-icon slot="prefix" name="chevron-down"></craft-icon>
                   ${t('Try another way')}
                 </craft-button>
diff --git a/resources/js/modules/auth/components/login/login-form.ts b/resources/js/modules/auth/components/login/login-form.ts
index e7cff171f71..8da419ded55 100644
--- a/resources/js/modules/auth/components/login/login-form.ts
+++ b/resources/js/modules/auth/components/login/login-form.ts
@@ -308,7 +308,7 @@ export default class CraftLoginForm extends LitElement {
                     <craft-button
                       type="button"
                       size="small"
-                      appearance="plain"
+                      variant="link"
                       @click="${this.#showResetPasswordForm}"
                       style="margin-block-start: var(--c-spacing-sm)"
                     >
diff --git a/resources/js/modules/auth/components/login/login-reset-password.ts b/resources/js/modules/auth/components/login/login-reset-password.ts
index 92c21b191e4..d74556a8cb1 100644
--- a/resources/js/modules/auth/components/login/login-reset-password.ts
+++ b/resources/js/modules/auth/components/login/login-reset-password.ts
@@ -116,7 +116,7 @@ export default class CraftLoginResetPassword extends LitElement {
 
         <craft-button
           type="button"
-          appearance="plain"
+          variant="link"
           size="small"
           @click="${this.#onBack}"
         >
diff --git a/resources/js/modules/elements/components/BaseElementIndex.vue b/resources/js/modules/elements/components/BaseElementIndex.vue
index 01095046e38..c2bcc3ed169 100644
--- a/resources/js/modules/elements/components/BaseElementIndex.vue
+++ b/resources/js/modules/elements/components/BaseElementIndex.vue
@@ -2,7 +2,7 @@
   import {computed, ref, watch} from 'vue';
   import {usePage} from '@inertiajs/vue3';
   import type {Table} from '@tanstack/vue-table';
-  import {Appearance, t} from '@craftcms/ui';
+  import {ButtonVariant, t} from '@craftcms/ui';
   import Text from '@/common/components/Text.vue';
   import Select from '@/common/form/Select.vue';
   import BulkActionsBar from '@/modules/elements/components/BulkActionsBar.vue';
@@ -143,7 +143,7 @@
               type="button"
               @click="table.previousPage()"
               :disabled="!table.getCanPreviousPage()"
-              :appearance="Appearance.Plain"
+              :variant="ButtonVariant.Plain"
               icon
               size="small"
             >
@@ -172,7 +172,7 @@
               @click="table.nextPage()"
               :disabled="!table.getCanNextPage()"
               size="small"
-              :appearance="Appearance.Plain"
+              :variant="ButtonVariant.Plain"
               icon
             >
               <craft-icon
diff --git a/resources/js/modules/elements/components/BulkActionsBar.vue b/resources/js/modules/elements/components/BulkActionsBar.vue
index 4fa6b9d580f..f80bb4d9d03 100644
--- a/resources/js/modules/elements/components/BulkActionsBar.vue
+++ b/resources/js/modules/elements/components/BulkActionsBar.vue
@@ -195,7 +195,7 @@
       <craft-button
         type="button"
         size="small"
-        appearance="plain"
+        variant="plain"
         @click="emit('clear')"
       >
         {{ t('Clear selection') }}
diff --git a/resources/js/modules/elements/components/ElementIndexToolbar.vue b/resources/js/modules/elements/components/ElementIndexToolbar.vue
index cf993cbc24a..7ce5b7fc6b6 100644
--- a/resources/js/modules/elements/components/ElementIndexToolbar.vue
+++ b/resources/js/modules/elements/components/ElementIndexToolbar.vue
@@ -75,7 +75,7 @@
               type="button"
               icon
               size="small"
-              appearance="plain"
+              variant="plain"
               v-if="search"
               @click="search = ''"
             >
@@ -85,7 +85,7 @@
               type="button"
               icon
               size="small"
-              appearance="plain"
+              variant="plain"
               @click="filterActive = true"
               :class="{'is-active': !!conditions}"
             >
@@ -113,7 +113,7 @@
         <template v-for="viewMode in viewModes" :key="viewMode.mode">
           <craft-button
             type="button"
-            :appearance="Appearance.Fill"
+            :variant="Appearance.Fill"
             :icon="viewMode.icon"
             :aria-label="viewMode.title"
             :value="viewMode.mode"
diff --git a/resources/js/modules/elements/components/IndexViewSettings.vue b/resources/js/modules/elements/components/IndexViewSettings.vue
index ec34e8381f3..6914301d0a9 100644
--- a/resources/js/modules/elements/components/IndexViewSettings.vue
+++ b/resources/js/modules/elements/components/IndexViewSettings.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
   import {ref, watch} from 'vue';
-  import {Appearance, t} from '@craftcms/ui';
+  import {ButtonVariant, t} from '@craftcms/ui';
   import Select from '@/common/form/Select.vue';
   import CheckboxGroup from '@/common/form/CheckboxGroup.vue';
   import type {CheckboxOption} from '@/common/types';
@@ -77,7 +77,7 @@
       type="button"
       slot="invoker"
       icon="sliders"
-      :appearance="Appearance.Fill"
+      :variant="ButtonVariant.Fill"
     >
       {{ t('View') }}
     </craft-button>
@@ -100,7 +100,7 @@
               icon="asc"
               value="asc"
               :aria-label="t('Sort ascending')"
-              :appearance="Appearance.Fill"
+              :variant="ButtonVariant.Fill"
               :active="sortDirection === 'asc'"
             ></craft-button>
             <craft-button
@@ -108,7 +108,7 @@
               icon="desc"
               value="desc"
               :aria-label="t('Sort descending')"
-              :appearance="Appearance.Fill"
+              :variant="ButtonVariant.Fill"
               :active="sortDirection === 'desc'"
             ></craft-button>
           </craft-button-group>
@@ -130,7 +130,7 @@
       <craft-button
         type="button"
         @click="closePopover"
-        :appearance="Appearance.Fill"
+        :variant="ButtonVariant.Fill"
         >{{ t('Close') }}</craft-button
       >
     </div>
diff --git a/resources/js/modules/elements/components/NewEntryButton.vue b/resources/js/modules/elements/components/NewEntryButton.vue
index 5bf764dd85a..7eab6e5c229 100644
--- a/resources/js/modules/elements/components/NewEntryButton.vue
+++ b/resources/js/modules/elements/components/NewEntryButton.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
   import {computed} from 'vue';
-  import {t} from '@craftcms/ui';
+  import {ButtonVariant, t} from '@craftcms/ui';
   import ActionMenu from '@/common/components/ActionMenu.vue';
   import type {ActionItem} from '@/common/types';
   import type {Source, SourceItem} from '@/modules/elements/types/sources';
@@ -175,8 +175,7 @@
       <craft-button
         slot="invoker"
         type="button"
-        appearance="solid"
-        variant="accent"
+        :variant="ButtonVariant.Primary"
         icon="plus"
       >
         {{ t('New {type}', {type: elementDisplayName}) }}
diff --git a/resources/js/modules/field-layout-designer/field-layout-designer.ts b/resources/js/modules/field-layout-designer/field-layout-designer.ts
index 200a7a429d0..2238a93ee85 100644
--- a/resources/js/modules/field-layout-designer/field-layout-designer.ts
+++ b/resources/js/modules/field-layout-designer/field-layout-designer.ts
@@ -364,7 +364,7 @@ export class FieldLayoutDesigner extends Base<FieldLayoutDesignerSettings> {
       type="button" 
       class="w-full fld-add-btn" 
       command="--add-field"
-      appearance="outline"
+      variant="outline"
       size="small"
     >
       ${t('Add')}
diff --git a/resources/js/modules/link-field/craft-link-field.ts b/resources/js/modules/link-field/craft-link-field.ts
index 3a9975fb670..9bc71a18bfe 100644
--- a/resources/js/modules/link-field/craft-link-field.ts
+++ b/resources/js/modules/link-field/craft-link-field.ts
@@ -527,7 +527,7 @@ class CraftLinkField extends LitElement {
         <div class="buttons right">
           <craft-button
             type="button"
-            appearance="plain"
+            variant="plain"
             size="small"
             @click=${this.cancel}
           >
diff --git a/resources/js/modules/sections/components/PreviewTargetsTable.vue b/resources/js/modules/sections/components/PreviewTargetsTable.vue
index edad6923c5b..702589ceb42 100644
--- a/resources/js/modules/sections/components/PreviewTargetsTable.vue
+++ b/resources/js/modules/sections/components/PreviewTargetsTable.vue
@@ -90,7 +90,7 @@
       size="small"
       @click="addPreviewTarget"
       class="w-full"
-      appearance="plain"
+      variant="plain"
     >
       {{ t('Add a target') }}
     </craft-button>
diff --git a/resources/js/pages/graphql/tokens/Edit.vue b/resources/js/pages/graphql/tokens/Edit.vue
index bf8ea46b738..e79f1415b5b 100644
--- a/resources/js/pages/graphql/tokens/Edit.vue
+++ b/resources/js/pages/graphql/tokens/Edit.vue
@@ -145,7 +145,7 @@
             slot="suffix"
             type="button"
             size="small"
-            appearance="plain"
+            variant="plain"
             :disabled="loadingToken"
             @click="copyHeader"
           >
diff --git a/resources/js/pages/install/Install.vue b/resources/js/pages/install/Install.vue
index d5b5d412189..2dbf0fcd2d9 100644
--- a/resources/js/pages/install/Install.vue
+++ b/resources/js/pages/install/Install.vue
@@ -221,7 +221,7 @@
                 <craft-button
                   type="button"
                   @click="goToPrevious"
-                  appearance="plain"
+                  variant="plain"
                   class="justify-self-start"
                 >
                   {{ t('Back') }}
diff --git a/resources/js/pages/users/Preferences.vue b/resources/js/pages/users/Preferences.vue
index e0bebf4abb2..3f9e1263890 100644
--- a/resources/js/pages/users/Preferences.vue
+++ b/resources/js/pages/users/Preferences.vue
@@ -195,7 +195,7 @@
                 v-for="option in props.notificationPositionOptions"
                 :key="option.value"
                 type="button"
-                appearance="outline"
+                variant="outline"
                 :active="
                   form.notificationPosition === option.value ? 'true' : null
                 "
@@ -218,7 +218,7 @@
                 v-for="option in props.slideoutPositionOptions"
                 :key="option.value"
                 type="button"
-                appearance="outline"
+                variant="outline"
                 :active="form.slideoutPosition === option.value ? 'true' : null"
                 :aria-pressed="form.slideoutPosition === option.value"
                 :title="option.label"
diff --git a/resources/templates/_components/fieldtypes/Markdown/settings.twig b/resources/templates/_components/fieldtypes/Markdown/settings.twig
index f2fefd7ce3d..dff2178b663 100644
--- a/resources/templates/_components/fieldtypes/Markdown/settings.twig
+++ b/resources/templates/_components/fieldtypes/Markdown/settings.twig
@@ -185,7 +185,7 @@
   <craft-disclosure>
     <craft-button
       type="button"
-      appearance="plain"
+      variant="plain"
       class="justify-self-start"
       icon="chevron-down"
       slot="invoker"
diff --git a/resources/templates/_includes/forms/componentSelect.twig b/resources/templates/_includes/forms/componentSelect.twig
index b8c374f3418..567e92ce9e1 100644
--- a/resources/templates/_includes/forms/componentSelect.twig
+++ b/resources/templates/_includes/forms/componentSelect.twig
@@ -150,7 +150,7 @@
           slot="invoker"
           icon="chevron-down"
           command="--choose-item"
-          appearance="outline"
+          variant="dashed"
           {{ attr({disabled: disabled}) }}
         >
           {{ 'Choose'|t('app') }}
diff --git a/resources/templates/_includes/forms/editableTable.twig b/resources/templates/_includes/forms/editableTable.twig
index 0820d3c85ec..769cda4fd8c 100644
--- a/resources/templates/_includes/forms/editableTable.twig
+++ b/resources/templates/_includes/forms/editableTable.twig
@@ -294,7 +294,7 @@
     <div
       class="border border-dashed border-neutral-border-quiet rounded-bl-md rounded-br-md border-t-0 p-1 pt-2 -mt-1"
     >
-      <craft-button type="button" appearance="plain" size="small" class="w-full" command="--add-row">
+      <craft-button type="button" variant="plain" size="small" class="w-full" command="--add-row">
         <craft-icon name="plus"></craft-icon>
         {{ buttonText }}
       </craft-button>
diff --git a/resources/views/forms/fld/designer.blade.php b/resources/views/forms/fld/designer.blade.php
index b3dd9169fad..7c3c66292f7 100644
--- a/resources/views/forms/fld/designer.blade.php
+++ b/resources/views/forms/fld/designer.blade.php
@@ -64,7 +64,7 @@ class="btngroup btngroup--exclusive"
                     <craft-button
                         type="button"
                         aria-pressed="true"
-                        appearance="outline"
+                        variant="outline"
                         size="small"
                         data-library="field"
                         class="w-full"
@@ -75,7 +75,7 @@ class="w-full"
                         type="button"
                         aria-pressed="false"
                         data-library="ui"
-                        appearance="outline"
+                        variant="outline"
                         size="small"
                         class="w-full"
                         @disabled($disabled)
diff --git a/resources/views/forms/fld/tab.blade.php b/resources/views/forms/fld/tab.blade.php
index a79d147f0d6..24efb2ca8d7 100644
--- a/resources/views/forms/fld/tab.blade.php
+++ b/resources/views/forms/fld/tab.blade.php
@@ -21,7 +21,7 @@
         <craft-button
             type="button"
             class="w-full fld-add-btn mt-2"
-            appearance="outline"
+            variant="outline"
             size="small"
             command="--add-field"
             @disabled($disabled)

From 7b6ea02e8434f9a67316390c2277d20a058bf9a2 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 10:19:43 -0500
Subject: [PATCH 7/8] Fix minor issues

---
 .../button-group/button-group.stories.ts      | 30 ++++++++-----------
 .../src/components/button/button.styles.ts    | 12 +++++++-
 2 files changed, 23 insertions(+), 19 deletions(-)

diff --git a/packages/craftcms-ui/src/components/button-group/button-group.stories.ts b/packages/craftcms-ui/src/components/button-group/button-group.stories.ts
index 7b349b56352..e68b9fa9065 100644
--- a/packages/craftcms-ui/src/components/button-group/button-group.stories.ts
+++ b/packages/craftcms-ui/src/components/button-group/button-group.stories.ts
@@ -68,29 +68,23 @@ export const RadioMode: Story = {
 };
 
 /**
- * Radio mode works across all button appearances. The selected button retains
- * its `active` styling regardless of the chosen appearance.
+ * Radio mode works across all button variants. The selected button retains
+ * its `active` styling regardless of the chosen variant.
  */
-export const RadioModeAppearances: Story = {
-  name: 'Radio mode — appearances',
+export const RadioModeVariants: Story = {
+  name: 'Radio mode — variants',
   render: () => html`
     <div style="display:flex;flex-direction:column;gap:1rem">
-      ${(['accent', 'filled', 'plain', 'dashed'] as const).map(
-        (appearance) => html`
+      ${(['solid', 'fill', 'outline', 'dashed', 'plain'] as const).map(
+        (variant) => html`
           <div style="display:flex;align-items:center;gap:1rem">
             <span style="width:4rem;font-size:0.75rem;color:var(--c-text-muted)"
-              >${appearance}</span
+              >${variant}</span
             >
-            <craft-button-group name="view-${appearance}" value="b">
-              <craft-button appearance="${appearance}" value="a"
-                >A</craft-button
-              >
-              <craft-button appearance="${appearance}" value="b"
-                >B</craft-button
-              >
-              <craft-button appearance="${appearance}" value="c"
-                >C</craft-button
-              >
+            <craft-button-group name="view-${variant}" value="b">
+              <craft-button variant="${variant}" value="a">A</craft-button>
+              <craft-button variant="${variant}" value="b">B</craft-button>
+              <craft-button variant="${variant}" value="c">C</craft-button>
             </craft-button-group>
           </div>
         `
@@ -139,7 +133,7 @@ export const FormAssociated: Story = {
         <craft-button value="table">Table</craft-button>
         <craft-button value="thumbs">Thumbnails</craft-button>
       </craft-button-group>
-      <craft-button type="submit" appearance="filled">Submit</craft-button>
+      <craft-button type="submit" variant="fill">Submit</craft-button>
     </form>
   `,
 };
diff --git a/packages/craftcms-ui/src/components/button/button.styles.ts b/packages/craftcms-ui/src/components/button/button.styles.ts
index 99eccc64031..3da1e944e00 100644
--- a/packages/craftcms-ui/src/components/button/button.styles.ts
+++ b/packages/craftcms-ui/src/components/button/button.styles.ts
@@ -97,6 +97,16 @@ export default css`
     --c-color-on-quiet: var(--c-color-danger-on-quiet);
   }
 
+  @media (hover: hover) {
+    :host(:hover) {
+      background-color: hsl(
+        from var(--c-color-fill-loud, var(--c-button-default-fill)) h s
+          calc(l - 5)
+      );
+      color: var(--c-color-on-loud);
+    }
+  }
+
   :host(:focus:not([disabled])),
   :host(:focus-visible) {
     outline: var(--c-focus-outline-width) solid var(--_focus-outline-color);
@@ -296,7 +306,7 @@ export default css`
 
   /* Link — renders as a text hyperlink: no fill or border, underlined. */
   :host([variant~='link']) {
-    display: inline;
+    display: inline-flex;
     appearance: none;
     background-color: transparent;
     border-color: transparent;

From cd708ea5cce00d3b7ddad08916b92ed153505701 Mon Sep 17 00:00:00 2001
From: Brian Hanson <brian@brianhanson.net>
Date: Fri, 24 Jul 2026 10:39:20 -0500
Subject: [PATCH 8/8] Cleanup

---
 .../src/components/chip/chip.stories.ts           |  6 +-----
 resources/js/common/components/FormActions.vue    |  7 ++++++-
 resources/js/common/components/Tooltip.vue        |  9 +--------
 resources/js/common/components/UserMenu.vue       |  6 +++++-
 .../js/modules/elements/components/FilterHud.vue  | 15 ++++-----------
 .../components/PluginLicenseIssues.vue            |  5 +----
 resources/js/pages/settings/routes/Index.vue      |  7 ++++++-
 7 files changed, 24 insertions(+), 31 deletions(-)

diff --git a/packages/craftcms-ui/src/components/chip/chip.stories.ts b/packages/craftcms-ui/src/components/chip/chip.stories.ts
index 3e72930a569..3a93695b529 100644
--- a/packages/craftcms-ui/src/components/chip/chip.stories.ts
+++ b/packages/craftcms-ui/src/components/chip/chip.stories.ts
@@ -81,11 +81,7 @@ export const Colors: Story = {
           ([name, value]) =>
             html`<craft-chip data-color="${value}">
               ${name}
-              <craft-button
-                size="small"
-                slot="suffix"
-                inherit
-                variant="plain"
+              <craft-button size="small" slot="suffix" inherit variant="plain"
                 >Button</craft-button
               >
             </craft-chip>`
diff --git a/resources/js/common/components/FormActions.vue b/resources/js/common/components/FormActions.vue
index 5941ff502c4..a1dc02214d9 100644
--- a/resources/js/common/components/FormActions.vue
+++ b/resources/js/common/components/FormActions.vue
@@ -87,7 +87,12 @@
       </slot>
       <ActionMenu icon="chevron-down" :actions="actionItems">
         <template #invoker="{label}">
-          <craft-button slot="invoker" :variant="ButtonVariant.Solid" type="button" icon>
+          <craft-button
+            slot="invoker"
+            :variant="ButtonVariant.Solid"
+            type="button"
+            icon
+          >
             <craft-icon name="chevron-down" :label="label"></craft-icon>
           </craft-button>
         </template>
diff --git a/resources/js/common/components/Tooltip.vue b/resources/js/common/components/Tooltip.vue
index 5fb76e7aefa..992cd7ee9d4 100644
--- a/resources/js/common/components/Tooltip.vue
+++ b/resources/js/common/components/Tooltip.vue
@@ -14,14 +14,7 @@
 </script>
 
 <template>
-  <craft-button
-    type="button"
-    :id="id"
-    variant="plain"
-    size="zero"
-    icon
-    inherit
-  >
+  <craft-button type="button" :id="id" variant="plain" size="zero" icon inherit>
     <slot name="icon">
       <craft-icon :name="icon"></craft-icon>
     </slot>
diff --git a/resources/js/common/components/UserMenu.vue b/resources/js/common/components/UserMenu.vue
index 8488a8ec91e..a5e5dd23b2e 100644
--- a/resources/js/common/components/UserMenu.vue
+++ b/resources/js/common/components/UserMenu.vue
@@ -52,7 +52,11 @@
 </script>
 
 <template>
-  <form :action="LoginController.logout['/{cpTrigger?}/logout']().url" method="post" ref="logoutForm">
+  <form
+    :action="LoginController.logout().url"
+    method="post"
+    ref="logoutForm"
+  >
     <input
       v-if="csrfTokenName && csrfTokenValue"
       type="hidden"
diff --git a/resources/js/modules/elements/components/FilterHud.vue b/resources/js/modules/elements/components/FilterHud.vue
index 412e3390298..63b14ac7a61 100644
--- a/resources/js/modules/elements/components/FilterHud.vue
+++ b/resources/js/modules/elements/components/FilterHud.vue
@@ -1,10 +1,5 @@
 <script setup lang="ts">
-  import {
-    t,
-    appendBodyHtml,
-    appendHeadHtml,
-    ButtonVariant,
-  } from '@craftcms/ui';
+  import {t, appendBodyHtml, appendHeadHtml, ButtonVariant} from '@craftcms/ui';
   import {useHttp, usePage} from '@inertiajs/vue3';
   import {onMounted, onUnmounted, ref, useTemplateRef} from 'vue';
   import ElementIndexController from '@actions/Elements/ElementIndex/ElementIndexController';
@@ -111,11 +106,9 @@
               @click="() => emit('close')"
               >{{ t('Cancel') }}</craft-button
             >
-            <craft-button
-              type="submit"
-              :variant="ButtonVariant.Primary"
-              >{{ t('Apply') }}</craft-button
-            >
+            <craft-button type="submit" :variant="ButtonVariant.Primary">{{
+              t('Apply')
+            }}</craft-button>
           </div>
         </template>
       </form>
diff --git a/resources/js/modules/plugin-manager/components/PluginLicenseIssues.vue b/resources/js/modules/plugin-manager/components/PluginLicenseIssues.vue
index 0d414708904..0da5e372859 100644
--- a/resources/js/modules/plugin-manager/components/PluginLicenseIssues.vue
+++ b/resources/js/modules/plugin-manager/components/PluginLicenseIssues.vue
@@ -33,10 +33,7 @@
       <Form :action="switchEdition()" method="post" v-slot="{processing}">
         <input type="hidden" name="pluginHandle" :value="plugin.handle" />
         <input type="hidden" name="edition" :value="plugin.licensedEdition" />
-        <craft-button
-          type="submit"
-          inherit
-          :loading="processing"
+        <craft-button type="submit" inherit :loading="processing"
           >Switch</craft-button
         >
       </Form>
diff --git a/resources/js/pages/settings/routes/Index.vue b/resources/js/pages/settings/routes/Index.vue
index 06e3597f2d6..897f412b754 100644
--- a/resources/js/pages/settings/routes/Index.vue
+++ b/resources/js/pages/settings/routes/Index.vue
@@ -83,7 +83,12 @@
 <template>
   <LayoutSlot name="actions">
     <Link :href="create()">
-      <craft-button v-if="!readOnly" type="button" icon="plus" :variant="ButtonVariant.Primary">
+      <craft-button
+        v-if="!readOnly"
+        type="button"
+        icon="plus"
+        :variant="ButtonVariant.Primary"
+      >
         {{ t('New route') }}
       </craft-button>
     </Link>