An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-082, AST-093): the core holds only props every platform honors; one API per language adapts per device (#8234)
Cindy Zhang2d78c4bdcf5e
diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.mdindex 400622a080..c5ece2246d 100644--- a/docs/specs/AST-082-native-first-surfaces/spec.md+++ b/docs/specs/AST-082-native-first-surfaces/spec.md@@ -36,10 +36,10 @@ that exist only on some platforms.Every component has one shared core contract that keeps its meaning, words,states, and accessibility the same everywhere, and a contract per platform that-adds what only that platform can do. A developer sees the props of the platform-they build for, in TypeScript and in each native language, and a prop from-another platform is an error rather than a silent no-op. Documentation and the-CLI show the same split.+adds the props that platform honors beyond the core. A developer sees the props+of the platform they build for, in TypeScript and in each native language, and a+prop from another platform is an error rather than a silent no-op. Documentation+and the CLI show the same split.`@astryxdesign/core` serves the web. `@astryxdesign/native` serves the nativeplatforms and reads core in one direction only, so web users install nothing@@ -79,15 +79,39 @@ depends only on runtimes it can maintain.express: native platforms are not limited to web markup and CSS, and the webis not limited to what native implementations can draw.- **FR3 — A component has a core contract and a contract per platform.** The- core contract is the component's name, its shared props with their meaning and- defaults, its states, its words, and its accessibility semantics (name, role,- state, focus behavior, and announcements). It is the same on every platform- that offers the component. A platform contract adds props only that platform- can honor. It never removes, renames, or changes the meaning of a core prop.- The web contract holds the web base props: styling inputs, DOM events, refs,- element choice, and HTML attributes. A component may exist on some platforms- only; using it elsewhere fails at type check or build with a message that names- the supported platforms, and never renders a silent substitute.+ core contract is the component's name, the props every platform that offers+ the component honors with the same meaning and defaults, its states, its+ words, and its accessibility semantics (name, role, state, focus behavior, and+ announcements). It is the same on every platform that offers the component.+ - A platform honors a prop when the prop behaves the way core already defines+ for that platform's input type. `tooltip` stays in the core: core defines+ what a tooltip does where there is no hover (Tooltip `touchTrigger`), and a+ touch platform behaves that way.+ - A prop leaves the core only when a platform that offers the component cannot+ match core's defined behavior for its input type. Such a prop belongs to the+ contracts of the platforms that can (web, iOS, macOS, Android, Windows), and+ the same prop may appear in several platform contracts with one meaning+ (FR8). `rel` and `target` on a link belong to the web contract: an app+ platform opens every link through the system and has no relationship or+ browsing context to set.+ - Within one language, one API serves every platform that language's apps+ run on and adapts per device, as SwiftUI's `.help` shows a tooltip on+ macOS and becomes a hint on iOS. A prop is scoped to a single platform only+ when no honest behavior exists on that language's other platforms; such a+ prop states its reason, and never makes an app branch by platform (`#if`)+ for behavior that could adapt.+ - A platform never offers a prop it does not fully honor. A prop a platform+ accepts but ignores, or honors only in part, breaks+ `architecture:public-component-api/INV2`.+ - A platform contract never removes, renames, or changes the meaning of a core+ prop. Moving a released prop from the core to the web contract changes no+ web caller's types, because the web types are the core contract plus the web+ contract; native contracts stop offering it.+ - The web contract holds the web base props: styling inputs, DOM events, refs,+ element choice, and HTML attributes.+ - A component may exist on some platforms only; using it elsewhere fails at+ type check or build with a message that names the supported platforms, and+ never renders a silent substitute.- **FR4 — The core contract is portable.** Every core prop has a form in eachlanguage a supported platform's apps are written in, including Swift andKotlin: strings, numbers, booleans, closed string sets, open string sets,@@ -410,24 +434,24 @@ depends only on runtimes it can maintain.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1, FR3 | Component documentation metadata check, plus type and build tests importing a platform-specific component | a shared component; a web-only component; a component on some native platforms; an unsupported platform | A component declares no platforms, claims an unsupported native platform, or an unsupported import type-checks, builds, or renders a substitute |-| FR4 | Contract generation to TypeScript, Swift, and Kotlin, compiled in each language | every core prop kind; a boolean combined with a closed string set; an open string set with a built-in name, a theme-declared name, and a name the platform has no rule for; a projected prop at each portable value and at a web-only value; a text, icon, and content slot, and a web call site passing a wider form; a free-form content or render-function prop in the core | A core prop has no Swift or Kotlin form, a non-portable prop enters the core, a named state collapses into `true` or `false`, a theme-declared name is rejected by a platform type, an unknown open-set name fails instead of drawing the base look, a wire value differs from the web value, a projected value maps to a different web value or a web-only value reaches a native type, or a slot accepts a wider form on a platform that cannot render it |-| FR5, FR6 | Type checks of fixture apps against each package and condition | core default (web); each native condition; `shared`; a platform prop in another platform's file and in a shared file | A platform prop type-checks under another platform's condition or under `shared`, a core prop is missing under any condition, or web types change |-| FR7 | Generated base-prop surfaces per platform, plus runtime targeting tests | shared base props; a core-owned concept; a core prop that reuses a base name; each targeted part | A shared base prop differs by platform, an owned concept's base prop overrides the core prop, or base props reach a different part on another platform |-| FR8 | Contract name check over every component | core prop vs platform prop; Swift and Kotlin keywords; platform toolkit names; reclaimed names; one name in two platform contracts | A collision passes, a reclaimed name is undeclared, or a same-named platform prop appears in a merged type |-| FR9 | Documentation and CLI output checks | core only; each platform selection; native package absent | Output for one platform lists another platform's prop, or a prop is unmarked |-| FR10 | `defineNativeTheme` unit and type tests, plus a resolution test per platform | durable `material` only; entry with and without a range; overlapping entries; platform `components`; native theme extension; a token in native configuration; platform term outside its entry or range | A token can be set, a platform term type-checks outside its entry or range, an entry applies outside its platform or range, overlap order is ignored, or extension drops members |-| FR11 | FR12 experience scores per scenario step, oldest and newest supported OS | navigation, sheet, menu, picker, switch, text entry, scrolling, keyboard shortcut, large text; a capability newer than the running OS | A step draws a custom control where the platform provides one, misses the touch-target minimum, ignores the text-size setting, or breaks on the oldest supported OS |-| FR12 | Scenario replay on candidates and reference, on real release builds and devices | each scenario on each candidate and the toolkit reference; oldest and newest supported OS; a lower-end device per platform | A candidate is scored without the reference, on a debug build, on emulation only, on one OS version, or on a different scenario set, or a visual score is given without device captures |-| FR13 | Dependency manifest audit of each native platform package | platform SDK; first-party project; a React Native out-of-tree desktop platform; third-party optional integration; third-party fork | A third-party library or fork is required to install, build, or render on the platform |-| FR14 | Compiler and render output comparison, core dependency graph check, and a web type surface diff | each maintained theme with and without the native package installed; runtime-mounted and built CSS; components; web types before and after; an existing web prop that renders a string as text becomes an icon slot | Any byte of CSS, mounted rules, or rendered web markup differs, core depends on native, or a web prop disappears outside a planned minor, or an existing web prop that renders a string as text becomes an icon slot in a patch rather than a planned minor |-| 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 | 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 |-| 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 |-| 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 |+| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, FR3 | Component documentation metadata check, plus type and build tests importing a platform-specific component, plus a per-platform prop check over every contract | a shared component; a web-only component; a component on some native platforms; an unsupported platform; a prop every offering platform honors; a prop only some platforms honor; a released prop moved from the core to the web contract; a prop that adapts across one language’s platforms; a single-platform prop | A component declares no platforms, claims an unsupported native platform, or an unsupported import type-checks, builds, or renders a substitute, a platform type accepts a prop that platform cannot honor, a core prop is missing on a platform that offers the component, or moving a prop to the web contract changes a web caller’s types, or a single-platform prop has no stated reason or makes an app branch by platform for behavior that could adapt |+| FR4 | Contract generation to TypeScript, Swift, and Kotlin, compiled in each language | every core prop kind; a boolean combined with a closed string set; an open string set with a built-in name, a theme-declared name, and a name the platform has no rule for; a projected prop at each portable value and at a web-only value; a text, icon, and content slot, and a web call site passing a wider form; a free-form content or render-function prop in the core | A core prop has no Swift or Kotlin form, a non-portable prop enters the core, a named state collapses into `true` or `false`, a theme-declared name is rejected by a platform type, an unknown open-set name fails instead of drawing the base look, a wire value differs from the web value, a projected value maps to a different web value or a web-only value reaches a native type, or a slot accepts a wider form on a platform that cannot render it |+| FR5, FR6 | Type checks of fixture apps against each package and condition | core default (web); each native condition; `shared`; a platform prop in another platform's file and in a shared file | A platform prop type-checks under another platform's condition or under `shared`, a core prop is missing under any condition, or web types change |+| FR7 | Generated base-prop surfaces per platform, plus runtime targeting tests | shared base props; a core-owned concept; a core prop that reuses a base name; each targeted part | A shared base prop differs by platform, an owned concept's base prop overrides the core prop, or base props reach a different part on another platform |+| FR8 | Contract name check over every component | core prop vs platform prop; Swift and Kotlin keywords; platform toolkit names; reclaimed names; one name in two platform contracts | A collision passes, a reclaimed name is undeclared, or a same-named platform prop appears in a merged type |+| FR9 | Documentation and CLI output checks | core only; each platform selection; native package absent | Output for one platform lists another platform's prop, or a prop is unmarked |+| FR10 | `defineNativeTheme` unit and type tests, plus a resolution test per platform | durable `material` only; entry with and without a range; overlapping entries; platform `components`; native theme extension; a token in native configuration; platform term outside its entry or range | A token can be set, a platform term type-checks outside its entry or range, an entry applies outside its platform or range, overlap order is ignored, or extension drops members |+| FR11 | FR12 experience scores per scenario step, oldest and newest supported OS | navigation, sheet, menu, picker, switch, text entry, scrolling, keyboard shortcut, large text; a capability newer than the running OS | A step draws a custom control where the platform provides one, misses the touch-target minimum, ignores the text-size setting, or breaks on the oldest supported OS |+| FR12 | Scenario replay on candidates and reference, on real release builds and devices | each scenario on each candidate and the toolkit reference; oldest and newest supported OS; a lower-end device per platform | A candidate is scored without the reference, on a debug build, on emulation only, on one OS version, or on a different scenario set, or a visual score is given without device captures |+| FR13 | Dependency manifest audit of each native platform package | platform SDK; first-party project; a React Native out-of-tree desktop platform; third-party optional integration; third-party fork | A third-party library or fork is required to install, build, or render on the platform |+| FR14 | Compiler and render output comparison, core dependency graph check, and a web type surface diff | each maintained theme with and without the native package installed; runtime-mounted and built CSS; components; web types before and after; an existing web prop that renders a string as text becomes an icon slot | Any byte of CSS, mounted rules, or rendered web markup differs, core depends on native, or a web prop disappears outside a planned minor, or an existing web prop that renders a string as text becomes an icon slot in a patch rather than a planned minor |+| 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 | 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 |+| 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 |+| 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@@ -613,6 +637,24 @@ Rejected: a native name per component for the same values, because one valuewould have two names. Rejected: changing core to a closed string set, becauseit breaks web callers outside a planned minor release.+### DEC-14 — The core holds only what every platform honors++**Reference:** `spec:AST-082/DEC-14`+**Decider:** cixzhang, 2026-10-24++A prop kept everywhere for consistency, but ignored where a platform cannot+honor it, tells callers it works when it does not. So the core holds the props+every platform that offers a component honors as core defines them, and a prop+some platforms cannot honor lives in the contracts of those that can. One module+can still serve several platforms, and a prop can work on only some of them.+People build once in a language and run on every device it reaches, so within a+language the API adapts per device and a single-platform prop is the rare+exception.++Rejected: keeping every web prop in the core with a per-platform opt-out list,+because each platform's real surface would be the core minus a list nobody+reads.+### DEC-15 — A logic-core tree degrades per node, and a failed host stays failed**Reference:** `spec:AST-082/DEC-15`diff --git a/docs/specs/AST-093-native-component-guidelines/spec.md b/docs/specs/AST-093-native-component-guidelines/spec.mdindex e63e89b75b..6b42a7efae 100644--- a/docs/specs/AST-093-native-component-guidelines/spec.md+++ b/docs/specs/AST-093-native-component-guidelines/spec.md@@ -93,8 +93,10 @@ validating, and reviewing individual native components whilechange to a native component ships with:- unit tests in its package's test target for parameter mapping, defaults,and state changes, built and run on every platform the package supports;- - parameters named and typed as the generated contract for the component- (`spec:AST-082/FR5`), with the contract drift tests passing, except for the+ - parameters named and typed as the platform's generated contract for the+ component (`spec:AST-082/FR5`): the core props every platform honors plus+ that platform's own props (`spec:AST-082/FR3`), never a prop kept for parity+ alone, with the contract drift tests passing, except for theinterim Swift views listed in Current-state impact;- accessibility assertions for the label, traits, and value the corecontract requires, plus a check at the largest Dynamic Type size;