feat: update font scale

[FBalint]

Font scale refresh

Body baseline moves 14px → 13px. text-sm was the de-facto default across the library and downstream usage; renaming so the most-used size is called base. New scale: text-xs/sm/base/lg/xl/2xl = 11/12/13/15/19/24px.

--font-scale CSS multiplier. For products that want a user-facing "bigger text" preference:

• Browser zoom scales the viewport (layout grows too).
• Native browser font-size prefs would work if the library used rem only for font-size. It doesn't — Tailwind emits rem for spacing (padding, margin, gap), so those scale too.
• --font-scale multiplies only font-size tokens. Every font-size is emitted as calc(<px> * var(--font-scale, 1)). Consumers override at any scope; spacing stays put.

Full separation of type and layout scaling requires a rem-for-font / px-for-spacing convention shift. Out of scope here; this PR lands the infrastructure.

Em-relative icon sizing. Icons across ~20 components moved from hardcoded pixels (size={12}, h-4 w-4) to em ratios, following Apple's font scaling pattern — a UI icon is a glyph in its text's context and scales with the surrounding font-size. This:

• collapses per-component-per-variant size tables into a single ratio rule,
• makes icons respond to --font-scale automatically.

Ratios in use:

Ratio	Where
1em (bare)	Carets / chevrons in form controls, buttons, pagination
0.85em	Inline glyphs in chips, badges, checkboxes
1.15em	Leading icons in dropdown / menu items
1.25em	Sidebar menu icons
var(--text-lg)	Nested-scope one-offs

What's in it

• Body baseline 13px. Scale = 11/12/13/15/19/24px.
• Role-based Text variants: display (24px semibold), page-title (19px medium), section-title (15px medium), heading (13px medium). heading1/2/3 soft-deprecated.
• Text.size="xs" and size="lg" on body variants soft-deprecated. bold narrowed to copy variants only.
• Button + form controls: sm = 26px / text-sm, base = 32px / text-base, lg = 36px / text-base. xs deprecated across all of them.
• Em-relative icon sizing across ~20 components.
• --font-scale multiplier on every font-size token.
• Line-height ratios re-tuned (sm/base/lg = 1.35/1.4/1.45) so dense components keep their dense feel.
• Cascading token updates in Banner, Toolbar, Label, Toast, Table, Collapsible, Sidebar, TableOfContents, Badge, LayerCard.

Changesets

14 changesets. Aggregated bump: minor.

Changeset	Bump	What
text-role-based-variants	minor	Role-based heading variants + Text deprecations
button-sizes-refresh	minor	Button heights/fonts + xs deprecation
form-controls-size-refresh	minor	Input, InputArea, Select, Combobox, Autocomplete, InputGroup
banner-typography-weight-first	minor	Banner title/description weight-first refactor
font-scale-multiplier	minor	--font-scale CSS var
icons-em-relative-sizing	minor	Em-based icon sizing across ~20 components
token-refresh-class-swaps	minor	Badge / Sidebar / TableOfContents token renames, no rendered change
line-height-ratios-tighten	patch	sm / base / lg line-height ratios tightened
toolbar-deprecate-xs	patch	Toolbar xs deprecation with single-warning remap
banner-action-sm-size	patch	Banner.Action size narrowed to "sm"
collapsible-trigger-text-base	patch	Collapsible caret shrinks 16→14px
label-tooltip-button-sm	patch	Label help button xs → sm
table-header-weight	patch	Table th semibold → medium; compact header xs → sm
toast-typography-role-based	patch	Toast at 15px

⚠️ Known breakage: Figma generation

Figma plugin is out of sync with the library. Sources:

• CSS parser (packages/kumo-figma/src/build-theme-data.ts) — updated to handle the new calc(<px> * var(--font-scale, 1)) wrapper. Working.
• KUMO_*_STYLING metadata — updated for control-size changes but KUMO_TEXT_STYLING.fontSizes.xl still reads 17, needs 19.
• Em-relative icons — no Figma equivalent; generators still expect absolute pixel sizes.
• Figma generators — hardcoded font sizes / control heights / snapshot fixtures not resynced.

pnpm --filter @cloudflare/kumo-figma test fails with 22 tests across tailwind-to-figma, drift-detection, and generator snapshots. Build still succeeds.

Testing

