# Cyan Usage Audit - Action 11.3.1.1

**Date**: 2025-01-27  
**Scope**: All `kodo-cyan` usage across the codebase  
**Total Instances**: 965 matches across 217 files

## Summary

Cyan is currently used extensively throughout the application. This audit categorizes usage to identify opportunities for reducing overuse and applying the 80/20 rule (80% neutral, 20% color).

## Categories

### 1. Primary Actions (✅ Keep Cyan)
**Purpose**: Main CTAs, primary interactive elements  
**Count**: ~150 instances

**Examples**:
- Button default variant: `bg-kodo-cyan` (primary CTAs)
- Active navigation states: `text-kodo-cyan`, `bg-kodo-cyan/10`
- Focus rings: `focus-visible:ring-kodo-cyan`
- Primary links and important actions
- Active tab indicators
- Selected states in lists

**Files**:
- `apps/web/src/components/ui/button.tsx` - Primary button variant
- `apps/web/src/components/layout/Sidebar.tsx` - Active nav items
- `apps/web/src/components/ui/tabs.tsx` - Active tabs
- `apps/web/src/pages/DashboardPage.tsx` - Primary actions
- `apps/web/src/features/library/pages/LibraryPage.tsx` - Primary filters/actions

### 2. Secondary Actions (⚠️ Replace with Steel)
**Purpose**: Non-primary buttons, hover states, borders  
**Count**: ~200 instances

**Examples**:
- Hover states on outline buttons: `hover:border-kodo-cyan/50`
- Secondary button borders
- Non-primary interactive elements
- Icon buttons (non-primary)
- Secondary navigation items

**Files**:
- `apps/web/src/components/ui/button.tsx` - Outline variant hover
- `apps/web/src/components/layout/Header.tsx` - Secondary nav items
- `apps/web/src/components/views/FileManagerView.tsx` - Secondary actions
- `apps/web/src/features/tracks/components/TrackFilters.tsx` - Filter buttons

### 3. Decorative/Background (⚠️ Reduce or Replace)
**Purpose**: Backgrounds, borders, decorative elements  
**Count**: ~300 instances

**Examples**:
- Backgrounds with opacity: `bg-kodo-cyan/10`, `bg-kodo-cyan/20`
- Decorative borders: `border-kodo-cyan/30`
- Empty state icons: `text-kodo-cyan`
- Section headers: `text-kodo-cyan`
- Card borders and highlights
- Progress indicators (non-critical)

**Files**:
- `apps/web/src/components/ui/KodoEmptyState.tsx` - Icon and border
- `apps/web/src/components/views/StudioView.tsx` - Decorative elements
- `apps/web/src/components/ui/progress.tsx` - Progress bars
- `apps/web/src/components/education/CourseCard.tsx` - Card decorations
- `apps/web/src/components/social/PostCard.tsx` - Card highlights

### 4. Informational (⚠️ Consider Steel or Keep)
**Purpose**: Info alerts, status indicators, metadata  
**Count**: ~150 instances

**Examples**:
- Info toasts: `bg-kodo-cyan/10 border-kodo-cyan/30`
- Status indicators
- Metadata highlights
- Info badges
- Loading spinners

**Files**:
- `apps/web/src/components/feedback/Toast.tsx` - Info variant
- `apps/web/src/components/feedback/Alert.tsx` - Info variant
- `apps/web/src/components/ui/Spinner.tsx` - Loading states
- `apps/web/src/components/OfflineIndicator.tsx` - Status indicator

### 5. Focus/Interaction States (✅ Keep Cyan)
**Purpose**: Focus rings, active states, keyboard navigation  
**Count**: ~100 instances

**Examples**:
- Focus rings: `focus-visible:ring-kodo-cyan`
- Active states: `active:bg-kodo-cyan`
- Keyboard navigation highlights
- Input focus states

**Files**:
- `apps/web/src/components/ui/input.tsx` - Focus states
- `apps/web/src/components/ui/select.tsx` - Focus states
- `apps/web/src/components/ui/checkbox.tsx` - Focus states
- All form components with focus rings

### 6. Text/Links (⚠️ Review Context)
**Purpose**: Text color, links, headings  
**Count**: ~65 instances

**Examples**:
- Links: `text-kodo-cyan hover:text-kodo-cyan`
- Headings: `text-kodo-cyan`
- Emphasized text
- Helper text

**Files**:
- `apps/web/src/components/layout/Header.tsx` - Links
- `apps/web/src/features/auth/components/TwoFactorVerify.tsx` - Links
- `apps/web/src/components/views/ProfileView.tsx` - Text highlights

## Recommendations

### High Priority (Action 11.3.1.2)
1. **Replace secondary action borders** with `kodo-steel`
   - Outline button hover states
   - Secondary navigation borders
   - Non-primary card borders

2. **Reduce decorative backgrounds**
   - Replace `bg-kodo-cyan/10` with `bg-kodo-steel/10` for non-primary elements
   - Keep cyan backgrounds only for primary CTAs and active states

3. **Update empty state icons**
   - Consider using `kodo-steel` for decorative icons
   - Keep cyan only for actionable icons

### Medium Priority
4. **Review informational elements**
   - Consider using `kodo-steel` for info alerts (non-critical)
   - Keep cyan for success/important info

5. **Audit text/links**
   - Replace non-primary links with steel
   - Keep cyan for primary navigation links

### Low Priority
6. **Maintain primary actions**
   - Keep all primary button variants
   - Keep active navigation states
   - Keep focus rings

## Target Distribution (80/20 Rule)

**Current**: ~40% cyan usage (estimated)  
**Target**: ~20% cyan usage

**Breakdown**:
- **80% Neutral**: Use `kodo-steel`, `kodo-graphite`, `kodo-ink` for backgrounds, borders, secondary elements
- **20% Color**: Use `kodo-cyan` only for:
  - Primary CTAs
  - Active states
  - Focus rings
  - Critical status indicators
  - Primary navigation

## Files Requiring Changes

### High Impact (Many instances):
1. `apps/web/src/components/ui/button.tsx` - Button variants
2. `apps/web/src/components/layout/Sidebar.tsx` - Navigation
3. `apps/web/src/components/views/StudioView.tsx` - Decorative elements
4. `apps/web/src/components/ui/KodoEmptyState.tsx` - Empty states
5. `apps/web/src/components/views/FileManagerView.tsx` - Secondary actions
6. `apps/web/src/features/tracks/components/TrackFilters.tsx` - Filters
7. `apps/web/src/components/education/CourseCard.tsx` - Cards
8. `apps/web/src/components/social/PostCard.tsx` - Cards

### Medium Impact:
- All view components with decorative cyan
- Form components with secondary cyan borders
- Card components with cyan highlights

## Next Steps

1. ✅ **Action 11.3.1.1**: Audit complete
2. ⏭️ **Action 11.3.1.2**: Replace secondary cyan with steel (non-primary actions)
3. ⏭️ **Action 11.3.1.3**: Apply 80/20 rule (80% neutral, 20% color)

## Notes

- This audit is based on pattern matching and may require manual review for context-specific decisions
- Some decorative uses may be intentional for brand consistency
- Focus states and active states should remain cyan for accessibility
- Primary CTAs must remain cyan for clear visual hierarchy