Spec — Typography

Facet Visual do Koder Design. Material parity: https://m3.material.io/styles/typography/fonts.

Two font families

Both ship with font-display: swap per #015 so the system fallback shows immediately; webfont swaps in without FOIT.

System fallback stack (browser/OS):

font-family: 'Inter', system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
font-family: 'JetBrains Mono', ui-monospace, "SF Mono", Menlo, Consolas, monospace;

Per-preset overrides via ui-style.kmd (e.g., terminal_classic uses JetBrains Mono for everything; gnome uses Cantarell first).

R1 — Type scale (15 roles)

Aligned with Material 3 type scale. Pixel sizes are dp (density- independent); browsers map 1:1 to CSS px below high-DPI.

R2 — Role binding contract

Every text node binds to a role, not a raw size:

// ❌
Text("Welcome", style: TextStyle(fontSize: 28, fontWeight: FontWeight.w600))

// ✅
Text("Welcome", style: KoderType.of(context).headlineMedium)

The theme exposes KoderType (planned in koder_kit) with 15 getters matching the role names above. Widget code never references px sizes.

R3 — Role usage guide

R4 — Per-class scale step (responsive)

Per window-size-classes.kmd, type adjusts per class:

"step" = next role up/down in the scale (e.g., headline-large -1 becomes headline-medium).

R5 — Color binding

Type color comes from color-roles.kmd:

Never use error red for non-error body text.

R6 — Multilingual / i18n considerations

Inter ships only Latin subset. For other scripts:

• pt-BR: covered by Latin
• East Asian (CJK): falls back to system "Noto Sans CJK" via font-family chain
• Arabic / RTL: falls back to system Arabic; layout flips via dir="rtl" per i18n/contract.kmd
• Devanagari, etc.: system fallback

When shipping a non-Latin locale officially, vendor the corresponding Noto Sans subset (~50 KB each) alongside Inter.

R7 — Accessibility

• Minimum body text size: 14 px (body-medium)
• Minimum touch-target text size: 12 px with line-height ≥ 1.4
• Line length: target 45-75 characters per line for body text
• Contrast: per color-roles.kmd R4 (AAA on text/bg)
• prefers-reduced-motion does NOT affect type
• Bold/italic combine with role, not replace: body-medium-bold is a STATE on body-medium, not a separate role

R8 — Code typography

Inline <code>:

• Font: JetBrains Mono
• Size: matches surrounding body role
• Background: surface-variant token
• Padding: 2px 6px
• Border-radius: radius-sm (4-6px depending on preset)

Block <pre><code>:

• Font: JetBrains Mono
• Size: 14 px (smaller than body to fit more lines)
• Background: bg-inset token
• Padding: 16-20 px depending on preset
• Border-radius: radius-md
• Overflow: scroll horizontal; never wrap

Syntax highlighting tokens come from themes/color-schemes.kmd Vocabulário de syntax (syntax_keyword, syntax_string, etc.).

R9 — Emphasized scale (Material 3 Expressive)

Material 3 Expressive ratifies a parallel 15-role emphasized scale: same role names as R1, with heavier weight and subtle tracking/leading adjustments. The emphasized scale exists alongside R1 (it does NOT replace it) and is opted into per-text-node when visual hierarchy needs more punch than weight-bump-within-role can provide.

R9.1 — Emphasized tokens

Weight deltas use variable-font axes when available (preferred); discrete weights when not.

R9.2 — Variable-font axes (preferred)

When the active font is variable (Inter VF, JetBrains Mono VF), emphasized prefers axes over weight family swap:

Variable axes preserve x-height and metrics, preventing layout shift when toggling baseline↔emphasized at runtime.

R9.3 — Decision tree: when to use emphasized

Is this the SINGLE most important text on the screen?
├── YES, and it's a hero context (landing, splash)
│       → display-*-emphasized
├── YES, and it's an app context (page title, primary CTA)
│       → headline/title/label *-emphasized
└── NO  → does the section need visual lift above body?
          ├── YES (featured article lede, key paragraph)
          │       → body-*-emphasized (use sparingly: max 1 paragraph per screen)
          └── NO → use R1 baseline

Anti-pattern: every other text emphasized. Emphasized loses meaning when overused. Rule of thumb: at most 1 emphasized role per visual unit (card, section, dialog).

R9.4 — Accessibility

Emphasized does NOT replace semantic HTML/ARIA. A body-large- emphasized is still <p>, not <h2>. Screen readers MUST receive the same announcement as the baseline counterpart.

Emphasized text MUST still meet AAA contrast per R5/color-roles.kmd R4. Heavier weight does not loosen contrast requirements.

R9.5 — Surface bindings

Surfaces MUST expose all 15 emphasized roles or none — partial implementation is a contract violation.

R9.6 — Per-preset variation

Cross-link

• themes/color-schemes.kmd — syntax + body color tokens
• themes/color-roles.kmd — text color roles
• themes/ui-style.kmd — per-preset font stack
• i18n/contract.kmd — locale-aware font loading
• foundations/elements.kmd — content family uses type tokens