Skip to content

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

TypeScript

spec(AST-093): native component guidelines and a spec area for native components (#8021)

Cindy Zhang1cafa66090aa
diff --git a/docs/specs/AST-093-native-component-guidelines/spec.md b/docs/specs/AST-093-native-component-guidelines/spec.md
new file mode 100644
index 0000000000..8d9ecc97b5
--- /dev/null
+++ b/docs/specs/AST-093-native-component-guidelines/spec.md
@@ -0,0 +1,173 @@
+---
+schema_version: 4
+template_version: 2
+kind: system-spec
+id: spec:AST-093
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-23
+phase: accepted
+owners: [cixzhang]
+affects_architecture: []
+affects_families: []
+affects_contributing: []
+affects_consumer_docs: []
+---
+
+# Native component guidelines 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 app built with `@astryxdesign/native` gets controls that look
+and behave like their platform's own, carry the app's brand wherever the
+platform leaves room for it, and were checked the same way every time.
+
+A contributor building a native component writes a short spec for it in one
+place and one shape, follows three guidelines in a fixed order (native-first,
+then the platform's own design guidelines, then the theme for everything else),
+and proves the result with the same tests and captures as every other native
+component. Native components start in Swift, for iOS and macOS.
+
+This record applies `spec:AST-082` to the work of specifying, building,
+validating, and reviewing individual native components while
+`@astryxdesign/native` is canary-only (`spec:AST-082/FR15`).
+
+## Non-goals
+
+- Which way of building a platform wins. `spec:AST-082/FR12` decides that by
+ measurement.
+- Supported OS versions (`spec:AST-082/OQ4`) and performance thresholds
+ (`spec:AST-082/OQ1`).
+- A component's core contract: its shared props, states, words, and
+ accessibility semantics. The component's own record and `spec:AST-082/FR3`
+ own them.
+- Guidelines for Android and Windows (OQ1).
+- Web components and `@astryxdesign/core`.
+- Equivalent internal implementations remain valid when they satisfy this
+ contract.
+
+## Requirements
+
+- **FR1 — Native component specs live in one place, in one shape.** A native
+ component's spec is `packages/native/specs/<language>/<Name>.md`, where
+ `<language>` is the language its implementations are written in (`swift`
+ first) and `<Name>` is the core component's name. It follows
+ `packages/native/specs/TEMPLATE.md`: summary, contract, native control,
+ platform guidelines, brand through the theme, states, accessibility, test and
+ validation, and open questions. One spec covers every implementation of the
+ component in that language, on every platform the language serves (Swift
+ serves `ios` and `macos`). A merged native component spec describes that
+ component's implementations in that language. It never changes the core
+ contract and never contradicts `spec:AST-082` or this record; where it does,
+ they win.
+- **FR2 — Native-first comes first.** A native component uses the platform's
+ own control when one satisfies its contract (`spec:AST-082/FR11`). In Swift
+ that is a SwiftUI control, or a UIKit or AppKit control where SwiftUI has
+ none. A component draws its own control only where the platform has none, and
+ its spec names the platform control it looked for and why it does not fit.
+- **FR3 — Apple platforms follow the Apple Human Interface Guidelines.** On
+ `ios` and `macos`, presentation and interaction follow the Apple Human
+ Interface Guidelines: layout and spacing conventions, minimum hit targets,
+ Dynamic Type, SF Symbols (`spec:AST-082/FR17`), system materials, motion
+ including Reduce Motion, haptics, and VoiceOver. Each spec names the guideline
+ pages it follows. The core contract keeps the component's meaning, words,
+ states, and accessibility semantics; the guidelines decide how the platform
+ presents them.
+- **FR4 — Brand shows through the theme everywhere else.** What FR2 and FR3
+ leave open, such as accent and fill color, type family, corner shape,
+ spacing, and icon choice, comes from the app's theme: tokens from its
+ `defineTheme` definition (`spec:AST-082/FR18`) and native intent and platform
+ entries from `defineNativeTheme` (`spec:AST-082/FR10`). A component reads
+ every such value from the theme, never hard-codes one, and never adds a
+ visual prop for one platform (`spec:AST-082/DEC-2`). Each spec lists the
+ theme values the component reads.
+- **FR5 — Every native component is tested and validated the same way.** A
+ change to a native component ships with:
+ - unit tests in its package's test target for parameter mapping, defaults,
+ and state changes, built and run on every platform the package supports;
+ - parameters named and typed as the generated contract for the component
+ (`spec:AST-082/FR5`), with the contract drift tests passing;
+ - accessibility assertions for the label, traits, and value the core
+ contract requires, plus a check at the largest Dynamic Type size;
+ - a check that the component renders from two different themes with no
+ value of its own in between;
+ - captures of every state from a simulator or device, in light and dark and
+ at the largest text size, attached to the change. Native-first, guideline,
+ and brand claims rest on these captures, never on source or style values
+ (`spec:AST-082/FR12`). A claim that could not be captured is reported as not
+ measured.
+- **FR6 — Native changes from the native group are approved on sight.** A pull
+ request whose every changed file is under `packages/native/`, and whose author
+ and every commit author are members of the native group, is approved by an
+ engineering owner on its exact head once its required checks pass, without a
+ separate code or design review. The native group is the GitHub accounts
+ `cixzhang`, `ejc3`, `ejhammond`, `ernestt`, `imdreamrunner`, and `vjeux`. A
+ pull request that changes any file outside `packages/native/`, or that carries
+ a commit from anyone else, follows the repository's normal review gate. A
+ request for changes from any reviewer still blocks the merge. Changing the
+ group is a change to this record.
+
+### Platform support
+
+- Supported feature/engine floor: each Swift package declares its own platforms
+ and OS versions until `spec:AST-082/OQ4` is settled.
+- Unsupported behavior: a capability newer than the running OS degrades as
+ `spec:AST-082/FR11` requires; a component never renders a blank or broken
+ state.
+- Browser evidence: none. Native claims are proven by captures from a
+ simulator or device (FR5).
+
+## Current-state impact
+
+- `@astryxdesign/native` gains `packages/native/specs/`, holding the template
+ and one directory per language, starting with `swift/`. The directory is not
+ published.
+- No architecture, family, contributing, or consumer-doc record changes.
+- No native component spec exists yet.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| FR1 | Review of the spec's path and sections against the template | a spec per language; a spec for a component with no core contract | A spec outside `packages/native/specs/<language>/`, missing a template section, or renaming a core prop passes review |
+| FR2 | The spec's native-control section and the state captures | a component built on a platform control; a component with no platform control | A component draws its own control where a platform control fits, with no reason in its spec |
+| FR3 | The spec's guideline section and the captures | hit target size; largest Dynamic Type; Reduce Motion; VoiceOver focus | A capture shows a hit target below the platform minimum or text that does not scale |
+| FR4 | Theme test with two themes, plus source review for literals | default theme; a second theme with different color, type, and shape | A brand value stays the same across both themes, or a platform-only visual prop is added |
+| FR5 | The package's tests on every supported platform and the captures attached to the change | light; dark; largest text; every state the core contract names | A change merges without tests, without captures, or with a capture-based claim backed only by source |
+| FR6 | The pull request's changed paths, commit authors, and approval | all native paths by group members; a path outside `packages/native/`; a commit from someone else | An out-of-scope pull request is approved without review, or an in-scope one waits on a separate review |
+
+## Decision log
+
+### DEC-1 — Platform conventions decide first; the theme fills what they leave open
+
+**Reference:** `spec:AST-093/DEC-1`
+**Decider:** cixzhang, 2026-10-23
+
+A person on iOS or macOS expects controls to look and act like the rest of
+their device, so the platform's own control and the Apple Human Interface
+Guidelines decide first. An app's identity still matters, so everything the
+platform leaves open comes from the theme the app already defines once for
+every surface.
+
+Rejected: matching the web rendering pixel for pixel, because it overrides the
+platform conventions the person relies on.
+
+### DEC-2 — Native changes from the native group do not wait on review
+
+**Reference:** `spec:AST-093/DEC-2`
+**Decider:** cixzhang, 2026-10-23
+
+`@astryxdesign/native` publishes only to the canary channel, so no stable user
+receives a native change. While the experiment runs, the people building it
+need to collect specs and land components quickly; required checks, captures,
+and any reviewer's request for changes still protect the branch.
+
+## Open questions
+
+- **OQ1 — Which guidelines apply on Android and Windows?** (`human-design`)
+ Each platform's first native component needs the counterpart of FR3 before it
+ merges.
diff --git a/packages/native/specs/README.md b/packages/native/specs/README.md
new file mode 100644
index 0000000000..28f4e33362
--- /dev/null
+++ b/packages/native/specs/README.md
@@ -0,0 +1,57 @@
+# Native component specs
+
+One short spec per native component, per language. The rules live in
+[AST-093 (Native component guidelines)](../../../docs/specs/AST-093-native-component-guidelines/spec.md),
+which applies [AST-082 (Native-first surfaces)](../../../docs/specs/AST-082-native-first-surfaces/spec.md).
+
+```text
+packages/native/specs/
+├── TEMPLATE.md # copy this for a new spec
+└── swift/ # Swift: iOS and macOS
+ └── <Name>.md # named as the core component, e.g. Button.md
+```
+
+Swift comes first. Kotlin and other languages get their own directory when
+their first component starts.
+
+## The three guidelines, in order
+
+1. **Native-first.** Use the platform's own control when it fits the
+ component's contract. In Swift: SwiftUI, then UIKit or AppKit. Draw a custom
+ control only when the platform has none, and say why in the spec.
+2. **Apple Human Interface Guidelines.** On iOS and macOS, presentation and
+ interaction follow the HIG: hit targets, Dynamic Type, SF Symbols, materials,
+ motion and Reduce Motion, haptics, VoiceOver. Name the pages you follow.
+3. **Brand through the theme.** Everything the first two leave open (color,
+ type family, shape, spacing, icon choice) comes from the app's theme:
+ `defineTheme` tokens and `defineNativeTheme` intent. Never hard-code a
+ brand value and never add a visual prop for one platform.
+
+The core contract (prop names, states, words, accessibility semantics) stays
+the same everywhere. A native spec never renames or changes it.
+
+## Adding a spec
+
+1. Copy `TEMPLATE.md` to `<language>/<Name>.md`.
+2. Fill every section. Write "None" rather than deleting one.
+3. Open a pull request that changes only files under `packages/native/`. A spec
+ can land on its own or with the component it describes.
+
+Pull requests that change only `packages/native/`, written entirely by the
+native group listed in AST-093 FR6, are approved once required checks pass.
+
+## Test and validation
+
+Every native component change ships with the evidence in AST-093 FR5. For
+Swift:
+
+```sh
+pnpm vitest run --project node packages/native # contracts, generated code, theme drift
+pnpm -F @astryxdesign/native typecheck
+cd packages/native/<swift package> && swift build && swift test # on a Mac with Xcode
+```
+
+CI builds and tests every Swift package under `packages/native/` on macOS and
+the iOS Simulator. Attach captures of every state, from a simulator or device,
+in light and dark and at the largest text size. Anything you could not capture
+is reported as not measured.
diff --git a/packages/native/specs/TEMPLATE.md b/packages/native/specs/TEMPLATE.md
new file mode 100644
index 0000000000..9eb1dd9857
--- /dev/null
+++ b/packages/native/specs/TEMPLATE.md
@@ -0,0 +1,60 @@
+# <Name> (<language>)
+
+<!-- Copy to packages/native/specs/<language>/<Name>.md. Fill every section;
+write "None" rather than deleting one. Present tense: describe what the
+component does, not how it was decided. Rules: AST-093. -->
+
+## Summary
+
+<!-- One to three sentences: who uses this component, in what situation, and
+what they get. -->
+
+## Contract
+
+- Core component: `<Name>` (core contract in `packages/native/src/components/<Name>.ts`).
+- Platforms: `<ios | macos>`.
+- Platform props: <!-- props only this platform offers, or "None". Never rename
+ or change a core prop. -->
+
+## Native control
+
+<!-- The platform control this is built on (SwiftUI first, then UIKit or
+AppKit). If the component draws its own control, name the platform control you
+looked for and why it does not fit. -->
+
+## Platform guidelines
+
+<!-- The Apple Human Interface Guidelines pages this follows, and what each one
+decides here: hit target, Dynamic Type, SF Symbols, materials, motion and
+Reduce Motion, haptics. -->
+
+## Brand through the theme
+
+| What | Theme value |
+| -------------- | ------------------------------------- |
+| <!-- color --> | <!-- token or native theme member --> |
+
+<!-- Every brand value the component reads. Nothing here is hard-coded. -->
+
+## States
+
+<!-- Every state the core contract names (default, pressed, disabled, loading,
+error, ...) and how each looks and behaves on this platform. -->
+
+## Accessibility
+
+<!-- VoiceOver label, traits, and value for each state; focus behavior; what is
+announced. These come from the core contract. -->
+
+## Test and validation
+
+- Unit tests: <!-- what the package's test target covers -->
+- Contract: parameters match the generated contract; drift tests pass.
+- Accessibility: <!-- assertions, and the largest Dynamic Type check -->
+- Theme: renders from two different themes with no value of its own.
+- Captures: every state, light and dark, largest text size, from a simulator or
+ device. <!-- list anything not measured -->
+
+## Open questions
+
+<!-- Unanswered questions only, or "None". -->
diff --git a/packages/native/specs/swift/README.md b/packages/native/specs/swift/README.md
new file mode 100644
index 0000000000..457ffec7d0
--- /dev/null
+++ b/packages/native/specs/swift/README.md
@@ -0,0 +1,8 @@
+# Swift component specs
+
+Specs for Astryx components written in Swift, for iOS and macOS. One file per
+component, named as the core component (`Button.md`, `TextInput.md`), copied
+from [`../TEMPLATE.md`](../TEMPLATE.md).
+
+Start with a component that already has a generated contract in
+`packages/native/src/components/`.