From a269fa0d1de961418b42fb60f7585b9dcc7d0277 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:11:28 -0800 Subject: [PATCH 1/5] spec(Card): React Native platform record --- .../components/Card/Card.react-native.spec.md | 222 ++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 docs/specs/components/Card/Card.react-native.spec.md diff --git a/docs/specs/components/Card/Card.react-native.spec.md b/docs/specs/components/Card/Card.react-native.spec.md new file mode 100644 index 0000000000000..c8de3de35126b --- /dev/null +++ b/docs/specs/components/Card/Card.react-native.spec.md @@ -0,0 +1,222 @@ +--- +schema_version: 3 +template_version: 7 +kind: component +id: component:react-native/Card +platform_of: component:Card +authority: draft +archive_reason: null +superseded_by: null +approved_by: null +approved_at: null +owners: [imdreamrunner] +review_triggers: + [public-api, behavior, layout, theming, accessibility, platform] +verified_by: [] +modules: [] +families: [] +design_specs: [] +architecture: + [ + architecture:component-theming-surface, + architecture:container-padding, + architecture:public-component-api, + ] +contributing: [] +system_specs: [spec:AST-082, spec:AST-093] +--- + +# Card (React Native) component contract + +## Contract at a glance + +| Area | Contract | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | React Native exports `Card` under core's name with core's `children`, `padding`, `variant` and `elevation`, with core's meaning and defaults. Its `variant` adds two values, `body` and `surface`, the theme's page and surface backgrounds (DEC-2). Core's `width`, `height`, `maxWidth` and `minHeight` stay in the web contract (DEC-1). | +| Behavior | A rounded surface from the theme that holds one discrete item: it paints its variant, draws `default`'s border inside its padding, casts its elevation's shadow, publishes its padding to what it holds, clips what does not fit, and turns bare words into body text. | +| End-user impact | A person sees grouped content on the same surface as on the web, with insets on the spacing scale; a screen reader reads what the card holds, not the card. | +| Builder impact | An app writes the same `Card` call site as on the web; its size comes from the layout around it. | +| Compatibility/readiness | Not yet released; additive. Draft. The core and web contracts are unchanged. | +| Review checks | Reject a card that becomes an accessibility element, a variant that falls through to another variant, a lost padding publication, bare words that fail to render, a sizing prop accepted and ignored, a visual value not taken from the theme, or a native dependency. | +| Governing rules | `component:Card` FR2, FR3, FR5 and AR1; `architecture:container-padding` INV11; `architecture:component-theming-surface`; `spec:AST-082` FR3–FR5 and FR7; `spec:AST-093` FR2 and FR4; DEC-1 and DEC-2 below. | + +This table is a review projection; the body below is authoritative. + +## Intent + +A card groups one discrete item, a profile, a metric or a product, on a surface +of its own. Card on React Native keeps core's props and surface, so a screen +reads the same on the web and on a phone, and it draws that surface from the +theme with React Native's own views. This record states only what React Native +adds to `component:Card` or does differently. + +## Compatibility and migration + +- Released default preserved: `not yet released` +- Compatibility class: additive +- Controlled/uncontrolled behavior: not applicable; Card holds no value +- Migration decision: none + +Consumer migration instructions belong in consumer docs and release notes. + +## Current-state impact + +- FR2 gap: `body` and `surface` cards keep their full padding inside their + border instead of reducing it by the border width as `default` does. + +## Ownership boundary + +**Owns** + +- Which of core's props React Native offers, and the `body` and `surface` + variants (FR1, FR2). +- How a React Native card holds its content: bare words, clipping and its + place in a row (FR4, FR5). +- How the card reads to screen readers on React Native (FR6). + +**Does not own / non-goals** + +- The meaning of Card's props, its variants, its padding resolution and its + published inset — owned by `component:Card` and + `architecture:container-padding`. +- A card that acts as one control — owned by `component:ClickableCard` and + `component:SelectableCard`. +- A page region — owned by `component:Section`. +- A card's size in a row — owned by the stack around it. + +## Public concepts + +| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior | +| ------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | --------- | --------------------------------------------------------------------- | ------------ | -------------------------------- | +| variant | core's values; `body`; `surface` | the card's fill: core's card, muted and palette fills, and on React Native the theme's page and surface backgrounds | every card | `default` | `component:Card`; `body` and `surface`: `component:react-native/Card` | experimental | an unknown value is a type error | + +## Behavioral and layout contract + +Draft requirements identify their basis so observed code is not mistaken for an +intentional decision. A `current` contract contains no unresolved rows. + +| ID | Candidate invariant | Basis | Draft review state | +| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------ | +| FR1 | React Native's `Card` MUST take core's `children`, `padding`, `variant` and `elevation` with core's names, meaning and defaults. `children` takes React content, as a platform contract whose implementation runs React may (`spec:AST-082` FR4). Base props are `id` and `isHidden` (`spec:AST-082` FR7) on the card's container, the part core's target sits on. It MUST NOT offer core's `width`, `height`, `maxWidth` or `minHeight` (DEC-1). | `component:Card`; `spec:AST-082` FR3, FR4, FR7; DEC-1 | verify | +| FR2 | `variant` MUST paint as `component:Card` FR2 states: `default` the card background with the theme's border, `transparent` nothing, `muted` the muted background, and each palette value its own background tint, with the corners of the theme's container radius. React Native adds `body` and `surface` (DEC-2), which paint the theme's page background and surface background with `default`'s border and its inset rule. A theme's own variant name paints the base surface, never another variant. | `component:Card` FR2; `architecture:component-theming-surface`; DEC-2 | verify | +| FR3 | `padding` MUST resolve and publish as `component:Card` FR3 states: an omitted `padding` takes the theme's card padding, spacing step 4 with none; a step applies to every edge; a bordered card reduces each edge by the theme's border width, never below zero; and the card publishes its inset to what it holds, so a `Layout` or a full-bleed `Divider` inside it meets its edges (`architecture:container-padding` INV11). | `component:Card` FR3; `architecture:container-padding` INV11 | verify | +| FR4 | The card MUST have no minimum width, so it shrinks in a row instead of holding the row at its content's width, and MUST clip what does not fit; it never scrolls. Its size comes from the layout around it: a `Stack`, a `StackItem` or the parent view (DEC-1). Inside a `Carousel` item, the card fills the item's height, so a row of cards is even. | `component:Card` FR4; DEC-1 | verify | +| FR5 | Bare words in `children` MUST render as body text in the theme's body type and text colour, since React Native draws words only inside a text view. Other content renders as given. | `component:Card`; `spec:AST-082` FR4 | verify | +| FR6 | The card MUST NOT be an accessibility element: it has no role, name or focus stop of its own, and VoiceOver and TalkBack reach the things it holds one by one (`component:Card` AR1). It announces nothing. | `component:Card` AR1 | verify | +| FR7 | `elevation` MUST cast no shadow for `none` and the theme's low, medium or high shadow for the other values (`component:Card` FR5). The theme's component overrides for Card apply over the card's own styles. | `component:Card` FR5; `architecture:component-theming-surface` | verify | + +### Allowed variation + +- **AV1 — Theme paint.** A theme may change the card's fills, border, corners, + shadows and padding through its tokens and its component overrides for Card, + without changing the card's structure or semantics. + +### Representative states + +| State | Required invariant | Allowed variation | +| --------------------------- | -------------------------------------------------------- | ----------------- | +| `default`, padding omitted | card background, border inside the theme's card padding | theme paint | +| `padding={0}` | content meets the card's edges | none | +| `body` in a surface section | the page background with `default`'s border | theme paint | +| a theme variant | the base surface | theme paint | +| in a narrow row | shrinks below its content width; clips | none | +| bare words | body text | none | +| with a screen reader | the card's content, one thing at a time; no card element | none | + +### Transformation and precedence order + +- **ORD1 — Padding.** `padding`, then the theme's card padding, then step 4 + (`component:Card` FR3). +- **ORD2 — Styles.** The card's own styles, then the theme's component + overrides for Card. + +### Performance and resources + +- **PR1 — No work of its own.** The card holds no timers or listeners; it + computes its frame only when its variant, elevation, padding or theme + changes. + +## Accessibility contract + +- **AR1 — No semantics added.** The card adds no role, name or focus stop; its + content's semantics pass through (FR6). +- **AR2 — Text size.** Bare words render as body text, which scales with + Dynamic Type and Android's font scale, and the card grows with its content. + +## Design relationships + +| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract | +| ---------------- | ------------------------------------------------------------ | ------------------------ | -------------- | ------------------ | +| Surface | the variant's fill, the container radius, `default`'s border | theme intent | container | FR2 | +| Shadow | the elevation's shadow | theme intent | supporting | FR7 | +| Padding | the spacing step or the theme's card padding | theme intent | container | FR3 | + +The component implements design requirements without copying their rationale. + +Platform control (`spec:AST-093` FR2): none. React Native has no card view, +and SwiftUI's grouped backgrounds and Android's card views are native views +React Native does not draw, so the card is a React Native `View` drawn from +the theme. + +Theme values read (`spec:AST-093` FR4): `color.backgroundCard`, +`color.backgroundMuted`, the palette background colours, `color.backgroundBody` +and `color.backgroundSurface`, the border colour and width, +`radius.container`, the `space` steps and the theme's card padding, the +`shadow.low`, `shadow.med` and `shadow.high` layers, the body type and text +colour, and the theme's component overrides for Card. + +## Family and system relationships + +- `component:Card` owns the props, the variants, the padding resolution and the + published inset; this record states how React Native draws them. +- `component:ClickableCard` and `component:SelectableCard` draw the same + surface for a card that acts. +- `architecture:container-padding` owns the padding a card publishes. + +## Verification map + +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| -------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | +| FR1 | Type tests against core's Card contract and each platform's types | each core prop; the sizing props | a sizing prop that type-checks, or a renamed core prop, fails | `audit:react-native/Card/api` | +| FR2, FR7, ORD2 | Unit tests of the frame with two themes | each variant; `body`; `surface`; a theme variant; each elevation; a theme override | a variant painted with another's fill, a border on a variant core draws without one, or an override that does not apply fails | `audit:react-native/Card/surface` | +| FR3, ORD1 | Unit tests of padding and the published inset | omitted; each step; `0`; a `default` and a `muted` card; a `Layout` inside | a padding off the step, a lost publication, or an inset that differs from core's fails | `audit:react-native/Card/padding` | +| FR4, FR5 | Unit tests of placement and content | a narrow row; a `Carousel` item; bare words; a view | a card that holds its row, a card that scrolls, or bare words that do not render fails | `audit:react-native/Card/layout` | +| FR6, AR1, AR2 | VoiceOver and TalkBack checks; unit tests of the accessibility props | a card with text and a button | a card element, a role or label on the card, or content the screen reader skips fails | `audit:react-native/Card/a11y` | + +## Decision log + +### DEC-1 — A card's size comes from the layout around it + +**Reference:** `component:react-native/Card/DEC-1` +**Decider:** imdreamrunner, 2026-11-18 + +Core's `width`, `height`, `maxWidth` and `minHeight` take a `SizeValue`: a +number of pixels or a CSS length string, such as a percentage, `rem` or +`calc()`, that React Native does not read (`spec:AST-082` FR4). On the web a +card's width in a row is already only a preference that a `StackItem` holds; +on React Native the `Stack`, the `StackItem` or the parent view sizes the card, +so the sizing props stay in the web contract and a card never offers a size it +lays out differently. + +### DEC-2 — React Native cards take the page and surface backgrounds + +**Reference:** `component:react-native/Card/DEC-2` +**Decider:** imdreamrunner, 2026-11-18 + +A checkout card on the page's colour inside a surface section needs the +theme's page or surface background. The web reaches those backgrounds through +a custom style on the card, which React Native's contract has no form for, so +React Native's `variant` adds `body` and `surface`, which read the theme's +background roles and stay bordered like `default` (`spec:AST-082` FR5). + +## Open questions + +- **OQ1 — Do `body` and `surface` join core's `variant`?** (`human-api`) + Options: core adds them for every platform, so the web reaches the page and + surface backgrounds without a custom style; or they stay values of React + Native's contract (DEC-2). + +## Content boundary + +This file does not duplicate consumer prop tables/examples, current audit +results, implementation steps, or family/system rules. It links to their owners. From 33a340b5a277e0f98724fd14c41dac5b30143799 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Thu, 19 Nov 2026 00:40:47 -0800 Subject: [PATCH 2/5] spec(Card): no React Native-only variants; native override source; sizing reason; text-size check --- .../components/Card/Card.react-native.spec.md | 134 ++++++++---------- 1 file changed, 59 insertions(+), 75 deletions(-) diff --git a/docs/specs/components/Card/Card.react-native.spec.md b/docs/specs/components/Card/Card.react-native.spec.md index c8de3de35126b..20c4011ce1da4 100644 --- a/docs/specs/components/Card/Card.react-native.spec.md +++ b/docs/specs/components/Card/Card.react-native.spec.md @@ -30,15 +30,15 @@ system_specs: [spec:AST-082, spec:AST-093] ## Contract at a glance -| Area | Contract | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | React Native exports `Card` under core's name with core's `children`, `padding`, `variant` and `elevation`, with core's meaning and defaults. Its `variant` adds two values, `body` and `surface`, the theme's page and surface backgrounds (DEC-2). Core's `width`, `height`, `maxWidth` and `minHeight` stay in the web contract (DEC-1). | -| Behavior | A rounded surface from the theme that holds one discrete item: it paints its variant, draws `default`'s border inside its padding, casts its elevation's shadow, publishes its padding to what it holds, clips what does not fit, and turns bare words into body text. | -| End-user impact | A person sees grouped content on the same surface as on the web, with insets on the spacing scale; a screen reader reads what the card holds, not the card. | -| Builder impact | An app writes the same `Card` call site as on the web; its size comes from the layout around it. | -| Compatibility/readiness | Not yet released; additive. Draft. The core and web contracts are unchanged. | -| Review checks | Reject a card that becomes an accessibility element, a variant that falls through to another variant, a lost padding publication, bare words that fail to render, a sizing prop accepted and ignored, a visual value not taken from the theme, or a native dependency. | -| Governing rules | `component:Card` FR2, FR3, FR5 and AR1; `architecture:container-padding` INV11; `architecture:component-theming-surface`; `spec:AST-082` FR3–FR5 and FR7; `spec:AST-093` FR2 and FR4; DEC-1 and DEC-2 below. | +| Area | Contract | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | React Native exports `Card` under core's name with core's `children`, `padding`, `variant` and `elevation`, with core's meaning and defaults. Core's `width`, `height`, `maxWidth` and `minHeight` stay in the web contract (DEC-1). | +| Behavior | A rounded surface from the theme that holds one discrete item: it paints its variant, draws `default`'s border inside its padding, casts its elevation's shadow, publishes its padding to what it holds, clips what does not fit, and turns bare words into body text. | +| End-user impact | A person sees grouped content on the same surface as on the web, with insets on the spacing scale; a screen reader reads what the card holds, not the card. | +| Builder impact | An app writes the same `Card` call site as on the web; its size comes from the layout around it. | +| Compatibility/readiness | Not yet released; additive. Draft. The core and web contracts are unchanged. | +| Review checks | Reject a card that becomes an accessibility element, a variant that falls through to another variant, a variant core does not have, a lost padding publication, bare words that fail to render, a sizing prop accepted and ignored, a visual value not taken from the theme, or a native dependency. | +| Governing rules | `component:Card` FR2, FR3, FR5 and AR1; `architecture:container-padding` INV11; `architecture:component-theming-surface`; `spec:AST-082` FR3, FR4, FR7, FR10 and DEC-2; `spec:AST-093` FR2, FR4 and FR5; DEC-1 below. | This table is a review projection; the body below is authoritative. @@ -61,15 +61,14 @@ Consumer migration instructions belong in consumer docs and release notes. ## Current-state impact -- FR2 gap: `body` and `surface` cards keep their full padding inside their - border instead of reducing it by the border width as `default` does. +- FR2 gap: the package's Card also takes the `variant` values `body` and + `surface`, the theme's page and surface backgrounds. ## Ownership boundary **Owns** -- Which of core's props React Native offers, and the `body` and `surface` - variants (FR1, FR2). +- Which of core's props React Native offers (FR1). - How a React Native card holds its content: bare words, clipping and its place in a row (FR4, FR5). - How the card reads to screen readers on React Native (FR6). @@ -86,49 +85,48 @@ Consumer migration instructions belong in consumer docs and release notes. ## Public concepts -| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior | -| ------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | --------- | --------------------------------------------------------------------- | ------------ | -------------------------------- | -| variant | core's values; `body`; `surface` | the card's fill: core's card, muted and palette fills, and on React Native the theme's page and surface backgrounds | every card | `default` | `component:Card`; `body` and `surface`: `component:react-native/Card` | experimental | an unknown value is a type error | +| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior | +| ------- | ----------------------- | ------- | ----------------------------------------- | ------- | ----- | --------- | ---------------------- | ## Behavioral and layout contract Draft requirements identify their basis so observed code is not mistaken for an intentional decision. A `current` contract contains no unresolved rows. -| ID | Candidate invariant | Basis | Draft review state | -| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------ | -| FR1 | React Native's `Card` MUST take core's `children`, `padding`, `variant` and `elevation` with core's names, meaning and defaults. `children` takes React content, as a platform contract whose implementation runs React may (`spec:AST-082` FR4). Base props are `id` and `isHidden` (`spec:AST-082` FR7) on the card's container, the part core's target sits on. It MUST NOT offer core's `width`, `height`, `maxWidth` or `minHeight` (DEC-1). | `component:Card`; `spec:AST-082` FR3, FR4, FR7; DEC-1 | verify | -| FR2 | `variant` MUST paint as `component:Card` FR2 states: `default` the card background with the theme's border, `transparent` nothing, `muted` the muted background, and each palette value its own background tint, with the corners of the theme's container radius. React Native adds `body` and `surface` (DEC-2), which paint the theme's page background and surface background with `default`'s border and its inset rule. A theme's own variant name paints the base surface, never another variant. | `component:Card` FR2; `architecture:component-theming-surface`; DEC-2 | verify | -| FR3 | `padding` MUST resolve and publish as `component:Card` FR3 states: an omitted `padding` takes the theme's card padding, spacing step 4 with none; a step applies to every edge; a bordered card reduces each edge by the theme's border width, never below zero; and the card publishes its inset to what it holds, so a `Layout` or a full-bleed `Divider` inside it meets its edges (`architecture:container-padding` INV11). | `component:Card` FR3; `architecture:container-padding` INV11 | verify | -| FR4 | The card MUST have no minimum width, so it shrinks in a row instead of holding the row at its content's width, and MUST clip what does not fit; it never scrolls. Its size comes from the layout around it: a `Stack`, a `StackItem` or the parent view (DEC-1). Inside a `Carousel` item, the card fills the item's height, so a row of cards is even. | `component:Card` FR4; DEC-1 | verify | -| FR5 | Bare words in `children` MUST render as body text in the theme's body type and text colour, since React Native draws words only inside a text view. Other content renders as given. | `component:Card`; `spec:AST-082` FR4 | verify | -| FR6 | The card MUST NOT be an accessibility element: it has no role, name or focus stop of its own, and VoiceOver and TalkBack reach the things it holds one by one (`component:Card` AR1). It announces nothing. | `component:Card` AR1 | verify | -| FR7 | `elevation` MUST cast no shadow for `none` and the theme's low, medium or high shadow for the other values (`component:Card` FR5). The theme's component overrides for Card apply over the card's own styles. | `component:Card` FR5; `architecture:component-theming-surface` | verify | +| ID | Candidate invariant | Basis | Draft review state | +| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ | +| FR1 | React Native's `Card` MUST take core's `children`, `padding`, `variant` and `elevation` with core's names, meaning and defaults. `children` takes React content, as a platform contract whose implementation runs React may (`spec:AST-082` FR4). Base props are `id` and `isHidden` (`spec:AST-082` FR7) on the card's container, the part core's target sits on. It MUST NOT offer core's `width`, `height`, `maxWidth` or `minHeight` (DEC-1). | `component:Card` FR2, FR3, FR5; `spec:AST-082` FR3, FR4, FR7; DEC-1 | verify | +| FR2 | `variant` MUST paint as `component:Card` FR2 states: `default` the card background with the theme's border, `transparent` nothing, `muted` the muted background, and each palette value its own background tint, with the corners of the theme's container radius. A theme's own variant name paints the base surface, never another variant. React Native offers no variant core does not have (`spec:AST-082` DEC-2). | `component:Card` FR2; `spec:AST-082` DEC-2; `architecture:component-theming-surface` | verify | +| FR3 | `padding` MUST resolve and publish as `component:Card` FR3 states: an omitted `padding` takes spacing step 4, or the padding a platform entry's `components` override for Card sets (`spec:AST-082` FR10); a step applies to every edge; a bordered card reduces each edge by the theme's border width, never below zero; and the card publishes its inset to what it holds, so a `Layout` or a full-bleed `Divider` inside it meets its edges (`architecture:container-padding` INV11). | `component:Card` FR3; `spec:AST-082` FR10; `architecture:container-padding` INV11 | verify | +| FR4 | The card MUST have no minimum width, so it shrinks in a row instead of holding the row at its content's width, and MUST clip what does not fit; it never scrolls. Its size comes from the layout around it: a `Stack`, a `StackItem` or the parent view (DEC-1). | `component:Card` FR4; DEC-1 | verify | +| FR5 | Bare words in `children` MUST render as body text in the theme's body type and text colour, since React Native draws words only inside a text view. Other content renders as given. | proposal; `spec:AST-082` FR4 | verify | +| FR6 | The card MUST NOT be an accessibility element: it has no role, name or focus stop of its own, and VoiceOver and TalkBack reach the things it holds one by one (`component:Card` AR1). It announces nothing. | `component:Card` AR1 | verify | +| FR7 | `elevation` MUST cast no shadow for `none` and the theme's low, medium or high shadow for the other values (`component:Card` FR5). A platform entry's `components` override for Card (`spec:AST-082` FR10) applies over the card's own styles. | `component:Card` FR5; `spec:AST-082` FR10 | verify | ### Allowed variation - **AV1 — Theme paint.** A theme may change the card's fills, border, corners, - shadows and padding through its tokens and its component overrides for Card, - without changing the card's structure or semantics. + shadows and padding through its tokens and a platform entry's `components` + override for Card (`spec:AST-082` FR10), without changing the card's + structure or semantics. ### Representative states -| State | Required invariant | Allowed variation | -| --------------------------- | -------------------------------------------------------- | ----------------- | -| `default`, padding omitted | card background, border inside the theme's card padding | theme paint | -| `padding={0}` | content meets the card's edges | none | -| `body` in a surface section | the page background with `default`'s border | theme paint | -| a theme variant | the base surface | theme paint | -| in a narrow row | shrinks below its content width; clips | none | -| bare words | body text | none | -| with a screen reader | the card's content, one thing at a time; no card element | none | +| State | Required invariant | Allowed variation | +| -------------------------- | -------------------------------------------------------- | ----------------- | +| `default`, padding omitted | card background, border inside spacing step 4 | theme paint | +| `padding={0}` | content meets the card's edges | none | +| a theme variant | the base surface | theme paint | +| in a narrow row | shrinks below its content width; clips | none | +| bare words | body text | none | +| with a screen reader | the card's content, one thing at a time; no card element | none | ### Transformation and precedence order -- **ORD1 — Padding.** `padding`, then the theme's card padding, then step 4 - (`component:Card` FR3). -- **ORD2 — Styles.** The card's own styles, then the theme's component - overrides for Card. +- **ORD1 — Padding.** `padding`, then a platform entry's `components` + override for Card, then step 4 (`component:Card` FR3). +- **ORD2 — Styles.** The card's own styles, then a platform entry's + `components` override for Card. ### Performance and resources @@ -149,7 +147,7 @@ intentional decision. A `current` contract contains no unresolved rows. | ---------------- | ------------------------------------------------------------ | ------------------------ | -------------- | ------------------ | | Surface | the variant's fill, the container radius, `default`'s border | theme intent | container | FR2 | | Shadow | the elevation's shadow | theme intent | supporting | FR7 | -| Padding | the spacing step or the theme's card padding | theme intent | container | FR3 | +| Padding | the spacing step, or a platform entry's override for Card | theme intent | container | FR3 | The component implements design requirements without copying their rationale. @@ -159,11 +157,10 @@ React Native does not draw, so the card is a React Native `View` drawn from the theme. Theme values read (`spec:AST-093` FR4): `color.backgroundCard`, -`color.backgroundMuted`, the palette background colours, `color.backgroundBody` -and `color.backgroundSurface`, the border colour and width, -`radius.container`, the `space` steps and the theme's card padding, the -`shadow.low`, `shadow.med` and `shadow.high` layers, the body type and text -colour, and the theme's component overrides for Card. +`color.backgroundMuted`, the palette background colours, the border colour and +width, `radius.container`, the `space` steps, the `shadow.low`, `shadow.med` +and `shadow.high` layers, the body type and text colour, and a platform +entry's `components` override for Card (`spec:AST-082` FR10). ## Family and system relationships @@ -175,13 +172,13 @@ colour, and the theme's component overrides for Card. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| -------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -| FR1 | Type tests against core's Card contract and each platform's types | each core prop; the sizing props | a sizing prop that type-checks, or a renamed core prop, fails | `audit:react-native/Card/api` | -| FR2, FR7, ORD2 | Unit tests of the frame with two themes | each variant; `body`; `surface`; a theme variant; each elevation; a theme override | a variant painted with another's fill, a border on a variant core draws without one, or an override that does not apply fails | `audit:react-native/Card/surface` | -| FR3, ORD1 | Unit tests of padding and the published inset | omitted; each step; `0`; a `default` and a `muted` card; a `Layout` inside | a padding off the step, a lost publication, or an inset that differs from core's fails | `audit:react-native/Card/padding` | -| FR4, FR5 | Unit tests of placement and content | a narrow row; a `Carousel` item; bare words; a view | a card that holds its row, a card that scrolls, or bare words that do not render fails | `audit:react-native/Card/layout` | -| FR6, AR1, AR2 | VoiceOver and TalkBack checks; unit tests of the accessibility props | a card with text and a button | a card element, a role or label on the card, or content the screen reader skips fails | `audit:react-native/Card/a11y` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | +| FR1 | Type tests against core's Card contract and each platform's types | each core prop; the sizing props | a sizing prop that type-checks, or a renamed core prop, fails | `audit:react-native/Card/api` | +| FR2, FR7, ORD2 | Unit tests of the frame with two themes | each variant; a theme variant; each elevation; a platform entry's `components` override for Card | a variant painted with another's fill, a border on a variant core draws without one, or an override that does not apply fails | `audit:react-native/Card/surface` | +| FR3, ORD1 | Unit tests of padding and the published inset | omitted; omitted with a platform override; each step; `0`; a `default` and a `muted` card; a `Layout` inside | a padding off the step, a lost publication, or an inset that differs from core's fails | `audit:react-native/Card/padding` | +| FR4, FR5 | Unit tests of placement and content | a narrow row; bare words; a view | a card that holds its row, a card that scrolls, or bare words that do not render fails | `audit:react-native/Card/layout` | +| FR6, AR1, AR2 | VoiceOver and TalkBack checks; unit tests of the accessibility props; captures at the default and largest text sizes | a card with text and a button; bare words at the largest Dynamic Type size and Android font scale | a card element, a role or label on the card, content the screen reader skips, bare words that do not scale, or a card that clips grown text fails | `audit:react-native/Card/a11y` | ## Decision log @@ -190,31 +187,18 @@ colour, and the theme's component overrides for Card. **Reference:** `component:react-native/Card/DEC-1` **Decider:** imdreamrunner, 2026-11-18 -Core's `width`, `height`, `maxWidth` and `minHeight` take a `SizeValue`: a -number of pixels or a CSS length string, such as a percentage, `rem` or -`calc()`, that React Native does not read (`spec:AST-082` FR4). On the web a -card's width in a row is already only a preference that a `StackItem` holds; -on React Native the `Stack`, the `StackItem` or the parent view sizes the card, -so the sizing props stay in the web contract and a card never offers a size it -lays out differently. - -### DEC-2 — React Native cards take the page and surface backgrounds - -**Reference:** `component:react-native/Card/DEC-2` -**Decider:** imdreamrunner, 2026-11-18 - -A checkout card on the page's colour inside a surface section needs the -theme's page or surface background. The web reaches those backgrounds through -a custom style on the card, which React Native's contract has no form for, so -React Native's `variant` adds `body` and `surface`, which read the theme's -background roles and stay bordered like `default` (`spec:AST-082` FR5). +Core's `width`, `height`, `maxWidth` and `minHeight` take a `SizeValue`, a +number of pixels or any CSS length string. React Native reads numbers and +percentages but not lengths such as `rem`, `vh` or `calc()`, so it cannot +honour the whole `SizeValue`, and a platform never offers a prop it honours +only in part (`spec:AST-082` FR3). On the web a card's width in a row is +already only a preference that a `StackItem` holds; on React Native the +`Stack`, the `StackItem` or the parent view sizes the card, so the sizing props +stay in the web contract. ## Open questions -- **OQ1 — Do `body` and `surface` join core's `variant`?** (`human-api`) - Options: core adds them for every platform, so the web reaches the page and - surface backgrounds without a custom style; or they stay values of React - Native's contract (DEC-2). +None. ## Content boundary From a9f40c49bb697f335efb1dd774e508a9c96c52d0 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:04:55 -0800 Subject: [PATCH 3/5] spec(Card): explicit padding wins over a platform override; guideline pages --- .../components/Card/Card.react-native.spec.md | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/specs/components/Card/Card.react-native.spec.md b/docs/specs/components/Card/Card.react-native.spec.md index 20c4011ce1da4..db7e968618201 100644 --- a/docs/specs/components/Card/Card.react-native.spec.md +++ b/docs/specs/components/Card/Card.react-native.spec.md @@ -93,15 +93,15 @@ Consumer migration instructions belong in consumer docs and release notes. Draft requirements identify their basis so observed code is not mistaken for an intentional decision. A `current` contract contains no unresolved rows. -| ID | Candidate invariant | Basis | Draft review state | -| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ | -| FR1 | React Native's `Card` MUST take core's `children`, `padding`, `variant` and `elevation` with core's names, meaning and defaults. `children` takes React content, as a platform contract whose implementation runs React may (`spec:AST-082` FR4). Base props are `id` and `isHidden` (`spec:AST-082` FR7) on the card's container, the part core's target sits on. It MUST NOT offer core's `width`, `height`, `maxWidth` or `minHeight` (DEC-1). | `component:Card` FR2, FR3, FR5; `spec:AST-082` FR3, FR4, FR7; DEC-1 | verify | -| FR2 | `variant` MUST paint as `component:Card` FR2 states: `default` the card background with the theme's border, `transparent` nothing, `muted` the muted background, and each palette value its own background tint, with the corners of the theme's container radius. A theme's own variant name paints the base surface, never another variant. React Native offers no variant core does not have (`spec:AST-082` DEC-2). | `component:Card` FR2; `spec:AST-082` DEC-2; `architecture:component-theming-surface` | verify | -| FR3 | `padding` MUST resolve and publish as `component:Card` FR3 states: an omitted `padding` takes spacing step 4, or the padding a platform entry's `components` override for Card sets (`spec:AST-082` FR10); a step applies to every edge; a bordered card reduces each edge by the theme's border width, never below zero; and the card publishes its inset to what it holds, so a `Layout` or a full-bleed `Divider` inside it meets its edges (`architecture:container-padding` INV11). | `component:Card` FR3; `spec:AST-082` FR10; `architecture:container-padding` INV11 | verify | -| FR4 | The card MUST have no minimum width, so it shrinks in a row instead of holding the row at its content's width, and MUST clip what does not fit; it never scrolls. Its size comes from the layout around it: a `Stack`, a `StackItem` or the parent view (DEC-1). | `component:Card` FR4; DEC-1 | verify | -| FR5 | Bare words in `children` MUST render as body text in the theme's body type and text colour, since React Native draws words only inside a text view. Other content renders as given. | proposal; `spec:AST-082` FR4 | verify | -| FR6 | The card MUST NOT be an accessibility element: it has no role, name or focus stop of its own, and VoiceOver and TalkBack reach the things it holds one by one (`component:Card` AR1). It announces nothing. | `component:Card` AR1 | verify | -| FR7 | `elevation` MUST cast no shadow for `none` and the theme's low, medium or high shadow for the other values (`component:Card` FR5). A platform entry's `components` override for Card (`spec:AST-082` FR10) applies over the card's own styles. | `component:Card` FR5; `spec:AST-082` FR10 | verify | +| ID | Candidate invariant | Basis | Draft review state | +| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------ | +| FR1 | React Native's `Card` MUST take core's `children`, `padding`, `variant` and `elevation` with core's names, meaning and defaults. `children` takes React content, as a platform contract whose implementation runs React may (`spec:AST-082` FR4). Base props are `id` and `isHidden` (`spec:AST-082` FR7) on the card's container, the part core's target sits on. It MUST NOT offer core's `width`, `height`, `maxWidth` or `minHeight` (DEC-1). | `component:Card` FR2, FR3, FR5; `spec:AST-082` FR3, FR4, FR7; DEC-1 | verify | +| FR2 | `variant` MUST paint as `component:Card` FR2 states: `default` the card background with the theme's border, `transparent` nothing, `muted` the muted background, and each palette value its own background tint, with the corners of the theme's container radius. A theme's own variant name paints the base surface, never another variant. React Native offers no variant core does not have (`spec:AST-082` DEC-2). | `component:Card` FR2; `spec:AST-082` DEC-2; `architecture:component-theming-surface` INV14 | verify | +| FR3 | `padding` MUST resolve and publish as `component:Card` FR3 states: an omitted `padding` takes spacing step 4, or the padding a platform entry's `components` override for Card sets (`spec:AST-082` FR10); a step applies to every edge; a bordered card reduces each edge by the theme's border width, never below zero; and the card publishes its inset to what it holds, so a `Layout` or a full-bleed `Divider` inside it meets its edges (`architecture:container-padding` INV11). | `component:Card` FR3; `spec:AST-082` FR10; `architecture:container-padding` INV11 | verify | +| FR4 | The card MUST have no minimum width, so it shrinks in a row instead of holding the row at its content's width, and MUST clip what does not fit; it never scrolls. Its size comes from the layout around it: a `Stack`, a `StackItem` or the parent view (DEC-1). | `component:Card` FR4; DEC-1 | verify | +| FR5 | Bare words in `children` MUST render as body text in the theme's body type and text colour, since React Native draws words only inside a text view. Other content renders as given. | proposal; `spec:AST-082` FR4 | verify | +| FR6 | The card MUST NOT be an accessibility element: it has no role, name or focus stop of its own, and VoiceOver and TalkBack reach the things it holds one by one (`component:Card` AR1). It announces nothing. | `component:Card` AR1 | verify | +| FR7 | `elevation` MUST cast no shadow for `none` and the theme's low, medium or high shadow for the other values (`component:Card` FR5). A platform entry's `components` override for Card (`spec:AST-082` FR10) applies over the card's own styles, except its padding, which follows ORD1: an explicit `padding` wins over it. | `component:Card` FR5; `spec:AST-082` FR10 | verify | ### Allowed variation @@ -126,7 +126,8 @@ intentional decision. A `current` contract contains no unresolved rows. - **ORD1 — Padding.** `padding`, then a platform entry's `components` override for Card, then step 4 (`component:Card` FR3). - **ORD2 — Styles.** The card's own styles, then a platform entry's - `components` override for Card. + `components` override for Card; padding follows ORD1, so an explicit + `padding` wins over the override (`component:Card` FR3). ### Performance and resources @@ -154,7 +155,8 @@ The component implements design requirements without copying their rationale. Platform control (`spec:AST-093` FR2): none. React Native has no card view, and SwiftUI's grouped backgrounds and Android's card views are native views React Native does not draw, so the card is a React Native `View` drawn from -the theme. +the theme. Guideline pages: Layout, Typography and Accessibility (Dynamic +Type, VoiceOver) in the Apple Human Interface Guidelines (`spec:AST-093` FR3). Theme values read (`spec:AST-093` FR4): `color.backgroundCard`, `color.backgroundMuted`, the palette background colours, the border colour and From 40ef15435af343df84b6d0a7c9ba782d4942e1ed Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:30:21 -0800 Subject: [PATCH 4/5] spec(Card): sizing props keep their number form; CSS lengths stay web --- .../components/Card/Card.react-native.spec.md | 88 ++++++++++--------- 1 file changed, 46 insertions(+), 42 deletions(-) diff --git a/docs/specs/components/Card/Card.react-native.spec.md b/docs/specs/components/Card/Card.react-native.spec.md index db7e968618201..86c1ffc683b9b 100644 --- a/docs/specs/components/Card/Card.react-native.spec.md +++ b/docs/specs/components/Card/Card.react-native.spec.md @@ -30,15 +30,15 @@ system_specs: [spec:AST-082, spec:AST-093] ## Contract at a glance -| Area | Contract | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | React Native exports `Card` under core's name with core's `children`, `padding`, `variant` and `elevation`, with core's meaning and defaults. Core's `width`, `height`, `maxWidth` and `minHeight` stay in the web contract (DEC-1). | -| Behavior | A rounded surface from the theme that holds one discrete item: it paints its variant, draws `default`'s border inside its padding, casts its elevation's shadow, publishes its padding to what it holds, clips what does not fit, and turns bare words into body text. | -| End-user impact | A person sees grouped content on the same surface as on the web, with insets on the spacing scale; a screen reader reads what the card holds, not the card. | -| Builder impact | An app writes the same `Card` call site as on the web; its size comes from the layout around it. | -| Compatibility/readiness | Not yet released; additive. Draft. The core and web contracts are unchanged. | -| Review checks | Reject a card that becomes an accessibility element, a variant that falls through to another variant, a variant core does not have, a lost padding publication, bare words that fail to render, a sizing prop accepted and ignored, a visual value not taken from the theme, or a native dependency. | -| Governing rules | `component:Card` FR2, FR3, FR5 and AR1; `architecture:container-padding` INV11; `architecture:component-theming-surface`; `spec:AST-082` FR3, FR4, FR7, FR10 and DEC-2; `spec:AST-093` FR2, FR4 and FR5; DEC-1 below. | +| Area | Contract | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | React Native exports `Card` under core's name with core's `children`, `padding`, `variant` and `elevation`, with core's meaning and defaults, and core's `width`, `height`, `maxWidth` and `minHeight` in their number form, points or dp. Their CSS length strings stay in the web contract (DEC-1). | +| Behavior | A rounded surface from the theme that holds one discrete item: it paints its variant, draws `default`'s border inside its padding, casts its elevation's shadow, publishes its padding to what it holds, clips what does not fit, and turns bare words into body text. | +| End-user impact | A person sees grouped content on the same surface as on the web, with insets on the spacing scale; a screen reader reads what the card holds, not the card. | +| Builder impact | An app writes the same `Card` call site as on the web; a number size applies as given, and without one the layout around the card sizes it. | +| Compatibility/readiness | Not yet released; additive. Draft. The web contract is unchanged. The core form of the four sizing props is their number values, with CSS length strings in the web contract (`spec:AST-082` FR4, DEC-12); recording that split is a `component:Card` change. | +| Review checks | Reject a card that becomes an accessibility element, a variant that falls through to another variant, a variant core does not have, a lost padding publication, bare words that fail to render, a number size that does not apply, a CSS length string accepted, a visual value not taken from the theme, or a native dependency. | +| Governing rules | `component:Card` FR2–FR5 and AR1; `architecture:container-padding` INV11; `architecture:component-theming-surface`; `spec:AST-082` FR3, FR4, FR7, FR10, DEC-2 and DEC-12; `spec:AST-093` FR2, FR4 and FR5; DEC-1 below. | This table is a review projection; the body below is authoritative. @@ -61,6 +61,8 @@ Consumer migration instructions belong in consumer docs and release notes. ## Current-state impact +- FR1 gap: the package's Card does not offer `width`, `height`, `maxWidth` or + `minHeight`. - FR2 gap: the package's Card also takes the `variant` values `body` and `surface`, the theme's page and surface backgrounds. @@ -81,7 +83,10 @@ Consumer migration instructions belong in consumer docs and release notes. - A card that acts as one control — owned by `component:ClickableCard` and `component:SelectableCard`. - A page region — owned by `component:Section`. -- A card's size in a row — owned by the stack around it. +- A card's size in a row without a number size — owned by the stack around + it. +- Recording the sizing props' split into a number core form and web CSS + strings — owned by `component:Card`. ## Public concepts @@ -93,15 +98,15 @@ Consumer migration instructions belong in consumer docs and release notes. Draft requirements identify their basis so observed code is not mistaken for an intentional decision. A `current` contract contains no unresolved rows. -| ID | Candidate invariant | Basis | Draft review state | -| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------ | -| FR1 | React Native's `Card` MUST take core's `children`, `padding`, `variant` and `elevation` with core's names, meaning and defaults. `children` takes React content, as a platform contract whose implementation runs React may (`spec:AST-082` FR4). Base props are `id` and `isHidden` (`spec:AST-082` FR7) on the card's container, the part core's target sits on. It MUST NOT offer core's `width`, `height`, `maxWidth` or `minHeight` (DEC-1). | `component:Card` FR2, FR3, FR5; `spec:AST-082` FR3, FR4, FR7; DEC-1 | verify | -| FR2 | `variant` MUST paint as `component:Card` FR2 states: `default` the card background with the theme's border, `transparent` nothing, `muted` the muted background, and each palette value its own background tint, with the corners of the theme's container radius. A theme's own variant name paints the base surface, never another variant. React Native offers no variant core does not have (`spec:AST-082` DEC-2). | `component:Card` FR2; `spec:AST-082` DEC-2; `architecture:component-theming-surface` INV14 | verify | -| FR3 | `padding` MUST resolve and publish as `component:Card` FR3 states: an omitted `padding` takes spacing step 4, or the padding a platform entry's `components` override for Card sets (`spec:AST-082` FR10); a step applies to every edge; a bordered card reduces each edge by the theme's border width, never below zero; and the card publishes its inset to what it holds, so a `Layout` or a full-bleed `Divider` inside it meets its edges (`architecture:container-padding` INV11). | `component:Card` FR3; `spec:AST-082` FR10; `architecture:container-padding` INV11 | verify | -| FR4 | The card MUST have no minimum width, so it shrinks in a row instead of holding the row at its content's width, and MUST clip what does not fit; it never scrolls. Its size comes from the layout around it: a `Stack`, a `StackItem` or the parent view (DEC-1). | `component:Card` FR4; DEC-1 | verify | -| FR5 | Bare words in `children` MUST render as body text in the theme's body type and text colour, since React Native draws words only inside a text view. Other content renders as given. | proposal; `spec:AST-082` FR4 | verify | -| FR6 | The card MUST NOT be an accessibility element: it has no role, name or focus stop of its own, and VoiceOver and TalkBack reach the things it holds one by one (`component:Card` AR1). It announces nothing. | `component:Card` AR1 | verify | -| FR7 | `elevation` MUST cast no shadow for `none` and the theme's low, medium or high shadow for the other values (`component:Card` FR5). A platform entry's `components` override for Card (`spec:AST-082` FR10) applies over the card's own styles, except its padding, which follows ORD1: an explicit `padding` wins over it. | `component:Card` FR5; `spec:AST-082` FR10 | verify | +| ID | Candidate invariant | Basis | Draft review state | +| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------ | +| FR1 | React Native's `Card` MUST take core's `children`, `padding`, `variant` and `elevation`, and `width`, `height`, `maxWidth` and `minHeight` in their number form, with core's names, meaning and defaults. `children` takes React content, as a platform contract whose implementation runs React may (`spec:AST-082` FR4). A size is a number of points on iOS and dp on Android, and applies as given, as core's number values do in pixels. Base props are `id` and `isHidden` (`spec:AST-082` FR7) on the card's container, the part core's target sits on. It MUST NOT offer the sizing props' CSS length strings (DEC-1). | `component:Card` FR2–FR5; `spec:AST-082` FR3, FR4, FR7, DEC-12; DEC-1 | verify | +| FR2 | `variant` MUST paint as `component:Card` FR2 states: `default` the card background with the theme's border, `transparent` nothing, `muted` the muted background, and each palette value its own background tint, with the corners of the theme's container radius. A theme's own variant name paints the base surface, never another variant. React Native offers no variant core does not have (`spec:AST-082` DEC-2). | `component:Card` FR2; `spec:AST-082` DEC-2; `architecture:component-theming-surface` INV14 | verify | +| FR3 | `padding` MUST resolve and publish as `component:Card` FR3 states: an omitted `padding` takes spacing step 4, or the padding a platform entry's `components` override for Card sets (`spec:AST-082` FR10); a step applies to every edge; a bordered card reduces each edge by the theme's border width, never below zero; and the card publishes its inset to what it holds, so a `Layout` or a full-bleed `Divider` inside it meets its edges (`architecture:container-padding` INV11). | `component:Card` FR3; `spec:AST-082` FR10; `architecture:container-padding` INV11 | verify | +| FR4 | The card MUST have no minimum width, so it shrinks in a row instead of holding the row at its content's width. A number `width`, `height`, `maxWidth` or `minHeight` applies as given, and a caller minimum wins over `width`, as in core; without one, the layout around the card sizes it: a `Stack`, a `StackItem` or the parent view. Where that layout leaves room, the card grows with its content, so grown text stays whole; it clips only what a fixed size or the layout leaves no room for, and it never scrolls. | `component:Card` FR4; DEC-1 | verify | +| FR5 | Bare words in `children` MUST render as body text in the theme's body type and text colour, since React Native draws words only inside a text view. Other content renders as given. | proposal; `spec:AST-082` FR4 | verify | +| FR6 | The card MUST NOT be an accessibility element: it has no role, name or focus stop of its own, and VoiceOver and TalkBack reach the things it holds one by one (`component:Card` AR1). It announces nothing. | `component:Card` AR1 | verify | +| FR7 | `elevation` MUST cast no shadow for `none` and the theme's low, medium or high shadow for the other values (`component:Card` FR5). A platform entry's `components` override for Card (`spec:AST-082` FR10) applies over the card's own styles, except its padding, which follows ORD1: an explicit `padding` wins over it. | `component:Card` FR5; `spec:AST-082` FR10 | verify | ### Allowed variation @@ -112,14 +117,14 @@ intentional decision. A `current` contract contains no unresolved rows. ### Representative states -| State | Required invariant | Allowed variation | -| -------------------------- | -------------------------------------------------------- | ----------------- | -| `default`, padding omitted | card background, border inside spacing step 4 | theme paint | -| `padding={0}` | content meets the card's edges | none | -| a theme variant | the base surface | theme paint | -| in a narrow row | shrinks below its content width; clips | none | -| bare words | body text | none | -| with a screen reader | the card's content, one thing at a time; no card element | none | +| State | Required invariant | Allowed variation | +| -------------------------- | ------------------------------------------------------------ | ----------------- | +| `default`, padding omitted | card background, border inside spacing step 4 | theme paint | +| `padding={0}` | content meets the card's edges | none | +| a theme variant | the base surface | theme paint | +| in a narrow row | shrinks below its content width; clips only what has no room | none | +| bare words | body text | none | +| with a screen reader | the card's content, one thing at a time; no card element | none | ### Transformation and precedence order @@ -174,29 +179,28 @@ entry's `components` override for Card (`spec:AST-082` FR10). ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -| FR1 | Type tests against core's Card contract and each platform's types | each core prop; the sizing props | a sizing prop that type-checks, or a renamed core prop, fails | `audit:react-native/Card/api` | -| FR2, FR7, ORD2 | Unit tests of the frame with two themes | each variant; a theme variant; each elevation; a platform entry's `components` override for Card | a variant painted with another's fill, a border on a variant core draws without one, or an override that does not apply fails | `audit:react-native/Card/surface` | -| FR3, ORD1 | Unit tests of padding and the published inset | omitted; omitted with a platform override; each step; `0`; a `default` and a `muted` card; a `Layout` inside | a padding off the step, a lost publication, or an inset that differs from core's fails | `audit:react-native/Card/padding` | -| FR4, FR5 | Unit tests of placement and content | a narrow row; bare words; a view | a card that holds its row, a card that scrolls, or bare words that do not render fails | `audit:react-native/Card/layout` | -| FR6, AR1, AR2 | VoiceOver and TalkBack checks; unit tests of the accessibility props; captures at the default and largest text sizes | a card with text and a button; bare words at the largest Dynamic Type size and Android font scale | a card element, a role or label on the card, content the screen reader skips, bare words that do not scale, or a card that clips grown text fails | `audit:react-native/Card/a11y` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | +| FR1 | Type tests against core's Card contract and each platform's types | each core prop; a number size for each sizing prop; a CSS length string for each | a CSS length string that type-checks, a number size refused, or a renamed core prop fails | `audit:react-native/Card/api` | +| FR2, FR7, ORD2 | Unit tests of the frame with two themes | each variant; a theme variant; each elevation; a platform entry's `components` override for Card | a variant painted with another's fill, a border on a variant core draws without one, or an override that does not apply fails | `audit:react-native/Card/surface` | +| FR3, ORD1 | Unit tests of padding and the published inset | omitted; omitted with a platform override; an explicit `padding` with a platform override; each step; `0`; a `default` and a `muted` card; a `Layout` inside | a padding off the step, an override that replaces an explicit `padding`, a lost publication, or an inset that differs from core's fails | `audit:react-native/Card/padding` | +| FR4, FR5 | Unit tests of placement, sizes and content | a narrow row; each number size; `minHeight` with a smaller `width`; content taller than a fixed `height`; bare words; a view | a card that holds its row, a number size that does not apply, a card that scrolls, or bare words that do not render fails | `audit:react-native/Card/layout` | +| FR6, AR1, AR2 | VoiceOver and TalkBack checks; unit tests of the accessibility props; captures at the default and largest text sizes | a card with text and a button; bare words at the largest Dynamic Type size and Android font scale | a card element, a role or label on the card, content the screen reader skips, bare words that do not scale, or a card that clips grown text fails | `audit:react-native/Card/a11y` | ## Decision log -### DEC-1 — A card's size comes from the layout around it +### DEC-1 — Sizing props take their number form on React Native **Reference:** `component:react-native/Card/DEC-1` **Decider:** imdreamrunner, 2026-11-18 Core's `width`, `height`, `maxWidth` and `minHeight` take a `SizeValue`, a -number of pixels or any CSS length string. React Native reads numbers and -percentages but not lengths such as `rem`, `vh` or `calc()`, so it cannot -honour the whole `SizeValue`, and a platform never offers a prop it honours -only in part (`spec:AST-082` FR3). On the web a card's width in a row is -already only a preference that a `StackItem` holds; on React Native the -`Stack`, the `StackItem` or the parent view sizes the card, so the sizing props -stay in the web contract. +number of pixels or any CSS length string. React Native draws a number size +but not lengths such as `rem`, `vh` or `calc()`, so its Card keeps the four +props in their number form, a number of points or dp, and their CSS length +strings stay in the web contract. A wider web type keeps its portable values +in the core instead of leaving the prop web-only (`spec:AST-082` FR4, DEC-12), +so a call site with a number size reads the same on every platform. ## Open questions From 7cf7ed48e3e5e40a9ff40e5a0527cad598576669 Mon Sep 17 00:00:00 2001 From: imdreamrunner <2252473+imdreamrunner@users.noreply.github.com> Date: Thu, 19 Nov 2026 01:57:53 -0800 Subject: [PATCH 5/5] spec(Card): a number height scrolls taller content, as core's does; minHeight over height --- .../components/Card/Card.react-native.spec.md | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/specs/components/Card/Card.react-native.spec.md b/docs/specs/components/Card/Card.react-native.spec.md index 86c1ffc683b9b..bb30bb9dfff16 100644 --- a/docs/specs/components/Card/Card.react-native.spec.md +++ b/docs/specs/components/Card/Card.react-native.spec.md @@ -33,7 +33,7 @@ system_specs: [spec:AST-082, spec:AST-093] | Area | Contract | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Public contract | React Native exports `Card` under core's name with core's `children`, `padding`, `variant` and `elevation`, with core's meaning and defaults, and core's `width`, `height`, `maxWidth` and `minHeight` in their number form, points or dp. Their CSS length strings stay in the web contract (DEC-1). | -| Behavior | A rounded surface from the theme that holds one discrete item: it paints its variant, draws `default`'s border inside its padding, casts its elevation's shadow, publishes its padding to what it holds, clips what does not fit, and turns bare words into body text. | +| Behavior | A rounded surface from the theme that holds one discrete item: it paints its variant, draws `default`'s border inside its padding, casts its elevation's shadow, publishes its padding to what it holds, clips content wider than it is, scrolls content taller than a set `height`, and turns bare words into body text. | | End-user impact | A person sees grouped content on the same surface as on the web, with insets on the spacing scale; a screen reader reads what the card holds, not the card. | | Builder impact | An app writes the same `Card` call site as on the web; a number size applies as given, and without one the layout around the card sizes it. | | Compatibility/readiness | Not yet released; additive. Draft. The web contract is unchanged. The core form of the four sizing props is their number values, with CSS length strings in the web contract (`spec:AST-082` FR4, DEC-12); recording that split is a `component:Card` change. | @@ -71,7 +71,7 @@ Consumer migration instructions belong in consumer docs and release notes. **Owns** - Which of core's props React Native offers (FR1). -- How a React Native card holds its content: bare words, clipping and its +- How a React Native card holds its content: bare words, clipping, scrolling and its place in a row (FR4, FR5). - How the card reads to screen readers on React Native (FR6). @@ -98,15 +98,15 @@ Consumer migration instructions belong in consumer docs and release notes. Draft requirements identify their basis so observed code is not mistaken for an intentional decision. A `current` contract contains no unresolved rows. -| ID | Candidate invariant | Basis | Draft review state | -| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------ | -| FR1 | React Native's `Card` MUST take core's `children`, `padding`, `variant` and `elevation`, and `width`, `height`, `maxWidth` and `minHeight` in their number form, with core's names, meaning and defaults. `children` takes React content, as a platform contract whose implementation runs React may (`spec:AST-082` FR4). A size is a number of points on iOS and dp on Android, and applies as given, as core's number values do in pixels. Base props are `id` and `isHidden` (`spec:AST-082` FR7) on the card's container, the part core's target sits on. It MUST NOT offer the sizing props' CSS length strings (DEC-1). | `component:Card` FR2–FR5; `spec:AST-082` FR3, FR4, FR7, DEC-12; DEC-1 | verify | -| FR2 | `variant` MUST paint as `component:Card` FR2 states: `default` the card background with the theme's border, `transparent` nothing, `muted` the muted background, and each palette value its own background tint, with the corners of the theme's container radius. A theme's own variant name paints the base surface, never another variant. React Native offers no variant core does not have (`spec:AST-082` DEC-2). | `component:Card` FR2; `spec:AST-082` DEC-2; `architecture:component-theming-surface` INV14 | verify | -| FR3 | `padding` MUST resolve and publish as `component:Card` FR3 states: an omitted `padding` takes spacing step 4, or the padding a platform entry's `components` override for Card sets (`spec:AST-082` FR10); a step applies to every edge; a bordered card reduces each edge by the theme's border width, never below zero; and the card publishes its inset to what it holds, so a `Layout` or a full-bleed `Divider` inside it meets its edges (`architecture:container-padding` INV11). | `component:Card` FR3; `spec:AST-082` FR10; `architecture:container-padding` INV11 | verify | -| FR4 | The card MUST have no minimum width, so it shrinks in a row instead of holding the row at its content's width. A number `width`, `height`, `maxWidth` or `minHeight` applies as given, and a caller minimum wins over `width`, as in core; without one, the layout around the card sizes it: a `Stack`, a `StackItem` or the parent view. Where that layout leaves room, the card grows with its content, so grown text stays whole; it clips only what a fixed size or the layout leaves no room for, and it never scrolls. | `component:Card` FR4; DEC-1 | verify | -| FR5 | Bare words in `children` MUST render as body text in the theme's body type and text colour, since React Native draws words only inside a text view. Other content renders as given. | proposal; `spec:AST-082` FR4 | verify | -| FR6 | The card MUST NOT be an accessibility element: it has no role, name or focus stop of its own, and VoiceOver and TalkBack reach the things it holds one by one (`component:Card` AR1). It announces nothing. | `component:Card` AR1 | verify | -| FR7 | `elevation` MUST cast no shadow for `none` and the theme's low, medium or high shadow for the other values (`component:Card` FR5). A platform entry's `components` override for Card (`spec:AST-082` FR10) applies over the card's own styles, except its padding, which follows ORD1: an explicit `padding` wins over it. | `component:Card` FR5; `spec:AST-082` FR10 | verify | +| ID | Candidate invariant | Basis | Draft review state | +| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------ | +| FR1 | React Native's `Card` MUST take core's `children`, `padding`, `variant` and `elevation`, and `width`, `height`, `maxWidth` and `minHeight` in their number form, with core's names, meaning and defaults. `children` takes React content, as a platform contract whose implementation runs React may (`spec:AST-082` FR4). A size is a number of points on iOS and dp on Android, and applies as given, as core's number values do in pixels. Base props are `id` and `isHidden` (`spec:AST-082` FR7) on the card's container, the part core's target sits on. It MUST NOT offer the sizing props' CSS length strings (DEC-1). | `component:Card` FR2–FR5; `spec:AST-082` FR3, FR4, FR7, DEC-12; DEC-1 | verify | +| FR2 | `variant` MUST paint as `component:Card` FR2 states: `default` the card background with the theme's border, `transparent` nothing, `muted` the muted background, and each palette value its own background tint, with the corners of the theme's container radius. A theme's own variant name paints the base surface, never another variant. React Native offers no variant core does not have (`spec:AST-082` DEC-2). | `component:Card` FR2; `spec:AST-082` DEC-2; `architecture:component-theming-surface` INV14 | verify | +| FR3 | `padding` MUST resolve and publish as `component:Card` FR3 states: an omitted `padding` takes spacing step 4, or the padding a platform entry's `components` override for Card sets (`spec:AST-082` FR10); a step applies to every edge; a bordered card reduces each edge by the theme's border width, never below zero; and the card publishes its inset to what it holds, so a `Layout` or a full-bleed `Divider` inside it meets its edges (`architecture:container-padding` INV11). | `component:Card` FR3; `spec:AST-082` FR10; `architecture:container-padding` INV11 | verify | +| FR4 | The card MUST have no minimum width, so it shrinks in a row instead of holding the row at its content's width. A number `width`, `height`, `maxWidth` or `minHeight` applies as given, and `minHeight` wins over a smaller `height`; without a size, the layout around the card sizes it: a `Stack`, a `StackItem` or the parent view. Where that layout leaves room, the card grows with its content, so grown text stays whole, and it clips content wider than it is. A number `height` other than the content's own makes the card scroll its content vertically when the content is taller, as core's `height` does (`component:Card` FR4); without a `height` it never scrolls. | `component:Card` FR4; DEC-1 | verify | +| FR5 | Bare words in `children` MUST render as body text in the theme's body type and text colour, since React Native draws words only inside a text view. Other content renders as given. | proposal; `spec:AST-082` FR4 | verify | +| FR6 | The card MUST NOT be an accessibility element: it has no role, name or focus stop of its own, and VoiceOver and TalkBack reach the things it holds one by one (`component:Card` AR1). It announces nothing. | `component:Card` AR1 | verify | +| FR7 | `elevation` MUST cast no shadow for `none` and the theme's low, medium or high shadow for the other values (`component:Card` FR5). A platform entry's `components` override for Card (`spec:AST-082` FR10) applies over the card's own styles, except its padding, which follows ORD1: an explicit `padding` wins over it. | `component:Card` FR5; `spec:AST-082` FR10 | verify | ### Allowed variation @@ -117,14 +117,14 @@ intentional decision. A `current` contract contains no unresolved rows. ### Representative states -| State | Required invariant | Allowed variation | -| -------------------------- | ------------------------------------------------------------ | ----------------- | -| `default`, padding omitted | card background, border inside spacing step 4 | theme paint | -| `padding={0}` | content meets the card's edges | none | -| a theme variant | the base surface | theme paint | -| in a narrow row | shrinks below its content width; clips only what has no room | none | -| bare words | body text | none | -| with a screen reader | the card's content, one thing at a time; no card element | none | +| State | Required invariant | Allowed variation | +| -------------------------- | --------------------------------------------------------------- | ----------------- | +| `default`, padding omitted | card background, border inside spacing step 4 | theme paint | +| `padding={0}` | content meets the card's edges | none | +| a theme variant | the base surface | theme paint | +| in a narrow row | shrinks below its content width; clips content wider than it is | none | +| bare words | body text | none | +| with a screen reader | the card's content, one thing at a time; no card element | none | ### Transformation and precedence order @@ -137,8 +137,8 @@ intentional decision. A `current` contract contains no unresolved rows. ### Performance and resources - **PR1 — No work of its own.** The card holds no timers or listeners; it - computes its frame only when its variant, elevation, padding or theme - changes. + computes its frame only when its variant, elevation, padding, number sizes or + theme changes. ## Accessibility contract @@ -179,13 +179,13 @@ entry's `components` override for Card (`spec:AST-082` FR10). ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -| FR1 | Type tests against core's Card contract and each platform's types | each core prop; a number size for each sizing prop; a CSS length string for each | a CSS length string that type-checks, a number size refused, or a renamed core prop fails | `audit:react-native/Card/api` | -| FR2, FR7, ORD2 | Unit tests of the frame with two themes | each variant; a theme variant; each elevation; a platform entry's `components` override for Card | a variant painted with another's fill, a border on a variant core draws without one, or an override that does not apply fails | `audit:react-native/Card/surface` | -| FR3, ORD1 | Unit tests of padding and the published inset | omitted; omitted with a platform override; an explicit `padding` with a platform override; each step; `0`; a `default` and a `muted` card; a `Layout` inside | a padding off the step, an override that replaces an explicit `padding`, a lost publication, or an inset that differs from core's fails | `audit:react-native/Card/padding` | -| FR4, FR5 | Unit tests of placement, sizes and content | a narrow row; each number size; `minHeight` with a smaller `width`; content taller than a fixed `height`; bare words; a view | a card that holds its row, a number size that does not apply, a card that scrolls, or bare words that do not render fails | `audit:react-native/Card/layout` | -| FR6, AR1, AR2 | VoiceOver and TalkBack checks; unit tests of the accessibility props; captures at the default and largest text sizes | a card with text and a button; bare words at the largest Dynamic Type size and Android font scale | a card element, a role or label on the card, content the screen reader skips, bare words that do not scale, or a card that clips grown text fails | `audit:react-native/Card/a11y` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | +| FR1 | Type tests against core's Card contract and each platform's types | each core prop; a number size for each sizing prop; a CSS length string for each | a CSS length string that type-checks, a number size refused, or a renamed core prop fails | `audit:react-native/Card/api` | +| FR2, FR7, ORD2 | Unit tests of the frame with two themes | each variant; a theme variant; each elevation; a platform entry's `components` override for Card | a variant painted with another's fill, a border on a variant core draws without one, or an override that does not apply fails | `audit:react-native/Card/surface` | +| FR3, ORD1 | Unit tests of padding and the published inset | omitted; omitted with a platform override; an explicit `padding` with a platform override; each step; `0`; a `default` and a `muted` card; a `Layout` inside | a padding off the step, an override that replaces an explicit `padding`, a lost publication, or an inset that differs from core's fails | `audit:react-native/Card/padding` | +| FR4, FR5 | Unit tests of placement, sizes and content | a narrow row; each number size; `minHeight` above a smaller `height`; content taller than a number `height`; bare words; a view | a card that holds its row, a number size that does not apply, a fixed-height card that clips taller content instead of scrolling, a card without a `height` that scrolls, or bare words that do not render fails | `audit:react-native/Card/layout` | +| FR6, AR1, AR2 | VoiceOver and TalkBack checks; unit tests of the accessibility props; captures at the default and largest text sizes | a card with text and a button; bare words at the largest Dynamic Type size and Android font scale | a card element, a role or label on the card, content the screen reader skips, bare words that do not scale, or a card that clips grown text fails | `audit:react-native/Card/a11y` | ## Decision log