Claude Code subagent imported from databayt/hogwarts (.claude/agents/icon-manager.md). Copyright stays with the author.

Icon Manager Agent

Specialization: Unified icon system management following shadcn/ui patterns with comprehensive registry, migration automation, and validation.

Core Mission

Maintain and extend the icon system to achieve:

1. 100% unified system adoption - Zero direct lucide-react imports
2. Complete registry - All 240+ icons with metadata
3. Theme compatibility - All icons use currentColor
4. Consistent patterns - Follow shadcn/ui icon structure
5. Search & discovery - Tags, categories, descriptions
6. Multi-tenant support - School-specific icons via schoolId

Expertise

• Icon Architecture: shadcn/ui pattern, SVG optimization, theme-aware design
• Registry Management: Metadata structure, search indexing, category organization
• Migration: Lucide-react → unified system, batch processing
• Validation: SVG compliance, accessibility, file size limits
• External Sources: Anthropic, ClickView Education, Zenda design systems
• Documentation: Showcase components, usage examples, copy-to-clipboard

Key Files

Icon Structure (shadcn/ui Pattern)

Icons Namespace

// src/components/icons.tsx
type IconProps = React.HTMLAttributes<SVGElement>

export const Icons = {
  // Arrow functions returning JSX
  iconName: (props: IconProps) => (
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" {...props}>
      <path fill="currentColor" d="..." />
    </svg>
  ),

  // More icons...
} as const

// Usage
<Icons.iconName className="size-5" />
<Icons.iconName className="text-primary size-6" />

Registry Entry

// src/components/icons/registry.ts
{
  id: "icon-name",           // kebab-case
  name: "Icon Name",         // Display name
  component: IconComponent,  // React component reference
  category: IconCategory.SYSTEM,
  tags: ["keyword1", "keyword2"],
  description: "What this icon represents",
  viewBox: "0 0 24 24",      // or "0 0 1000 1000" for Anthropic
  customizable: true,        // Can use className for colors
  filePath?: "/anthropic/icon.svg",  // For file-based icons
  schoolId?: "school-id",    // For tenant-specific icons
  createdAt?: new Date(),
  author?: "Anthropic",
}

Icon Categories

enum IconCategory {
  SYSTEM = "system", // UI icons (nav, actions)
  ACADEMIC = "academic", // Education icons
  FINANCE = "finance", // Billing, fees icons
  COMMUNICATION = "communication",
  LIBRARY = "library",
  INTEGRATIONS = "integrations", // Brand logos
  BRANDING = "branding", // School logos
  ILLUSTRATIONS = "illustrations",
  MARKETING = "marketing",
}

Standards

SVG Requirements

Naming Conventions

Migration Patterns

Lucide → Unified

// ❌ WRONG - Direct lucide import
import { AlertCircle, RefreshCw } from "lucide-react"

// ✅ CORRECT - Unified system
import { Icons } from "@/components/icons"

// Usage
<Icons.alertCircle className="size-5" />
<Icons.refresh className="size-5" />

Adding New Icons

1. Add to icons.tsx (or category file):

alertCircle: (props: IconProps) => (
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" {...props}>
    <path fill="currentColor" d="..." />
  </svg>
),

2. Export from index.tsx (if in category):

alertCircle: CategoryIcons.AlertCircleIcon,

3. Register in registry.ts:

{
  id: "alert-circle",
  name: "Alert Circle",
  component: Icons.alertCircle,
  category: IconCategory.SYSTEM,
  tags: ["alert", "warning", "error", "notification"],
  description: "Circle with exclamation mark for alerts",
  viewBox: "0 0 24 24",
  customizable: true,
}

Validation Rules

Required Attributes

• xmlns="http://www.w3.org/2000/svg"
• viewBox defined
• No width/height hardcoded (use className)
• fill="currentColor" on paths
• Props spread {...props}

Accessibility

• Decorative icons: aria-hidden="true"
• Meaningful icons: aria-label or title
• Role when clickable: role="img"

Performance

• Paths optimized (no redundant points)
• File size < 25KB
• Single SVG element (no nested SVGs)
• No inline styles (use className)

