Axiom Uikit
Developmentaxiom-uikitAxiom Uikit is an Agent Skill for development published in the CharlesWiltgen/Axiom repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when bridging UIKit and SwiftUI, modernizing UIKit apps (scene lifecycle, resizability), debugging Auto Layout, Combine, TextKit, PencilKit, or UIKit animations.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/CharlesWiltgen/Axiom/blob/HEAD/.claude-plugin/plugins/axiom/skills/axiom-uikit/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/axiom-uikit, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
UIKit & Bridging
You MUST use this skill for ANY UIKit bridging, Auto Layout, Combine, TextKit, or UIKit animation work.
Quick Reference
| Symptom / Task | Reference |
|---|---|
| UIViewRepresentable, UIViewControllerRepresentable | See skills/uikit-bridging.md |
| Embedding SwiftUI in UIKit (UIHostingController) | See skills/uikit-bridging.md |
| Coordinator pattern, updateUIView lifecycle | See skills/uikit-bridging.md |
| "Unable to simultaneously satisfy constraints" | See skills/auto-layout-debugging.md |
| Constraint conflicts, ambiguous layout | See skills/auto-layout-debugging.md |
| Views not appearing, positioned incorrectly | See skills/auto-layout-debugging.md |
| CAAnimation completion handler not firing | See skills/uikit-animation-debugging.md |
| Spring physics wrong on device, duration mismatch | See skills/uikit-animation-debugging.md |
| Animation jank, CATransaction timing | See skills/uikit-animation-debugging.md |
| Combine publishers, AnyCancellable lifecycle | See skills/combine-patterns.md |
| @Published properties, Combine ↔ async/await | See skills/combine-patterns.md |
| When to use Combine vs async/await | See skills/combine-patterns.md |
UIScene lifecycle required, resizable apps, size classes, tab sidebar OS27 | See skills/uikit-modernization.md |
| TextKit 2 architecture, NSTextLayoutManager | See skills/textkit-ref.md |
| Writing Tools integration (iOS 26) | See skills/textkit-ref.md |
Viewport rendering surfaces, attachment reuse, collapsible text OS27 | See skills/textkit-ref.md |
| SwiftUI TextEditor, TextKit 1 migration | See skills/textkit-ref.md |
| PencilKit canvas, PKToolPicker, drawing persistence | See skills/pencilkit-paperkit.md |
| Apple Pencil Pro (squeeze, barrel roll, hover, haptics) | See skills/pencilkit-paperkit.md |
Handwriting recognition (PKStrokeRecognizer), stroke identity/slicing OS27 | See skills/pencilkit-paperkit-ref.md |
| PaperKit markup canvas (shapes, images, text + drawing) | See skills/pencilkit-paperkit-ref.md |
PaperKit programmatic markup model (subelements, adornments) OS27 | See skills/pencilkit-paperkit-ref.md |
Decision Tree
digraph uikit {
start [label="UIKit task" shape=ellipse];
what [label="What do you need?" shape=diamond];
start -> what;
what -> "skills/uikit-bridging.md" [label="wrap UIKit in SwiftUI\nor SwiftUI in UIKit"];
what -> "skills/auto-layout-debugging.md" [label="constraint errors,\nlayout issues"];
what -> "skills/uikit-animation-debugging.md" [label="CAAnimation bugs,\nspring physics,\ncompletion handlers"];
what -> "skills/combine-patterns.md" [label="publishers, sinks,\n@Published,\nasync/await bridge"];
what -> "skills/textkit-ref.md" [label="text layout,\nWriting Tools,\nTextKit migration"];
what -> "skills/pencilkit-paperkit.md" [label="drawing canvas,\nApple Pencil,\nPaperKit markup"];
what -> "skills/uikit-modernization.md" [label="scene lifecycle (required 27),\nresizable apps,\nsize classes"];
}
- Scene-lifecycle migration, "app won't launch on 27", resizability, size classes, tab sidebar? →
skills/uikit-modernization.md - UIViewRepresentable / UIViewControllerRepresentable / UIHostingController? →
skills/uikit-bridging.md - "Unable to simultaneously satisfy constraints" / layout bugs? →
skills/auto-layout-debugging.md - CAAnimation completion missing / spring physics wrong / animation jank? →
skills/uikit-animation-debugging.md - Combine publishers / AnyCancellable / @Published / Combine ↔ async bridge? →
skills/combine-patterns.md - TextKit 2 / Writing Tools / TextEditor / TextKit 1 migration? →
skills/textkit-ref.md - PencilKit canvas / Apple Pencil / PaperKit markup? →
skills/pencilkit-paperkit.md - Pure SwiftUI view question (no UIKit bridging)? →
/skill axiom-swiftui - Design decisions, HIG, Liquid Glass, SF Symbols, typography? →
/skill axiom-design - Block retain cycles in UIKit callbacks? → See axiom-performance (
skills/objc-block-retain-cycles.md) - Memory leaks from Combine subscriptions? → Start with
skills/combine-patterns.md, then axiom-performance if leak persists
Conflict Resolution
uikit vs swiftui: When working with UI code:
- Use uikit when wrapping UIKit in SwiftUI or vice versa, or debugging UIKit-specific issues (Auto Layout, CAAnimation)
- Use swiftui for pure SwiftUI views, navigation, layout, animations
uikit vs concurrency: When Combine interacts with async/await:
- Use uikit (
skills/combine-patterns.md) for bridging Combine pipelines with async/await - Use concurrency for pure async/await patterns, actors, Sendable
uikit vs performance: When animations or layout cause performance issues:
- Try uikit FIRST — Most animation jank is CATransaction timing or layer state, not a profiling issue
- Only use performance if animation logic is correct but rendering is slow
uikit vs axiom-data: When @Published properties relate to data persistence:
- Use uikit for Combine publisher patterns and @Published lifecycle
- Use axiom-data for SwiftData/Core Data model layer concerns
Anti-Rationalization
| Thought | Reality |
|---|---|
| "I'll just use UIHostingController, it's simple" | Hosting has sizing, lifecycle, and navigation edge cases. skills/uikit-bridging.md covers the gotchas. |
| "Auto Layout error is just a warning, I'll ignore it" | Unsatisfied constraints cause unpredictable layout at runtime. Fix them now. |
| "I know how CAAnimation works" | 90% of CAAnimation bugs are CATransaction timing, not Core Animation. Check skills/uikit-animation-debugging.md. |
| "Combine is dead, just rewrite with async/await" | Combine has no deprecation notice. Rewriting working pipelines wastes time. skills/combine-patterns.md covers when to migrate vs maintain. |
| "TextKit 1 still works fine" | TextKit 1 misses Writing Tools integration and has known layout bugs Apple won't fix. See skills/textkit-ref.md. |
| "I'll store cancellables in a local variable" | Local AnyCancellable deallocates immediately, killing the subscription. |
| "I'll archive the PKCanvasView to save the drawing" | Archiving the view loses editability. Persist drawing.dataRepresentation(). See skills/pencilkit-paperkit.md. |
| "My tool picker won't show, the API must be broken" | The canvas must becomeFirstResponder() after setVisible(_:forFirstResponder:). See skills/pencilkit-paperkit.md. |
Example Invocations
User: "How do I wrap a UIKit view in SwiftUI?"
→ Read: skills/uikit-bridging.md
User: "I'm getting 'Unable to simultaneously satisfy constraints'"
→ Read: skills/auto-layout-debugging.md
User: "My CAAnimation completion handler never fires"
→ Read: skills/uikit-animation-debugging.md
User: "Should I use Combine or async/await for this?"
→ Read: skills/combine-patterns.md
User: "How do I integrate Writing Tools with my text editor?"
→ Read: skills/textkit-ref.md
User: "How do I add an Apple Pencil drawing canvas with the tool picker?"
→ Read: skills/pencilkit-paperkit.md
User: "How do I add a PaperKit markup canvas with shapes and text?"
→ Read: skills/pencilkit-paperkit-ref.md
User: "My SwiftUI view has a memory leak from a Combine subscription"
→ Read: skills/combine-patterns.md
User: "How do I embed SwiftUI in my UIKit app?"
→ Read: skills/uikit-bridging.md