An open source design system that's fully customizable and agent ready
TypeScript
fix(theme): Android text follows the system font scale with no setup (#10727)
Cindy Zhang7bd08bbe5c69
diff --git a/.changeset/android-text-scale-env.md b/.changeset/android-text-scale-env.mdnew file mode 100644index 0000000000..a6949449ab--- /dev/null+++ b/.changeset/android-text-scale-env.md@@ -0,0 +1,8 @@+---+'@astryxdesign/core': patch+'@astryxdesign/cli': patch+---++[fix] On Android, text follows the reader's system font scale in every theme with no setup, in browsers that report `env(preferred-text-scale)` (verified on Chromium; Chrome stable not yet verified). The root `Theme` reads `env(preferred-text-scale)` and scales every font size by it, as it already follows Dynamic Type on iPhone. Before, the system font scale reached Astryx text only when the page added `<meta name="text-scale" content="scale">`. A page with `content="scale"` keeps working as it did: its root font size carries the scale, and the root `Theme` adds none. Browsers without either see no change. `astryx docs typography/type-scale` describes it.++@cixzhangdiff --git a/docs/specs/AST-102-typography-theme-owned/spec.md b/docs/specs/AST-102-typography-theme-owned/spec.mdindex 6b4122384f..dc6259c3f6 100644--- a/docs/specs/AST-102-typography-theme-owned/spec.md+++ b/docs/specs/AST-102-typography-theme-owned/spec.md@@ -76,12 +76,13 @@ the person's device.replaces the mobile reading base of `design:mobile-typography` DR1, smalleror larger, and DR2's pin does not apply: every role scales from that size;DR1 and DR2 apply when none is set, and the iOS text-entry floor of- `family:input-fields` FR9 still holds. On Android, the system font scale reaches the- page's root font size only with `<meta name="text-scale" content="scale">`;- Astryx sizes from the root, so with it the whole scale follows (verified on- Chromium 159.0.8142.0 on Android; Chrome on Android is unverified on current- stable). Without it the root stays 16 px, and the browser's own zoom setting- magnifies the page instead.+ `family:input-fields` FR9 still holds. On Android, Core reads the system font scale+ from `env(preferred-text-scale)` and scales every font size by it, so the+ whole scale follows with no switch (DEC-3, DEC-4). A page that carries+ `<meta name="text-scale" content="scale">` already has the system font scale+ on its root font size, which Astryx sizes from, so Core adds none (the root+ font size follows the meta on Chromium 159.0.8142.0 on Android; Chrome on+ Android is unverified on current stable).- **FR4 — Larger text stays usable.** Up to 200% of the theme's sizes, everycomponent keeps all of its content and function (WCAG 2.2 success criterion1.4.4). Above 200%, reading text keeps growing; a label inside a dense control, such@@ -100,7 +101,8 @@ the person's device.- Browser evidence (`spec:AST-013` FR10): Safari on iOS proves an FR2 theme'sbody text in the system body font and FR3 across Dynamic Type categories;Chromium 159.0.8142.0 on Android in the emulator proves FR3's Android- behavior with the system font scale, with and without the text-scale meta; a desktop browser proves FR3 with its default font size and zoom, and FR4 at+ behavior with the system font scale, with and without the text-scale meta,+ and Chrome on Android stays unverified on current stable; a desktop browser proves FR3 with its default font size and zoom, and FR4 at200% and above; token and source checks prove FR1.## Current-state impact@@ -124,17 +126,19 @@ the person's device.FR1's block size, `component:Token` FR1's element size, and InputGroup'srow height in `family:input-fields`, so a larger label can overflow; thoserecords treat their sizes as minimums under FR4.- - Android's system font scale reaches Astryx text only through the- text-scale meta; Core does not read `env(preferred-text-scale)`.+ - Core's `env(preferred-text-scale)` read is verified on Chromium+ 159.0.8142.0 on Android (system scale 1.3: body 20.8 px without the meta;+ no double scaling with it); Chrome on Android is unverified on current+ stable.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1 | Source check over Core and Lab component styles plus token review | family, size, and line height of rendered text in component styles; an inherited value; a `1em` icon size; coarse and fine pointer; a platform font keyword; the iOS text-entry floor | A Core or Lab web component sets the family, size, or line height of text it renders outside typography tokens and not by inheritance, or applies a platform font keyword directly; icon sizing, the family floor, and a hidden internal element that only measures a platform text style are not failures |-| FR2 | Theme token review plus Safari on iOS, top-level document | an unbranded shipped theme using the system body font family; a branded theme; the default theme | A branded theme's body font replaced by the system font, or a system body font applied by a component instead of a theme token |-| FR3 | Safari on iOS across Dynamic Type categories; Chromium 159.0.8142.0 on Android in the emulator at system font scale 1.3, with `<meta name="text-scale" content="scale">` (root 21 px as measured; rem sizes scale with it), without it (root 16 px), and without it at Default zoom 133% (root 16 px, page zoom); Chrome on Android unverified on current stable; a desktop browser with a larger default font size and with zoom; theme review; `scripts/check-theme-text-size-units.test.mjs` (no first-party theme sets a text or font size in px) | a branded and an unbranded theme; no size set; default category; a size set on each platform; Android with and without the text-scale meta; macOS Safari at its default text size, whose fixed 13 px Body names no category, so every scale stays 1 (`dynamicType.test.ts`; a browser reading is a recorded follow-up) | Text that ignores a size the person set; text that differs from the theme's family or size when none is set, other than the `family:input-fields` FR9 iOS text-entry floor; a theme family replaced; a public option, prop, or document attribute; a changed root font size |-| FR4 | Desktop browser at 200%, 250%, and 300% text size, plus Safari on iOS at accessibility categories | reading text; a button, text input, tab, badge, table cell, and segmented control | Lost content or function at 200% or less; a label clipped by its control's height at any size; a control that keeps a fixed height while its text grows |+| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Source check over Core and Lab component styles plus token review | family, size, and line height of rendered text in component styles; an inherited value; a `1em` icon size; coarse and fine pointer; a platform font keyword; the iOS text-entry floor | A Core or Lab web component sets the family, size, or line height of text it renders outside typography tokens and not by inheritance, or applies a platform font keyword directly; icon sizing, the family floor, and a hidden internal element that only measures a platform text style are not failures |+| FR2 | Theme token review plus Safari on iOS, top-level document | an unbranded shipped theme using the system body font family; a branded theme; the default theme | A branded theme's body font replaced by the system font, or a system body font applied by a component instead of a theme token |+| FR3 | Safari on iOS across Dynamic Type categories; Chromium 159.0.8142.0 on Android in the emulator at system font scale 1.3, with `<meta name="text-scale" content="scale">` (root 21 px as measured; rem sizes scale with it), without it (root 16 px), and without it at Default zoom 133% (root 16 px, page zoom); Chrome on Android unverified on current stable; `dynamicType.test.ts` (every scale reads `env(preferred-text-scale)` where the engine has no `-apple-system-body`; none on a page with the text-scale meta); Chromium 159.0.8142.0 on Android at system font scale 1.3 with Core's read: without the meta, root 16 px, body 20.8 px, `display-1` 54.6 px; with the meta, root 21 px, body 21 px, `display-1` 55.125 px, no double scaling; at 1.0, sizes equal main with and without the meta; a desktop browser with a larger default font size and with zoom; theme review; `scripts/check-theme-text-size-units.test.mjs` (no first-party theme sets a text or font size in px) | a branded and an unbranded theme; no size set; default category; a size set on each platform; Android with and without the text-scale meta; macOS Safari at its default text size, whose fixed 13 px Body names no category, so every scale stays 1 (`dynamicType.test.ts`; a browser reading is a recorded follow-up) | Text that ignores a size the person set; text that differs from the theme's family or size when none is set, other than the `family:input-fields` FR9 iOS text-entry floor; a theme family replaced; a public option, prop, or document attribute; a changed root font size |+| FR4 | Desktop browser at 200%, 250%, and 300% text size, plus Safari on iOS at accessibility categories | reading text; a button, text input, tab, badge, table cell, and segmented control | Lost content or function at 200% or less; a label clipped by its control's height at any size; a control that keeps a fixed height while its text grows |## Decision log@@ -178,6 +182,18 @@ is a theme option, prop, or document attribute.Rejected: a public opt-in option or document attribute for the size.+### DEC-4 — Android's system font scale is read the same way++**Reference:** `spec:AST-102/DEC-4`+**Decider:** Specs consistency ruling, `2026-11-09`, applying DEC-3++Where the platform exposes the person's size only through+`env(preferred-text-scale)`, as Chromium on Android does, Core reads it there+too, so products still need no switch; a page with+`<meta name="text-scale" content="scale">` already carries it on its root font+size, so Core adds none. Like DEC-3's reads, it is not a theme option, prop, or+document attribute.+## Open questionsNone.diff --git a/packages/cli/assets/docs/tree/type-scale.doc.mjs b/packages/cli/assets/docs/tree/type-scale.doc.mjsindex d26958cc3f..c3517ee57c 100644--- a/packages/cli/assets/docs/tree/type-scale.doc.mjs+++ b/packages/cli/assets/docs/tree/type-scale.doc.mjs@@ -152,7 +152,7 @@ const denseTheme = defineTheme({content: [{type: 'prose',- text: "On iPhone, readers pick a text size in Settings (Display & Text Size, then Larger Text), and native apps grow or shrink their text with it. Every theme does the same in Safari on iPhone, which exposes that choice through `font: -apple-system-body`: each font size follows the reader's choice on the curve of the iOS text style it plays, so body text scales like Body, `heading-1` like Title 1 and display text like Large Title, and every role keeps its order. A size the theme fixes at a length, such as a 12px supporting size, scales on the curve of the step it reads by default; a size in `em` or `%` follows its parent, and one that reads a variable follows that variable. At the default size every font size is the theme's own. The family, spacing, radius and the root font size never change, line heights keep their ratios, text inputs keep their 16px floor on iOS, and browsers without the keyword see no change. There is nothing to turn on: no theme option, prop or document attribute.",+ text: "On iPhone, readers pick a text size in Settings (Display & Text Size, then Larger Text), and native apps grow or shrink their text with it. Every theme does the same in Safari on iPhone, which exposes that choice through `font: -apple-system-body`: each font size follows the reader's choice on the curve of the iOS text style it plays, so body text scales like Body, `heading-1` like Title 1 and display text like Large Title, and every role keeps its order. A size the theme fixes at a length, such as a 12px supporting size, scales on the curve of the step it reads by default; a size in `em` or `%` follows its parent, and one that reads a variable follows that variable. At the default size every font size is the theme's own. The family, spacing, radius and the root font size never change, line heights keep their ratios, text inputs keep their 16px floor on iOS, and on Android the system font scale grows every font size through `env(preferred-text-scale)` where the browser reports it; browsers with neither see no change. There is nothing to turn on: no theme option, prop or document attribute.",},{type: 'prose',diff --git a/packages/core/src/theme/Theme.test.tsx b/packages/core/src/theme/Theme.test.tsxindex 178c5fb67b..bfe5919b37 100644--- a/packages/core/src/theme/Theme.test.tsx+++ b/packages/core/src/theme/Theme.test.tsx@@ -339,8 +339,9 @@ describe('Theme', () => {});// The gate is the capability alone, never a platform idiom (one touch// behavior on every touch device): a touch callout without- // `font: -apple-system-body` reads nothing.- it('reads no text size where the engine has no font: -apple-system-body', () => {+ // `font: -apple-system-body` measures nothing, and every scale reads+ // `env(preferred-text-scale)`.+ it('measures no text size where the engine has no font: -apple-system-body, and reads env(preferred-text-scale)', () => {vi.stubGlobal('CSS', {supports: vi.fn((property: string) => property === '-webkit-touch-callout',@@ -349,7 +350,10 @@ describe('Theme', () => {vi.stubGlobal('CSSStyleSheet',class {- replaceSync() {}+ text = '';+ replaceSync(text: string) {+ this.text = text;+ }},);Object.defineProperty(document, 'adoptedStyleSheets', {@@ -357,17 +361,24 @@ describe('Theme', () => {writable: true,value: [],});+ let unmount = () => {};try {- render(+ ({unmount} = render(<Theme theme={testTheme}><span>web</span></Theme>,- );+ ));expect(document.querySelector('[data-astryx-text-size-probe]'),).toBeNull();- expect(document.adoptedStyleSheets).toEqual([]);+ const adopted = (+ document.adoptedStyleSheets as unknown as {text: string}[]+ )+ .map(sheet => sheet.text)+ .join('');+ expect(adopted).toContain('env(preferred-text-scale, 1)');} finally {+ unmount();vi.unstubAllGlobals();delete (document as {adoptedStyleSheets?: unknown}).adoptedStyleSheets;}diff --git a/packages/core/src/theme/Theme.tsx b/packages/core/src/theme/Theme.tsxindex 6495acba16..952c7ff850 100644--- a/packages/core/src/theme/Theme.tsx+++ b/packages/core/src/theme/Theme.tsx@@ -325,9 +325,8 @@ function useRootThemeSync(/*** Hook to keep the page's text size scales on the reader's text size (iOS- * Dynamic Type) for the root provider; see dynamicType.ts. Skipped for nested- * Theme instances, and a no-op where the engine has no- * `font: -apple-system-body`.+ * Dynamic Type, or `env(preferred-text-scale)` elsewhere) for the root+ * provider; see dynamicType.ts. Skipped for nested Theme instances.*/function useRootTextSizeSync(isNested: boolean): void {useIsomorphicLayoutEffect(() => {diff --git a/packages/core/src/theme/dynamicType.test.ts b/packages/core/src/theme/dynamicType.test.tsindex 62b2d59c0c..344c3ccf47 100644--- a/packages/core/src/theme/dynamicType.test.ts+++ b/packages/core/src/theme/dynamicType.test.ts@@ -1002,13 +1002,55 @@ describe('the root sync', () => {// The gate is the capability alone, never a platform idiom (one touch// behavior on every touch device).- it('does nothing where the engine has no font: -apple-system-body, touch callout or not', () => {+ it('reads env(preferred-text-scale) for every scale where the engine has no font: -apple-system-body, touch callout or not', () => {pretendEngine({textSize: false, touchCallout: true});- expect(syncReaderTextSize(document)).toBeUndefined();+ const before = htmlAttributes();+ const cleanup = syncReaderTextSize(document);+ expect(cleanup).toBeTypeOf('function');expect(document.querySelector('[data-astryx-text-size-probe]')).toBeNull();+ for (const step of ['body', 'title1', 'largeTitle'] as const) {+ expect(adoptedText()).toContain(+ `${dynamicTypeScaleProperty(step)}: env(preferred-text-scale, 1);`,+ );+ }+ expect(htmlAttributes()).toBe(before);+ cleanup?.();expect(document.adoptedStyleSheets).toEqual([]);});+ // The meta already scales the root font size, and rem sizes follow it.+ it('gives no scales on a page whose text-scale meta scales the root font size', () => {+ pretendEngine({textSize: false});+ const meta = document.createElement('meta');+ meta.name = 'text-scale';+ meta.content = 'scale';+ document.head.append(meta);+ try {+ expect(syncReaderTextSize(document)).toBeUndefined();+ expect(document.adoptedStyleSheets).toEqual([]);+ } finally {+ meta.remove();+ }+ });++ // `legacy` keeps the root at 16 px, so the scales still apply.+ it('still reads env(preferred-text-scale) under a legacy text-scale meta', () => {+ pretendEngine({textSize: false});+ const meta = document.createElement('meta');+ meta.name = 'text-scale';+ meta.content = 'legacy';+ document.head.append(meta);+ try {+ const cleanup = syncReaderTextSize(document);+ expect(adoptedText()).toContain(+ `${dynamicTypeScaleProperty('body')}: env(preferred-text-scale, 1);`,+ );+ cleanup?.();+ } finally {+ meta.remove();+ }+ });+it('follows the reader text size wherever the engine provides it, with no platform check', () => {pretendEngine({textSize: true, touchCallout: false});probeSize = '23px';diff --git a/packages/core/src/theme/dynamicType.ts b/packages/core/src/theme/dynamicType.tsindex e06ff1e26b..d8f6a30f53 100644--- a/packages/core/src/theme/dynamicType.ts+++ b/packages/core/src/theme/dynamicType.ts@@ -21,8 +21,14 @@* and gives the page that category's scales in an adopted stylesheet. It* reads again when the probe resizes. Each theme writes a font size as its* own value times the scale of the text style it plays, so only sizes move.- * Every scale is 1 at the default category and in every other browser.- * macOS Safari knows the keyword, but its fixed 13px Body names no category.+ * Every scale is 1 at the default category. macOS Safari knows the keyword,+ * but its fixed 13px Body names no category.+ *+ * Elsewhere every scale reads `env(preferred-text-scale)`, with 1 as the+ * fallback, so an engine without it changes nothing. Chromium on Android sets+ * it from the system font scale. A page that carries+ * `<meta name="text-scale" content="scale">` already scales its root font+ * size, so it gets no scales: rem sizes follow the root once.** SYNC: When modified, update:* - /packages/core/src/theme/dynamicType.test.ts@@ -166,12 +172,29 @@ function scaleRuleForColumn(column: number): string {if (column < 0 || column === LARGE) {return '';}+ return scaleRule(style =>+ formatScale(typography[style][column] / typography[style][LARGE]),+ );+}++/** The value every scale takes where the engine reports one text scale. */+export const PREFERRED_TEXT_SCALE = 'env(preferred-text-scale, 1)';++/**+ * The rule that gives every scaled style the engine's one text scale. The+ * system font scale on Android grows all text by the same factor.+ */+export function preferredTextScaleRule(): string {+ return scaleRule(() => PREFERRED_TEXT_SCALE);+}++function scaleRule(scaleOf: (style: DynamicTypeStyle) => string): string {const declarations = (entries: [string, string][]) =>entries.map(([name, value]) => ` ${name}: ${value};`).join('\n');return `@layer astryx-base {\n:root {\n${declarations(scaledFontSizeEntries(textSizeDefaults))}\n}\n}\n:root {\n${declarations(SCALED_STYLES.map(style => [dynamicTypeScaleProperty(style),- formatScale(typography[style][column] / typography[style][LARGE]),+ scaleOf(style),]),)}\n}`;}@@ -334,10 +357,11 @@ function lengthInPx(value: string | undefined): number | null {/*** Measure the reader's text size and give the page its scales; returns the- * cleanup. Does nothing where the engine has no `font: -apple-system-body` or- * cannot construct a stylesheet (every supported browser that has the keyword- * can); where its Body size names no category (macOS Safari's fixed 13px),- * every scale stays 1.+ * cleanup. Where the engine has no `font: -apple-system-body`, every scale+ * reads `env(preferred-text-scale)` instead, unless the page carries the+ * text-scale meta. Does nothing where the engine cannot construct a+ * stylesheet; where its Body size names no category (macOS Safari's fixed+ * 13px), every scale stays 1.** The probe is a hidden, empty `font: -apple-system-body` box, 1em square,* appended to `<body>` outside every app subtree: it renders no text, and it@@ -382,12 +406,15 @@ const sharedSyncs = new WeakMap<function startReaderTextSizeSync(doc: Document): (() => void) | undefined {const view = doc.defaultView;if (- !view?.CSS?.supports?.('font', '-apple-system-body') ||+ view == null ||typeof view.CSSStyleSheet !== 'function' ||!Array.isArray(doc.adoptedStyleSheets)) {return undefined;}+ if (!view.CSS?.supports?.('font', '-apple-system-body')) {+ return startPreferredTextScale(doc, view);+ }const probe = doc.createElement('span');probe.setAttribute('aria-hidden', 'true');@@ -417,3 +444,25 @@ function startReaderTextSizeSync(doc: Document): (() => void) | undefined {);};}++/**+ * Give every scale `env(preferred-text-scale)`, which the engine keeps+ * current, so nothing is measured or observed. Does nothing on a page whose+ * text-scale meta already scales the root font size.+ */+function startPreferredTextScale(+ doc: Document,+ view: Window & typeof globalThis,+): (() => void) | undefined {+ if (doc.querySelector('meta[name="text-scale"][content="scale" i]') != null) {+ return undefined;+ }+ const sheet = new view.CSSStyleSheet();+ sheet.replaceSync(preferredTextScaleRule());+ doc.adoptedStyleSheets = [...doc.adoptedStyleSheets, sheet];+ return () => {+ doc.adoptedStyleSheets = doc.adoptedStyleSheets.filter(+ adopted => adopted !== sheet,+ );+ };+}