Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion docs/specs/AST-082-native-first-surfaces/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -505,7 +505,19 @@ 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.
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved

Amended 2026-11-18 (**Decider:** `cixzhang`, `2026-11-18 13:08 PT`): `Button` and
`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
native-only look stays theme intent (OQ7).

### DEC-3 — How a native platform is built is decided by measurement

Expand Down Expand Up @@ -733,3 +745,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.
5 changes: 3 additions & 2 deletions docs/specs/AST-093-native-component-guidelines/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
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:
Expand Down Expand Up @@ -183,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 |

Expand Down