Frontend Implementation Plan

This skill teaches how to create comprehensive implementation plans for frontend features, screens, and components. It provides a framework-agnostic approach to documenting UI architecture, design specifications, and development guidelines.

When to Use This Skill

Planning implementation for new UI screens or features
Documenting existing implementations for team reference
Creating technical specifications for frontend work
Establishing design system documentation
Teaching implementation patterns to developers
Preparing handoff documentation between design and development

Core Principles

1. Structure Over Specifics

A good implementation plan follows a clear hierarchy:

Implementation Plan
├── Overview (What & Why)
├── Architecture (Component Hierarchy)
├── Design Specifications (Visual Standards)
├── Component Details (Props, States, Behavior)
├── Data Flow (API Integration, State Management)
├── User Interactions (Navigation, Events)
├── Quality Assurance (Testing, Accessibility, Performance)
└── Migration & Integration (How to Implement)

2. Framework-Agnostic Thinking

Document what needs to be built, not just how in a specific framework:

Good ✅:

Stats Card Component
- Displays: Icon, label, numeric value, optional trend
- States: Default, loading, hover, error
- Variants: Clickable vs. static
- Responsiveness: Stacks vertically on mobile

Too Specific ❌:

Create a React component using useState and useQuery...

3. Design System First

Define the design system before component details:

Typography Scale
├── Page Titles: 40px, semibold, tight tracking
├── Section Headers: 32px, semibold
├── Body Text: 16px, regular, relaxed tracking
└── Captions: 13px, light

Color Palette
├── Primary: Brand color for actions
├── Text Hierarchy: Primary → Secondary → Tertiary
├── Semantic Colors: Success, Warning, Error, Info
└── Neutrals: Backgrounds, borders, disabled states

Spacing System
├── Base Unit: 4px or 8px
├── Component Padding: 24px (large), 16px (medium), 8px (small)
├── Section Gaps: 48px (large), 32px (medium), 16px (small)
└── Layout Grid: Column count, gutter width

4. Component Documentation Pattern

For each component, document:

Purpose - What it displays, when to use it
Anatomy - Visual breakdown of parts
Props/Configuration - Input parameters
States - Loading, empty, error, success, disabled
Variants - Size, style, behavior variations
Accessibility - ARIA labels, keyboard navigation
Examples - Visual or code examples

5. State Management Clarity

Explicitly document all UI states:

Loading State:

What: Skeleton/spinner while data fetches
When: API call in progress
Pattern: Show placeholder matching final layout

Empty State:

What: Friendly message when no data
When: Valid but empty data response
Pattern: Icon + message + call-to-action

Error State:

What: Error message with retry option
When: API failure or invalid data
Pattern: Error icon + explanation + retry button

Success State:

What: Populated with real data
When: Data loaded successfully
Pattern: Full component render

Implementation Plan Structure

Section 1: Overview

## 1. Overview

### Purpose
[What this feature/screen does and why it exists]

### User Goals
- [Primary user objective]
- [Secondary user objective]

### Key Features
- [Feature 1]
- [Feature 2]

### Success Criteria
- [Measurable outcome 1]
- [Measurable outcome 2]

Section 2: Architecture

## 2. Architecture

### Component Hierarchy

Screen/Feature ├── Layout Components │ ├── Header │ ├── Sidebar (optional) │ └── Footer ├── Feature Components │ ├── Main Content Area │ ├── Filter/Search Bar │ └── Data Display Grid └── Shared Components ├── Loading Skeleton ├── Empty State └── Error Boundary


### File Structure

/components /feature-name /FeatureMain.tsx (or .vue, .svelte, etc.) /FeatureHeader.tsx /FeatureCard.tsx /shared /Button.tsx /Input.tsx /types /feature-name.ts /hooks (or composables, stores) /useFeatureData.ts

Section 3: Design Specifications

## 3. Design Specifications

### Visual Hierarchy
- Primary elements: [Description + specs]
- Secondary elements: [Description + specs]
- Tertiary elements: [Description + specs]

### Typography
| Element | Size | Weight | Color | Line Height |
|---------|------|--------|-------|-------------|
| Page Title | 40px | Bold | Primary | 1.2 |
| Section Header | 24px | Semibold | Primary | 1.4 |
| Body Text | 16px | Regular | Secondary | 1.6 |

### Colors
| Use Case | Color Code | Usage |
|----------|------------|-------|
| Primary Action | #FF6B00 | Buttons, links |
| Text Primary | #1A1A1A | Main content |
| Text Secondary | #666666 | Descriptions |
| Border | #E5E5E5 | Dividers, outlines |

