Skip to content

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

TypeScript
10.0 KB
Raw Blame

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 in packages/core/src/<Name>/. Each view has core's component name in the Astryx module (Button, Text), which re-exports SwiftUI and the generated contracts, so an app file writes import Astryx alone. In a file that also imports SwiftUI, write Astryx.Button and SwiftUI.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; Banner has 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 the astryx template id. 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/native leaves them out of its npm package. A template is built only from Astryx views 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.swift per theme, declaring Theme.<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 as Theme.native) are not wired in.