Skip to content

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

TypeScript

spec(native): Swift theme generator turns any Astryx theme into an AstryxTheme (#8031)

Cindy Zhang0026f37ae181
diff --git a/packages/native/specs/README.md b/packages/native/specs/README.md
index 61fff02f08..895f19138e 100644
--- a/packages/native/specs/README.md
+++ b/packages/native/specs/README.md
@@ -8,7 +8,8 @@ which applies [AST-082 (Native-first surfaces)](../../../docs/specs/AST-082-nati
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
+ ├── <Name>.md # named as the core component, e.g. Button.md
+ └── library/ # rules every Swift component or build step shares
```
Swift comes first. Kotlin and other languages get their own directory when
diff --git a/packages/native/specs/swift/library/README.md b/packages/native/specs/swift/library/README.md
new file mode 100644
index 0000000000..461f432c46
--- /dev/null
+++ b/packages/native/specs/swift/library/README.md
@@ -0,0 +1,14 @@
+# Swift library specs
+
+Rules that every Astryx Swift component or Swift build step shares, one
+concern per file. A component spec (`../<Name>.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
+guidelines). Where one of them and an approved record disagree, the record
+wins.
+
+| File | Concern |
+| -------------------- | ------------------------------------------------------------------------------------- |
+| `accessibility.md` | How core's accessibility semantics reach VoiceOver and Apple's accessibility settings |
+| `theme-generator.md` | How any Astryx theme becomes a Swift `AstryxTheme` |
diff --git a/packages/native/specs/swift/library/theme-generator.md b/packages/native/specs/swift/library/theme-generator.md
new file mode 100644
index 0000000000..7831599553
--- /dev/null
+++ b/packages/native/specs/swift/library/theme-generator.md
@@ -0,0 +1,205 @@
+# Theme generator (Swift)
+
+- Status: draft
+- Relation: extends AST-082 FR10, FR18 and AST-093 FR4, and applies AST-082
+ FR16 and AST-006. It is the one path by which a theme reaches Swift.
+
+## Summary
+
+An iOS app built with Astryx shows its own brand, not only core's default: any
+Astryx theme, from a published theme package such as neutral or from the
+product itself, becomes a Swift `AstryxTheme` that `.astryxTheme(.neutral)`
+applies, with the same light and dark values and typeface the web uses. Every shared
+token is a typed Swift member, so a misspelled token fails to compile instead
+of drawing nothing. The generator runs core's own resolver, so Swift never
+re-implements theme logic.
+
+## Requirements
+
+- **G1 — Input is a portable theme; core resolves it.** The generator is one
+ function, `renderSwiftTheme(theme, options)`. Its input is a `PortableTheme`
+ (name, tokens, theme-local tokens; AST-082 FR18). A `DefinedTheme` from
+ `defineTheme` passes unchanged, since it is a `PortableTheme` plus a web
+ part the generator ignores. Until core ships `PortableTheme`, the input type
+ is `DefinedTheme`. Values come only from core's
+ `resolveThemeTokens(theme, {mode})`, called once with `mode: 'light'` and
+ once with `mode: 'dark'`. A token whose whole value is
+ `light-dark(<light>, <dark>)` takes its first argument in light mode and its
+ second in dark mode, as the resolver hands them. The generator never reads
+ `theme.tokens` directly and never evaluates a color or reference itself.
+- **G2 — Core is read only at build time.** The generator runs at build time;
+ generated Swift imports only SwiftUI and carries nothing from core at run
+ time (AST-082 FR16). Until core's portable entry ships, the generator reads
+ core at build time through `@astryxdesign/core/theme` and
+ `@astryxdesign/core/theme/tokens`, the build-time reads AST-082 FR16 allows
+ a native build script, each listed in the boundary check; once the portable
+ entry ships, it reads core only through that entry.
+- **G3 — One shared token type, one file per theme.**
+ - `swift-ios-1/core/Theme/Generated/AstryxTokens.swift` declares the typed
+ token surface: `AstryxTokens` with one member per group (`color`, `space`,
+ `radius`, `size`, `font`), each a struct with one typed member per token.
+ It is generated from core's resolved token names, which are the same for
+ every theme (G5), so it does not depend on any one theme.
+ - Each theme becomes `swift-ios-1/core/Theme/Generated/<SwiftName>Theme.swift`,
+ which declares `AstryxTheme.<swiftName>` with an `AstryxTokens` value for
+ light and one for dark.
+ - `<swiftName>` is the theme's `name` with a leading `astryx-` removed, in
+ lower camel case (`neutral` → `neutral`, `y2k` → `y2k`, a product's
+ `acme-brand` → `acmeBrand`). Core's defaults, which core resolves with no
+ theme (`resolveThemeTokens(null, {mode})`), are `default`. A name that is not a valid Swift identifier, is a Swift keyword
+ other than `default`, or repeats another generated theme's name fails the
+ run.
+ - Each file starts with a header naming the source package, its version, and
+ the theme name, says "Do not edit", and names the regenerate command.
+- **G4 — Output is deterministic.** The same theme and the same core produce
+ byte-identical files: members sorted, numbers in their shortest exact form,
+ no dates, paths, or machine details.
+- **G5 — The token set is a contract.** The generator keeps these groups of
+ core's resolved token names: `color-*`, `spacing-*`, `radius-*`,
+ `size-element-*`, `border-width`, `font-size-*`, `font-weight-*`,
+ `font-family-*`, and `text-<style>-*` for `heading-1` to `heading-6`,
+ `body`, `large`, `label`, and `supporting`. Core fills every shared token a
+ theme leaves out, so every theme has the same shared members. Adding a group
+ changes this spec, the generator, and the Swift reader in one pull request,
+ together with the first component that reads it.
+- **G6 — Token names map to Swift members by one rule.** A token's Swift member
+ is its group and the rest of its name in lower camel case, with each `-`
+ between two digits written `_`:
+
+ | Token | Member |
+ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+ | `color-<rest>` | `color.<rest>`: `color-text-primary` → `color.textPrimary`, `color-data-blue-1` → `color.dataBlue1` |
+ | `spacing-<n>` | `space.s<n>`: `spacing-4` → `space.s4`, `spacing-0-5` → `space.s0_5` |
+ | `radius-<rest>` | `radius.<rest>`: `radius-element` → `radius.element` |
+ | `size-element-<rest>`, `border-width` | `size.element<Rest>`: `size-element-md` → `size.elementMd`; `size.borderWidth` |
+ | `font-size-<rest>`, `font-weight-<rest>`, `font-family-<rest>` | `font.size<Rest>`, `font.weight<Rest>`, `font.family<Rest>`: `font-size-2xl` → `font.size2xl`, `font-family-body` → `font.familyBody` |
+ | `text-<style>-<part>` | `font.<style><Part>`: `text-body-size` → `font.bodySize`, `text-heading-1-weight` → `font.heading1Weight` |
+
+ Two tokens that map to the same member, or a member that is a Swift keyword
+ or does not start with a letter, fail the run with both token names.
+
+- **G7 — Values are typed and exact, or the run fails.**
+ - Colors are `Color` values in sRGB, from `#RGB`, `#RGBA`, `#RRGGBB`,
+ `#RRGGBBAA`, `rgb()`/`rgba()` and `hsl()`/`hsla()` (comma or space
+ separated, hue in degrees or unitless, alpha as a number or a percentage),
+ and the keywords `black`, `white`, and `transparent`. Every color is
+ stored as 8-bit sRGB channels: an `hsl()` value is converted exactly, then
+ each channel is rounded to the nearest of 256 steps, halves up.
+ - Lengths are `CGFloat` points: `rem` × 16, `px` × 1. Unitless numbers
+ (weights, line-height ratios) are `CGFloat`.
+ - Font families are `[String]`, quotes removed, in the CSS stack's order.
+ - Any other value in a kept group, such as `oklch()`, `color-mix()`,
+ `calc()`, an unresolved `var()`, or `light-dark()`, fails the run with the
+ theme, mode, token, and value. A token present in one mode and missing in
+ the other fails the same way. Nothing is dropped or guessed.
+- **G8 — Theme-local tokens wait for a per-mode source.** A theme's local
+ tokens (AST-006) are generated only once core's resolver returns them per
+ mode, as it returns shared tokens; until then the generator emits none and
+ reports each local token it leaves out. When generated, each value is keyed
+ by its exact custom-property name (AST-006 FR3, DEC-2), with no second
+ identifier and no prefix read or removed, in a map of its value's type (G7)
+ for light and for dark, carried only by that theme
+ (`AstryxTheme.neutral.local.dark.colors["--astryx-theme-neutral-color-status-fill-accent"]`).
+ A name the theme does not declare returns `nil`, and the caller chooses
+ what to draw. Only code written for that theme reads them; shared components never
+ do.
+- **G9 — Components read typed members.** Components read tokens only through
+ the typed members (`theme.color.textPrimary`). A lookup by token name may
+ exist inside the package as a fallback for wire-driven code; it is not public
+ and no component uses it.
+- **G10 — Font names map to SwiftUI fonts, with a system fallback.** The reader
+ walks a family list in order and uses the first family the app has
+ available (`UIFont(name:size:)` on iOS, `NSFont(name:size:)` on macOS, is
+ not nil) as `Font.custom(_:size:relativeTo:)`, so on iOS it still scales
+ with Dynamic Type. A
+ generic or system name ends the walk with the system font: `-apple-system`,
+ `system-ui`, `BlinkMacSystemFont`, and `sans-serif` → `.default` design;
+ `ui-monospace`, `SF Mono`, `monospace` → `.monospaced`; `ui-serif`, `serif`
+ → `.serif`; `ui-rounded` → `.rounded`. A list with no available family draws
+ the system font. The library never bundles or downloads a font; an app that
+ wants its brand typeface bundles and registers the font file itself.
+- **G11 — Native intent has a reserved slot.** `AstryxTheme.native` is a
+ documented member that is empty until a component reads native intent (D3).
+- **G12 — Every published theme is generated, and a product's own theme can be.**
+ Core's default theme and every theme package under `packages/themes/` whose
+ `package.json` is not `private` has a generated file. A product generates its
+ own theme by passing its theme to `renderSwiftTheme`, or through the
+ package's command (`generate:swift-ios --theme <module>#<export>`).
+- **G13 — The drift check covers the typed surface.** A test regenerates
+ `AstryxTokens.swift` and every committed theme file and fails when any file
+ differs, when a published theme has no file, or when a file has no published
+ theme. The failure names the regenerate command.
+- **G14 — Generated files stay committed for now.** Swift Package Manager
+ installs from a git commit and cannot run the Node generator, so generated
+ files are committed beside the Swift sources until CI publishes generated
+ Swift to a Swift-only branch or tag, as the package README notes.
+
+## Acceptance checks
+
+| Requirement | Check |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| G1 | A theme whose resolved token differs from its raw `theme.tokens` entry (a reference) shows the resolved value in Swift. A `DefinedTheme` with web component overrides generates the same file as the same theme without them. |
+| G2 | A source check finds no import of core in `packages/native/` outside the build-time reads AST-082 FR16 lists (the two theme entries, core's component documentation, its built-in icon names, and its locale catalogs; later only the portable entry). Generated Swift imports only SwiftUI. |
+| G3 | `swiftc -typecheck` compiles `AstryxTokens.swift` and every theme file together; each theme file declares one `AstryxTheme` static named as G3 says; two themes with the same name fail the run. |
+| G4 | Generating twice, and on two CI machines, gives byte-identical output. |
+| G5 | Every theme's light and dark values fill every member of `AstryxTokens`, equal to core's resolved names filtered by the G5 groups. |
+| G6 | Unit tests map every row of the G6 table; two tokens that collide fail with both names. A Swift fixture referencing `theme.color.textPrimray` fails to compile. |
+| G7 | A token written as `light-dark(#000, #fff)` generates black in light and white in dark. `hsl(210 100% 50%)` generates the same color as `#0080FF`. Unit tests convert every listed form; `oklch(0 0 0 / 5%)` in a kept group fails with theme, mode, token, and value in the message; `"Figtree", -apple-system, sans-serif` becomes `["Figtree", "-apple-system", "sans-serif"]`. |
+| G8 | Neutral's local tokens generate nothing today and each is reported; a fixture whose local tokens come back per mode generates its values keyed by their exact custom-property names in that theme's `local` maps, none in `AstryxTokens`. |
+| G9 | A source check finds no token lookup by string in any component. |
+| G10 | On iOS and macOS, a Swift test with no bundled Figtree resolves `font.familyBody` to the system font and with a registered test font resolves to that font; on iOS, both scale between Large and AX5. |
+| G11 | `AstryxTheme.native` exists, is documented, and holds no values. |
+| G12 | A test reads `packages/themes/*/package.json` and finds one generated file per non-private package plus `default`. A fixture product theme renders through `renderSwiftTheme`. |
+| G13 | Editing one generated value or member name by hand fails the drift test with the regenerate command in the message. |
+| G14 | The README's generated-Swift note lists the generated theme files. |
+
+## Decisions
+
+- **D1 — The boundary check covers all of `packages/native/`.** The
+ package-boundary check scans every folder under `packages/native/`, so a core
+ import anywhere in the package is checked against AST-082 FR16, with every
+ build-time read FR16 allows listed by name: the generator's two theme entries
+ (G2), the contract generator's reads of core's component documentation and
+ built-in icon names, and the strings generator's read of core's locale
+ catalogs.
+- **D2 — Shared tokens are typed from the start.** For the shared token
+ surface, the generator emits typed members
+ (G3, G6), not string-keyed dictionaries, so a wrong token name fails to
+ compile and autocompletion lists every token. Rejected: string keys with a
+ missing-token fallback, because a typo ships invisible text. A theme's local
+ values are keyed by their exact names instead (G8), because AST-006 FR3
+ allows no second identifier.
+- **D3 — Native intent comes from `defineNativeTheme` into a reserved slot.**
+ Native visual intent (durable `material`, platform entries, icons; AST-082
+ FR10, FR17) comes from `defineNativeTheme`, a native theme that wraps the
+ portable theme. When the first component reads `material`, the generator
+ takes the native theme, reads the wrapped portable theme from it, and fills
+ `AstryxTheme.native` already resolved per OS version range, so one call
+ produces one file. Composing native intent inside `defineTheme` is outside
+ this spec.
+
+- **D4 — Increase Contrast is outside this spec.** Core themes have light and
+ dark modes only, so the generator emits no increased-contrast values. A
+ contrast mode in core is decided on its own, outside `packages/native/`.
+ Until it exists, when Increase Contrast is on, components draw their borders
+ and separators with `color.borderEmphasized` instead of `color.border`
+ (checked by a Swift test that sets `colorSchemeContrast` to increased and
+ reads the border color).
+
+## Current state
+
+- `packages/native/` has generated contract types for Apple platforms
+ (`apple/`) and no Swift theme types or theme generator.
+- The SwiftUI view package (`swift-ios-1/`) is added separately with a
+ generator for core's default theme only, written as string-keyed token
+ dictionaries; this spec describes the generator it grows into.
+- Core's `resolveThemeTokens` returns shared tokens per mode and no local
+ tokens; neutral declares local tokens, stored as `light-dark(…)` strings.
+- Published theme packages: butter, chocolate, gothic, matcha, neutral, stone,
+ y2k (probe is private). Their raw values use `oklch()` and `color-mix()` outside the G5 groups
+ (shadows, component styles), and `color-mix()` inside it only in
+ `--color-syntax-added` and `--color-syntax-removed`.
+
+## Open questions
+
+None.