headquarter/openspec/changes/archive/2026-05-19-universal-icon-system/design.md

Universal Icon System - Design

Architecture

Icon System
├── Icon Component (centralized wrapper)
│   ├── Size variants: sm, md, lg, xl
│   ├── Color: inherited or explicit
│   └── Accessibility: aria-label, role
├── Icon Registry (mapping names to Phosphor icons)
└── Usage throughout app
    ├── Navigation icons
    ├── Action icons
    ├── Status indicators
    └── Git operation icons

Component Design

Icon Component

Props:

interface IconProps {
  name: IconName;
  size?: "sm" | "md" | "lg" | "xl";
  color?: string;
  weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone";
  className?: string;
  ariaLabel?: string;
}

Size Mapping:

• sm: 16px
• md: 20px (default)
• lg: 24px
• xl: 32px

Color:

• Default: inherits from parent via currentColor
• Explicit: uses CSS variable or direct color value

Icon Registry

Categories:

Navigation:

• home - Dashboard
• projects - Projects list
• repositories - Git repositories
• settings - User settings
• profile - User profile

Actions:

• add - Create new
• edit - Edit item
• delete - Delete item
• save - Save changes
• cancel - Cancel action
• refresh - Refresh/reload
• copy - Copy to clipboard

Status:

• success - Checkmark
• error - X mark
• warning - Warning triangle
• info - Information circle
• loading - Spinner

Git Operations:

• branch - Git branch
• commit - Git commit
• merge - Merge branches
• history - Commit history
• pull - Pull changes
• push - Push changes

Files:

• file - Generic file
• folder - Directory
• code - Code file
• document - Text document

Migration Plan

Phase 1: Setup

1. Install @phosphor-icons/react
2. Create Icon component
3. Create icon registry mapping

Phase 2: Replace Raw Unicode

Replace all instances of raw Unicode symbols:

• ✓ → Icon name="check"
• ✗ → Icon name="x"
• ⚠ → Icon name="warning"
• ● → Icon name="dot"
• ❓ → Icon name="question"
• ↓ → Icon name="arrow-down"

Phase 3: Update Components

Update existing components to use icon system:

• GitToolbar
• GitRepositoriesPage
• FileEditor
• AppShell navigation
• Dialog buttons
• Form validation indicators

Phase 4: Styling

• Ensure consistent spacing around icons
• Add hover states where applicable
• Maintain alignment with text

Accessibility

• All icons have meaningful aria-label
• Decorative icons use aria-hidden="true"
• Focus indicators for interactive icons
• Sufficient color contrast

Technical Details

Library: @phosphor-icons/react Bundle Impact: Tree-shakeable, ~2KB per icon used Browser Support: All modern browsers Fallback: None needed - SVG-based, always renders

CSS Integration

.icon {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  flex-shrink: 0;
}

.icon-sm { width: 16px; height: 16px; }
.icon-md { width: 20px; height: 20px; }
.icon-lg { width: 24px; height: 24px; }
.icon-xl { width: 32px; height: 32px; }

/* Inherit color from parent */
.icon svg {
  fill: currentColor;
}