An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-012): compact is width below md or height below 500 on every platform (#8274)
Cindy Zhang10ca8eaeecda
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex f914c0d204..db632a68de 100644--- a/docs/architecture/public-component-api.md+++ b/docs/architecture/public-component-api.md@@ -32,6 +32,7 @@ deciding_specs:spec:AST-012/DEC-2,spec:AST-071/DEC-1,spec:AST-017/DEC-23,+ spec:AST-012/DEC-6,]---@@ -165,6 +166,12 @@ guidance owns the process used to propose and test APIs.When a touch default changes a released component's behavior, that`presentation` value is the restoring prop `spec:AST-017` FR3 names(`spec:AST-017/DEC-23`).+- **INV17 — Compact has one shared definition.** A component that chooses a+ presentation by screen size uses the theme's compact definition: width below+ the effective `md` point or height below 500, with the same numbers on every+ platform (`spec:AST-012` FR9). It keeps no compact numbers of its own, as+ INV14 keeps no parallel breakpoint table. A layout width the caller picks,+ such as AppShell's `mobileNav.breakpoint`, follows INV14 instead.This record applies to stable public packages. Lab components are not stablepublic promises until promotion.@@ -199,7 +206,8 @@ public promises until promotion.evidence required by the release process.- A component exposing a named theme width point uses the fixed vocabulary andexclusive upper-edge behavior from `spec:AST-012`; it does not maintain a- parallel hardcoded breakpoint table.+ parallel hardcoded breakpoint table. A component that chooses a presentation+ by screen size uses the compact definition (INV17).- Changes to a family-owned API update the family contract rather than copyingits rule into this record or every component.- A component that accepts or derives a navigation destination follows@@ -227,6 +235,7 @@ public promises until promotion.- `spec:AST-017/DEC-23` — a touch presentation or open-surface touch mode isa default the caller can always override, through one `presentation` propthat also restores the previous surface and mode.+- `spec:AST-012/DEC-6` — compact is one definition, the same on every platform.Transition Action sequencing and pending behavior belong to their component orfamily contract. This record links that owner once it is current; it does not@@ -246,6 +255,7 @@ copy the component matrix.| INV14 | `AppShell.test.tsx` | A component hardcodes a divergent point or treats equality as below || INV15 | Public-API review of the generated declaration inventory | A part or StyleX-typed styling prop ships without class-name and inline-style counterparts on the same element || INV16 | Public-API review of touch presentations plus coarse- and fine-pointer runtime tests | A stable component that presents a different surface or switches an open surface's input mode under a coarse pointer and has no `presentation` value that keeps its fine-pointer surface and mode; such a touch mode callers cannot reach; a default that overrides an explicit caller choice |+| INV17 | Resolver tests at the compact edges plus public-API review | A component that chooses a presentation by screen size with its own numbers, or disagrees with the theme compact definition at width 768 or height 500 || Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices |Known verification gaps:diff --git a/docs/specs/AST-012/spec.md b/docs/specs/AST-012/spec.mdindex f527988f07..a841f8e5b2 100644--- a/docs/specs/AST-012/spec.md+++ b/docs/specs/AST-012/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-09-02+approved_at: 2026-10-24phase: acceptedowners: [cixzhang, rubyycheung, imdreamrunner]affects_architecture:@@ -98,11 +98,13 @@ A breakpoint map alone emits no CSS. Only rules with adaptation values do.base below `sm`; there is no configurable `xs: 0` point. Defining or overridingthe map alone MUST NOT emit CSS.- **FR2 — Conditions are named, closed, and composable.** A `when` object may- contain `width`, `pointer`, `contrast`, and `motion`; fields are ANDed.+ contain `width`, `height`, `pointer`, `contrast`, and `motion`; fields are+ ANDed.`width` accepts `from` and `below` using the five fixed names and MUST containone or both. `from` is inclusive, `below` is exclusive, either edge may beomitted but not both, and a bounded width MUST resolve to `from < below`.- `pointer` accepts `coarse | fine`; `contrast` accepts+ `height` accepts only `{below: 500}`: a viewport height below 500, exclusive,+ the height edge of the FR9 compact definition. `pointer` accepts `coarse | fine`; `contrast` accepts`more | less | no-preference`; `motion` accepts `reduce | no-preference`.Future environment fields require explicit additions to this closed vocabulary.- **FR3 — Rules are named objects.** `adaptations.rules` contains@@ -161,6 +163,20 @@ A breakpoint map alone emits no CSS. Only rules with adaptation values do.`architecture:theme-application`, and with no active theme it uses the FR1defaults. `defaultIsMobile` remains an SSR hint; the client query uses theeffective map after hydration.+- **FR9 — Compact has one definition on every platform.** A screen is compact+ while its viewport width is below the effective `md` point (FR1) or its+ viewport height is below 500. The numbers are the same on every platform: CSS+ pixels on the web, points on iOS, and density-independent pixels on Android;+ native presentations do not map compact to platform size classes. The theme+ exports this one definition, and every resolver that chooses a presentation+ by screen size uses it, including the web touch presentation resolver,+ Selector's `adaptive` presentation, and `@astryxdesign/native`; none keeps+ size numbers of its own. A resolver that also needs a coarse pointer ANDs+ that with compact. Compact governs only the choice of a presentation, such as+ a sheet in place of a popover; a layout width a caller picks, such as+ AppShell's `mobileNav.breakpoint` (FR8), is not compact. Theme `adaptations`+ stay web-only (`spec:AST-082` FR18); native reads the compact numbers from+ the portable theme.- **IR1 — Normalize and reject atomically.** One path validates width breakpoints,named condition fields, width ranges, theme extension, enrolled local-tokennames, and concrete expanded values for both `defineTheme` and@@ -197,8 +213,8 @@ A breakpoint map alone emits no CSS. Only rules with adaptation values do.### Platform support-- Adaptations use viewport-width, primary-pointer, contrast-preference, and- reduced-motion queries within Astryx's browser support floor; there is no+- Adaptations use viewport-width, viewport-height, primary-pointer,+ contrast-preference, and reduced-motion queries within Astryx's browser support floor; there is noJavaScript styling fallback.- Real Chromium MUST verify conditions, nesting, AppShell agreement, and firstpaint. Real Safari MUST verify exclusive width edges and primary-pointer@@ -223,15 +239,25 @@ implemented.Its value resolver, explicit-value preservation, CSS generation/build parity, andextension metadata remain useful implementation evidence.+The theme exports no compact definition, and `when` has no `height` field.+Selector's, MultiSelector's, ContextMenu's, and DropdownMenu's `adaptive`+presentation (MoreMenu forwards to DropdownMenu) and DropdownMenu's compact-touch+sub-menu decisions use `(max-width: 768px) and (pointer: coarse)`, and the+ContextMenu and MoreMenu consumer docs describe it as "768px and below": a coarse-pointer screen exactly 768 pixels wide and at least 500 tall counts as compact, and a landscape phone wider than 768 pixels but under+500 tall does not. Under FR9 the first opens the popover and the+second the bottom sheet; the release note for that change names `presentation`+as the way to keep a surface. `PortableTheme` carries no compact definition, and `@astryxdesign/native` has no compact resolver yet; it adopts FR9 when it gains one.+## Verification-| Contract | Verification | Representative states | Failure signal |-| -------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| FR1–FR3 | Width-breakpoint and condition matrix plus browser boundaries | defaults/overrides; from/below/range; pointer/contrast/motion; multi-field AND; empty/no rules | A point acts as an upper bound, intervals gap/overlap, fields OR together, or an unused map emits CSS. |-| FR4–FR7 | Shared resolver, surface, cascade-order, and extension tests | enrolled/unenrolled local tokens; incomplete scales; finite built-ins; open primitive values absent from root; root-enrolled and rule-only custom values; unresolved shared results; later generated vs earlier explicit leaves; surface collisions | A rule enrolls a local or component value, a valid open value requires a dummy root rule, adaptation validation diverges from root validation, an unresolved result becomes a permanent exemption, or inherited order is lost. |-| FR8 | Theme/AppShell integration | all names/`none`; SSR hint; no/nearest/root/nested theme; exact boundaries | AppShell uses the wrong map, equality, or scope. |-| IR1–IR3 | Runtime/build and CLI positive/negative fixtures | invalid map/range/field; source axis metadata; duplicate `when`; root-restoring rules; finite/open/unresolved component domains; declaration targets; root-enrolled and rule-only custom values; non-CSS token reads | Invalid input writes output, root and adaptation component validation disagree, an independently valid value is forced into root, an adaptation conditionally enrolls a custom value, or tooling misses a rule-only value. |-| IR4 | Generated-module import and size tests | no rules/rules; source/built parent and child; generative/local-token metadata | Breakpoints, rules, order, or metadata disappear; extension diverges; CSS text enters the module; or resolved layers duplicate. |+| Contract | Verification | Representative states | Failure signal |+| ----------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| FR1–FR3 | Width-breakpoint and condition matrix plus browser boundaries | defaults/overrides; from/below/range; pointer/contrast/motion; multi-field AND; empty/no rules | A point acts as an upper bound, intervals gap/overlap, fields OR together, or an unused map emits CSS. |+| FR4–FR7 | Shared resolver, surface, cascade-order, and extension tests | enrolled/unenrolled local tokens; incomplete scales; finite built-ins; open primitive values absent from root; root-enrolled and rule-only custom values; unresolved shared results; later generated vs earlier explicit leaves; surface collisions | A rule enrolls a local or component value, a valid open value requires a dummy root rule, adaptation validation diverges from root validation, an unresolved result becomes a permanent exemption, or inherited order is lost. |+| FR8 | Theme/AppShell integration | all names/`none`; SSR hint; no/nearest/root/nested theme; exact boundaries | AppShell uses the wrong map, equality, or scope. |+| FR2 (height), FR9 | Condition matrix plus resolver tests on web and native | width 767/768 at height 800; width 1024 at height 499/500; overridden `md`; Selector `adaptive`; the web touch resolver; a native resolver | A resolver with its own size numbers or an inclusive edge, a native resolver using platform size classes or different numbers, or a `height` value other than `below: 500` accepted |+| IR1–IR3 | Runtime/build and CLI positive/negative fixtures | invalid map/range/field; source axis metadata; duplicate `when`; root-restoring rules; finite/open/unresolved component domains; declaration targets; root-enrolled and rule-only custom values; non-CSS token reads | Invalid input writes output, root and adaptation component validation disagree, an independently valid value is forced into root, an adaptation conditionally enrolls a custom value, or tooling misses a rule-only value. |+| IR4 | Generated-module import and size tests | no rules/rules; source/built parent and child; generative/local-token metadata | Breakpoints, rules, order, or metadata disappear; extension diverges; CSS text enters the module; or resolved layers duplicate. |## Decision log@@ -305,6 +331,19 @@ validation tighten adaptations automatically.Rejected: adaptation-specific value resolvers, allowlists, unresolved-domainexceptions, and dummy root rules for independently valid values.+### DEC-6 — Compact is one definition on every platform++**Reference:** `spec:AST-012/DEC-6`+**Decider:** `cixzhang`, `2026-10-24`++A phone, a small tablet, and a short landscape window all lack room for an+anchored surface, so compact is width below the `md` point or height below 500. The same numbers on every platform keep one component presenting the same+way on the web and in native code, and one exported definition keeps resolvers+from drifting apart.++Rejected: mapping compact to each platform's size classes, which makes the+same screen compact on one platform and not another.+## Open questionsNone.diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.mdindex 3ba70bf536..7830f8b39a 100644--- a/docs/specs/AST-082-native-first-surfaces/spec.md+++ b/docs/specs/AST-082-native-first-surfaces/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-10-21+approved_at: 2026-10-24phase: acceptedowners: [cixzhang]affects_architecture:@@ -251,7 +251,10 @@ depends only on runtimes it can maintain.that version's controls and materials. A capability newer than the running OSdegrades to the closest earlier platform equivalent or to durable intent, neverto a broken or blank state. Touch targets meet the platform minimum, and text- follows the platform's text-size setting. A native platform is supported only+ follows the platform's text-size setting. When a component chooses between+ presentations by screen size, compact is `spec:AST-012` FR9 in points or+ density-independent pixels, not the platform's size classes; the platform's+ own control still presents the chosen surface. A native platform is supported onlywhen it meets the FR12 criteria on its oldest and newest supported OS versions.- **FR12 — Approaches are compared on one scorecard.** Every candidate way ofbuilding a native platform is measured the same way. Candidates include@@ -363,8 +366,9 @@ depends only on runtimes it can maintain.core contract: an icon is decorative unless it carries a label.- **FR18 — The theme definition has a portable part and a web part.** The- portable entry exports `PortableTheme`: a theme's name, tokens, and theme-local- tokens, each resolvable without CSS to a concrete value per color mode, such as+ portable entry exports `PortableTheme`: a theme's name, tokens, theme-local+ tokens, and the compact definition of `spec:AST-012` FR9 (the effective `md`+ width point and the 500 height edge), each resolvable without CSS to a concrete value per color mode, such asa color, a length in density-independent units, a number, or a font name. Theweb part holds what only the web compiles or renders: component overrides keyedby web theme targets, icon and indicator registries of React elements,@@ -427,8 +431,10 @@ depends only on runtimes it can maintain.- `architecture:theme-compilation` gains the native theme boundary when a nativeplatform ships (INV9, INV10).- `architecture:theme-authoring-contract` gains `PortableTheme` as the portable- part of `DefinedTheme` when the portable entry ships. `DefineThemeInput` and- `DefinedTheme` are unchanged for web callers.+ part of `DefinedTheme` when the portable entry ships. `DefineThemeInput` is+ unchanged for web callers; `DefinedTheme` gains the compact definition+ (`spec:AST-012` FR9) additively, derived from the theme's effective `md` point,+ and is otherwise unchanged.- The `theme` and `cli` consumer docs and every component's documentation gainplatform marking when the first native contract ships.- `@astryxdesign/native` ships on the canary channel with the FR19 wire: the@@ -463,7 +469,7 @@ depends only on runtimes it can maintain.| FR15 | Package metadata and release-channel checks | native package manifest; a stable release; a canary release | The native package is publishable as a stable release before a platform is supported || FR16 | Package-boundary check, plus a native fixture app installed and bundled without `react-dom` or StyleX | an import of the portable entry; an import of a core component or the web theme entry from native; a listed build-time read from a native build script; an unlisted one; a core import of native; a core contract change | Native resolves a DOM type, `react-dom`, StyleX, or a web module; either direction of the boundary is crossed, an unlisted build-time read passes; or a core contract change does not reach native contracts on the next build || FR17 | Icon map coverage check per native platform, plus override resolution tests | every built-in name; a namespaced name; a theme platform icon with and without a version range; an app-registered icon; an icon slot given an unknown name in a development and a release build; an asset icon the app ships and one it does not; a missing asset icon in a development and a release build | A built-in name has no platform default, a theme or app icon fails to replace the default, a scoped icon applies outside its range, a web icon is substituted, or an unknown name draws something in a release build or does not stop a development build with its name, or a missing asset icon draws a substitute, or a development build does not stop with a missing asset’s name |-| FR18 | Type tests over `PortableTheme` and `DefinedTheme`, token resolution tests per color mode, and `defineNativeTheme` reporting tests | each maintained theme; a theme with component overrides, icons, indicators, media surfaces, and adaptations; light and dark; a length, a color, and a font token | `DefinedTheme` changes for a web caller, a portable token needs CSS to resolve, `PortableTheme` references a React or DOM type, or a web part with content is dropped without a report |+| FR18 | Type tests over `PortableTheme` and `DefinedTheme`, token resolution tests per color mode, and `defineNativeTheme` reporting tests | each maintained theme; a theme with component overrides, icons, indicators, media surfaces, and adaptations; light and dark; a length, a color, and a font token; a theme that overrides `md`, whose compact definition follows the override | A `DefinedTheme` member a web caller uses is removed or changes, a portable token needs CSS to resolve, `PortableTheme` references a React or DOM type, a web part with content is dropped without a report, or the compact definition does not follow a theme's effective `md` || FR19 | Wire type tests per platform condition, Swift decoding tests, host tests in a JavaScript engine, and a logic core run with no host globals | a tree with a content slot; a listed and an unlisted callback; an unknown component; an unknown closed-set value; a missing required prop; a node carrying a prop the host does not know; input that is not an action; a bundle with no entry; a JavaScript error; a bridge version mismatch; a tree the host cannot read at all; a tree sent after a failure | A view gets an unlisted callback, an action carries a different key or arguments, one unreadable node blanks its siblings, a prop the host does not know makes its node unsupported, the logic core accepts input that is not an action, or a failed host draws a tree or sends an action |## Decision log@@ -614,8 +620,9 @@ foreign next to system controls.Native platforms need a theme's identity, not its CSS. Splitting `DefinedTheme`into `PortableTheme` and a web part gives native the shared identity through the-portable entry, keeps React elements and CSS out of native apps, and changes-nothing for web callers, because `DefinedTheme` is still the whole.+portable entry, keeps React elements and CSS out of native apps, and removes+nothing for web callers, because `DefinedTheme` is still the whole; the portable+compact definition it gains is additive.Rejected: native reading the whole `DefinedTheme`, because it carries Reactelements, CSS maps, and DOM-typed imports native cannot use.diff --git a/docs/specs/AST-093-native-component-guidelines/spec.md b/docs/specs/AST-093-native-component-guidelines/spec.mdindex 0028eaba7a..e544890340 100644--- a/docs/specs/AST-093-native-component-guidelines/spec.md+++ b/docs/specs/AST-093-native-component-guidelines/spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-10-23+approved_at: 2026-10-24phase: acceptedowners: [cixzhang]affects_architecture: []@@ -84,7 +84,8 @@ validating, and reviewing individual native components whileincluding Reduce Motion, haptics, and VoiceOver. Each spec names the guidelinepages it follows. The core contract keeps the component's meaning, words,states, and accessibility semantics; the guidelines decide how the platform- presents them.+ presents them, except that a choice between presentations by screen size uses+ the compact definition of `spec:AST-012` FR9 rather than size classes.- **FR4 — Brand shows through the theme everywhere else.** What FR2 and FR3leave open, such as accent and fill color, type family, corner shape,spacing, and icon choice, comes from the app's theme: tokens from itsdiff --git a/packages/core/src/Selector/Selector.spec.md b/packages/core/src/Selector/Selector.spec.mdindex 2914bd6bdc..a66f26aced 100644--- a/packages/core/src/Selector/Selector.spec.md+++ b/packages/core/src/Selector/Selector.spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-08-30+approved_at: 2026-10-24owners: [cixzhang, imdreamrunner]review_triggers: [public-api, behavior, layout, theming, accessibility]verified_by:@@ -48,7 +48,7 @@ connection between the closed trigger and its selection surface.## Compatibility and migration- Released defaults and behavior are unchanged except the `presentation`- default, which DEC-1 sets.+ default, which DEC-1 sets, and `adaptive`'s compact test (below).- `indicatorPosition` defaults to `end`; a rendered selection mark occupiesspace at that logical edge, while an empty resolved indicator occupies none.- `presentation` defaults to `adaptive` (DEC-1): the modal bottom sheet on@@ -57,6 +57,13 @@ connection between the closed trigger and its selection surface.stable-default change, so it ships as `[breaking]` in a scheduled minor under`spec:AST-017`; callers that need the anchored popover on every device pass`popover`.+- `adaptive`'s compact test becomes `spec:AST-012` FR9 (width below the+ effective `md` point or height below 500) in place of the shipped+ `(max-width: 768px)` query: a coarse-pointer screen exactly 768 pixels wide and at least 500 tall opens the popover, and a coarse-pointer screen wider than 768 but under+ 500 tall opens the bottom sheet. Both surfaces keep selection working, so no+ caller must change source and the change is not breaking under+ `spec:AST-017` FR1; `popover` and `bottom-sheet` pin one surface. It is+ pending until the shared resolver conforms; FR4 describes the shipped query.- `hasClear` changes the value contract to include `null`; that distinction isalready part of the public type.- `isReadOnly` is additive and defaults to `false`. It preserves the selected