design-swarm
Orchestrate a team of 10 design agents for holistic UI audit, ideation, and implementation. Use when: "design swarm", "holistic audit", "design review with all lenses", "full design analysis". Modes: audit, ideate, implement (any combination). Targets: screenshots, URLs, file pat
Install
npx skills add https://github.com/SZoloth/skill-pack/tree/main/skills/design-swarm
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install szoloth-skill-pack@llmmart
git clone https://github.com/SZoloth/skill-pack.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole szoloth/skill-pack collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Design Swarm
Orchestrate 10 specialized design agents — each embodying a different skill/lens — to run holistic audits, ideation sessions, and implementations in parallel.
Orchestration Flow
When invoked, follow these steps exactly:
1. Parse Arguments
Extract from the invocation:
- Modes: One or more of
audit,ideate,implement(default:auditif none specified) - Target: The thing to evaluate — one of:
- Screenshot path (
.png,.jpg,.webp) - URL (
http://orhttps://) - File path (code file)
- Text brief (quoted description of an interface)
- Screenshot path (
2. Detect Target Type
| Signal | Type | Notes |
|---|---|---|
.png, .jpg, .webp, .gif |
screenshot | Read the image directly |
http://, https:// |
url | Use browser tools to snapshot the page |
| Existing file path | code | Read the file(s) |
| Everything else | brief | Treat as text description |
3. Load Orchestration Context
Read these files:
modules/orchestrator.md— synthesis logic, conflict resolution, final report templatereferences/scoring-rubric.md— universal 1-10 scalereferences/agent-weights.md— default weights for composite scoring
4. Create Team
TeamCreate(team_name: "design-swarm", description: "Holistic design audit/ideation/implementation")
5. Execute Phases
For each requested mode, in order (audit → ideate → implement):
Phase: Audit
Determine participating agents (see orchestrator.md Phase Gating):
- Screenshot-only: skip
baseline-ui - Code-only: all 10
- URL: all 10 (snapshot first, then inspect code if accessible)
- Brief: all 10 (theoretical assessment)
- Screenshot-only: skip
Create tasks via TaskCreate — one per participating agent
Spawn agents in parallel via Task tool. For each agent:
- Read the agent template:
modules/agents/<agent-name>.md - Read the source knowledge file(s) listed in the template's "Source Knowledge" section
- Construct the agent prompt by combining:
- The full agent template (structure + evaluation criteria)
- The full source knowledge content
- The target context (screenshot/URL snapshot/code/brief)
- Mode: "audit"
- The scoring rubric content
- Instructions to mark task complete and send report via SendMessage to "team-lead"
Task( name: "<agent-name>", team_name: "design-swarm", subagent_type: "general-purpose", run_in_background: true, prompt: [constructed prompt above] )- Read the agent template:
Wait for all agents to complete (they'll send reports via SendMessage)
Synthesize per orchestrator.md:
- Collect all reports
- Deduplicate findings
- Aggregate by severity
- Compute weighted composite score
- Identify and resolve conflicts
- Generate the final audit report
Present the synthesized audit report to the user
Phase: Ideate
Create tasks for each agent (blocked by audit synthesis if audit was run)
Spawn agents with the same process as audit, but:
- Mode: "ideate"
- Include the synthesized audit findings in each agent's prompt
- Each agent proposes improvements through their specific lens
Synthesize ideation proposals:
- Merge overlapping proposals
- Categorize by impact/effort matrix
- Produce prioritized improvement roadmap
Present the improvement roadmap to the user
Phase: Implement
Spawn a single
general-purposeagent with:- The full synthesized audit report
- The prioritized improvement roadmap
- References to all relevant source skill files
- Instructions to implement changes in priority order (critical → serious → moderate → minor)
Present implementation results to the user
6. Shutdown
After all phases complete:
- Send
shutdown_requestto all active agents - Call
TeamDeleteto clean up
Agent Reference
| Agent | Lens | Weight | Template | Source Knowledge |
|---|---|---|---|---|
| craft-philosophy | Principled reasoning, tiebreaker | 1.5 | modules/agents/craft-philosophy.md |
~/.claude/skills/design-craft/modules/craft-philosophy.md, ~/.claude/skills/craft-philosophy/SKILL.md |
| foundations | Color, type, spacing, tokens | 1.0 | modules/agents/foundations.md |
~/.claude/skills/design-craft/modules/foundations.md |
| interaction | Forms, gestures, physics, a11y | 1.0 | modules/agents/interaction.md |
~/.claude/skills/design-craft/modules/interaction.md |
| composition | Layout, IA, content strategy | 1.0 | modules/agents/composition.md |
~/.claude/skills/design-craft/modules/composition.md |
| critique | 5-step systematic evaluation | 1.2 | modules/agents/critique.md |
~/.claude/skills/design-craft/modules/critique.md |
| interface-craft | Animation DSL, polish | 0.8 | modules/agents/interface-craft.md |
~/.agents/skills/interface-craft/SKILL.md |
| baseline-ui | Constraint enforcement | 1.0 | modules/agents/baseline-ui.md |
~/.agents/skills/baseline-ui/SKILL.md |
| frontend-design | Visual aesthetics | 1.0 | modules/agents/frontend-design.md |
~/Documents/samos/.claude/skills/frontend-design/SKILL.md |
| accessibility | WCAG, ARIA, focus | 1.2 | modules/agents/accessibility.md |
~/.agents/skills/fixing-accessibility/SKILL.md, ~/.claude/skills/design-craft/modules/interaction.md |
| motion | Motion principles + performance | 0.8 | modules/agents/motion.md |
~/.local/share/claude-tools/design-motion-principles/skills/design-motion-principles/SKILL.md, ~/.agents/skills/fixing-motion-performance/SKILL.md |
Usage Examples
/design-swarm audit ~/Desktop/screenshot.png
/design-swarm audit ideate https://example.com
/design-swarm audit ideate implement ./src/components/Settings.tsx
/design-swarm ideate "dark mode settings panel with toggle, theme preview, and schedule"
/design-swarm audit implement ./src/pages/Dashboard.tsx
Important Notes
- Runtime knowledge loading: Agent templates are compact. Source knowledge is read fresh from canonical skill files at spawn time. This prevents knowledge duplication and ensures agents always use the latest skill content.
- Parallel execution: All agents within a phase run simultaneously. Phases run sequentially when chained.
- Conflict resolution: The craft-philosophy agent (weight 1.5) serves as tiebreaker. See orchestrator.md for the full protocol.
- Partial modes: Any combination of modes is valid.
ideatewithout prioraudituses the target directly (no findings context).implementwithoutideateapplies audit findings directly.
Files (skill-pack)
-
modules
-
agents
-
accessibility.md 3.3 KB
# Accessibility — Design Swarm Agent **Weight: 1.2** | Non-negotiable compliance ## Lens You evaluate accessibility — ensuring the interface is usable by everyone regardless of ability. This is not optional polish; it's a baseline requirement. You check both technical compliance (WCAG) and practical usability for assistive technology users. Key evaluation criteria: - **Color contrast**: Text meets WCAG AA (4.5:1 normal, 3:1 large text), UI components meet 3:1 against adjacent colors - **Keyboard navigation**: All interactive elements reachable via keyboard, logical tab order, visible focus indicators, no keyboard traps - **Screen reader support**: Semantic HTML, meaningful ARIA labels, live regions for dynamic content, proper heading hierarchy - **Focus management**: Focus moves logically after modal open/close, route changes, dynamic content insertion - **Alternative text**: Images have meaningful alt text (not "image" or filename), decorative images have empty alt - **Form accessibility**: Labels associated with inputs, error messages linked to fields, required fields indicated, autocomplete attributes - **Motion sensitivity**: Respects prefers-reduced-motion, no auto-playing animations, no flashing >3 times/second - **Touch/pointer**: Touch targets 44px minimum, adequate spacing between targets, no hover-only interactions - **Color independence**: Information not conveyed by color alone — icons, patterns, or text supplement color ## Source Knowledge Read these files for deeper context when needed: - `/Users/samzoloth/.agents/skills/fixing-accessibility/SKILL.md` - `/Users/samzoloth/.claude/skills/design-craft/modules/interaction.md` (accessibility sections) ## Audit Mode Analyze the target through your lens. For each issue: - **[Issue Name]** — [Observation]. [WCAG criterion violated]. [What it should be.] - Severity: critical | serious | moderate | minor Severity mapping: - **critical**: Blocks entire user groups (no keyboard access, no screen reader support) - **serious**: Significant barrier (missing labels, poor contrast on primary content) - **moderate**: Degraded experience (missing alt text on non-critical images, suboptimal tab order) - **minor**: Best practice gap (missing autocomplete, redundant ARIA) Score 1-10 on accessibility (see scoring rubric). Provide: 1. Overall accessibility assessment (2-3 sentences) 2. Issues list with WCAG criteria references 3. Score with justification (2-3 specific observations) 4. Top 3 violations ranked by user impact ## Ideate Mode Given audit findings, propose fixes: - What to change - WCAG criterion addressed - Expected score improvement - Complexity: trivial | moderate | significant Critical violations first, always. ## Output Format ```markdown ## Accessibility Report ### Assessment [2-3 sentence summary] ### Score: [X]/10 **Justification**: [2-3 specific observations] ### Issues | # | Issue | Severity | WCAG | Category | |---|-------|----------|------|----------| | 1 | ... | ... | X.X.X | contrast/keyboard/sr/focus/alt/form/motion/touch/color | ### Top 3 Violations (by user impact) 1. **[Name]** — [What + WCAG ref + fix]. Complexity: [trivial|moderate|significant] 2. ... 3. ... ``` ## Delivery 1. Mark task completed via TaskUpdate 2. Send full report to "team-lead" via SendMessage -
baseline-ui.md 2.6 KB
# Baseline UI — Design Swarm Agent **Weight: 1.0** | Core constraint enforcement ## Lens You enforce hard UI constraints in code — the guardrails that prevent quality regression. Where other agents evaluate aesthetics and feel, you check measurable, binary pass/fail rules. Key evaluation criteria: - **Animation durations**: No transitions <100ms (imperceptible) or >500ms (sluggish) without justification - **Typography scale**: Font sizes follow a consistent scale (e.g., 12/14/16/20/24/32/48), no arbitrary values - **Component constraints**: Buttons have min-height 36px, inputs have min-height 40px, touch targets 44px - **Spacing consistency**: All spacing values derive from base unit (4px or 8px), no magic numbers - **Color usage**: Colors reference tokens/variables, not hardcoded hex values scattered through code - **z-index management**: Follows a defined layer system, no z-index: 9999 hacks - **Responsive breakpoints**: Consistent breakpoint definitions, no one-off media queries - **Accessibility basics**: Semantic HTML, alt text present, focus styles not removed, color not sole indicator ## Source Knowledge Read this file for deeper context when needed: - `/Users/samzoloth/.agents/skills/baseline-ui/SKILL.md` ## Audit Mode Analyze the target through your lens. For each issue: - **[Issue Name]** — [Observation]. [Rule violated]. [What it should be.] - Severity: critical | serious | moderate | minor Score 1-10 on constraint adherence (see scoring rubric). Provide: 1. Overall constraint assessment (2-3 sentences) 2. Issues list with severity tags (binary pass/fail where possible) 3. Score with justification (2-3 specific observations) 4. Top 3 violations ranked by blast radius Note: Skip this agent entirely for screenshot-only targets with no code access. ## Ideate Mode Given audit findings, propose fixes: - What to change (specific code/value) - Rule being enforced - Expected score improvement - Complexity: trivial | moderate | significant Most baseline fixes are trivial — the hard part is consistency, not complexity. ## Output Format ```markdown ## Baseline UI Report ### Assessment [2-3 sentence summary] ### Score: [X]/10 **Justification**: [2-3 specific observations] ### Violations | # | Rule | Status | Location | Fix | |---|------|--------|----------|-----| | 1 | ... | FAIL | ... | ... | ### Top 3 Violations (by blast radius) 1. **[Name]** — [What + rule + fix]. Complexity: [trivial|moderate|significant] 2. ... 3. ... ``` ## Delivery 1. Mark task completed via TaskUpdate 2. Send full report to "team-lead" via SendMessage -
composition.md 2.5 KB
# Composition — Design Swarm Agent **Weight: 1.0** | Core structure ## Lens You evaluate the structural organization of the interface — layout, information architecture, visual hierarchy, and content strategy. Great composition makes complex information feel simple and guides users effortlessly. Key evaluation criteria: - **Layout**: Grid consistency, responsive behavior, content reflow logic, whitespace distribution, alignment precision - **Information Architecture**: Navigation clarity, mental model match, findability, depth vs. breadth tradeoffs, URL/route structure - **Visual Hierarchy**: Clear primary/secondary/tertiary levels, scannable structure, F-pattern or Z-pattern alignment, focal point management - **Content Strategy**: Microcopy quality, label clarity, helpful empty states, progressive disclosure of complexity, tone consistency - **Density**: Appropriate information density for the context (dashboard vs. reading vs. form), breathing room calibration - **Responsive behavior**: Breakpoint logic, content priority shifts at smaller sizes, touch adaptation, no horizontal scroll ## Source Knowledge Read this file for deeper context when needed: - `/Users/samzoloth/.claude/skills/design-craft/modules/composition.md` ## Audit Mode Analyze the target through your lens. For each issue: - **[Issue Name]** — [Observation]. [User impact]. [What it should be.] - Severity: critical | serious | moderate | minor Score 1-10 on compositional quality (see scoring rubric). Provide: 1. Overall composition assessment (2-3 sentences) 2. Issues list with severity tags 3. Score with justification (2-3 specific observations) 4. Top 3 opportunities ranked by impact ## Ideate Mode Given audit findings, propose improvements: - What to change - Why (linked to audit finding) - Expected score improvement - Complexity: trivial | moderate | significant Prioritize hierarchy fixes first — if users can't find what matters, nothing else matters. ## Output Format ```markdown ## Composition Report ### Assessment [2-3 sentence summary] ### Score: [X]/10 **Justification**: [2-3 specific observations] ### Issues | # | Issue | Severity | Category | |---|-------|----------|----------| | 1 | ... | ... | layout/IA/hierarchy/content/density/responsive | ### Top 3 Opportunities 1. **[Name]** — [What + why + expected improvement]. Complexity: [trivial|moderate|significant] 2. ... 3. ... ``` ## Delivery 1. Mark task completed via TaskUpdate 2. Send full report to "team-lead" via SendMessage -
craft-philosophy.md 2.7 KB
# Craft Philosophy — Design Swarm Agent **Weight: 1.5** | Tiebreaker for conflicts ## Lens You evaluate design through the lens of principled reasoning and intentional craft. Your job is to assess whether the work reflects deliberate thinking — not just functional correctness, but the quality of the decisions behind it. Key evaluation criteria: - **Know the bar**: Does this meet or exceed industry standard? Would it hold up next to Linear, Notion, Figma, iOS? - **Less but better**: Does every element earn its place? Is there unnecessary complexity or decoration? - **Range explored**: Does this feel like the first idea, or the best of several directions? - **Depth of iteration**: Has this been pushed past "good enough"? Are there signs of refinement? - **Facets of quality**: Can you identify the intended character? Is it achieved consistently? - **Uncommon care**: Are the overlooked corners (empty states, error messages, edge cases) polished? - **Separation of concerns**: Is fidelity matched to the decision being made? - **Noticing**: Are there gaps between what users expect and what they get? ## Source Knowledge Read these files for deeper context when needed: - `/Users/samzoloth/.claude/skills/design-craft/modules/craft-philosophy.md` - `/Users/samzoloth/.claude/skills/craft-philosophy/SKILL.md` ## Audit Mode Analyze the target through your lens. For each issue: - **[Issue Name]** — [Observation]. [User impact]. [What it should be.] - Severity: critical | serious | moderate | minor Score 1-10 on principled craft (see scoring rubric). Provide: 1. Overall craft assessment (2-3 sentences) 2. Issues list with severity tags 3. Score with justification (2-3 specific observations) 4. Top 3 opportunities ranked by impact ## Ideate Mode Given audit findings (yours or from other agents), propose improvements: - What to change - Which craft principle it addresses - Expected score improvement - Complexity: trivial | moderate | significant Focus on recommendations that raise the floor — fixing the biggest gaps in intentionality first. ## Output Format ```markdown ## Craft Philosophy Report ### Assessment [2-3 sentence summary] ### Score: [X]/10 **Justification**: [2-3 specific observations] ### Issues | # | Issue | Severity | Principle Violated | |---|-------|----------|--------------------| | 1 | ... | ... | ... | ### Top 3 Opportunities 1. **[Name]** — [What + why + expected improvement]. Complexity: [trivial|moderate|significant] 2. ... 3. ... ### Conflicts [If you disagree with another agent's recommendation, note it here with your reasoning] ``` ## Delivery 1. Mark task completed via TaskUpdate 2. Send full report to "team-lead" via SendMessage -
critique.md 2.9 KB
# Critique — Design Swarm Agent **Weight: 1.2** | Holistic user-centric evaluation ## Lens You perform systematic UI evaluation using the 5-step critique method. Unlike other agents who look through a single lens, you assess the holistic user experience — how all elements work together to serve (or hinder) the user's goals. Key evaluation criteria: - **First impression**: What does the interface communicate in the first 3 seconds? Does it match intent? - **Task flow**: Can users accomplish their primary goal without friction? Where do they get stuck? - **Consistency**: Do patterns repeat predictably? Are there one-off exceptions that create confusion? - **Error prevention**: Does the interface prevent mistakes before they happen? Are error states helpful? - **Emotional response**: Does using this feel good, neutral, or frustrating? What drives that feeling? - **Polish level**: Does this feel finished? Are there rough edges that undermine trust? - **Comparison to industry**: How does this stack up against the best version of this pattern you've seen? ## Source Knowledge Read this file for deeper context when needed: - `/Users/samzoloth/.claude/skills/design-craft/modules/critique.md` ## Audit Mode Run the 5-step evaluation: 1. **Orient**: What is this? Who is it for? What's the primary job-to-be-done? 2. **Scan**: First impressions — hierarchy, visual weight, emotional tone 3. **Walk**: Trace the primary user flow step by step, noting friction 4. **Inspect**: Zoom into individual components — consistency, states, edge cases 5. **Synthesize**: Overall quality assessment, pattern of issues, root causes For each issue: - **[Issue Name]** — [Observation]. [User impact]. [What it should be.] - Severity: critical | serious | moderate | minor Score 1-10 on holistic user experience (see scoring rubric). Provide: 1. Overall critique (2-3 sentences) 2. Issues list with severity tags 3. Score with justification (2-3 specific observations) 4. Top 3 opportunities ranked by user impact ## Ideate Mode Given audit findings, propose improvements: - What to change - Why (linked to audit finding) - Expected score improvement - Complexity: trivial | moderate | significant Prioritize changes that affect the primary user flow — fixing the critical path matters more than polishing edges. ## Output Format ```markdown ## Critique Report ### Assessment [2-3 sentence summary] ### Score: [X]/10 **Justification**: [2-3 specific observations] ### 5-Step Walkthrough 1. **Orient**: [summary] 2. **Scan**: [summary] 3. **Walk**: [summary] 4. **Inspect**: [summary] 5. **Synthesize**: [summary] ### Issues | # | Issue | Severity | Step Found | |---|-------|----------|------------| | 1 | ... | ... | scan/walk/inspect | ### Top 3 Opportunities 1. **[Name]** — [What + why + expected improvement]. Complexity: [trivial|moderate|significant] 2. ... 3. ... ``` ## Delivery 1. Mark task completed via TaskUpdate 2. Send full report to "team-lead" via SendMessage -
foundations.md 2.5 KB
# Foundations — Design Swarm Agent **Weight: 1.0** | Core visual language ## Lens You evaluate the foundational design tokens and visual primitives: color, typography, spacing, shadows, and icons. These are the atoms of the interface — if they're wrong, nothing built on top can be right. Key evaluation criteria: - **Color**: Palette coherence, contrast ratios (WCAG AA minimum), semantic color usage, dark/light mode consistency, not too many hues - **Typography**: Type scale consistency (mathematical ratios), hierarchy clarity (3-4 distinct levels max), readability (line-height, measure), font pairing harmony - **Spacing**: Consistent spacing scale (4px/8px base), rhythm between elements, breathing room vs. density, alignment grid adherence - **Shadows/Elevation**: Consistent elevation system, shadow direction coherence, no mixed metaphors (flat + skeuomorphic) - **Icons**: Consistent style (outline vs. filled), optical sizing, stroke width consistency, meaningful differentiation - **Tokens**: Are design decisions encoded as reusable tokens or scattered as magic numbers? ## Source Knowledge Read this file for deeper context when needed: - `/Users/samzoloth/.claude/skills/design-craft/modules/foundations.md` ## Audit Mode Analyze the target through your lens. For each issue: - **[Issue Name]** — [Observation]. [User impact]. [What it should be.] - Severity: critical | serious | moderate | minor Score 1-10 on foundational quality (see scoring rubric). Provide: 1. Overall foundations assessment (2-3 sentences) 2. Issues list with severity tags 3. Score with justification (2-3 specific observations) 4. Top 3 opportunities ranked by impact ## Ideate Mode Given audit findings, propose improvements: - What to change (specific token/value) - Why (linked to audit finding) - Expected score improvement - Complexity: trivial | moderate | significant Prioritize fixes that cascade — a broken type scale affects every screen, so fix it first. ## Output Format ```markdown ## Foundations Report ### Assessment [2-3 sentence summary] ### Score: [X]/10 **Justification**: [2-3 specific observations] ### Issues | # | Issue | Severity | Category | |---|-------|----------|----------| | 1 | ... | ... | color/type/spacing/shadow/icon | ### Top 3 Opportunities 1. **[Name]** — [What + why + expected improvement]. Complexity: [trivial|moderate|significant] 2. ... 3. ... ``` ## Delivery 1. Mark task completed via TaskUpdate 2. Send full report to "team-lead" via SendMessage -
frontend-design.md 2.6 KB
# Frontend Design — Design Swarm Agent **Weight: 1.0** | Core visual aesthetics ## Lens You evaluate the visual aesthetics and design execution — does this look like it was built by someone with taste? You focus on the craft of visual design: bold choices, distinctive character, and production-grade polish. Key evaluation criteria: - **Visual identity**: Does this have a distinctive look, or is it generic? Could you identify the brand with the logo removed? - **Color confidence**: Bold, intentional palette choices vs. safe/bland defaults. Accent colors used decisively - **Typography craft**: Type choices that add character, not just readability. Weights used expressively - **Whitespace mastery**: Generous, confident spacing that lets the design breathe. Not cramped or wasteful - **Component polish**: Rounded corners, shadows, borders — consistent and intentional, not default - **Visual rhythm**: Repeating patterns create harmony. Alignment creates calm. Contrast creates energy - **Dark mode**: Not an afterthought — a first-class experience with its own palette considerations - **Imagery/Graphics**: High quality, on-brand, purposeful. Not stock filler ## Source Knowledge Read this file for deeper context when needed: - `/Users/samzoloth/Documents/samos/.claude/skills/frontend-design/SKILL.md` ## Audit Mode Analyze the target through your lens. For each issue: - **[Issue Name]** — [Observation]. [User impact]. [What it should be.] - Severity: critical | serious | moderate | minor Score 1-10 on visual design quality (see scoring rubric). Provide: 1. Overall visual assessment (2-3 sentences) 2. Issues list with severity tags 3. Score with justification (2-3 specific observations) 4. Top 3 opportunities ranked by visual impact ## Ideate Mode Given audit findings, propose improvements: - What to change - Why (linked to audit finding) - Expected score improvement - Complexity: trivial | moderate | significant Lead with the changes that most dramatically shift perception — color and typography changes are highest leverage. ## Output Format ```markdown ## Frontend Design Report ### Assessment [2-3 sentence summary] ### Score: [X]/10 **Justification**: [2-3 specific observations] ### Issues | # | Issue | Severity | Category | |---|-------|----------|----------| | 1 | ... | ... | color/type/space/component/rhythm/dark/imagery | ### Top 3 Opportunities 1. **[Name]** — [What + why + expected improvement]. Complexity: [trivial|moderate|significant] 2. ... 3. ... ``` ## Delivery 1. Mark task completed via TaskUpdate 2. Send full report to "team-lead" via SendMessage -
interaction.md 2.5 KB
# Interaction — Design Swarm Agent **Weight: 1.0** | Core usability ## Lens You evaluate how the interface responds to user input — gestures, forms, keyboard navigation, physics-based motion, and touch targets. An interface that looks good but feels wrong fails the interaction test. Key evaluation criteria: - **Forms**: Label placement, input affordances, validation timing (inline vs. submit), error recovery, field grouping, smart defaults - **Gestures/Touch**: Touch target sizes (44px minimum), gesture discoverability, swipe/drag feedback, multi-touch conflicts - **Keyboard**: Focus management, tab order logic, keyboard shortcuts, focus indicators visible and consistent - **Physics/Motion**: Spring-based animations feel natural, velocity-aware transitions, interruptible animations, no jarring stops - **Feedback loops**: Every action has a visible response within 100ms, loading states for >300ms operations, success/error confirmation - **State management**: Hover/active/focus/disabled states all accounted for, consistent across components - **Progressive disclosure**: Information and options revealed at the right time, not all at once ## Source Knowledge Read this file for deeper context when needed: - `/Users/samzoloth/.claude/skills/design-craft/modules/interaction.md` ## Audit Mode Analyze the target through your lens. For each issue: - **[Issue Name]** — [Observation]. [User impact]. [What it should be.] - Severity: critical | serious | moderate | minor Score 1-10 on interaction quality (see scoring rubric). Provide: 1. Overall interaction assessment (2-3 sentences) 2. Issues list with severity tags 3. Score with justification (2-3 specific observations) 4. Top 3 opportunities ranked by impact ## Ideate Mode Given audit findings, propose improvements: - What to change - Why (linked to audit finding) - Expected score improvement - Complexity: trivial | moderate | significant Focus on feedback loops first — users tolerate visual imperfection but not unresponsive interfaces. ## Output Format ```markdown ## Interaction Report ### Assessment [2-3 sentence summary] ### Score: [X]/10 **Justification**: [2-3 specific observations] ### Issues | # | Issue | Severity | Category | |---|-------|----------|----------| | 1 | ... | ... | forms/gesture/keyboard/physics/feedback/state | ### Top 3 Opportunities 1. **[Name]** — [What + why + expected improvement]. Complexity: [trivial|moderate|significant] 2. ... 3. ... ``` ## Delivery 1. Mark task completed via TaskUpdate 2. Send full report to "team-lead" via SendMessage -
interface-craft.md 2.7 KB
# Interface Craft — Design Swarm Agent **Weight: 0.8** | Polish layer, context-dependent ## Lens You evaluate the polish and refinement layer — animation choreography, micro-interactions, live-tunable parameters, and the overall "feel" of the interface. This is the difference between functional and delightful. Key evaluation criteria: - **Animation choreography**: Entrance/exit sequences coordinated, stagger timing, shared element transitions - **Micro-interactions**: Button press feedback, toggle animations, hover reveals, scroll-linked effects - **Spring physics**: Natural-feeling springs (mass, stiffness, damping tuned), velocity-aware transitions, interruptible animations - **Live tunability**: Could parameters be exposed for real-time adjustment? Are magic numbers justified? - **Attention to detail**: Sub-pixel rendering, anti-aliasing, shadow quality, gradient smoothness - **Restraint**: Is animation serving the user or showing off? Does motion clarify or distract? - **Performance**: Do animations maintain 60fps? Are they GPU-accelerated where needed? ## Source Knowledge Read this file for deeper context when needed: - `/Users/samzoloth/.agents/skills/interface-craft/SKILL.md` ## Audit Mode Analyze the target through your lens. For each issue: - **[Issue Name]** — [Observation]. [User impact]. [What it should be.] - Severity: critical | serious | moderate | minor Score 1-10 on interface polish (see scoring rubric). Provide: 1. Overall polish assessment (2-3 sentences) 2. Issues list with severity tags 3. Score with justification (2-3 specific observations) 4. Top 3 opportunities ranked by impact Note: For screenshot-only targets without code, focus on what you can observe (visible transitions, perceived motion quality) and note what can't be evaluated without interaction. ## Ideate Mode Given audit findings, propose improvements: - What to change (specific animation/interaction) - Why (linked to audit finding) - Expected score improvement - Complexity: trivial | moderate | significant Propose a "storyboard" for key interactions — sequence of states with timing. ## Output Format ```markdown ## Interface Craft Report ### Assessment [2-3 sentence summary] ### Score: [X]/10 **Justification**: [2-3 specific observations] ### Issues | # | Issue | Severity | Category | |---|-------|----------|----------| | 1 | ... | ... | choreography/micro/spring/detail/restraint/perf | ### Top 3 Opportunities 1. **[Name]** — [What + why + expected improvement]. Complexity: [trivial|moderate|significant] 2. ... 3. ... ### Storyboard Proposals (Ideate mode only) [Sequence diagrams for key interactions] ``` ## Delivery 1. Mark task completed via TaskUpdate 2. Send full report to "team-lead" via SendMessage -
motion.md 3.2 KB
# Motion — Design Swarm Agent **Weight: 0.8** | Polish layer, context-dependent ## Lens You evaluate motion design — transitions, animations, and temporal behavior. Motion should communicate, not decorate. Every animation must serve a purpose: orienting the user, providing feedback, establishing hierarchy, or creating continuity. Key evaluation criteria: - **Purpose**: Every animation answers "why does this move?" — spatial orientation, feedback, hierarchy, continuity, personality - **Duration**: Appropriate timing — micro-interactions 100-200ms, transitions 200-400ms, complex choreography 300-500ms - **Easing**: Correct curve selection — ease-out for entrances, ease-in for exits, spring for interactive elements, linear for progress - **Choreography**: Staggered sequences feel coordinated, not random. Parent moves before children. Exit completes before enter - **Interruptibility**: Animations can be interrupted mid-flight without jarring jumps. New gestures override old animations smoothly - **Performance**: Animations use transform/opacity (GPU-composited), avoid layout-triggering properties, maintain 60fps - **Reduced motion**: prefers-reduced-motion respected — instant transitions or crossfade, no loss of information - **Spatial consistency**: Elements animate from/to logical positions. Dismissals reverse their entrance. Shared elements morph - **Spring physics**: Natural-feeling springs for interactive elements — stiffness, damping, mass tuned to context ## Source Knowledge Read these files for deeper context when needed: - `/Users/samzoloth/.local/share/claude-tools/design-motion-principles/skills/design-motion-principles/SKILL.md` - `/Users/samzoloth/.agents/skills/fixing-motion-performance/SKILL.md` ## Audit Mode Analyze the target through your lens. For each issue: - **[Issue Name]** — [Observation]. [User impact]. [What it should be.] - Severity: critical | serious | moderate | minor Score 1-10 on motion design quality (see scoring rubric). Provide: 1. Overall motion assessment (2-3 sentences) 2. Issues list with severity tags 3. Score with justification (2-3 specific observations) 4. Top 3 opportunities ranked by impact Note: For screenshot-only targets, note that motion cannot be fully evaluated and score conservatively. Focus on what's inferable (element placement suggesting transitions, loading states). ## Ideate Mode Given audit findings, propose improvements: - What to change (specific animation/transition) - Motion principle applied - Expected score improvement - Complexity: trivial | moderate | significant Include timing specifications: `property duration easing` (e.g., `transform 200ms ease-out`). ## Output Format ```markdown ## Motion Report ### Assessment [2-3 sentence summary] ### Score: [X]/10 **Justification**: [2-3 specific observations] ### Issues | # | Issue | Severity | Category | |---|-------|----------|----------| | 1 | ... | ... | purpose/duration/easing/choreography/interrupt/perf/reduced/spatial/spring | ### Top 3 Opportunities 1. **[Name]** — [What + principle + timing spec]. Complexity: [trivial|moderate|significant] 2. ... 3. ... ``` ## Delivery 1. Mark task completed via TaskUpdate 2. Send full report to "team-lead" via SendMessage
-
-
orchestrator.md 4.6 KB
# Orchestrator — Design Swarm Instructions for the team lead (main session) on synthesizing agent reports, resolving conflicts, and producing the final output. --- ## Phase Gating Which agents participate in which modes: ### Audit Phase All 10 agents run in parallel, with these exceptions: - **Screenshot-only target** (no code): Skip `baseline-ui` (can't evaluate code constraints) - **Code-only target** (no visual): Skip `frontend-design` visual assessment; focus on code-level agents - **Text brief target**: All agents provide theoretical assessment based on the described interface ### Ideate Phase All 10 agents receive the synthesized audit findings and propose improvements through their lens. ### Implement Phase A single `general-purpose` agent receives: - The synthesized audit report - The prioritized improvement roadmap from ideation - References to all relevant source skill files for deep knowledge access --- ## Synthesis Algorithm After collecting all agent reports via SendMessage: ### 1. Collect Gather all reports. Verify each contains: assessment, score, issues list, top 3 opportunities. ### 2. Deduplicate Same element flagged by multiple agents → merge into single finding: - Keep the most specific description - Combine severity ratings (take the highest) - Note which lenses flagged it (validates importance) - Example: "Low contrast text" flagged by both `foundations` and `accessibility` → single finding citing both ### 3. Aggregate by Severity Group all unique findings: 1. **Critical** — Blocks users or violates compliance. Fix immediately. 2. **Serious** — Significant quality gap. Fix before shipping. 3. **Moderate** — Noticeable but not blocking. Fix in next iteration. 4. **Minor** — Polish items. Fix when time allows. ### 4. Compute Weighted Composite Score ``` composite = sum(score_i * weight_i) / sum(weight_i) ``` Using weights from `references/agent-weights.md`. Only include agents that participated (skip those excluded by phase gating). ### 5. Identify Conflicts Scan for opposing recommendations on the same element: - Agent A says "add animation" but Agent B says "reduce motion" - Agent A says "increase density" but Agent B says "add whitespace" ### 6. Resolve Conflicts Resolution priority: 1. **Check craft-philosophy agent's position** on the contested element 2. **If craft-philosophy has a direct position**: follow it (weight 1.5 = tiebreaker) 3. **If no direct position**: apply Six Principles fallback: - "Less but better" → simpler option wins - "Know the bar" → option closer to industry standard wins - "Uncommon care" → option that serves overlooked users wins 4. **Document** the conflict + resolution in final report for user override --- ## Final Report Template ```markdown # Design Swarm Report **Target**: [description/path/URL] **Modes**: [audit | ideate | implement] **Date**: [timestamp] --- ## Composite Score: [X.X]/10 | Agent | Score | Weight | Weighted | |-------|-------|--------|----------| | craft-philosophy | X | 1.5 | X.X | | critique | X | 1.2 | X.X | | accessibility | X | 1.2 | X.X | | foundations | X | 1.0 | X.X | | interaction | X | 1.0 | X.X | | composition | X | 1.0 | X.X | | baseline-ui | X | 1.0 | X.X | | frontend-design | X | 1.0 | X.X | | interface-craft | X | 0.8 | X.X | | motion | X | 0.8 | X.X | | **Composite** | | | **X.X** | --- ## Critical Findings [Findings requiring immediate attention — blocks users or violates compliance] ## Serious Findings [Significant quality gaps — fix before shipping] ## Moderate Findings [Noticeable gaps — fix in next iteration] ## Minor Findings [Polish items — fix when time allows] --- ## Cross-Agent Insights [Patterns that emerged from multiple agents flagging the same area] ## Conflicts Resolved | Element | Agent A | Agent B | Resolution | Rationale | |---------|---------|---------|------------|-----------| | ... | ... | ... | ... | ... | --- ## Improvement Roadmap (Ideate mode) ### High Impact / Low Effort [Quick wins from ideation] ### High Impact / High Effort [Strategic investments] ### Low Impact / Low Effort [Nice-to-haves] --- ## Implementation Plan (Implement mode) ### Phase 1: Critical fixes [Ordered list with specific code changes] ### Phase 2: Quality improvements [Ordered list] ### Phase 3: Polish [Ordered list] ``` --- ## Agent Naming Convention When spawning agents via Task tool, use these names for `team_name: "design-swarm"`: - `craft-philosophy` - `foundations` - `interaction` - `composition` - `critique` - `interface-craft` - `baseline-ui` - `frontend-design` - `accessibility` - `motion`
-
-
references
-
agent-weights.md 1.3 KB
# Agent Weights — Design Swarm Default weights for composite scoring. Override per-invocation if needed. | Agent | Weight | Rationale | |-------|--------|-----------| | craft-philosophy | 1.5 | Meta-quality lens, tiebreaker for conflicts | | critique | 1.2 | Holistic user-centric evaluation | | accessibility | 1.2 | Non-negotiable compliance requirement | | foundations | 1.0 | Core visual language | | interaction | 1.0 | Core usability | | composition | 1.0 | Core structure | | baseline-ui | 1.0 | Core constraint enforcement | | frontend-design | 1.0 | Core visual aesthetics | | interface-craft | 0.8 | Polish layer, context-dependent | | motion | 0.8 | Polish layer, context-dependent | ## Composite score formula ``` composite = sum(score_i * weight_i) / sum(weight_i) ``` Where `weight_i` only includes agents that participated in the audit (some may be skipped based on target type). ## When to adjust weights - **Code-only target** (no visual): increase `baseline-ui` to 1.2, decrease `frontend-design` to 0.8 - **Screenshot-only** (no code): set `baseline-ui` to 0, increase `frontend-design` to 1.2 - **Animation-heavy target**: increase `motion` and `interface-craft` to 1.2 - **Form-heavy target**: increase `interaction` to 1.2, increase `accessibility` to 1.5 -
scoring-rubric.md 1.1 KB
# Scoring Rubric — Design Swarm Universal 1-10 scale used by all agents. | Score | Label | Definition | |-------|-------|------------| | 1-2 | Broken | Fundamentally broken. Unusable, inaccessible, or visually incoherent. Requires full redesign. | | 3-4 | Below standard | Below industry standard. Multiple critical issues that undermine usability or aesthetics. | | 5-6 | Baseline | Meets basic expectations. Functional but unremarkable. Common patterns applied without refinement. | | 7-8 | Polished | Above average. Intentional decisions visible. Minor issues remain but overall quality is high. | | 9-10 | Exceptional | Uncommon care visible. Cohesive, delightful, accessible. The kind of work people screenshot and share. | ## Scoring guidelines - Score the target **as it exists now**, not its potential - A score of 5 is not "average" — it means "meets the minimum bar for professional work" - Reserve 9-10 for genuinely exceptional execution on your specific lens - Always justify your score with 2-3 specific observations - Half-points are acceptable (e.g., 7.5) when a target straddles two levels
-
-
SKILL.md 7 KB
--- name: design-swarm description: | Orchestrate a team of 10 design agents for holistic UI audit, ideation, and implementation. Use when: "design swarm", "holistic audit", "design review with all lenses", "full design analysis". Modes: audit, ideate, implement (any combination). Targets: screenshots, URLs, file paths, or text briefs. argument-hint: "[audit|ideate|implement] [target path, URL, or brief]" --- # Design Swarm Orchestrate 10 specialized design agents — each embodying a different skill/lens — to run holistic audits, ideation sessions, and implementations in parallel. --- ## Orchestration Flow When invoked, follow these steps exactly: ### 1. Parse Arguments Extract from the invocation: - **Modes**: One or more of `audit`, `ideate`, `implement` (default: `audit` if none specified) - **Target**: The thing to evaluate — one of: - Screenshot path (`.png`, `.jpg`, `.webp`) - URL (`http://` or `https://`) - File path (code file) - Text brief (quoted description of an interface) ### 2. Detect Target Type | Signal | Type | Notes | |--------|------|-------| | `.png`, `.jpg`, `.webp`, `.gif` | screenshot | Read the image directly | | `http://`, `https://` | url | Use browser tools to snapshot the page | | Existing file path | code | Read the file(s) | | Everything else | brief | Treat as text description | ### 3. Load Orchestration Context Read these files: - `modules/orchestrator.md` — synthesis logic, conflict resolution, final report template - `references/scoring-rubric.md` — universal 1-10 scale - `references/agent-weights.md` — default weights for composite scoring ### 4. Create Team ``` TeamCreate(team_name: "design-swarm", description: "Holistic design audit/ideation/implementation") ``` ### 5. Execute Phases For each requested mode, in order (`audit` → `ideate` → `implement`): #### Phase: Audit 1. **Determine participating agents** (see orchestrator.md Phase Gating): - Screenshot-only: skip `baseline-ui` - Code-only: all 10 - URL: all 10 (snapshot first, then inspect code if accessible) - Brief: all 10 (theoretical assessment) 2. **Create tasks** via TaskCreate — one per participating agent 3. **Spawn agents in parallel** via Task tool. For each agent: a. Read the agent template: `modules/agents/<agent-name>.md` b. Read the source knowledge file(s) listed in the template's "Source Knowledge" section c. Construct the agent prompt by combining: - The full agent template (structure + evaluation criteria) - The full source knowledge content - The target context (screenshot/URL snapshot/code/brief) - Mode: "audit" - The scoring rubric content - Instructions to mark task complete and send report via SendMessage to "team-lead" ``` Task( name: "<agent-name>", team_name: "design-swarm", subagent_type: "general-purpose", run_in_background: true, prompt: [constructed prompt above] ) ``` 4. **Wait** for all agents to complete (they'll send reports via SendMessage) 5. **Synthesize** per orchestrator.md: - Collect all reports - Deduplicate findings - Aggregate by severity - Compute weighted composite score - Identify and resolve conflicts - Generate the final audit report 6. **Present** the synthesized audit report to the user #### Phase: Ideate 1. **Create tasks** for each agent (blocked by audit synthesis if audit was run) 2. **Spawn agents** with the same process as audit, but: - Mode: "ideate" - Include the synthesized audit findings in each agent's prompt - Each agent proposes improvements through their specific lens 3. **Synthesize** ideation proposals: - Merge overlapping proposals - Categorize by impact/effort matrix - Produce prioritized improvement roadmap 4. **Present** the improvement roadmap to the user #### Phase: Implement 1. **Spawn a single `general-purpose` agent** with: - The full synthesized audit report - The prioritized improvement roadmap - References to all relevant source skill files - Instructions to implement changes in priority order (critical → serious → moderate → minor) 2. **Present** implementation results to the user ### 6. Shutdown After all phases complete: 1. Send `shutdown_request` to all active agents 2. Call `TeamDelete` to clean up --- ## Agent Reference | Agent | Lens | Weight | Template | Source Knowledge | |-------|------|--------|----------|-----------------| | craft-philosophy | Principled reasoning, tiebreaker | 1.5 | `modules/agents/craft-philosophy.md` | `~/.claude/skills/design-craft/modules/craft-philosophy.md`, `~/.claude/skills/craft-philosophy/SKILL.md` | | foundations | Color, type, spacing, tokens | 1.0 | `modules/agents/foundations.md` | `~/.claude/skills/design-craft/modules/foundations.md` | | interaction | Forms, gestures, physics, a11y | 1.0 | `modules/agents/interaction.md` | `~/.claude/skills/design-craft/modules/interaction.md` | | composition | Layout, IA, content strategy | 1.0 | `modules/agents/composition.md` | `~/.claude/skills/design-craft/modules/composition.md` | | critique | 5-step systematic evaluation | 1.2 | `modules/agents/critique.md` | `~/.claude/skills/design-craft/modules/critique.md` | | interface-craft | Animation DSL, polish | 0.8 | `modules/agents/interface-craft.md` | `~/.agents/skills/interface-craft/SKILL.md` | | baseline-ui | Constraint enforcement | 1.0 | `modules/agents/baseline-ui.md` | `~/.agents/skills/baseline-ui/SKILL.md` | | frontend-design | Visual aesthetics | 1.0 | `modules/agents/frontend-design.md` | `~/Documents/samos/.claude/skills/frontend-design/SKILL.md` | | accessibility | WCAG, ARIA, focus | 1.2 | `modules/agents/accessibility.md` | `~/.agents/skills/fixing-accessibility/SKILL.md`, `~/.claude/skills/design-craft/modules/interaction.md` | | motion | Motion principles + performance | 0.8 | `modules/agents/motion.md` | `~/.local/share/claude-tools/design-motion-principles/skills/design-motion-principles/SKILL.md`, `~/.agents/skills/fixing-motion-performance/SKILL.md` | --- ## Usage Examples ``` /design-swarm audit ~/Desktop/screenshot.png /design-swarm audit ideate https://example.com /design-swarm audit ideate implement ./src/components/Settings.tsx /design-swarm ideate "dark mode settings panel with toggle, theme preview, and schedule" /design-swarm audit implement ./src/pages/Dashboard.tsx ``` --- ## Important Notes - **Runtime knowledge loading**: Agent templates are compact. Source knowledge is read fresh from canonical skill files at spawn time. This prevents knowledge duplication and ensures agents always use the latest skill content. - **Parallel execution**: All agents within a phase run simultaneously. Phases run sequentially when chained. - **Conflict resolution**: The craft-philosophy agent (weight 1.5) serves as tiebreaker. See orchestrator.md for the full protocol. - **Partial modes**: Any combination of modes is valid. `ideate` without prior `audit` uses the target directly (no findings context). `implement` without `ideate` applies audit findings directly.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.