Swift development skill
This skill guides AI agents and contributors working in the swift/ directory. It outlines target
boundaries, coding standards, testing patterns, and mandatory verification steps.
1. Specification and blueprint grounding
Before modifying or implementing Swift code, inspect the authoritative specifications:
- Protocol envelopes and schemas:
specification/v0_9_1/json/ defines wire-format types
and validation schemas.
- Component catalog schema:
basic/catalog.json defines
components, properties, and function signatures.
- Core module blueprint:
a2ui_core.blueprint.md specifies state
handling, JSON pointer rules, auto-vivification, and error semantics.
- Framework adapter blueprint:
a2ui_framework_adapter.blueprint.md specifies view mapping,
reactive subscription lifecycles, and layout behavior.
- Reference implementation:
renderers/web_core/ serves as
the canonical behavioral reference for edge-case resolution.
2. Swift target architecture
The Swift implementation uses targets defined in root Package.swift:
A2UIJSON (core/Sources/A2UIJSON): Pure
JSON Schema 2020-12 definitions and remote schema registry storage.
A2UICore (core/Sources/A2UICore): Stateful
runtime engine managing MessageProcessor, DataModel, SurfaceGroupModel, pointer evaluation,
and action routing.
BasicCatalog (core/Sources/BasicCatalog):
Core schema definitions and function handlers for Basic Catalog components.
A2UISwiftUI (swiftui/Sources/A2UISwiftUI):
SwiftUI adapter providing the root Surface view, recursive ComponentNodeView, and
environment keys.
BasicCatalogSwiftUI
(swiftui/Sources/BasicCatalog): Concrete
SwiftUI view implementations conforming to ComponentImplementation.
A2UISampleClient (swift/sample): Interactive iOS Gallery
application managed via Xcode project file.
3. Mandatory coding standards
All Swift code must strictly follow
swift/CODING_STANDARDS.md and the Google Swift Style Guide:
- One primary type per file: Every class, struct, enum, and protocol must live in a dedicated
file named after the type.
- 100-character line limit: No line of code, comment, docstring, or markdown may exceed 100
characters.
- 2-space indentation: Enforced by
swift-format.
- Apache 2.0 copyright header: Required on every new
.swift file:// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
- Safe optional handling: Never use force-unwrapping (
!) or forced tries (try!). Use
optional bindings (if let, guard let) or propagate throwing errors.
4. Swift Testing conventions
Tests use the native Swift Testing framework:
- Import
Testing instead of XCTest.
- Annotate test functions with
@Test.
- Use
#expect(...) for assertions.
- In tests, replace force unwraps with
try #require(...) to produce clean test failures instead of
crashes.
- Avoid
@testable import. Test only the public API surface.
- Use standard camelCase identifiers for test function names without backticks or spaces.
5. Verification workflow
After making any code changes in swift/, run this verification sequence from the repository root:
- Auto-format code:
swift-format format -i -r Package.swift swift/
- Lint check:
swift-format lint -r Package.swift swift/
- Run unit tests:
swift test
Or run filtered tests during iterative development:swift test --filter A2UICoreTests
swift test --filter A2UISwiftUITests
- Compile check:
swift build
6. Integration with repository skills
1---2name: a2ui-swift-development3description: >-4 Grounding, coding standards, testing practices, and verification workflows for developing in the5 A2UI Swift codebase (under the swift/ directory). Use whenever implementing features, modifying6 state logic, creating SwiftUI views, or writing tests in Swift.7metadata:8 source: https://skillmd.com/skills/google/a2ui-swift-development9---1011# Swift development skill1213This skill guides AI agents and contributors working in the `swift/` directory. It outlines target14boundaries, coding standards, testing patterns, and mandatory verification steps.1516---1718## 1. Specification and blueprint grounding1920Before modifying or implementing Swift code, inspect the authoritative specifications:2122- **Protocol envelopes and schemas**:23 [`specification/v0_9_1/json/`](../../../specification/v0_9_1/json/) defines wire-format types24 and validation schemas.25- **Component catalog schema**:26 [`basic/catalog.json`](../../../specification/v0_9_1/catalogs/basic/catalog.json) defines27 components, properties, and function signatures.28- **Core module blueprint**:29 [`a2ui_core.blueprint.md`](../../../blueprints/modules/a2ui_core.blueprint.md) specifies state30 handling, JSON pointer rules, auto-vivification, and error semantics.31- **Framework adapter blueprint**:32 [`a2ui_framework_adapter.blueprint.md`][framework-adapter-blueprint] specifies view mapping,33 reactive subscription lifecycles, and layout behavior.34- **Reference implementation**: [`renderers/web_core/`](../../../renderers/web_core/) serves as35 the canonical behavioral reference for edge-case resolution.3637[framework-adapter-blueprint]: ../../../blueprints/modules/a2ui_framework_adapter.blueprint.md3839---4041## 2. Swift target architecture4243The Swift implementation uses targets defined in root [`Package.swift`](../../../Package.swift):4445- **`A2UIJSON`** ([`core/Sources/A2UIJSON`](../../../swift/core/Sources/A2UIJSON)): Pure46 JSON Schema 2020-12 definitions and remote schema registry storage.47- **`A2UICore`** ([`core/Sources/A2UICore`](../../../swift/core/Sources/A2UICore)): Stateful48 runtime engine managing `MessageProcessor`, `DataModel`, `SurfaceGroupModel`, pointer evaluation,49 and action routing.50- **`BasicCatalog`** ([`core/Sources/BasicCatalog`](../../../swift/core/Sources/BasicCatalog)):51 Core schema definitions and function handlers for Basic Catalog components.52- **`A2UISwiftUI`** ([`swiftui/Sources/A2UISwiftUI`](../../../swift/swiftui/Sources/A2UISwiftUI)):53 SwiftUI adapter providing the root `Surface` view, recursive `ComponentNodeView`, and54 environment keys.55- **`BasicCatalogSwiftUI`**56 ([`swiftui/Sources/BasicCatalog`](../../../swift/swiftui/Sources/BasicCatalog)): Concrete57 SwiftUI view implementations conforming to `ComponentImplementation`.58- **`A2UISampleClient`** ([`swift/sample`](../../../swift/sample)): Interactive iOS Gallery59 application managed via Xcode project file.6061---6263## 3. Mandatory coding standards6465All Swift code must strictly follow66[`swift/CODING_STANDARDS.md`](../../../swift/CODING_STANDARDS.md) and the Google Swift Style Guide:67681. **One primary type per file**: Every class, struct, enum, and protocol must live in a dedicated69 file named after the type.702. **100-character line limit**: No line of code, comment, docstring, or markdown may exceed 10071 characters.723. **2-space indentation**: Enforced by `swift-format`.734. **Apache 2.0 copyright header**: Required on every new `.swift` file:74 ```swift75 // Copyright 2024 Google LLC76 //77 // Licensed under the Apache License, Version 2.0 (the "License");78 // you may not use this file except in compliance with the License.79 // You may obtain a copy of the License at80 //81 // https://www.apache.org/licenses/LICENSE-2.082 //83 // Unless required by applicable law or agreed to in writing, software84 // distributed under the License is distributed on an "AS IS" BASIS,85 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.86 // See the License for the specific language governing permissions and87 // limitations under the License.88 ```895. **Safe optional handling**: Never use force-unwrapping (`!`) or forced tries (`try!`). Use90 optional bindings (`if let`, `guard let`) or propagate throwing errors.9192---9394## 4. Swift Testing conventions9596Tests use the native Swift Testing framework:9798- Import `Testing` instead of `XCTest`.99- Annotate test functions with `@Test`.100- Use `#expect(...)` for assertions.101- In tests, replace force unwraps with `try #require(...)` to produce clean test failures instead of102 crashes.103- Avoid `@testable import`. Test only the public API surface.104- Use standard camelCase identifiers for test function names without backticks or spaces.105106---107108## 5. Verification workflow109110After making any code changes in `swift/`, run this verification sequence from the repository root:1111121. **Auto-format code**:113 ```bash114 swift-format format -i -r Package.swift swift/115 ```1162. **Lint check**:117 ```bash118 swift-format lint -r Package.swift swift/119 ```1203. **Run unit tests**:121 ```bash122 swift test123 ```124 Or run filtered tests during iterative development:125 ```bash126 swift test --filter A2UICoreTests127 swift test --filter A2UISwiftUITests128 ```1294. **Compile check**:130 ```bash131 swift build132 ```133134---135136## 6. Integration with repository skills137138- **Blueprint compliance**: When updating models or schemas, check compliance with139 [`a2ui-blueprint-compliance`](../../../blueprints/skills/a2ui-blueprint-compliance/SKILL.md).140- **Test quality**: Verify assertion strength and boundary cases with141 [`a2ui-test-quality-check`](../a2ui-test-quality-check/SKILL.md).142- **Documentation sync**: Ensure documentation reflects code changes using143 [`a2ui-doc-sync-check`](../a2ui-doc-sync-check/SKILL.md).