puffpastry-frontend/.junie/plans/modernize-icon-system.md

---
sessionId: session-261002-165538-pjxq
---

# Requirements

### Overview & Goals
The objective of this initiative is to replace the fragmented, ad-hoc SVG icon implementations in `src/components/icons/` with a high-utility, predictable, and performant Vue 3 icon architecture. 

Currently, icons in the project are implemented with substantial inconsistencies:
- Several icons wrap raw SVG markup inside container `<div>` tags with hardcoded layout properties (e.g., `class="h-4 w-4 cursor-pointer mx-2"`).
- Other icons render raw SVG tags with inconsistent prop contracts (e.g., `:box="96"` vs `:viewBox="36"` vs `:width="20"` vs hardcoded inline styles).
- Fills, strokes, and hover behaviors are frequently hardcoded in scoped CSS or inline SVG attributes, preventing utility classes (Tailwind CSS `text-*`, `fill-current`, `stroke-current`, `size-*`) from controlling colors and dimensions naturally.

This proposal establishes a standardized, tree-shakeable, and type-safe icon system designed to maximize developer throughput, eliminate styling friction, reduce bundle waste, and ensure complete accessibility compliance.

### Scope

#### In Scope
- **Foundation Layer**: Create an extensible, typed `IconBase.vue` component and `types.ts` defining standard icon contracts (`IconName`, `IconSize`, sizing scales, accessibility attributes).
- **Icon Normalization**: Refactor all 14 existing icon components (`Abstain`, `Arrow`, `Cancel`, `Confirm`, `DownArrow`, `Download`, `Filter`, `Identification`, `Menu`, `Plus`, `SpeechBubbles`, `Stack`, `ThumbsDown`, `ThumbsUp`) into pure SVG components using `currentColor` and consistent viewBox geometries.
- **Dynamic Registry**: Create a unified `AppIcon.vue` for dynamic runtime icon rendering and `src/components/icons/index.ts` for clean tree-shakeable named exports.
- **Call-Site Migration**: Refactor all 8 consuming components and views (`Sidebar.vue`, `ProposalContainer.vue`, `ProposalDetail.vue`, `ProposalExportCard.vue`, `ProposalVotingCard.vue`, `VotingControls.vue`, `AmendmentCarousel.vue`, `HomeView.vue`) to use the new icon interfaces and standard Tailwind classes.
- **Build & Quality Assurance**: Ensure zero TypeScript errors (`vue-tsc`), clean Vite builds, and consistent rendering across light/dark backgrounds and responsive viewport sizes.

#### Out of Scope
- Introducing external heavyweight icon packages or third-party web font libraries that would increase bundle size or external network dependencies.
- Modifying non-icon business logic, wallet integrations, or backend API service definitions.

### User Stories
- **As a Developer**, I want all icons to behave as first-class Vue components with uniform props and `currentColor` support so that I can style their size, color, and hover states directly using Tailwind CSS without fighting inner scoped CSS or arbitrary wrapper `<div>`s.
- **As a Developer**, I want autocompletion and type checking when specifying icon names so that runtime icon typos and missing assets are caught at compile time.
- **As an End User**, I want all icons to render crisply, scale smoothly across devices, and support screen readers properly so that UI interactions are fast, intuitive, and accessible.

### Functional Requirements
- **FR-1: Standardized Root Element**: Every individual icon component must render a semantic `<svg>` root element without superfluous wrapper `<div>` elements.
- **FR-2: Sizing Flexibility**: Icons must accept standardized size presets (`'xs' | 'sm' | 'md' | 'lg' | 'xl'`), numerical/pixel dimensions, or inherit sizing directly from standard Tailwind classes (`size-4`, `w-5 h-5`).
- **FR-3: Color & Theme Inheritance**: Icons must inherit foreground colors from their parent container by default via `fill="currentColor"` or `stroke="currentColor"`, allowing instant theme adaptations (`text-slate-500`, `hover:text-green-500`, `fill-amber-500`).
- **FR-4: Dynamic & Direct Imports**: The system must support direct named component imports (e.g., `import { IconFilter } from '@/components/icons'`) and dynamic component resolution (e.g., `<AppIcon name="filter" />`).
- **FR-5: Accessibility Support**: Decorative icons must default to `aria-hidden="true"`, while standalone interactive or informational icons must support customizable `title` and `role="img"` attributes.

