Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(AST-082): native build scripts may read core until the portable entry ships (#8048)

Cindy Zhang21631be69648
diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md
index 86ebf298b1..afb7beae5c 100644
--- a/docs/specs/AST-082-native-first-surfaces/spec.md
+++ b/docs/specs/AST-082-native-first-surfaces/spec.md
@@ -274,7 +274,14 @@ depends only on runtimes it can maintain.
build time, so a core contract change reaches every native platform on its next
build; generated Swift and Kotlin bindings carry nothing from core at run time.
A package-boundary check enforces both directions: core never imports native,
- and native never imports core outside the portable entry. The portable entry
+ and native never imports core outside the portable entry. Until the portable
+ entry ships, a native build script may read core at build time through
+ `@astryxdesign/core/theme` and `@astryxdesign/core/theme/tokens`, and read
+ core's component documentation, its built-in icon names, and its locale
+ catalogs as data, to
+ generate native code and to check native coverage in native tests. The
+ boundary check lists each such read by name and refuses any other, and no
+ native runtime code or generated binding imports core. The portable entry
is an entry of `@astryxdesign/core` (DEC-8). It makes `react-dom` and StyleX
optional peers of core and keeps resolved token values apart from the web theme
compiler.
@@ -343,23 +350,23 @@ 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 free-form content or render-function prop in the core | A core prop has no Swift or Kotlin form, or a non-portable prop enters the core |
-| 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 | Any byte of CSS, mounted rules, or rendered web markup differs, core depends on native, or a web prop disappears outside 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 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; 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 | 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, or a web icon is substituted |
-| 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 |
+| 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 free-form content or render-function prop in the core | A core prop has no Swift or Kotlin form, or a non-portable prop enters the core |
+| 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 | Any byte of CSS, mounted rules, or rendered web markup differs, core depends on native, or a web prop disappears outside 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 | 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, or a web icon is substituted |
+| 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 |
## Decision log
@@ -456,7 +463,8 @@ Web users install nothing native, native apps load nothing web, and a core
release never waits on a native platform. Core keeps the core and web contracts;
`@astryxdesign/native` holds the native platform contracts, the Swift and Kotlin
bindings, native theme configuration, and native implementations, and reads core
-only through the portable entry (FR16).
+only through the portable entry, apart from the build-time reads FR16 lists
+until that entry ships.
Rejected: native types and implementations inside `@astryxdesign/core`, because
every web consumer would carry them and core's API would grow with each platform.