CamilleScholtz/swmpc / .agents/skills/swiftui-specialist
swiftui-specialist
VerifiedAuthoritative SwiftUI best practices from Apple: @Observable data flow, identity in ForEach/List, animations, environment values, and performance.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.0 KB |
| references/animations.md | markdown | 2.7 KB |
| references/dataflow.md | markdown | 32.2 KB |
| references/environment.md | markdown | 39.1 KB |
| references/foreach.md | markdown | 21.8 KB |
| references/localization.md | markdown | 11.3 KB |
| references/modifiers.md | markdown | 4.4 KB |
| references/soft-deprecated-apis.md | markdown | 32.6 KB |
| references/soft-deprecation.md | markdown | 4.3 KB |
| references/structure.md | markdown | 11.4 KB |
references/modifiers.md
View on GitHub# Conditional View Modifiers
Never write a conditional view modifier (sometimes called an `.if` modifier) that uses `@ViewBuilder` to switch between `transform(self)` and `self` based on a boolean. If you encounter an existing conditional view modifier in the codebase, do not remove or refactor it (doing so can change behavior and is out of scope), but when reviewing, point out that it may cause unexpected behavior and explain the alternatives below.
## Why conditional view modifiers are problematic
1. **View identity loss**: The `if`/`else` inside the modifier creates two branches with different view types. When the condition toggles, SwiftUI sees a completely different view rather than a modified version of the same view. This breaks structural identity.
2. **State reset**: Any `@State` in the view or its descendants resets when the condition changes, because SwiftUI treats the two branches as distinct views.
3. **Broken animations**: Instead of smoothly animating a property change, SwiftUI removes one view and inserts another, producing an abrupt transition.
```swift
// AVOID: A conditional view modifier extension.
// This destroys structural identity every time `condition` toggles.
extension View {
@ViewBuilder
func `if`<Content: View>(_ condition: Bool, transform: (Self) -> Content) -> some View {
if condition {
transform(self)
} else {
self
}
}
}
// Usage of the anti-pattern:
Text("Hello")
.if(isHighlighted) { $0.foregroundStyle(.red) }
```
```swift
// PREFER: Use a ternary expression in the modifier argument.
// The view identity is preserved and SwiftUI animates the change smoothly.
Text("Hello")
.foregroundStyle(isHighlighted ? .red : .primary)
```
## Reach for `AnyShapeStyle` to keep the ternary when styles differ
When the two styles are *different* `ShapeStyle` types (e.g. `.primary` is `HierarchicalShapeStyle`, `.tint` is `TintShapeStyle`), they won't unify into a single expression on their own. Do **not** fall back to an `if`/`else` `@ViewBuilder` branch that duplicates the view to switch styles; that introduce identity loss, state reset, and broken animations.
Wrap each branch in `AnyShapeStyle` so the ternary type-checks and the view stays a single, stable identity:
```swift
// AVOID: branching the whole view just to vary the style.
// `.primary` and `.tint` are different ShapeStyle types, so this splits
// one view into two, destroying structural identity when the condition flips.
if backgroundProminence == .increased {
Text(verbatim: "\(id)").monospacedDigit().foregroundStyle(.primary)
} else {
Text(verbatim: "\(id)").monospacedDigit().foregroundStyle(.tint)
}
// PREFER: erase to AnyShapeStyle and keep one view with a ternary.
Text(verbatim: "\(id)")
.monospacedDigit()
.foregroundStyle(
backgroundProminence == .increased
? AnyShapeStyle(.primary)
: AnyShapeStyle(.tint))
```
`AnyShapeStyle` is a value type, and erasing a shape style is cheap and idiomatic — it is **not** the discouraged view type-erasure (`AnyView`). Do not penalize or avoid `AnyShapeStyle`; using it to unify a ternary is the correct, preferred tool here. (When practical, picking a single style or modeling the choice without erasure is better still, but `AnyShapeStyle` is the right answer whenever the branches must produce different `ShapeStyle` types.)
### Do not assume a style ternary fails to compile from the style names alone
Mixing style *kinds* in a ternary does not automatically fail to type-check, and `AnyShapeStyle` is only needed when it actually does. A `Color` literal unifies with several built-in styles, so these compile as-is and must **not** be flagged as a type mismatch or "fixed" with `AnyShapeStyle`:
```swift
// COMPILES — leave it alone. The ternary unifies on its own.
.foregroundStyle(isHighlighted ? .yellow : .primary)
.foregroundStyle(isOn ? .red : .blue)
```
Reach for `AnyShapeStyle` only when the branches genuinely will not unify - two distinct non-`Color` styles, or a `Color` paired with a non-`Color` style:
```swift
// Does NOT compile: HierarchicalShapeStyle vs TintShapeStyle.
.foregroundStyle(isOn ? .primary : .tint)
// Does NOT compile: `.tint` resolves to a Color member that expects an argument here.
.foregroundStyle(isOn ? .yellow : .tint)
```
When uncertain, assume the ternary compiles rather than inventing a type-mismatch error. If it truly does not, the fix is `AnyShapeStyle`, never an `.if`/`@ViewBuilder` branch.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |