| name | polish-and-refinement |
| description | Take a working app from "it works" to "it feels right." Covers Figma matching, Liquid Glass, animations, haptics, dark mode, and the subjective quality that separates a good app from a great one. Use this skill after all screens are built and data persistence is working. This is where Figma enters the workflow if you designed polished comps. |
Polish and Refinement
The app works. Data persists. Navigation flows. Now make it feel like YOUR app.
When to Use
- All screens are built and functional
- Data persistence is working
- You're ready to move from "works" to "feels great"
- You have Figma comps you want to match (optional)
The Polish Checklist
Work through these categories. Each one is a focused Claude Code session or Conductor workspace.
1. Color and Tinting
Apply the app's color system:
- Primary tint color: [hex] throughout the app
- Verify all interactive elements use the tint (buttons, links, toggles)
- Check that semantic colors (destructive red, success green) still
use system defaults
- Verify dark mode: tint should still be readable and vibrant
2. Liquid Glass (iOS 26)
Apply Liquid Glass material to:
- Navigation bars
- Tab bar
- [Any other chrome elements you want]
Do not apply Liquid Glass to:
- Content areas
- Cards or list rows
- Sheets (use system default presentation)
Use Sosumi MCP to look up the latest Liquid Glass APIs. These are new and evolving. Tell Claude Code:
Search Sosumi for "glassEffect" and "Liquid Glass" to get the
latest API documentation before implementing.
See references/liquid-glass.md for known patterns and the AvdLee SwiftUI Agent Skill repo for comprehensive Liquid Glass guidance.
Known gotchas:
.glassEffect() must be applied AFTER background modifiers, not before- System chrome (nav bars, tab bars) gets Liquid Glass automatically in iOS 26
- Do NOT manually apply
.glassEffect to system chrome (doubles the effect)
- Leave intensity and tinting at system defaults for v1
Glass-button label rules — read carefully before building any custom glass button:
-
NEVER apply .foregroundColor(.white) or .foregroundStyle(.white) to labels inside .glassProminent buttons. The system applies a vibrancy treatment that produces the correct tinted-white automatically; forcing .white overrides vibrancy and gives flat pure-white glyphs that look painted-on. The rule is specifically about WHITE — explicit Color.black for dark-mode legibility against pale-tint pills (see below) is a different and acceptable concern.
-
Tinted glass that's NOT a Button uses .glassEffect(.regular.tint(...).interactive(), in: Capsule()). The .interactive() modifier is what gives you the press-scale + bounce + shimmer that .glassProminent includes for free on Buttons. Without it the surface looks like flat tinted glass and feels dead.
-
For a glass button that needs a specific visible height (e.g. 44pt to match a sibling .glassProminent "Done" button), build the label manually instead of relying on SecondaryGlassButtonStyle-style wrappers. Style wrappers with internal minHeight: 32 + 8pt vertical padding compute their capsule around (label + padding) ≈ 33pt visible, which an outer .frame(height: 44) does NOT override — the outer frame just reserves space, the visible pill stays 33pt. Manual recipe:
Button { … } label: {
Text("Cancel")
.font(.subheadline.weight(.semibold))
.foregroundStyle(.primary)
.padding(.horizontal, 16)
.frame(height: 44)
.contentShape(Capsule())
.frostedGlass(in: Capsule())
}
.buttonStyle(.plain)
-
Dark mode + light pastel tints: the system's vibrancy can pick a tinted-white that is illegible on cream / pale-yellow / pale-orange pills. Override the label color in dark mode only; let light mode keep system vibrancy. Idiomatic SwiftUI:
Group {
if systemColorScheme == .dark {
Text("Continue").foregroundStyle(Color.black)
} else {
Text("Continue")
}
}
The Group { if/else } wrapper lets @ViewBuilder type-erase the two branches so you can attach .font() and .frame() once outside.
-
Even-distribution layout: Spacer(minLength: 0) between fixed-width slots beats HStack(spacing: …) for "icons spread across the bar's full width" patterns. Spacers absorb whatever residual width the bar has, so the first and last slots anchor to the bar's leading and trailing edges and the gaps between them stay equal regardless of bar width or device size.
3. Typography Hierarchy
Review typography across all screens:
- Screen titles should use .largeTitle or .title weight
- Section headers should use .headline
- Body content should use .body
- Secondary info should use .subheadline or .caption in .secondary color
- Numbers and counts should use .monospacedDigit to prevent layout shifting
4. Haptics
Add haptic feedback to:
- Destructive actions (context menu delete): .notification(.warning)
- Successful actions (project created, item saved): .notification(.success)
- Stitch counter tap: .impact(.medium)
- Toggle switches: already handled by native Toggle
- Pull to refresh: already handled by native .refreshable
5. Animations and Transitions
Verify default animations are smooth:
- Sheet presentations: system default (do not customize)
- Navigation pushes: system default (do not customize)
- List item appearance: use .animation with .default curve
- State changes (progress ring updating): animate with .spring
Do not add custom transition animations unless specifically requested.
System defaults are almost always better.
6. Empty States
Review every screen that displays a list:
- [ ] Projects home: empty state with illustration + CTA
- [ ] Explore: search with no results message
- [ ] [Other list screens]
Empty states should feel intentional, not like a bug. Center the
content vertically, use .secondary text color, and include a clear
action button if the user can do something about it.
7. Loading States
Add loading indicators where data takes time:
- Initial data fetch: ProgressView centered
- Image loading: placeholder with ProgressView overlay
- Save operations: disable the save button, show spinner
Use native ProgressView for everything. No custom spinners.
8. Error States
Handle common errors gracefully:
- Network failure (if applicable): retry button
- Save failure: alert with error message
- Delete failure: alert with error message
- Data corruption: graceful fallback, don't crash
9. Dark Mode
Run every screen in dark mode (Shift+Cmd+A in simulator):
10. Dynamic Type
Test with large accessibility font sizes (Settings > Accessibility > Larger Text in simulator):
Figma Matching (Optional Phase)
If you designed polished screens in Figma, this is where they enter:
Match [Screen Name] to this Figma frame: [URL/node ID].
The screen already works. Adjust only visual presentation:
spacing, typography weight, hierarchy, and accent color.
Do not change functionality or replace native components.
See the figma-to-code skill for detailed guidance on this workflow.
Anti-Patterns
| Temptation | Why It Fails |
|---|
| Polishing before the app works | You'll polish screens that get rebuilt during development |
| Custom animation curves for everything | Inconsistent with iOS. System animations feel more native |
| Overriding system dark mode colors | Apple's semantic colors are carefully tuned. Trust them |
| Adding decorative elements (shadows, gradients) that iOS doesn't use | Your app should feel like an iOS app, not a Dribbble shot |
| Spending hours on Liquid Glass intensity values | Ship with reasonable defaults. Tune in a future update |
Verification
The best test is the "hand it to someone" test:
- Install on a real device (not simulator)
- Hand it to someone who has never seen the app
- Watch them use it without guidance
- Note where they hesitate, get confused, or something feels off
- Those notes become your final polish list
Time Estimate
4-6 hours total, spread across multiple focused sessions.
