puffpastry-frontend/.junie/plans/style-amendment-carousel-cards.md

---
sessionId: session-261005-163409-12mw
---

# Requirements

### Overview & Goals
Enhance the visual design, contrast hierarchy, and layout ergonomics of the amendment cards inside `AmendmentCarousel.vue`. The carousel cards will feature a distinct yet gentle contrast against the surrounding background surface, cleaner typography, well-proportioned padding, refined interactive states, and consistent styling with the rest of the application's design system.

### Scope
- **In Scope**:
  - Updating the background color, borders, shadows, and hover transitions of amendment cards in `AmendmentCarousel.vue`.
  - Harmonizing the visual contrast between the carousel track and card surfaces.
  - Improving card internal typography (header font, summary line height, status chip positioning).
  - Enhancing action buttons (confirm/reject) and bottom fade gradients.
  - Modernizing the "Add Amendment" placeholder card to match dimensions and visual hierarchy.
  - Refining carousel navigation arrow buttons and keyboard focus states.
- **Out of Scope**:
  - Changes to underlying backend API schemas or data models.
  - Functional logic changes to amendment creation or voting workflows.

### User Stories
- **As a user reading proposals**, I want amendment cards to stand out clearly from the page background with balanced contrast and legible text so that I can quickly review proposed changes without visual fatigue.
- **As a voter/reviewer**, I want interactive elements (confirm, reject, card click, add amendment) to have intuitive hover and focus feedback so that navigating and acting upon amendments is efficient and error-free.

### Functional & Visual Requirements
- **Card Contrast & Surface**: Amendment cards must have a defined surface (`bg-white` / `bg-slate-50`) paired with subtle bordering (`border border-slate-200`) and soft shadow elevation (`shadow-xs` / `shadow-sm`) to ensure clear separation from neutral carousel containers.
- **Spacing & Proportions**: Inner card padding must expand from the current tight `px-2 py-1` to a balanced `p-3.5` or `p-4`, ensuring adequate breathing room for content.
- **Typography & Details**:
  - Card title formatted cleanly using header font styles with proper wrapping/truncation.
  - Status chips positioned with uniform margin and alignment.
  - Multi-line summary truncated with a fading gradient that dynamically matches the card surface during hover transitions.
- **Action Buttons**: Quick-action confirm and reject icons sized appropriately with accessible hover backgrounds and contrast colors.
- **"Add Amendment" Card**: Styled with dashed borders, matching border radii and heights, and harmonious amber highlight accents upon hover.
- **Navigation Controls**: Left/right carousel scroll buttons updated with modern rounded borders, backdrop blur, and distinct focus rings.

# Technical Design

### Current Implementation
In `src/components/AmendmentCarousel.vue`, the amendment card currently uses:
- `class="w-36 md:w-72 lg:w-80 shrink-0 rounded-md shadow-lg px-2 py-1 cursor-pointer hover:bg-amber-50 transition-colors"`
- Missing an explicit base background color, causing inconsistent contrast against different page container backgrounds (`bg-gray-200` in `App.vue`, `ProposalDetail.vue` sections).
- Cramped internal padding (`px-2 py-1`) and a static gradient mask (`from-white`) that can clash during transitions.
- Action buttons (`Confirm`, `Cancel`) lacking dedicated interactive hit targets.

### Key Decisions
1. **Subtle Surface Contrast vs Harsh Borders**:
   - *Decision*: Use `bg-white` (or `bg-slate-50/90`) paired with a lightweight border (`border-slate-200/80` to `border-slate-300`) and gentle elevation (`shadow-sm` on rest, `shadow-md` on hover).
   - *Rationale*: Maximizes readability and visual clarity while maintaining a calm, modern aesthetic that fits the application's slate/amber palette.
2. **Dynamic Gradient Masking**:
   - *Decision*: Tie the summary fade gradient to the card's background state (`bg-gradient-to-t from-white group-hover:from-amber-50/70`).
   - *Rationale*: Eliminates visual artifacting when hovering over cards with long text summaries.
3. **Ergonomic Sizing & Targets**:
   - *Decision*: Expand default minimum card widths (`w-48 sm:w-72 lg:w-80`) and provide `p-4` internal padding, giving action buttons `p-1 rounded-full hover:bg-slate-100` hitboxes.
   - *Rationale*: Improves tap target usability and visual pacing across responsive viewports.

