An open source design system that's fully customizable and agent ready
Astryx for Apple platforms
Experimental. Canary only. Part of
@astryxdesign/native. APIs change without notice.
One Swift package with two products:
Astryx: SwiftUI views painted with the theme's tokens, the theme environment, and core's localized messages. It is arm A of the AST-082 experiment (pure native: platform views painted with Astryx's tokens).AstryxNative: contract types generated from core's component documentation, the wire a TypeScript logic core sends, and the logic host that runs one (arm C).
Page templates built from the views are a separate package with no products, because templates are clone-only and never published.
Layout
apple/
├── Package.swift # products Astryx and AstryxNative
├── Sources/
│ ├── Astryx/ # SwiftUI views (module Astryx)
│ │ ├── Theme/ # tokens, the theme environment, Dynamic Type
│ │ │ └── Generated/ # typed tokens and every published theme, generated; do not edit
│ │ ├── Resources/ # core's messages per locale, generated; do not edit
│ │ ├── Localization/
│ │ ├── Icon/ # Icon
│ │ ├── Avatar/ # Avatar
│ │ ├── Item/ # Item
│ │ ├── List/ # ListItem
│ │ ├── Text/ # Text
│ │ ├── Heading/ # Heading
│ │ ├── Button/ # Button
│ │ ├── TextInput/ # TextInput
│ │ ├── Thumbnail/ # Thumbnail
│ │ ├── Card/ # Card
│ │ └── Banner/ # Banner
│ └── AstryxNative/ # contracts, wire, logic host (module AstryxNative)
│ └── Generated/ # generated; do not edit
├── Tests/
│ ├── AstryxTests/
│ └── AstryxNativeTests/
└── Templates/ # page templates to copy; its own package, never published
├── Package.swift # no products; compiles and tests the templates
├── Login/ # LoginTemplate, from `astryx template login`
└── Tests/
Each component's Swift spec sits beside its core spec, at
docs/specs/components/<ComponentRoot>/<Name>.swift.spec.md.
Sources/Astryx/<Name>/holds one folder per component, named as inpackages/core/src/<Name>/. Each view has core's component name in theAstryxmodule (Button,Text), which re-exports SwiftUI and the generated contracts, so an app file writesimport Astryxalone. In a file that also imports SwiftUI, writeAstryx.ButtonandSwiftUI.Button. A component's parameters use core's prop names and values (variant: .primary,size: .lg,isLoading), so code reads the same across web and native. Every view with a core contract takes its generated<Name>Props(AST-093 FR5) and has a labeled initializer that builds the same props;Bannerhas no native contract yet (the generated contracts do not include it), so its parameters are hand-written.Templates/holds one folder per page template, named after theastryx templateid. Templates are clone-only, as on the web: you copy a template's folder into your app and own it from then on. They are a separate package with no products, so nothing imports them, and@astryxdesign/nativeleaves them out of its npm package. A template is built only fromAstryxviews and SwiftUI layout, and matches the web template's content and states. Rules a template needs, such as validation, live in a plain value type beside the view so tests can check them without a screen.
Use it
Depend on the Astryx product. To start from a template, copy its folder,
such as Templates/Login/, into your app's sources; it then belongs to your
app.
import Astryx
@main
struct DemoApp: App {
var body: some Scene {
WindowGroup {
LoginTemplate().astryxTheme() // copied from Templates/Login/
}
}
}
astryxTheme(_:) paints a subtree with a theme; without it, components use
core's default theme. Either way they follow Dark Mode and the person's text
size.
On iOS and iPadOS 26 and later, a Button in a navigation bar or toolbar draws
no fill of its own, so the bar's Liquid Glass shows, and astryxFloating() on
a container of controls over scrolling content gives its Buttons the system's
glass. A variant keeps its meaning in glass, and Reduce Transparency or
Increase Contrast draws a solid token fill instead. Elsewhere, and on macOS,
Buttons keep their token look.
Theme tokens
Components read every color, size, and font from the astryx environment
value, never from a constant of their own. astryx.tokens holds the theme's
tokens in the current mode as typed members (tokens.color.textPrimary,
tokens.space.s4, tokens.font.body.size), so a misspelled token fails to
compile. Font tokens come grouped: each type style (tokens.font.body,
tokens.font.heading1) holds its size, weight, and leading, and
tokens.font.family, .size, and .weight hold the scales. Text sizes grow
with Dynamic Type. An app reads the same members for its own SwiftUI layout,
such as stack spacing (astryx.tokens.space.s4).
Icon(.search) draws a shared icon name as the platform's SF Symbol, at
core's icon size and color, hidden from VoiceOver unless it has a label.
IconName holds every built-in name as a static member; a theme maps a name
to another symbol or to an image the app ships, or registers a
<library>:<name> name, with
Theme(…, icons: ["acme:rocket": "airplane", "close": .assetName("brand.close")]).
An asset the app does not ship stops a development build with a message that
names it, and draws nothing in a release build.
Font families come from the theme's font-family-* stacks: the first family
the device has wins, and a system family such as -apple-system or
sans-serif is the system font. Icons use core's shared icon names
(success, warning, …), drawn as an SF Symbol by default; a theme replaces
one with Theme(…, icons: ["success": "checkmark.seal.fill"]).
Sources/Astryx/Theme/Generated/ is written by the Swift theme generator
(../specs/swift/library/theme-generator.md) from core's own resolver, light
and dark:
Tokens.swift: the typed token surface, from core's token names.- One
<Name>Theme.swiftper theme, declaringTheme.<name>: core's defaults (.default) and every published theme package (.butter,.chocolate,.gothic,.matcha,.neutral,.stone,.y2k).
LoginTemplate().astryxTheme(.neutral)
Regenerate after a theme or core token change:
pnpm -F @astryxdesign/native generate:swift-ios
A product generates its own theme the same way, from its theme's module and export:
node packages/native/scripts/swift-ios-theme.mjs --theme ./src/acmeTheme.ts#acmeTheme --out ./Sources/Theme
The generator reads the CSS forms its spec lists
(specs/swift/library/theme-generator.md, G7): hex and named colors, rgb(),
hsl(), hwb(), Lab, LCH, OKLab, OKLCH, color() in the listed spaces,
color-mix(), and relative colors (wide-gamut colors kept as Display P3),
lengths with calc(), and [light, dark] tuples. A value it can only
approximate, such as a color outside Display P3 (clipped, as browsers draw it),
prints a warning after the run; a value with no static form, such as
currentColor or 50%, takes core's default for that token with a warning, or
stops the run when core has none. A form the generator does not read yet stops
the run, saying so. Add --strict to fail on any warning.
A theme's local tokens are not generated yet; the generator names each one it leaves out.
Fonts. A theme's font families are carried as data. Astryx never bundles
a font: a component walks the theme's family list in order and uses the first
family the app has registered; a system family in the list (such as
-apple-system or sans-serif) is the system font, and a list with no
registered family falls back to the system font. To draw a theme's brand face, bundle and register it
in the app. Faces the published themes name (body, heading, code):
| Theme | Faces to bundle |
|---|---|
.default |
none (system fonts) |
.butter |
Outfit, JetBrains Mono |
.chocolate |
Albert Sans, Fraunces, JetBrains Mono |
.gothic |
Fustat, JetBrains Mono |
.matcha |
DM Sans, Playwrite US Trad, JetBrains Mono |
.neutral |
Figtree |
.stone |
Figtree, Montserrat, JetBrains Mono |
.y2k |
Poppins, JetBrains Mono |
The same command writes
Sources/Astryx/Resources/<locale>.lproj/Localizable.strings from core's
locale catalogs, so words the components speak to assistive technology, such
as a loading button's "Loading", follow the person's language. Tests in
@astryxdesign/native fail when either committed output drifts from core.
Working on it
On a Mac with Xcode or the Swift command-line tools:
cd packages/native/apple
swift test # both products
cd Templates && swift test # templates, against the Astryx product
Both packages also declare macOS 14 so they build and test on a Mac without a
simulator; iOS 17 is the target. Open Templates/Package.swift in Xcode to
run LoginTemplate in an iOS simulator through its preview.
To add a component, create Sources/Astryx/<Name>/<Name>.swift declaring
<Name> with core's prop names, writing SwiftUI.<Name> wherever it means the
system type, read its tokens from astryx, and add tests under
Tests/AstryxTests/. To add a template, create
Templates/<Name>/<Name>Template.swift from the output of
astryx template <id>, with tests under Templates/Tests/.
Not here yet
- Pixel and behavior parity with the web components has not been measured.
- Theme-local tokens and platform theme entries
(
defineNativeTheme, reserved asTheme.native) are not wired in.