@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/components/button/button.css.js

@@ -1,45 +1,90 @@
 import { css } from "lit";
 
+/**
+ * Styled entirely from src/tokens/tokens.js — see CLAUDE.md, "The foundation
+ * rule". Every measurement was matched to the token that already carries the
+ * ds-button value; nothing was copied across as a literal.
+ *
+ * The --button-* properties below are component-local semantic aliases, not
+ * design tokens. Declaring them on :host is deliberate: outer-tree rules beat
+ * :host, so a page can still theme a button with
+ * `bd-button { --bd-button-primary-bg: … }`.
+ */
 export default css`
   :host {
     display: inline-flex;
-    --button-background-primary: var(--color-blue-500);
-    --button-background-primary-hover: var(--color-blue-600);
-    --button-background-primary-focus: var(--color-blue-700);
 
-    --button-background-secondary: var(--color-neutral-950);
-    --button-background-secondary-hover: var(--color-neutral-900);
-    --button-background-secondary-focus: var(--color-neutral-800);
-
-    --button-background-danger: var(--color-red-600);
-    --button-background-danger-hover: var(--color-red-700);
-    --button-background-danger-focus: var(--color-red-800);
-
-    --color-button-background-outline: var(--color-neutral-950);
-    --border-button-background-outline: var(--color-neutral-950);
-    --button-background-outline-hover: var(--color-neutral-50);
-    --border-button-background-outline-hover: var(--color-neutral-950);
-    --button-background-outline-focus: var(--color-neutral-800);
-
-    --color-button-background-primary-outline: var(--color-blue-500);
-    --border-button-background-primary-outline: var(--color-blue-500);
-    --button-background-primary-outline-hover: var(--color-blue-50);
-    --border-button-background-primary-outline-hover: var(--color-blue-500);
-    --button-background-primary-outline-focus: var(--color-blue-500);
-    --bd-accesibility-focus: var(--color-blue-500);
-
-    --button-arrow-size: 1.1em;
-    --button-arrow-shift: 0.65em;
-    --button-arrow-inset: 0.65em;
-    --button-arrow-offset: -0.4em;
-
-    --button-radius-rounded: var(--spacing-30);
+    /* Component-local aliases, not design tokens. Each defaults to the
+       --button-* token that carries the system-wide answer, so there are two
+       places to change a button and they do different jobs: set the token on
+       :root to move every button in the document, or set the alias on the
+       bd-button element to move one.
+
+       The alias is also what surface="dark" switches further down, which is
+       why it stays even now that the tokens behind it are live. */
+
+    /* ---- primary: blue fill ------------------------------------------- */
+    --bd-button-primary-bg: var(--button-primary-background-default);
+    --bd-button-primary-bg-hover: var(--button-primary-background-hover);
+    --bd-button-primary-bg-active: var(--button-primary-background-active);
+    --bd-button-primary-text: var(--button-primary-text-default);
+
+    /* ---- secondary: near-black fill ----------------------------------- */
+    --bd-button-secondary-bg: var(--button-secondary-background-default);
+    --bd-button-secondary-bg-hover: var(--button-secondary-background-hover);
+    --bd-button-secondary-bg-active: var(--button-secondary-background-active);
+    --bd-button-secondary-text: var(--button-secondary-text-default);
+
+    /* ---- tertiary: blue outline --------------------------------------- */
+    --bd-button-tertiary-text: var(--button-tertiary-text-default);
+    --bd-button-tertiary-border: var(--button-tertiary-border-default);
+    --bd-button-tertiary-bg-hover: var(--button-tertiary-background-hover);
+    --bd-button-tertiary-text-hover: var(--button-tertiary-text-hover);
+    --bd-button-tertiary-border-hover: var(--button-tertiary-border-hover);
+    --bd-button-tertiary-bg-active: var(--button-tertiary-background-active);
+    --bd-button-tertiary-text-active: var(--button-tertiary-text-active);
+
+    /* ---- ghost: dark outline ------------------------------------------ */
+    --bd-button-ghost-text: var(--button-ghost-text-default);
+    --bd-button-ghost-border: var(--button-ghost-border-default);
+    --bd-button-ghost-bg-hover: var(--button-ghost-background-hover);
+    --bd-button-ghost-text-hover: var(--button-ghost-text-hover);
+    --bd-button-ghost-bg-active: var(--button-ghost-background-active);
+    --bd-button-ghost-text-active: var(--button-ghost-text-active);
+
+    /* ---- accent: red fill --------------------------------------------- */
+    --bd-button-accent-bg: var(--button-accent-background-default);
+    --bd-button-accent-bg-hover: var(--button-accent-background-hover);
+    --bd-button-accent-bg-active: var(--button-accent-background-active);
+    --bd-button-accent-text: var(--button-accent-text-default);
+
+    /* ---- white and outline-white: fixed presets for a coloured banner --
+       They ignore surface on purpose; see the note on VARIANTS in button.js. */
+    --bd-button-white-bg: var(--button-white-background-default);
+    --bd-button-white-bg-hover: var(--button-white-background-hover);
+    --bd-button-white-bg-active: var(--button-white-background-active);
+    --bd-button-white-text: var(--button-white-text-default);
+
+    --bd-button-outline-white-text: var(--button-outline-white-text-default);
+    --bd-button-outline-white-border: var(--button-outline-white-border-default);
+    --bd-button-outline-white-bg-hover: var(--button-outline-white-background-hover);
+    --bd-button-outline-white-bg-active: var(--button-outline-white-background-active);
+
+    /* ---- disabled, shared across every variant ----------------------- */
+    --bd-button-disabled-bg: var(--button-disabled-backgroundColor);
+    --bd-button-disabled-text: var(--button-disabled-color);
+    --bd-button-disabled-border: var(--button-disabled-borderColor);
+
+    /* accent carries no ring on a light page; on a dark one it needs a
+       boundary, so the value is switched rather than the rule */
+    --bd-button-accent-ring: var(--button-accent-ring-default);
+
+    --bd-button-border-width: var(--border-width-2);
   }
 
   /* ============================================
-     ALIGNMENT SUPPORT
+     ALIGNMENT
      ============================================ */
-  
   :host([align="center"]) {
     display: flex;
     justify-content: center;
@@ -72,28 +117,49 @@ export default css`
     display: flex;
   }
 
