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

Universal Icon System Specification

Requirements

Functional Requirements

1. Icon Component: Centralized Icon component that wraps Phosphor icons
2. Icon Registry: Mapping of logical names to Phosphor icon components
3. Size Variants: Support for sm (16px), md (20px), lg (24px), xl (32px)
4. Color Inheritance: Default to currentColor, support explicit colors
5. Accessibility: Proper ARIA labels and roles
6. Tree Shaking: Only include icons that are actually used

Non-Functional Requirements

1. Bundle Size: Minimal impact (~2KB per icon weight variant)
2. Performance: No layout shift, instant rendering
3. Browser Support: All modern browsers (Chrome, Firefox, Safari, Edge)
4. Consistency: Identical rendering across all platforms

Icon Registry

Navigation Icons

• dashboard → House
• projects → Folder
• repositories → GitBranch
• settings → Gear
• profile → User
• logout → SignOut

Action Icons

• add → Plus
• edit → PencilSimple
• delete → Trash
• save → FloppyDisk
• cancel → X
• refresh → ArrowsClockwise
• copy → Copy
• search → MagnifyingGlass
• menu → List
• close → X

Status Icons

• success → Check
• error → X
• warning → Warning
• info → Info
• loading → Spinner

Git Icons

• branch → GitBranch
• commit → GitCommit
• merge → GitMerge
• history → ClockCounterClockwise
• pull → ArrowDown
• push → ArrowUp
• fetch → ArrowsClockwise

File Icons

• file → File
• folder → Folder
• code → Code
• document → FileText
• image → Image
• binary → FileBinary

Migration Checklist

Components to Update

• app-shell.tsx - Navigation icons
• git-toolbar.tsx - Git operation icons
• git-repositories.tsx - Status/validation icons
• repo-workspace.tsx - File tree icons
• file-editor.tsx - File type icons
• dashboard.tsx - Dashboard icons
• projects.tsx - Project action icons
• settings.tsx - Settings icons
• tool-types.tsx - Tool type icons
• ssh-keys.tsx - Key management icons
• profile.tsx - Profile icons
• commit-dialog.tsx - Dialog icons
• syntax-highlighter.tsx - Copy icon
• code-editor.tsx - Edit icons
• All button components with icons

CSS Requirements

.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; }

Accessibility Requirements

1. All functional icons must have aria-label
2. Decorative icons must have aria-hidden="true"
3. Interactive icons must be focusable
4. Color contrast ratio ≥ 4.5:1

Dependencies

• @phosphor-icons/react - React component library