From a3391201063e9537d3927377e70f5df58dbc6872 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Wed, 18 Nov 2026 19:37:58 -0800 Subject: [PATCH 1/3] docs(spec): AST-082 DEC-2 amendment, Button and IconButton take a surface prop; OQ7 asks which other surfaces do --- docs/specs/AST-082-native-first-surfaces/spec.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md index e6e13bc3e2b0e..360c1ebf6d695 100644 --- a/docs/specs/AST-082-native-first-surfaces/spec.md +++ b/docs/specs/AST-082-native-first-surfaces/spec.md @@ -505,7 +505,13 @@ props (DEC-6) carry behavior and presentation choices a platform offers, not visuals. Rejected: visual props for one platform on components, because they move a -theme decision into every call site. +theme decision into every call site. Amended: `Button` and `IconButton`'s +`surface` prop is the one exception. + +Amended 2026-11-18 (**Decider:** `cixzhang`, `2026-11-18 13:08 PT`): `Button` and +`IconButton` take a per-call-site `surface` prop (`plain` default, or `glass`) as a +situational appearance choice, typed from the shared contracts. Every other +native-only look stays theme intent (OQ7). ### DEC-3 — How a native platform is built is decided by measurement @@ -733,3 +739,6 @@ would need the same words again. `aria-*` or `data-*` input still type-checks. Options: a lint rule, a development warning with the input not applied, or both. Recommendation: both, with the runtime change shipped as a breaking change under FR14. +- **OQ7 — Which other surfaces take surface-specific props, and where do they + live in the contracts?** (`human-api`) DEC-2 names `Button` and `IconButton`'s + `surface` prop as the one exception to theme-owned native looks. From 7d1dba0fc5dfcf8c5ee7747d49989e662d3f386c Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Wed, 18 Nov 2026 20:05:50 -0800 Subject: [PATCH 2/3] docs(spec): surface is a native platform prop, wins when set, and falls back to chrome material; AST-093 FR4 names the exception --- docs/specs/AST-082-native-first-surfaces/spec.md | 8 +++++++- docs/specs/AST-093-native-component-guidelines/spec.md | 3 ++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md index 360c1ebf6d695..6eef6888f9c8f 100644 --- a/docs/specs/AST-082-native-first-surfaces/spec.md +++ b/docs/specs/AST-082-native-first-surfaces/spec.md @@ -510,7 +510,13 @@ theme decision into every call site. Amended: `Button` and `IconButton`'s Amended 2026-11-18 (**Decider:** `cixzhang`, `2026-11-18 13:08 PT`): `Button` and `IconButton` take a per-call-site `surface` prop (`plain` default, or `glass`) as a -situational appearance choice, typed from the shared contracts. Every other +situational appearance choice. It is a platform prop in the iOS and Android +contracts (FR3, FR5); the core and web contracts do not have it. An explicit +`surface` decides that Button or IconButton's look. When `surface` is unset, the +theme's native `material` intent and the platform's placement rule decide it. +Where a platform or OS version has no system glass, `glass` draws that +platform's chrome material, as the platform's record defines; Reduce +Transparency and Increase Contrast apply as for any glass. Every other native-only look stays theme intent (OQ7). ### DEC-3 — How a native platform is built is decided by measurement diff --git a/docs/specs/AST-093-native-component-guidelines/spec.md b/docs/specs/AST-093-native-component-guidelines/spec.md index 89f01d602e54c..0aa099dc281e1 100644 --- a/docs/specs/AST-093-native-component-guidelines/spec.md +++ b/docs/specs/AST-093-native-component-guidelines/spec.md @@ -101,7 +101,8 @@ validating, and reviewing individual native components while `defineTheme` definition (`spec:AST-082/FR18`) and native intent and platform entries from `defineNativeTheme` (`spec:AST-082/FR10`). A component reads every such value from the theme, never hard-codes one, and never adds a - visual prop for one platform (`spec:AST-082/DEC-2`). Each spec lists the + visual prop for one platform, except `Button` and `IconButton`'s `surface` + prop (`spec:AST-082/DEC-2`). Each spec lists the theme values the component reads. - **FR5 — Every native component is tested and validated the same way.** A change to a native component ships with: From daa65a8a12c4c92ef04c934c12b6c66a195c9e1c Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Wed, 18 Nov 2026 20:29:24 -0800 Subject: [PATCH 3/3] docs(spec): surface is in every native contract and has no default; AST-093's FR4 check names the exception --- docs/specs/AST-082-native-first-surfaces/spec.md | 10 +++++----- docs/specs/AST-093-native-component-guidelines/spec.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md index 6eef6888f9c8f..2633b6013460c 100644 --- a/docs/specs/AST-082-native-first-surfaces/spec.md +++ b/docs/specs/AST-082-native-first-surfaces/spec.md @@ -509,11 +509,11 @@ theme decision into every call site. Amended: `Button` and `IconButton`'s `surface` prop is the one exception. Amended 2026-11-18 (**Decider:** `cixzhang`, `2026-11-18 13:08 PT`): `Button` and -`IconButton` take a per-call-site `surface` prop (`plain` default, or `glass`) as a -situational appearance choice. It is a platform prop in the iOS and Android -contracts (FR3, FR5); the core and web contracts do not have it. An explicit -`surface` decides that Button or IconButton's look. When `surface` is unset, the -theme's native `material` intent and the platform's placement rule decide it. +`IconButton` take a per-call-site `surface` prop (`plain` or `glass`) as a +situational appearance choice. It is a platform prop in every native platform's +contract (FR3, FR5); the core and web contracts do not have it. `surface` has no +default: unset follows the theme's native `material` intent and the platform's +placement rule; `plain` or `glass` overrides them. Where a platform or OS version has no system glass, `glass` draws that platform's chrome material, as the platform's record defines; Reduce Transparency and Increase Contrast apply as for any glass. Every other diff --git a/docs/specs/AST-093-native-component-guidelines/spec.md b/docs/specs/AST-093-native-component-guidelines/spec.md index 0aa099dc281e1..f2415fccc25a0 100644 --- a/docs/specs/AST-093-native-component-guidelines/spec.md +++ b/docs/specs/AST-093-native-component-guidelines/spec.md @@ -184,7 +184,7 @@ validating, and reviewing individual native components while | FR1 | Review of the views' folder and of the spec's path beside the core component's spec, plus `pnpm check:knowledge` on its record frontmatter, id, and `platform_of` | a spec per language; a spec for a component with no core contract; a member component core keeps in another component's folder | Views outside the folder that mirrors the core component root, a component spec outside the core component's folder under `docs/specs/components/`, without valid record frontmatter, under another id, naming no core component, or renaming a core prop passes | | FR2 | The spec's account of the platform control it builds on, or why none fits, and the state captures | a component built on a platform control; a component with no platform control | A component draws its own control where a platform control fits, with no reason in its spec | | FR3 | The spec's account of the platform guidelines it follows, and the captures | hit target size; largest Dynamic Type; Reduce Motion; VoiceOver focus | A capture shows a hit target below the platform minimum or text that does not scale | -| FR4 | Theme test with two themes, plus source review for literals | default theme; a second theme with different color, type, and shape | A brand value stays the same across both themes, or a platform-only visual prop is added | +| FR4 | Theme test with two themes, plus source review for literals | default theme; a second theme with different color, type, and shape | A brand value stays the same across both themes, or a platform-only visual prop other than `Button` and `IconButton`'s `surface` (`spec:AST-082/DEC-2`) is added | | FR5 | The package's tests on every supported platform and the captures attached to the change | light; dark; largest text; every state the core contract names | A change merges without tests, without captures, or with a capture-based claim backed only by source | | FR6 | Changed paths, commit authors, the review app's exact-head review, the spec review's findings, and the approval | all native paths by group members; a spec-defined requirement unmet; behavior no spec defines; a native component spec under `docs/specs/components/`; a path outside `packages/native/` and those specs; a commit from someone else | An approval without an exact-head review-app pass or a spec review, an approval with a spec-defined requirement unmet, an out-of-scope pull request approved without review, or an in-scope one blocked only for behavior no spec defines |