-  :host([data-bd-button-focus]) {
-    outline: var(--spacing-2) solid var(--bd-accesibility-focus);
-    outline-offset: var(--spacing-2);
-    border-radius: var(--radius-md);
+  /* ============================================
+     FOCUS
+     The design specifies no focus state, but 2.4.7 requires one.
+
+     This used to be driven from JavaScript: two requestAnimationFrame hops
+     checked :focus-visible and set a data attribute the CSS then styled.
+     :focus-visible does that natively, so the detection is gone and the ring
+     is the shared one from Foundations/Focus — a two-colour ring whose white
+     inner band keeps it visible on a coloured hero, which the old
+     single-colour outline could not do. It is composed with
+     --bd-button-edge rather than replacing it, so an outlined variant keeps
+     its own boundary while focused; see the note on that property.
+     ============================================ */
+  button:focus,
+  a:focus {
+    outline: none;
   }
 
-  :host([shape="rounded"][data-bd-button-focus]) {
-    border-radius: var(--button-radius-rounded);
+  .button:focus-visible {
+    outline: none;
+    box-shadow: var(--focus-outline-primary), var(--bd-button-edge);
   }
 
-  button:focus,
-  button:focus-visible,
-  a:focus,
-  a:focus-visible {
-    outline: none;
-    box-shadow: none;
+  /* A white control needs the ring the other way up. --focus-outline-primary
+     puts its WHITE band against the control, which is what keeps it visible on
+     a coloured hero -- and is exactly wrong when the control is itself white:
+     measured on Button — White / Outline-White, the inner band was 1.00:1
+     against the button's own fill and the blue band 2.38:1 against the hero
+     (1.75:1 at the gradient's light end), so neither reached the 3:1 WCAG
+     2.4.11 asks. outline-white is here too because restoring its boundary
+     above puts a white border where the white band used to sit on the hero. */
+  .button--white:focus-visible,
+  .button--outline-white:focus-visible {
+    box-shadow: var(--focus-outline-inverse), var(--bd-button-edge);
   }
 
   a.button {
     text-decoration: none;
   }
 
+  /* ============================================
+     SHARED
+     ============================================ */
   .button,
   .bd-contact-btn {
     display: inline-flex;
@@ -101,67 +167,131 @@ export default css`
     align-items: center;
     text-align: center;
     text-decoration: none;
-    color: var(--color-neutral-0);
     border: none;
     cursor: pointer;
-    transition: background-color var(--transition-duration-normal) var(--transition-easing-smooth),
-      transform var(--transition-duration-normal) var(--transition-easing-smooth),
-      box-shadow var(--transition-duration-normal) var(--transition-easing-smooth),
-      color var(--transition-duration-normal) var(--transition-easing-smooth);
-    gap: var(--spacing-10);
+    font-family: var(--typography-fontFamily-sans);
+    font-weight: var(--typography-control-label-large-fontWeight);
+    line-height: var(--typography-control-label-large-lineHeight);
     vertical-align: middle;
-    line-height: 1;
     box-sizing: border-box;
-  }
-
-  .button__label {
-    display: inline-block;
-  }
 
-  .button--primary {
-    background-color: var(--button-background-primary);
-    color: var(--color-neutral-0);
-  }
-
-  .button--primary:hover {
-    background-color: var(--button-background-primary-hover);
-  }
-
-  .button--primary:active {
-    background-color: var(--button-background-primary-focus);
-  }
+    /* The variant's own boundary, held in a custom property so the focus ring
+       can COMPOSE with it. box-shadow is a single list, not additive, and
+       .button:focus-visible (0,2,0) outranks .button--ghost (0,1,0) -- so a
+       focus rule that declared box-shadow directly erased the border of every
+       outlined variant. A focused ghost button lost its dark outline and wore
+       a blue ring instead, which read as a tertiary button. The default is a
+       zero-spread transparent shadow rather than the keyword none, so the value
+       a valid shadow the focus rule can append to. */
+    --bd-button-edge: 0 0 0 0 transparent;
+    box-shadow: var(--bd-button-edge);
 
-  .button--secondary {
-    background-color: var(--button-background-secondary);
-    color: var(--color-neutral-0);
+    transition: background-color var(--transition-duration-normal) var(--transition-easing-smooth),
+      box-shadow var(--transition-duration-normal) var(--transition-easing-smooth),
+      color var(--transition-duration-normal) var(--transition-easing-smooth);
   }
 
-  .button--secondary:hover {
-    background-color: var(--button-background-secondary-hover);
+  /* bd-contact-button has no variant, so it would inherit no colour at all */
+  .button.bd-contact-btn {
+    background-color: transparent;
+    color: var(--color-text-brand);
+    gap: var(--spacing-8);
+
+    /* Same inset bd-back carries, and for the same reason. Without it this
+       control was a bare line box measuring 159x20 -- a 20px tall target
+       against the 24x24 WCAG 2.5.8 asks of anything that is not inline in a
+       sentence, so 4px short, and a standalone CTA has no exception to claim.
+       It also left the focus ring sitting on the glyphs' ascenders.
+
+       bd-back is the same shape of control -- text, a trailing mark, no fill --
+       and already answers this with 12px 16px, which takes a 16px line to about
+       44px: the same height bd-button reaches through its own padding. Reading
+       the inset off the sibling rather than picking a number is what keeps the
+       two text CTAs in step. */
+    padding: var(--spacing-12) var(--spacing-16);
+
+    /* This control takes no size class -- it is a text CTA with a trailing
+       arrow, not a filled button -- so it arrived with no radius at all, and
+       the shared ring drew SQUARE corners around a bare line box while every
+       other button's ring followed a curve.
+
+       --button-medium-borderRadius, not --focus-outline-radius. The focus
+       token is the documented default for an element with NO radius, and that
+       is what this rule used first -- but with the inset above the control is
+       now a 44px box standing next to bd-button at the same height, and the
+       focus token is --radius-sm where medium buttons are --radius-md. Four
+       pixels against six is small, and it is visible when they sit in a row.
+       Matching the size band this control actually occupies is the better
+       answer than matching the rule for controls that occupy none.
+
+       Declared unconditionally rather than under :focus-visible because the
+       control draws no background and no border at rest, so the radius is
+       invisible until the ring needs it. */
+    border-radius: var(--button-medium-borderRadius);
   }
 
-  .button--secondary:active {
-    background-color: var(--button-background-secondary-focus);
+  /* ============================================
+     SIZE
+     Height is left to padding and line-height rather than pinned with a
+     min-height, which lands within half a pixel of the design: 33.5 / 44 /
+     54.5 against 34 / 45 / 55. The previous rules also carried hardcoded
+     min-widths (115px, 150px) that the design does not ask for at all.
+
+     The radius comes from --button-*-borderRadius rather than --radius-*
+     directly. Same values, so nothing moves here — but a button and a field
+     of the same size sit in the same form row, and reading both from their
+     own size-matched alias is what keeps them in step. Spelled as raw scale
+     steps on one side and aliases on the other, they had drifted a step apart
+     at sm and md without either side looking wrong on its own.
+     ============================================ */
+  .button--small {
+    padding: var(--button-small-padding);
+    font-size: var(--button-small-fontSize);
+    border-radius: var(--button-small-borderRadius);
+    gap: var(--button-small-gap);
   }
 
-  .button--danger {
-    background-color: var(--button-background-danger);
-    color: var(--color-neutral-0);
+  .button--medium {
+    padding: var(--button-medium-padding);
+    font-size: var(--button-medium-fontSize);
+    border-radius: var(--button-medium-borderRadius);
+    gap: var(--button-medium-gap);
   }
 
-  // .button--danger:hover {
-  //   background-color: var(--button-background-danger-hover);
-  // }
- 
-  .button--danger:active {
-    background-color: var(--button-background-danger-focus);
+  .button--large {
+    padding: var(--button-large-padding);
+    font-size: var(--button-large-fontSize);
+    border-radius: var(--button-large-borderRadius);
+    gap: var(--button-large-gap);
+  }
+
+  .button--bold {
+    /* no role: the class is the semantic. .button--bold says what this
+       declaration does, so a role naming it would only restate the class --
+       there is no text-content type here for a role to describe, just an
+       emphasis the caller asked for by name. The same holds for a weight
+       driven by an active or selected state: that is a UI state, the category
+       CLAUDE.md keeps apart from type when it says a focus ring is never
+       expressed by swapping a border colour. This is the argument for every
+       "no role: state or modifier" marker in the package -- the others point
+       here rather than restating it. */
+    font-weight: var(--typography-fontWeight-semibold);
+  }
+
+  /* shape="rounded". After the size rules on purpose: same specificity, so
+     source order is what lets the shape replace the size band's corner. */
+  .button--rounded {
+    border-radius: var(--radius-3xl);
   }
 
   /* ============================================
-     HOVER CU SĂGEATĂ (implicit pentru kind="danger")
-     Lățimea butonului rămâne fixă: textul se translatează
-     spre stânga, iar săgeata (poziționată absolut) apare în dreapta.
+     HOVER ARROW — accent, unless no-arrow
+     The button keeps its width: the label slides left and the arrow,
+     absolutely positioned, fades in where the label was.
      ============================================ */
+  .button__label {
+    display: inline-block;
+  }
 
   .button--with-arrow {
     position: relative;
@@ -175,115 +305,334 @@ export default css`
   .button--with-arrow .button__arrow {
     position: absolute;
     top: 50%;
-    right: var(--button-arrow-inset);
-    width: var(--button-arrow-size);
-    height: var(--button-arrow-size);
-    display: inline-flex;
+    right: var(--spacing-12);
     opacity: 0;
-    transform: translate(var(--button-arrow-offset), -50%);
-    transition: opacity var(--transition-duration-normal) var(--transition-easing-smooth),
+    transform: translate(calc(-1 * var(--spacing-8)), -50%);
+    transition:
+      opacity var(--transition-duration-normal) var(--transition-easing-smooth),
       transform var(--transition-duration-normal) var(--transition-easing-smooth);
     pointer-events: none;
   }
 
   .button--with-arrow:hover .button__label,
   .button--with-arrow:focus-visible .button__label {
-    transform: translateX(calc(var(--button-arrow-shift) * -1));
+    transform: translateX(calc(-1 * var(--spacing-12)));
   }
 
   .button--with-arrow:hover .button__arrow,
   .button--with-arrow:focus-visible .button__arrow {
     opacity: 1;
-    transform: translate(0, -50%);
+    transform: translate(var(--spacing-0), -50%);
   }
 
-  /* Pe touch nu există hover real — nu lăsăm săgeata „blocată” după tap */
+  /* A touch screen has no real hover; do not leave the arrow stuck after a tap. */
   @media (hover: none) {
     .button--with-arrow:hover .button__label {
       transform: none;
     }
+
     .button--with-arrow:hover .button__arrow {
       opacity: 0;
     }
   }
-   
-  .button--outline {
-    background-color: transparent;
-    border: var(--border-width-2) solid var(--border-button-background-outline);
-    color: var(--color-button-background-outline);
+
+  /* ============================================
+     SHAPE — icon-only
+     A circle around one icon. The diameter is not pinned, for the same reason
+     the labelled height is not: equal padding on every side plus the icon step
+     gives 8+16+8 = 32, 12+20+12 = 44 and 16+24+16 = 56. Only md sits level
+     with a labelled button beside it: the labelled heights are 33.5, 44 and
+     54.5, so sm is 1.5px shorter and lg 1.5px taller. Both differences come
+     from the label's line box, which an icon does not have, and closing them
+     would need an off-scale padding. sm is below the 44px target, exactly as
+     the labelled sm is.
+
+     The padding stays on the spacing scale, which is rem, while the icon is on
+     the icon scale, which is px. So when a reader enlarges their text the
+     circle grows and the glyph does not -- the target gets bigger for the
+     reader a bigger target helps, and the shape stays round because the
+     padding is equal on both axes.
+
+     The compound selectors outrank the size classes whatever the source
+     order, and they carry the radius too, so a size class can never put
+     its own corner back. The slotted rule sizes a caller's icon to the step
+     even if it was given a size of its own: a 20px glyph in a 56px circle
+     reads as the wrong control, not as a choice.
+     ============================================ */
+  .button--icon-only {
+    line-height: var(--typography-lineHeight-none);
+  }
+  .button--icon-only.button--small {
+    --bd-button-icon-size: var(--icon-sm-size);
+    padding: var(--spacing-8);
+    border-radius: var(--radius-full);
+  }
+  .button--icon-only.button--medium {
+    --bd-button-icon-size: var(--icon-md-size);
+    padding: var(--spacing-12);
+    border-radius: var(--radius-full);
+  }
+  .button--icon-only.button--large {
+    --bd-button-icon-size: var(--icon-lg-size);
+    padding: var(--spacing-16);
+    border-radius: var(--radius-full);
+  }
+  .button--icon-only > ::slotted(*) {
+    height: var(--bd-button-icon-size);
+  }
+  /* loading swaps the icon for the spinner, so the spinner takes the icon's
+     box rather than its em size, and the circle does not shrink while busy */
+  .button--icon-only .spinner {
+    width: var(--bd-button-icon-size);
+    height: var(--bd-button-icon-size);
+  }
+
+  /* ============================================
+     VARIANT — primary
+     ============================================ */
+  .button--primary {
+    background-color: var(--bd-button-primary-bg);
+    color: var(--bd-button-primary-text);
+  }
+  .button--primary:hover {
+    background-color: var(--bd-button-primary-bg-hover);
+  }
+  .button--primary:active {
+    background-color: var(--bd-button-primary-bg-active);
   }
 
-  .button--outline:hover {
-    background-color: var(--button-background-outline-hover);
-    border: var(--border-width-2) solid var(--border-button-background-outline-hover);
+  /* ============================================
+     VARIANT — secondary
+     ============================================ */
+  .button--secondary {
+    background-color: var(--bd-button-secondary-bg);
+    color: var(--bd-button-secondary-text);
+  }
+  .button--secondary:hover {
+    background-color: var(--bd-button-secondary-bg-hover);
+  }
+  .button--secondary:active {
+    background-color: var(--bd-button-secondary-bg-active);
   }
 
-  .button--outline:active {
-    background-color: var(--button-background-outline-focus);
-    color: var(--color-neutral-0);
+  /* ============================================
+     VARIANT — tertiary (blue outline)
+     ============================================ */
+  .button--tertiary {
+    background-color: transparent;
+    --bd-button-edge: inset 0 0 0 var(--bd-button-border-width) var(--bd-button-tertiary-border);
+    color: var(--bd-button-tertiary-text);
+  }
+  .button--tertiary:hover {
+    background-color: var(--bd-button-tertiary-bg-hover);
+    --bd-button-edge: inset 0 0 0 var(--bd-button-border-width) var(--bd-button-tertiary-border-hover);
+    color: var(--bd-button-tertiary-text-hover);
+  }
+  .button--tertiary:active {
+    background-color: var(--bd-button-tertiary-bg-active);
+    --bd-button-edge: inset 0 0 0 var(--bd-button-border-width) var(--bd-button-tertiary-bg-active);
+    color: var(--bd-button-tertiary-text-active);
   }
 
-  .button--primary--outline {
+  /* ============================================
+     VARIANT — ghost (dark outline)
+     ============================================ */
+  .button--ghost {
     background-color: transparent;
-    border: var(--border-width-2) solid var(--border-button-background-primary-outline);
-    color: var(--color-button-background-primary-outline);
+    --bd-button-edge: inset 0 0 0 var(--bd-button-border-width) var(--bd-button-ghost-border);
+    color: var(--bd-button-ghost-text);
+  }
+  .button--ghost:hover {
+    background-color: var(--bd-button-ghost-bg-hover);
+    color: var(--bd-button-ghost-text-hover);
+  }
+  .button--ghost:active {
+    background-color: var(--bd-button-ghost-bg-active);
+    --bd-button-edge: inset 0 0 0 var(--bd-button-border-width) var(--bd-button-ghost-bg-active);
+    color: var(--bd-button-ghost-text-active);
   }
 
-  .button--primary--outline:hover {
-    background-color: var(--button-background-primary-outline-hover);
-    border: var(--border-width-2) solid var(--border-button-background-primary-outline-hover);
+  /* ============================================
+     VARIANT — accent
+     ============================================ */
+  .button--accent {
+    background-color: var(--bd-button-accent-bg);
+    color: var(--bd-button-accent-text);
+    --bd-button-edge: inset 0 0 0 var(--bd-button-border-width) var(--bd-button-accent-ring);
+  }
+  .button--accent:hover {
+    background-color: var(--bd-button-accent-bg-hover);
+  }
+  .button--accent:active {
+    background-color: var(--bd-button-accent-bg-active);
   }
 
-  .button--primary--outline:active {
-    background-color: var(--button-background-primary-outline-focus);
-    color: var(--color-neutral-0);
+  /* ============================================
+     SURFACE — dark
+
+     For a hero or any panel with a full background colour. On a light page
+     every variant passes; on a coloured one 21 of 25 variant/surface pairings
+     failed, because tertiary and ghost put their ink straight onto the page
+     and primary is literally the same colour as a blue-500 hero (1.00:1).
+
+     The design carries no on-dark set — its axes are Size, Variant and State
+     only — so these values are derived from our own palette rather than read
+     off a spec, and every one is measured against blue-500, blue-600,
+     blue-700, neutral-900 and neutral-950. They need a designer's sign-off.
+
+     Two notes on what changed shape rather than just colour: ghost drops its
+     ring here, because a white ring would make it identical to tertiary, and
+     dropping it is what "ghost" conventionally means anyway. accent keeps its
+     red so the conversion signal survives, and gains a white ring to give it
+     a boundary against blue.
+
+     WHY THE INK IS A ROLE AND THE GROUNDS ARE NOT, which is what the inline
+     no role: markers below point at. check:color-coverage gained sight of
+     these declarations on 2026-09-15 and classified twenty-three of them; a
+     role of the right CATEGORY exists at the value for nineteen, and exactly
+     nine survive the second question, which is whether the role's JOB is this
+     declaration's job.
+
+     The nine that do are all ink, and each one matches a role's own words.
+     tertiary and ghost put their label straight onto the hero, and
+     --color-text-inverse is defined as the high-emphasis ink on an inverse
+     ground. Once a variant inverts and the label sits on the button's own
+     light fill, it is ordinary ink again -- --color-text-primary -- or brand
+     ink, --color-text-brand. disabled's label is a control the user cannot
+     operate, which is --color-text-disabled's whole definition rather than a
+     step on the hierarchy. Every one is value-identical, so nothing here
+     renders differently.
+
+     The grounds and hairlines have no role, and the reason is not scarcity.
+     --color-surface-default carries this exact white, and its own theme
+     clause in Foundations/Surfaces reads "On dark it is the dark ground, not
+     white" -- so adopting it here would assert the opposite of what the
+     declaration means. surface-subtle is a wash behind a group, not a press
+     fill. surface-muted is a state surface and would fit primary's pressed
+     step on value and nearly on job, but these three values are one ramp
+     measured against the hero rather than three independent choices, and
+     binding its last step to a role that can move on its own would break the
+     relationship the measurement established. At neutral-700 and neutral-600
+     there is no surface or border role at all, and there is no solid white
+     border role anywhere: --color-border-container-inverse is white at 12%.
+
+     So the missing vocabulary is nameable, and it is two entries: a control
+     fill on an inverse ground, and a solid hairline on an inverse ground.
+     Adding either is a vocabulary decision for the same designer pass this
+     block is already waiting on, and token-scales.js is explicit that one
+     consumer is not enough to name a role. Recorded, not taken.
+     ============================================ */
+  :host([surface='dark']) {
+    /* white fill, brand label — the strongest thing on a coloured hero */
+    --bd-button-primary-bg: var(--color-neutral-0);  /* no role: on-dark ground; see the block note */
+    --bd-button-primary-bg-hover: var(--color-neutral-50);  /* no role: on-dark ground; see the block note */
+    --bd-button-primary-bg-active: var(--color-neutral-100);  /* no role: on-dark ground; see the block note */
+    --bd-button-primary-text: var(--color-text-brand);
+
+    /* neutral-100 rather than a lighter step: it is the lightest fill that
+       still clears 3:1 against a blue-500 hero while staying distinguishable
+       from primary's pure white */
+    --bd-button-secondary-bg: var(--color-neutral-100);  /* no role: on-dark ground; see the block note */
+    --bd-button-secondary-bg-hover: var(--color-neutral-50);  /* no role: on-dark ground; see the block note */
+    --bd-button-secondary-bg-active: var(--color-neutral-0);  /* no role: on-dark ground; see the block note */
+    --bd-button-secondary-text: var(--color-text-primary);
+
+    /* the outlined one: white ring, white label, inverting on hover */
+    --bd-button-tertiary-text: var(--color-text-inverse);
+    --bd-button-tertiary-border: var(--color-neutral-0);  /* no role: on-dark hairline; see the block note */
+    --bd-button-tertiary-bg-hover: var(--color-neutral-0);  /* no role: on-dark ground; see the block note */
+    --bd-button-tertiary-text-hover: var(--color-text-brand);
+    --bd-button-tertiary-border-hover: var(--color-neutral-0);  /* no role: on-dark hairline; see the block note */
+    --bd-button-tertiary-bg-active: var(--color-neutral-50);  /* no role: on-dark ground; see the block note */
+    --bd-button-tertiary-text-active: var(--color-text-brand);
+
+    /* no ring at all, so it stays distinct from tertiary */
+    --bd-button-ghost-text: var(--color-text-inverse);
+    --bd-button-ghost-border: transparent;
+    --bd-button-ghost-bg-hover: var(--color-neutral-0);  /* no role: on-dark ground; see the block note */
+    --bd-button-ghost-text-hover: var(--color-text-primary);
+    --bd-button-ghost-bg-active: var(--color-neutral-50);  /* no role: on-dark ground; see the block note */
+    --bd-button-ghost-text-active: var(--color-text-primary);
+
+    /* unchanged red, plus a boundary against the hero */
+    --bd-button-accent-ring: var(--color-neutral-0);
+
+    /* muted downward instead of upward: a neutral-100 fill would read as an
+       active control on a dark hero. Exempt from contrast under WCAG 1.4.3. */
+    --bd-button-disabled-bg: var(--color-neutral-700);  /* no role: on-dark ground; see the block note */
+    --bd-button-disabled-text: var(--color-text-disabled);
+    --bd-button-disabled-border: var(--color-neutral-600);  /* no role: on-dark hairline; see the block note */
+
   }
 
-  .button--small {
-    padding: var(--spacing-8) var(--spacing-16);
-    font-size: var(--spacing-14);
-    font-weight: var(--typography-fontWeight-normal);
-    font-family: var(--typography-fontFamily-sans);
-    border-radius: var(--radius-md);
-    min-height: var(--dimension-34px);
-    min-width: 115px;
+  /* ============================================
+     STATE — disabled
+     Filled variants go grey; outlined ones keep a transparent fill and take
+     the subtle border. Contrast is exempt here under WCAG 1.4.3.
+     ============================================ */
+  .button:disabled,
+  .button[aria-disabled="true"] {
+    cursor: not-allowed;
+    pointer-events: none;
+    background-color: var(--bd-button-disabled-bg);
+    --bd-button-edge: 0 0 0 0 transparent;
+    color: var(--bd-button-disabled-text);
   }
 
-  .button--medium {
-    padding: var(--spacing-12) var(--spacing-20);
-    font-size: var(--spacing-16);
-    font-weight: var(--typography-fontWeight-normal);
-    font-family: var(--typography-fontFamily-sans);
-    border-radius: var(--radius-lg);
-    min-height: var(--dimension-45px);
-    min-width: 150px;
+  .button--tertiary:disabled,
+  .button--ghost:disabled,
+  .button--tertiary[aria-disabled="true"],
+  .button--ghost[aria-disabled="true"] {
+    background-color: transparent;
+    --bd-button-edge: inset 0 0 0 var(--bd-button-border-width) var(--bd-button-disabled-border);
+    color: var(--bd-button-disabled-text);
   }
 
-  .button--large {
-    padding: var(--spacing-16) var(--spacing-24);
-    font-size: var(--spacing-18);
-    font-weight: var(--typography-fontWeight-normal);
-    font-family: var(--typography-fontFamily-sans);
-    border-radius: var(--radius-lg);
-    min-height: var(--dimension-55px);
-    min-width: 150px;
+  /* ============================================
+     STATE — loading
+     The variant keeps its own colours, so the spinner is drawn in
+     currentColor and sized in em to track the type scale — which is what the
+     design's loading widths imply (they exceed the default by exactly one
+     font-size plus the gap).
+     ============================================ */
+  .button--loading {
+    cursor: progress;
+    pointer-events: none;
   }
 
-  .button--rounded {
-    border-radius: var(--radius-3xl);
+  .spinner {
+    width: 1em;
+    height: 1em;
+    flex: none;
+    box-sizing: border-box;
+    border: var(--border-width-2) solid currentColor;
+    border-top-color: transparent;
+    border-radius: var(--radius-full);
+    animation: bd-button-spin var(--transition-duration-slower)
+      var(--transition-easing-linear) infinite;
   }
 
-   .button--bold {
-    font: normal normal var(--typography-fontWeight-medium) var(--typography-fontSize-lg) / var(--dimension-24px) Roboto, sans-serif;
+  @keyframes bd-button-spin {
+    to { transform: rotate(360deg); }
   }
 
-  /* slot-ul nu mai e copil direct al .button (e în .button__label) */
-  .button ::slotted(*) {
+  /* The slot sits inside .button__label now, not directly in .button. */
+  .button__label > ::slotted(*) {
     display: inline-block;
-    width: 100%;
     text-align: center;
   }
 
+  /* box-shadow is not rendered in forced-colors mode, which would leave the
+     outlined variants with no visible boundary at all, so a real border comes
+     back there. It costs 4px of height, which does not matter when the user
+     agent is repainting everything anyway. */
+  @media (forced-colors: active) {
+    .button--tertiary,
+    .button--ghost {
+      border: var(--bd-button-border-width) solid currentColor;
+    }
+  }
+
   @media (prefers-reduced-motion: reduce) {
     .button,
     .bd-contact-btn,
@@ -291,32 +640,53 @@ export default css`
     .button__arrow {
       transition: none !important;
     }
-  }
 
+    /* a spinner that cannot spin should still read as busy, so it pulses
+       rather than freezing into a static broken ring */
+    .spinner {
+      animation: bd-button-pulse var(--transition-duration-slower)
+        var(--transition-easing-smooth) infinite alternate;
+      border-top-color: currentColor;
+    }
+
+    @keyframes bd-button-pulse {
+      to { opacity: var(--opacity-pulse); }
+    }
+  }
+  /* ============================================
+     VARIANT — white and outline-white
+
+     Fixed presets for a solid-colour banner, where even a surface="dark"
+     primary would sit too close in tone. They ignore surface on purpose —
+     see the note on VARIANTS in button.js.
+
+     These two were appended below the stylesheet's last rule and unindented,
+     and they hardcoded their colours instead of going through the aliases
+     every other variant uses: 1.5px against the 2px border width the docs
+     describe, #ffffff8c, and two rgba() whites. None of it could be rethemed
+     and none of it was visible to the lint, which does not read 8-digit hex
+     or rgba().
+     ============================================ */
   .button--white {
-    background-color: var(--color-neutral-0);
-    color: var(--color-blue-500);
+    background-color: var(--bd-button-white-bg);
+    color: var(--bd-button-white-text);
   }
-
   .button--white:hover {
-    background-color: var(--color-blue-50);
+    background-color: var(--bd-button-white-bg-hover);
   }
-
   .button--white:active {
-    background-color: var(--color-blue-100);
+    background-color: var(--bd-button-white-bg-active);
   }
 
   .button--outline-white {
     background-color: transparent;
-    box-shadow: inset 0 0 0 1.5px #ffffff8c;
-    color: var(--color-neutral-0);
+    --bd-button-edge: inset 0 0 0 var(--bd-button-border-width) var(--bd-button-outline-white-border);
+    color: var(--bd-button-outline-white-text);
   }
-
   .button--outline-white:hover {
-    background-color: rgba(255, 255, 255, 0.1);
+    background-color: var(--bd-button-outline-white-bg-hover);
   }
-
   .button--outline-white:active {
-    background-color: rgba(255, 255, 255, 0.2);
+    background-color: var(--bd-button-outline-white-bg-active);
   }
-`;
+`;