Skip to content

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

TypeScript

spec(AST-082): native-first platforms in @astryxdesign/native; core + platform contracts with platform-scoped types (#7640)

Cindy Zhangd0f9afe7ce75
diff --git a/docs/specs/AST-082-native-first-surfaces/spec.md b/docs/specs/AST-082-native-first-surfaces/spec.md
new file mode 100644
index 0000000000..86ebf298b1
--- /dev/null
+++ b/docs/specs/AST-082-native-first-surfaces/spec.md
@@ -0,0 +1,543 @@
+---
+schema_version: 4
+template_version: 2
+kind: system-spec
+id: spec:AST-082
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-21
+phase: accepted
+owners: [cixzhang]
+affects_architecture:
+ [
+ architecture:theme-authoring-contract,
+ architecture:theme-compilation,
+ architecture:public-component-api,
+ architecture:cli-surface,
+ ]
+affects_families: []
+affects_contributing: []
+affects_consumer_docs: [theme, cli]
+---
+
+# Native-first surfaces system spec
+
+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
+
+## Intent
+
+A person using an Astryx product gets a native-first experience wherever they
+use it: in a browser, or in a native app on iOS, Android, macOS, or Windows. On
+each platform, components behave, respond, and perform like that platform's best
+software on the OS version the person runs, and a product can offer experiences
+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.
+
+`@astryxdesign/core` serves the web. `@astryxdesign/native` serves the native
+platforms and reads core in one direction only, so web users install nothing
+native and native apps load nothing web. A team defines its visual identity once,
+in one Astryx theme; native-only visual intent is written as durable outcomes
+that keep their meaning as platforms change, and anything tied to one platform or
+OS version is written only inside that platform's entry.
+
+Astryx chooses how each native platform is built by measuring candidate
+approaches against the platform's own toolkit on the same scenarios, and it
+depends only on runtimes it can maintain.
+
+## Non-goals
+
+- The order in which platforms ship (OQ2) and each platform's supported OS
+ versions (OQ4).
+- Exact performance thresholds (OQ1). This record owns what is measured and how
+ approaches are compared.
+- The internals of any one platform's implementation, once it satisfies this
+ contract.
+- Product templates, navigation structures, and app shells built from Astryx
+ components.
+- Changing a web caller's types or behavior. Web removals that this contract
+ implies follow `spec:AST-017` (FR14).
+- Equivalent internal implementations remain valid when they satisfy this
+ contract.
+
+## Requirements
+
+- **FR1 — Astryx targets the web and named native platforms.** The web surface
+ is browsers. The native surface is apps on the native platforms `ios` (iPhone
+ and iPad), `android`, `macos`, and `windows`. Each native platform declares the
+ OS versions it supports (OQ4). A native platform is supported only when it
+ meets FR11 and FR12. Every component declares the platforms it supports.
+- **FR2 — Each platform targets its own ceiling.** An implementation may use any
+ capability its platform offers. No platform is limited to what another can
+ express: native platforms are not limited to web markup and CSS, and the web
+ is 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.
+- **FR4 — The core contract is portable.** Every core prop has a form in each
+ language a supported platform's apps are written in, including Swift and
+ Kotlin: strings, numbers, booleans, closed string sets, arrays, records of
+ these, optional values, and callbacks whose arguments are portable. Free-form
+ content (`ReactNode`) and render functions are not portable. They belong to the
+ web contract and to any platform contract whose implementation runs React; the
+ core expresses content as a typed slot instead, such as text, an icon, or a
+ named Astryx component.
+- **FR5 — Platform props are platform-scoped types.** `@astryxdesign/core`
+ exposes the core contracts and the web contracts; its default types are the web
+ contracts, unchanged for web callers. `@astryxdesign/native` exposes the native
+ platform contracts, selected by the consumer's type-resolution condition:
+ `ios`, `android`, `macos`, or `windows`. Consumer configuration depends on these
+ condition names, so they are public. Under a platform's condition, a
+ component's props are its core contract plus that platform's contract, and a
+ prop from another platform's contract is a type error. Swift and Kotlin
+ bindings ship from `@astryxdesign/native`, generated from the same contract
+ definition as the TypeScript types.
+- **FR6 — Code for several native platforms can use the core alone.** Under the
+ `shared` condition, `@astryxdesign/native` exposes only core contracts.
+ Code that runs on more than one native platform type-checks against it, and a
+ platform prop there is a type error; platform props live in that platform's
+ files. Whether shared code must use this condition is OQ5. A file shared by web and
+ native code imports only core contract types and non-visual logic; each
+ platform's own files import that platform's components (DEC-9).
+- **FR7 — Base props are coordinated across platforms.**
+ - **Shared base props** are the same on every platform: `id`, a stable
+ identifier, and `isHidden`, which removes the component from layout and the
+ accessibility tree. Each platform maps them to its own mechanism, such as the
+ `id` attribute on the web and the accessibility identifier on iOS.
+ - **Platform base props** belong to one platform's contract. The web base
+ props are the DOM attributes that `architecture:public-component-api`
+ governs.
+ - **Targeting:** each component declares the part its base props attach to,
+ such as its root, trigger, control, or container, and the part is the same on
+ every platform. A family record that already routes base props, such as
+ `family:input-fields`, decides the part for its members.
+ - **Reconciliation:** a core prop owns its concept. The platform base props
+ for a concept a core prop owns are not part of that component's platform
+ contract; a core `label` owns the accessible name, so the web
+ `aria-label`/`aria-labelledby` and the iOS accessibility label are not
+ separate inputs. A platform base prop whose name a core prop uses is removed
+ from that platform's base, as the DOM `onChange` is where a component's
+ `onChange` reports a value. This extends
+ `architecture:public-component-api/INV5`: component-owned accessibility and
+ behavior cannot be overwritten. How a removed hyphenated attribute that the
+ type system cannot refuse is enforced is OQ6.
+- **FR8 — Prop names do not collide across platforms.**
+ - A platform prop never reuses a core prop name.
+ - A core prop name is not a keyword in Swift or Kotlin, and is not a name a
+ platform toolkit already uses with a different meaning, such as `style` or
+ `testID` in React Native.
+ - Astryx may reclaim a web base name for a component prop when the component
+ owns that concept. Each reclaimed name is declared, and the platform's own
+ meaning is removed from that component's base props (FR7). `onChange`,
+ `title`, `color`, and `content` are reclaimed today.
+ - The same name may appear in two platform contracts only for the same concept,
+ such as a `menuStyle` with each platform's own values. It never appears in a
+ type that merges platforms, and documentation shows each platform's values.
+ - A web contract prop that fails these rules, such as `as` (a Swift and Kotlin
+ keyword) or `style`, stays in the web contract and never enters the core.
+- **FR9 — Documentation and the CLI are platform-aware.** Every prop in a
+ component's documentation is marked core or names its platform, and every
+ example names the platform it targets. Native platform contracts are
+ documented by `@astryxdesign/native`. `astryx component <Name>` shows the core
+ contract and, with a platform selection, that platform's contract. Output for
+ one platform never lists another platform's props as available. Theme
+ documentation shows native theme configuration per platform.
+- **FR10 — Native theme configuration builds on the defined theme.** One
+ `defineTheme` definition serves the web and every native platform, and it stays
+ the single authority for tokens. Tokens and theme-local tokens are the
+ shared part and mean the same thing everywhere
+ (`architecture:theme-compilation/INV10`); web-only parts follow FR18. `@astryxdesign/native` exports
+ `defineNativeTheme(theme, config)`, which takes a `DefinedTheme` unchanged and
+ adds native-only visual intent; it never sets or overrides tokens:
+ - **Durable intent.** Members name an outcome a person sees, never a platform
+ feature name or an OS version. The first member is `material`, typed
+ `'opaque' | 'translucent'`. Every native platform reads durable intent and
+ realizes it with the closest capability of the running OS version, such as
+ the system glass material on iOS versions that have one, or an earlier
+ system blur. A platform with no such capability renders as if the member
+ were absent.
+ - **Platform entries.** `platforms.<platform>` uses the platform names of FR1
+ and FR5 and holds an ordered list of entries. An entry may name an OS version
+ range, `minVersion` and an optional `maxVersion`; an entry without a range
+ applies to every supported version. An entry holds members from that
+ platform's own vocabulary, such as `material: 'liquidGlass'` for `ios`, and
+ `components`: overrides for that platform's theme targets, including targets
+ that exist only in that platform's contract. An entry applies only on its
+ platform and inside its range. There, its members replace durable members of
+ the same name, and a later matching entry replaces an earlier one.
+ - A platform feature name is valid only inside its platform's entry, and a
+ feature that exists only on some OS versions is valid only in an entry whose
+ range lies within them.
+ - A native theme may `extends` another: durable members merge member by
+ member, and a child's entry list for a platform replaces the base's list for
+ that platform. Every value is plain serializable data, and a member outside
+ the published vocabulary is a type error.
+- **FR11 — Native platforms are native-first on every supported OS version.** A
+ component uses the platform's own control or convention when one satisfies its
+ contract: navigation, sheets, menus, pickers, switches, text input, scrolling,
+ focus, keyboard shortcuts, haptics, and system materials. It draws a custom
+ control only where the platform has none. On each supported OS version it uses
+ that version's controls and materials. A capability newer than the running OS
+ degrades to the closest earlier platform equivalent or to durable intent, never
+ to 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
+ when it meets the FR12 criteria on its oldest and newest supported OS versions.
+- **FR12 — Approaches are compared on one scorecard.** Every candidate way of
+ building a native platform is measured the same way. Candidates include
+ platform views on generated contracts, React Native components, component
+ logic in TypeScript running in a JavaScript engine that drives platform views,
+ and Astryx's web React components run through a native renderer:
+ - **Scenarios:** one shared set of scripted user flows over representative
+ components and templates, each step defined once by the person's gesture
+ and its expected state, and replayed unchanged on every candidate and on
+ the reference.
+ - **Reference:** the same scenarios built directly with the platform's own
+ toolkit, such as SwiftUI or UIKit, Jetpack Compose, AppKit, or WinUI. The
+ reference sets the ceiling a candidate is scored against.
+ - **Devices:** real hardware running release builds, on the oldest and newest
+ supported OS version of each platform, including a lower-end device.
+ - **Captures:** every scenario step is captured as a screenshot on the
+ device, every behavior, such as a sheet opening and dismissing, a
+ navigation transition, a gesture, scrolling, press feedback, and the
+ keyboard appearing, as a short video, and every scenario as a screen
+ recording. Captures are taken for each candidate, the reference, and the web
+ rendering of the same scenario, in light and dark and at the largest text
+ size. Visual and motion scores are judged from these captures, never from
+ source code or style values.
+ - **Experience:** conformance to platform conventions and to the core
+ contract (FR3), judged per scenario step, and behavior and motion, judged
+ per behavior video for timing, gesture response, and interruptibility
+ against the reference.
+ - **Brand preservation:** how recognizably the theme's identity, its color,
+ typography, shape, spacing, and icons, carries to the platform while the
+ screen stays native-first, judged against the web rendering of the same
+ theme, plus pixel checks on the captures against the theme's resolved
+ values.
+ - **Performance:** time to first content, frame pacing and dropped frames
+ during each scenario, input-to-response latency, memory, and the size the
+ approach adds to an app.
+ - **Accessibility:** parity with the core contract for names, roles, states,
+ focus order, and announcements under each platform's screen reader.
+ - **Maintenance:** the work one Astryx release and one new OS version require
+ on that platform, whether core contract changes reach it automatically, and
+ the time from an OS release to shipping one of its new features.
+ - **Developer speed:** time from an edit to seeing it on a device, and the
+ share of an app's code reused across platforms.
+ - **Dependencies:** every required runtime dependency, classified under FR13.
+
+ A candidate that fails FR13 or falls below the OQ1 thresholds is not
+ supported, whatever its other scores.
+
+- **FR13 — Required dependencies are platform, first-party, or React Native's
+ own platforms.** A native platform's required runtime dependencies are limited
+ to the platform's own SDKs, open-source projects maintained by the organization
+ that maintains Astryx, such as React, React Native, Hermes, and StyleX, and,
+ for macOS and Windows, the out-of-tree platforms React Native names as its own
+ for them (`react-native-macos` and `react-native-windows`). Any other
+ third-party library or fork may be an optional integration, an example, or a
+ reference. It is never required to use Astryx on any platform. The FR12
+ dependency measure records each required runtime's maintainer and how far its
+ releases trail React Native's.
+- **FR14 — Core is unchanged by native support.** `@astryxdesign/core` never
+ imports or depends on `@astryxdesign/native`. For every theme, generated CSS,
+ mounted rules, and rendered web markup are byte-identical whether or not the
+ native package is installed. The web contract keeps every prop and base prop it
+ has today. A removal that FR7 or FR8 implies for a web caller is a breaking
+ change and ships only in a planned minor under `spec:AST-017`.
+- **FR15 — Native support ships on the canary channel until a platform is
+ supported.** `@astryxdesign/native` is a private, canary-only package
+ (`spec:AST-033/FR4`): it publishes only to the canary channel and never as a
+ stable release. It joins the stable release group in a planned minor once its
+ first platform is supported under FR11 and FR12. Until then, its platform
+ contracts and native theme configuration may change in any canary.
+- **FR16 — Native reads core in one direction, through a portable entry.**
+ `@astryxdesign/native` reads `@astryxdesign/core` only through a portable entry
+ that carries the core contracts as types and data, the `DefinedTheme` type, and
+ resolved token values. The portable entry has no DOM types, requires neither
+ `react-dom` nor StyleX, and includes no web theme compiler or web component
+ implementation, so a native app neither installs nor bundles web-only code.
+ Native platform contracts are generated from the core contract definitions at
+ 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
+ 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.
+
+- **FR17 — Icons share names and default to platform symbols.** Every
+ platform shares Astryx's semantic icon names, the built-in names plus
+ namespaced `<library>:<name>` names, carried by the portable entry. Each native
+ platform maps every built-in name to a default image from its own system set,
+ such as SF Symbols on Apple platforms and Material icons on Android, and a
+ native platform is supported only when its map covers every built-in name. An
+ icon the app or theme defines replaces the platform default. Native theme
+ configuration names platform icons as data inside a platform entry, such as
+ `icons: {close: {systemName: 'xmark.circle'}}`, so an icon that exists only on
+ some OS versions can be scoped like any other platform term; images an app
+ supplies are registered in code. A native platform has no default for a name it
+ does not map and never substitutes a web icon. Icon accessibility follows the
+ 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
+ a color, a length in density-independent units, a number, or a font name. The
+ web part holds what only the web compiles or renders: component overrides keyed
+ by web theme targets, icon and indicator registries of React elements,
+ media-surface overrides, adaptations, and build metadata. `DefinedTheme` is
+ `PortableTheme` plus the web part, so every web caller and every maintained
+ theme keeps its types and behavior. `defineNativeTheme` accepts a
+ `PortableTheme`, so a `DefinedTheme` passes unchanged. When it receives web
+ parts with content, it reports each one in development as having no native
+ meaning rather than dropping it silently; native component theming comes from
+ platform entries (FR10), and native icons follow FR17.
+
+### Platform support
+
+- Supported feature/engine floor: the web floor is unchanged. Each native
+ platform declares its supported OS versions (OQ4). Platform-scoped types need a
+ TypeScript version that supports custom resolution conditions.
+- Unsupported behavior: on an OS version outside every platform entry, durable
+ intent applies; a durable member a platform cannot realize renders as absent;
+ a platform-specific prop or component used for another platform fails at type
+ check or build (FR3, FR5).
+- Browser evidence: none for FR14, which is proven at compiler and render
+ output. Native claims are proven on real devices under FR12.
+
+## Current-state impact
+
+- `architecture:public-component-api` gains the shared base props, the web base
+ as a platform contract, base-prop targeting, and core-owned concepts (FR7)
+ when a native platform ships.
+- `architecture:cli-surface` gains the platform selection for component output
+ (FR9).
+- `architecture:theme-compilation` gains the native theme boundary when a native
+ platform 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.
+- The `theme` and `cli` consumer docs and every component's documentation gain
+ platform marking when the first native contract ships.
+- `@astryxdesign/native` does not exist yet, and `@astryxdesign/core` has no
+ portable entry yet. Core peer-depends on `react-dom` and StyleX, and its theme entry includes
+ the web theme compiler.
+- Built-in icon names are defined beside the web icon registry, which maps them to
+ React elements; the portable entry carries the names only when it ships.
+- No native platform is supported yet. Every shipped component supports the web
+ only, and its props form its web contract.
+
+## 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 |
+
+## Decision log
+
+### DEC-1 — Every platform targets its own ceiling; platforms share a core contract and the theme
+
+**Reference:** `spec:AST-082/DEC-1`
+**Decider:** cixzhang, 2026-10-20
+
+A person on any platform should get a native-first experience, so no platform
+is held to what another can express. What every platform shares is the core
+contract and the theme, which keeps behavior, words, accessibility, and identity
+consistent while each platform uses its own capabilities fully.
+
+Rejected: requiring every platform to run the web implementation, because it
+caps native experiences at what web markup and CSS can express.
+
+### DEC-2 — Native-only visuals are theme configuration, not component props
+
+**Reference:** `spec:AST-082/DEC-2`
+**Decider:** cixzhang, 2026-10-20
+
+An app's look already lives in its theme, so native-only visual intent builds on
+the defined theme in a native theme the web never loads. It can change while
+native platforms learn what they need, without risk to any web user. Platform
+props (DEC-6) carry behavior and presentation choices a platform offers, not
+visuals.
+
+Rejected: visual props for one platform on components, because they move a
+theme decision into every call site.
+
+### DEC-3 — How a native platform is built is decided by measurement
+
+**Reference:** `spec:AST-082/DEC-3`
+**Decider:** cixzhang, 2026-10-20
+
+Generated native components and web components run through a native renderer
+both remain candidates. The FR12 scorecard, measured against the platform's own
+toolkit, decides which approach a platform uses, and a platform may change
+approach when a candidate scores higher.
+
+### DEC-4 — Astryx requires only platform, first-party, and React Native's own platform runtimes
+
+**Reference:** `spec:AST-082/DEC-4`
+**Decider:** cixzhang, 2026-10-21
+
+A platform whose required runtime Astryx cannot maintain can break or stall
+outside the project's control, so required dependencies are limited to platform
+SDKs and first-party projects (FR13). React Native's out-of-tree desktop
+platforms are allowed so that React Native and pure native can be compared on
+macOS and Windows as on iOS and Android; the scorecard measures their
+maintenance risk instead of excluding them.
+
+Rejected: requiring any other third-party runtime or fork, because Astryx could
+neither fix it nor schedule around it.
+
+### DEC-5 — Native theme intent is durable; platform and version features are scoped
+
+**Reference:** `spec:AST-082/DEC-5`
+**Decider:** cixzhang, 2026-10-20
+
+Platform features are introduced, renamed, and retired across OS releases, so
+the shared native vocabulary names outcomes a person sees, and each platform
+maps them to what its running OS offers. A feature that exists only on one
+platform or OS version stays expressible inside that platform's entry and
+range, so it never reaches a platform or version where it means nothing.
+
+Rejected: platform feature names in shared native intent, because they lose
+their meaning on other platforms and OS versions.
+
+### DEC-6 — Components have platform contracts on a shared core, exposed as platform-scoped types
+
+**Reference:** `spec:AST-082/DEC-6`
+**Decider:** cixzhang, 2026-10-20
+
+One strict contract for every platform reduces each component to what every
+platform can honor, while separate per-platform components lose the shared
+meaning that people, agents, and documentation rely on. A shared core plus
+platform contracts keeps one meaning and lets each platform add its own props,
+and platform-scoped types make a prop from another platform a compile error in
+TypeScript, Swift, and Kotlin rather than a silent no-op. The TypeScript compiler
+enforces this for every named prop; hyphenated JSX attributes are the exception
+(OQ6).
+
+Rejected: one type that merges every platform's props, because it lets one
+platform's prop reach another platform's code and merges same-named props with
+different values.
+
+### DEC-7 — Native lives in its own package, `@astryxdesign/native`
+
+**Reference:** `spec:AST-082/DEC-7`
+**Decider:** cixzhang, 2026-10-21
+
+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).
+
+Rejected: native types and implementations inside `@astryxdesign/core`, because
+every web consumer would carry them and core's API would grow with each platform.
+
+### DEC-8 — The portable entry is an entry of `@astryxdesign/core`
+
+**Reference:** `spec:AST-082/DEC-8`
+**Decider:** cixzhang, 2026-10-21
+
+The core contracts, the theme definition, and token resolution already live in
+core, so a portable entry inside core moves no existing code while native is
+canary-only. Native depends on core's exact version, as other canary-only
+packages do. This decision is revisited before `@astryxdesign/native` joins the
+stable release group (FR15).
+
+Rejected: a separate shared package now, because it moves code and adds a
+package to the release group before any native platform has shipped.
+
+### DEC-9 — Web and native share contracts and logic, not components
+
+**Reference:** `spec:AST-082/DEC-9`
+**Decider:** cixzhang, 2026-10-21
+
+Code shared between a web app and a native app imports core contract types and
+non-visual logic only, and each platform's files import that platform's
+components. This keeps the one-way boundary (FR16) intact, and most native apps
+share logic rather than screens with their web app.
+
+Rejected: a shared component entry that resolves to core on the web and to
+native elsewhere, because it hides which platform's contract a call site gets.
+
+### DEC-10 — Native icons default to platform symbols
+
+**Reference:** `spec:AST-082/DEC-10`
+**Decider:** cixzhang, 2026-10-21
+
+An icon that sits beside system controls should look like the platform's own,
+so where neither the app nor the theme defines an icon, each native platform
+draws its system symbol for the shared name. Brand consistency remains a theme
+or app choice.
+
+Rejected: Astryx's web icons on every platform by default, because they look
+foreign next to system controls.
+
+### DEC-11 — The theme definition splits into a portable part and a web part
+
+**Reference:** `spec:AST-082/DEC-11`
+**Decider:** cixzhang, 2026-10-21
+
+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.
+
+Rejected: native reading the whole `DefinedTheme`, because it carries React
+elements, CSS maps, and DOM-typed imports native cannot use.
+
+## Open questions
+
+- **OQ1 — What thresholds make a candidate supported?** (`human-design`)
+ Options: parity with the toolkit reference within a fixed tolerance, or fixed
+ absolute budgets per platform. Recommendation: relative to the reference on
+ the same device and OS version — time to first content and memory within 10%,
+ no more dropped frames than the reference across a scenario, and full
+ accessibility parity — because absolute budgets drift as devices change.
+- **OQ2 — Which native platforms ship first?** (`human-design`) Options: `ios`
+ and `android` first, `macos` first, or all together. Recommendation: `ios` and
+ `android`, then `macos`, then `windows`.
+- **OQ4 — Which OS versions does each native platform support?**
+ (`human-design`) Options: the latest two major versions of each OS, or a floor
+ tied to a minimum share of active devices. Recommendation: the latest two
+ major versions, reviewed at each major OS release, because it bounds testing
+ and keeps scoped entries few.
+- **OQ5 — Must code for several native platforms use the core-only condition?**
+ (`human-api`) Options: required, so a platform prop in shared code fails in one
+ check; or optional, with shared code type-checked once per platform it runs on.
+ Recommendation: required by default, because a per-platform check passes a
+ leaked prop on every platform where the prop exists and catches it only on the
+ others.
+- **OQ6 — How are removed hyphenated base props enforced?** (`human-api`)
+ TypeScript does not check hyphenated JSX attribute names, so a removed
+ `aria-*` or `data-*` input still type-checks. Options: a lint rule, a
+ development warning with the input not applied, or both. Recommendation: both,
+ with the runtime change shipped as a breaking change under FR14.