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.mdnew file mode 100644index 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.