An open source design system that's fully customizable and agent ready
schema_version: 4 template_version: 2 kind: system-spec id: spec:AST-112 authority: draft archive_reason: null superseded_by: null approved_by: null approved_at: null phase: proposed owners: [imdreamrunner] affects_architecture: [architecture:cli-surface] affects_families: [] affects_contributing: [] affects_consumer_docs: [cli]
React Native foundation system spec
Intent
A developer builds an iOS and Android app with React Native and Astryx by installing three kinds of package: a component library written in JavaScript, a platform layer that holds every line of native code, and command-line tools that create, check, and preview the app. The app gets Astryx's components, themes, and icons, and native capabilities (storage, files, camera, media, web content, documents, native controls) through one consistent API. The app itself holds no hand-written native code, builds in a generated native project, and installs only the native capabilities it uses.
Two apps work with these packages: the Astryx app on iOS and Android, for previewing projects and browsing the components, and Astryx Stage, the desktop app for macOS, Linux, and Windows, which renders an app built with these packages with iOS and Android looks for development (FR12).
These packages are the React Native candidate of spec:AST-082/FR12 for the
ios and android platforms. They follow spec:AST-082: dependencies under
FR13, the canary channel under FR15, the one-way read of core under FR16, and
shared icon names under FR17.
Non-goals
- Which candidate wins a platform.
spec:AST-082/FR12decides that by measurement. - The contract of any one component. Each component's own record and
spec:AST-082/FR3own it; this record owns where the React Native implementation lives and how its packages relate. - macOS and Windows as targets for apps built with these packages.
- The design of each capability's methods beyond the shared rules in FR6 to FR9. Each capability documents its own methods, options, and reasons.
- The internals of Astryx Stage (FR12), beyond what an app and the CLI depend on.
- The Astryx app's design, features, and distribution.
- Equivalent internal implementations remain valid when they satisfy this contract.
Requirements
- FR1 — Three package families. The public set is:
@astryxdesign/react-native: the component library. Components, the app root (AstryxAppRoot), theming, and the hooks an app uses. JavaScript and TypeScript only.@astryxdesign/react-native-platform: the platform core. The result vocabulary (FR6), the capability shape (FR7), the types of every capability, the registry seams the capability packages plug into, the generic capabilities (storage, secure storage, files, network, cookies, permissions, haptics, clipboard, client identity), the gesture owner, gesture root, touch shield, presentation, menu, and action-sheet hosts, system symbols, and system materials.- Capability packages, each one native unit:
@astryxdesign/react-native-platform-camera(camera view, live code scanning, and code decoding from still images),-media(audio and video playback),-web(web view and sign-in session),-pdf(document view), and-controls(native button, text field, date pickers, and the swipe-row, drag-snap, and zoom-pager views). @astryxdesign/react-native-cli: the React Native experiment CLI, which installs theastryx-rncommand (FR13).
- FR2 — Dependencies point one way.
- The library takes the platform core as a peer dependency and calls it directly. The platform imports nothing from the library, in source or in tests.
- A capability package depends on the platform core only. A need that crosses capabilities goes through a registration hook in the platform core, never through a dependency between capability packages.
- The library reaches an optional capability package only through the
platform core's guarded loader (
AstryxPlatform.capability(name)), so an app without that package installs and bundles nothing of it. - None of these packages depends on another Astryx package at run time,
other than these dependencies, the reads of
@astryxdesign/corethatspec:AST-082/FR16allows, and@astryxdesign/native(FR10, OQ2, OQ3), which a platform package uses at the version the repository's release gives every package (FR14).@astryxdesign/coreand@astryxdesign/clinever depend on them (spec:AST-082/FR14). - React Native command-line tools are development dependencies. An app's
runtime never imports them, and
@astryxdesign/clinever depends on them.
- FR3 — Installing a package is the opt-in. Each capability package carries its own native module, permissions, system frameworks, manifest entries, and services. An app that does not install it carries none of them. No build flag, environment variable, or configuration switch turns a capability on or off. The platform core requests no permission beyond network state.
- FR4 — Native code lives only in the platform packages.
- The library contains no native code and has no runtime dependency beyond
react,react-native, and the platform core. - An app holds no hand-written native code. Its iOS and Android projects are generated from the app's configuration. The platform core ships one configuration plugin, and each capability package provides its host declarations (usage descriptions, manifest entries, background modes) as data that the plugin writes into the generated project. A capability package ships no plugin of its own.
- An app-level native setting is configuration that a plugin writes into the generated project. JavaScript cannot read or change it at run time.
- Each platform package ships its native code as source that the app's native build compiles; it registers itself through autolinking and React Native's code generation.
@astryxdesign/nativeis the single cross-platform contracts package ofspec:AST-082(DEC-7). The React Native platform ships as the core and per-capability packages of FR1 because each capability carries its own native code, permissions, and size, so an app installs only what it uses. The React Native packages may consume@astryxdesign/native's generated contracts (OQ2).
- The library contains no native code and has no runtime dependency beyond
- FR5 — The public surface is deliberate. Each package declares its entries
in its
exportsmap, and an import outside the map is unsupported..is the app API../testingis the testing surface: mocks of every native module in its absent, older, and current shapes, event emitters, and a Jest setup file. It is public and documented../hostholds the plumbing the library and the capability packages need, such as the library's hosts. It has the statusspec:AST-017FR21 gives Core's./internal/*: reserved for Astryx's own packages, undocumented for apps, versioned in lockstep with the set (FR14), limited by a package-boundary check, and outside the compatibility promise. An app imports from.../app.plugin.js, on the platform core only, is the configuration plugin (FR4)..exports nothing named*ForTesting,reset*,SIMULATED_*, or*_NAME.- A renamed or removed public name stays exported, marked
@deprecated, for one minor version.
- FR6 — One result vocabulary. Every asynchronous call in the platform
packages resolves
AstryxResult<T, R>:{ok: true, …}with its data, or{ok: false, reason, message?}. It never rejects.reasoncomes from a closed set per capability plus the common reasonsno-module,unsupported,unsupported-option,cancelled, anderror.unsupportedmeans the binary predates the method;unsupported-optionmeans it predates an option of a method it has, or the platform cannot honor that option.cancelledis the one failure that is not an error: the person declined or dismissed something. A caller branches on it and shows no error.messageis platform text for logs. It never carries a URL's query, a cookie, a key, or a token.
- FR7 — One capability shape.
- Every capability object has
isAvailable(): boolean(synchronous, cheap, cached) andversion(): number | null, andsupports(feature)where the capability has optional features. Every view has anis<View>Available()probe. - A path a platform or an older binary does not support answers
unsupportedorunsupported-option. It is never a silent no-op and never a quietly weaker behavior. - Permissions are explicit:
AstryxPermissions.getandrequest, and ause<Capability>Permission()hook. Mounting a view never prompts. - Hooks own lifecycle: they cancel their work on unmount and return stable callbacks. Root tags, module handles, and native versions never appear in app-facing types.
- Names follow React Native's own conventions:
source={{uri}},ref,on<Event>(event)with one object argument,isandhasbooleans, and string unions for closed sets. A call takes its subject first and one options object, with defaults for every option.
- Every capability object has
- FR8 — Native interfaces evolve additively. Every TurboModule and native
component spec in the platform packages follows these rules, and a check in
each package enforces them:
- A module is read with
TurboModuleRegistry.get, nevergetEnforcing; an absent module answersno-module. - Each module's handle is read only by its own wrapper.
- New behavior is a new optional method or prop. A shipped method's arguments and result never change.
- A new method takes one request object and resolves one result object with
status(ok,cancelled, orerror),reason, andmessage. A domain outcome, such as "not found", is a field of anokresult. - Every module reports
getConstants().version, its behavior revision. - A member that exists on one platform only says so in its name or tag.
- Every spec file has a header with its owner, platforms, first version, and stability, and every component spec has a version history.
- A module is read with
- FR9 — The library speaks Astryx; the platform speaks the platform. The
platform's public types use platform vocabulary, except the native controls,
whose appearance is Astryx's design language. The library maps Astryx
vocabulary onto the platform: icon names onto system symbols
(
spec:AST-082/FR17), feedback moments onto haptic kinds, and the theme onto native appearance.AstryxAppRootwires the platform's hosts by default and takesnativeHostsoptions;NativeHostsProvidercomposes the same hosts for an app that builds its own root. - FR10 — The packages build on core and on the shared native code.
- Tokens, themes, and icon names come from
@astryxdesign/core's one theme definition (spec:AST-082/FR10), read underspec:AST-082/FR16. The React Native packages never define a second token set. - Components keep core's names and core contracts (
spec:AST-082/FR3). - Where
@astryxdesign/native's Swift package provides a native control or view for a component, the platform wraps that shared control instead of drawing a second one.
- Tokens, themes, and icon names come from
- FR11 — Expo builds are supported; Expo Go is not a target. The platform
packages build in a prebuild or development-build project and in EAS Build
through the platform core's configuration plugin (FR4), with no manual native
edits. They do
not run in Expo Go, and no package requires an Expo runtime library
(
spec:AST-082/FR13). Expo's API shapes do not limit the platform's API. - FR12 — Astryx Stage is the contract developers build against. Astryx
Stage runs on macOS, Linux, and Windows. It renders an app
built with these packages with iOS and Android looks, headless or in a
window, for previews, scripted checks, and agent loops.
- Every public platform API has an implementation in Astryx Stage whose behavior matches iOS and Android. A missing or divergent path is a defect, and the capability's documentation names it until it is fixed.
- Each capability's documentation states its behavior in Astryx Stage as the contract and notes where iOS and Android differ.
- Astryx Stage is a development tool. An app never depends on it at run time.
- FR13 — React Native commands live in an experiment CLI.
@astryxdesign/react-native-cliinstalls theastryx-rncommand, the experiment space for React Native commands. It is canary-only, and its commands may change or disappear in any canary. The released command-line shape for React Native is OQ5.- Commands:
create(a new app),doctor(the toolchain, the project, and the installed Astryx Stage),generate(the native projects from configuration), and commands that install, select, open, and run the desktop app, capture and inspect a rendering, and run scripted checks. Their names are proposals under OQ5 (for examplestage install | update | use | list | open | run | shot | inspect | test | sweep). - Astryx Stage's version is pinned per project in a configuration file the React
Native command-line tool owns, never in
astryx.config, whose keys@astryxdesign/clivalidates. The install command verifies each binary's checksum and signature, and the first command that needs Astryx Stage installs the pinned version. --remoteruns an Astryx Stage command on a remote runner and returns the same result as a local run.- Its commands follow the output and exit-code rules of
architecture:cli-surface: no question is ever asked, every--jsonemission is one envelope, codes are stable and append-only, and exit codes do not depend on the output mode. It shares flag style with@astryxdesign/cliand writes no key intoastryx.config. A command therefore keeps its contract whichever released shape OQ5 settles. @astryxdesign/clicontains no React Native commands, so a web project installs nothing for them.
- Commands:
- FR14 — One React Native release train. All the packages in FR1 except
the experiment CLI carry the same version and release together.
- While they are canary-only, they publish on the canary channel only, under
spec:AST-082/FR15, and carry the version the repository's canary release gives every package: core's declared version with-canary.<sha>(spec:AST-017FR46). They join the stable channel in a planned minor once a platform is supported. - A package that depends on another package of the set requires it at exactly the set's version.
- The platform core's loader refuses a capability package whose version differs from core's, or that reports no version, in development and in release alike: it treats the package as not installed, so the library takes its non-native path, and it logs one error that names both versions. Packages from two releases never run together.
- Before 1.0, a minor version may change the API. Each release has a changelog per package with migration steps for every rename and removal, and a release records the packed tarballs with their hashes.
- While they are canary-only, they publish on the canary channel only, under
- FR15 — Evidence matches the claim.
- Evidence for native behavior comes from the iOS Simulator, the Android emulator, devices, and Astryx Stage. The Simulator and the emulator are the source of truth during development; every change to native behavior is checked there and in Astryx Stage.
- A passing build is not evidence of behavior. A claim about camera, haptic feel, or performance needs a real device.
- Every platform package's tests cover each native module in its absent,
older, and current shapes through
./testing. - API blocks in each package's documentation are generated from source, and a check fails when they drift.
Platform support
- Supported feature/engine floor: iOS at React Native's own minimum and Android API level 24, on React Native's New Architecture (Fabric and TurboModules) only, with the React and React Native versions each package declares as peers.
- Unsupported behavior: a capability a binary lacks answers
no-moduleorunsupported(FR6, FR7); a view a binary lacks reports itself unavailable and the library draws its fallback; Expo Go and the old architecture are not supported (FR11). - Browser evidence: none. Native claims are proven on the Simulator, the emulator, devices, and Astryx Stage (FR15).
Current-state impact
- New packages under
packages/: the library, the platform core, the five capability packages, and the experiment CLI, each canary-only (FR14). @astryxdesign/cliis unchanged. The released command-line shape for React Native (OQ5) may changearchitecture:cli-surfacewhen it is decided.- The React Native packages join the repository's canary release and carry its version (FR14).
spec:AST-017FR21 extends the status of Core's./internal/*to the platform's./hostentry (FR5).spec:AST-082DEC-7 gains one sentence: the React Native candidate's native code lives in the platform packages ofspec:AST-112(FR4), and@astryxdesign/nativestays the single cross-platform contracts package.- The package-boundary check gains the FR2 rules: no import from the library in the platform, no dependency between capability packages, and no dependency on these packages from core or the CLI.
Verification
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1 | Package manifest check of names and entries; the canary release's package list | each package in the public set | A package missing from the set, or a set package missing from the canary release |
| FR2 | Package-boundary and source check | the platform's source and tests; each capability package | The platform imports the library, or one capability package depends on another |
| FR3 | Generated native project of an app with the core only, compared with one per capability package | permissions, frameworks, manifest entries, services | An app without a capability package carries any of its declarations |
| FR4 | npm pack file lists; a generated sample app's project from configuration |
the library's files; the sample's iOS and Android projects | The library ships native code, a capability package ships a plugin, or the sample needs a manual native edit |
| FR5 | exports map and public-entry name check; package-boundary check of ./host imports |
., ./testing, ./host, ./app.plugin.js |
A private name on ., a deep import resolving, or an app importing ./host |
| FR6 | Unit tests of every asynchronous call through ./testing mocks |
absent, older, and current module; a missing option; a native throw; cancel | A call rejects, or answers a reason outside its set |
| FR7 | Unit tests of each capability's probes, permissions, and hook cleanup | an older binary; a view mounted without permission; unmount | A silent no-op, a prompt on mount, or work that outlives its component |
| FR8 | Spec rules check in each platform package | a new method; a component spec; a platform-only member | A changed shipped method, a missing header, or a new method without status |
| FR9 | Source check of platform public types; library tests of the mappings and the default hosts | an icon name; a feedback moment; a theme change | Astryx vocabulary in a generic capability type, or the app root without hosts |
| FR10 | Token comparison between the library and core's theme; review of shared native controls | every token; each component with a shared native control | A token value that differs from core's, or a second native control drawn beside a shared one |
| FR11 | Prebuild and EAS Build of the sample app | the sample with every capability package | The build needs a manual native edit, or a package requires an Expo runtime library |
| FR12 | Scripted checks of each capability in Astryx Stage, the simulator, and the emulator | each public API | An Astryx Stage result differs from iOS and Android and the documentation does not name it |
| FR13 | CLI contract tests of each astryx-rn command: JSON envelopes, exit codes, Astryx Stage's checksum and signature refusal, --remote parity; a dependency check of @astryxdesign/cli |
each command; a tampered binary; a web project | An exit code that depends on --json, a tampered binary runs, or @astryxdesign/cli contains or depends on React Native commands |
| FR14 | Canary release dry run; dependency check of in-set ranges; a loader test with a capability package of another version and one without a version | a release of every package; a mixed install | Packages with different versions, an in-set range that is not exact, a mixed install that runs, or a release without a changelog or hashes |
| FR15 | Review of each native change's evidence; documentation drift check | a native behavior change; a renamed API | A native claim backed only by a build or by anything other than the Simulator, the emulator, a device, or Astryx Stage, or documentation that no longer matches |
Decision log
DEC-1 — The platform is a layer for Astryx, below the library
Reference: spec:AST-112/DEC-1
Decider: imdreamrunner, 2026-11-09
The platform owns the native contract and first-class capability objects; the library calls them directly and keeps the Astryx mapping. Apps call the same objects for capabilities the library does not cover. Dependencies point from the library to the platform only, so the native API stays clean and the library can change without touching native code.
Rejected: a design-system-neutral platform built for standalone use, because it would duplicate the mapping the library owns.
DEC-2 — One package per native capability
Reference: spec:AST-112/DEC-2
Decider: imdreamrunner, 2026-11-09
An app that stores data does not ship a camera permission, a media service, or their frameworks. Installing a package is the opt-in, which autolinking and prebuild already support without any switch.
Rejected: one package with build flags, because every app would carry every declaration unless each build remembered to turn it off.
DEC-3 — Apps hold no native code
Reference: spec:AST-112/DEC-3
Decider: imdreamrunner, 2026-11-09
The platform packages bring all native code; an app's native projects are generated from configuration with the platform core's plugin. An Astryx upgrade then reaches every app through its dependencies, and no app carries native code that drifts from the platform.
Rejected: app-owned native shell code, because each app would maintain native code the platform cannot update.
DEC-4 — Results, never rejections
Reference: spec:AST-112/DEC-4
Decider: imdreamrunner, 2026-11-09
Every failure is data in one shape with a closed reason, so a caller handles it with a type-checked branch, and a cancel is told apart from an error.
Rejected: rejecting promises for failures, because an unhandled rejection is easy to miss and its reason is not typed.
DEC-5 — Expo builds, not Expo Go
Reference: spec:AST-112/DEC-5
Decider: imdreamrunner, 2026-11-09
Cloud and prebuild builds are a goal, so the platform core carries a configuration plugin. Expo Go cannot load the packages' native code, and an API limited to what every Expo module offers would cap the platform.
Rejected: an adapter package for Expo's module system, because it adds a second interface to keep in step without enabling any build.
DEC-6 — React Native commands start in an experiment CLI
Reference: spec:AST-112/DEC-6
Decider: imdreamrunner, 2026-11-09
React Native commands change quickly while the packages are canary-only, so they
start in astryx-rn, a separate experiment program, and stay out of
@astryxdesign/cli. The released command-line shape is OQ5.
DEC-7 — Astryx Stage's behavior is the contract developers read
Reference: spec:AST-112/DEC-7
Decider: imdreamrunner, 2026-11-09
Developers build against Astryx Stage, so its behavior is what they rely on. Astryx's own development checks the simulator and emulator as the source of truth and keeps Astryx Stage matched to them. A missing or divergent path is a defect.
DEC-8 — One release train, canary first
Reference: spec:AST-112/DEC-8
Decider: imdreamrunner, 2026-11-09
The library and the platform packages change together, so they share
one version and release together. They stay on the canary channel until a
platform is supported under spec:AST-082/FR15.
Open questions
- OQ2 — When do the library's component props come from
@astryxdesign/native's platform contracts? (human-api) Options: now, under theiosandandroidconditions; or once core's portable entry ships. Recommendation: once the portable entry ships, with a check until then that the library's props match the generated contracts. - OQ3 — How does an app receive
@astryxdesign/native's Swift code? (checkable) Options: the platform package vendors the Swift sources it wraps; or the platform's native build depends on the Swift package directly. - OQ4 — Where are Astryx Stage's binaries published? (
human-design) Options: per OS and architecture packages on npm that the CLI installs; or release assets that the CLI downloads and verifies. Recommendation: release assets with checksums and signatures, because the binaries are large and npm's optional dependencies install every architecture's metadata. - OQ5 — What is the released command-line shape for React Native?
(
human-api; owners: imdreamrunner and josephfarina) Options:- An extension of the core CLI. An optional integration package (name
proposed:
@astryxdesign/cli-react-native) contributes anrncommand group to@astryxdesign/cli(astryx rn …) through a newcommandscontribution in the integration manifest, loaded like other contributions: from the project's integrations inside a project, and from computer-level integrations outside one (spec:AST-081/FR12). Gains: one command, one help, output, and error-code contract, enforced by the core CLI. Costs: the core CLI needs a command extension point (the manifest'scliCommandkey names the printed command prefix only), and React Native commands release on the core CLI's peer range. - A separate CLI.
astryx-rnitself becomes the released program, optionally withastryx rnforwarding to it. Gains: no change to the core CLI, and an independent release cadence. Costs: a second help, output, and error-code surface to keep in step, and two command names in documentation. - Commands inside
@astryxdesign/cli. Gains: one package, no extension point. Costs: every web project installs React Native commands.
- An extension of the core CLI. An optional integration package (name
proposed: