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