@usefragments/ui 1.7.0 → 2.0.0

package/src/components/Button/Button.module.scss

@@ -1,27 +1,35 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../tokens/measurements.generated" as measurements;
 @use "../../recipes/action";
 
+// Two axes, one recipe. `tone` publishes the colour channels (fill, ink, wash,
+// line); `variant` decides which channel paints which slot. Every channel and
+// every slot carries a neutral fallback so a bare `.button` still renders.
+
 .button {
   @include button-reset;
   @include interactive-base;
   @include action.base;
+  @include high-contrast-outline;
 
+  // Slots the variant paints.
   --_button-bg: transparent;
   --_button-bg-hover: var(--fui-bg-hover, #{$fui-bg-hover});
   --_button-bg-active: var(--fui-bg-active, #{$fui-bg-active});
   --_button-border: transparent;
-  --_button-border-hover: var(--_button-border);
+  --_button-border-hover: var(--_button-border, transparent);
   --_button-color: var(--fui-text-primary, #{$fui-text-primary});
   --_button-shadow: none;
-  --_button-shadow-hover: var(--_button-shadow);
-  --_button-shadow-active: var(--_button-shadow);
+  --_button-shadow-hover: var(--_button-shadow, none);
+  --_button-shadow-active: var(--_button-shadow, none);
 
-  border: var(--fui-stroke-hairline, 1px) solid var(--_button-border);
+  border: var(--fui-stroke-hairline, #{$fui-stroke-hairline}) solid
+    var(--_button-border, transparent);
   border-radius: var(--fui-button-radius, var(--fui-radius-lg, #{$fui-radius-lg}));
-  background: var(--_button-bg);
-  box-shadow: var(--_button-shadow);
-  color: var(--_button-color);
+  background: var(--_button-bg, transparent);
+  box-shadow: var(--_button-shadow, none);
+  color: var(--_button-color, var(--fui-text-primary, #{$fui-text-primary}));
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   white-space: nowrap;
 
@@ -34,25 +42,37 @@
   }
 
   &:hover:not(:disabled):not([data-disabled]) {
-    border-color: var(--_button-border-hover);
-    background: var(--_button-bg-hover);
-    box-shadow: var(--_button-shadow-hover);
+    border-color: var(--_button-border-hover, transparent);
+    background: var(--_button-bg-hover, var(--fui-bg-hover, #{$fui-bg-hover}));
+    box-shadow: var(--_button-shadow-hover, none);
   }
 
   &:active:not(:disabled):not([data-disabled]),
   &[data-pressed] {
-    border-color: var(--_button-border-hover);
-    background: var(--_button-bg-active);
-    box-shadow: var(--_button-shadow-active);
+    border-color: var(--_button-border-hover, transparent);
+    background: var(--_button-bg-active, var(--fui-bg-active, #{$fui-bg-active}));
+    box-shadow: var(--_button-shadow-active, none);
+  }
+
+  // Tactile press. 0.96 exactly: lower reads as exaggerated. Rides the
+  // interactive-base transition, so a release mid-press eases back.
+  @media (prefers-reduced-motion: no-preference) {
+    &:active:not(:disabled):not([data-disabled]):not(.link) {
+      scale: 0.96;
+    }
   }
 
   &:focus-visible {
     box-shadow:
-      0 0 0 1px
+      0 0 0 var(--fui-stroke-hairline, #{$fui-stroke-hairline})
         color-mix(in srgb, var(--fui-focus-ring-color, #{$fui-focus-ring-color}) 34%, transparent),
-      0 0 0 calc(var(--fui-focus-ring-width, #{$fui-focus-ring-width}) + 1px)
+      0 0 0
+        calc(
+          var(--fui-focus-ring-width, #{$fui-focus-ring-width}) +
+            var(--fui-stroke-hairline, #{$fui-stroke-hairline})
+        )
         color-mix(in srgb, var(--fui-focus-ring-color, #{$fui-focus-ring-color}) 14%, transparent),
-      var(--_button-shadow);
+      var(--_button-shadow, none);
   }
 
   &:disabled,
@@ -61,13 +81,9 @@
   }
 }
 
-.xs {
-  @include action.size("micro");
-
-  > svg {
-    @include action.glyph("micro");
-  }
-}
+// ============================================
+// Sizes
+// ============================================
 
 .sm {
   @include action.size("sm");
@@ -93,19 +109,9 @@
   }
 }
 
-// ============================================
-// Optical alignment: icon + text combinations
-// ============================================
-// Icons (SVGs) have built-in whitespace that makes symmetric padding look
-// uneven. When an icon leads or trails text, reduce padding on the icon
-// side so the content appears optically centered.
-//
-.xs:not(.icon):has(> svg:first-child:not(:last-child)) {
-  padding-inline-start: action.icon-side-inset("micro");
-}
-.xs:not(.icon):has(> svg:last-child:not(:first-child)) {
-  padding-inline-end: action.icon-side-inset("micro");
-}
+// Optical alignment: icons (SVGs) carry built-in whitespace that makes
+// symmetric padding look uneven. When an icon leads or trails text, reduce
+// padding on the icon side so the content appears optically centered.
 .sm:not(.icon):has(> svg:first-child:not(:last-child)) {
   padding-inline-start: action.icon-side-inset("sm");
 }
@@ -125,152 +131,257 @@
   padding-inline-end: action.icon-side-inset("lg");
 }
 
-// Variants
-.primary {
-  --_button-bg: var(--fui-button-primary-bg);
-  --_button-bg-hover: var(--fui-button-primary-bg-hover);
-  --_button-bg-active: var(--fui-button-primary-bg-active);
-  --_button-border: var(--fui-button-primary-border);
-  --_button-border-hover: var(--fui-button-primary-border-hover);
-  --_button-color: var(
+// ============================================
+// Tones — colour channels
+// ============================================
+// fill / on-fill / fill-line → the solid variant
+// ink                       → foreground of soft, outline, ghost, link
+// soft                      → the tinted fill of the soft variant
+// wash                      → hover/active fill of outline, ghost, link
+// line                      → the outline border
+
+.toneNeutral {
+  --_tone-fill: var(--fui-bg-inverse, #{$fui-bg-inverse});
+  --_tone-fill-hover: color-mix(
+    in srgb,
+    var(--fui-bg-inverse, #{$fui-bg-inverse}) 88%,
+    var(--fui-text-inverse, #{$fui-text-inverse})
+  );
+  --_tone-fill-active: color-mix(
+    in srgb,
+    var(--fui-bg-inverse, #{$fui-bg-inverse}) 80%,
+    var(--fui-text-inverse, #{$fui-text-inverse})
+  );
+  --_tone-fill-line: var(--_tone-fill, var(--fui-bg-inverse, #{$fui-bg-inverse}));
+  --_tone-fill-line-hover: var(--_tone-fill-hover, var(--fui-bg-inverse, #{$fui-bg-inverse}));
+  --_tone-on-fill: var(--fui-text-inverse, #{$fui-text-inverse});
+  --_tone-ink: var(--fui-button-neutral-color, var(--fui-text-primary, #{$fui-text-primary}));
+  --_tone-soft: var(--fui-button-neutral-bg, var(--fui-bg-tertiary, #{$fui-bg-tertiary}));
+  --_tone-soft-hover: var(--fui-button-neutral-bg-hover, var(--fui-bg-hover, #{$fui-bg-hover}));
+  --_tone-soft-active: var(--fui-button-neutral-bg-active, var(--fui-bg-active, #{$fui-bg-active}));
+  --_tone-wash: var(--fui-bg-hover, #{$fui-bg-hover});
+  --_tone-wash-active: var(--fui-bg-active, #{$fui-bg-active});
+  --_tone-line: var(--fui-button-neutral-border, var(--fui-border-strong, #{$fui-border-strong}));
+  --_tone-line-hover: var(
+    --fui-button-neutral-border-hover,
+    var(--fui-border-strong, #{$fui-border-strong})
+  );
+}
+
+// Accent solid reads the primary-chrome tokens so the ink-first default and a
+// consumer brand seed both paint the primary action (see `_variables.scss`).
+.toneAccent {
+  --_tone-fill: var(--fui-button-primary-bg, var(--fui-color-accent, #{$fui-color-accent}));
+  --_tone-fill-hover: var(
+    --fui-button-primary-bg-hover,
+    var(--fui-color-accent-hover, #{$fui-color-accent-hover})
+  );
+  --_tone-fill-active: var(
+    --fui-button-primary-bg-active,
+    var(--fui-color-accent-active, #{$fui-color-accent-active})
+  );
+  --_tone-fill-line: var(
+    --fui-button-primary-border,
+    var(--fui-color-accent, #{$fui-color-accent})
+  );
+  --_tone-fill-line-hover: var(
+    --fui-button-primary-border-hover,
+    var(--fui-color-accent-hover, #{$fui-color-accent-hover})
+  );
+  --_tone-on-fill: var(
     --fui-button-primary-color,
     var(--fui-color-on-accent, #{$fui-color-on-accent})
   );
-  --_button-shadow: var(--fui-button-primary-shadow);
-  --_button-shadow-hover: var(--fui-button-primary-shadow);
-  --_button-shadow-active: var(--fui-button-primary-shadow-active);
+  --_tone-ink: var(--fui-color-accent, #{$fui-color-accent});
+  --_tone-soft: color-mix(in srgb, var(--fui-color-accent, #{$fui-color-accent}) 12%, transparent);
+  --_tone-soft-hover: color-mix(
+    in srgb,
+    var(--fui-color-accent, #{$fui-color-accent}) 18%,
+    transparent
+  );
+  --_tone-soft-active: color-mix(
+    in srgb,
+    var(--fui-color-accent, #{$fui-color-accent}) 24%,
+    transparent
+  );
+  --_tone-wash: color-mix(in srgb, var(--fui-color-accent, #{$fui-color-accent}) 10%, transparent);
+  --_tone-wash-active: color-mix(
+    in srgb,
+    var(--fui-color-accent, #{$fui-color-accent}) 18%,
+    transparent
+  );
+  --_tone-line: color-mix(in srgb, var(--fui-color-accent, #{$fui-color-accent}) 48%, transparent);
+  --_tone-line-hover: var(--fui-color-accent, #{$fui-color-accent});
 }
 
-.secondary {
-  --_button-bg: var(--fui-button-neutral-bg);
-  --_button-bg-hover: var(--fui-button-neutral-bg-hover);
-  --_button-bg-active: var(--fui-button-neutral-bg-active);
-  // Secondary hierarchy comes from its fill. The transparent border preserves
-  // control geometry while leaving visible neutral borders to `.outlined`.
-  --_button-border: transparent;
-  --_button-border-hover: transparent;
-  --_button-color: var(--fui-button-neutral-color, var(--fui-text-primary, #{$fui-text-primary}));
-  --_button-shadow: var(--fui-button-neutral-shadow);
-  --_button-shadow-hover: var(--fui-button-neutral-shadow);
-  --_button-shadow-active: var(--fui-button-neutral-shadow-active);
+// Semantic tones share one derivation: the fill is the seed, hover and active
+// lean toward the tone's ink (darker on paper, lighter on charcoal), the
+// tinted surfaces come from the `-bg` / `-text` / `-border` ramp.
+@mixin _semantic-tone($tone, $seed, $bg, $text, $border) {
+  --_tone-fill: var(--fui-color-#{$tone}, #{$seed});
+  --_tone-fill-hover: color-mix(
+    in srgb,
+    var(--fui-color-#{$tone}, #{$seed}) 88%,
+    var(--fui-color-#{$tone}-text, #{$text})
+  );
+  --_tone-fill-active: color-mix(
+    in srgb,
+    var(--fui-color-#{$tone}, #{$seed}) 80%,
+    var(--fui-color-#{$tone}-text, #{$text})
+  );
+  --_tone-fill-line: color-mix(
+    in srgb,
+    var(--fui-color-#{$tone}, #{$seed}) 76%,
+    var(--fui-color-#{$tone}-text, #{$text})
+  );
+  --_tone-fill-line-hover: color-mix(
+    in srgb,
+    var(--fui-color-#{$tone}, #{$seed}) 62%,
+    var(--fui-color-#{$tone}-text, #{$text})
+  );
+  --_tone-on-fill: color-mix(in srgb, var(--fui-color-#{$tone}, #{$seed}) 8%, white);
+  --_tone-ink: var(--fui-color-#{$tone}-text, #{$text});
+  --_tone-soft: var(--fui-color-#{$tone}-bg, #{$bg});
+  --_tone-soft-hover: color-mix(
+    in srgb,
+    var(--fui-color-#{$tone}-bg, #{$bg}) 90%,
+    var(--fui-color-#{$tone}-text, #{$text})
+  );
+  --_tone-soft-active: color-mix(
+    in srgb,
+    var(--fui-color-#{$tone}-bg, #{$bg}) 80%,
+    var(--fui-color-#{$tone}-text, #{$text})
+  );
+  --_tone-wash: var(--fui-color-#{$tone}-bg, #{$bg});
+  --_tone-wash-active: color-mix(
+    in srgb,
+    var(--fui-color-#{$tone}-bg, #{$bg}) 85%,
+    var(--fui-color-#{$tone}-text, #{$text})
+  );
+  --_tone-line: var(--fui-color-#{$tone}-border, #{$border});
+  --_tone-line-hover: var(--fui-color-#{$tone}-text, #{$text});
 }
 
-.ghost {
-  --_button-bg: transparent;
-  --_button-bg-hover: var(--fui-bg-hover, #{$fui-bg-hover});
-  --_button-bg-active: var(--fui-bg-active, #{$fui-bg-active});
+.toneInfo {
+  @include _semantic-tone(
+    "info",
+    $fui-color-info,
+    $fui-color-info-bg,
+    $fui-color-info-text,
+    $fui-color-info-border
+  );
+}
+
+.toneSuccess {
+  @include _semantic-tone(
+    "success",
+    $fui-color-success,
+    $fui-color-success-bg,
+    $fui-color-success-text,
+    $fui-color-success-border
+  );
+}
+
+.toneWarning {
+  @include _semantic-tone(
+    "warning",
+    $fui-color-warning,
+    $fui-color-warning-bg,
+    $fui-color-warning-text,
+    $fui-color-warning-border
+  );
+}
+
+.toneDanger {
+  @include _semantic-tone(
+    "danger",
+    $fui-color-danger,
+    $fui-color-danger-bg,
+    $fui-color-danger-text,
+    $fui-color-danger-border
+  );
+}
+
+// ============================================
+// Variants — which channel paints which slot
+// ============================================
+
+.solid {
+  --_button-bg: var(--_tone-fill, var(--fui-bg-inverse, #{$fui-bg-inverse}));
+  --_button-bg-hover: var(--_tone-fill-hover, var(--fui-bg-inverse, #{$fui-bg-inverse}));
+  --_button-bg-active: var(--_tone-fill-active, var(--fui-bg-inverse, #{$fui-bg-inverse}));
+  --_button-border: var(--_tone-fill-line, var(--fui-bg-inverse, #{$fui-bg-inverse}));
+  --_button-border-hover: var(--_tone-fill-line-hover, var(--fui-bg-inverse, #{$fui-bg-inverse}));
+  --_button-color: var(--_tone-on-fill, var(--fui-text-inverse, #{$fui-text-inverse}));
+  --_button-shadow: var(--fui-button-primary-shadow, none);
+  --_button-shadow-hover: var(--fui-button-primary-shadow, none);
+  --_button-shadow-active: var(--fui-button-primary-shadow-active, none);
+}
+
+// Soft hierarchy comes from its fill. The transparent border preserves
+// control geometry while leaving visible borders to `.outline`.
+.soft {
+  --_button-bg: var(--_tone-soft, var(--fui-bg-tertiary, #{$fui-bg-tertiary}));
+  --_button-bg-hover: var(--_tone-soft-hover, var(--fui-bg-hover, #{$fui-bg-hover}));
+  --_button-bg-active: var(--_tone-soft-active, var(--fui-bg-active, #{$fui-bg-active}));
   --_button-border: transparent;
   --_button-border-hover: transparent;
-  --_button-color: var(--fui-text-primary, #{$fui-text-primary});
-  --_button-shadow: none;
-  --_button-shadow-hover: none;
-  --_button-shadow-active: none;
+  --_button-color: var(--_tone-ink, var(--fui-text-primary, #{$fui-text-primary}));
+  --_button-shadow: var(--fui-button-neutral-shadow, none);
+  --_button-shadow-hover: var(--fui-button-neutral-shadow, none);
+  --_button-shadow-active: var(--fui-button-neutral-shadow-active, none);
 }
 
-// Link: accent-coloured, transparent background. For tertiary CTAs
-// ("View all →", "Learn more →") that should feel linkish but live in
-// button contexts. Differs from ghost (text-primary) by using accent.
-.link {
+.outline {
+  --_button-bg: color-mix(in srgb, var(--fui-bg-elevated, #{$fui-bg-elevated}) 42%, transparent);
+  --_button-bg-hover: var(--_tone-wash, var(--fui-bg-hover, #{$fui-bg-hover}));
+  --_button-bg-active: var(--_tone-wash-active, var(--fui-bg-active, #{$fui-bg-active}));
+  --_button-border: var(--_tone-line, var(--fui-border-strong, #{$fui-border-strong}));
+  --_button-border-hover: var(--_tone-line-hover, var(--fui-border-strong, #{$fui-border-strong}));
+  --_button-color: var(--_tone-ink, var(--fui-text-primary, #{$fui-text-primary}));
+  --_button-shadow: var(--fui-button-outlined-shadow, #{$fui-button-outlined-shadow});
+  --_button-shadow-hover: var(--fui-button-neutral-shadow, none);
+  --_button-shadow-active: var(--fui-button-neutral-shadow-active, none);
+}
+
+.ghost {
   --_button-bg: transparent;
-  --_button-bg-hover: color-mix(
-    in srgb,
-    var(--fui-color-accent, #{$fui-color-accent}) 10%,
-    transparent
-  );
-  --_button-bg-active: color-mix(
-    in srgb,
-    var(--fui-color-accent, #{$fui-color-accent}) 18%,
-    transparent
-  );
+  --_button-bg-hover: var(--_tone-wash, var(--fui-bg-hover, #{$fui-bg-hover}));
+  --_button-bg-active: var(--_tone-wash-active, var(--fui-bg-active, #{$fui-bg-active}));
   --_button-border: transparent;
   --_button-border-hover: transparent;
-  --_button-color: var(--fui-color-accent, #{$fui-color-accent});
+  --_button-color: var(--_tone-ink, var(--fui-text-primary, #{$fui-text-primary}));
   --_button-shadow: none;
   --_button-shadow-hover: none;
   --_button-shadow-active: none;
 }
 
-// Quiet: a button that reads as text. The neutral sibling of `link` — nothing
-// but the foreground changes on hover, because in a meta line, a breadcrumb or
-// a footnote a box would be the loudest thing on the row for the least
-// important one. It is also the one variant that drops the interactive height
-// floor: there is no box to hold open, so it sits on the line it is in and
-// takes its hit target from the text and the row's own padding. That makes it
-// the wrong choice for a standalone action — reach for `ghost` there.
-.quiet {
-  @include action.inline;
-
+// Link: reads like a link, behaves like an action. Same open chrome as ghost,
+// but it defaults to the accent tone and underlines on hover so a tertiary
+// CTA ("View all →") is never mistaken for a toolbar ghost.
+.link {
   --_button-bg: transparent;
-  --_button-bg-hover: transparent;
-  --_button-bg-active: transparent;
+  --_button-bg-hover: var(--_tone-wash, var(--fui-bg-hover, #{$fui-bg-hover}));
+  --_button-bg-active: var(--_tone-wash-active, var(--fui-bg-active, #{$fui-bg-active}));
   --_button-border: transparent;
   --_button-border-hover: transparent;
-  --_button-color: var(--fui-text-tertiary, #{$fui-text-tertiary});
+  --_button-color: var(--_tone-ink, var(--fui-color-accent, #{$fui-color-accent}));
   --_button-shadow: none;
   --_button-shadow-hover: none;
   --_button-shadow-active: none;
 
-  font-weight: var(--fui-font-weight-normal, $fui-font-weight-normal);
-
-  // Only the custom property is restated: `color` reads it on .button, so the
-  // foreground follows without a second `color` declaration to keep in step.
   &:hover:not(:disabled):not([data-disabled]) {
-    --_button-color: var(--fui-text-secondary, #{$fui-text-secondary});
-  }
-
-  &:active:not(:disabled):not([data-disabled]),
-  &[data-pressed] {
-    --_button-color: var(--fui-text-primary, #{$fui-text-primary});
+    text-decoration: underline;
+    text-underline-offset: var(--fui-raw-space-2, #{measurements.raw-space(2)});
   }
 }
 
-.danger {
-  // Flat danger fill — no gradient. Hover/active darken the solid colour.
-  --_button-bg: var(--fui-color-danger, #{$fui-color-danger});
-  --_button-bg-hover: color-mix(
-    in srgb,
-    var(--fui-color-danger, #{$fui-color-danger}) 88%,
-    black 12%
-  );
-  --_button-bg-active: color-mix(
-    in srgb,
-    var(--fui-color-danger, #{$fui-color-danger}) 80%,
-    black 20%
-  );
-  --_button-border: color-mix(
-    in srgb,
-    var(--fui-color-danger, #{$fui-color-danger}) 76%,
-    black 24%
-  );
-  --_button-border-hover: color-mix(
-    in srgb,
-    var(--fui-color-danger, #{$fui-color-danger}) 62%,
-    black 38%
-  );
-  --_button-color: color-mix(in srgb, var(--fui-color-danger, #{$fui-color-danger}) 8%, white);
-  --_button-shadow: var(--fui-button-primary-shadow);
-  --_button-shadow-hover: var(--fui-button-primary-shadow);
-  --_button-shadow-active: var(--fui-button-primary-shadow-active);
-}
-
-.outlined {
-  --_button-bg: color-mix(in srgb, var(--fui-bg-elevated, #{$fui-bg-elevated}) 42%, transparent);
-  --_button-bg-hover: var(--fui-button-neutral-bg-hover);
-  --_button-bg-active: var(--fui-button-neutral-bg-active);
-  --_button-border: var(--fui-button-neutral-border);
-  --_button-border-hover: var(--fui-button-neutral-border-hover);
-  --_button-color: var(--fui-button-neutral-color, var(--fui-text-primary, #{$fui-text-primary}));
-  --_button-shadow: var(--fui-button-outlined-shadow, #{$fui-button-outlined-shadow});
-  --_button-shadow-hover: var(--fui-button-neutral-shadow);
-  --_button-shadow-active: var(--fui-button-neutral-shadow-active);
-}
-
 // Icon-only button (square aspect ratio)
 .icon {
-  inline-size: var(--_fui-action-track);
-  block-size: var(--_fui-action-track);
-  min-block-size: var(--_fui-action-track);
-  padding-inline: 0;
+  inline-size: var(--_fui-action-track, #{action.track("md")});
+  block-size: var(--_fui-action-track, #{action.track("md")});
+  min-block-size: var(--_fui-action-track, #{action.track("md")});
+  padding-inline: var(--fui-raw-space-0, #{measurements.raw-space(0)});
 }
 
 // Full width
@@ -278,10 +389,6 @@
   width: 100%;
 }
 
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
-
 // ============================================
 // Accessibility: Reduced Motion
 // ============================================
@@ -291,35 +398,3 @@
     transition: none;
   }
 }
-
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
-
-@media (prefers-contrast: more) {
-  .secondary {
-    border-width: var(--fui-stroke-default, 2px);
-    border-color: var(--fui-text-primary, $fui-text-primary);
-  }
-
-  .outlined {
-    border-width: var(--fui-stroke-default, 2px);
-    border-color: var(--fui-text-primary, $fui-text-primary);
-  }
-
-  .ghost {
-    border-width: var(--fui-stroke-default, 2px);
-
-    &:hover:not(:disabled) {
-      border-color: var(--fui-text-primary, $fui-text-primary);
-    }
-  }
-
-  .link {
-    border-width: var(--fui-stroke-default, 2px);
-
-    &:hover:not(:disabled) {
-      border-color: var(--fui-color-accent, $fui-color-accent);
-    }
-  }
-}

package/src/components/Button/index.tsx

@@ -22,31 +22,31 @@ function composeEventHandlers<T extends (...args: any[]) => void>(
  * Button props.
  * @see https://usefragments.com/components/button
  */
+export type ButtonVariant = "solid" | "soft" | "outline" | "ghost" | "link";
+export type ButtonTone = "neutral" | "accent" | "info" | "success" | "warning" | "danger";
+export type ButtonSize = "sm" | "md" | "lg";
+
 type ButtonBaseProps = {
   children: React.ReactNode;
-  /** Visual style variant.
-   * @default "primary"
+  /** Chrome family.
+   * @default "solid"
    * @see https://usefragments.com/components/button#variants
    * @remarks
-   * - `"link"` — accent-coloured, transparent; for tertiary CTAs like "View all →"
-   * - `"quiet"` — neutral text button with no box and no height floor; for meta lines and footnotes
-   * - `"icon"` — convenience alias for outlined + icon-only layout
-   * - `"outline"` — alias for `"outlined"` */
-  variant?:
-    | "primary"
-    | "secondary"
-    | "ghost"
-    | "link"
-    | "quiet"
-    | "danger"
-    | "outlined"
-    | "outline"
-    | "icon";
-  /** Button size. `"xs"` is for inline row-action controls (accept/dismiss, table-row icons) where `"sm"` is too tall.
+   * - `"solid"` — filled; the one action you want taken here
+   * - `"soft"` — tinted fill, no border; supporting actions
+   * - `"outline"` — hairline border on a transparent surface
+   * - `"ghost"` — no fill, no border; dense toolbars and repeated rows
+   * - `"link"` — reads like a link, behaves like an action; tertiary CTAs */
+  variant?: ButtonVariant;
+  /** Colour. Defaults to `"accent"` on `solid` and `link`, `"neutral"` on
+   * `soft`, `outline` and `ghost`.
+   * @see https://usefragments.com/components/button#tones */
+  tone?: ButtonTone;
+  /** Control height.
    * @default "md"
    * @see https://usefragments.com/components/button#sizes */
-  size?: "xs" | "sm" | "md" | "lg";
-  /** Render as icon-only button (square aspect ratio). Prefer `variant="icon"` for the default outlined icon button. */
+  size?: ButtonSize;
+  /** Render as icon-only button (square aspect ratio). Always pass `aria-label`. */
   icon?: boolean;
   /** Make button full width of container */
   fullWidth?: boolean;
@@ -55,6 +55,23 @@ type ButtonBaseProps = {
   asChild?: boolean;
 };
 
+const DEFAULT_TONE: Record<ButtonVariant, ButtonTone> = {
+  solid: "accent",
+  link: "accent",
+  soft: "neutral",
+  outline: "neutral",
+  ghost: "neutral",
+};
+
+const TONE_CLASS: Record<ButtonTone, string> = {
+  neutral: styles.toneNeutral,
+  accent: styles.toneAccent,
+  info: styles.toneInfo,
+  success: styles.toneSuccess,
+  warning: styles.toneWarning,
+  danger: styles.toneDanger,
+};
+
 // Button as native button element
 export interface ButtonAsButtonProps
   extends ButtonBaseProps, Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
@@ -73,7 +90,8 @@ const ButtonRoot = React.forwardRef<HTMLButtonElement | HTMLAnchorElement, Butto
   function Button(props, ref) {
     const {
       children,
-      variant: variantProp = "primary",
+      variant = "solid",
+      tone: toneProp,
       size: sizeProp,
       icon = false,
       fullWidth = false,
@@ -83,20 +101,15 @@ const ButtonRoot = React.forwardRef<HTMLButtonElement | HTMLAnchorElement, Butto
     } = props;
 
     const size = useResolvedControlSize(sizeProp);
-    const iconOnly = icon || variantProp === "icon";
-
-    // Resolve aliases:
-    // "outline" → "outlined"
-    // "icon" → visual "outlined" + icon-only sizing
-    const variant =
-      variantProp === "outline" ? "outlined" : variantProp === "icon" ? "outlined" : variantProp;
+    const tone = toneProp ?? DEFAULT_TONE[variant];
     const canonicalStamp = fragmentsCanonicalStampProps("Button");
 
     const classNames = [
       styles.button,
       styles[size],
       styles[variant],
-      iconOnly && styles.icon,
+      TONE_CLASS[tone],
+      icon && styles.icon,
       fullWidth && styles.fullWidth,
       className,
     ]