### Non-Functional Requirements
- **Performance**: Zero runtime overhead from external bundle bloat; SVG trees must remain tree-shakeable and lightweight.
- **Type Safety**: Fully typed with TypeScript 5+ and Vue 3 `<script setup>` compiler macros.
- **Maintainability**: Clear separation of concern between icon vector geometries and presentation styles. Adding a new icon must require minimal boilerplate.

# Technical Design

### Current Implementation
The current codebase contains 14 icon files located in `src/components/icons/`:
- `DownArrow.vue`, `Filter.vue`, `Identification.vue`, `Menu.vue`, `Plus.vue`, and `SpeechBubbles.vue` contain outer `<div class="h-4 w-4 cursor-pointer mx-2">` wrappers, hardcoding margins, cursor behavior, and dimensions inside the icon definition.
- `Abstain.vue`, `Cancel.vue`, and `Confirm.vue` define custom `withDefaults(defineProps<{ box?: number; width?: number | string; height?: number | string }>())` props but hardcode geometry coordinates.
- `Stack.vue` defines `:viewBox="0 0 ${viewBox} ${viewBox}"` (defaulting to 90) but hardcodes `style="width: 20px; height: 20px;"` and `fill="white"`.
- `Arrow.vue` hardcodes `style="width: 10px; height: 20px;"`.
- `SpeechBubbles.vue` and `DownArrow.vue` include scoped CSS with ID selectors and `!important` color overrides (`#down-arrow:hover`, `#speech-bubbles:hover`), preventing Tailwind styling from parent components.
- Consuming components (`VotingControls.vue`, `ProposalVotingCard.vue`, `ProposalExportCard.vue`, `AmendmentCarousel.vue`, `Sidebar.vue`, `ProposalContainer.vue`, `ProposalDetail.vue`, `HomeView.vue`) use incompatible styling workarounds (e.g., manual `:box="96"`, inline style overrides, or duplicate Tailwind wrapper classes).

### Key Decisions
1. **First-Class Vue SVG Components with `IconBase` Wrapper**:
   - *Decision*: Standardize each icon as a dedicated Vue component composed around a lightweight `IconBase.vue` (or direct standardized `<svg>` element) using `currentColor`.
   - *Rationale*: Eliminates unwanted DOM nesting (`<div>` wrapping `<svg>`), allows full Tailwind utility class passthrough (`class="..."` directly targets `<svg>`), and ensures maximum rendering performance and tree-shakability without external package bloat.
2. **Unified `AppIcon.vue` Dynamic Component**:
   - *Decision*: Provide an `AppIcon.vue` component that maps an `IconName` string union to the corresponding icon component.
   - *Rationale*: Gives developers the choice between static named component imports (best for explicit, statically analyzable components) and dynamic string-based icon rendering (best for config-driven UI, tables, or iteration).
3. **Tailwind-First Sizing & Color Design**:
   - *Decision*: Default icon dimensions to `1em` (or preset sizes) and `currentColor` fill/stroke, allowing standard Tailwind classes (`size-4`, `text-slate-400`, `hover:text-amber-500`) to govern appearance effortlessly.
   - *Rationale*: Maximizes developer utility by keeping icon styling consistent with all other UI components in Tailwind CSS.

### Proposed Architecture & Flow

