@astryxdesign/native 0.7.5-canary.8b74911 → 0.7.5-canary.8be99c4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/apple/Package.swift +5 -1
  2. package/apple/README.md +13 -9
  3. package/apple/Sources/Astryx/Banner/Banner.swift +2 -2
  4. package/apple/Sources/Astryx/Base/BaseProps.swift +16 -0
  5. package/apple/Sources/Astryx/Button/Button.swift +3 -2
  6. package/apple/Sources/Astryx/Card/Card.swift +95 -19
  7. package/apple/Sources/Astryx/Heading/Heading.swift +90 -19
  8. package/apple/Sources/Astryx/Icon/Icon.spec.md +51 -47
  9. package/apple/Sources/Astryx/Icon/Icon.swift +5 -4
  10. package/apple/Sources/Astryx/Text/Text.swift +89 -70
  11. package/apple/Sources/Astryx/Text/TypeStyle.swift +143 -0
  12. package/apple/Sources/Astryx/Theme/AstryxIcons.swift +72 -1
  13. package/apple/Sources/Astryx/Theme/Generated/ButterTheme.swift +352 -406
  14. package/apple/Sources/Astryx/Theme/Generated/ChocolateTheme.swift +352 -406
  15. package/apple/Sources/Astryx/Theme/Generated/DefaultTheme.swift +352 -406
  16. package/apple/Sources/Astryx/Theme/Generated/GothicTheme.swift +352 -406
  17. package/apple/Sources/Astryx/Theme/Generated/MatchaTheme.swift +352 -406
  18. package/apple/Sources/Astryx/Theme/Generated/NeutralTheme.swift +352 -406
  19. package/apple/Sources/Astryx/Theme/Generated/StoneTheme.swift +352 -406
  20. package/apple/Sources/Astryx/Theme/Generated/Tokens.swift +296 -238
  21. package/apple/Sources/Astryx/Theme/Generated/Y2kTheme.swift +352 -406
  22. package/apple/Sources/Astryx/Theme/Shadow.swift +41 -0
  23. package/apple/Sources/Astryx/Theme/Theme.swift +14 -43
  24. package/apple/Sources/Astryx/Tooltip/TooltipPresenter.swift +529 -0
  25. package/apple/Sources/Astryx/Wire/AstryxNodeView.swift +75 -0
  26. package/apple/Tests/AstryxTests/BannerTests.swift +1 -1
  27. package/apple/Tests/AstryxTests/CardTests.swift +133 -3
  28. package/apple/Tests/AstryxTests/EnvironmentTests.swift +2 -2
  29. package/apple/Tests/AstryxTests/HeadingTests.swift +41 -13
  30. package/apple/Tests/AstryxTests/IconTests.swift +49 -3
  31. package/apple/Tests/AstryxTests/Resources/astryx-test-icon.png +0 -0
  32. package/apple/Tests/AstryxTests/TextInputTests.swift +1 -1
  33. package/apple/Tests/AstryxTests/TextTests.swift +90 -6
  34. package/apple/Tests/AstryxTests/ThemeTests.swift +4 -10
  35. package/apple/Tests/AstryxTests/TooltipPresenterTests.swift +170 -0
  36. package/apple/Tests/AstryxTests/TwoThemeTests.swift +5 -5
  37. package/package.json +4 -4
  38. package/src/theme/swiftIOSTheme.test.ts +78 -12
@@ -32,6 +32,10 @@ let package = Package(
32
32
  resources: [.process("Resources")]
33
33
  ),
34
34
  .testTarget(name: "AstryxNativeTests", dependencies: ["AstryxNative"], path: "Tests/AstryxNativeTests"),
35
- .testTarget(name: "AstryxTests", dependencies: ["Astryx"], path: "Tests/AstryxTests"),
35
+ .testTarget(
36
+ name: "AstryxTests", dependencies: ["Astryx"], path: "Tests/AstryxTests",
37
+ // A tiny image that stands in for an app-shipped icon asset.
38
+ resources: [.process("Resources")]
39
+ ),
36
40
  ]
37
41
  )
package/apple/README.md CHANGED
@@ -51,16 +51,15 @@ apple/
51
51
  that also imports SwiftUI, write `Astryx.Button` and `SwiftUI.Button`. A
52
52
  component's parameters use core's prop names
