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.mdindex 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.mdindex 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: anyAstryx 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 sharedtoken is a typed Swift member, so a misspelled token fails to compile insteadof 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 portableentry 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 forevery 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 forlight and one for dark.- `<swiftName>` is the theme's `name` with a leading `astryx-` removed, inlower 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 keywordother than `default`, or repeats another generated theme's name fails therun.- - 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 producebyte-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 secondidentifier 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 chooseswhat to draw. Only code written for that theme reads them; shared components neverdo.@@ -118,7 +123,7 @@ re-implements theme logic.→ `.serif`; `ui-rounded` → `.rounded`. A list with no available family drawsthe system font. The library never bundles or downloads a font; an app thatwants 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 adocumented 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 thepackage'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 filediffers, when a published theme has no file, or when a file has no publishedtheme. 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 theportable theme. When the first component reads `material`, the generatortakes 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 callproduces one file. Composing native intent inside `defineTheme` is outsidethis spec.