An open source design system that's fully customizable and agent ready
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-24 phase: accepted owners: [cixzhang] affects_architecture: [] affects_families: [] affects_contributing: [] affects_consumer_docs: []
Native component guidelines system spec
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/FR12decides 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/FR3own them. - Guidelines for Android and Windows (OQ1).
- Web components and
@astryxdesign/core. - Equivalent internal implementations remain valid when they satisfy this contract.
Requirements
- FR1 — A native component's spec lives beside the core component's. Each
native component's views live in its language's implementation, in the
folder that mirrors its core component root (the core source directory):
<ComponentRoot>, which is<Name>when core keeps the component in its own folder, so core'sAvatar/AvatarStatusDotputs the Swift AvatarStatusDot views inAvatar/too. Spec lookup routes a native view to its component's records by that folder, which is why the folder is part of the contract. Its spec is<Name>.<language>.spec.mdin the core component's folder underdocs/specs/components/, beside the core record (docs/specs/components/<ComponentRoot>/<Name>.spec.md), asarchitecture:knowledge-contractsDEC-15 places every component record. Each language has one implementation package; for Swift that ispackages/native/apple/, with the component's views inpackages/native/apple/Sources/Astryx/<ComponentRoot>/, and its spec isdocs/specs/components/<ComponentRoot>/<Name>.swift.spec.md.<Name>is the core component's name, and<ComponentRoot>the folder core keeps it in. The spec is a knowledge record of kindcomponentwith idcomponent:<language>/<Name>that names its core component inplatform_of, built fromdocs/templates/knowledge/component-spec.md(architecture:knowledge-contractsINV27). Until the core component has its own record,platform_ofstill namescomponent:<Name>, and the core component's public source and documentation stand in as its contract. One spec covers every implementation of the component in that language, on every platform the language serves (Swift servesiosandmacos). Rules that apply across a language's components are architecture records underpackages/native/specs/<language>/, named<slug>.spec.md. A merged native component spec describes that component's implementations in that language. It never changes the core contract and never contradictsspec:AST-082or 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
iosandmacos, 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, except that a choice between presentations by screen size uses the compact definition ofspec:AST-012FR9 rather than size classes. - 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
defineThemedefinition (spec:AST-082/FR18) and native intent and platform entries fromdefineNativeTheme(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 platform's generated contract for the
component (
spec:AST-082/FR5): the core props every platform honors plus that platform's own props (spec:AST-082/FR3), never a prop kept for parity alone, with the contract drift tests passing, except for the interim Swift views listed in Current-state impact; - 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 after a spec
review. A pull request whose every changed file is under
packages/native/or is a native component spec (docs/specs/components/**/<Name>.<language>.spec.md), and whose author and every commit author are members of the native group, is approved by an engineering owner on its exact head, without a separate code or design review, once all three hold: its required checks pass; the review app has reviewed that exact head and names no defect; and a review of the change againstspec:AST-082, this record, and the native spec of every component it touches finds every requirement they define met. Behavior a spec defines must match it, and a change that breaks such a requirement is not approved. Behavior no spec defines yet does not block approval, as in the lab package: the review records each such behavior as a spec gap so a spec can follow. The native group is the GitHub accountscixzhang,ejc3,ejhammond,ernestt,imdreamrunner, andvjeux. A pull request that changes any file outside those paths, 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/OQ4is settled. - Unsupported behavior: a capability newer than the running OS degrades as
spec:AST-082/FR11requires; 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/nativegainspackages/native/specs/, holding one directory per language, starting withswift/. The directory is not published.- The Swift specs under
packages/native/specs/swift/and the package templatepackages/native/specs/TEMPLATE.mdpredate FR1's record form. They convert to knowledge records in one change, which removes the template. Until then, the package READMEs still name the template, and a new component spec follows FR1 instead. - No architecture, family, contributing, or consumer-doc record changes.
- No native component spec exists yet.
- Component folders live inside a language's implementation package. For
Swift that is
packages/native/apple/, whoseAstryxproduct holds the SwiftUI views. - The first Swift views in the
Astryxproduct (Banner, Button, Card, Heading, Text, and TextInput) take hand-written parameters, includingactionfor the contract'sonClick, until they move to the generated contracts. Until then they are the only native components exempt from FR5's generated-parameter requirement; every other FR5 check applies to them. A new view never takes this exemption. - Swift tests run as Swift package tests, where SwiftUI exposes no accessibility tree, so FR5's accessibility assertions check the label, traits, and value a view sets, not the tree VoiceOver reads. Until an app-hosted iOS test target exists, a change reports the rendered tree's accessibility as not measured, as FR5 reports a claim it could not capture. Every other FR5 check applies.
Verification
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1 | Review of the views' folder and of the spec's path beside the core component's spec, plus pnpm check:knowledge on its record frontmatter, id, and platform_of |
a spec per language; a spec for a component with no core contract; a member component core keeps in another component's folder | Views outside the folder that mirrors the core component root, a component spec outside the core component's folder under docs/specs/components/, without valid record frontmatter, under another id, naming no core component, or renaming a core prop passes |
| FR2 | The spec's account of the platform control it builds on, or why none fits, 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 account of the platform guidelines it follows, 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 | Changed paths, commit authors, the review app's exact-head review, the spec review's findings, and the approval | all native paths by group members; a spec-defined requirement unmet; behavior no spec defines; a native component spec under docs/specs/components/; a path outside packages/native/ and those specs; a commit from someone else |
An approval without an exact-head review-app pass or a spec review, an approval with a spec-defined requirement unmet, an out-of-scope pull request approved without review, or an in-scope one blocked only for behavior no spec defines |
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 merge on a spec 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 land components quickly, so a native change waits on no separate code
or design review. The specs stay the contract: every change is reviewed against
them before approval, and a spec-defined requirement it breaks blocks it.
Behavior no spec covers yet is welcome, as in the lab package, and becomes a
spec gap to close rather than a reason to wait. Required checks, captures, and
any reviewer's request for changes still protect the branch.
Rejected: approving on passing checks alone, because a change that breaks a spec would merge unreviewed.
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.