Frontend Flow

Quality-first frontend development workflow for Pulse Radar.

Overview

┌─────────────────────────────────────────────────────────────┐
│  QUALITY-FOCUSED FRONTEND WORKFLOW                          │
│                                                              │
│  1. SESSION    2. DISCOVERY   3. IMPLEMENT   4. STORYBOOK   │
│  ────────────  ────────────   ────────────   ────────────   │
│  Journal       Storybook MCP  Tokens         Stories        │
│  Beads         Vault Search   Patterns       Screenshots    │
│  Context       AGENTS.md      Design System  Interaction    │
│                                                              │
│  5. VERIFICATION (CRITICAL)   6. KNOWLEDGE                  │
│  ────────────────────────────  ────────────                 │
│  TypeScript → ESLint → Tests   Journal done                 │
│  Story check → Accessibility   Capture                      │
│  ALL MUST PASS                 Beads update                 │
└─────────────────────────────────────────────────────────────┘

Principle: Quality over speed. Verification must pass before task completion.

Phase 1: Session & Context

Trigger: Starting frontend work

Actions:

1. Start journal session: /obsidian:journal session "Task title"
2. Get issue context: bd show {issue}
3. Read previous handoff if exists

Goal: Establish context and enable progress tracking.

Phase 2: Discovery (CRITICAL!)

Trigger: BEFORE creating or modifying any component

Required checks:

# 1. Check existing components in Storybook
storybook_list_components

# 2. Get props API for similar components
storybook_get_component_props componentId="..."

# 3. Search knowledge vault
/obsidian:search "relevant pattern"

# 4. Read Design System rules
frontend/AGENTS.md

Checkpoint: "Existing component found? → USE IT instead of creating new!"

Anti-pattern: Creating new component without Storybook check = quality violation.

→ See @references/discovery.md for detailed checklist.

Phase 3: Implementation (Design System)

Trigger: During code writing

Required rules:

| Rule | Use | Don't Use | |------|-----|-----------| | Colors | @shared/tokens/* | bg-red-500, text-green-600 | | Patterns | @shared/patterns/* | Manual composition | | Icons | lucide-react | heroicons, Radix icons | | Touch | h-11 w-11 (44px) | h-9 w-9 (36px) | | Spacing | gap-2, gap-4, p-4 | gap-3, p-5 (off-grid) | | Icon buttons | aria-label="..." | No label | | Status | Icon + Text | Color only |

Related skills: /frontend, /design-tokens

Phase 3.5: Component Portability (NEW!)

Trigger: When creating/modifying components in shared/

Principle: Components in shared/ must be PORTABLE — work without API, store, router.

┌─────────────────────────────────────────────────────────────┐
│  PORTABLE COMPONENT = Pure Function                         │
│                                                             │
│  Props → Component → UI                                     │
│                                                             │
│  ✅ No useQuery/useMutation inside                          │
│  ✅ No apiClient/fetch calls inside                         │
│  ✅ No useNavigate/useParams/useLocation                    │
│  ✅ No useStore (Zustand) directly                          │
│  ✅ All data via props                                      │
│  ✅ Works in Storybook WITHOUT providers                    │
└─────────────────────────────────────────────────────────────┘

Anti-pattern (FORBIDDEN):

// ❌ NON-PORTABLE — violates CDD principles
import { useQuery } from '@tanstack/react-query'
import { apiClient } from '@/shared/lib/api'

export function ActivityHeatmap() {
  const { data } = useQuery({ queryFn: () => apiClient.get('/activity') })
  return <Heatmap data={data} />
}

Correct pattern (Presenter + Hook):

// ✅ PORTABLE PRESENTER — shared/components/
interface ActivityHeatmapProps {
  data: ActivityDataPoint[]
  isLoading?: boolean
  className?: string
}

export function ActivityHeatmap({ data, isLoading, className }: ActivityHeatmapProps) {
  if (isLoading) return <ActivityHeatmapSkeleton />
  return <HeatmapRenderer data={data} className={className} />
}

// Data hook — features/activity/hooks/ or page level
export function useActivityData(timeRange: TimeRange) {
  return useQuery({
    queryKey: ['activity', timeRange],
    queryFn: () => activityService.getActivity(timeRange)
  })
}

// Page usage — composition
function DashboardPage() {
  const { data, isLoading } = useActivityData('week')
  return <ActivityHeatmap data={data ?? []} isLoading={isLoading} />
}

Portability Checklist:

• [ ] No useQuery/useMutation in shared/components
• [ ] No apiClient/fetch imports in shared/components
• [ ] No useNavigate/useParams in shared/components
• [ ] All data passed via typed props interface
• [ ] Optional className prop for customization
• [ ] Works in Storybook without QueryClient/Router mocks

Verification command:

# Should return 0 violations
grep -rE "useQuery|apiClient" src/shared/components --include="*.tsx" | grep -v test

Phase 3.6: Component Integration Decision (NEW!)

Trigger: When needing a new UI element

Decision Tree:

NEED NEW UI ELEMENT?
         │
         ▼
┌─────────────────────────────┐
│ 1. Check shared/ui/         │ → EXISTS → USE IT
└─────────────────────────────┘
         │ NOT FOUND
         ▼
┌─────────────────────────────┐
│ 2. Check shared/components/ │ → EXISTS → USE IT
└─────────────────────────────┘
         │ NOT FOUND
         ▼
┌─────────────────────────────┐
│ 3. Check shared/patterns/   │ → EXISTS → USE IT
└─────────────────────────────┘
         │ NOT FOUND
         ▼
┌─────────────────────────────┐
│ 4. Check shadcn registry    │
│    ui.shadcn.com/docs       │
└─────────────────────────────┘
         │
    FOUND ┴ NOT FOUND
      │        │
      ▼        ▼
  EVALUATE   BUILD in shared/components
      │
 Fits 80%? ┬ YES → npx shadcn add → shared/ui
           │
           └ NO → WRAP in shared/components

