@astryxdesign/native 0.7.5-canary.0c00688 → 0.7.5-canary.10ca8ea

package/README.md

@@ -12,20 +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.                                                                                                                                        |
-| 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.                                                                                        |
+| 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. React Native and Android
-bindings are not built yet; see [the experiment matrix](#experiment-matrix).
+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"]
@@ -129,6 +132,7 @@ 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
 ```
 

package/apple/Package.swift

@@ -1,18 +1,35 @@
 // 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",
+      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,188 @@
+# 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/
+│   │   ├── Text/          # AstryxText
+│   │   ├── Heading/       # AstryxHeading
+│   │   ├── Button/        # AstryxButton
+│   │   ├── TextInput/     # AstryxTextInput
+│   │   ├── Card/          # AstryxCard
+│   │   └── Banner/        # AstryxBanner
+│   └── 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>/`. 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:
+  - `AstryxButton` takes `action` where core has `onClick`.
+  - `AstryxButton` takes `fillsWidth` where core has `width="100%"`.
+  - `AstryxButton` takes `icon` as a shared icon name (`"search"`), which the
+    generated `ButtonProps` does not carry yet.
+  - `AstryxTextInput` takes a `Binding` where core has `value` and `onChange`.
+  - `AstryxHeading`'s `level` is optional where core requires it.
+  - `AstryxCard` 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
+import SwiftUI
+
+@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.
+
+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>/Astryx<Name>.swift` with
+core's prop names, 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/AstryxBanner.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 AstryxBanner: 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)) {
+        AstryxText(title, weight: .semibold)
+        if let description {
+          AstryxText(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(Text(accessibilityText))
+  }
+
+  /// What VoiceOver reads: the title, then the description.
+  var accessibilityText: String {
+    description.map { "\(title), \($0)" } ?? title
+  }
+}

package/apple/Sources/Astryx/Button/AstryxButton.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 AstryxButton: 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 {
+    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)
+        }
+        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(Text(accessibilityText))
+    .accessibilityAddTraits(Self.accessibilityTraits)
+    .accessibilityValue(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())
+  }
+}

package/apple/Sources/Astryx/Card/AstryxCard.swift

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import SwiftUI
+
+/// A card: one independent item on the theme's card ground, with a hairline
+/// border and the container radius.
+public struct AstryxCard<Content: View>: View {
+  let padding: Int
+  let content: Content
+  @Environment(\.astryx) private var astryx
+
+  /// - Parameter padding: a step on the spacing ladder, as core's `padding`.
+  public init(padding: Int = 4, @ViewBuilder content: () -> Content) {
+    self.padding = padding
+    self.content = content()
+  }
+
+  public var body: some View {
+    let shape = RoundedRectangle(
+      cornerRadius: astryx.size("radius-container", 12),
+      style: .continuous
+    )
+    // Several child views stack in one card, top to bottom with no gap of
+    // their own, as children flow inside core's Card.
+    VStack(alignment: .leading, spacing: 0) { content }
+      .padding(astryx.space(padding))
+      .frame(maxWidth: .infinity, alignment: .leading)
+      .background(shape.fill(astryx.color("color-background-card")))
+      .overlay(
+        shape.strokeBorder(astryx.color("color-border"), lineWidth: astryx.size("border-width", 1))
+      )
+  }
+}

package/apple/Sources/Astryx/Heading/AstryxHeading.swift

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// Adapted from github.com/ejc3/astryx-swift (MIT).
+
+import SwiftUI
+
+/// A heading at levels 1 through 6, painted with the theme's heading tokens
+/// and exposed to VoiceOver as a heading.
+public struct AstryxHeading: View {
+  let content: String
+  let level: Int
+  @Environment(\.astryx) private var astryx
+
+  public init(_ content: String, level: Int = 2) {
+    self.content = content
+    self.level = min(max(level, 1), 6)
+  }
+
+  public var body: some View {
+    Text(content)
+      .font(
+        astryx.font(
+          size: "text-heading-\(level)-size",
+          20,
+          weight: "text-heading-\(level)-weight",
+          family: "font-family-heading"
+        )
+      )
+      .foregroundStyle(astryx.color("color-text-primary"))
+      .accessibilityAddTraits(Self.accessibilityTraits)
+      .accessibilityHeading(headingLevel)
+  }
+
+  /// The traits assistive technology gets: a header.
+  static var accessibilityTraits: AccessibilityTraits { .isHeader }
+
+  var headingLevel: AccessibilityHeadingLevel {
+    switch level {
+    case 1: .h1
+    case 2: .h2
+    case 3: .h3
+    case 4: .h4
+    case 5: .h5
+    default: .h6
+    }
+  }
+}

package/apple/Sources/Astryx/Localization/AstryxStrings.swift

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import Foundation
+
+/// Core's catalog messages, read from `Resources/<locale>.lproj`, which
+/// `generate:swift-ios` writes from core's locale catalogs.
+enum AstryxStrings {
+  /// What a loading button says to assistive technology.
+  static var buttonLoading: String { localized("@astryx.button.loading", "Loading") }
+
+  static func localized(_ key: String, _ english: String) -> String {
+    resourceBundle.localizedString(forKey: key, value: english, table: nil)
+  }
+
+  static var resourceBundle: Bundle {
+    #if SWIFT_PACKAGE
+    Bundle.module
+    #else
+    Bundle.main
+    #endif
+  }
+}

package/apple/Sources/Astryx/Resources/af.lproj/Localizable.strings

@@ -0,0 +1,4 @@
+/* Generated by @astryxdesign/native from core's locale catalogs. Do not edit. */
+
+/* Screen-reader-only live-region announcement while a Button is in its loading state (spinner shown, action in flight). Progressive sense ("work in progress"), not a noun. Kept separate from `typeahead.loading` — translations may diverge. */
+"@astryx.button.loading" = "Laai tans";

package/apple/Sources/Astryx/Resources/ar.lproj/Localizable.strings

@@ -0,0 +1,4 @@
+/* Generated by @astryxdesign/native from core's locale catalogs. Do not edit. */
+
+/* Screen-reader-only live-region announcement while a Button is in its loading state (spinner shown, action in flight). Progressive sense ("work in progress"), not a noun. Kept separate from `typeahead.loading` — translations may diverge. */
+"@astryx.button.loading" = "جارٍ التحميل";

package/apple/Sources/Astryx/Resources/ca.lproj/Localizable.strings

@@ -0,0 +1,4 @@
+/* Generated by @astryxdesign/native from core's locale catalogs. Do not edit. */
+
+/* Screen-reader-only live-region announcement while a Button is in its loading state (spinner shown, action in flight). Progressive sense ("work in progress"), not a noun. Kept separate from `typeahead.loading` — translations may diverge. */
+"@astryx.button.loading" = "S’està carregant";

package/apple/Sources/Astryx/Resources/cs.lproj/Localizable.strings

@@ -0,0 +1,4 @@
+/* Generated by @astryxdesign/native from core's locale catalogs. Do not edit. */
+
+/* Screen-reader-only live-region announcement while a Button is in its loading state (spinner shown, action in flight). Progressive sense ("work in progress"), not a noun. Kept separate from `typeahead.loading` — translations may diverge. */
+"@astryx.button.loading" = "Načítání";

package/apple/Sources/Astryx/Resources/da.lproj/Localizable.strings

@@ -0,0 +1,4 @@
+/* Generated by @astryxdesign/native from core's locale catalogs. Do not edit. */
+
+/* Screen-reader-only live-region announcement while a Button is in its loading state (spinner shown, action in flight). Progressive sense ("work in progress"), not a noun. Kept separate from `typeahead.loading` — translations may diverge. */
+"@astryx.button.loading" = "Indlæser";

package/apple/Sources/Astryx/Resources/de.lproj/Localizable.strings

@@ -0,0 +1,4 @@
+/* Generated by @astryxdesign/native from core's locale catalogs. Do not edit. */
+
+/* Screen-reader-only live-region announcement while a Button is in its loading state (spinner shown, action in flight). Progressive sense ("work in progress"), not a noun. Kept separate from `typeahead.loading` — translations may diverge. */
+"@astryx.button.loading" = "Wird geladen";