### Spacing & Layout
- Container: [Max width, padding]
- Grid: [Columns, gap]
- Component padding: [Internal spacing]
- Section margins: [Between major sections]

### Responsive Breakpoints
- Mobile: 0-767px (1 column)
- Tablet: 768-1023px (2 columns)
- Desktop: 1024px+ (3-4 columns)

Section 4: Component Specifications

For each major component:

## Component: [Name]

### Purpose
[What it does, when it's used]

### Anatomy

┌─────────────────────────────┐ │ Icon Title Badge │ │ │ │ Supporting text │ │ ━━━━━━━━━━ Progress: 75% │ │ │ │ [Action Button] │ └─────────────────────────────┘


### Configuration/Props
```typescript
interface ComponentProps {
  title: string
  description?: string
  progress: number (0-100)
  status: 'active' | 'pending' | 'complete'
  onAction: () => void
}

States

Default: Normal display
Hover: Subtle highlight, cursor pointer
Loading: Show skeleton
Disabled: Grayed out, no interaction
Error: Red border, error icon

Variants

Size: Small (compact), Medium (default), Large (featured)
Type: Clickable (with onClick), Display-only

Accessibility

[ ] ARIA label on interactive elements
[ ] Keyboard navigation (Tab, Enter, Space)
[ ] Focus visible indicator
[ ] Screen reader announcements

Example

[Screenshot/mockup or code example]


### Section 5: Data Flow

```markdown
## 5. Data Flow

### Data Sources
- API: `GET /api/resource` → Returns `Resource[]`
- Local Storage: Cached user preferences
- URL Parameters: Filter/sort state

### State Management

Global State (Store/Context) ├── User session data └── App-wide settings

Component State (Local) ├── Form inputs ├── UI toggles (modals, dropdowns) └── Temporary filters

Server State (Query library) ├── Fetched data from API ├── Loading/error states └── Cache management


### API Integration

Fetch Pattern:

Component mounts → Trigger API call
Show loading state
On success → Update UI with data
On error → Show error state with retry

Endpoints Needed:

GET /api/items → List items
POST /api/items → Create item
PATCH /api/items/:id → Update item
DELETE /api/items/:id → Remove item

Section 6: User Interactions

## 6. User Interactions

### Navigation Flow

Entry Point → Screen A → Action → Screen B ↓ ↓ Alternative Path Alternative Outcome


### Interaction Map
| Element | Trigger | Action | Result |
|---------|---------|--------|--------|
| Filter dropdown | Click/Select | Update filtered view | Re-render list |
| Search input | Type (debounced) | Filter items | Update results |
| Action button | Click | Navigate/Submit | Go to detail page |
| Sort icon | Click | Toggle sort order | Reorder items |

### Keyboard Shortcuts (if applicable)
- `Tab`: Navigate between focusable elements
- `Enter/Space`: Activate focused button
- `Esc`: Close modal/dropdown
- `Ctrl+F`: Focus search (optional)

Section 7: Quality Assurance

## 7. Quality Assurance

### Testing Checklist
**Visual States**:
- [ ] Loading state displays correctly
- [ ] Empty state shows appropriate message
- [ ] Error state includes retry option
- [ ] Success state renders data properly

**Responsive Design**:
- [ ] Mobile (375px): Single column, readable
- [ ] Tablet (768px): Optimized layout
- [ ] Desktop (1024px+): Full feature set

**Interactions**:
- [ ] All buttons clickable and responsive
- [ ] Forms validate correctly
- [ ] Navigation works as expected
- [ ] Filters apply properly

### Accessibility Audit
- [ ] All images have alt text
- [ ] Form inputs have labels
- [ ] Focus indicators visible
- [ ] Color contrast ≥ 4.5:1 (WCAG AA)
- [ ] Keyboard navigation functional
- [ ] Screen reader compatible

### Performance Targets
- [ ] First Contentful Paint < 1.5s
- [ ] Time to Interactive < 3s
- [ ] No layout shifts (CLS < 0.1)
- [ ] Images optimized/lazy loaded
- [ ] Large lists virtualized (if >100 items)

### Browser Support
- Chrome/Edge (latest 2 versions)
- Firefox (latest 2 versions)
- Safari (latest 2 versions)
- Mobile browsers (iOS Safari, Chrome Mobile)

Section 8: Implementation Guide

## 8. Implementation Guide

### Phase 1: Foundation
1. Set up component files and structure
2. Define TypeScript types/interfaces
3. Implement design tokens (colors, spacing, typography)
4. Create base components (Button, Input, Card)

### Phase 2: Core Features
1. Build main screen layout
2. Implement data fetching/state management
3. Create feature-specific components
4. Wire up user interactions

### Phase 3: States & Edge Cases
1. Add loading skeletons
2. Implement empty states
3. Handle error scenarios
4. Add form validation

### Phase 4: Polish & Optimization
1. Add animations/transitions
2. Optimize performance
3. Test accessibility
4. Cross-browser testing

### Migration Notes (if updating existing code)
- **Breaking Changes**: [List any breaking changes]
- **Backwards Compatibility**: [How to maintain during transition]
- **Rollout Strategy**: [Phased or all-at-once deployment]

Best Practices

Documentation Quality

Be Specific: Use exact values (not "large padding" but "24px padding")
Include Visuals: Diagrams, mockups, or ASCII art for clarity
Reference Real Examples: Link to similar implementations
Version Control: Date the document, note which version of design/product

Design System Documentation

Single Source of Truth: One place for all design tokens
Live Examples: Show components in action, not just specs
Usage Guidelines: When to use each component variant
Don't Use: Anti-patterns and what to avoid

Component Documentation

Atomic Design: Document from smallest (atoms) to largest (pages)
Props Over Implementation: Focus on interface, not internals
State Exhaustiveness: Document every possible state
Edge Cases: List unusual scenarios and how to handle them

Maintenance

Keep It Updated: Mark outdated sections clearly
Link to Code: Connect docs to actual implementation
Review Process: Docs updated whenever design/requirements change
Feedback Loop: Developers flag unclear documentation

Common Patterns

Grid/List Views

### Grid Layout Pattern
- Container: Responsive grid
- Items: Uniform card components
- Empty Slots: Show placeholder or hide
- Loading: Skeleton items matching card layout
- Pagination: Load more button or infinite scroll

Filter/Search Pattern

### Filter System
- Filters: Dropdowns for categorical data
- Search: Text input with debounce (300ms)
- Sort: Dropdown or clickable headers
- Clear: Reset all filters button
- URL State: Persist filters in URL params

Modal/Dialog Pattern

### Modal Behavior
- Trigger: Button or link
- Backdrop: Dim page, close on click
- Focus Trap: Tab cycles within modal
- Close: X button, Esc key, backdrop click
- Scroll: Lock body scroll, scroll within modal

Form Pattern

### Form Structure
- Fields: Clear labels, helpful placeholders
- Validation: Real-time + on submit
- Errors: Inline messages, field highlighting
- Submit: Disabled during processing, success feedback
- Autosave: Optional, with save indicator

Framework Examples

While this skill is framework-agnostic, here are translation hints:

State Management

React: useState, useReducer, Context, Redux, Zustand
Vue: ref, reactive, provide/inject, Pinia
Angular: Services, RxJS
Svelte: Stores

Data Fetching

React: TanStack Query, SWR, Apollo
Vue: VueQuery, composables
Angular: HttpClient + Services
Svelte: Stores + async/await

Styling Approaches

Utility CSS: Tailwind, UnoCSS
CSS-in-JS: styled-components, Emotion
CSS Modules: Scoped styles per component
Atomic CSS: shadcn/ui, Radix, Headless UI

Checklist for Complete Plans

Before finalizing an implementation plan, verify:

[ ] Overview: Purpose and goals clearly stated
[ ] Architecture: Component hierarchy diagram included
[ ] Design Specs: Typography, colors, spacing defined
[ ] Components: Each major component documented
[ ] Data Flow: API endpoints and state management specified
[ ] Interactions: User flows and navigation mapped
[ ] States: Loading, empty, error, success all covered
[ ] Accessibility: WCAG compliance checklist included
[ ] Testing: Test scenarios and acceptance criteria listed
[ ] Performance: Optimization targets defined
[ ] Responsive: Mobile, tablet, desktop specs provided
[ ] Implementation: Step-by-step guide or phases outlined

Anti-Patterns to Avoid

❌ Vague Specifications: "Make it look nice" → ✅ "24px padding, #E5E5E5 border"

❌ Framework Lock-in: "Use React hooks" → ✅ "Manage component-level state"

❌ Missing States: Only documenting happy path → ✅ Document all states

❌ No Accessibility: Forgetting keyboard/screen readers → ✅ Include a11y checklist

❌ Overly Technical: Focus on code syntax → ✅ Focus on behavior and UX

❌ Static Documentation: No updates after creation → ✅ Living document

❌ No Examples: All text, no visuals → ✅ Include diagrams, mockups, code samples

frontend-implementation-plan