```mermaid
graph TD
    subgraph Consumers
        A[Sidebar.vue]
        B[VotingControls.vue]
        C[ProposalVotingCard.vue]
        D[AmendmentCarousel.vue]
        E[ProposalContainer.vue]
        F[Other Views / Modals]
    end

    subgraph Icon System Layer
        G[AppIcon.vue Dynamic Component]
        H[Named Exports in icons/index.ts]
        I[IconBase.vue Core Sizing & A11y Wrapper]
    end

    subgraph Icon Definitions
        J[IconAbstain.vue]
        K[IconConfirm.vue]
        L[IconCancel.vue]
        M[IconFilter.vue]
        N[IconDownload.vue]
        O[IconIdentification.vue]
        P[Other 8 SVG Icons...]
    end

    A & B & C & D & E & F -->|Static Named Import| H
    A & B & C & D & E & F -->|Dynamic Name Prop| G
    G --> H
    H --> J & K & L & M & N & O & P
    J & K & L & M & N & O & P -->|Composes / Inherits| I
```

### Data Models / Contracts

#### `src/components/icons/types.ts`
```typescript
export type IconName =
  | 'abstain'
  | 'arrow'
  | 'cancel'
  | 'confirm'
  | 'down-arrow'
  | 'download'
  | 'filter'
  | 'identification'
  | 'menu'
  | 'plus'
  | 'speech-bubbles'
  | 'stack'
  | 'thumbs-down'
  | 'thumbs-up';

export type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number | string;

export interface IconBaseProps {
  size?: IconSize;
  viewBox?: string;
  title?: string;
  ariaHidden?: boolean;
  role?: string;
}
```

#### `src/components/icons/IconBase.vue`
```vue
<template>
  <svg
    xmlns="http://www.w3.org/2000/svg"
    :viewBox="viewBox"
    :width="computedSize"
    :height="computedSize"
    :aria-hidden="title ? undefined : ariaHidden"
    :aria-label="title"
    :role="title ? 'img' : (role || 'presentation')"
    class="inline-block shrink-0 align-middle select-none fill-current"
  >
    <title v-if="title">{{ title }}</title>
    <slot />
  </svg>
</template>

<script setup lang="ts">
import { computed } from 'vue';
import type { IconBaseProps } from './types';

const props = withDefaults(defineProps<IconBaseProps>(), {
  viewBox: '0 0 24 24',
  ariaHidden: true,
  size: 'md',
});

const sizeMap: Record<string, string> = {
  xs: '12',
  sm: '16',
  md: '20',
  lg: '24',
  xl: '32',
};

const computedSize = computed(() => {
  if (typeof props.size === 'number') return props.size;
  return sizeMap[props.size] || props.size;
});
</script>
```

### File Structure & Changes