### Proposed Changes
1. **`src/components/AmendmentCarousel.vue`**:
   - Refactor amendment `<article>` card markup and classes:
     - Apply `group relative flex flex-col justify-between rounded-xl border border-slate-200/90 bg-white p-4 shadow-sm transition-all duration-200 hover:-translate-y-0.5 hover:border-amber-300 hover:bg-amber-50/40 hover:shadow-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-900`.
   - Update header section inside card:
     - Title styled with `font-header font-bold text-slate-900 text-sm sm:text-base leading-snug`.
     - Confirm/Reject actions styled with subtle circular icon button wrappers.
   - Update summary text block and gradient overlay:
     - `text-xs leading-relaxed text-slate-600` with smoothly fading overlay.
   - Refactor "Add Amendment" `<article>`:
     - Apply matching rounded corners (`rounded-xl`), dashed border styling (`border-2 border-dashed border-slate-300 hover:border-amber-500`), and balanced icon/label grouping.
   - Modernize `.carousel-btn`:
     - Update class styling to `border border-slate-300 bg-white/95 text-slate-700 shadow-md hover:bg-slate-50 hover:text-slate-950 hover:border-slate-400 backdrop-blur-sm transition focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-slate-900`.

### File Structure
- `src/components/AmendmentCarousel.vue` *(Modified)*: Main carousel component containing card templates, scroller, action triggers, and scoped styles.

# Testing

### Validation Approach
Verify visual appeal, responsive layout behavior, contrast ratios, and interactive states directly in the Vue component.

### Key Scenarios
1. **Resting & Hover States**:
   - Verify amendment cards render with clean background separation from the carousel track.
   - Verify hover transition smoothly shifts background tint (`amber-50/40`), border accent, and elevation without layout shift.
2. **Text Hierarchy & Gradient Mask**:
   - Verify amendment title, status chip, and multi-line summary render with clear typographic hierarchy.
   - Verify summary text fade seamlessly matches the card surface on both resting and hover states.
3. **Interactive Actions & Buttons**:
   - Confirm and reject buttons trigger appropriate handlers with clear visual feedback upon hover and click.
   - Verify "Add Amendment" card matches carousel dimensions and triggers creation modal on click / keyboard navigation.
4. **Carousel Navigation & Responsiveness**:
   - Verify scroll left and right buttons appear when content overflows and operate smoothly with visible focus indicators.
   - Test layout across mobile (`w-48` / `w-64`) and desktop breakpoints (`w-72` / `w-80`).

# Delivery Steps

### ✓ Step 1: Refine amendment card surface styling and contrast hierarchy
Amendment cards feature subtle surface contrast against the background, refined spacing, and polished borders.

- Update the card container background to `bg-white` (or `bg-slate-50/90`) with a fine border (`border border-slate-200/80` or `border-slate-300`) and soft elevation (`shadow-xs` / `shadow-sm` transitioning to `shadow-md` on hover).
- Increase inner padding to `p-4` (or `p-3.5`) for improved breathing room and ergonomic proportions.
- Update hover state to cleanly transition surface background (`hover:bg-amber-50/70` or `hover:border-amber-300`).
- Ensure cards maintain consistent height and flex alignment across different screen sizes (`w-48 sm:w-72 lg:w-80`).

### ✓ Step 2: Harmonize card content typography, action controls, and carousel styling
Amendment content, action buttons, gradient masks, the 'Add Amendment' card, and navigation buttons look cohesive and accessible.

- Apply header typography styling (`font-header` or `font-semibold text-slate-900`) to amendment titles with proper text truncation.
- Enhance confirm/reject action buttons with dedicated hover/focus states, touch target padding, and tooltips or aria attributes.
- Align the summary text line-height and update the bottom gradient fade (`bg-gradient-to-t from-white group-hover:from-amber-50/70`) to match the card background.
- Redesign the 'Add Amendment' dashed card with matching dimensions, rounded corners, subtle slate background tint, and smooth amber hover transitions.
- Polish carousel navigation buttons with clean border, backdrop blur, and accessible focus rings.