Where to put new component:

| Type | Location | Example | |------|----------|---------| | shadcn primitive | shared/ui/ | Button, Dialog, Select | | shadcn + customize | shared/ui/ (modify) | Badge with new variant | | Composition | shared/patterns/ | CardWithStatus, FormField | | Business reusable | shared/components/ | SearchBar, TopicSelector | | Feature-specific | features/X/components/ | AtomCard, ProviderList | | Page-specific | pages/X/components/ | DashboardStats |

Adding shadcn component example:

# 1. Check if exists
grep -r "DatePicker\|Calendar" src/shared/

# 2. Add from shadcn
npx shadcn@latest add calendar

# 3. Create composition wrapper if needed
# src/shared/components/DatePicker/index.tsx

Checkpoint: "Component location decided? Portability requirements clear?"

Phase 4: Storybook (Component Library)

Trigger: After creating/modifying component

Mandatory coverage:

| Location | Story Required? | Min Stories | |----------|-----------------|-------------| | shared/ui/ | Always | 4-6 | | shared/patterns/ | Always | 5-8 | | shared/components/ | Always | 4-6 | | features/*/ | If >50 LOC or reused | 2-4 |

Actions:

1. Create .stories.tsx with tags: ['autodocs']
2. Cover all variants, states, sizes
3. Add interaction tests for clickable elements
4. Capture screenshot: storybook_capture_screenshot storyId="..."

Checkpoint: "Story created with full coverage?"

Related skill: /storybook

Phase 5: Verification Pipeline (MOST IMPORTANT!)

Trigger: After code written, BEFORE considering task complete

Required pipeline (ALL steps!):

cd frontend

# 1. TypeScript — type safety
npx tsc --noEmit

# 2. ESLint — Design System compliance (9 rules)
npm run lint

# 3. Unit tests — logic correctness
npm run test:run

# 4. Story coverage — documentation
npm run story:check

# 5. Accessibility (for shared/ components)
npm run test:a11y

ESLint Design System Rules (all 9 — ERROR level):

| # | Rule | Ensures | |---|------|---------| | 1 | no-raw-tailwind-colors | Semantic tokens only | | 2 | no-odd-spacing | 4px grid system | | 3 | no-heroicons | lucide-react only | | 4 | no-raw-zindex | Named z-index tokens | | 5 | no-direct-fonts | Font tokens only | | 6 | no-raw-page-wrapper | PageWrapper required | | 7 | no-direct-api-imports | Service classes | | 8 | no-hardcoded-api-paths | API_ENDPOINTS config | | 9 | stories-require-autodocs | Autodocs tag |

If any step fails: Fix → Re-run pipeline → Don't proceed until ALL pass.

→ See @references/verification.md for troubleshooting.

Phase 6: Knowledge Capture

Trigger: After successful verification

Actions:

1. Close journal session: /obsidian:journal done
2. Add findings as wikilinks: [[знання/паттерни/pattern-name]]
3. Capture learnings: /obsidian:capture auto
4. Update Beads: bd comments add {issue} "Progress: ..."
5. Generate handoff for next session

Learning categories:

• знання/паттерни/ — reusable approaches
• знання/рішення/ — architectural decisions
• знання/помилки/ — mistakes to avoid

→ See @references/documentation.md for templates.

Quality Gates

| Gate | Criterion | Blocking? | |------|-----------|-----------| | Discovery | Storybook checked BEFORE coding | Yes | | Design System | Tokens instead of raw colors | Yes (ESLint blocks) | | Storybook | Story for shared/ components | Yes | | TypeScript | tsc --noEmit passes | Yes | | ESLint | 9 Design System rules pass | Yes | | Tests | Unit tests pass | Yes | | Story Coverage | story:check passes | Yes | | Accessibility | test:a11y for shared/ | Recommended | | Knowledge | Learnings captured in vault | Recommended |

Principle: If verification fails → task NOT complete.

Quick Reference

Commands:

| Action | Command | |--------|---------| | Start Storybook | just storybook | | TypeScript check | npx tsc --noEmit | | ESLint | npm run lint | | ESLint fix | npm run lint:fix | | Unit tests | npm run test:run | | Story coverage | npm run story:check | | A11y tests | npm run test:a11y |

Related skills:

| Skill | When to use | |-------|-------------| | /frontend | Architecture, state management | | /storybook | Story templates, interaction tests | | /design-tokens | Token API reference | | /testing | Vitest, Playwright patterns |

Example

User: "Create TopicCard component"

Claude follows frontend-flow:

1. [Session] /obsidian:journal session "TopicCard component"

2. [Discovery] BEFORE coding!
   → storybook_list_components → check existing cards
   → Found CardWithStatus — base structure exists!
   → /obsidian:search "card pattern" → found prior decisions

3. [Implementation]
   → Using @shared/tokens for colors
   → Using @shared/patterns/CardWithStatus as base
   → All icon buttons with aria-label
   → 44px touch targets

4. [Storybook]
   → TopicCard.stories.tsx with tags: ['autodocs']
   → 5 stories: Default, Empty, Loading, Error, WithBadge
   → storybook_capture_screenshot

5. [Verification] ALL must pass!
   → npx tsc --noEmit ✅
   → npm run lint ✅ (9 ESLint rules pass)
   → npm run test:run ✅
   → npm run story:check ✅
   → npm run test:a11y ✅

6. [Knowledge]
   → /obsidian:journal done
   → Findings: [[знання/паттерни/topic-card-composition]]
   → /obsidian:capture auto

Key: Verification runs COMPLETELY before task is considered done.