Spec — Themes: Materials

Facet Visual do Koder Design. Material parity: https://learn.microsoft.com/windows/apps/design/style/acrylic

• https://learn.microsoft.com/windows/apps/design/style/mica.

R1 — Material vocabulary

Koder ships 2 materials, both opt-in (default surfaces stay opaque per verge.kmd):

Other materials (smoke, tinted glass, frosted) are not in the canonical vocabulary. PR to add new ones requires Koder Brand approval

• accessibility audit.

R2 — Opacity + blur defaults

R3 — Fallback contract

Browsers/compositors without backdrop-filter:

.kds-material-acrylic {
  background: var(--kds-material-acrylic-bg);  /* opaque fallback */
}
@supports (backdrop-filter: blur(1px)) {
  .kds-material-acrylic {
    backdrop-filter: blur(var(--kds-material-acrylic-blur))
                     saturate(var(--kds-material-acrylic-saturation));
  }
}

Result: every surface always paints; only the live blur is conditional.

R4 — Platform binding (koder_kit)

Flutter desktop variants of koder_kit expose:

• KoderMicaWindow — root scaffold widget mapping to platform-native window backdrop API (WinUI 3 SystemBackdrop.MICA on Windows; NSVisualEffectView via plugin on macOS; opaque tint on Linux until KWin/Mutter ships compositor blur reliably).
• KoderAcrylicSurface — floating surface widget. Same fallback chain.

Web/Flutter Web uses the CSS path above directly.

R5 — When NOT to use

• App body content — use plain --kdr-surface. Acrylic on content reduces contrast and breaks accessibility.
• Mobile — Koder mobile apps use flat opaque surfaces per koder-app/behaviors.kmd. Backdrop-blur is a battery hog on mid-range Android; the spec excludes it.
• TVs — Tizen/WebOS rendering pipeline doesn't blur well; opaque surfaces stay the default.

R6 — "Glass" is Acrylic (XR reconciliation)

The XR spec (xr-preview.kmd § R3) defines --kds-xr-glass-blur and --kds-xr-glass-opacity for floating spatial panels. These are the spatial projection of Acrylic — not a third material. "Glass" is a colloquial alias for the Acrylic material, the same way XR depth is a projection of the 2D depth axis (depth.kmd).

Canonical mapping (XR renderers derive, never redefine):

Consequence: a flyout on the web and a floating panel in XR read as the same material, lit by the same rig.

A distinct named "Glass" material (frosted / tinted) is out of vocabulary per R1 and would require Koder Brand approval + accessibility audit before it could ship — tracked, not assumed.

prefers-reduced-transparency: reduce collapses Acrylic (and therefore XR glass) to its opaque fallback (R3) — translucency is never the sole carrier of meaning.

T1-T4 — Tests

T1 — Token presence: every theme produces --kds-material-mica-bg and --kds-material-acrylic-bg resolvable to a valid color value.

T2 — Fallback: with backdrop-filter disabled, .kds-material-acrylic still renders an opaque-but-tinted surface (no transparent gap).

T3 — Verge audit: koder-spec-audit verge --material confirms no canonical preset overrides the material tokens with a hard-coded color.

T4 — XR mapping: --kds-xr-glass-* tokens resolve to the Acrylic values in R6 (blur/opacity/saturation equal within rounding); no theme defines XR glass independently of Acrylic.