53
53
  and values (`variant: .primary`, `size: .lg`, `isLoading`), so code reads
54
- the same across web and native, with six exceptions, the interim shape
55
- AST-093 FR5 exempts until the components move onto the generated contracts:
54
+ the same across web and native. `Text`, `Heading`, and `Card` take the
55
+ generated `TextProps`, `HeadingProps`, and `CardProps`, as AST-093 FR5 asks;
56
+ the others keep four exceptions, the interim shape FR5 exempts until they move onto the generated
57
+ contracts:
56
58
  - `Button` takes `action` where core has `onClick`.
57
59
  - `Button` takes `fillsWidth` where core has `width="100%"`.
58
60
  - `Button` takes `icon` as a shared icon name (`"search"`), which the
59
61
  generated `ButtonProps` does not carry yet.
60
62
  - `TextInput` takes a `Binding` where core has `value` and `onChange`.
61
- - `Heading`'s `level` is optional where core requires it.
62
- - `Card` takes `padding` as a whole spacing step, so it cannot spell
63
- core's `0.5` and `1.5` steps.
64
63
  - **`Templates/`** holds one folder per page template, named after the
65
64
  `astryx template` id. Templates are clone-only, as on the web: you copy a
66
65
  template's folder into your app and own it from then on. They are a
@@ -99,16 +98,21 @@ size.
99
98
  Components read every color, size, and font from the `astryx` environment
100
99
  value, never from a constant of their own. `astryx.tokens` holds the theme's
101
100
  tokens in the current mode as typed members (`tokens.color.textPrimary`,
102
- `tokens.space.s4`, `tokens.font.bodySize`), so a misspelled token fails to
103
- compile. Text sizes grow with Dynamic Type. The components still read some
101
+ `tokens.space.s4`, `tokens.font.body.size`), so a misspelled token fails to
102
+ compile. Font tokens come grouped: each type style (`tokens.font.body`,
103
+ `tokens.font.heading1`) holds its `size`, `weight`, and `leading`, and
104
+ `tokens.font.family`, `.size`, and `.weight` hold the scales. Text sizes grow with Dynamic Type. The components still read some
104
105
  tokens by core's name (`astryx.color("color-accent")`); moving them onto the
105
106
  typed members comes next.
106
107
 
107
108
  `Icon(.search)` draws a shared icon name as the platform's SF Symbol, at
108
109
  core's icon size and color, hidden from VoiceOver unless it has a `label`.
109
110
  `IconName` holds every built-in name as a static member; a theme maps a name
110
- to another symbol, or registers a `<library>:<name>` name, with
111
- `Theme(…, icons: ["acme:rocket": "airplane"])`.
111
+ to another symbol or to an image the app ships, or registers a
112
+ `<library>:<name>` name, with
113
+ `Theme(…, icons: ["acme:rocket": "airplane", "close": .assetName("brand.close")])`.
114
+ An asset the app does not ship stops a development build with a message that
115
+ names it, and draws nothing in a release build.
112
116
 
113
117
  Font families come from the theme's `font-family-*` stacks: the first family
114
118
  the device has wins, and a system family such as `-apple-system` or
