Skip to content

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

TypeScript

spec(native): Swift theme headers carry no version; theme types use unprefixed names (#8038)

Cindy Zhang10cba067d3e1
diff --git a/packages/native/specs/swift/library/README.md b/packages/native/specs/swift/library/README.md
index df7ca418e1..0fdf608b35 100644
--- a/packages/native/specs/swift/library/README.md
+++ b/packages/native/specs/swift/library/README.md
@@ -14,4 +14,4 @@ wins.
| `accessibility.md` | How core's accessibility semantics reach VoiceOver and Apple's accessibility settings |
| `component-api.md` | How a SwiftUI view is named and takes its generated contract |
| `slots.md` | How each slot kind (text, icon, content) appears in SwiftUI |
-| `theme-generator.md` | How any Astryx theme becomes a Swift `AstryxTheme` |
+| `theme-generator.md` | How any Astryx theme becomes a Swift `Theme` |
diff --git a/packages/native/specs/swift/library/theme-generator.md b/packages/native/specs/swift/library/theme-generator.md
index 7831599553..8d8608a3b8 100644
--- a/packages/native/specs/swift/library/theme-generator.md
+++ b/packages/native/specs/swift/library/theme-generator.md
@@ -8,7 +8,7 @@
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)`
+product itself, becomes a Swift `Theme` 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
@@ -35,13 +35,16 @@ re-implements theme logic.
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`,
+ - `swift-ios-1/core/Theme/Generated/Tokens.swift` declares the typed
+ token surface: `Tokens` 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.
+ - Type names follow the Swift component API spec: unprefixed, in the
+ `Astryx` module, so `Astryx.Theme.neutral` and `Theme.neutral` name the
+ same value.
- Each theme becomes `swift-ios-1/core/Theme/Generated/<SwiftName>Theme.swift`,
- which declares `AstryxTheme.<swiftName>` with an `AstryxTokens` value for
+ which declares `Theme.<swiftName>` with a `Tokens` 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
@@ -49,8 +52,10 @@ re-implements theme logic.
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.
+ - Each file starts with a header naming the source package and the theme
+ name, says "Do not edit", and names the regenerate command. The header
+ never names a version, so a release that only bumps versions changes no
+ generated file.
- **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.
@@ -99,7 +104,7 @@ re-implements theme logic.
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"]`).
+ (`Theme.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.
@@ -118,7 +123,7 @@ re-implements theme logic.
→ `.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
+- **G11 — Native intent has a reserved slot.** `Theme.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
@@ -126,7 +131,7 @@ re-implements theme logic.
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
+ `Tokens.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
@@ -140,15 +145,15 @@ re-implements theme logic.
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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. |
+| G3 | `swiftc -typecheck` compiles `Tokens.swift` and every theme file together; each theme file declares one `Theme` 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. |
+| G5 | Every theme's light and dark values fill every member of `Tokens`, 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`. |
+| 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 `Tokens`. |
| 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. |
+| G11 | `Theme.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. |
@@ -174,7 +179,7 @@ re-implements theme logic.
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
+ `Theme.native` already resolved per OS version range, so one call
produces one file. Composing native intent inside `defineTheme` is outside
this spec.