Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(native): a Swift theme maps an icon to an SF Symbol or an app asset (AST-082 FR17) (#8343)

Cindy Zhangd70e0ec01372
diff --git a/packages/native/apple/Package.swift b/packages/native/apple/Package.swift
index efe82b00f9..ebb6cc5238 100644
--- a/packages/native/apple/Package.swift
+++ b/packages/native/apple/Package.swift
@@ -32,6 +32,10 @@ let package = Package(
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")]
+ ),
]
)
diff --git a/packages/native/apple/README.md b/packages/native/apple/README.md
index 1bb257a681..9395b3e669 100644
--- a/packages/native/apple/README.md
+++ b/packages/native/apple/README.md
@@ -107,8 +107,11 @@ typed members comes next.
`Icon(.search)` draws a shared icon name as the platform's SF Symbol, at
core's icon size and color, hidden from VoiceOver unless it has a `label`.
`IconName` holds every built-in name as a static member; a theme maps a name
-to another symbol, or registers a `<library>:<name>` name, with
-`Theme(…, icons: ["acme:rocket": "airplane"])`.
+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
diff --git a/packages/native/apple/Sources/Astryx/Banner/Banner.swift b/packages/native/apple/Sources/Astryx/Banner/Banner.swift
index 2c5d00388e..c780b797d6 100644
--- a/packages/native/apple/Sources/Astryx/Banner/Banner.swift
+++ b/packages/native/apple/Sources/Astryx/Banner/Banner.swift
@@ -49,9 +49,9 @@ public struct Banner: 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)
diff --git a/packages/native/apple/Sources/Astryx/Button/Button.swift b/packages/native/apple/Sources/Astryx/Button/Button.swift
index 938ec00954..4b0429893c 100644
--- a/packages/native/apple/Sources/Astryx/Button/Button.swift
+++ b/packages/native/apple/Sources/Astryx/Button/Button.swift
@@ -70,8 +70,9 @@ public struct Button: View {
// 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))
}
SwiftUI.Text(label).lineLimit(1)
}
diff --git a/packages/native/apple/Sources/Astryx/Icon/Icon.spec.md b/packages/native/apple/Sources/Astryx/Icon/Icon.spec.md
index 4ab0649d7a..d3cadcf92e 100644
--- a/packages/native/apple/Sources/Astryx/Icon/Icon.spec.md
+++ b/packages/native/apple/Sources/Astryx/Icon/Icon.spec.md
@@ -32,21 +32,22 @@ system_specs: [spec:AST-082, spec:AST-093]
## 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 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. |
-| 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. |
-| 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/`. |
+| 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, so an
+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.
@@ -63,10 +64,12 @@ Consumer migration instructions belong in consumer docs and release notes.
**Owns**
-- Resolving a shared icon name to an SF Symbol: the theme's mapping, else the
- platform default.
-- Drawing the symbol in a square box at core's icon size, grown with Dynamic
- Type, in core's icon color token.
+- 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**
@@ -80,27 +83,28 @@ Consumer migration instructions belong in consumer docs and release notes.
## 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 name | 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` |
+| 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 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 |
-| 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 |
+| 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 symbol is the platform's SF Symbol, not the web's
- SVG; a theme may map any name to another SF Symbol.
+- **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
@@ -114,14 +118,16 @@ Consumer migration instructions belong in consumer docs and release notes.
### Transformation and precedence order
-- **ORD1 — Symbol.** Theme mapping → platform default → nothing.
+- **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 loading.** The view draws a system symbol by name and holds
- no image data of its own.
+- **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
@@ -134,14 +140,14 @@ Consumer migration instructions belong in consumer docs and release notes.
## Design relationships
-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
-| ---------------- | --------------------------------------------- | -------------------------- | -------------- | ------------------ |
-| Glyph | SF Symbols (Apple Human Interface Guidelines) | prescribed by the platform | supporting | FR1, FR2 |
+| 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:)`. It is the platform's own icon
-view and satisfies the contract, so no custom drawing is needed (`spec:AST-093`
+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.
@@ -158,13 +164,13 @@ Theme values read: `color.iconPrimary`, `color.iconSecondary`,
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| -------- | ----------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- | -------------------------- |
-| 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` |
-| 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` |
+| 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
@@ -172,9 +178,7 @@ No component-local decision is recorded.
## Open questions
-- **OQ1 — Can a theme map a name to an image the app ships?** (`human-api`)
- Swift slots S2 allows an asset as well as an SF Symbol; `Theme(icons:)` holds
- SF Symbol names only.
+None.
## Content boundary
diff --git a/packages/native/apple/Sources/Astryx/Icon/Icon.swift b/packages/native/apple/Sources/Astryx/Icon/Icon.swift
index a3a231e590..463efa3a05 100644
--- a/packages/native/apple/Sources/Astryx/Icon/Icon.swift
+++ b/packages/native/apple/Sources/Astryx/Icon/Icon.swift
@@ -33,9 +33,10 @@ public struct Icon: View {
public var body: some View {
if props.base.isHidden != true {
- if let symbol = Icon.symbol(for: props.icon, themeIcons: astryx.icons) {
+ if let source = Icon.symbol(for: props.icon, themeIcons: astryx.icons) {
let side = Icon.points(for: resolvedSize) * astryx.textScale
- Image(systemName: symbol)
+ // An asset the app does not ship draws nothing (IconImage.image).
+ source.image?
.resizable()
.scaledToFit()
.frame(width: side, height: side)
@@ -94,8 +95,8 @@ public struct Icon: View {
/// The SF Symbol a name draws: the theme's mapping (which also registers a
/// `<library>:<name>` name), else the platform default; `nil` for a name
/// neither maps.
- nonisolated static func symbol(for name: IconName, themeIcons: [String: String]) -> String? {
- themeIcons[name.rawValue] ?? astryxDefaultIcons[name.rawValue]
+ nonisolated static func symbol(for name: IconName, themeIcons: [String: IconImage]) -> IconImage? {
+ themeIcons[name.rawValue] ?? astryxDefaultIcons[name.rawValue].map(IconImage.systemName)
}
}
diff --git a/packages/native/apple/Sources/Astryx/Theme/AstryxIcons.swift b/packages/native/apple/Sources/Astryx/Theme/AstryxIcons.swift
index ef1cc7210d..1d72a0225c 100644
--- a/packages/native/apple/Sources/Astryx/Theme/AstryxIcons.swift
+++ b/packages/native/apple/Sources/Astryx/Theme/AstryxIcons.swift
@@ -1,9 +1,80 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+import SwiftUI
+#if canImport(UIKit)
+import UIKit
+#elseif canImport(AppKit)
+import AppKit
+#endif
+
+/// The image a shared icon name draws on Apple platforms (AST-082 FR17): an SF
+/// Symbol, or an image the app ships in its asset catalog. A string literal is
+/// an SF Symbol name, so `["success": "checkmark.seal.fill"]` maps a symbol.
+public enum IconImage: Equatable, Hashable, Sendable, ExpressibleByStringLiteral {
+ /// An SF Symbol, by its system name.
+ case systemName(String)
+ /// An image in the app's main bundle asset catalog, by its asset name.
+ case assetName(String)
+
+ public init(stringLiteral value: String) {
+ self = .systemName(value)
+ }
+
+ /// The image to draw. An asset the app does not ship stops a development
+ /// build with a message that names the asset, and draws nothing in a release
+ /// build, as an unknown icon name does (AST-082 FR17). An asset draws as its
+ /// asset catalog renders it: a template image takes the icon's color, an
+ /// original image keeps its own colors.
+ public var image: Image? { image(in: .main) }
+
+ /// The image from `bundle`: the app's main bundle in an app, a test bundle
+ /// in tests. A missing asset is reported through `reportMissing`, which
+ /// stops a development build (`assertionFailure` does nothing in a release
+ /// build), and the image is nil, so nothing draws.
+ func image(
+ in bundle: Bundle,
+ reportMissing: (String) -> Void = { assertionFailure("Astryx: an icon maps to the asset \"\($0)\", which the app does not ship") }
+ ) -> Image? {
+ switch self {
+ case .systemName(let name):
+ return Image(systemName: name)
+ case .assetName(let name):
+ guard astryxAppShipsAsset(name, in: bundle) else {
+ reportMissing(name)
+ return nil
+ }
+ return Image(name, bundle: bundle)
+ }
+ }
+
+ /// The icon at a text size. An SF Symbol scales with the font the caller
+ /// applies; an asset, which has no font size, fits a square `side` points
+ /// wide, the same text-relative size, grown with Dynamic Type.
+ @ViewBuilder func sized(_ side: CGFloat, in bundle: Bundle = .main) -> some View {
+ if let image = image(in: bundle) {
+ switch self {
+ case .systemName: image
+ case .assetName: image.resizable().scaledToFit().frame(width: side, height: side)
+ }
+ }
+ }
+}
+
+/// Whether `bundle` has an image asset with this name.
+func astryxAppShipsAsset(_ name: String, in bundle: Bundle = .main) -> Bool {
+ #if canImport(UIKit)
+ UIImage(named: name, in: bundle, with: nil) != nil
+ #elseif canImport(AppKit)
+ bundle.image(forResource: name) != nil
+ #else
+ false
+ #endif
+}
+
/// The SF Symbol each of Astryx's built-in icon names draws by default on
/// Apple platforms (AST-082 FR17). A test keeps this map equal to
/// `NATIVE_ICON_DEFAULTS` in `@astryxdesign/native`; a theme replaces any
-/// entry through `Theme(icons:)`.
+/// entry through `Theme(icons:)`, with an SF Symbol or an app asset.
let astryxDefaultIcons: [String: String] = [
"close": "xmark",
"chevronDown": "chevron.down",
diff --git a/packages/native/apple/Sources/Astryx/Theme/Theme.swift b/packages/native/apple/Sources/Astryx/Theme/Theme.swift
index f68578720b..5c172844cf 100644
--- a/packages/native/apple/Sources/Astryx/Theme/Theme.swift
+++ b/packages/native/apple/Sources/Astryx/Theme/Theme.swift
@@ -16,14 +16,16 @@ import AppKit
public struct Theme: Equatable, Sendable {
public var light: Tokens
public var dark: Tokens
- /// SF Symbols that replace the defaults for shared icon names, such as
- /// `["success": "checkmark.seal.fill"]` (AST-082 FR17).
- public var icons: [String: String]
+ /// Images that replace the defaults for shared icon names, or register a
+ /// `<library>:<name>` name (AST-082 FR17): an SF Symbol, such as
+ /// `["success": "checkmark.seal.fill"]`, or an app asset, such as
+ /// `["close": .assetName("brand.close")]`.
+ public var icons: [String: IconImage]
/// Native visual intent from `defineNativeTheme`. Reserved: empty until a
/// component reads it.
public var native: NativeIntent
- public init(light: Tokens, dark: Tokens, icons: [String: String] = [:], native: NativeIntent = .init()) {
+ public init(light: Tokens, dark: Tokens, icons: [String: IconImage] = [:], native: NativeIntent = .init()) {
self.light = light
self.dark = dark
self.icons = icons
@@ -48,12 +50,12 @@ public struct AstryxStyle: Sendable {
/// How much Dynamic Type grows text at the person's setting (1 at Large).
public let textScale: CGFloat
/// The theme's replacements for shared icon names.
- public let icons: [String: String]
+ public let icons: [String: IconImage]
/// Whether the person turned on Bold Text (`legibilityWeight == .bold`).
public let isBoldText: Bool
public init(
- tokens: Tokens, textScale: CGFloat = 1, icons: [String: String] = [:], isBoldText: Bool = false
+ tokens: Tokens, textScale: CGFloat = 1, icons: [String: IconImage] = [:], isBoldText: Bool = false
) {
self.tokens = tokens
self.textScale = textScale
@@ -101,11 +103,12 @@ public struct AstryxStyle: Sendable {
)
}
- /// The SF Symbol for a shared icon name (AST-082 FR17): the theme's
- /// replacement, else the default. An unknown name stops a development
- /// build with a message that names it, and draws nothing in a release build.
- public func icon(_ name: String) -> String? {
- if let symbol = icons[name] ?? astryxDefaultIcons[name] { return symbol }
+ /// The image for a shared icon name (AST-082 FR17): the theme's
+ /// replacement, else the default SF Symbol. An unknown name stops a
+ /// development build with a message that names it, and draws nothing in a
+ /// release build.
+ public func icon(_ name: String) -> IconImage? {
+ if let image = icons[name] ?? astryxDefaultIcons[name].map(IconImage.systemName) { return image }
assertionFailure("Astryx has no icon named \"\(name)\"")
return nil
}
diff --git a/packages/native/apple/Tests/AstryxTests/IconTests.swift b/packages/native/apple/Tests/AstryxTests/IconTests.swift
index 2ebff77dac..7423ff2956 100644
--- a/packages/native/apple/Tests/AstryxTests/IconTests.swift
+++ b/packages/native/apple/Tests/AstryxTests/IconTests.swift
@@ -16,9 +16,9 @@ import AppKit
@Test func everyBuiltInNameDrawsASymbolThePlatformHas() {
#expect(IconName.builtIn.count == astryxDefaultIcons.count)
for name in IconName.builtIn {
- let symbol = Icon.symbol(for: name, themeIcons: [:])
- #expect(symbol != nil, "no symbol for \(name.rawValue)")
- if let symbol {
+ let image = Icon.symbol(for: name, themeIcons: [:])
+ #expect(image != nil, "no symbol for \(name.rawValue)")
+ if case .systemName(let symbol) = image {
#if canImport(UIKit)
#expect(UIImage(systemName: symbol) != nil, "\(symbol) is not an SF Symbol here")
#elseif canImport(AppKit)
@@ -36,6 +36,52 @@ import AppKit
#expect(Icon.symbol(for: "acme:rocket", themeIcons: [:]) == nil)
}
+// AST-082 FR17 and Swift slots S2: a theme maps a name to an SF Symbol or to
+// an image the app ships; a string literal is an SF Symbol name.
+
+@Test func aThemeMapsANameToAnAppAsset() {
+ let icons: [String: IconImage] = ["close": .assetName("brand.close"), "search": "sparkle.magnifyingglass"]
+ #expect(Icon.symbol(for: .close, themeIcons: icons) == .assetName("brand.close"))
+ #expect(Icon.symbol(for: .search, themeIcons: icons) == .systemName("sparkle.magnifyingglass"))
+ let theme = Theme(light: Theme.default.light, dark: Theme.default.dark, icons: icons)
+ #expect(AstryxStyle(tokens: theme.light, icons: theme.icons).icon("close") == .assetName("brand.close"))
+}
+
+@Test func aStringLiteralIsAnSFSymbolName() {
+ let image: IconImage = "xmark"
+ #expect(image == .systemName("xmark"))
+ #expect(IconImage.systemName("xmark").image != nil)
+}
+
+@Test func aShippedAssetIsFoundAndAMissingOneIsNot() {
+ // The test bundle stands in for the app's main bundle. IconImage.image stops
+ // a development build for a missing asset, so a missing asset is checked
+ // through the lookup it relies on instead of by drawing.
+ #expect(astryxAppShipsAsset("astryx-test-icon", in: .module))
+ #expect(IconImage.assetName("astryx-test-icon").image(in: .module) != nil)
+ #expect(astryxAppShipsAsset("astryx.test.no-such-asset", in: .module) == false)
+}
+
+@Test func aMissingAssetDrawsNothingAndIsReported() {
+ // As a release build sees it: the report does not stop the run, and the
+ // image is nil, so the icon draws nothing. A development build's report is
+ // assertionFailure, which stops it with the asset's name.
+ var reported: [String] = []
+ let image = IconImage.assetName("astryx.test.no-such-asset").image(in: .module) { reported.append($0) }
+ #expect(image == nil)
+ #expect(reported == ["astryx.test.no-such-asset"])
+}
+
+@MainActor
+@Test func anAssetIconTakesTheTextRelativeSizeASymbolGets() {
+ let asset = IconImage.assetName("astryx-test-icon")
+ let small = Pixels(asset.sized(14, in: .module).fixedSize())
+ let large = Pixels(asset.sized(28, in: .module).fixedSize())
+ #expect(small.width > 0)
+ #expect(large.width == small.width * 2)
+ #expect(large.height == large.width)
+}
+
@Test func iconNamesAreStringsOnTheWire() throws {
let encoded = try JSONEncoder().encode([IconName.chevronDown, "acme:rocket"])
#expect(String(decoding: encoded, as: UTF8.self) == #"["chevronDown","acme:rocket"]"#)
diff --git a/packages/native/apple/Tests/AstryxTests/Resources/astryx-test-icon.png b/packages/native/apple/Tests/AstryxTests/Resources/astryx-test-icon.png
new file mode 100644
index 0000000000..5bc9e562a5
Binary files /dev/null and b/packages/native/apple/Tests/AstryxTests/Resources/astryx-test-icon.png differ
diff --git a/packages/native/specs/swift/library/slots.md b/packages/native/specs/swift/library/slots.md
index dfc59cff2a..1a88b16b89 100644
--- a/packages/native/specs/swift/library/slots.md
+++ b/packages/native/specs/swift/library/slots.md
@@ -38,10 +38,13 @@ places as on the web, read by VoiceOver in the same order.
static member (`.search`, `.close`), generated from AST-082 FR17's shared
icon names, read at build time through the icon-names read AST-082 FR16 lists
(later through core's portable entry), never from core's web icon registry. A
- namespaced name (`"acme:rocket"`) is valid once the app registers it in code
- with the image to draw (an SF Symbol name or an asset). An unknown name
- stops a development build with a message naming it, and draws nothing in a
- release build, never a substitute.
+ namespaced name (`"acme:rocket"`) is valid once the theme maps it to an
+ image. `Theme(icons:)` maps a shared or namespaced name to an `IconImage`:
+ `.systemName(_:)` for an SF Symbol, or `.assetName(_:)` for an image in the
+ app's asset catalog, as AST-082 FR17 names a native icon by `systemName` or
+ `assetName`; a string literal is an SF Symbol name. An unknown name, or an
+ asset the app does not ship, stops a development build with a message
+ naming it, and draws nothing in a release build, never a substitute.
- **S3 — Content slots are open, the SwiftUI way.** A content slot is a generic
`@ViewBuilder` closure parameter named as the core prop
(`startContent: () -> StartContent` where `StartContent: View`), as in
diff --git a/packages/native/specs/swift/library/theme-generator.md b/packages/native/specs/swift/library/theme-generator.md
index e5a638266f..2451a7303d 100644
--- a/packages/native/specs/swift/library/theme-generator.md
+++ b/packages/native/specs/swift/library/theme-generator.md
@@ -180,7 +180,9 @@ re-implements theme logic.
portable theme. When the first component reads `material`, the generator
takes the native theme, reads the wrapped portable theme from it, and fills
`Theme.native` already resolved per OS version range, so one call
- produces one file. Composing native intent inside `defineTheme` is outside
+ produces one file. A platform entry's icons (`{systemName}` or
+ `{assetName}`, AST-082 FR17) become `Theme.icons` entries of
+ `.systemName(_:)` or `.assetName(_:)`. Composing native intent inside `defineTheme` is outside
this spec.
- **D4 — Increase Contrast is outside this spec.** Core themes have light and