@inchurch/matcha-theme 20.0.8 → 20.276.0

package/components/matcha-buttons.scss

@@ -1,784 +1,908 @@
-// =============================================================================
-// matcha-buttons.scss — Button & Icon Button (modernized)
-// Aligned with Figma: matcha/button + matcha/icon-button
-// Sizes: SM(32) MD(40) LG(48) XL(56) + legacy aliases (tiny/small/medium/large/huge)
-// Variants: Filled(default) Outline Ghost(basic) Alpha Link
-// State layer: ::before opacity pattern (consistent with all DS components)
-// =============================================================================
-
-// ── Disabled mixins ─────────────────────────────────────────────────────────
-
-@mixin _disabled-solid-button($theme) {
-    background: var(--matcha-color-disabled-bg, #{getDisabled($theme)});
-    color: var(--matcha-color-disabled-fg, #{getDisabledBgContrast($theme)});
-    box-shadow: 0 0 0 0px inset;
-    pointer-events: none;
-}
-
-@mixin _disabled-basic-button($theme) {
-    background: var(--matcha-color-surface, #{getSurface($theme)});
-    color: var(--matcha-color-disabled-bg, #{getDisabled($theme)});
-    box-shadow: 0 0 0 0px inset;
-    pointer-events: none;
-}
-
-@mixin _disabled-outline-button($theme) {
-    background: transparent;
-    color: var(--matcha-color-disabled-bg, #{getDisabled($theme)});
-    box-shadow: 0 0 0 var(--matcha-border-thin, 2px) inset;
-    pointer-events: none;
-}
-
-@mixin _disabled-alpha-button($theme) {
-    background: var(--matcha-color-disabled-bg-alpha, #{getDisabledAlpha($theme)});
-    color: var(--matcha-color-disabled-bg, #{getDisabled($theme)});
-    box-shadow: 0 0 0 0px inset;
-    pointer-events: none;
-}
-
-@mixin _disabled-link-button($theme) {
-    background: transparent;
-    color: var(--matcha-color-disabled-bg, #{getDisabled($theme)});
-    box-shadow: 0 0 0 0px inset;
-    pointer-events: none;
-}
-
-// ── Size classes (responsive, aligned with Figma XS/SM/MD/LG/XL) ────────────
-
-@mixin generate-matcha-button-size-classes($helper-breakpoints) {
-    @each $breakpoint, $materialBreakpoint in $helper-breakpoints {
-        @include media-breakpoint($materialBreakpoint) {
-            $infix: if($materialBreakpoint == null, "", "-#{$breakpoint}");
-
-            // XS — 28px. Figma matcha/button XS: pad 8 · gap 2 · text/caption (11/400/14, letter 0.3)
-            &[size#{$infix}="xs"] {
-                padding: 0 var(--matcha-space-100, 8px);
-                font-size: var(--matcha-text-caption, 11px);
-                font-weight: var(--matcha-weight-regular, 400);
-                line-height: var(--matcha-leading-caption, 14px);
-                letter-spacing: var(--matcha-letter-spacing-caption, 0.3px);
-                height: 28px;
-                gap: var(--matcha-space-025, 2px);
-            }
-
-            // SM — 32px. Figma: pad 8 · gap 4 · text/button-sm (13/500/19 letter 0.2)
-            &[size#{$infix}="sm"],
-            &[size#{$infix}="tiny"] {
-                padding: 0 var(--matcha-space-100, 8px);
-                font-size: var(--matcha-text-button-sm, 13px);
-                font-weight: var(--matcha-weight-medium, 500);
-                line-height: var(--matcha-leading-button-sm, 19px);
-                height: 32px;
-                gap: var(--matcha-space-050, 4px);
-            }
-
-            // MD — 40px. Figma: pad 16 · gap 8 · text/button-md (14/500/20)
-            &[size#{$infix}="md"],
-            &[size#{$infix}="small"] {
-                padding: 0 var(--matcha-space-200, 16px);
-                font-size: var(--matcha-text-md, 14px);
-                font-weight: var(--matcha-weight-medium, 500);
-                line-height: var(--matcha-leading-md, 20px);
-                height: 40px;
-                gap: var(--matcha-space-100, 8px);
-            }
-
-            // LG — 48px. Figma: pad 24 · gap 8
-            &[size#{$infix}="lg"],
-            &[size#{$infix}="medium"] {
-                padding: 0 var(--matcha-space-300, 24px);
-                font-size: var(--matcha-text-lg, 16px);
-                font-weight: var(--matcha-weight-semibold, 600);
-                line-height: var(--matcha-leading-button-lg, 22px);
-                height: 48px;
-                gap: var(--matcha-space-100, 8px);
-            }
-
-            // XL — 56px. Figma: pad 32 · gap 8
-            &[size#{$infix}="xl"],
-            &[size#{$infix}="large"],
-            &[size#{$infix}="huge"] {
-                padding: 0 var(--matcha-space-400, 32px);
-                font-size: var(--matcha-text-lg, 16px);
-                font-weight: var(--matcha-weight-semibold, 600);
-                line-height: var(--matcha-leading-button-lg, 22px);
-                height: 56px;
-                gap: var(--matcha-space-100, 8px);
-            }
-        }
-    }
-}
-
-// ── Structural ──────────────────────────────────────────────────────────────
-
-button[matcha-button],
-a[matcha-button],
-button[matcha-icon-button],
-a[matcha-icon-button],
-button[matcha-link],
-a[matcha-link] {
-    overflow: hidden;
-    position: relative;
-    font-size: var(--matcha-text-md, 14px);
-    font-weight: var(--matcha-weight-medium, 500);
-    font-family: inherit;
-    height: px-to-rem(40px); // default MD; overridden by size attribute selectors
-    appearance: auto;
-    text-rendering: auto;
-    letter-spacing: var(--matcha-letter-spacing-button, 0.2px);
-    word-spacing: normal;
-    line-height: normal;
-    text-transform: none;
-    text-indent: 0px;
-    text-shadow: none;
-    text-align: center;
-    text-wrap: nowrap;
-    display: flex;
-    justify-content: center;
-    align-items: center;
-    cursor: pointer;
-    box-sizing: border-box;
-    border: none;
-    border-radius: var(--matcha-radius-lg, 8px);
-
-    * { pointer-events: none; }
-
-    // Figma spec: ícones dentro de button herdam a foreground color do botão
-    // (matcha-icon tem color-default próprio via tema — forçamos inherit com !important
-    // pra vencer o tema que aplica em [class^="i-matcha-"] globalmente)
-    matcha-icon,
-    [class^="i-matcha-"],
-    [class*=" i-matcha-"] {
-        color: inherit !important;
-    }
-
-    @include generate-matcha-button-size-classes($helper-breakpoints);
-
-    // Figma matcha/button usa DOIS feedbacks combinados:
-    //   1. Cor do bg muda (accent-default → accent-hover → accent-pressed)
-    //   2. State-layer overlay por cima (matcha/color/state-layer/fg)
-    //      - Filled:  opacity 0.15 hover / 0.30 active
-    //      - Outline/Ghost: opacity 0.10 hover / 0.20 active
-    // ::before aplica o state-layer; :hover/:active ou .is-state-* ativam.
-    transition:
-        background-color 150ms cubic-bezier(0.4, 0, 0.2, 1),
-        box-shadow 150ms cubic-bezier(0.4, 0, 0.2, 1),
-        color 150ms cubic-bezier(0.4, 0, 0.2, 1);
-
-    &::before {
-        content: '';
-        position: absolute;
-        inset: 0;
-        background: var(--matcha-color-state-layer-fg, currentColor);
-        opacity: 0;
-        border-radius: inherit;
-        pointer-events: none;
-        transition: opacity 150ms cubic-bezier(0.4, 0, 0.2, 1);
-    }
-
-    // Filled (variant default) — state-layer forte
-    &:hover:not([disabled]):not([disabled="true"]):not([outline]):not([basic]):not([ghost]):not([link]):not([alpha]):not([matcha-link])::before,
-    &.is-state-hover:not([outline]):not([basic]):not([ghost]):not([alpha])::before {
-        opacity: 0.15;
-    }
-    &:active:not([disabled]):not([disabled="true"]):not([outline]):not([basic]):not([ghost]):not([link]):not([alpha]):not([matcha-link])::before,
-    &.is-state-active:not([outline]):not([basic]):not([ghost]):not([alpha])::before {
-        opacity: 0.30;
-    }
-
-    // Outline / Ghost — state-layer sutil
-    &[outline]:hover:not([disabled]):not([disabled="true"])::before,
-    &[basic]:hover:not([disabled]):not([disabled="true"])::before,
-    &[ghost]:hover:not([disabled]):not([disabled="true"])::before,
-    &[outline].is-state-hover::before,
-    &[basic].is-state-hover::before,
-    &[ghost].is-state-hover::before {
-        opacity: 0.10;
-    }
-    &[outline]:active:not([disabled]):not([disabled="true"])::before,
-    &[basic]:active:not([disabled]):not([disabled="true"])::before,
-    &[ghost]:active:not([disabled]):not([disabled="true"])::before,
-    &[outline].is-state-active::before,
-    &[basic].is-state-active::before,
-    &[ghost].is-state-active::before {
-        opacity: 0.20;
-    }
-
-    &[disabled] {
-        pointer-events: none;
-        cursor: default;
-    }
-
-    // ── Variant modifiers (estrutural — cores vêm do mixin de tema) ──
-    &[basic]:not([basic="false"]),
-    &[ghost]:not([ghost="false"]) {
-        background: transparent;
-    }
-
-    &[outline]:not([outline="false"]) {
-        background: transparent;
-
-        &[link]:not([link="false"]) {
-            &[size="sm"], &[size="tiny"] { padding: 0 var(--matcha-space-100, 8px); gap: var(--matcha-space-050, 4px); }
-            &[size="md"], &[size="small"] { padding: 0 var(--matcha-space-150, 12px); gap: var(--matcha-space-100, 8px); }
-            &[size="lg"], &[size="medium"] { padding: 0 var(--matcha-space-200, 16px); gap: var(--matcha-space-150, 12px); }
-            &[size="xl"], &[size="large"], &[size="huge"] { padding: 0 var(--matcha-space-200, 16px); gap: var(--matcha-space-150, 12px); }
-        }
-    }
-
-    &[pill]:not([pill="false"]) {
-        border-radius: var(--matcha-radius-pill, 9999px);
-    }
-
-    &[link]:not([link="false"]) {
-        text-transform: initial;
-        letter-spacing: 0;
-        text-decoration: none;
-        padding: 0;
-        background: transparent;
-    }
-
-    // ── matcha-link specific (Figma spec 16914:500) ──
-    // SM=11/14 Regular letter 0.3 · MD=14/20 Medium · LG=16/22 SemiBold
-    // Hover/Active → underline automático. Underline=true → permanente.
-    // Disabled → opacity via disabled-fg color (no underline).
-    &[matcha-link] {
-        height: auto;
-        min-height: 0;
-        max-height: none;
-        padding: 0;
-        background: transparent;
-        border-radius: 0;
-        text-decoration: none; // reset do underline default do <a>; hover/class re-aplica
-
-        &[size="sm"], &[size="tiny"] {
-            font-size: var(--matcha-text-caption, 11px);
-            line-height: var(--matcha-leading-caption, 14px);
-            font-weight: var(--matcha-weight-regular, 400);
-            letter-spacing: var(--matcha-letter-spacing-caption, 0.3px);
-            height: auto;
-            max-height: none;
-        }
-        &[size="md"], &[size="small"] {
-            font-size: var(--matcha-text-md, 14px);
-            line-height: var(--matcha-leading-md, 20px);
-            font-weight: var(--matcha-weight-medium, 500);
-            letter-spacing: var(--matcha-letter-spacing-button, 0.2px);
-            height: auto;
-            max-height: none;
-        }
-        &[size="lg"], &[size="medium"] {
-            font-size: var(--matcha-text-lg, 16px);
-            line-height: var(--matcha-leading-button-lg, 22px);
-            font-weight: var(--matcha-weight-semibold, 600);
-            letter-spacing: var(--matcha-letter-spacing-button, 0.2px);
-            height: auto;
-            max-height: none;
-        }
-
-        // State layer fica off (link não tem overlay/bg)
-        &::before { display: none; }
-        // Press scale também off — link é texto
-        transition: none;
-        &:active:not([disabled]):not([disabled="true"]) { transform: none; }
-
-        // Hover e active: underline (Figma spec)
-        &:hover:not([disabled]):not([disabled="true"]),
-        &:active:not([disabled]):not([disabled="true"]) {
-            text-decoration: underline;
-        }
-
-        // Underline permanente via property (classe do HostBinding no component)
-        &.matcha-link--underline {
-            text-decoration: underline;
-        }
-    }
-
-    &[icon]:not([icon="false"]) {
-        aspect-ratio: 1;
-        display: flex;
-        align-items: center;
-        justify-content: center;
-
-        // Icon-button padding per Figma spec matcha/icon-button (all-direction):
-        // XS=6 · SM=6 · MD=8 · LG=12 · XL=16 (padding igual em todos os lados)
-        &[size="xs"] {
-            padding: var(--matcha-space-075, 6px) !important;
-        }
-        &[size="sm"], &[size="tiny"] {
-            padding: var(--matcha-space-075, 6px) !important;
-        }
-        &[size="md"], &[size="small"] {
-            padding: var(--matcha-space-100, 8px) !important;
-        }
-        &[size="lg"], &[size="medium"] {
-            padding: var(--matcha-space-150, 12px) !important;
-        }
-        &[size="xl"], &[size="large"], &[size="huge"] {
-            padding: var(--matcha-space-200, 16px) !important;
-        }
-
-        // Auto-size inner matcha-icon conforme Figma matcha/icon-button spec:
-        // XS→16 · SM→20 · MD→24 · LG→24 · XL→24
-        &[size="xs"] [class^="i-matcha-"],
-        &[size="xs"] [class*=" i-matcha-"] {
-            font-size: var(--matcha-icon-size-sm, 16px);
-            width: var(--matcha-icon-size-sm, 16px);
-            height: var(--matcha-icon-size-sm, 16px);
-            line-height: var(--matcha-icon-size-sm, 16px);
-        }
-        &[size="sm"] [class^="i-matcha-"],
-        &[size="sm"] [class*=" i-matcha-"],
-        &[size="tiny"] [class^="i-matcha-"],
-        &[size="tiny"] [class*=" i-matcha-"] {
-            font-size: 20px;
-            width: 20px;
-            height: 20px;
-            line-height: 20px;
-        }
-        &[size="md"] [class^="i-matcha-"],
-        &[size="md"] [class*=" i-matcha-"],
-        &[size="small"] [class^="i-matcha-"],
-        &[size="small"] [class*=" i-matcha-"],
-        &[size="lg"] [class^="i-matcha-"],
-        &[size="lg"] [class*=" i-matcha-"],
-        &[size="medium"] [class^="i-matcha-"],
-        &[size="medium"] [class*=" i-matcha-"],
-        &[size="xl"] [class^="i-matcha-"],
-        &[size="xl"] [class*=" i-matcha-"],
-        &[size="large"] [class^="i-matcha-"],
-        &[size="large"] [class*=" i-matcha-"],
-        &[size="huge"] [class^="i-matcha-"],
-        &[size="huge"] [class*=" i-matcha-"] {
-            font-size: var(--matcha-icon-size-md, 24px);
-            width: var(--matcha-icon-size-md, 24px);
-            height: var(--matcha-icon-size-md, 24px);
-            line-height: var(--matcha-icon-size-md, 24px);
-        }
-    }
-
-    // ── Badge ──
-    &[badge]:not([badge="false"]) {
-        overflow: visible;
-        position: relative;
-
-        &::after {
-            content: "";
-            position: absolute;
-            top: -0.25rem;
-            right: -0.25rem;
-            width: 1.32rem;
-            height: 1.32rem;
-            border-radius: var(--matcha-radius-pill, 9999px);
-            z-index: 2;
-        }
-
-        &[size="sm"]::after, &[size="tiny"]::after { width: 0.75rem; height: 0.75rem; top: -0.15rem; right: -0.15rem; }
-        &[size="md"]::after, &[size="small"]::after { width: 1rem; height: 1rem; top: -0.2rem; right: -0.2rem; }
-        &[size="xl"]::after, &[size="large"]::after, &[size="huge"]::after { width: 1.5rem; height: 1.5rem; top: -0.3rem; right: -0.3rem; }
-    }
-
-    // ── Focus ring ──
-    &:focus-visible:not([disabled]) {
-        outline: var(--matcha-state-focus-ring-width, 2px) solid var(--matcha-color-accent, #6200ee);
-        outline-offset: var(--matcha-state-focus-ring-offset, 2px);
-    }
-
-    @media (prefers-reduced-motion: reduce) {
-        &::before { transition: none; }
-        &, &:active:not([disabled]):not([disabled="true"]) { transition: none; transform: none; }
-    }
-
-    // ── Loading state ──
-    // Spinner inline do lado direito do conteúdo + content dims pra 60%
-    // Preserva width (não shift) e bloqueia cliques com pointer-events.
-    &.matcha-button--loading {
-        pointer-events: none;
-        cursor: progress;
-
-        // Dim no content interior (tudo exceto o spinner)
-        > :not(.matcha-button__spinner) {
-            opacity: 0.6;
-        }
-    }
-
-    .matcha-button__spinner {
-        display: inline-flex;
-        align-items: center;
-        justify-content: center;
-        margin-left: var(--matcha-space-100, 8px);
-        flex: none;
-        line-height: 0;
-
-        svg {
-            display: block;
-        }
-
-        @media (prefers-reduced-motion: reduce) {
-            svg circle animateTransform {
-                // Retarda mas não remove (ainda sinaliza loading)
-                dur: 2s !important;
-            }
-        }
-    }
-
-    // Visually hidden span pra screen readers (loading announcement)
-    .matcha-button__sr-only {
-        position: absolute !important;
-        width: 1px !important;
-        height: 1px !important;
-        padding: 0 !important;
-        margin: -1px !important;
-        overflow: hidden !important;
-        clip: rect(0, 0, 0, 0) !important;
-        white-space: nowrap !important;
-        border: 0 !important;
-    }
-
-    // ── Touch targets (WCAG 2.5.5: 44x44 mínimo em coarse pointers) ──
-    // XS (28), SM (32), MD (40) ficam abaixo de 44px — expande hit area invisível.
-    @media (pointer: coarse) {
-        &[size="xs"],
-        &[size="sm"], &[size="tiny"],
-        &[size="md"], &[size="small"] {
-            position: relative;
-
-            &::after {
-                content: '';
-                position: absolute;
-                inset: -8px;            // expande ~16px em cada eixo → 28+16=44, 32+16=48, 40+16=56 ✓
-                z-index: 0;
-                pointer-events: auto;   // captura cliques aqui
-            }
-
-            // ::before já é usado pro state layer, então nosso overlay vai no ::after
-            // State layer (::before) fica colado ao botão visual, overlay (::after) expande hit.
-        }
-    }
-}
-
-// ── Theme mixin ─────────────────────────────────────────────────────────────
-
-@mixin matcha-button-theme($theme) {
-    // ═════════════════════════════════════════════════════════════════════════
-    // CSS var-based theming (regra DS-ARCHITECTURE #7: Tokens over hardcode)
-    //
-    // Todo botão usa --matcha-button-color como token interno.
-    // `[color="X"]` apenas mapeia pra esses tokens — as variantes
-    // (filled/outline/ghost/alpha/link) interpretam um único set de vars.
-    //
-    // Consumidor pode override QUALQUER cor via style:
-    //   <button matcha-button style="--matcha-button-color: #ff00ff">Custom</button>
-    //
-    // Adicionar cor nova = adicionar 1 mapping (3 linhas).
-    // ═════════════════════════════════════════════════════════════════════════
-
-    button[matcha-button],
-    a[matcha-button],
-    button[matcha-icon-button],
-    a[matcha-icon-button],
-    button[matcha-link],
-    a[matcha-link] {
-        // Tokens internos (Figma matcha/button 13913:1088):
-        //   --matcha-button-color         = bg do filled (Default)
-        //   --matcha-button-color-hover   = bg filled / stroke outline (Hover)
-        //   --matcha-button-color-pressed = bg filled / stroke+text (Active)
-        //   --matcha-button-color-text-on = texto do filled (accent/text-on etc.)
-        //   --matcha-button-color-alpha   = alpha modifier / ripple
-        //   --matcha-button-color-edge    = stroke do outline (Default)
-        --matcha-button-color: var(--matcha-color-neutral);
-        --matcha-button-color-hover: var(--matcha-color-neutral-hover);
-        --matcha-button-color-pressed: var(--matcha-color-neutral-hover);
-        --matcha-button-color-text-on: var(--matcha-color-neutral-contrast);
-        --matcha-button-color-alpha: var(--matcha-color-neutral-alpha);
-        --matcha-button-color-edge: var(--matcha-color-fg, #{getForeground($theme)});
-
-        // ── Color mapping ────────────────────────────────────────────────────────────────
-        &[color="basic"] {
-            --matcha-button-color: var(--matcha-color-neutral);
-            --matcha-button-color-hover: var(--matcha-color-neutral-hover);
-            --matcha-button-color-pressed: var(--matcha-color-neutral-hover);
-            --matcha-button-color-text-on: var(--matcha-color-neutral-contrast);
-            --matcha-button-color-alpha: var(--matcha-color-neutral-alpha);
-            --matcha-button-color-edge: var(--matcha-color-fg, #{getForeground($theme)});
-        }
-        &[color="primary"] {
-            --matcha-button-color: var(--matcha-color-primary, #{getPrimary($theme)});
-            --matcha-button-color-hover: var(--matcha-color-primary-hover);
-            --matcha-button-color-pressed: var(--matcha-color-primary-pressed);
-            --matcha-button-color-text-on: var(--matcha-color-primary-contrast, #{getPrimaryContrast($theme)});
-            --matcha-button-color-alpha: var(--matcha-color-primary-alpha, #{getPrimaryAlpha($theme)});
-            --matcha-button-color-edge: var(--matcha-color-primary, #{getPrimary($theme)});
-        }
-        &[color="accent"] {
-            --matcha-button-color: var(--matcha-color-accent, #{getAccent($theme)});
-            --matcha-button-color-hover: var(--matcha-color-accent-hover);
-            --matcha-button-color-pressed: var(--matcha-color-accent-pressed);
-            --matcha-button-color-text-on: var(--matcha-color-accent-text-on);
-            --matcha-button-color-alpha: var(--matcha-color-accent-alpha, #{getAccentAlpha($theme)});
-            --matcha-button-color-edge: var(--matcha-color-accent, #{getAccent($theme)});
-        }
-        &[color="success"] {
-            --matcha-button-color: var(--matcha-color-success, #{getSuccess($theme)});
-            --matcha-button-color-hover: var(--matcha-color-success-hover);
-            --matcha-button-color-pressed: var(--matcha-color-success-pressed);
-            --matcha-button-color-text-on: var(--matcha-color-success-contrast, #{getSuccessContrast($theme)});
-            --matcha-button-color-alpha: var(--matcha-color-success-alpha, #{getSuccessAlpha($theme)});
-            --matcha-button-color-edge: var(--matcha-color-success, #{getSuccess($theme)});
-        }
-        &[color="warn"] {
-            --matcha-button-color: var(--matcha-color-warn, #{getWarn($theme)});
-            --matcha-button-color-hover: var(--matcha-color-warn-hover);
-            --matcha-button-color-pressed: var(--matcha-color-warn-pressed);
-            --matcha-button-color-text-on: var(--matcha-color-warn-contrast, #{getWarnContrast($theme)});
-            --matcha-button-color-alpha: var(--matcha-color-warn-alpha, #{getWarnAlpha($theme)});
-            --matcha-button-color-edge: var(--matcha-color-warn, #{getWarn($theme)});
-        }
-        &[color="danger"] {
-            --matcha-button-color: var(--matcha-color-danger, #{getDanger($theme)});
-            --matcha-button-color-hover: var(--matcha-color-danger-hover);
-            --matcha-button-color-pressed: var(--matcha-color-danger-pressed);
-            --matcha-button-color-text-on: var(--matcha-color-danger-contrast, #{getDangerContrast($theme)});
-            --matcha-button-color-alpha: var(--matcha-color-danger-alpha, #{getDangerAlpha($theme)});
-            --matcha-button-color-edge: var(--matcha-color-danger, #{getDanger($theme)});
-        }
-        &[color="info"] {
-            --matcha-button-color: var(--matcha-color-info, #{getInfo($theme)});
-            --matcha-button-color-hover: var(--matcha-color-info-hover);
-            --matcha-button-color-pressed: var(--matcha-color-info-pressed);
-            --matcha-button-color-text-on: var(--matcha-color-info-contrast, #{getInfoContrast($theme)});
-            --matcha-button-color-alpha: var(--matcha-color-info-alpha, #{getInfoAlpha($theme)});
-            --matcha-button-color-edge: var(--matcha-color-info, #{getInfo($theme)});
-        }
-
-        // ── Filled (default variant) ──────────────────────────────────────────────────────
-        // Figma: Default=accent · Hover=accent-hover · Active=accent-pressed
-        background: var(--matcha-button-color);
-        color: var(--matcha-button-color-text-on);
-
-        &:hover:not([disabled]):not([disabled="true"]):not([outline]):not([basic]):not([ghost]):not([link]):not([alpha]):not([matcha-link]) {
-            background: var(--matcha-button-color-hover);
-        }
-        &:active:not([disabled]):not([disabled="true"]):not([outline]):not([basic]):not([ghost]):not([link]):not([alpha]):not([matcha-link]) {
-            background: var(--matcha-button-color-pressed);
-        }
-
-        // ── Variant: outline ────────────────────────────────────────────────────────────────
-        // Figma matcha/button (13913:1088) vs matcha/icon-button (13914:482):
-        //   BUTTON outline: texto=text-primary · ícones=edge (accent)
-        //   ICON-BUTTON outline: host color=edge (ícone herda via inherit !important)
-        //   Hover: icons/host = accent-hover (texto button mantém primary)
-        //   Active: tudo = accent-pressed
-        &[outline]:not([outline="false"]),
-        &[variant="outline"] {
-            background: transparent;
-            box-shadow: inset 0 0 0 var(--matcha-border-thin, 2px) var(--matcha-button-color-edge);
-            color: var(--matcha-color-text-primary);
-
-            &:hover:not([disabled]):not([disabled="true"]) {
-                box-shadow: inset 0 0 0 var(--matcha-border-thin, 2px) var(--matcha-button-color-hover);
-            }
-            &:active:not([disabled]):not([disabled="true"]) {
-                box-shadow: inset 0 0 0 var(--matcha-border-thin, 2px) var(--matcha-button-color-pressed);
-                color: var(--matcha-button-color-pressed);
-            }
-        }
-
-        // Icon-button outline: host color = edge (ícone é o único conteúdo semântico)
-        &[matcha-icon-button][outline]:not([outline="false"]),
-        &[matcha-icon-button][variant="outline"] {
-            color: var(--matcha-button-color-edge);
-
-            &:hover:not([disabled]):not([disabled="true"]) {
-                color: var(--matcha-button-color-hover);
-            }
-            &:active:not([disabled]):not([disabled="true"]) {
-                color: var(--matcha-button-color-pressed);
-            }
-        }
-
-        // Button outline: ícones (Left/Right) acompanham edge — texto mantém primary
-        &[matcha-button][outline]:not([outline="false"]) matcha-icon,
-        &[matcha-button][outline]:not([outline="false"]) [class^="i-matcha-"],
-        &[matcha-button][outline]:not([outline="false"]) [class*=" i-matcha-"],
-        &[matcha-button][variant="outline"] matcha-icon,
-        &[matcha-button][variant="outline"] [class^="i-matcha-"],
-        &[matcha-button][variant="outline"] [class*=" i-matcha-"] {
-            color: var(--matcha-button-color-edge) !important;
-        }
-        &[matcha-button][outline]:hover:not([disabled]):not([disabled="true"]) matcha-icon,
-        &[matcha-button][outline]:hover:not([disabled]):not([disabled="true"]) [class^="i-matcha-"],
-        &[matcha-button][outline].is-state-hover matcha-icon {
-            color: var(--matcha-button-color-hover) !important;
-        }
-        &[matcha-button][outline]:active:not([disabled]):not([disabled="true"]) matcha-icon,
-        &[matcha-button][outline]:active:not([disabled]):not([disabled="true"]) [class^="i-matcha-"],
-        &[matcha-button][outline].is-state-active matcha-icon {
-            color: var(--matcha-button-color-pressed) !important;
-        }
-
-        // ── Variant: ghost (basic = legacy alias) ────────────────────────────────────────
-        // Figma: Default/Hover=text-primary · Active=accent-pressed (texto + ícones)
-        //        Ícones do button ghost acompanham edge quando a cor é semântica
-        &[basic]:not([basic="false"]),
-        &[ghost]:not([ghost="false"]),
-        &[variant="ghost"] {
-            background: transparent;
-            color: var(--matcha-color-text-primary);
-
-            &:active:not([disabled]):not([disabled="true"]) {
-                color: var(--matcha-button-color-pressed);
-            }
-        }
-
-        // Button ghost: ícones acompanham edge (accent) — texto mantém primary
-        &[matcha-button][basic]:not([basic="false"]) matcha-icon,
-        &[matcha-button][basic]:not([basic="false"]) [class^="i-matcha-"],
-        &[matcha-button][ghost]:not([ghost="false"]) matcha-icon,
-        &[matcha-button][ghost]:not([ghost="false"]) [class^="i-matcha-"],
-        &[matcha-button][variant="ghost"] matcha-icon,
-        &[matcha-button][variant="ghost"] [class^="i-matcha-"] {
-            color: var(--matcha-button-color-edge) !important;
-        }
-        &[matcha-button][ghost]:hover:not([disabled]):not([disabled="true"]) matcha-icon,
-        &[matcha-button][basic]:hover:not([disabled]):not([disabled="true"]) matcha-icon,
-        &[matcha-button][ghost].is-state-hover matcha-icon,
-        &[matcha-button][basic].is-state-hover matcha-icon {
-            color: var(--matcha-button-color-hover) !important;
-        }
-        &[matcha-button][ghost]:active:not([disabled]):not([disabled="true"]) matcha-icon,
-        &[matcha-button][basic]:active:not([disabled]):not([disabled="true"]) matcha-icon,
-        &[matcha-button][ghost].is-state-active matcha-icon,
-        &[matcha-button][basic].is-state-active matcha-icon {
-            color: var(--matcha-button-color-pressed) !important;
-        }
-
-        // ── Modifier: alpha ──────────────────────────────────────────────
-        &[alpha]:not([alpha="false"]) {
-            background: var(--matcha-button-color-alpha);
-            color: var(--matcha-button-color);
-        }
-
-        // ── Modifier: link (legacy, afeta button[link="true"]) ───────────
-        // matcha-link tem seu próprio bloco (&[matcha-link]) com regras
-        // próprias de underline (hover + .matcha-link--underline)
-        &[link]:not([link="false"]):not([matcha-link]) {
-            background: transparent;
-            color: var(--matcha-button-color);
-            text-decoration: underline;
-        }
-        // matcha-link: apenas cor do texto (o bloco estrutural [matcha-link]
-        // define text-decoration: none + hover/active + class underline)
-        &[matcha-link] {
-            color: var(--matcha-button-color);
-        }
-
-        // ── State: disabled ──────────────────────────────────────────────
-        // Figma (13913:1088) Disabled state:
-        //   Filled:  bg=interaction/disabled-bg · label+icons=accent/text-on (mesma cor do filled default)
-        //   Outline: stroke=interaction/disabled-bg (NÃO disabled-border) · label+icons=disabled-fg
-        //   Ghost:   sem bg/stroke · label+icons=disabled-fg
-        //   State-layer overlay DESLIGADO em todos disabled.
-        &[disabled]:not([disabled="false"]),
-        &[disabled="true"] {
-            pointer-events: none;
-            cursor: not-allowed;
-
-            // state-layer overlay desligado
-            &::before { opacity: 0 !important; }
-
-            // Filled — bg disabled + texto/ícones accent-text-on (Figma spec)
-            background: var(--matcha-color-interaction-disabled-bg);
-            color: var(--matcha-color-accent-text-on);
-            box-shadow: none;
-
-            // Outline — stroke usa mesma cor do filled-bg (Figma usa interaction/disabled-bg)
-            &[outline]:not([outline="false"]),
-            &[variant="outline"] {
-                background: transparent;
-                color: var(--matcha-color-interaction-disabled-fg);
-                box-shadow: inset 0 0 0 var(--matcha-border-thin, 2px) var(--matcha-color-interaction-disabled-bg);
-            }
-
-            // Ghost / basic / link — só texto dedicado
-            &[basic]:not([basic="false"]),
-            &[ghost]:not([ghost="false"]),
-            &[variant="ghost"],
-            &[link]:not([link="false"]) {
-                background: transparent;
-                color: var(--matcha-color-interaction-disabled-fg);
-                box-shadow: none;
-            }
-
-            // Alpha — bg alpha dedicado
-            &[alpha]:not([alpha="false"]) {
-                background: var(--matcha-color-interaction-disabled-bg-alpha);
-                color: var(--matcha-color-interaction-disabled-fg);
-            }
-
-            // Ícones do button (Left/Right) no disabled:
-            //   Filled: herdam color do host (accent-text-on) ✓
-            //   Outline/Ghost: forçam disabled-fg pra sobrescrever regra !important do edge
-            &[matcha-button][outline] matcha-icon,
-            &[matcha-button][outline] [class^="i-matcha-"],
-            &[matcha-button][outline] [class*=" i-matcha-"],
-            &[matcha-button][basic] matcha-icon,
-            &[matcha-button][basic] [class^="i-matcha-"],
-            &[matcha-button][ghost] matcha-icon,
-            &[matcha-button][ghost] [class^="i-matcha-"],
-            &[matcha-button][variant="outline"] matcha-icon,
-            &[matcha-button][variant="outline"] [class^="i-matcha-"],
-            &[matcha-button][variant="ghost"] matcha-icon,
-            &[matcha-button][variant="ghost"] [class^="i-matcha-"] {
-                color: var(--matcha-color-interaction-disabled-fg) !important;
-            }
-        }
-
-        // ── Badge indicator (always accent, pattern fixo) ────────────────
-        &[badge]:not([badge="false"])::after {
-            background: var(--matcha-color-accent, #{getAccent($theme)});
-        }
-
-        // ── Ripple overlay ───────────────────────────────────────────────
-        .ripple {
-            background: var(--matcha-button-color-alpha);
-        }
-    }
-}
-
-// ── matcha-icon-button: auto-size inner icons per Figma spec ────────────────
-// XS button (28) → icon 16  ·  SM (32) → 20  ·  MD (40)/LG (48)/XL (56) → 24
-button[matcha-icon-button],
-a[matcha-icon-button] {
-    aspect-ratio: 1;
-
-    matcha-icon {
-        flex: none; // NÃO expandir com o button
-    }
-
-    &[size="xs"] matcha-icon,
-    &[size="tiny"] matcha-icon {
-        font-size: 16px !important;
-        width: 16px !important;
-        height: 16px !important;
-        line-height: 16px !important;
-    }
-    &[size="sm"] matcha-icon,
-    &[size="small"] matcha-icon {
-        font-size: 20px !important;
-        width: 20px !important;
-        height: 20px !important;
-        line-height: 20px !important;
-    }
-    &[size="md"] matcha-icon,
-    &[size="medium"] matcha-icon,
-    &[size="lg"] matcha-icon,
-    &[size="large"] matcha-icon,
-    &[size="xl"] matcha-icon,
-    &[size="huge"] matcha-icon {
-        font-size: 24px !important;
-        width: 24px !important;
-        height: 24px !important;
-        line-height: 24px !important;
-    }
-}
+// =============================================================================
+// matcha-buttons.scss — Button & Icon Button (modernized)
+// Aligned with Figma: matcha/button + matcha/icon-button
+// Sizes: SM(32) MD(40) LG(48) XL(56) + legacy aliases (tiny/small/medium/large/huge)
+// Variants: Filled(default) Outline Ghost(basic) Alpha Link
+// State layer: ::before opacity pattern (consistent with all DS components)
+// =============================================================================
+
+// ── Disabled mixins ─────────────────────────────────────────────────────────
+
+@mixin _disabled-solid-button($theme) {
+    background: var(--matcha-color-disabled-bg, #{getDisabled($theme)});
+    color: var(--matcha-color-disabled-fg, #{getDisabledBgContrast($theme)});
+    box-shadow: 0 0 0 0px inset;
+    pointer-events: none;
+}
+
+@mixin _disabled-basic-button($theme) {
+    background: var(--matcha-color-surface, #{getSurface($theme)});
+    color: var(--matcha-color-disabled-bg, #{getDisabled($theme)});
+    box-shadow: 0 0 0 0px inset;
+    pointer-events: none;
+}
+
+@mixin _disabled-outline-button($theme) {
+    background: transparent;
+    color: var(--matcha-color-disabled-bg, #{getDisabled($theme)});
+    box-shadow: 0 0 0 var(--matcha-border-thin, 2px) inset;
+    pointer-events: none;
+}
+
+@mixin _disabled-alpha-button($theme) {
+    background: var(--matcha-color-disabled-bg-alpha, #{getDisabledAlpha($theme)});
+    color: var(--matcha-color-disabled-bg, #{getDisabled($theme)});
+    box-shadow: 0 0 0 0px inset;
+    pointer-events: none;
+}
+
+@mixin _disabled-link-button($theme) {
+    background: transparent;
+    color: var(--matcha-color-disabled-bg, #{getDisabled($theme)});
+    box-shadow: 0 0 0 0px inset;
+    pointer-events: none;
+}
+
+// ── Size classes (responsive, aligned with Figma XS/SM/MD/LG/XL) ────────────
+
+@mixin generate-matcha-button-size-classes($helper-breakpoints) {
+    @each $breakpoint, $materialBreakpoint in $helper-breakpoints {
+        @include media-breakpoint($materialBreakpoint) {
+            $infix: if($materialBreakpoint == null, "", "-#{$breakpoint}");
+
+            // XS — 28px. Figma matcha/button XS: pad 8 · gap 2 · text/caption (11/400/14, letter 0.3)
+            &[size#{$infix}="xs"] {
+                padding: 0 var(--matcha-space-100, 8px);
+                font-size: var(--matcha-text-p-tiny, 11px);
+                font-weight: var(--matcha-weight-regular, 400);
+                line-height: var(--matcha-leading-p-tiny, 14px);
+                letter-spacing: var(--matcha-letter-spacing-caption, 0.3px);
+                height: 28px;
+                gap: var(--matcha-space-025, 2px);
+            }
+
+            // SM — 32px. Figma: pad 8 · gap 4 · text/button-sm (13/500/19 letter 0.2)
+            &[size#{$infix}="sm"],
+            &[size#{$infix}="tiny"] {
+                padding: 0 var(--matcha-space-100, 8px);
+                font-size: var(--matcha-text-label-sm, 13px);
+                font-weight: var(--matcha-weight-medium, 500);
+                line-height: var(--matcha-leading-label-sm, 19px);
+                height: 32px;
+                gap: var(--matcha-space-050, 4px);
+            }
+
+            // MD — 40px. Figma: pad 16 · gap 8 · text/button-md (14/500/20)
+            &[size#{$infix}="md"],
+            &[size#{$infix}="small"] {
+                padding: 0 var(--matcha-space-200, 16px);
+                font-size: var(--matcha-text-md, 14px);
+                font-weight: var(--matcha-weight-medium, 500);
+                line-height: var(--matcha-leading-md, 20px);
+                height: 40px;
+                gap: var(--matcha-space-100, 8px);
+            }
+
+            // LG — 48px. Figma: pad 24 · gap 8
+            &[size#{$infix}="lg"],
+            &[size#{$infix}="medium"] {
+                padding: 0 var(--matcha-space-300, 24px);
+                font-size: var(--matcha-text-lg, 16px);
+                font-weight: var(--matcha-weight-semibold, 600);
+                line-height: var(--matcha-leading-label-lg, 22px);
+                height: 48px;
+                gap: var(--matcha-space-100, 8px);
+            }
+
+            // XL — 56px. Figma: pad 32 · gap 8
+            &[size#{$infix}="xl"],
+            &[size#{$infix}="large"],
+            &[size#{$infix}="huge"] {
+                padding: 0 var(--matcha-space-400, 32px);
+                font-size: var(--matcha-text-lg, 16px);
+                font-weight: var(--matcha-weight-semibold, 600);
+                line-height: var(--matcha-leading-label-lg, 22px);
+                height: 56px;
+                gap: var(--matcha-space-100, 8px);
+            }
+        }
+    }
+}
+
+// ── Structural ──────────────────────────────────────────────────────────────
+
+button[matcha-button],
+a[matcha-button],
+button[matcha-icon-button],
+a[matcha-icon-button],
+button[matcha-link],
+a[matcha-link] {
+    overflow: hidden;
+    position: relative;
+    font-size: var(--matcha-text-md, 14px);
+    font-weight: var(--matcha-weight-medium, 500);
+    font-family: inherit;
+    height: px-to-rem(40px); // default MD; overridden by size attribute selectors
+    appearance: auto;
+    text-rendering: auto;
+    letter-spacing: var(--matcha-letter-spacing-button, 0.2px);
+    word-spacing: normal;
+    line-height: normal;
+    text-transform: none;
+    text-indent: 0px;
+    text-shadow: none;
+    text-align: center;
+    text-wrap: nowrap;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    cursor: pointer;
+    box-sizing: border-box;
+    border: none;
+    border-radius: var(--matcha-radius-lg, 8px);
+
+    * { pointer-events: none; }
+
+    // Figma spec: ícones dentro de button herdam a foreground color do botão
+    // (matcha-icon tem color-default próprio via tema — forçamos inherit com !important
+    // pra vencer o tema que aplica em [class^="i-matcha-"] globalmente)
+    matcha-icon,
+    [class^="i-matcha-"],
+    [class*=" i-matcha-"] {
+        color: inherit !important;
+    }
+
+    @include generate-matcha-button-size-classes($helper-breakpoints);
+
+    // Figma matcha/button usa DOIS feedbacks combinados:
+    //   1. Cor do bg muda (accent-default → accent-hover → accent-pressed)
+    //   2. State-layer overlay por cima (matcha/color/state-layer/fg)
+    //      - Filled:  opacity 0.15 hover / 0.30 active
+    //      - Outline/Ghost: opacity 0.10 hover / 0.20 active
+    // ::before aplica o state-layer; :hover/:active ou .is-state-* ativam.
+    transition:
+        background-color 150ms cubic-bezier(0.4, 0, 0.2, 1),
+        box-shadow 150ms cubic-bezier(0.4, 0, 0.2, 1),
+        color 150ms cubic-bezier(0.4, 0, 0.2, 1);
+
+    &::before {
+        content: '';
+        position: absolute;
+        inset: 0;
+        background: var(--matcha-color-state-layer-fg, currentColor);
+        opacity: 0;
+        border-radius: inherit;
+        pointer-events: none;
+        transition: opacity 150ms cubic-bezier(0.4, 0, 0.2, 1);
+    }
+
+    // Filled (variant default) — state-layer forte
+    &:hover:not([disabled]):not([disabled="true"]):not([outline]):not([basic]):not([ghost]):not([link]):not([alpha]):not([matcha-link])::before,
+    &.is-state-hover:not([outline]):not([basic]):not([ghost]):not([alpha])::before {
+        opacity: 0.15;
+    }
+    &:active:not([disabled]):not([disabled="true"]):not([outline]):not([basic]):not([ghost]):not([link]):not([alpha]):not([matcha-link])::before,
+    &.is-state-active:not([outline]):not([basic]):not([ghost]):not([alpha])::before {
+        opacity: 0.30;
+    }
+
+    // Outline / Ghost — state-layer sutil
+    &[outline]:hover:not([disabled]):not([disabled="true"])::before,
+    &[basic]:hover:not([disabled]):not([disabled="true"])::before,
+    &[ghost]:hover:not([disabled]):not([disabled="true"])::before,
+    &[outline].is-state-hover::before,
+    &[basic].is-state-hover::before,
+    &[ghost].is-state-hover::before {
+        opacity: 0.10;
+    }
+    &[outline]:active:not([disabled]):not([disabled="true"])::before,
+    &[basic]:active:not([disabled]):not([disabled="true"])::before,
+    &[ghost]:active:not([disabled]):not([disabled="true"])::before,
+    &[outline].is-state-active::before,
+    &[basic].is-state-active::before,
+    &[ghost].is-state-active::before {
+        opacity: 0.20;
+    }
+
+    &[disabled] {
+        pointer-events: none;
+        cursor: default;
+    }
+
+    // ── Variant modifiers (estrutural — cores vêm do mixin de tema) ──
+    &[basic]:not([basic="false"]),
+    &[ghost]:not([ghost="false"]) {
+        background: transparent;
+    }
+
+    &[outline]:not([outline="false"]) {
+        background: transparent;
+
+        &[link]:not([link="false"]) {
+            &[size="sm"], &[size="tiny"] { padding: 0 var(--matcha-space-100, 8px); gap: var(--matcha-space-050, 4px); }
+            &[size="md"], &[size="small"] { padding: 0 var(--matcha-space-150, 12px); gap: var(--matcha-space-100, 8px); }
+            &[size="lg"], &[size="medium"] { padding: 0 var(--matcha-space-200, 16px); gap: var(--matcha-space-150, 12px); }
+            &[size="xl"], &[size="large"], &[size="huge"] { padding: 0 var(--matcha-space-200, 16px); gap: var(--matcha-space-150, 12px); }
+        }
+    }
+
+    &[pill]:not([pill="false"]) {
+        border-radius: var(--matcha-radius-pill, 9999px);
+    }
+
+    &[link]:not([link="false"]) {
+        text-transform: initial;
+        letter-spacing: 0;
+        text-decoration: none;
+        padding: 0;
+        background: transparent;
+    }
+
+    // ── matcha-link specific (Figma spec 16914:500) ──
+    // SM=11/14 Regular letter 0.3 · MD=14/20 Medium · LG=16/22 SemiBold
+    // Hover/Active → underline automático. Underline=true → permanente.
+    // Disabled → opacity via disabled-fg color (no underline).
+    &[matcha-link] {
+        height: auto;
+        min-height: 0;
+        max-height: none;
+        padding: 0;
+        background: transparent;
+        border-radius: 0;
+        text-decoration: none; // reset do underline default do <a>; hover/class re-aplica
+
+        &[size="sm"], &[size="tiny"] {
+            font-size: var(--matcha-text-p-tiny, 11px);
+            line-height: var(--matcha-leading-p-tiny, 14px);
+            font-weight: var(--matcha-weight-regular, 400);
+            letter-spacing: var(--matcha-letter-spacing-caption, 0.3px);
+            height: auto;
+            max-height: none;
+        }
+        &[size="md"], &[size="small"] {
+            font-size: var(--matcha-text-md, 14px);
+            line-height: var(--matcha-leading-md, 20px);
+            font-weight: var(--matcha-weight-medium, 500);
+            letter-spacing: var(--matcha-letter-spacing-button, 0.2px);
+            height: auto;
+            max-height: none;
+        }
+        &[size="lg"], &[size="medium"] {
+            font-size: var(--matcha-text-lg, 16px);
+            line-height: var(--matcha-leading-label-lg, 22px);
+            font-weight: var(--matcha-weight-semibold, 600);
+            letter-spacing: var(--matcha-letter-spacing-button, 0.2px);
+            height: auto;
+            max-height: none;
+        }
+
+        // State layer fica off (link não tem overlay/bg)
+        &::before { display: none; }
+        // Press scale também off — link é texto
+        transition: none;
+        &:active:not([disabled]):not([disabled="true"]) { transform: none; }
+
+        // Hover e active: underline (Figma spec)
+        &:hover:not([disabled]):not([disabled="true"]),
+        &:active:not([disabled]):not([disabled="true"]) {
+            text-decoration: underline;
+        }
+
+        // Underline permanente via property (classe do HostBinding no component)
+        &.matcha-link--underline {
+            text-decoration: underline;
+        }
+
+        // ── Canonical extended size names (tiny|small|medium|large|huge) ────────
+        // matcha-link expõe a escala CANÔNICA por extenso, 1:1 com sm/md/lg
+        // (sm→small · md→medium · lg→large). O bloco acima pareia esses nomes com
+        // a escala LEGADA do matcha-button (small=md, medium=lg), então
+        // re-asseguramos aqui — scoped APENAS ao matcha-link — os mesmos pixels do
+        // tier abreviado correspondente (sem mudança visual). tiny→sm tier (menor
+        // disponível), huge→lg tier (maior disponível no link).
+        &[size="tiny"],
+        &[size="small"] {
+            font-size: var(--matcha-text-p-tiny, 11px);
+            line-height: var(--matcha-leading-p-tiny, 14px);
+            font-weight: var(--matcha-weight-regular, 400);
+            letter-spacing: var(--matcha-letter-spacing-caption, 0.3px);
+            height: auto;
+            max-height: none;
+        }
+        &[size="medium"] {
+            font-size: var(--matcha-text-md, 14px);
+            line-height: var(--matcha-leading-md, 20px);
+            font-weight: var(--matcha-weight-medium, 500);
+            letter-spacing: var(--matcha-letter-spacing-button, 0.2px);
+            height: auto;
+            max-height: none;
+        }
+        &[size="large"],
+        &[size="huge"] {
+            font-size: var(--matcha-text-lg, 16px);
+            line-height: var(--matcha-leading-label-lg, 22px);
+            font-weight: var(--matcha-weight-semibold, 600);
+            letter-spacing: var(--matcha-letter-spacing-button, 0.2px);
+            height: auto;
+            max-height: none;
+        }
+    }
+
+    &[icon]:not([icon="false"]) {
+        aspect-ratio: 1;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+
+        // Icon-button padding per Figma spec matcha/icon-button (all-direction):
+        // XS=6 · SM=6 · MD=8 · LG=12 · XL=16 (padding igual em todos os lados)
+        &[size="xs"] {
+            padding: var(--matcha-space-075, 6px) !important;
+        }
+        &[size="sm"], &[size="tiny"] {
+            padding: var(--matcha-space-075, 6px) !important;
+        }
+        &[size="md"], &[size="small"] {
+            padding: var(--matcha-space-100, 8px) !important;
+        }
+        &[size="lg"], &[size="medium"] {
+            padding: var(--matcha-space-150, 12px) !important;
+        }
+        &[size="xl"], &[size="large"], &[size="huge"] {
+            padding: var(--matcha-space-200, 16px) !important;
+        }
+
+        // Auto-size inner matcha-icon conforme Figma matcha/icon-button spec:
+        // XS→16 · SM→20 · MD→24 · LG→24 · XL→24
+        &[size="xs"] [class^="i-matcha-"],
+        &[size="xs"] [class*=" i-matcha-"] {
+            font-size: var(--matcha-icon-size-sm, 16px);
+            width: var(--matcha-icon-size-sm, 16px);
+            height: var(--matcha-icon-size-sm, 16px);
+            line-height: var(--matcha-icon-size-sm, 16px);
+        }
+        &[size="sm"] [class^="i-matcha-"],
+        &[size="sm"] [class*=" i-matcha-"],
+        &[size="tiny"] [class^="i-matcha-"],
+        &[size="tiny"] [class*=" i-matcha-"] {
+            font-size: 20px;
+            width: 20px;
+            height: 20px;
+            line-height: 20px;
+        }
+        &[size="md"] [class^="i-matcha-"],
+        &[size="md"] [class*=" i-matcha-"],
+        &[size="small"] [class^="i-matcha-"],
+        &[size="small"] [class*=" i-matcha-"],
+        &[size="lg"] [class^="i-matcha-"],
+        &[size="lg"] [class*=" i-matcha-"],
+        &[size="medium"] [class^="i-matcha-"],
+        &[size="medium"] [class*=" i-matcha-"],
+        &[size="xl"] [class^="i-matcha-"],
+        &[size="xl"] [class*=" i-matcha-"],
+        &[size="large"] [class^="i-matcha-"],
+        &[size="large"] [class*=" i-matcha-"],
+        &[size="huge"] [class^="i-matcha-"],
+        &[size="huge"] [class*=" i-matcha-"] {
+            font-size: var(--matcha-icon-size-md, 24px);
+            width: var(--matcha-icon-size-md, 24px);
+            height: var(--matcha-icon-size-md, 24px);
+            line-height: var(--matcha-icon-size-md, 24px);
+        }
+    }
+
+    // ── Badge ──
+    &[badge]:not([badge="false"]) {
+        overflow: visible;
+        position: relative;
+
+        &::after {
+            content: "";
+            position: absolute;
+            top: -0.25rem;
+            right: -0.25rem;
+            width: 1.32rem;
+            height: 1.32rem;
+            border-radius: var(--matcha-radius-pill, 9999px);
+            z-index: 2;
+        }
+
+        &[size="sm"]::after, &[size="tiny"]::after { width: 0.75rem; height: 0.75rem; top: -0.15rem; right: -0.15rem; }
+        &[size="md"]::after, &[size="small"]::after { width: 1rem; height: 1rem; top: -0.2rem; right: -0.2rem; }
+        &[size="xl"]::after, &[size="large"]::after, &[size="huge"]::after { width: 1.5rem; height: 1.5rem; top: -0.3rem; right: -0.3rem; }
+    }
+
+    // ── Focus ring ──
+    &:focus-visible:not([disabled]) {
+        outline: var(--matcha-state-focus-ring-width, 2px) solid var(--matcha-color-accent, #6200ee);
+        outline-offset: var(--matcha-state-focus-ring-offset, 2px);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        &::before { transition: none; }
+        &, &:active:not([disabled]):not([disabled="true"]) { transition: none; transform: none; }
+    }
+
+    // ── Loading state ──
+    // Spinner inline do lado direito do conteúdo + content dims pra 60%
+    // Preserva width (não shift) e bloqueia cliques com pointer-events.
+    &.matcha-button--loading {
+        pointer-events: none;
+        cursor: progress;
+
+        // Dim no content interior (tudo exceto o spinner)
+        > :not(.matcha-button__spinner) {
+            opacity: 0.6;
+        }
+    }
+
+    .matcha-button__spinner {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        margin-left: var(--matcha-space-100, 8px);
+        flex: none;
+        line-height: 0;
+
+        svg {
+            display: block;
+        }
+
+        @media (prefers-reduced-motion: reduce) {
+            svg circle animateTransform {
+                // Retarda mas não remove (ainda sinaliza loading)
+                dur: 2s !important;
+            }
+        }
+    }
+
+    // Visually hidden span pra screen readers (loading announcement)
+    .matcha-button__sr-only {
+        position: absolute !important;
+        width: 1px !important;
+        height: 1px !important;
+        padding: 0 !important;
+        margin: -1px !important;
+        overflow: hidden !important;
+        clip: rect(0, 0, 0, 0) !important;
+        white-space: nowrap !important;
+        border: 0 !important;
+    }
+
+    // ── Touch targets (WCAG 2.5.5: 44x44 mínimo em coarse pointers) ──
+    // XS (28), SM (32), MD (40) ficam abaixo de 44px — expande hit area invisível.
+    @media (pointer: coarse) {
+        &[size="xs"],
+        &[size="sm"], &[size="tiny"],
+        &[size="md"], &[size="small"] {
+            position: relative;
+
+            &::after {
+                content: '';
+                position: absolute;
+                inset: -8px;            // expande ~16px em cada eixo → 28+16=44, 32+16=48, 40+16=56 ✓
+                z-index: 0;
+                pointer-events: auto;   // captura cliques aqui
+            }
+
+            // ::before já é usado pro state layer, então nosso overlay vai no ::after
+            // State layer (::before) fica colado ao botão visual, overlay (::after) expande hit.
+        }
+    }
+}
+
+// ── Theme mixin ─────────────────────────────────────────────────────────────
+
+@mixin matcha-button-theme($theme) {
+    // ═════════════════════════════════════════════════════════════════════════
+    // CSS var-based theming (regra DS-ARCHITECTURE #7: Tokens over hardcode)
+    //
+    // Todo botão usa --matcha-button-color como token interno.
+    // `[color="X"]` apenas mapeia pra esses tokens — as variantes
+    // (filled/outline/ghost/alpha/link) interpretam um único set de vars.
+    //
+    // Consumidor pode override QUALQUER cor via style:
+    //   <button matcha-button style="--matcha-button-color: #ff00ff">Custom</button>
+    //
+    // Adicionar cor nova = adicionar 1 mapping (3 linhas).
+    // ═════════════════════════════════════════════════════════════════════════
+
+    button[matcha-button],
+    a[matcha-button],
+    button[matcha-icon-button],
+    a[matcha-icon-button],
+    button[matcha-link],
+    a[matcha-link] {
+        // Tokens internos (Figma matcha/button 13913:1088):
+        //   --matcha-button-color         = bg do filled (Default)
+        //   --matcha-button-color-hover   = bg filled / stroke outline (Hover)
+        //   --matcha-button-color-pressed = bg filled / stroke+text (Active)
+        //   --matcha-button-color-text-on = texto do filled (accent/text-on etc.)
+        //   --matcha-button-color-alpha   = alpha modifier / ripple
+        //   --matcha-button-color-edge    = stroke do outline (Default)
+        --matcha-button-color: var(--matcha-color-neutral);
+        --matcha-button-color-hover: var(--matcha-color-neutral-hover);
+        --matcha-button-color-pressed: var(--matcha-color-neutral-hover);
+        --matcha-button-color-text-on: var(--matcha-color-neutral-contrast);
+        --matcha-button-color-alpha: var(--matcha-color-neutral-alpha);
+        --matcha-button-color-edge: var(--matcha-color-fg, #{getForeground($theme)});
+
+        // Badge ring herda o bg do botão (filled) — outline/ghost override pra surface,
+        // pois o bg deles é transparente e o ring deve casar com a página atrás.
+        --matcha-color-badge-border: var(--matcha-button-color);
+
+        // ── Color mapping ────────────────────────────────────────────────────────────────
+        &[color="basic"] {
+            --matcha-button-color: var(--matcha-color-neutral);
+            --matcha-button-color-hover: var(--matcha-color-neutral-hover);
+            --matcha-button-color-pressed: var(--matcha-color-neutral-hover);
+            --matcha-button-color-text-on: var(--matcha-color-neutral-contrast);
+            --matcha-button-color-alpha: var(--matcha-color-neutral-alpha);
+            --matcha-button-color-edge: var(--matcha-color-fg, #{getForeground($theme)});
+        }
+        &[color="primary"] {
+            --matcha-button-color: var(--matcha-color-primary, #{getPrimary($theme)});
+            --matcha-button-color-hover: var(--matcha-color-primary-hover);
+            --matcha-button-color-pressed: var(--matcha-color-primary-pressed);
+            --matcha-button-color-text-on: var(--matcha-color-primary-contrast, #{getPrimaryContrast($theme)});
+            --matcha-button-color-alpha: var(--matcha-color-primary-alpha, #{getPrimaryAlpha($theme)});
+            --matcha-button-color-edge: var(--matcha-color-primary, #{getPrimary($theme)});
+        }
+        &[color="accent"] {
+            --matcha-button-color: var(--matcha-color-accent, #{getAccent($theme)});
+            --matcha-button-color-hover: var(--matcha-color-accent-hover);
+            --matcha-button-color-pressed: var(--matcha-color-accent-pressed);
+            --matcha-button-color-text-on: var(--matcha-color-accent-text-on);
+            --matcha-button-color-alpha: var(--matcha-color-accent-alpha, #{getAccentAlpha($theme)});
+            --matcha-button-color-edge: var(--matcha-color-accent, #{getAccent($theme)});
+        }
+        &[color="success"] {
+            --matcha-button-color: var(--matcha-color-success, #{getSuccess($theme)});
+            --matcha-button-color-hover: var(--matcha-color-success-hover);
+            --matcha-button-color-pressed: var(--matcha-color-success-pressed);
+            --matcha-button-color-text-on: var(--matcha-color-success-contrast, #{getSuccessContrast($theme)});
+            --matcha-button-color-alpha: var(--matcha-color-success-alpha, #{getSuccessAlpha($theme)});
+            --matcha-button-color-edge: var(--matcha-color-success, #{getSuccess($theme)});
+        }
+        &[color="warn"] {
+            --matcha-button-color: var(--matcha-color-warn, #{getWarn($theme)});
+            --matcha-button-color-hover: var(--matcha-color-warn-hover);
+            --matcha-button-color-pressed: var(--matcha-color-warn-pressed);
+            --matcha-button-color-text-on: var(--matcha-color-warn-contrast, #{getWarnContrast($theme)});
+            --matcha-button-color-alpha: var(--matcha-color-warn-alpha, #{getWarnAlpha($theme)});
+            --matcha-button-color-edge: var(--matcha-color-warn, #{getWarn($theme)});
+        }
+        &[color="danger"] {
+            --matcha-button-color: var(--matcha-color-danger, #{getDanger($theme)});
+            --matcha-button-color-hover: var(--matcha-color-danger-hover);
+            --matcha-button-color-pressed: var(--matcha-color-danger-pressed);
+            --matcha-button-color-text-on: var(--matcha-color-danger-contrast, #{getDangerContrast($theme)});
+            --matcha-button-color-alpha: var(--matcha-color-danger-alpha, #{getDangerAlpha($theme)});
+            --matcha-button-color-edge: var(--matcha-color-danger, #{getDanger($theme)});
+        }
+        &[color="info"] {
+            --matcha-button-color: var(--matcha-color-info, #{getInfo($theme)});
+            --matcha-button-color-hover: var(--matcha-color-info-hover);
+            --matcha-button-color-pressed: var(--matcha-color-info-pressed);
+            --matcha-button-color-text-on: var(--matcha-color-info-contrast, #{getInfoContrast($theme)});
+            --matcha-button-color-alpha: var(--matcha-color-info-alpha, #{getInfoAlpha($theme)});
+            --matcha-button-color-edge: var(--matcha-color-info, #{getInfo($theme)});
+        }
+
+        // ── Filled (default variant) ──────────────────────────────────────────────────────
+        // Figma: Default=accent · Hover=accent-hover · Active=accent-pressed
+        background: var(--matcha-button-color);
+        color: var(--matcha-button-color-text-on);
+
+        &:hover:not([disabled]):not([disabled="true"]):not([outline]):not([basic]):not([ghost]):not([link]):not([alpha]):not([matcha-link]) {
+            background: var(--matcha-button-color-hover);
+        }
+        &:active:not([disabled]):not([disabled="true"]):not([outline]):not([basic]):not([ghost]):not([link]):not([alpha]):not([matcha-link]) {
+            background: var(--matcha-button-color-pressed);
+        }
+
+        // ── Variant: outline ────────────────────────────────────────────────────────────────
+        // Figma matcha/button (13913:1088) vs matcha/icon-button (13914:482):
+        //   BUTTON outline: texto=text-primary · ícones=edge (accent)
+        //   ICON-BUTTON outline: host color=edge (ícone herda via inherit !important)
+        //   Hover: icons/host = accent-hover (texto button mantém primary)
+        //   Active: tudo = accent-pressed
+        &[outline]:not([outline="false"]),
+        &[variant="outline"] {
+            background: transparent;
+            box-shadow: inset 0 0 0 var(--matcha-border-thin, 2px) var(--matcha-button-color-edge);
+            // Color slot: text segue --matcha-button-color-edge (border+text matching),
+            // com fallback pra text-primary quando consumer não setar a var.
+            // Antes era hardcoded text-primary → consumer tinha que duelar specificity.
+            color: var(--matcha-button-color-edge);
+            // Badge ring transparente — bg é transparente, qualquer cor fixa
+            // colide com o bg-do-pai-da-página (impossível detectar em CSS).
+            --matcha-color-badge-border: transparent;
+
+            &:hover:not([disabled]):not([disabled="true"]) {
+                box-shadow: inset 0 0 0 var(--matcha-border-thin, 2px) var(--matcha-button-color-hover);
+            }
+            &:active:not([disabled]):not([disabled="true"]) {
+                box-shadow: inset 0 0 0 var(--matcha-border-thin, 2px) var(--matcha-button-color-pressed);
+                color: var(--matcha-button-color-pressed);
+            }
+        }
+
+        // Icon-button outline: host color = edge (ícone é o único conteúdo semântico)
+        &[matcha-icon-button][outline]:not([outline="false"]),
+        &[matcha-icon-button][variant="outline"] {
+            color: var(--matcha-button-color-edge);
+
+            &:hover:not([disabled]):not([disabled="true"]) {
+                color: var(--matcha-button-color-hover);
+            }
+            &:active:not([disabled]):not([disabled="true"]) {
+                color: var(--matcha-button-color-pressed);
+            }
+        }
+
+        // Button outline: ícones (Left/Right) acompanham edge — texto mantém primary
+        &[matcha-button][outline]:not([outline="false"]) matcha-icon,
+        &[matcha-button][outline]:not([outline="false"]) [class^="i-matcha-"],
+        &[matcha-button][outline]:not([outline="false"]) [class*=" i-matcha-"],
+        &[matcha-button][variant="outline"] matcha-icon,
+        &[matcha-button][variant="outline"] [class^="i-matcha-"],
+        &[matcha-button][variant="outline"] [class*=" i-matcha-"] {
+            color: var(--matcha-button-color-edge) !important;
+        }
+        &[matcha-button][outline]:hover:not([disabled]):not([disabled="true"]) matcha-icon,
+        &[matcha-button][outline]:hover:not([disabled]):not([disabled="true"]) [class^="i-matcha-"],
+        &[matcha-button][outline].is-state-hover matcha-icon {
+            color: var(--matcha-button-color-hover) !important;
+        }
+        &[matcha-button][outline]:active:not([disabled]):not([disabled="true"]) matcha-icon,
+        &[matcha-button][outline]:active:not([disabled]):not([disabled="true"]) [class^="i-matcha-"],
+        &[matcha-button][outline].is-state-active matcha-icon {
+            color: var(--matcha-button-color-pressed) !important;
+        }
+
+        // ── Variant: ghost (basic = legacy alias) ────────────────────────────────────────
+        // Figma: Default/Hover=text-primary · Active=accent-pressed (texto + ícones)
+        // Slot --matcha-button-ghost-text com fallback text-primary (Figma intent
+        // preservado). Consumer override via parent: --matcha-button-ghost-text: X
+        &[basic]:not([basic="false"]),
+        &[ghost]:not([ghost="false"]),
+        &[variant="ghost"] {
+            background: transparent;
+            color: var(--matcha-button-ghost-text, var(--matcha-color-text-primary));
+            // Badge ring transparente — bg é transparente, qualquer cor fixa
+            // colide com o bg-do-pai-da-página (impossível detectar em CSS).
+            --matcha-color-badge-border: transparent;
+
+            &:active:not([disabled]):not([disabled="true"]) {
+                color: var(--matcha-button-color-pressed);
+            }
+        }
+
+        // Button ghost: ícones acompanham edge (accent) — texto mantém primary
+        &[matcha-button][basic]:not([basic="false"]) matcha-icon,
+        &[matcha-button][basic]:not([basic="false"]) [class^="i-matcha-"],
+        &[matcha-button][ghost]:not([ghost="false"]) matcha-icon,
+        &[matcha-button][ghost]:not([ghost="false"]) [class^="i-matcha-"],
+        &[matcha-button][variant="ghost"] matcha-icon,
+        &[matcha-button][variant="ghost"] [class^="i-matcha-"] {
+            color: var(--matcha-button-color-edge) !important;
+        }
+        &[matcha-button][ghost]:hover:not([disabled]):not([disabled="true"]) matcha-icon,
+        &[matcha-button][basic]:hover:not([disabled]):not([disabled="true"]) matcha-icon,
+        &[matcha-button][ghost].is-state-hover matcha-icon,
+        &[matcha-button][basic].is-state-hover matcha-icon {
+            color: var(--matcha-button-color-hover) !important;
+        }
+        &[matcha-button][ghost]:active:not([disabled]):not([disabled="true"]) matcha-icon,
+        &[matcha-button][basic]:active:not([disabled]):not([disabled="true"]) matcha-icon,
+        &[matcha-button][ghost].is-state-active matcha-icon,
+        &[matcha-button][basic].is-state-active matcha-icon {
+            color: var(--matcha-button-color-pressed) !important;
+        }
+
+        // ── Icon-button neutral (basic/default) — Figma matcha/icon-button ──
+        // Outline/Ghost Default (13914:179 / 13914:332) vinculam o glyph — e a
+        // borda do Outline — a matcha/color/icon/default (#75767a light / #9aa0a6
+        // dark), o MESMO token do matcha-icon solto. O texto do botão usa fg/
+        // text-primary; o ícone do icon-button NÃO. Redireciona edge + ghost-text
+        // só pro icon-button neutro. Cores override (accent/danger/...) seguem a
+        // própria cor via os blocos &[color="..."] acima.
+        &[matcha-icon-button]:not([color]),
+        &[matcha-icon-button][color="basic"] {
+            --matcha-button-color-edge: var(--matcha-color-icon-default);
+            --matcha-button-ghost-text: var(--matcha-color-icon-default);
+        }
+
+        // ── Modifier: alpha ──────────────────────────────────────────────
+        &[alpha]:not([alpha="false"]) {
+            background: var(--matcha-button-color-alpha);
+            color: var(--matcha-button-color);
+        }
+
+        // ── Modifier: link (legacy, afeta button[link="true"]) ───────────
+        // matcha-link tem seu próprio bloco (&[matcha-link]) com regras
+        // próprias de underline (hover + .matcha-link--underline)
+        &[link]:not([link="false"]):not([matcha-link]) {
+            background: transparent;
+            color: var(--matcha-button-color);
+            text-decoration: underline;
+        }
+        // matcha-link: apenas cor do texto (o bloco estrutural [matcha-link]
+        // define text-decoration: none + hover/active + class underline)
+        &[matcha-link] {
+            color: var(--matcha-button-color);
+        }
+
+        // ── State: disabled ──────────────────────────────────────────────
+        // Figma (13913:1088) Disabled state:
+        //   Filled:  bg=interaction/disabled-bg · label+icons=accent/text-on (mesma cor do filled default)
+        //   Outline: stroke=interaction/disabled-bg (NÃO disabled-border) · label+icons=disabled-fg
+        //   Ghost:   sem bg/stroke · label+icons=disabled-fg
+        //   State-layer overlay DESLIGADO em todos disabled.
+        &[disabled]:not([disabled="false"]),
+        &[disabled="true"] {
+            pointer-events: none;
+            cursor: not-allowed;
+
+            // state-layer overlay desligado
+            &::before { opacity: 0 !important; }
+
+            // Filled — bg disabled + texto/ícones accent-text-on (Figma spec)
+            background: var(--matcha-color-interaction-disabled-bg);
+            color: var(--matcha-color-accent-text-on);
+            box-shadow: none;
+
+            // Outline — stroke usa mesma cor do filled-bg (Figma usa interaction/disabled-bg)
+            &[outline]:not([outline="false"]),
+            &[variant="outline"] {
+                background: transparent;
+                color: var(--matcha-color-interaction-disabled-fg);
+                box-shadow: inset 0 0 0 var(--matcha-border-thin, 2px) var(--matcha-color-interaction-disabled-bg);
+            }
+
+            // Ghost / basic / link — só texto dedicado
+            &[basic]:not([basic="false"]),
+            &[ghost]:not([ghost="false"]),
+            &[variant="ghost"],
+            &[link]:not([link="false"]) {
+                background: transparent;
+                color: var(--matcha-color-interaction-disabled-fg);
+                box-shadow: none;
+            }
+
+            // Alpha — bg alpha dedicado
+            &[alpha]:not([alpha="false"]) {
+                background: var(--matcha-color-interaction-disabled-bg-alpha);
+                color: var(--matcha-color-interaction-disabled-fg);
+            }
+
+            // Ícones do button (Left/Right) no disabled:
+            //   Filled: herdam color do host (accent-text-on) ✓
+            //   Outline/Ghost: forçam disabled-fg pra sobrescrever regra !important do edge
+            &[matcha-button][outline] matcha-icon,
+            &[matcha-button][outline] [class^="i-matcha-"],
+            &[matcha-button][outline] [class*=" i-matcha-"],
+            &[matcha-button][basic] matcha-icon,
+            &[matcha-button][basic] [class^="i-matcha-"],
+            &[matcha-button][ghost] matcha-icon,
+            &[matcha-button][ghost] [class^="i-matcha-"],
+            &[matcha-button][variant="outline"] matcha-icon,
+            &[matcha-button][variant="outline"] [class^="i-matcha-"],
+            &[matcha-button][variant="ghost"] matcha-icon,
+            &[matcha-button][variant="ghost"] [class^="i-matcha-"] {
+                color: var(--matcha-color-interaction-disabled-fg) !important;
+            }
+        }
+
+        // ── Badge indicator (always accent, pattern fixo) ────────────────
+        &[badge]:not([badge="false"])::after {
+            background: var(--matcha-color-accent, #{getAccent($theme)});
+        }
+
+        // ── Ripple overlay ───────────────────────────────────────────────
+        .ripple {
+            background: var(--matcha-button-color-alpha);
+        }
+    }
+}
+
+// ── matcha-icon-button: auto-size inner icons per Figma spec ────────────────
+// XS button (28) → icon 16  ·  SM (32) → 20  ·  MD (40)/LG (48)/XL (56) → 24
+button[matcha-icon-button],
+a[matcha-icon-button] {
+    aspect-ratio: 1;
+
+    matcha-icon {
+        flex: none; // NÃO expandir com o button
+    }
+
+    &[size="xs"] matcha-icon,
+    &[size="tiny"] matcha-icon {
+        font-size: 16px !important;
+        width: 16px !important;
+        height: 16px !important;
+        line-height: 16px !important;
+    }
+    &[size="sm"] matcha-icon,
+    &[size="small"] matcha-icon {
+        font-size: 20px !important;
+        width: 20px !important;
+        height: 20px !important;
+        line-height: 20px !important;
+    }
+    &[size="md"] matcha-icon,
+    &[size="medium"] matcha-icon,
+    &[size="lg"] matcha-icon,
+    &[size="large"] matcha-icon,
+    &[size="xl"] matcha-icon,
+    &[size="huge"] matcha-icon {
+        font-size: 24px !important;
+        width: 24px !important;
+        height: 24px !important;
+        line-height: 24px !important;
+    }
+
+    // ── Canonical extended size names (tiny|small|medium|large|huge) ────────────
+    // matcha-icon-button expõe a escala CANÔNICA por extenso, 1:1 com as
+    // abreviações xs/sm/md/lg/xl (xs→tiny · sm→small · md→medium · lg→large ·
+    // xl→huge). O matcha-buttons.scss compartilhado pareia esses nomes com a
+    // escala LEGADA do matcha-button (small=md, medium=lg, …), então re-asseguramos
+    // aqui — scoped APENAS ao icon-button — os pixels corretos (sem mudança visual).
+    &[size="tiny"]   { height: 28px; }
+    &[size="small"]  { height: 32px; }
+    &[size="medium"] { height: 40px; }
+    &[size="large"]  { height: 48px; }
+    &[size="huge"]   { height: 56px; }
+
+    &[size="tiny"][icon]   { padding: var(--matcha-space-075, 6px) !important; }
+    &[size="small"][icon]  { padding: var(--matcha-space-075, 6px) !important; }
+    &[size="medium"][icon] { padding: var(--matcha-space-100, 8px) !important; }
+    &[size="large"][icon]  { padding: var(--matcha-space-150, 12px) !important; }
+    &[size="huge"][icon]   { padding: var(--matcha-space-200, 16px) !important; }
+}
+
+// ── Forced colors (Windows High Contrast) ──
+// Buttons precisam ser claramente acionáveis em high-contrast.
+@media (forced-colors: active) {
+    button[matcha-button],
+    a[matcha-button],
+    button[matcha-icon-button],
+    a[matcha-icon-button] {
+        // Filled: usa botão de sistema (ButtonFace/ButtonText) — afford clicável.
+        background: ButtonFace !important;
+        color: ButtonText !important;
+        border: 1px solid ButtonText !important;
+        box-shadow: none !important;
+
+        // Outline/ghost/alpha/link — bg transparente, border CanvasText.
+        &[outline], &[basic], &[alpha], &[link] {
+            background: transparent !important;
+            border-color: CanvasText !important;
+            color: CanvasText !important;
+        }
+
+        // Disabled — GrayText system token.
+        &[disabled],
+        &.is-disabled {
+            color: GrayText !important;
+            border-color: GrayText !important;
+        }
+
+        &:focus-visible {
+            outline: 2px solid CanvasText !important;
+            outline-offset: 2px;
+        }
+    }
+}
+
+// ── Print ──
+// Buttons hide (interativos, não fazem sentido em papel).
+@media print {
+    button[matcha-button],
+    a[matcha-button],
+    button[matcha-icon-button],
+    a[matcha-icon-button] {
+        display: none !important;
+    }
+}