```
src/
├── components/
│   ├── icons/
│   │   ├── types.ts                   # [NEW] IconName, IconSize, Prop interfaces
│   │   ├── IconBase.vue               # [NEW] Common SVG wrapper component
│   │   ├── AppIcon.vue                # [NEW] Dynamic icon component resolver
│   │   ├── index.ts                   # [NEW] Centralized export entry point
│   │   ├── Abstain.vue                # [REFACTORED] Standardized SVG component
│   │   ├── Arrow.vue                  # [REFACTORED] Standardized SVG component
│   │   ├── Cancel.vue                 # [REFACTORED] Standardized SVG component
│   │   ├── Confirm.vue                # [REFACTORED] Standardized SVG component
│   │   ├── DownArrow.vue              # [REFACTORED] Removed wrapper div & CSS overrides
│   │   ├── Download.vue               # [REFACTORED] Standardized SVG component
│   │   ├── Filter.vue                 # [REFACTORED] Removed wrapper div & CSS overrides
│   │   ├── Identification.vue         # [REFACTORED] Removed wrapper div & standardized viewBox
│   │   ├── Menu.vue                   # [REFACTORED] Removed wrapper div & standardized stroke/fill
│   │   ├── Plus.vue                   # [REFACTORED] Removed wrapper div
│   │   ├── SpeechBubbles.vue          # [REFACTORED] Removed wrapper div & CSS overrides
│   │   ├── Stack.vue                  # [REFACTORED] Standardized viewBox & removed hardcoded fill
│   │   ├── ThumbsDown.vue             # [REFACTORED] Standardized SVG component
│   │   └── ThumbsUp.vue               # [REFACTORED] Standardized SVG component
│   ├── AmendmentCarousel.vue          # [UPDATED] Clean icon props & Tailwind classes
│   ├── ProposalContainer.vue          # [UPDATED] Clean icon sizing without wrapper conflicts
│   ├── ProposalDetail.vue             # [UPDATED] Clean icon sizing without wrapper conflicts
│   ├── ProposalExportCard.vue         # [UPDATED] Clean icon props & transitions
│   ├── ProposalVotingCard.vue         # [UPDATED] Removed obsolete :box props; standardized colors
│   ├── Sidebar.vue                    # [UPDATED] Replaced wrapped Filter with clean SVG icon
│   └── VotingControls.vue             # [UPDATED] Clean Tailwind fill & hover state integration
└── views/
    └── HomeView.vue                   # [UPDATED] Clean Stack icon styling
```

### Risks & Mitigations
- **Risk**: Visual regression if existing viewBox ratios or path alignments change during normalization.
  - *Mitigation*: Preserve the exact vector path strings and original coordinate spaces (`viewBox="0 0 30 30"`, `0 0 96 96"`, etc.) for each respective icon inside its component definition, ensuring 100% pixel-perfect output.
- **Risk**: Missing layout spacing when removing wrapper divs (e.g. `mx-2`, `cursor-pointer`).
  - *Mitigation*: Move layout concerns (`mx-2`, `cursor-pointer`, flex alignments) directly to the consuming container or parent button elements at all call sites.

# Testing

### Validation Approach
Verification will follow a multi-tier approach to ensure structural, aesthetic, and functional correctness across the application:
1. **Static Type & Lint Validation**: Verify strict type conformity via TypeScript compiler (`vue-tsc -b`) to ensure no broken imports or invalid prop bindings exist.
2. **Component Integration & Build Validation**: Perform full production bundling (`vite build`) to confirm zero asset resolution issues or tree-shaking failures.
3. **Visual & Interaction Verification**: Validate icon rendering across all consuming views, checking sizing, color inheritance, hover states, and responsive behavior.

### Key Scenarios
- **Scenario 1: Dynamic Icon Rendering (`AppIcon`)**:
  - Render `<AppIcon name="confirm" class="text-green-500" />` and `<AppIcon name="cancel" class="text-red-500" />`.
  - Expected: Correct SVGs render with specified colors, inheriting parent classes properly without extra container nodes.
- **Scenario 2: Direct Component Import & Tailwind Utility Sizing**:
  - Render `<IconFilter class="size-4 text-white hover:text-slate-200" />` in `Sidebar.vue`.
  - Expected: Icon scales to 16x16px, displays in white, and transitions to light slate on hover without unwanted wrapper margins.
- **Scenario 3: Interactive Voting Controls & Active States**:
  - In `VotingControls.vue` and `ProposalVotingCard.vue`, trigger approval and rejection vote states.
  - Expected: `Confirm` and `Cancel` icons respond dynamically to positive/negative vote states (`fill-green-500`, `fill-red-500`) with smooth transitions.
- **Scenario 4: Carousel Navigation Chevrons**:
  - In `AmendmentCarousel.vue`, navigate through amendments using the left and right arrow buttons.
  - Expected: `Arrow` icon renders crisply, rotates correctly with Tailwind's `rotate-180` for left navigation, and responds to click events.

