@astryxdesign/native 0.7.5-canary.cd53c2d → 0.7.5-canary.d695efb

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,41 @@
 // 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",
+      // A tiny image that stands in for an app-shipped icon asset.
+      resources: [.process("Resources")]
+    ),
   ]
 )

package/apple/README.md

@@ -0,0 +1,203 @@
+# 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. `Text`, `Heading`, and `Card` take the
+  generated `TextProps`, `HeadingProps`, and `CardProps`, as AST-093 FR5 asks;
+  the others keep four exceptions, the interim shape FR5 exempts until they 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`.
+- **`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.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. 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 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`).
+
+```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 icon = astryx.icon(status.iconName) {
+        // Sized with the title so it grows with Dynamic Type.
+        icon.sized(astryx.fontSize("text-body-size", 14))
+          .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/Base/BaseProps.swift

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+extension View {
+  /// Core's base props on a view: `id` names it for UI tests, and `isHidden`
+  /// removes it from layout and from assistive technology, as core's `hidden`
+  /// attribute does.
+  @ViewBuilder func astryxBase(_ base: AstryxBaseProps) -> some View {
+    if base.isHidden == true {
+      EmptyView()
+    } else if let id = base.id {
+      accessibilityIdentifier(id)
+    } else {
+      self
+    }
+  }
+}

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

@@ -0,0 +1,168 @@
+// 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 image = astryx.icon(icon) {
+          // An asset matches the label's text size, as a symbol does.
+          image.sized(astryx.fontSize("text-label-size", 14))
+        }
+        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())
+  }
+}

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

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/// A card: one independent item on the theme's card ground. It takes core's
+/// Card props (`CardProps`) and stacks its content top to bottom, as children
+/// flow inside core's Card.
+public struct Card<Content: View>: View {
+  public let props: CardProps
+  let content: Content
+  @Environment(\.astryx) private var astryx
+
+  /// - Parameters:
+  ///   - padding: core's `padding`, a step on the spacing scale; step 4 when
+  ///     nil.
+  ///   - variant: core's `variant`: the card ground, or `transparent` for none.
+  ///     Only `default` draws a border.
+  ///   - elevation: core's `elevation`, the theme's shadow at that depth.
+  ///   - base: core's base props.
+  ///   - content: core's `children`.
+  public init(
+    padding: CardPadding? = nil,
+    variant: CardVariant? = nil,
+    elevation: CardElevation? = nil,
+    base: AstryxBaseProps = AstryxBaseProps(),
+    @ViewBuilder content: () -> Content
+  ) {
+    self.props = CardProps(padding: padding, variant: variant, elevation: elevation, base: base)
+    self.content = content()
+  }
+
+  public var body: some View {
+    let shape = RoundedRectangle(cornerRadius: astryx.tokens.radius.container, style: .continuous)
+    let variant = props.variant ?? .default
+    // The border sits inside the padding, so the content's inset is the
+    // padding step, as in core.
+    SwiftUI.VStack(alignment: .leading, spacing: 0) { content }
+      .padding(padding)
+      .frame(maxWidth: .infinity, alignment: .leading)
+      .background(shape.fill(Self.ground(variant, astryx.tokens.color)))
+      .overlay {
+        if variant == .default {
+          shape.strokeBorder(astryx.tokens.color.border, lineWidth: astryx.tokens.size.borderWidth)
+        }
+      }
+      .astryxShadow(Self.shadow(props.elevation ?? .none, astryx.tokens.shadow), in: shape)
+      .astryxBase(props.base)
+  }
+
+  var padding: CGFloat {
+    let space = astryx.tokens.space
+    switch props.padding ?? .v4 {
+    case .v0: return space.s0
+    case .v0_5: return space.s0_5
+    case .v1: return space.s1
+    case .v1_5: return space.s1_5
+    case .v2: return space.s2
+    case .v3: return space.s3
+    case .v4: return space.s4
+    case .v5: return space.s5
+    case .v6: return space.s6
+    case .v8: return space.s8
+    case .v10: return space.s10
+    }
+  }
+
+  /// The ground core's Card draws for a variant.
+  static func ground(_ variant: CardVariant, _ color: ColorTokens) -> Color {
+    switch variant {
+    case .default: color.backgroundCard
+    case .transparent: .clear
+    case .muted: color.backgroundMuted
+    case .blue: color.backgroundBlue
+    case .cyan: color.backgroundCyan
+    case .gray: color.backgroundGray
+    case .green: color.backgroundGreen
+    case .orange: color.backgroundOrange
+    case .pink: color.backgroundPink
+    case .purple: color.backgroundPurple
+    case .red: color.backgroundRed
+    case .teal: color.backgroundTeal
+    case .yellow: color.backgroundYellow
+    }
+  }
+
+  /// The theme's shadow at an elevation.
+  static func shadow(_ elevation: CardElevation, _ shadow: ShadowTokens) -> [ShadowLayer] {
+    switch elevation {
+    case .none: []
+    case .low: shadow.low
+    case .med: shadow.med
+    case .high: shadow.high
+    }
+  }
+}
+
+extension Card where Content == AstryxNodeList {
+  /// A card from core's props, with its children as the wire tree a logic
+  /// core sends; `send` carries the children's callbacks back to the core.
+  public init(
+    _ props: CardProps,
+    children: [AstryxNode],
+    send: @escaping @Sendable (AstryxAction) -> Void
+  ) {
+    self.props = props
+    self.content = AstryxNodeList(nodes: children, send: send)
+  }
+}