@astryxdesign/native 0.7.5-canary.f2dafed → 0.7.5-canary.f943c2b

package/README.md

@@ -12,16 +12,23 @@ rests on evidence.
 
 ## What is here today
 
-| Part           | Path                              | What it does                                                                                                                                                                                                                                 |
-| -------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Contracts      | `src/contract/`                   | Reads a core component's documentation and splits its props into a portable **core contract** and a **web-only** part, with a reason for each web-only prop. Checks prop names against Swift and Kotlin keywords and platform toolkit names. |
-| Platform types | `@astryxdesign/native/components` | TypeScript props per platform, chosen by type-resolution condition: `ios`, `android`, `macos`, `windows`, or `shared` for the core contract only.                                                                                            |
-| Swift binding  | `apple/`                          | A Swift package with props generated from the same contracts. iOS and macOS props sit behind `#if os(...)`.                                                                                                                                  |
-| Native theme   | `defineNativeTheme`               | Durable theme intent (`material: 'opaque' \| 'translucent'`) plus platform entries scoped by OS version, such as Liquid Glass from iOS 26. Never sets tokens.                                                                                |
-| Icons          | `NATIVE_ICON_DEFAULTS`            | Astryx's built-in icon names mapped to SF Symbols on Apple platforms and Material Symbols on Android.                                                                                                                                        |
-
-Only `Selector` has native additions so far. React Native and Android bindings
-are not built yet; see [the experiment matrix](#experiment-matrix).
+| Part           | Path                              | What it does                                                                                                                                                                                                                                                                                                 |
+| -------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Contracts      | `src/contract/`                   | Reads a core component's documentation and splits its props into a portable **core contract** and a **web-only** part, with a reason for each web-only prop. Checks prop names against Swift and Kotlin keywords and platform toolkit names.                                                                 |
+| Platform types | `@astryxdesign/native/components` | TypeScript props per platform, chosen by type-resolution condition: `ios`, `android`, `macos`, `windows`, or `shared` for the core contract only.                                                                                                                                                            |
+| Swift binding  | `apple/`                          | A Swift package with two products: `AstryxNative`, props generated from the same contracts (iOS and macOS props sit behind `#if os(...)`) plus the logic host, and `Astryx`, SwiftUI views drawn with core's tokens. Clone-only page templates sit in `apple/Templates/`. See [its README](apple/README.md). |
+| Native theme   | `defineNativeTheme`               | Durable theme intent (`material: 'opaque' \| 'translucent'`) plus platform entries scoped by OS version, such as Liquid Glass from iOS 26. Never sets tokens.                                                                                                                                                |
+| Icons          | `NATIVE_ICON_DEFAULTS`            | Astryx's built-in icon names mapped to SF Symbols on Apple platforms and Material Symbols on Android.                                                                                                                                                                                                        |
+| Wire           | `AstryxNode`, `AstryxAction`      | Each component as JSON a TypeScript core sends a native host (arm C), and the action a host sends back when a view calls a callback. Swift decodes `<Name>Node` and turns it into `<Name>Props` with `viewProps(send:)`.                                                                                     |
+| Logic core     | `@astryxdesign/native/logic`      | `createLogicCore` holds a screen's state, builds its node tree, and reduces actions; `connectBridge` carries it to a native host as JSON. ECMAScript built-ins only, so it runs in Hermes. Shaped after EJ Campbell's astryx-swift spike.                                                                    |
+| Logic host     | `AstryxLogicHost` (Swift)         | Runs a logic core bundle in JavaScriptCore, decodes each tree into `AstryxNode`, and sends views' actions back. A Hermes host speaks the same bridge.                                                                                                                                                        |
+
+Contracts cover Badge, Button, Card, Divider, Heading, HStack, ProgressBar,
+Selector, Switch, Text, TextInput, and VStack. The `Astryx` Swift product draws
+Text, Heading, Button, TextInput, Card, and Banner, and `apple/Templates/` the
+`login` template, in SwiftUI.
+React Native and Android bindings are not built yet; see
+[the experiment matrix](#experiment-matrix).
 
 ```ts
 // tsconfig.json for an iOS app: "customConditions": ["ios"]
@@ -34,22 +41,131 @@ const props: SelectorProps = {
 };
 ```
 
+How core documentation becomes a contract:
+
+- A callback whose arguments are values followed by the DOM event that caused
+  them, such as `(checked: boolean, e: ChangeEvent) => void`, keeps the values
+  in the core; the event stays on the web.
+- A callback that carries only an event stays on the web, unless the component
+  names it in `callbacks`, as Button does for `onClick`. Its core form takes no
+  arguments. A callback with an event before a value stays on the web either
+  way.
+- Free-form content becomes a typed slot only where a component declares one
+  in `slots`; `text` is a string, as for a badge's label or a heading's words,
+  and `content` is child Astryx components, as for a stack's or a card's
+  children. A SwiftUI view takes content as a view builder, so `<Name>Props`
+  leaves it out; `<Name>Node` carries it as child nodes.
+- A closed set of numbers, such as a heading level, is a Swift enum with raw
+  values.
+- A core prop may share a platform toolkit's name only when the component
+  declares in `sameMeaning` that it means the same thing there.
+
+### The wire (arm C)
+
+A TypeScript core sends a tree of nodes and receives actions. A node lists the
+callbacks the core listens to in `events`; a view gets only those callbacks.
+
+```ts
+// tsconfig: "customConditions": ["ios"]
+import type {AstryxAction, AstryxNode} from '@astryxdesign/native/components';
+
+const screen: AstryxNode = {
+  component: 'VStack',
+  key: 'root',
+  props: {
+    gap: 2,
+    children: [
+      {
+        component: 'Switch',
+        key: 'wifi',
+        props: {label: 'Wi-Fi', value: true},
+        events: ['onChange'],
+      },
+    ],
+  },
+};
+// What the host sends back when the switch is turned off:
+const action: AstryxAction = {
+  key: 'wifi',
+  component: 'Switch',
+  event: 'onChange',
+  args: [false],
+};
+```
+
+```swift
+let host = AstryxLogicHost(bundle: bundleSource) // calls the bundle's global astryxStart(host)
+if case .switch(let wifi) = host.root {
+  let props = wifi.viewProps(send: host.send)
+}
+```
+
+```ts
+// tsconfig: "customConditions": ["ios"]
+import type {AstryxAction, AstryxNode} from '@astryxdesign/native/components';
+import {connectBridge, createLogicCore} from '@astryxdesign/native/logic';
+import type {Bridge, BridgeHost} from '@astryxdesign/native/logic';
+
+const core = createLogicCore<{wifi: boolean}, AstryxNode, AstryxAction>({
+  initial: {wifi: true},
+  view: state => ({
+    component: 'Switch',
+    key: 'wifi',
+    props: {label: 'Wi-Fi', value: state.wifi},
+    events: ['onChange'],
+  }),
+  reduce: (state, action) =>
+    action.component === 'Switch' && action.event === 'onChange'
+      ? {wifi: action.args[0]}
+      : state,
+});
+// The bundle's entry: the native host calls it with its two calls in and
+// gets back the bridge it reads snapshots from and dispatches actions to.
+(globalThis as {astryxStart?: (host: BridgeHost) => Bridge}).astryxStart =
+  host => connectBridge(core, host);
+```
+
 ## Working on it
 
 ```sh
+pnpm -F @astryxdesign/native typecheck        # source and tests
 pnpm -F @astryxdesign/native build            # dist/, including platform types
+pnpm -F @astryxdesign/native typecheck:types  # every platform's types, after build
 pnpm -F @astryxdesign/native generate:apple   # regenerate apple/Sources/.../Generated
+pnpm -F @astryxdesign/native generate:swift-ios # regenerate the Astryx product's typed tokens, every published theme, and strings
 pnpm vitest run --project node packages/native
 ```
 
 Generated Swift is committed so a Swift package can pin a commit. A test fails
 when it drifts from the contracts.
 
+**Cleanup needed.** Committing the generated Swift
+(`apple/Sources/AstryxNative/Generated`) is temporary. It is there only because
+Swift Package Manager installs a package from a git commit and cannot run the
+Node generator. The intended replacement: CI generates the Swift files and
+publishes them to a Swift-only branch or tag that apps pin, and the generated
+files are ignored on `main`.
+
 Boundaries, checked by `pnpm check:package-boundaries`:
 
 - `@astryxdesign/core` never imports this package.
-- This package's source never imports core. It reads core's documentation
-  files as data at build time.
+- No file in this package, in any folder, imports core, apart from the
+  build-time reads AST-082 FR16 lists until core's portable entry ships: the
+  theme generator in `scripts/` may import `@astryxdesign/core/theme` and
+  `@astryxdesign/core/theme/tokens`; `scripts/swift-ios-strings.mjs` may
+  read core's locale catalogs (`@astryxdesign/core/locales/*.json`); and
+  `scripts/core-docs.mjs` reads core's component documentation and built-in
+  icon names as data.
+- The check reads source text in every folder except `node_modules`, `dist`,
+  `.build`, and `.swiftpm`. It flags any other module specifier that names
+  core (`import`, `require`, `require.resolve`, `import.meta.resolve`, or a
+  relative path into `packages/core`). It also flags a path to core's package,
+  written as adjacent string segments (`'@astryxdesign', 'core'`,
+  `'node_modules', '@astryxdesign/core'`, `'packages', 'core'`) or inside one
+  string (`node_modules/@astryxdesign/core`, `packages/core`). In
+  `scripts/core-docs.mjs` it allows exactly one such path, the `CORE_ROOT`
+  definition, and only the listed reads under `CORE_ROOT`. It does not follow
+  paths computed in other ways.
 
 ## Experiment matrix
 

package/apple/Package.swift

@@ -1,18 +1,37 @@
 // swift-tools-version: 6.0
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-// Experimental Astryx for Apple platforms (AST-082). The contract types under
-// Sources/AstryxNative/Generated are generated by `pnpm generate:apple`; do not
-// edit them by hand.
+// Experimental Astryx for Apple platforms (AST-082). Two products:
+// - `Astryx`: SwiftUI views painted with the theme's tokens, the theme
+//   environment, and core's localized messages (Sources/Astryx).
+// - `AstryxNative`: the contract types generated by `pnpm generate:apple`
+//   (Sources/AstryxNative/Generated; do not edit them by hand) and the logic
+//   host.
+// Page templates are a separate package in Templates/, with no products,
+// because they are clone-only source and are never published.
 
 import PackageDescription
 
 let package = Package(
   name: "AstryxNative",
+  defaultLocalization: "en",
   platforms: [.iOS(.v17), .macOS(.v14)],
-  products: [.library(name: "AstryxNative", targets: ["AstryxNative"])],
+  products: [
+    .library(name: "Astryx", targets: ["Astryx"]),
+    .library(name: "AstryxNative", targets: ["AstryxNative"]),
+  ],
   targets: [
     .target(name: "AstryxNative", path: "Sources/AstryxNative"),
+    // Resources holds core's catalog messages per locale, generated.
+    .target(
+      name: "Astryx",
+      dependencies: ["AstryxNative"],
+      path: "Sources/Astryx",
+      // Each component's spec lives beside its view (AST-093 FR1).
+      exclude: ["Icon/Icon.spec.md"],
+      resources: [.process("Resources")]
+    ),
     .testTarget(name: "AstryxNativeTests", dependencies: ["AstryxNative"], path: "Tests/AstryxNativeTests"),
+    .testTarget(name: "AstryxTests", dependencies: ["Astryx"], path: "Tests/AstryxTests"),
   ]
 )

package/apple/README.md

@@ -0,0 +1,199 @@
+# 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
+
+```text
+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, Icon.spec.md
+│   │   ├── Text/          # Text
+│   │   ├── Heading/       # Heading
+│   │   ├── Button/        # Button
+│   │   ├── TextInput/     # TextInput
+│   │   ├── 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/
+```
+
+- **`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, with six exceptions, the interim shape
+  AST-093 FR5 exempts until the components move onto the generated contracts:
+  - `Button` takes `action` where core has `onClick`.
+  - `Button` takes `fillsWidth` where core has `width="100%"`.
+  - `Button` takes `icon` as a shared icon name (`"search"`), which the
+    generated `ButtonProps` does not carry yet.
+  - `TextInput` takes a `Binding` where core has `value` and `onChange`.
+  - `Heading`'s `level` is optional where core requires it.
+  - `Card` takes `padding` as a whole spacing step, so it cannot spell
+    core's `0.5` and `1.5` steps.
+- **`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.
+
+```swift
+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.
+
+## 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.bodySize`), so a misspelled token fails to
+compile. Text sizes grow with Dynamic Type. The components still read some
+tokens by core's name (`astryx.color("color-accent")`); moving them onto the
+typed members comes next.
+
+`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 registers a `<library>:<name>` name, with
+`Theme(…, icons: ["acme:rocket": "airplane"])`.
+
+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`).
+
+```swift
+LoginTemplate().astryxTheme(.neutral)
+```
+
+Regenerate after a theme or core token change:
+
+```sh
+pnpm -F @astryxdesign/native generate:swift-ios
+```
+
+A product generates its own theme the same way, from its theme's module and
+export:
+
+```sh
+node packages/native/scripts/swift-ios-theme.mjs --theme ./src/acmeTheme.ts#acmeTheme --out ./Sources/Theme
+```
+
+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:
+
+```sh
+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
+
+- The views do not use the generated contract types in `AstryxNative` yet.
+  Moving them onto those types is how a core prop change reaches Swift.
+- Pixel and behavior parity with the web components has not been measured.
+- Increase Contrast, theme-local tokens, and platform theme entries
+  (`defineNativeTheme`, reserved as `Theme.native`) are not wired in.

package/apple/Sources/Astryx/Banner/Banner.swift

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import SwiftUI
+
+/// Core's `Banner` statuses.
+public enum AstryxBannerStatus: String, CaseIterable, Sendable {
+  case info
+  case warning
+  case error
+  case success
+
+  /// The shared icon name for this status (AST-082 FR17), drawn as the
+  /// theme's or the platform's symbol for it.
+  var iconName: String { rawValue }
+
+  var groundToken: String {
+    switch self {
+    case .info: "color-accent-muted"
+    case .warning: "color-warning-muted"
+    case .error: "color-error-muted"
+    case .success: "color-success-muted"
+    }
+  }
+
+  var iconToken: String {
+    switch self {
+    case .info: "color-accent"
+    case .warning: "color-warning"
+    case .error: "color-error"
+    case .success: "color-success"
+    }
+  }
+}
+
+/// A message about the page or a section of it. The status sets the color
+/// and icon only; the title must say what happened, because the icon is
+/// decorative to VoiceOver.
+public struct Banner: View {
+  let status: AstryxBannerStatus
+  let title: String
+  let description: String?
+  @Environment(\.astryx) private var astryx
+
+  public init(status: AstryxBannerStatus, title: String, description: String? = nil) {
+    self.status = status
+    self.title = title
+    self.description = description
+  }
+
+  public var body: some View {
+    HStack(alignment: .firstTextBaseline, spacing: astryx.space(2)) {
+      if let symbol = astryx.icon(status.iconName) {
+        // Sized with the title so it grows with Dynamic Type.
+        Image(systemName: symbol)
+          .font(astryx.font(size: "text-body-size", 14, weight: "text-body-weight"))
+          .foregroundStyle(astryx.color(status.iconToken))
+          .accessibilityHidden(true)
+      }
+      VStack(alignment: .leading, spacing: astryx.space(1)) {
+        Text(title, weight: .semibold)
+        if let description {
+          Text(description, color: .secondary)
+        }
+      }
+      .frame(maxWidth: .infinity, alignment: .leading)
+    }
+    .padding(astryx.space(3))
+    .background(
+      RoundedRectangle(cornerRadius: astryx.size("radius-container", 12), style: .continuous)
+        .fill(astryx.color(status.groundToken))
+    )
+    .accessibilityElement(children: .ignore)
+    .accessibilityLabel(SwiftUI.Text(accessibilityText))
+  }
+
+  /// What VoiceOver reads: the title, then the description.
+  var accessibilityText: String {
+    description.map { "\(title), \($0)" } ?? title
+  }
+}

package/apple/Sources/Astryx/Button/Button.swift

@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// Adapted from github.com/ejc3/astryx-swift (MIT).
+
+import SwiftUI
+
+/// Core's `Button` variants.
+public enum AstryxButtonVariant: String, CaseIterable, Sendable {
+  case primary
+  case secondary
+  case ghost
+  case destructive
+}
+
+/// Core's `Button` sizes: `size-element-sm`, `-md`, and `-lg` high.
+public enum AstryxButtonSize: String, CaseIterable, Sendable {
+  case sm
+  case md
+  case lg
+
+  var heightToken: String { "size-element-\(rawValue)" }
+  var fallbackHeight: CGFloat {
+    switch self {
+    case .sm: 28
+    case .md: 32
+    case .lg: 36
+    }
+  }
+}
+
+/// A labeled action, painted with the theme's tokens. The tap area reaches
+/// the platform's 44-by-44-point minimum even when the drawn button is smaller.
+public struct Button: View {
+  let label: String
+  let variant: AstryxButtonVariant
+  let size: AstryxButtonSize
+  let icon: String?
+  let isLoading: Bool
+  let isDisabled: Bool
+  let fillsWidth: Bool
+  let action: () -> Void
+  @Environment(\.astryx) private var astryx
+
+  /// - Parameters:
+  ///   - icon: a shared icon name, such as `"search"`, shown before the
+  ///     label; the theme's symbol for it, else the platform default.
+  ///   - fillsWidth: the button takes the whole width it is offered, as
+  ///     core's `width="100%"` does.
+  public init(
+    label: String,
+    variant: AstryxButtonVariant = .secondary,
+    size: AstryxButtonSize = .md,
+    icon: String? = nil,
+    isLoading: Bool = false,
+    isDisabled: Bool = false,
+    fillsWidth: Bool = false,
+    action: @escaping () -> Void
+  ) {
+    self.label = label
+    self.variant = variant
+    self.size = size
+    self.icon = icon
+    self.isLoading = isLoading
+    self.isDisabled = isDisabled
+    self.fillsWidth = fillsWidth
+    self.action = action
+  }
+
+  public var body: some View {
+    SwiftUI.Button(action: activate) {
+      // The label keeps its place while loading so the width holds; the
+      // spinner draws over it.
+      HStack(spacing: astryx.space(2)) {
+        if let icon, let symbol = astryx.icon(icon) {
+          Image(systemName: symbol)
+        }
+        SwiftUI.Text(label).lineLimit(1)
+      }
+      .opacity(isLoading ? 0 : 1)
+      .overlay {
+        if isLoading {
+          ProgressView().controlSize(.small).tint(foreground)
+        }
+      }
+    }
+    .buttonStyle(
+      AstryxButtonStyle(
+        astryx: astryx,
+        size: size,
+        fillsWidth: fillsWidth,
+        foreground: foreground,
+        background: background
+      )
+    )
+    // As core's Button: a loading button stays undimmed and focusable, keeps
+    // its label, and says Loading; taps do nothing until it finishes.
+    .disabled(isDisabled)
+    .accessibilityLabel(SwiftUI.Text(accessibilityText))
+    .accessibilityAddTraits(Self.accessibilityTraits)
+    .accessibilityValue(SwiftUI.Text(loadingValue ?? ""))
+    .onChange(of: isLoading) { _, loading in
+      if loading { AccessibilityNotification.Announcement(AstryxStrings.buttonLoading).post() }
+    }
+  }
+
+  /// The button's accessible name: its label, also while loading.
+  var accessibilityText: String { label }
+
+  /// The traits assistive technology gets: a button.
+  static var accessibilityTraits: AccessibilityTraits { .isButton }
+
+  /// What assistive technology reads after the label while loading: core's
+  /// catalog message, in the person's language.
+  var loadingValue: String? { isLoading ? AstryxStrings.buttonLoading : nil }
+
+  /// Runs the action unless the button is loading.
+  func activate() {
+    guard !isLoading else { return }
+    action()
+  }
+
+  private var foreground: Color {
+    switch variant {
+    case .primary: astryx.color("color-on-accent")
+    case .destructive: astryx.color("color-on-error")
+    case .secondary, .ghost: astryx.color("color-text-primary")
+    }
+  }
+
+  private var background: Color {
+    switch variant {
+    case .primary: astryx.color("color-accent")
+    case .destructive: astryx.color("color-error")
+    case .secondary: astryx.color("color-neutral")
+    case .ghost: .clear
+    }
+  }
+}
+
+struct AstryxButtonStyle: ButtonStyle {
+  let astryx: AstryxStyle
+  let size: AstryxButtonSize
+  let fillsWidth: Bool
+  let foreground: Color
+  let background: Color
+  @Environment(\.isEnabled) private var isEnabled
+
+  func makeBody(configuration: Configuration) -> some View {
+    let shape = RoundedRectangle(
+      cornerRadius: astryx.size("radius-element", 8),
+      style: .continuous
+    )
+    // Grows with text size, but not so far that one line of a large label
+    // becomes a tall slab.
+    let height = astryx.size(size.heightToken, size.fallbackHeight) * min(astryx.textScale, 1.4)
+    configuration.label
+      .font(astryx.font(size: "text-label-size", 14, weight: "text-label-weight"))
+      .foregroundStyle(foreground)
+      .padding(.horizontal, astryx.space(3))
+      .frame(maxWidth: fillsWidth ? .infinity : nil, minHeight: height)
+      .background(shape.fill(background))
+      .opacity(isEnabled ? (configuration.isPressed ? 0.75 : 1) : 0.5)
+      // Drawn at the token size; laid out at least 44 by 44 so the whole
+      // platform-minimum tap area counts.
+      .frame(minWidth: 44, minHeight: 44)
+      .contentShape(Rectangle())
+  }
+}