• 1250 kumo unit tests pass.
• pnpm typecheck clean.
• pnpm lint clean.
• Docs FontScaleToggle manually exercised.
• Figma plugin tests fail — see above.

---

• Reviews
  • bonk has reviewed the change
  • automated review not possible because: draft for downstream-app preview; will request review after real-world trial
• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:

[pkg-pr-new]

npm i https://pkg.pr.new/@cloudflare/kumo@682

commit: c8c7c3b

[github-actions]

Docs Preview

View docs preview

Commit: c8c7c3b

[github-actions]

Visual Regression Report — 43 changed, 0 unchanged

43 screenshot(s) with visual changes:

Button / Basic

621 px (0.7%) changed

Before	After	Diff

Button / Variant: Primary

891 px (1.01%) changed

Before	After	Diff

Button / Variant: Secondary

646 px (0.73%) changed

Before	After	Diff

Button / Variant: Ghost

115 px (0.13%) changed

Before	After	Diff

Button / Variant: Destructive

1,226 px (1.38%) changed

Before	After	Diff

Button / Variant: Outline

351 px (0.4%) changed

Before	After	Diff

Button / Variant: Secondary Destructive

1,130 px (1.28%) changed

Before	After	Diff

Button / Sizes

1,309 px (1.48%) changed

Before	After	Diff

Button / With Icon

889 px (1%) changed

Before	After	Diff

Button / Icon Only

212 px (0.24%) changed

Before	After	Diff

Button / Loading State

1,025 px (1.16%) changed

Before	After	Diff

Button / Disabled State

178 px (0.2%) changed

Before	After	Diff

Button / Title

1,236 px (1.4%) changed

Before	After	Diff

Button / Link as Button

1,246 px (1.41%) changed

Before	After	Diff

Button / Link with Tooltip

799 px (0.9%) changed

Before	After	Diff

Button / Disabled Link

816 px (0.92%) changed

Before	After	Diff

Dialog / Dialog With Actions

369 px (0.42%) changed

Before	After	Diff

Dialog / Dialog Basic

461 px (0.52%) changed

Before	After	Diff

Dialog / Dialog Sizes

3,326 px (3.76%) changed

Before	After	Diff

Dialog / Dialog Alert

1,596 px (1.8%) changed

Before	After	Diff

Dialog / Dialog Confirmation

1,452 px (1.64%) changed

Before	After	Diff

Dialog / Custom Max Width

1,034 px (1.17%) changed

Before	After	Diff

Dialog / Dialog With Select

568 px (0.64%) changed

Before	After	Diff

Dialog / Dialog With Combobox

612 px (0.69%) changed

Before	After	Diff

Dialog / Dialog With Dropdown

568 px (0.64%) changed

Before	After	Diff

Dialog (Open)

1,838,050 px (7.54%) changed

Before	After	Diff

Select / Select Basic

956 px (1.08%) changed

Before	After	Diff

Select / Select Sizes

34,434 px (21.21%) changed

Before	After	Diff

Select / Select Without Label

733 px (0.83%) changed

Before	After	Diff

Select / Select With Description

8,360 px (8.03%) changed

Before	After	Diff

Select / Select With Error

8,050 px (7.74%) changed

Before	After	Diff

Select / Select Placeholder

1,118 px (1.26%) changed

Before	After	Diff

Select / Select With Tooltip

792 px (0.89%) changed

Before	After	Diff

Select / Select Custom Rendering

1,118 px (1.26%) changed

Before	After	Diff

Select / Select Loading

13,698 px (7.77%) changed

Before	After	Diff

Select / Select Multiple

1,565 px (1.77%) changed

Before	After	Diff

Select / Select Complex

8,040 px (7.73%) changed

Before	After	Diff

Select / Select Disabled Options

1,738 px (1.96%) changed

Before	After	Diff

Select / Select Disabled Items

664 px (0.75%) changed

Before	After	Diff

Select / Select Grouped

784 px (0.89%) changed

Before	After	Diff

Select / Select Grouped With Disabled

1,585 px (1.79%) changed

Before	After	Diff

Select / Select Long List

8,317 px (7.99%) changed

Before	After	Diff

Select (Open)

2,337,786 px (9.4%) changed

Before	After	Diff

---

Generated by Kumo Visual Regression