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:

code

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 ✅:

code

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 ❌:

code

Create a React component using useState and useQuery...

3. Design System First

Define the design system before component details:

code

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

markdown

## 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

markdown

## 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

code


### 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

code

Section 3: Design Specifications

markdown

## 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:

markdown

## Component: [Name]

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

### Anatomy

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

code


### 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]

code


### 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

code


### 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

code

Section 6: User Interactions

markdown

## 6. User Interactions

### Navigation Flow

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

code


### 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

markdown

## 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

markdown

## 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

markdown

### 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

markdown

### 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

markdown

### 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

markdown

### 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:

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

Frontend Implementation Plan

When to Use This Skill

Core Principles

1. Structure Over Specifics

2. Framework-Agnostic Thinking

3. Design System First

4. Component Documentation Pattern

5. State Management Clarity

Implementation Plan Structure

Section 1: Overview

Section 2: Architecture

Section 3: Design Specifications

Section 4: Component Specifications

States

Variants

Accessibility

Example

Section 6: User Interactions

Section 7: Quality Assurance

Section 8: Implementation Guide

Best Practices

Documentation Quality

Design System Documentation

Component Documentation

Maintenance

Common Patterns

Grid/List Views

Filter/Search Pattern

Modal/Dialog Pattern

Form Pattern

Framework Examples

State Management

Data Fetching

Styling Approaches

Checklist for Complete Plans

Anti-Patterns to Avoid

Additional Resources

Documentation Tools

Inspiration Sources