@inchurch/matcha-theme 21.4.0 → 22.1.0

package/components/matcha-avatar.scss

@@ -1,301 +1,440 @@
-// =============================================================================
-// matcha-avatar.scss — Avatar component (photo, initials, placeholder + status)
-// Aligned with Figma Avatar/Matcha: XS(24) SM(32) MD(40) LG(56) XL(80) 2XL(96)
-// =============================================================================
-
-// ── Structural (outside mixin) ──────────────────────────────────────────────
-
-.matcha-avatar {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  position: relative;
-  // SEM overflow:hidden — o status indicator fica no canto fora do círculo
-  // visível e seria cortado. A <img> com border-radius inherit já se arredonda
-  // sozinha; SVG e Initials ficam dentro dos bounds.
-  border-radius: var(--matcha-radius-pill, 9999px);
-
-  font-weight: var(--matcha-weight-medium, 500);
-  user-select: none;
-  flex-shrink: 0;
-}
-
-// =============================================================================
-// Ring colored (additive) — controlado pelo [ring] @Input do component.
-// 2px solid + halo alpha externo. Não ocupa layout (box-shadow puro).
-//
-// Aplicado no .matcha-avatar INNER (não no host) porque o inner é quem tem
-// width/height/border-radius:pill — box-shadow segue o radius desse elemento
-// e renderiza circular. No host (inline default) sairia retangular.
-// =============================================================================
-matcha-avatar[ring] .matcha-avatar {
-  box-shadow:
-    0 0 0 2px transparent,
-    0 0 0 3px var(--matcha-avatar-ring-color, currentColor);
-}
-
-matcha-avatar[ring]:not([ring="neutral"]) .matcha-avatar {
-  box-shadow:
-    0 0 0 2px transparent,
-    0 0 0 3px var(--matcha-avatar-ring-color, currentColor),
-    0 0 0 5px var(--matcha-avatar-ring-halo, transparent);
-}
-
-// ── Variants (sizes, initials, icon, disabled) — nested em .matcha-avatar pra
-// usar `&.matcha-avatar-*` syntax. Bloco separado do base styles (linha 8-21)
-// porque matcha-avatar[ring] (acima) é regra absoluta, não nested.
-.matcha-avatar {
-  // ── Sizes — Canonical 5-step scale: tiny 24 · small 40 · medium 56 · large 80 · huge 96.
-  // Abbreviations kept as @deprecated aliases, mapped BY PIXEL SIZE (old 32px `sm` dropped → tiny).
-  // NOTE: --matcha-avatar-* tokens still carry the legacy abbreviated names; re-tier them to
-  // tiny/small/medium/large/huge on the Figma/DSV3 side (token rename is design-driven).
-  &.matcha-avatar-tiny,
-  &.matcha-avatar-xs,
-  &.matcha-avatar-sm {
-    width: var(--matcha-avatar-xs, 24px);
-    height: var(--matcha-avatar-xs, 24px);
-    font-size: var(--matcha-text-2xs, 10px);
-    line-height: 1;
-  }
-
-  &.matcha-avatar-small,
-  &.matcha-avatar-md {
-    width: var(--matcha-avatar-md, 40px);
-    height: var(--matcha-avatar-md, 40px);
-    font-size: var(--matcha-text-md, 14px);
-    line-height: 1;
-  }
-
-  &.matcha-avatar-medium,
-  &.matcha-avatar-lg {
-    width: var(--matcha-avatar-lg, 56px);
-    height: var(--matcha-avatar-lg, 56px);
-    font-size: var(--matcha-text-2xl, 20px);
-    line-height: 1;
-  }
-
-  &.matcha-avatar-large,
-  &.matcha-avatar-xl {
-    width: var(--matcha-avatar-xl, 80px);
-    height: var(--matcha-avatar-xl, 80px);
-    font-size: var(--matcha-text-3xl, 24px);
-    line-height: 1;
-  }
-
-  &.matcha-avatar-huge,
-  &.matcha-avatar-2xl {
-    width: var(--matcha-avatar-2xl, 96px);
-    height: var(--matcha-avatar-2xl, 96px);
-    font-size: var(--matcha-text-4xl, 32px);
-    line-height: 1;
-  }
-
-  // ── Image ──
-  .matcha-avatar-image {
-    width: 100%;
-    height: 100%;
-    object-fit: cover;
-    border-radius: inherit;
-  }
-
-  // ── Initials ──
-  .matcha-avatar-initials {
-    font-weight: var(--matcha-weight-medium, 500);
-    text-transform: uppercase;
-    letter-spacing: var(--matcha-letter-spacing-wide, 0.5px);
-  }
-
-  // ── Placeholder icon ──
-  .matcha-avatar-icon {
-    width: 100%;
-    height: 100%;
-  }
-
-  // ── Disabled ──
-  &.matcha-avatar--disabled,
-  &.color-disabled {
-    opacity: var(--matcha-opacity-disabled, 0.38);
-    pointer-events: none;
-  }
-}
-
-// ── Placeholder — vazado canônico (Figma matcha/avatar 5668:32088) ──────────
-// SVG usa fill-rule=evenodd: disco preenchido com currentColor + silhueta vazada.
-// `currentColor` do disco precisa ser a COR DA MARCA (não o contrast da .color class
-// global, que é branco/preto). Override aqui força o token de palette.
-.matcha-avatar.matcha-avatar--placeholder {
-  background: transparent !important;
-
-  &.light-blue { color: var(--matcha-color-palette-light-blue) !important; }
-  &.pink       { color: var(--matcha-color-palette-pink) !important; }
-  &.teal       { color: var(--matcha-color-palette-teal) !important; }
-  &.purple     { color: var(--matcha-color-palette-purple) !important; }
-  &.orange     { color: var(--matcha-color-palette-orange) !important; }
-  &.yellow     { color: var(--matcha-color-palette-yellow) !important; }
-  &.neutral    { color: var(--matcha-color-icon-default) !important; }
-}
-
-// Neutral em Initials — cinza canônico Figma (icon-default).
-.matcha-avatar:not(.matcha-avatar--placeholder).neutral {
-  background: var(--matcha-color-icon-default);
-}
-
-// ── Initials — bg + fg por palette canônica Figma DSV3 (6 cores) ────────────
-// O palette inverte por tema (light=tons saturados, dark=tons claros). text-primary
-// também inverte (#1a1d21 light / #e8eaed dark). Combinar os dois → contraste péssimo
-// em dark mode (1.2-2.9:1 FAIL). Por isso fg é fixed-per-color, não token-based.
-//
-// Light mode: pink/teal/purple bg escuros → fg branco. light-blue/orange/yellow bg
-//             claros → fg preto (light-blue precisa #000 puro pra AA por 0.08).
-// Dark mode:  todos os bg ficam lighter → fg preto funciona em tudo (5-12:1).
-
-.matcha-avatar:not(.matcha-avatar--placeholder) {
-  // Backgrounds (mesmo seletor pros 2 temas — palette token já inverte sozinho).
-  &.light-blue { background: var(--matcha-color-palette-light-blue); }
-  &.pink       { background: var(--matcha-color-palette-pink); }
-  &.teal       { background: var(--matcha-color-palette-teal); }
-  &.purple     { background: var(--matcha-color-palette-purple); }
-  &.orange     { background: var(--matcha-color-palette-orange); }
-  &.yellow     { background: var(--matcha-color-palette-yellow); }
-}
-
-// Light mode — bgs saturados (pink/teal/purple = escuros), fg branco passa AA.
-// orange/yellow/light-blue = claros, fg precisa ser dark (#000 pra light-blue por margem).
-.theme-default-light .matcha-avatar:not(.matcha-avatar--placeholder) {
-  &.light-blue { color: #000; }              // 5.42:1 AA
-  &.pink       { color: #fff; }              // 4.95:1 AA
-  &.teal       { color: #fff; }              // 5.32:1 AA
-  &.purple     { color: #fff; }              // 6.30:1 AA
-  &.orange     { color: #1a1a1a; }           // 4.59:1 AA
-  &.yellow     { color: #1a1a1a; }           // 8.52:1 AAA
-  &.neutral    { color: #fff; }              // icon-default #5f656b vs #fff = 5.18:1 AA
-}
-
-// Dark mode — todos os bgs ficam lighter (#54c5f7, #e46291, #4fb7ad, etc).
-// Texto branco falha em todos. Texto dark funciona em todos.
-.theme-default-dark .matcha-avatar:not(.matcha-avatar--placeholder) {
-  &.light-blue { color: #1a1a1a; }           // 8.87:1 AAA
-  &.pink       { color: #1a1a1a; }           // 5.35:1 AA
-  &.teal       { color: #1a1a1a; }           // 7.22:1 AAA
-  &.purple     { color: #1a1a1a; }           // 4.98:1 AA
-  &.orange     { color: #1a1a1a; }           // 8.58:1 AAA
-  &.yellow     { color: #1a1a1a; }           // 11.94:1 AAA
-  &.neutral    { color: #1a1a1a; }           // icon-default #9aa0a6 vs #1a1a1a = 5.97:1 AA
-}
-
-// ── Screen reader only utility (visualmente oculto, lido por AT) ────────────
-.matcha-avatar-sr-only {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  padding: 0;
-  margin: -1px;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border: 0;
-}
-
-// ── Status indicator ────────────────────────────────────────────────────────
-// Cores estruturais (online/offline/busy) ficam fora do mixin pra renderizar
-// independente de classe de tema (`theme-default-light`, etc.). Tokens com
-// fallback hardcoded resolvem o caso de tema não inicializado.
-
-.matcha-avatar-status {
-  position: absolute;
-  bottom: 0;
-  right: 0;
-  border-radius: var(--matcha-radius-pill, 9999px);
-  border: var(--matcha-border-thin, 2px) solid var(--matcha-color-surface-card, #fff);
-  box-sizing: border-box;
-
-  // Size scales with avatar
-  .matcha-avatar-xs &,
-  .matcha-avatar-tiny & { width: var(--matcha-avatar-status-xs, 8px); height: var(--matcha-avatar-status-xs, 8px); }
-
-  .matcha-avatar-sm &,
-  .matcha-avatar-small & { width: var(--matcha-avatar-status-sm, 10px); height: var(--matcha-avatar-status-sm, 10px); }
-
-  .matcha-avatar-md &,
-  .matcha-avatar-medium & { width: var(--matcha-avatar-status-md, 12px); height: var(--matcha-avatar-status-md, 12px); }
-
-  .matcha-avatar-lg &,
-  .matcha-avatar-large & { width: var(--matcha-avatar-status-lg, 14px); height: var(--matcha-avatar-status-lg, 14px); }
-
-  .matcha-avatar-xl & { width: var(--matcha-avatar-status-xl, 16px); height: var(--matcha-avatar-status-xl, 16px); }
-
-  .matcha-avatar-2xl &,
-  .matcha-avatar-huge & { width: var(--matcha-avatar-status-2xl, 18px); height: var(--matcha-avatar-status-2xl, 18px); }
-
-  // Cores estruturais — fallback hardcoded pra funcionar mesmo sem tema.
-  &.matcha-avatar-status--online  { background-color: var(--matcha-color-success, #16a34a); }
-  &.matcha-avatar-status--offline { background-color: var(--matcha-color-text-placeholder, #9ca3af); }
-  &.matcha-avatar-status--busy    { background-color: var(--matcha-color-danger, #dc2626); }
-}
-
-// ── Theme mixin ─────────────────────────────────────────────────────────────
-
-@mixin matcha-avatar-theme($theme) {
-  .matcha-avatar {
-    // Placeholder: SVG usa fill="currentColor" e herda do host. A classe de
-    // cor (.blue/.orange/etc) define color=foreground + background=cor cheia,
-    // então o icon vazado fica visível na cor escolhida pelo usuário.
-    // Sem fallback hardcoded aqui — quando o user não passa color, o @Input
-    // default 'blue' resolve via .blue do matcha-style.css.
-
-    &.matcha-avatar--disabled,
-    &.color-disabled {
-      background-color: var(--matcha-color-disabled-bg);
-      color: var(--matcha-color-disabled-fg);
-    }
-  }
-
-  // Status border-color por tema (estrutural já resolve cores de fundo via tokens).
-  .matcha-avatar-status {
-    border-color: var(--matcha-color-surface-card);
-  }
-}
-
-// =============================================================================
-// A11y / modernity media queries
-// =============================================================================
-
-// Forced colors (Windows High Contrast) — bg colors podem virar invisíveis,
-// usar SelectedItem/Highlight pros estados, CanvasText/Canvas pra borders.
-@media (forced-colors: active) {
-  .matcha-avatar {
-    border: 1px solid CanvasText;
-
-    &.matcha-avatar--disabled,
-    &.color-disabled {
-      opacity: 0.5;
-      border-color: GrayText;
-    }
-  }
-
-  // Status dot — em high-contrast as 3 cores ficam idênticas. Compensamos
-  // com pattern visual: online=fill, offline=outline, busy=outline duplo.
-  .matcha-avatar-status {
-    background: SelectedItem !important;
-    border: 2px solid Canvas !important;
-
-    &.matcha-avatar-status--offline {
-      background: Canvas !important;
-      border: 2px solid CanvasText !important;
-    }
-
-    &.matcha-avatar-status--busy {
-      background: SelectedItem !important;
-      box-shadow: 0 0 0 2px Canvas, 0 0 0 4px CanvasText;
-    }
-  }
-}
-
-// Reduced motion — mata todas transitions/animations.
-@media (prefers-reduced-motion: reduce) {
-  .matcha-avatar,
-  .matcha-avatar-status {
-    transition: none !important;
-    animation: none !important;
-  }
-}
+// =============================================================================
+// matcha-avatar.scss — Avatar component (photo, initials, placeholder + status)
+// Aligned with Figma Avatar/Matcha: XS(24) SM(32) MD(40) LG(56) XL(80) 2XL(96)
+// =============================================================================
+
+// ── Structural (outside mixin) ──────────────────────────────────────────────
+
+.matcha-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  // SEM overflow:hidden — o status indicator fica no canto fora do círculo
+  // visível e seria cortado. A <img> com border-radius inherit já se arredonda
+  // sozinha; SVG e Initials ficam dentro dos bounds.
+  border-radius: var(--matcha-radius-pill, 9999px);
+
+  font-weight: var(--matcha-weight-medium, 500);
+  user-select: none;
+  flex-shrink: 0;
+}
+
+// =============================================================================
+// Ring colored (additive) — controlado pelo [ring] @Input do component.
+// 2px solid + halo alpha externo. Não ocupa layout (box-shadow puro).
+//
+// Aplicado no .matcha-avatar INNER (não no host) porque o inner é quem tem
+// width/height/border-radius:pill — box-shadow segue o radius desse elemento
+// e renderiza circular. No host (inline default) sairia retangular.
+// =============================================================================
+matcha-avatar[ring] .matcha-avatar {
+  box-shadow:
+    0 0 0 2px transparent,
+    0 0 0 3px var(--matcha-avatar-ring-color, currentColor);
+}
+
+matcha-avatar[ring]:not([ring="neutral"]) .matcha-avatar {
+  box-shadow:
+    0 0 0 2px transparent,
+    0 0 0 3px var(--matcha-avatar-ring-color, currentColor),
+    0 0 0 5px var(--matcha-avatar-ring-halo, transparent);
+}
+
+// ── Variants (sizes, initials, icon, disabled) — nested em .matcha-avatar pra
+// usar `&.matcha-avatar-*` syntax. Bloco separado do base styles (linha 8-21)
+// porque matcha-avatar[ring] (acima) é regra absoluta, não nested.
+.matcha-avatar {
+  // ── Sizes — Canonical 5-step scale: tiny 24 · small 40 · medium 56 · large 80 · huge 96.
+  // Abbreviations kept as @deprecated aliases, mapped BY PIXEL SIZE (old 32px `sm` dropped → tiny).
+  // NOTE: --matcha-avatar-* tokens still carry the legacy abbreviated names; re-tier them to
+  // tiny/small/medium/large/huge on the Figma/DSV3 side (token rename is design-driven).
+  &.matcha-avatar-tiny,
+  &.matcha-avatar-xs,
+  &.matcha-avatar-sm {
+    width: var(--matcha-avatar-xs, 24px);
+    height: var(--matcha-avatar-xs, 24px);
+    font-size: var(--matcha-text-2xs, 10px);
+    line-height: 1;
+  }
+
+  &.matcha-avatar-small,
+  &.matcha-avatar-md {
+    width: var(--matcha-avatar-md, 40px);
+    height: var(--matcha-avatar-md, 40px);
+    font-size: var(--matcha-text-md, 14px);
+    line-height: 1;
+  }
+
+  &.matcha-avatar-medium,
+  &.matcha-avatar-lg {
+    width: var(--matcha-avatar-lg, 56px);
+    height: var(--matcha-avatar-lg, 56px);
+    font-size: var(--matcha-text-2xl, 20px);
+    line-height: 1;
+  }
+
+  &.matcha-avatar-large,
+  &.matcha-avatar-xl {
+    width: var(--matcha-avatar-xl, 80px);
+    height: var(--matcha-avatar-xl, 80px);
+    font-size: var(--matcha-text-3xl, 24px);
+    line-height: 1;
+  }
+
+  &.matcha-avatar-huge,
+  &.matcha-avatar-2xl {
+    width: var(--matcha-avatar-2xl, 96px);
+    height: var(--matcha-avatar-2xl, 96px);
+    font-size: var(--matcha-text-4xl, 32px);
+    line-height: 1;
+  }
+
+  // ── Image ──
+  .matcha-avatar-image {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    border-radius: inherit;
+  }
+
+  // ── Initials ──
+  .matcha-avatar-initials {
+    font-weight: var(--matcha-weight-medium, 500);
+    text-transform: uppercase;
+    letter-spacing: var(--matcha-letter-spacing-wide, 0.5px);
+  }
+
+  // ── Placeholder icon ──
+  .matcha-avatar-icon {
+    width: 100%;
+    height: 100%;
+  }
+
+  // ── Disabled ──
+  &.matcha-avatar--disabled,
+  &.color-disabled {
+    opacity: var(--matcha-opacity-disabled, 0.38);
+    pointer-events: none;
+  }
+}
+
+// ── Placeholder — vazado canônico (Figma matcha/avatar 5668:32088) ──────────
+// SVG usa fill-rule=evenodd: disco preenchido com currentColor + silhueta vazada.
+// `currentColor` do disco precisa ser a COR DA MARCA (não o contrast da .color class
+// global, que é branco/preto). Override aqui força o token de palette.
+.matcha-avatar.matcha-avatar--placeholder {
+  background: transparent !important;
+
+  &.light-blue { color: var(--matcha-color-palette-light-blue) !important; }
+  &.pink       { color: var(--matcha-color-palette-pink) !important; }
+  &.teal       { color: var(--matcha-color-palette-teal) !important; }
+  &.purple     { color: var(--matcha-color-palette-purple) !important; }
+  &.orange     { color: var(--matcha-color-palette-orange) !important; }
+  &.yellow     { color: var(--matcha-color-palette-yellow) !important; }
+  &.neutral    { color: var(--matcha-color-icon-default) !important; }
+}
+
+// Neutral em Initials — cinza canônico Figma (icon-default).
+.matcha-avatar:not(.matcha-avatar--placeholder).neutral {
+  background: var(--matcha-color-icon-default);
+}
+
+// ── Initials — bg + fg por palette canônica Figma DSV3 (6 cores) ────────────
+// O palette inverte por tema (light=tons saturados, dark=tons claros). text-primary
+// também inverte (#1a1d21 light / #e8eaed dark). Combinar os dois → contraste péssimo
+// em dark mode (1.2-2.9:1 FAIL). Por isso fg é fixed-per-color, não token-based.
+//
+// Light mode: pink/teal/purple bg escuros → fg branco. light-blue/orange/yellow bg
+//             claros → fg preto (light-blue precisa #000 puro pra AA por 0.08).
+// Dark mode:  todos os bg ficam lighter → fg preto funciona em tudo (5-12:1).
+
+.matcha-avatar:not(.matcha-avatar--placeholder) {
+  // Backgrounds (mesmo seletor pros 2 temas — palette token já inverte sozinho).
+  &.light-blue { background: var(--matcha-color-palette-light-blue); }
+  &.pink       { background: var(--matcha-color-palette-pink); }
+  &.teal       { background: var(--matcha-color-palette-teal); }
+  &.purple     { background: var(--matcha-color-palette-purple); }
+  &.orange     { background: var(--matcha-color-palette-orange); }
+  &.yellow     { background: var(--matcha-color-palette-yellow); }
+}
+
+// Light mode — bgs saturados (pink/teal/purple = escuros), fg branco passa AA.
+// orange/yellow/light-blue = claros, fg precisa ser dark (#000 pra light-blue por margem).
+.theme-default-light .matcha-avatar:not(.matcha-avatar--placeholder) {
+  &.light-blue { color: #000; }              // 5.42:1 AA
+  &.pink       { color: #fff; }              // 4.95:1 AA
+  &.teal       { color: #fff; }              // 5.32:1 AA
+  &.purple     { color: #fff; }              // 6.30:1 AA
+  &.orange     { color: #1a1a1a; }           // 4.59:1 AA
+  &.yellow     { color: #1a1a1a; }           // 8.52:1 AAA
+  &.neutral    { color: #fff; }              // icon-default #5f656b vs #fff = 5.18:1 AA
+}
+
+// Dark mode — todos os bgs ficam lighter (#54c5f7, #e46291, #4fb7ad, etc).
+// Texto branco falha em todos. Texto dark funciona em todos.
+.theme-default-dark .matcha-avatar:not(.matcha-avatar--placeholder) {
+  &.light-blue { color: #1a1a1a; }           // 8.87:1 AAA
+  &.pink       { color: #1a1a1a; }           // 5.35:1 AA
+  &.teal       { color: #1a1a1a; }           // 7.22:1 AAA
+  &.purple     { color: #1a1a1a; }           // 4.98:1 AA
+  &.orange     { color: #1a1a1a; }           // 8.58:1 AAA
+  &.yellow     { color: #1a1a1a; }           // 11.94:1 AAA
+  &.neutral    { color: #1a1a1a; }           // icon-default #9aa0a6 vs #1a1a1a = 5.97:1 AA
+}
+
+// ── Avatar Group — empilhamento horizontal com overlap + overflow "+N" ──────
+// Substitui a composição manual (SCSS local) feita nas telas. -10px de overlap
+// é um offset visual bespoke (não genérico) — mantido literal de propósito.
+.matcha-avatar-group {
+  display: inline-flex;
+  align-items: center;
+
+  matcha-avatar {
+    margin-left: -10px;
+    border: var(--matcha-border-thin, 2px) solid var(--matcha-color-surface-card);
+    border-radius: var(--matcha-radius-pill, 9999px);
+
+    &:first-child {
+      margin-left: 0;
+    }
+  }
+
+  &__more {
+    margin-left: var(--matcha-space-100, 8px);
+    font-size: var(--matcha-text-sm, 12px);
+    font-weight: var(--matcha-weight-semibold, 600);
+    color: var(--matcha-color-text-secondary);
+  }
+}
+
+// ── Screen reader only utility (visualmente oculto, lido por AT) ────────────
+.matcha-avatar-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+// ── Status indicator ────────────────────────────────────────────────────────
+// Cores estruturais (online/offline/busy) ficam fora do mixin pra renderizar
+// independente de classe de tema (`theme-default-light`, etc.). Tokens com
+// fallback hardcoded resolvem o caso de tema não inicializado.
+
+.matcha-avatar-status {
+  position: absolute;
+  bottom: 0;
+  right: 0;
+  border-radius: var(--matcha-radius-pill, 9999px);
+  border: var(--matcha-border-thin, 2px) solid var(--matcha-color-surface-card, #fff);
+  box-sizing: border-box;
+
+  // Size scales with avatar
+  .matcha-avatar-xs &,
+  .matcha-avatar-tiny & { width: var(--matcha-avatar-status-xs, 8px); height: var(--matcha-avatar-status-xs, 8px); }
+
+  .matcha-avatar-sm &,
+  .matcha-avatar-small & { width: var(--matcha-avatar-status-sm, 10px); height: var(--matcha-avatar-status-sm, 10px); }
+
+  .matcha-avatar-md &,
+  .matcha-avatar-medium & { width: var(--matcha-avatar-status-md, 12px); height: var(--matcha-avatar-status-md, 12px); }
+
+  .matcha-avatar-lg &,
+  .matcha-avatar-large & { width: var(--matcha-avatar-status-lg, 14px); height: var(--matcha-avatar-status-lg, 14px); }
+
+  .matcha-avatar-xl & { width: var(--matcha-avatar-status-xl, 16px); height: var(--matcha-avatar-status-xl, 16px); }
+
+  .matcha-avatar-2xl &,
+  .matcha-avatar-huge & { width: var(--matcha-avatar-status-2xl, 18px); height: var(--matcha-avatar-status-2xl, 18px); }
+
+  // Cores estruturais — fallback hardcoded pra funcionar mesmo sem tema.
+  &.matcha-avatar-status--online  { background-color: var(--matcha-color-success, #16a34a); }
+  &.matcha-avatar-status--offline { background-color: var(--matcha-color-text-placeholder, #9ca3af); }
+  &.matcha-avatar-status--busy    { background-color: var(--matcha-color-danger, #dc2626); }
+}
+
+// ── "Nome ao lado" (showName) ───────────────────────────────────────────────
+// Root: `display: contents` por padrão — transparente no layout, idêntico a
+// hoje (só a bolinha conta como box). Vira inline-flex (bolinha + texto lado
+// a lado) só quando showTextStack (showName + hasName) — ver component.
+.matcha-avatar-root {
+  display: contents;
+
+  &--inline {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--matcha-space-100, 8px);
+    min-width: 0;
+  }
+
+  // Stacked (hero/profile header) — bolinha + texto empilhados, centralizados.
+  // Substitui a composição manual <header><matcha-avatar/><h1/><p/></header>.
+  &--stacked {
+    display: inline-flex;
+    flex-direction: column;
+    align-items: center;
+    text-align: center;
+    gap: var(--matcha-space-100, 8px);
+  }
+}
+
+.matcha-avatar-text {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+
+  &__primary {
+    color: var(--matcha-color-text-primary);
+    font-weight: var(--matcha-weight-medium, 500);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__caption {
+    color: var(--matcha-color-text-muted);
+    font-weight: var(--matcha-weight-regular, 400);
+    font-variant-numeric: tabular-nums;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+}
+
+// Equilíbrio tipográfico por tamanho do avatar — seletor de irmão contra as
+// classes de tamanho já existentes na bolinha (`.matcha-avatar-<size>`), sem
+// duplicar a classe de tamanho no host. 5 tiers, escala proporcional ao avatar.
+.matcha-avatar-tiny ~ .matcha-avatar-text,
+.matcha-avatar-xs ~ .matcha-avatar-text {
+  .matcha-avatar-text__primary { font-size: var(--matcha-text-sm, 12px); line-height: var(--matcha-leading-sm, 16px); }
+  .matcha-avatar-text__caption { font-size: var(--matcha-text-xs, 11px); line-height: var(--matcha-leading-xs, 14px); }
+}
+
+.matcha-avatar-small ~ .matcha-avatar-text,
+.matcha-avatar-md ~ .matcha-avatar-text {
+  .matcha-avatar-text__primary { font-size: var(--matcha-text-md, 14px); line-height: var(--matcha-leading-md, 20px); }
+  .matcha-avatar-text__caption { font-size: var(--matcha-text-sm, 12px); line-height: var(--matcha-leading-sm, 16px); }
+}
+
+.matcha-avatar-medium ~ .matcha-avatar-text,
+.matcha-avatar-lg ~ .matcha-avatar-text {
+  .matcha-avatar-text__primary { font-size: var(--matcha-text-lg, 16px); line-height: var(--matcha-leading-lg, 24px); }
+  .matcha-avatar-text__caption { font-size: var(--matcha-text-md, 14px); line-height: var(--matcha-leading-md, 20px); }
+}
+
+.matcha-avatar-large ~ .matcha-avatar-text,
+.matcha-avatar-xl ~ .matcha-avatar-text {
+  .matcha-avatar-text__primary { font-size: var(--matcha-text-xl, 18px); line-height: var(--matcha-leading-xl, 24px); }
+  .matcha-avatar-text__caption { font-size: var(--matcha-text-lg, 16px); line-height: var(--matcha-leading-lg, 24px); }
+}
+
+.matcha-avatar-huge ~ .matcha-avatar-text,
+.matcha-avatar-2xl ~ .matcha-avatar-text {
+  .matcha-avatar-text__primary { font-size: var(--matcha-text-title-lg, 20px); line-height: var(--matcha-leading-title-lg, 28px); }
+  .matcha-avatar-text__caption { font-size: var(--matcha-text-xl, 18px); line-height: var(--matcha-leading-xl, 24px); }
+}
+
+// ── Stacked (hero/profile header) — tipografia maior, negrito, centralizada.
+// Classe composta (.matcha-avatar-text.matcha-avatar-text--stacked) tem mais
+// especificidade que a escada inline acima — sobrescreve sem depender de ordem.
+.matcha-avatar-tiny ~ .matcha-avatar-text.matcha-avatar-text--stacked,
+.matcha-avatar-xs ~ .matcha-avatar-text.matcha-avatar-text--stacked {
+  .matcha-avatar-text__primary { font-size: var(--matcha-text-title-sm, 16px); font-weight: var(--matcha-weight-bold, 700); line-height: var(--matcha-leading-title-sm, 22px); }
+  .matcha-avatar-text__caption { font-size: var(--matcha-text-sm, 12px); line-height: var(--matcha-leading-sm, 16px); }
+}
+
+.matcha-avatar-small ~ .matcha-avatar-text.matcha-avatar-text--stacked,
+.matcha-avatar-md ~ .matcha-avatar-text.matcha-avatar-text--stacked {
+  .matcha-avatar-text__primary { font-size: var(--matcha-text-title-sm, 16px); font-weight: var(--matcha-weight-bold, 700); line-height: var(--matcha-leading-title-sm, 22px); }
+  .matcha-avatar-text__caption { font-size: var(--matcha-text-sm, 12px); line-height: var(--matcha-leading-sm, 16px); }
+}
+
+.matcha-avatar-medium ~ .matcha-avatar-text.matcha-avatar-text--stacked,
+.matcha-avatar-lg ~ .matcha-avatar-text.matcha-avatar-text--stacked {
+  .matcha-avatar-text__primary { font-size: var(--matcha-text-title-md, 18px); font-weight: var(--matcha-weight-bold, 700); line-height: var(--matcha-leading-title-md, 24px); }
+  .matcha-avatar-text__caption { font-size: var(--matcha-text-md, 14px); line-height: var(--matcha-leading-md, 20px); }
+}
+
+.matcha-avatar-large ~ .matcha-avatar-text.matcha-avatar-text--stacked,
+.matcha-avatar-xl ~ .matcha-avatar-text.matcha-avatar-text--stacked {
+  .matcha-avatar-text__primary { font-size: var(--matcha-text-title-md, 18px); font-weight: var(--matcha-weight-bold, 700); line-height: var(--matcha-leading-title-md, 24px); }
+  .matcha-avatar-text__caption { font-size: var(--matcha-text-md, 14px); line-height: var(--matcha-leading-md, 20px); }
+}
+
+.matcha-avatar-huge ~ .matcha-avatar-text.matcha-avatar-text--stacked,
+.matcha-avatar-2xl ~ .matcha-avatar-text.matcha-avatar-text--stacked {
+  .matcha-avatar-text__primary { font-size: var(--matcha-text-title-lg, 20px); font-weight: var(--matcha-weight-bold, 700); line-height: var(--matcha-leading-title-lg, 28px); }
+  .matcha-avatar-text__caption { font-size: var(--matcha-text-lg, 16px); line-height: var(--matcha-leading-lg, 24px); }
+}
+
+// ── Theme mixin ─────────────────────────────────────────────────────────────
+
+@mixin matcha-avatar-theme($theme) {
+  .matcha-avatar {
+    // Placeholder: SVG usa fill="currentColor" e herda do host. A classe de
+    // cor (.blue/.orange/etc) define color=foreground + background=cor cheia,
+    // então o icon vazado fica visível na cor escolhida pelo usuário.
+    // Sem fallback hardcoded aqui — quando o user não passa color, o @Input
+    // default 'blue' resolve via .blue do matcha-style.css.
+
+    &.matcha-avatar--disabled,
+    &.color-disabled {
+      background-color: var(--matcha-color-disabled-bg);
+      color: var(--matcha-color-disabled-fg);
+    }
+  }
+
+  // Status border-color por tema (estrutural já resolve cores de fundo via tokens).
+  .matcha-avatar-status {
+    border-color: var(--matcha-color-surface-card);
+  }
+}
+
+// =============================================================================
+// A11y / modernity media queries
+// =============================================================================
+
+// Forced colors (Windows High Contrast) — bg colors podem virar invisíveis,
+// usar SelectedItem/Highlight pros estados, CanvasText/Canvas pra borders.
+@media (forced-colors: active) {
+  .matcha-avatar {
+    border: 1px solid CanvasText;
+
+    &.matcha-avatar--disabled,
+    &.color-disabled {
+      opacity: 0.5;
+      border-color: GrayText;
+    }
+  }
+
+  // Status dot — em high-contrast as 3 cores ficam idênticas. Compensamos
+  // com pattern visual: online=fill, offline=outline, busy=outline duplo.
+  .matcha-avatar-status {
+    background: SelectedItem !important;
+    border: 2px solid Canvas !important;
+
+    &.matcha-avatar-status--offline {
+      background: Canvas !important;
+      border: 2px solid CanvasText !important;
+    }
+
+    &.matcha-avatar-status--busy {
+      background: SelectedItem !important;
+      box-shadow: 0 0 0 2px Canvas, 0 0 0 4px CanvasText;
+    }
+  }
+}
+
+// Reduced motion — mata todas transitions/animations.
+@media (prefers-reduced-motion: reduce) {
+  .matcha-avatar,
+  .matcha-avatar-status {
+    transition: none !important;
+    animation: none !important;
+  }
+}