@astryxdesign/native 0.7.5-canary.10ca8ea → 0.7.5-canary.116f54b

package/apple/Package.swift

@@ -27,9 +27,15 @@ let package = Package(
       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"),
+    .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

@@ -26,12 +26,13 @@ apple/
 │   │   │   └── 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
+│   │   ├── 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/
@@ -44,17 +45,22 @@ apple/
 ```
 
 - **`Sources/Astryx/<Name>/`** holds one folder per component, named as in
-  `packages/core/src/<Name>/`. A component's parameters use core's prop names
+  `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:
-  - `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
+  the same across web and native. `Text` and `Heading` take the generated
+  `TextProps` and `HeadingProps`, as AST-093 FR5 asks; the others keep five
+  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.
-  - `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
+  - `TextInput` takes a `Binding` where core has `value` and `onChange`.
+  - `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
@@ -74,7 +80,6 @@ app.
 
 ```swift
 import Astryx
-import SwiftUI
 
 @main
 struct DemoApp: App {
@@ -95,11 +100,22 @@ size.
 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.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
@@ -173,8 +189,9 @@ 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
+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/`.

package/apple/Sources/Astryx/Banner/{AstryxBanner.swift → Banner.swift}

@@ -35,7 +35,7 @@ public enum AstryxBannerStatus: String, CaseIterable, Sendable {
 /// 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 {
+public struct Banner: View {
   let status: AstryxBannerStatus
   let title: String
   let description: String?
@@ -49,17 +49,17 @@ public struct AstryxBanner: View {
 
   public var body: some View {
     HStack(alignment: .firstTextBaseline, spacing: astryx.space(2)) {
-      if let symbol = astryx.icon(status.iconName) {
+      if let icon = astryx.icon(status.iconName) {
         // Sized with the title so it grows with Dynamic Type.
-        Image(systemName: symbol)
+        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)) {
-        AstryxText(title, weight: .semibold)
+        Text(title, weight: .semibold)
         if let description {
-          AstryxText(description, color: .secondary)
+          Text(description, color: .secondary)
         }
       }
       .frame(maxWidth: .infinity, alignment: .leading)
@@ -70,7 +70,7 @@ public struct AstryxBanner: View {
         .fill(astryx.color(status.groundToken))
     )
     .accessibilityElement(children: .ignore)
-    .accessibilityLabel(Text(accessibilityText))
+    .accessibilityLabel(SwiftUI.Text(accessibilityText))
   }
 
   /// What VoiceOver reads: the title, then the description.

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/{AstryxButton.swift → Button.swift}

@@ -29,7 +29,7 @@ public enum AstryxButtonSize: String, CaseIterable, Sendable {
 
 /// 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 {
+public struct Button: View {
   let label: String
   let variant: AstryxButtonVariant
   let size: AstryxButtonSize
@@ -66,14 +66,15 @@ public struct AstryxButton: View {
   }
 
   public var body: some View {
-    Button(action: activate) {
+    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)
+        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))
         }
-        Text(label).lineLimit(1)
+        SwiftUI.Text(label).lineLimit(1)
       }
       .opacity(isLoading ? 0 : 1)
       .overlay {
@@ -94,9 +95,9 @@ public struct AstryxButton: View {
     // 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))
+    .accessibilityLabel(SwiftUI.Text(accessibilityText))
     .accessibilityAddTraits(Self.accessibilityTraits)
-    .accessibilityValue(Text(loadingValue ?? ""))
+    .accessibilityValue(SwiftUI.Text(loadingValue ?? ""))
     .onChange(of: isLoading) { _, loading in
       if loading { AccessibilityNotification.Announcement(AstryxStrings.buttonLoading).post() }
     }

package/apple/Sources/Astryx/Card/{AstryxCard.swift → Card.swift}

@@ -4,7 +4,7 @@ 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 {
+public struct Card<Content: View>: View {
   let padding: Int
   let content: Content
   @Environment(\.astryx) private var astryx

package/apple/Sources/Astryx/Exports.swift

@@ -0,0 +1,8 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+// `import Astryx` is the only import an app file needs: it brings SwiftUI and
+// the generated contracts with it. In a file that imports only Astryx, a name
+// Astryx shares with SwiftUI (`Button`, `Text`) means Astryx's view, and
+// `SwiftUI.Button` names the system one (Swift component API spec, A1, A1a).
+@_exported import AstryxNative
+@_exported import SwiftUI

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

@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// Adapted from github.com/ejc3/astryx-swift (MIT).
+
+/// A heading at levels 1 through 6, painted with the theme's heading tokens
+/// and exposed to VoiceOver as a heading. It takes core's Heading props
+/// (`HeadingProps`).
+public struct Heading: View {
+  public let props: HeadingProps
+  @Environment(\.astryx) private var astryx
+  @Environment(\.multilineTextAlignment) private var inheritedAlignment
+
+  public init(_ props: HeadingProps) {
+    self.props = props
+  }
+
+  /// - Parameters:
+  ///   - children: the words, core's `children`.
+  ///   - level: core's `level`: the heading's place in the outline, which
+  ///     also sets its look unless `type` is given.
+  ///   - type: core's `type`, a display style that replaces the level's look.
+  ///   - weight: core's `weight`, replacing the look's weight.
+  ///   - accessibilityLevel: core's `accessibilityLevel`, the level VoiceOver
+  ///     reads when it differs from `level`.
+  ///   - color: core's `color`; primary when nil.
+  ///   - maxLines: core's `maxLines`; text past it is truncated. Unset, a
+  ///     surrounding `.lineLimit` still applies.
+  ///   - justify: core's `justify`, the alignment of wrapped lines.
+  ///   - hasStrikethrough: core's `hasStrikethrough`.
+  ///   - base: core's base props.
+  public init(
+    _ children: String,
+    level: HeadingLevel,
+    type: HeadingType? = nil,
+    weight: HeadingWeight? = nil,
+    accessibilityLevel: HeadingAccessibilityLevel? = nil,
+    color: HeadingColor? = nil,
+    maxLines: Double? = nil,
+    justify: HeadingJustify? = nil,
+    hasStrikethrough: Bool? = nil,
+    base: AstryxBaseProps = AstryxBaseProps()
+  ) {
+    self.init(
+      HeadingProps(
+        level: level,
+        type: type,
+        weight: weight,
+        children: children,
+        accessibilityLevel: accessibilityLevel,
+        color: color,
+        maxLines: maxLines,
+        justify: justify,
+        hasStrikethrough: hasStrikethrough,
+        base: base
+      )
+    )
+  }
+
+  public var body: some View {
+    styled(SwiftUI.Text(props.children))
+      .astryxMaxLines(props.maxLines)
+      .multilineTextAlignment(props.justify?.alignment ?? inheritedAlignment)
+      .astryxJustified(props.justify?.frameAlignment)
+      .accessibilityAddTraits(Self.accessibilityTraits)
+      .accessibilityHeading(headingLevel)
+      .astryxBase(props.base)
+  }
+
+  func styled(_ text: SwiftUI.Text) -> SwiftUI.Text {
+    var style = typeStyle
+    if let weight = props.weight {
+      style.weight = astryx.tokens.font.weight.value(named: weight.rawValue)
+    }
+    var text = text.font(astryx.font(style))
+    if let color = astryx.tokens.color.text(named: (props.color ?? .primary).rawValue) {
+      text = text.foregroundStyle(color)
+    }
+    if props.hasStrikethrough == true { text = text.strikethrough() }
+    return text
+  }
+
+  /// The level's heading style, or the display style `type` names, in the
+  /// theme's heading family.
+  var typeStyle: TypeStyle {
+    let font = astryx.tokens.font
+    let style: TypeStyleTokens =
+      switch props.type {
+      case .display1: font.display1
+      case .display2: font.display2
+      case .display3: font.display3
+      case nil:
+        switch props.level {
+        case .v1: font.heading1
+        case .v2: font.heading2
+        case .v3: font.heading3
+        case .v4: font.heading4
+        case .v5: font.heading5
+        case .v6: font.heading6
+        }
+      }
+    return TypeStyle(style, families: font.family.heading)
+  }
+
+  /// The traits assistive technology gets: a header.
+  static var accessibilityTraits: AccessibilityTraits { .isHeader }
+
+  /// The level VoiceOver reads: `accessibilityLevel` when given, else `level`.
+  var headingLevel: AccessibilityHeadingLevel {
+    switch props.accessibilityLevel?.rawValue ?? props.level.rawValue {
+    case 1: .h1
+    case 2: .h2
+    case 3: .h3
+    case 4: .h4
+    case 5: .h5
+    default: .h6
+    }
+  }
+}

package/apple/Sources/Astryx/Icon/Icon.spec.md

@@ -0,0 +1,186 @@
+---
+schema_version: 5
+template_version: 8
+kind: component
+id: component:swift/Icon
+platform_of: component:Icon
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, theming, accessibility]
+verified_by:
+  [
+    packages/native/apple/Tests/AstryxTests/IconTests.swift,
+    packages/native/src/contract/contracts.test.ts,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-size-cascade,
+    architecture:icon-resolution-and-component-slots,
+  ]
+contributing: []
+system_specs: [spec:AST-082, spec:AST-093]
+---
+
+# Icon (Swift) component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                                            |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `Icon(_ icon: IconName, color: IconColor? = nil, size: IconSize? = nil, label: String? = nil)` and `Icon(_ props: IconProps)`, a SwiftUI `View` in module `Astryx`. `IconName` is a string-backed name with every built-in name as a static member (`.search`, `.close`).                           |
+| Behavior                | Draws the image the theme or the platform maps the name to (an SF Symbol, or an asset the app ships), in a square box at core's icon size grown with Dynamic Type, in core's icon color token or the surrounding foreground. A name nothing maps, or an asset the app does not ship, draws nothing. |
+| End-user impact         | A person sees the platform's own symbol for each shared icon, or the app's own artwork where its theme maps one, sized and colored as on the web, and VoiceOver reads only icons that carry a label.                                                                                                |
+| Builder impact          | An app passes a shared name (`.search`) or a name it maps in its theme (`"acme:rocket"`). An SVG component, which the web also accepts, has no Swift form.                                                                                                                                          |
+| Compatibility/readiness | Additive: a new view and a new generated `IconName` type. Draft; built and tested on macOS and the iOS Simulator; device captures are attached to the change.                                                                                                                                       |
+| Review checks           | Reject a substitute symbol for an unknown name, an image or attributed-text form of the icon slot, a visual parameter beyond the contract, an unlabeled icon that VoiceOver reads, or an owner's size winning over an explicit `size`.                                                              |
+| Governing rules         | `spec:AST-082` FR4, FR7, FR17; `spec:AST-093` FR1–FR5; the Swift component API, styles, slots, theme environment, and accessibility records under `packages/native/specs/swift/library/`.                                                                                                           |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Icon on Apple platforms draws Astryx's shared icon names as SF Symbols, or as
+images the app ships where its theme maps them, so an
+icon beside system controls looks like the platform's own while its size, color,
+and accessibility follow the core `Icon` contract.
+
+## Compatibility and migration
+
+- Released default preserved: `not yet released`
+- Compatibility class: additive
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- Resolving a shared icon name to an image: the theme's mapping (an SF Symbol
+  or an app asset), else the platform's default SF Symbol.
+- Drawing the image in a square box at core's icon size, grown with Dynamic
+  Type, in core's icon color token. An asset takes the color token when its
+  asset catalog renders it as a template image, and keeps its own colors when
+  it renders as an original image.
+- The icon's VoiceOver exposure.
+
+**Does not own / non-goals**
+
+- The meaning of `icon`, `color`, `size`, and `label` and the built-in names —
+  owned by `component:Icon` and `spec:AST-082` FR17.
+- Which size an owner gives the icons in its icon slot — owned by each owning
+  component and `architecture:component-size-cascade`.
+- The default SF Symbol for each name — owned by `@astryxdesign/native`'s icon
+  defaults, which a test keeps equal to the Swift map.
+
+## Public concepts
+
+| Concept       | Closed values or states                                                                                   | Meaning                                                                                           | Availability by variant/orientation/state | Default                    | Owner                  | Stability    | Invalid-value behavior                                                  |
+| ------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------- | ---------------------- | ------------ | ----------------------------------------------------------------------- |
+| icon name     | the built-in names; a `<library>:<name>` the theme maps                                                   | `IconName`, a string on the wire, with each built-in as a static member                           | always                                    | required                   | `component:Icon`       | experimental | an unmapped name stops a development build and draws nothing in release |
+| symbol source | theme mapping; platform default                                                                           | `Theme(icons:)` replaces a built-in or registers a library name with an SF Symbol or an app asset | always                                    | platform default           | `component:swift/Icon` | experimental | a theme entry wins over the default                                     |
+| size          | `xsm`, `sm`, `md`, `lg`; unset                                                                            | 12, 16, 20, 24 points at the default text size                                                    | always                                    | owner's icon size, else md | `component:Icon`       | experimental | unset takes the owner's size, then `md`                                 |
+| color         | `primary`, `secondary`, `tertiary`, `disabled`, `accent`, `success`, `error`, `warning`, `inherit`; unset | core's icon color tokens; `inherit` keeps the surrounding foreground                              | always                                    | `inherit`                  | `component:Icon`       | experimental | unset is `inherit`                                                      |
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                               | Basis                                                       | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ |
+| FR1 | The view MUST draw the image the theme's `icons` maps the name to, an SF Symbol or an asset the app ships, else the platform default for a built-in name. A name neither maps, or an asset the app does not ship, MUST stop a development build with a message naming it and draw nothing in a release build, never a substitute. | `spec:AST-082` FR17; Swift slots S2                         | verify             |
+| FR2 | The symbol MUST fit a square box whose side is core's size in points (12, 16, 20, 24 for `xsm`, `sm`, `md`, `lg`), multiplied by the Dynamic Type scale the theme environment reads.                                                                                                                                              | core `Icon` sizes; `spec:AST-093` FR3; theme environment E1 | verify             |
+| FR3 | The view MUST use its own `size`, else the size its owning component gives icons in its documented icon slot, else `md`.                                                                                                                                                                                                          | `architecture:component-size-cascade`; Swift slots S4       | verify             |
+| FR4 | The view MUST draw in core's token for its `color` — primary and secondary icon tokens, the secondary icon token for `tertiary`, the disabled icon token, and the accent, success, error, and warning colors — and, for `inherit` or no color, MUST keep the surrounding foreground style.                                        | core `Icon` color map; `spec:AST-093` FR4                   | verify             |
+| FR5 | Both initializers MUST build the same `IconProps`; the labeled initializer takes the contract's props with the generated types and defaults, and base props (`id`, `isHidden`) come through `IconProps`. With `isHidden` the view draws nothing; `id` becomes the accessibility identifier.                                       | Swift component API A2, A3, A7; `spec:AST-082` FR7          | verify             |
+
+### Allowed variation
+
+- **AV1 — Glyph shape.** The glyph is the platform's SF Symbol, not the web's
+  SVG; a theme may map any name to another SF Symbol or to an image the app
+  ships (`spec:AST-082` FR17).
+
+### Representative states
+
+| State                       | Required invariant                            | Allowed variation            |
+| --------------------------- | --------------------------------------------- | ---------------------------- |
+| every size                  | box side 12, 16, 20, 24 points at Large text  | glyph proportions per symbol |
+| every color, light and dark | the color's token in the current mode         | none                         |
+| inside an owner's icon slot | the owner's size unless the icon sets its own | none                         |
+| largest text size           | the box grows with Dynamic Type               | none                         |
+| labeled and unlabeled       | VoiceOver reads only the labeled icon         | none                         |
+
+### Transformation and precedence order
+
+- **ORD1 — Image.** Theme mapping (SF Symbol or app asset) → platform default
+  SF Symbol → nothing.
+- **ORD2 — Size.** Explicit `size` → owner's icon size → `md`, then × Dynamic
+  Type scale.
+
+### Performance and resources
+
+- **PR1 — No image data of its own.** The view draws a system symbol by name,
+  or an asset from the app's main bundle by name; it holds no image data and
+  loads nothing from the network.
+
+## Accessibility contract
+
+- **AR1 — Decorative unless labeled.** With no `label`, or an empty one, the
+  view is hidden from VoiceOver. With a label, it is one image element named by
+  the label, keeping SwiftUI's image trait and adding none (`spec:AST-082` FR17;
+  Swift accessibility X1, X4).
+- **AR2 — Rendered tree not measured.** Tests assert what the view sets; the
+  rendered accessibility tree is not measured until an app-hosted target exists.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                             | Representation authority   | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------- | -------------------------- | -------------- | ------------------ |
+| Glyph            | SF Symbols (Apple Human Interface Guidelines), or an app asset | prescribed by the platform | supporting     | FR1, FR2           |
+
+The component implements design requirements without copying their rationale.
+
+Platform control: SwiftUI `Image(systemName:)`, or `Image(_:bundle:)` for an
+app asset. It is the platform's own icon view and satisfies the contract, so no custom drawing is needed (`spec:AST-093`
+FR2). Guideline pages: SF Symbols and Accessibility in the Apple Human
+Interface Guidelines.
+
+Theme values read: `color.iconPrimary`, `color.iconSecondary`,
+`color.iconDisabled`, `color.accent`, `color.success`, `color.error`,
+`color.warning`, the theme's `icons` map, and the Dynamic Type scale.
+
+## Family and system relationships
+
+- `component:Icon` owns the props, the built-in names, the size scale, and the
+  color map; this record states only how Swift draws them.
+- `architecture:component-size-cascade` owns when an owner's icon size applies;
+  owners set it through an internal environment value this view reads.
+
+## Verification map
+
+| Contract | Verification                                                                                                        | Representative states                                                                                                                   | Mutation or failure expectation                                                                                          | Audit section              |
+| -------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
+| FR1      | `IconTests.swift` symbol and asset tests (a test bundle stands in for the app's); `contracts.test.ts` IconName test | every built-in; theme replacement; library name; a shipped asset; a missing asset drawing nothing and reported (the release-build path) | a missing default, a symbol absent on the platform, a missing asset that draws or goes unreported, or a substitute fails | `audit:swift/Icon/symbols` |
+| FR2, FR3 | `IconTests.swift` size and Dynamic Type renders                                                                     | each size; owner size; explicit size; AX5                                                                                               | a wrong side or an owner size beating an explicit size fails                                                             | `audit:swift/Icon/size`    |
+| FR4      | `IconTests.swift` color map and two-theme render                                                                    | every color; neutral and butter                                                                                                         | a wrong token or a color of the view's own fails                                                                         | `audit:swift/Icon/color`   |
+| FR5      | `IconTests.swift` initializer and hidden tests                                                                      | both initializers; `isHidden`                                                                                                           | differing props or a drawn hidden icon fails                                                                             | `audit:swift/Icon/api`     |
+| AR1      | `IconTests.swift` accessibility assertions                                                                          | labeled, unlabeled, empty label                                                                                                         | an unlabeled icon with a label, or a labeled one without, fails                                                          | `audit:swift/Icon/a11y`    |
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.