@@ -49,9 +49,9 @@ public struct Banner: View {
49
49
 
50
50
  public var body: some View {
51
51
  HStack(alignment: .firstTextBaseline, spacing: astryx.space(2)) {
52
- if let symbol = astryx.icon(status.iconName) {
52
+ if let icon = astryx.icon(status.iconName) {
53
53
  // Sized with the title so it grows with Dynamic Type.
54
- Image(systemName: symbol)
54
+ icon.sized(astryx.fontSize("text-body-size", 14))
55
55
  .font(astryx.font(size: "text-body-size", 14, weight: "text-body-weight"))
56
56
  .foregroundStyle(astryx.color(status.iconToken))
57
57
  .accessibilityHidden(true)
@@ -0,0 +1,16 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ extension View {
4
+ /// Core's base props on a view: `id` names it for UI tests, and `isHidden`
5
+ /// removes it from layout and from assistive technology, as core's `hidden`
6
+ /// attribute does.
7
+ @ViewBuilder func astryxBase(_ base: AstryxBaseProps) -> some View {
8
+ if base.isHidden == true {
9
+ EmptyView()
10
+ } else if let id = base.id {
11
+ accessibilityIdentifier(id)
12
+ } else {
13
+ self
14
+ }
15
+ }
16
+ }
@@ -70,8 +70,9 @@ public struct Button: View {
70
70
  // The label keeps its place while loading so the width holds; the
71
71
  // spinner draws over it.
72
72
  HStack(spacing: astryx.space(2)) {
73
- if let icon, let symbol = astryx.icon(icon) {
74
- Image(systemName: symbol)
73
+ if let icon, let image = astryx.icon(icon) {
74
+ // An asset matches the label's text size, as a symbol does.
75
+ image.sized(astryx.fontSize("text-label-size", 14))
75
76
  }
76
77
  SwiftUI.Text(label).lineLimit(1)
77
78
  }
@@ -1,33 +1,109 @@
1
1
  // Copyright (c) Meta Platforms, Inc. and affiliates.
2
2
 
3
- import SwiftUI
4
-
5
- /// A card: one independent item on the theme's card ground, with a hairline
6
- /// border and the container radius.
3
+ /// A card: one independent item on the theme's card ground. It takes core's
4
+ /// Card props (`CardProps`) and stacks its content top to bottom, as children
5
+ /// flow inside core's Card.
7
6
  public struct Card<Content: View>: View {
8
- let padding: Int
7
+ public let props: CardProps
9
8
  let content: Content
10
9
  @Environment(\.astryx) private var astryx
11
10
 
12
- /// - Parameter padding: a step on the spacing ladder, as core's `padding`.
13
- public init(padding: Int = 4, @ViewBuilder content: () -> Content) {
14
- self.padding = padding
11
+ /// - Parameters:
12
+ /// - padding: core's `padding`, a step on the spacing scale; step 4 when
13
+ /// nil.
14
+ /// - variant: core's `variant`: the card ground, or `transparent` for none.
15
+ /// Only `default` draws a border.
16
+ /// - elevation: core's `elevation`, the theme's shadow at that depth.
17
+ /// - base: core's base props.
18
+ /// - content: core's `children`.
19
+ public init(
20
+ padding: CardPadding? = nil,
21
+ variant: CardVariant? = nil,
22
+ elevation: CardElevation? = nil,
23
+ base: AstryxBaseProps = AstryxBaseProps(),
24
+ @ViewBuilder content: () -> Content
25
+ ) {
26
+ self.props = CardProps(padding: padding, variant: variant, elevation: elevation, base: base)
15
27
  self.content = content()
16
28
  }
17
29
 
18
30
  public var body: some View {
19
- let shape = RoundedRectangle(
20
- cornerRadius: astryx.size("radius-container", 12),
21
- style: .continuous
22
- )
23
- // Several child views stack in one card, top to bottom with no gap of
24
- // their own, as children flow inside core's Card.
25
- VStack(alignment: .leading, spacing: 0) { content }
26
- .padding(astryx.space(padding))
31
+ let shape = RoundedRectangle(cornerRadius: astryx.tokens.radius.container, style: .continuous)
32
+ let variant = props.variant ?? .default
33
+ // The border sits inside the padding, so the content's inset is the
34
+ // padding step, as in core.
35
+ SwiftUI.VStack(alignment: .leading, spacing: 0) { content }
36
+ .padding(padding)
27
37
  .frame(maxWidth: .infinity, alignment: .leading)
28
- .background(shape.fill(astryx.color("color-background-card")))
29
- .overlay(
30
- shape.strokeBorder(astryx.color("color-border"), lineWidth: astryx.size("border-width", 1))
38
+ .background(shape.fill(Self.ground(variant, astryx.tokens.color)))
39
+ .overlay {
40
+ if variant == .default {
41
+ shape.strokeBorder(astryx.tokens.color.border, lineWidth: astryx.tokens.size.borderWidth)
42
+ }
43
+ }
44
+ .astryxShadow(
45
+ Self.shadow(props.elevation ?? .none, astryx.tokens.shadow), in: shape,
46
+ borderWidth: variant == .default ? astryx.tokens.size.borderWidth : 0
31
47
  )
48
+ .astryxBase(props.base)
49
+ }
50
+
51
+ var padding: CGFloat {
52
+ let space = astryx.tokens.space
53
+ switch props.padding ?? .v4 {
54
+ case .v0: return space.s0
55
+ case .v0_5: return space.s0_5
56
+ case .v1: return space.s1
57
+ case .v1_5: return space.s1_5
58
+ case .v2: return space.s2
59
+ case .v3: return space.s3
60
+ case .v4: return space.s4
61
+ case .v5: return space.s5
62
+ case .v6: return space.s6
63
+ case .v8: return space.s8
64
+ case .v10: return space.s10
65
+ }
66
+ }
67
+
68
+ /// The ground core's Card draws for a variant.
69
+ static func ground(_ variant: CardVariant, _ color: ColorTokens) -> Color {
70
+ switch variant {
71
+ case .default: color.backgroundCard
72
+ case .transparent: .clear
73
+ case .muted: color.backgroundMuted
74
+ case .blue: color.backgroundBlue
75
+ case .cyan: color.backgroundCyan
76
+ case .gray: color.backgroundGray
77
+ case .green: color.backgroundGreen
78
+ case .orange: color.backgroundOrange
79
+ case .pink: color.backgroundPink
80
+ case .purple: color.backgroundPurple
81
+ case .red: color.backgroundRed
82
+ case .teal: color.backgroundTeal
83
+ case .yellow: color.backgroundYellow
84
+ }
85
+ }
86
+
87
+ /// The theme's shadow at an elevation.
88
+ static func shadow(_ elevation: CardElevation, _ shadow: ShadowTokens) -> [ShadowLayer] {
89
+ switch elevation {
90
+ case .none: []
91
+ case .low: shadow.low
92
+ case .med: shadow.med
93
+ case .high: shadow.high
94
+ }
95
+ }
96
+ }
97
+
98
+ extension Card where Content == AstryxNodeList {
99
+ /// A card from core's props, with its children as the wire tree a logic
100
+ /// core sends; `send` carries the children's callbacks back to the core.
101
+ public init(
102
+ _ props: CardProps,
103
+ children: [AstryxNode],
104
+ send: @escaping @Sendable (AstryxAction) -> Void
105
+ ) {
106
+ self.props = props
107
+ self.content = AstryxNodeList(nodes: children, send: send)
32
108
  }
33
109
  }
@@ -1,40 +1,111 @@
1
1
  // Copyright (c) Meta Platforms, Inc. and affiliates.
2
2
  // Adapted from github.com/ejc3/astryx-swift (MIT).
3
3
 
4
- import SwiftUI
5
-
6
4
  /// A heading at levels 1 through 6, painted with the theme's heading tokens
7
- /// and exposed to VoiceOver as a heading.
5
+ /// and exposed to VoiceOver as a heading. It takes core's Heading props
6
+ /// (`HeadingProps`).
8
7
  public struct Heading: View {
9
- let content: String
10
- let level: Int
8
+ public let props: HeadingProps
11
9
  @Environment(\.astryx) private var astryx
10
+ @Environment(\.multilineTextAlignment) private var inheritedAlignment
12
11
 
13
- public init(_ content: String, level: Int = 2) {
14
- self.content = content
15
- self.level = min(max(level, 1), 6)
12
+ public init(_ props: HeadingProps) {
13
+ self.props = props
16
14
  }
17
15
 
18
- public var body: some View {
19
- SwiftUI.Text(content)
20
- .font(
21
- astryx.font(
22
- size: "text-heading-\(level)-size",
23
- 20,
24
- weight: "text-heading-\(level)-weight",
25
- family: "font-family-heading"
26
- )
16
+ /// - Parameters:
17
+ /// - children: the words, core's `children`.
18
+ /// - level: core's `level`: the heading's place in the outline, which
19
+ /// also sets its look unless `type` is given.
20
+ /// - type: core's `type`, a display style that replaces the level's look.
21
+ /// - weight: core's `weight`, replacing the look's weight.
22
+ /// - accessibilityLevel: core's `accessibilityLevel`, the level VoiceOver
23
+ /// reads when it differs from `level`.
24
+ /// - color: core's `color`; primary when nil.
25
+ /// - maxLines: core's `maxLines`; text past it is truncated. Unset, a
26
+ /// surrounding `.lineLimit` still applies.
27
+ /// - justify: core's `justify`, the alignment of wrapped lines.
28
+ /// - hasStrikethrough: core's `hasStrikethrough`.
29
+ /// - base: core's base props.
30
+ public init(
31
+ _ children: String,
32
+ level: HeadingLevel,
33
+ type: HeadingType? = nil,
34
+ weight: HeadingWeight? = nil,
35
+ accessibilityLevel: HeadingAccessibilityLevel? = nil,
36
+ color: HeadingColor? = nil,
37
+ maxLines: Double? = nil,
38
+ justify: HeadingJustify? = nil,
39
+ hasStrikethrough: Bool? = nil,
40
+ base: AstryxBaseProps = AstryxBaseProps()
41
+ ) {
42
+ self.init(
43
+ HeadingProps(
44
+ level: level,
45
+ type: type,
46
+ weight: weight,
47
+ children: children,
48
+ accessibilityLevel: accessibilityLevel,
49
+ color: color,
50
+ maxLines: maxLines,
51
+ justify: justify,
52
+ hasStrikethrough: hasStrikethrough,
53
+ base: base
27
54
  )
28
- .foregroundStyle(astryx.color("color-text-primary"))
55
+ )
56
+ }
57
+
58
+ public var body: some View {
59
+ styled(SwiftUI.Text(props.children))
60
+ .astryxMaxLines(props.maxLines)
61
+ .multilineTextAlignment(props.justify?.alignment ?? inheritedAlignment)
62
+ .astryxJustified(props.justify?.frameAlignment)
29
63
  .accessibilityAddTraits(Self.accessibilityTraits)
30
64
  .accessibilityHeading(headingLevel)
65
+ .astryxBase(props.base)
66
+ }
67
+
68
+ func styled(_ text: SwiftUI.Text) -> SwiftUI.Text {
69
+ var style = typeStyle
70
+ if let weight = props.weight {
71
+ style.weight = astryx.tokens.font.weight.value(named: weight.rawValue)
72
+ }
73
+ var text = text.font(astryx.font(style))
74
+ if let color = astryx.tokens.color.text(named: (props.color ?? .primary).rawValue) {
75
+ text = text.foregroundStyle(color)
76
+ }
77
+ if props.hasStrikethrough == true { text = text.strikethrough() }
78
+ return text
79
+ }
80
+
81
+ /// The level's heading style, or the display style `type` names, in the
82
+ /// theme's heading family.
83
+ var typeStyle: TypeStyle {
84
+ let font = astryx.tokens.font
85
+ let style: TypeStyleTokens =
86
+ switch props.type {
87
+ case .display1: font.display1
88
+ case .display2: font.display2
89
+ case .display3: font.display3
90
+ case nil:
91
+ switch props.level {
92
+ case .v1: font.heading1
93
+ case .v2: font.heading2
94
+ case .v3: font.heading3
95
+ case .v4: font.heading4
96
+ case .v5: font.heading5
97
+ case .v6: font.heading6
98
+ }
99
+ }
100
+ return TypeStyle(style, families: font.family.heading)
31
101
  }
32
102
 
33
103
  /// The traits assistive technology gets: a header.
34
104
  static var accessibilityTraits: AccessibilityTraits { .isHeader }
35
105
 
106
+ /// The level VoiceOver reads: `accessibilityLevel` when given, else `level`.
36
107
  var headingLevel: AccessibilityHeadingLevel {
37
- switch level {
108
+ switch props.accessibilityLevel?.rawValue ?? props.level.rawValue {
38
109
  case 1: .h1
39
110
  case 2: .h2
40
111
  case 3: .h3
@@ -32,21 +32,22 @@ system_specs: [spec:AST-082, spec:AST-093]
32
32
 
33
33
  ## Contract at a glance
34
34
 
35
- | Area | Contract |
36
- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
37
- | 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`). |
38
- | Behavior | Draws the SF Symbol the theme or the platform maps the name to, 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 draws nothing. |
39
- | End-user impact | A person sees the platform's own symbol for each shared icon, sized and colored as on the web, and VoiceOver reads only icons that carry a label. |
40
- | 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. |
41
- | 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. |
42
- | 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`. |
43
- | 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/`. |
35
+ | Area | Contract |
36
+ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
37
+ | 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`). |
38
+ | 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. |
39
+ | 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. |
40
+ | 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. |
41
+ | 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. |
42
+ | 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`. |
43
+ | 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/`. |
44
44
 
45
45
  This table is a review projection; the body below is authoritative.
46
46
 
47
47
  ## Intent
48
48
 
49
- Icon on Apple platforms draws Astryx's shared icon names as SF Symbols, so an
49
+ Icon on Apple platforms draws Astryx's shared icon names as SF Symbols, or as
50
+ images the app ships where its theme maps them, so an
50
51
  icon beside system controls looks like the platform's own while its size, color,
51
52
  and accessibility follow the core `Icon` contract.
52
53
 
@@ -63,10 +64,12 @@ Consumer migration instructions belong in consumer docs and release notes.
63
64
 
64
65
  **Owns**
65
66
 
66
- - Resolving a shared icon name to an SF Symbol: the theme's mapping, else the
67
- platform default.
68
- - Drawing the symbol in a square box at core's icon size, grown with Dynamic
69
- Type, in core's icon color token.
67
+ - Resolving a shared icon name to an image: the theme's mapping (an SF Symbol
68
+ or an app asset), else the platform's default SF Symbol.
69
+ - Drawing the image in a square box at core's icon size, grown with Dynamic
70
+ Type, in core's icon color token. An asset takes the color token when its
71
+ asset catalog renders it as a template image, and keeps its own colors when
72
+ it renders as an original image.
70
73
  - The icon's VoiceOver exposure.
71
74
 
72
75
  **Does not own / non-goals**
@@ -80,27 +83,28 @@ Consumer migration instructions belong in consumer docs and release notes.
80
83
 
81
84
  ## Public concepts
82
85
 
83
- | Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
84
- | ------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------- | ---------------------- | ------------ | ----------------------------------------------------------------------- |
85
- | 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 |
86
- | symbol source | theme mapping; platform default | `Theme(icons:)` replaces a built-in or registers a library name with an SF Symbol name | always | platform default | `component:swift/Icon` | experimental | a theme entry wins over the default |
87
- | 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` |
88
- | 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` |
86
+ | Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
87
+ | ------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------- | ---------------------- | ------------ | ----------------------------------------------------------------------- |
88
+ | 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 |
89
+ | 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 |
90
+ | 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` |
91
+ | 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` |
89
92
 
90
93
  ## Behavioral and layout contract
91
94
 
92
- | ID | Candidate invariant | Basis | Draft review state |
93
- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ |
94
- | FR1 | The view MUST draw the SF Symbol the theme's `icons` maps the name to, else the platform default for a built-in name. A name neither maps 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 |
95
- | 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 |
96
- | 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 |
97
- | 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 |
98
- | 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 |
95
+ | ID | Candidate invariant | Basis | Draft review state |
96
+ | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ |
97
+ | 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 |
98
+ | 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 |
99
+ | 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 |
100
+ | 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 |
101
+ | 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 |
99
102
 
100
103
  ### Allowed variation
101
104
 
102
- - **AV1 — Glyph shape.** The symbol is the platform's SF Symbol, not the web's
103
- SVG; a theme may map any name to another SF Symbol.
105
+ - **AV1 — Glyph shape.** The glyph is the platform's SF Symbol, not the web's
106
+ SVG; a theme may map any name to another SF Symbol or to an image the app
107
+ ships (`spec:AST-082` FR17).
104
108
 
105
109
  ### Representative states
106
110
 
@@ -114,14 +118,16 @@ Consumer migration instructions belong in consumer docs and release notes.
114
118
 
115
119
  ### Transformation and precedence order
116
120
 
117
- - **ORD1 — Symbol.** Theme mapping → platform default → nothing.
121
+ - **ORD1 — Image.** Theme mapping (SF Symbol or app asset) → platform default
122
+ SF Symbol → nothing.
118
123
  - **ORD2 — Size.** Explicit `size` → owner's icon size → `md`, then × Dynamic
119
124
  Type scale.
120
125
 
121
126
  ### Performance and resources
122
127
 
123
- - **PR1 — No image loading.** The view draws a system symbol by name and holds
124
- no image data of its own.
128
+ - **PR1 — No image data of its own.** The view draws a system symbol by name,
129
+ or an asset from the app's main bundle by name; it holds no image data and
130
+ loads nothing from the network.
125
131
 
126
132
  ## Accessibility contract
127
133
 
@@ -134,14 +140,14 @@ Consumer migration instructions belong in consumer docs and release notes.
134
140
 
135
141
  ## Design relationships
136
142
 
137
- | Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
138
- | ---------------- | --------------------------------------------- | -------------------------- | -------------- | ------------------ |
139
- | Glyph | SF Symbols (Apple Human Interface Guidelines) | prescribed by the platform | supporting | FR1, FR2 |
143
+ | Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
144
+ | ---------------- | -------------------------------------------------------------- | -------------------------- | -------------- | ------------------ |
145
+ | Glyph | SF Symbols (Apple Human Interface Guidelines), or an app asset | prescribed by the platform | supporting | FR1, FR2 |
140
146
 
141
147
  The component implements design requirements without copying their rationale.
142
148
 
143
- Platform control: SwiftUI `Image(systemName:)`. It is the platform's own icon
144
- view and satisfies the contract, so no custom drawing is needed (`spec:AST-093`
149
+ Platform control: SwiftUI `Image(systemName:)`, or `Image(_:bundle:)` for an
150
+ app asset. It is the platform's own icon view and satisfies the contract, so no custom drawing is needed (`spec:AST-093`
145
151
  FR2). Guideline pages: SF Symbols and Accessibility in the Apple Human
146
152
  Interface Guidelines.
147
153
 
@@ -158,13 +164,13 @@ Theme values read: `color.iconPrimary`, `color.iconSecondary`,
158
164
 
159
165
  ## Verification map
160
166
 
161
- | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
162
- | -------- | ----------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- | -------------------------- |
163
- | FR1 | `IconTests.swift` symbol tests; `contracts.test.ts` IconName test | every built-in; theme replacement; library name | a missing default, a symbol absent on the platform, or a substitute fails | `audit:swift/Icon/symbols` |
164
- | 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` |
165
- | 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` |
166
- | FR5 | `IconTests.swift` initializer and hidden tests | both initializers; `isHidden` | differing props or a drawn hidden icon fails | `audit:swift/Icon/api` |
167
- | 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` |
167
+ | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
168
+ | -------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
169
+ | 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` |
170
+ | 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` |
171
+ | 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` |
172
+ | FR5 | `IconTests.swift` initializer and hidden tests | both initializers; `isHidden` | differing props or a drawn hidden icon fails | `audit:swift/Icon/api` |
173
+ | 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` |
168
174
 
169
175
  ## Decision log
170
176
 
@@ -172,9 +178,7 @@ No component-local decision is recorded.
172
178
 
173
179
  ## Open questions
174
180
 
175
- - **OQ1 — Can a theme map a name to an image the app ships?** (`human-api`)
176
- Swift slots S2 allows an asset as well as an SF Symbol; `Theme(icons:)` holds
177
- SF Symbol names only.
181
+ None.
178
182
 
179
183
  ## Content boundary
180
184
 
@@ -33,9 +33,10 @@ public struct Icon: View {
33
33
 
34
34
  public var body: some View {
35
35
  if props.base.isHidden != true {
36
- if let symbol = Icon.symbol(for: props.icon, themeIcons: astryx.icons) {
36
+ if let source = Icon.symbol(for: props.icon, themeIcons: astryx.icons) {
37
37
  let side = Icon.points(for: resolvedSize) * astryx.textScale
38
- Image(systemName: symbol)
38
+ // An asset the app does not ship draws nothing (IconImage.image).
39
+ source.image?
39
40
  .resizable()
40
41
  .scaledToFit()
41
42
  .frame(width: side, height: side)
@@ -94,8 +95,8 @@ public struct Icon: View {
94
95
  /// The SF Symbol a name draws: the theme's mapping (which also registers a
95
96
  /// `<library>:<name>` name), else the platform default; `nil` for a name
96
97
  /// neither maps.
97
- nonisolated static func symbol(for name: IconName, themeIcons: [String: String]) -> String? {
98
- themeIcons[name.rawValue] ?? astryxDefaultIcons[name.rawValue]
98
+ nonisolated static func symbol(for name: IconName, themeIcons: [String: IconImage]) -> IconImage? {
99
+ themeIcons[name.rawValue] ?? astryxDefaultIcons[name.rawValue].map(IconImage.systemName)
99
100
  }
100
101
  }
101
102