### Edge Cases
- **Custom Dimension Overrides**: Passing explicit numeric `size={28}` or arbitrary Tailwind strings (`class="w-7 h-7"`) must scale SVG viewports smoothly without clipping.
- **Accessibility Verification**: When `title` is supplied, `<svg>` must render a `<title>` node and set `role="img"`; when omitted, it must set `aria-hidden="true"`.
- **Empty or Missing Styling**: Icons with no explicit color class must default to `currentColor`, seamlessly adopting surrounding text color.

# Delivery Steps

### ✓ Step 1: Establish IconBase and type system
A unified `IconBase.vue` component and type definitions are created to serve as the standardized foundation for all project icons.

- Define TypeScript contracts and type definitions in `src/components/icons/types.ts` (`IconName`, `IconSize`, `IconBaseProps`).
- Create `src/components/icons/IconBase.vue` rendering a semantic `<svg>` root element with default classes (`inline-block shrink-0 align-middle select-none`), standardized sizing mapping (`xs`: 12px, `sm`: 16px, `md`: 20px, `lg`: 24px, `xl`: 32px or custom dimensions), `currentColor` inheritance, and accessibility attributes (`aria-hidden`, `role="img"`, `title`).
- Create `src/components/icons/AppIcon.vue` providing dynamic lookup and rendering of icons by name with full type safety and prop forwarding.

### ✓ Step 2: Refactor and normalize all icon components
All 14 icon components are refactored into clean, single-element SVG components adhering to the standardized base interface.

- Remove extraneous `<div>` wrapper containers and hardcoded margins (`mx-2`) from `DownArrow.vue`, `Filter.vue`, `Identification.vue`, `Menu.vue`, `Plus.vue`, and `SpeechBubbles.vue`.
- Eliminate hardcoded inline styles (`style="fill:#ffffff"`, `style="width: 10px; height: 20px;"`) and scoped hover overrides (`#speech-bubbles:hover`, `#down-arrow:hover`) in favor of standard `currentColor` / Tailwind class pass-through.
- Standardize viewBox definitions and geometry across `Abstain.vue`, `Arrow.vue`, `Cancel.vue`, `Confirm.vue`, `Download.vue`, `Stack.vue`, `ThumbsDown.vue`, `ThumbsUp.vue`, and other icons.
- Create `src/components/icons/index.ts` exporting all icon components as named exports, the dynamic `AppIcon` component, and relevant TypeScript types for streamlined imports.

### ✓ Step 3: Migrate consuming components to modernized icons
All existing UI components and views are updated to consume the normalized icon system cleanly with Tailwind styling.

- Update `src/components/Sidebar.vue` to use `<Filter />` (or `<IconFilter />`) cleanly inside navigation buttons without unwanted wrapper margins.
- Update `src/components/ProposalContainer.vue` and `src/components/ProposalDetail.vue` to render `Identification` with proper dimensions and colors.
- Update `src/components/VotingControls.vue` and `src/components/ProposalVotingCard.vue` to remove obsolete `:box` / `:width` / `:height` props from `Confirm`, `Cancel`, and `Abstain`, styling them with Tailwind classes (`size-5 text-green-500 hover:text-green-600 fill-current`).
- Update `src/components/AmendmentCarousel.vue` and `src/components/ProposalExportCard.vue` to use standard arrow and download icons with seamless transition and hover effects.
- Update `src/views/HomeView.vue` to replace inline styles on `Stack` with standard component props/classes.

### ✓ Step 4: Verify build integrity, visual fidelity, and accessibility
The modernized icon system is validated across TypeScript compilation, build pipeline, and UI rendering.

- Execute `vue-tsc -b` and `vite build` to guarantee zero type errors or broken import references across the application.
- Verify visual fidelity, color transitions, hover states, and responsive layout scaling across all pages (Home, Proposal Detail, Voting modal, Carousel).
- Ensure accessibility tags (`aria-hidden="true"` on decorative icons and appropriate labels on interactive icon buttons) work correctly without DOM nesting violations.