An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-093): native component specs live in each component's folder (#8033)
Cindy Zhang5df9b6a4db49
diff --git a/docs/specs/AST-093-native-component-guidelines/spec.md b/docs/specs/AST-093-native-component-guidelines/spec.mdindex 59fb091b3a..10f5fae044 100644--- a/docs/specs/AST-093-native-component-guidelines/spec.md+++ b/docs/specs/AST-093-native-component-guidelines/spec.md@@ -52,18 +52,24 @@ validating, and reviewing individual native components while## 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+- **FR1 — A native component's spec lives beside its implementation.** Each+ native component has its own folder in its language's implementation, named+ as the core component, and its spec is `<Name>.spec.md` in that folder, as+ core does (`packages/core/src/<Name>/<Name>.spec.md`). For Swift that is+ `packages/native/swift-ios-<n>/core/<Name>/<Name>.spec.md`, beside the+ component's views. `<Name>` is the core component's name. The spec follows`packages/native/specs/TEMPLATE.md`: summary, contract, native control,platform guidelines, brand through the theme, states, accessibility, test andvalidation, and open questions. One spec covers every implementation of thecomponent 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.+ serves `ios` and `macos`). When more than one package in a language implements+ a component, such as a later `swift-ios-<n>` generation or a macOS-only+ package, the spec lives in that component's folder in the lowest-numbered+ live package of the language. Rules that apply across a language's components+ live under `packages/native/specs/<language>/`. 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'sown control when one satisfies its contract (`spec:AST-082/FR11`). In Swiftthat is a SwiftUI control, or a UIKit or AppKit control where SwiftUI has@@ -135,6 +141,9 @@ validating, and reviewing individual native components whilepublished.- 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 `swift-ios-1`, which arrives with the SwiftUI package; until it+ is on `main`, no component folder exists and no component spec can be added.- The first Swift views in `swift-ios-1` (Banner, Button, Card, Heading, Text,and TextInput) take hand-written parameters, including `action` for thecontract's `onClick`, until they move to the generated contracts. Until then@@ -146,7 +155,7 @@ validating, and reviewing individual native components while| 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 |+| FR1 | Review of the spec's path beside the component and its sections against the template | a spec per language; a spec for a component with no core contract | A component spec outside its component's folder, 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 |diff --git a/packages/native/specs/README.md b/packages/native/specs/README.mdindex 895f19138e..ca2701c5ba 100644--- a/packages/native/specs/README.md+++ b/packages/native/specs/README.md@@ -1,15 +1,21 @@# Native component specs-One short spec per native component, per language. The rules live in+One short spec per native component, per language, kept in the component's own+folder beside its implementation, the way core keeps `TabList.spec.md` next to+`TabList.tsx`. 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- └── library/ # rules every Swift component or build step shares+packages/native/+├── specs/+│ ├── TEMPLATE.md # copy this for a new component spec+│ └── swift/ # rules shared by every Swift component+│ └── library/ # rules every Swift component or build step shares+└── swift-ios-1/core/+ └── <Name>/ # one folder per component, named as core's+ ├── Astryx<Name>.swift+ └── <Name>.spec.md # the component's spec, e.g. Button.spec.md```Swift comes first. Kotlin and other languages get their own directory when@@ -33,7 +39,8 @@ the same everywhere. A native spec never renames or changes it.## Adding a spec-1. Copy `TEMPLATE.md` to `<language>/<Name>.md`.+1. Copy `TEMPLATE.md` to the component's folder as `<Name>.spec.md`, for+ Swift `swift-ios-1/core/<Name>/<Name>.spec.md`.2. Fill every section. Write "None" rather than deleting one.3. Open a pull request that changes only files under `packages/native/`. A speccan land on its own or with the component it describes.diff --git a/packages/native/specs/TEMPLATE.md b/packages/native/specs/TEMPLATE.mdindex 9eb1dd9857..96b0ebcdc7 100644--- a/packages/native/specs/TEMPLATE.md+++ b/packages/native/specs/TEMPLATE.md@@ -1,6 +1,7 @@# <Name> (<language>)-<!-- Copy to packages/native/specs/<language>/<Name>.md. Fill every section;+<!-- Copy into the component's folder as <Name>.spec.md (Swift:+packages/native/swift-ios-1/core/<Name>/<Name>.spec.md). Fill every section;write "None" rather than deleting one. Present tense: describe what thecomponent does, not how it was decided. Rules: AST-093. -->diff --git a/packages/native/specs/swift/README.md b/packages/native/specs/swift/README.mdindex 457ffec7d0..acfdb0be25 100644--- a/packages/native/specs/swift/README.md+++ b/packages/native/specs/swift/README.md@@ -1,8 +1,11 @@-# Swift component specs+# Swift 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).+Rules shared by every Astryx component written in Swift, for iOS and macOS.++A single component's spec lives in that component's own folder, beside its+views: `packages/native/swift-ios-1/core/<Name>/<Name>.spec.md`, named as the+core component (`Button.spec.md`, `TextInput.spec.md`) and copied from+[`../TEMPLATE.md`](../TEMPLATE.md).Start with a component that already has a generated contract in`packages/native/src/components/`.diff --git a/packages/native/specs/swift/library/README.md b/packages/native/specs/swift/library/README.mdindex 5f5b39f484..723d48fa4a 100644--- a/packages/native/specs/swift/library/README.md+++ b/packages/native/specs/swift/library/README.md@@ -1,7 +1,8 @@# Swift library specsRules that every Astryx Swift component or Swift build step shares, one-concern per file. A component spec (`../<Name>.md`, from+concern per file. A component spec (`<Name>.spec.md` in the component's own+folder, such as `swift-ios-1/core/Button/Button.spec.md`, from`../../TEMPLATE.md`) follows these and records only where a component differs.These specs apply AST-082 (native-first surfaces) and AST-093 (native component