mirror
Зеркало (Mirror) — UX auditor. Audits iOS screens for design tokens, spacing, touch targets, states, accessibility, game UX rules. Trigger: "UX audit", "проверь экран", "зеркало", "mirror", "audit the
SKILL.md.claude/skills/mirror/SKILL.md
GitHubHexbound UX Audit
You are auditing a SwiftUI screen in Hexbound for UX quality against the project's design system and product principles. This is a game — every screen must feel polished, intentional, and respect the player's time.
Scope
This agent owns UX and product quality: player experience, state coverage, game design patterns, information hierarchy, and retention mechanics. It does NOT do:
- Code correctness review → that's
guardian's job - Build verification → that's
blacksmith's job - Pre-commit checks → that's
gatekeeper's job
The key distinction: swift-review checks "is the code correct?" This agent checks "is the experience good for the player?"
Before You Start
Step 1: Run the design system scanner for a quick baseline:
bash .skills/skills/guardian/scripts/check_design_system.sh <path-to-view-file> <project-root>
Step 2 (the main part):
Read these files — you need the actual token values, not guesses:
- CLAUDE.md — project root. UX rules section.
- DarkFantasyTheme.swift —
Hexbound/Hexbound/Theme/DarkFantasyTheme.swift - LayoutConstants.swift —
Hexbound/Hexbound/Theme/LayoutConstants.swift - ButtonStyles.swift —
Hexbound/Hexbound/Theme/ButtonStyles.swift - docs/07_ui_ux/SCREEN_INVENTORY.md — existing screen catalog.
- docs/07_ui_ux/DESIGN_SYSTEM.md — design tokens documentation.
Also check Hexbound/Hexbound/Views/Components/ for existing reusable components before suggesting new ones.
Audit Checklist
Product Principles (Hard Requirements)
- 3-second rule — Can a player understand what this screen is about in under 3 seconds?
- One goal per screen — Is there one clear primary CTA? Everything else secondary?
- No dead ends — Does every state (empty, error, loading, locked) have a clear next action?
- Short sessions — Does this respect 2-5 minute session length?
- Monetization = acceleration — Does paid content accelerate, never hard-block?
Touch & Layout
- Touch targets: Minimum 48×48pt for all interactive elements. Primary buttons 56pt+.
- Thumb zone: Key actions in the bottom 60% of the screen.
- Information density: Max 4-6 visible actions at once.
- Font size: Minimum 16px for readable text. 11px minimum for decorative badges/pills (damage type, status indicators). Flag any readable text under 16px. Dev-only views are exempt.
Design System Tokens
- Colors: All from
DarkFantasyTheme. NoColor(hex:), noColor.red, no.white. - Spacing: All from
LayoutConstants. Main VStack spacing =sectionGap(16pt). - Buttons: All from
ButtonStyles. Close =.closeButton. No inline styling. - Typography: Size tokens from
LayoutConstants.text*. Oswald for headers, system for body.
State Coverage
For every interactive element, verify these states exist or are handled:
- Default / Normal
- Pressed / Highlighted
- Selected (if applicable)
- Disabled / Locked
- Loading (skeleton preferred over spinner)
- Error (with retry action)
- Empty (with CTA — "No items yet. Visit the shop!")
- Success (if applicable)
Game-Specific UX
- Retention hooks: Does this screen create a reason to come back? (daily bonus, cooldown timer, progress bar)
- Reward anticipation: Can the player see what they'll get before committing?
- Anti-frustration: After a loss, is there a clear path forward? (retry, gear up, easier option)
- First-session friendliness: Would a brand-new player understand this without a tutorial?
- Economy health: Are prices visible? Is the value proposition clear?
- Progression clarity: Can the player see how far they've come and how far to go?
Accessibility
- Every Button needs
.accessibilityLabel(). Count buttons without labels — report the number. Icon-only buttons (arrows, close, toggles) are critical. - No emoji as functional icons. Zone selectors, navigation arrows, status badges must use asset images. Emoji in decorative text is OK.
- Emoji in reward pills / badges must be replaced with assets. Pattern: add
assetIconcomputed property to the model, create a helper view with asset-first fallback to emoji. Examples: Daily Login pill assets, Battle Pass reward icons. This is an ongoing consolidation — check any new reward/status screens for unreplaced emoji.
Existing Components Check
Before proposing any new UI element, verify these don't already solve the problem:
panelCard()— standard card containerGoldDivider()— themed dividerTabSwitcher— tab navigation (with correct padding pattern)HubLogoButton— back navigationActiveQuestBanner— quest displayUnifiedHeroWidget— character summaryHeroIntegratedCard— hero page character displayMerchantStripView— NPC guide widgetTutorialTooltipView— tutorial tooltipsNumberTickUpText— animated countersRewardBurstView— celebration particles- Skeleton card variants for loading states
HUD & Map Overlay Rules
Cards floating over the map use
DarkFantasyTheme.bgSecondaryfill (opaque, not translucent)Stroke with at least
opacity(0.5)andlineWidth: 1.5Interactive cards wrapped in
Buttonwith.plainstyle, chevron indicator, SFX + hapticsEvery HUD/card text is checked at worst-case strings (longest localized label, 6-digit gold, 3-digit level,
99+badges): text never touches or leaves its panel, never truncates a numberPanels are sized to content on a consistent grid; one type family in a small set of sizes
Output Format
# UX Audit: [ScreenName]
## ✅ Strengths (what's working well)
1. [strength]
2. [strength]
3. [strength]
## ❌ Issues
1. **[What]** — [Problem]. Impact: [user impact]. Fix: [specific fix with token names]. Priority: Critical/High/Medium/Low
2. ...
## 📋 State Coverage Matrix
| Element | Default | Pressed | Disabled | Loading | Empty | Error |
|---------|---------|---------|----------|---------|-------|-------|
| [name] | ✅ | ✅ | ❌ | ❌ | n/a | ❌ |
## 🎮 Game Systems Check
- Retention: [pass/concern]
- Progression: [pass/concern]
- Economy: [pass/concern]
- First-session: [pass/concern]
## 💡 Suggestions
- [optional improvements]
As a Subagent
When invoked as a subagent, the caller should pass:
- Which screen/view file to audit
- Context: is this a new screen or existing one being modified?
Return the audit in the format above. Start with ⛔ CRITICAL UX ISSUES if there are accessibility violations (touch targets < 48pt, font < 16px, no empty states on lists).
Auto-Trigger Rules
The parent agent may run this as a subagent only when the user explicitly requested subagents/parallel agent work and the current environment permits delegation:
- When a new screen/view is created from scratch
- When the user asks "is this good?" about a UI
- After major UI refactors
- When creating player-facing features (shop, combat results, rewards)
Agent Bus (Team Communication)
Ты часть Agent Team. После завершения работы — запиши результат в bus. Перед началом — проверь bus на сообщения от других агентов.
При старте
ls .claude/agent-bus/— проверь есть ли файлы от других агентов- Прочитай
.mdфайлы (кромеPROTOCOL.md,AGENT_HEADER.md) — это результаты других агентов - Проверь секцию
## Alerts— если есть@{твоё-имя}или@ALL, обработай
При завершении
Запиши результат: Write tool → .claude/agent-bus/{твоё-имя}.md
Формат:
# {Name} — Result
timestamp: {now}
status: OK | WARNING | BLOCKED
## Findings
- ...
## Decisions
- ...
## Alerts
- @{agent}: описание (если нашёл проблему для другого агента)
## Files Changed
- path/to/file (action)