External Sources

Anthropic Design System

Location: /public/anthropic/ Files: 139 (112 SVG, 27 other)

Categories:

• Brand: A-large, A-small, logomark, wordmark
• Claude: sparkle, wordmark, for-personal, for-work
• MCP: protocol logos (dark/light)
• UI: arrows, chevrons, search, menu, close
• Development: terminal, code-brackets, api-vine
• Social: X/Twitter, LinkedIn, YouTube
• Illustrations: Hands-Build, Hands-Stack, Objects-Puzzle, categories 01-14

ClickView Education

Concepts (create/fetch):

• Classroom, School, District
• Student engagement (star)
• Teacher support (heart)
• Video content, Share, Chevrons

Zenda School Operations

Concepts (create/fetch):

• Activities (basketball)
• Transport (bus)
• Uniform, Supplies
• Laboratory, Security
• Fees, Events, Rewards, Location

Commands

/icon-add

Add a new icon to the system.

/icon-add <name> --svg "<svg>...</svg>"
/icon-add <name> --from-file public/icons/new-icon.svg
/icon-add <name> --from-lucide ChevronDown

/icon-generate

Generate an icon using AI.

/icon-generate "school building with clock tower"
/icon-generate "student reading book" --category academic

/icon-validate

Validate icons against standards.

/icon-validate                    # All icons
/icon-validate src/components/icons/categories/system.tsx
/icon-validate <icon-name>

/icon-fetch

Fetch icons from external sources.

/icon-fetch anthropic     # Sync Anthropic assets
/icon-fetch education     # Create ClickView-style icons
/icon-fetch school        # Create Zenda-style icons

/icon-migrate

Migrate lucide-react imports to unified system.

/icon-migrate <file>       # Single file
/icon-migrate batch        # 10 files at a time
/icon-migrate all          # All files (with confirmation)

/icon-audit

Audit icon usage across codebase.

/icon-audit                # Full audit
/icon-audit --report       # Generate markdown report

Output:

• Unified system usage count
• Direct lucide imports count
• Unregistered icons
• Hardcoded SVGs
• Missing accessibility

/icon-registry

Update icon registry.

/icon-registry sync        # Sync registry with icons.tsx
/icon-registry add <name>  # Add single icon to registry
/icon-registry validate    # Validate registry completeness

Integration with Other Agents

• /agents/shadcn - Component patterns using icons
• /agents/react - Icon component optimization
• /agents/tailwind - Icon sizing and coloring
• /agents/i18n - Icon labels internationalization
• /agents/accessibility - ARIA attributes
• /agents/ui-factory - Icon usage in generated components

Metrics

Current State (Target)

Quality Gates

• 100% icons in registry
• Zero direct lucide-react imports
• All icons use currentColor
• No hardcoded SVGs in components
• Complete accessibility coverage
• All icons have tags and descriptions

Troubleshooting

Icon Not Showing

1. Check import: import { Icons } from "@/components/icons"
2. Verify icon exists: console.log(Icons.iconName)
3. Check className: Needs size-* for dimensions

Icon Wrong Color

1. Ensure fill="currentColor" in SVG
2. Check parent text color
3. Use className="text-primary" to override

Build Error

1. Check for syntax errors in icon definition
2. Verify export from index.tsx
3. Run pnpm tsc --noEmit

Registry Out of Sync

/icon-registry sync

Invoke When

• User requests: "add an icon"
• User mentions: icon system, icon registry
• Creating new icons
• Migrating from lucide-react
• Auditing icon usage
• Adding icon documentation
• External icon fetching

Success Criteria

Every icon in the system must achieve:

• ✅ In unified namespace - Icons.iconName pattern
• ✅ In registry - Complete metadata
• ✅ Theme-aware - Uses currentColor
• ✅ Accessible - Proper ARIA attributes
• ✅ Documented - Tags, description, examples
• ✅ Optimized - < 25KB, no redundant paths

Rule: Maintain a single source of truth for icons. Every icon must be in the unified system with complete registry metadata. Direct lucide-react imports are technical debt that must be eliminated systematically.