nextcraft/.ciagent/PLAN.md

Nextcraft v0.1 — PLAN.md

Overview

This plan covers execution phases 1-6 of milestone v0.1 (UI/UX Prototype). Each phase is a vertical slice that produces a demoable milestone. Phases are ordered by dependency — later phases build on earlier ones.

---

Phase 1: Project Scaffolding

Requirements: REQ-001, REQ-002, REQ-003, REQ-004, REQ-005 Persona: design-system-engineer (Wave 1), data-engineer (Wave 1), frontend-engineer (Wave 2) Goal: Monorepo builds, dev server starts, component library has all primitives, mock data typed, routing works

Wave 1: Foundation (parallel — no shared file conflicts)

Task 1-1-01: Monorepo scaffolding

• Persona: design-system-engineer
• Files: package.json, pnpm-workspace.yaml, turbo.json, tsconfig.json, .npmrc
• Action: Create root monorepo config. pnpm workspaces pointing to apps/* and packages/*. Turborepo with build/dev/lint/typecheck pipelines. Root tsconfig with path aliases.
• Verify: pnpm install succeeds; workspace packages detected
• Done: pnpm list -r shows all workspace packages

Task 1-1-02: Shared types package

• Persona: data-engineer
• Files: packages/types/package.json, packages/types/tsconfig.json, packages/types/domain.ts, packages/types/marketplace.ts, packages/types/user.ts, packages/types/ui.ts, packages/types/index.ts
• Action: Create all shared TypeScript type definitions: Competency, CompetencyStack, Microcredential, Artifact, ProcessTrace, OralDefense, AssessmentRubric, Job, Employer, Candidate, JobPosting, TalentMatch, SearchFilter, Learner, Admin, EmployerUser, AgeGroup, Role, plus UI types (ComponentProps, ThemeConfig, Breakpoint).
• Verify: pnpm typecheck passes in packages/types
• Done: All types exported from index.ts; no type errors

Task 1-1-03: Mock data package

• Persona: data-engineer
• Files: packages/mock-data/package.json, packages/mock-data/tsconfig.json, packages/mock-data/competency-stacks.ts, packages/mock-data/jobs.ts, packages/mock-data/candidates.ts, packages/mock-data/employers.ts, packages/mock-data/learner-progress.ts, packages/mock-data/ai-tutor-responses.ts, packages/mock-data/index.ts
• Action: Create typed mock data: 5 competency stacks (AI Orchestration Engineer with 15 competencies, AI Safety & Governance with 14, Human-AI Product Designer with 13, AI-Augmented Field Operator with 12, Computational Sciences with 16). 20+ mock jobs. 15+ mock candidates. 10+ mock employers. Mock learner progress. Pre-scripted AI tutor responses.
• Verify: All mock data matches types from packages/types; pnpm typecheck passes
• Done: All mock data exported from index.ts; types match

Wave 2: UI Foundation (depends on Wave 1)

Task 1-2-01: Next.js app initialization

• Persona: frontend-engineer
• Files: apps/web/package.json, apps/web/tsconfig.json, apps/web/next.config.ts, apps/web/app/layout.tsx, apps/web/app/page.tsx, apps/web/app/globals.css
• Action: Initialize Next.js app with App Router, TypeScript, Tailwind CSS v4. Configure Inter font via next/font. Set up path aliases to packages. Create root layout with theme provider. Create placeholder home page.
• Verify: pnpm dev starts; pnpm build succeeds; page renders at localhost:3000
• Done: Next.js app runs with Tailwind CSS and Inter font

Task 1-2-02: Design tokens and Tailwind config

• Persona: design-system-engineer
• Files: packages/ui/package.json, packages/ui/tsconfig.json, packages/ui/src/index.ts, packages/ui/src/tokens/index.ts, apps/web/app/globals.css (update)
• Action: Create packages/ui package. Define design tokens as TypeScript constants and CSS custom properties: color palette (indigo/violet primary, emerald accent, slate neutral, dark mode variants), typography scale (12px-48px), spacing system (4px base), breakpoints (375px, 768px, 1280px), shadows, radii. Configure Tailwind v4 @theme with custom colors.
• Verify: Design tokens importable from packages/ui; Tailwind classes work with custom colors
• Done: import { tokens } from '@nextcraft/ui' works; bg-primary-500 class works

Task 1-2-03: UI primitives

• Persona: design-system-engineer
• Files: packages/ui/src/primitives/button.tsx, packages/ui/src/primitives/input.tsx, packages/ui/src/primitives/card.tsx, packages/ui/src/primitives/badge.tsx, packages/ui/src/primitives/avatar.tsx, packages/ui/src/primitives/dialog.tsx, packages/ui/src/primitives/tabs.tsx, packages/ui/src/primitives/progress.tsx, packages/ui/src/primitives/tooltip.tsx, packages/ui/src/primitives/skeleton.tsx, packages/ui/src/primitives/toast.tsx, packages/ui/src/primitives/index.ts
• Action: Create all 12 primitive components. Each is a React component with TypeScript props, Tailwind styling, forwardRef, and size variants. Button (primary, secondary, ghost, destructive). Input (text, search, with label). Card (with header, body, footer slots). Badge (default, success, warning, error). Avatar (with image, fallback, sizes). Dialog (modal, with overlay). Tabs (horizontal, with active indicator). Progress (linear, circular). Tooltip (on hover). Skeleton (shimmer). Toast (with variants).
• Verify: All primitives importable; each renders without error; variants work
• Done: 12 primitives exported from packages/ui

Task 1-2-04: Layout components

• Persona: design-system-engineer
• Files: packages/ui/src/layouts/container.tsx, packages/ui/src/layouts/grid.tsx, packages/ui/src/layouts/sidebar.tsx, packages/ui/src/layouts/split-panel.tsx, packages/ui/src/layouts/dashboard-layout.tsx, packages/ui/src/layouts/index.ts
• Action: Create layout components. Container (max-width variants: sm, md, lg, xl, full). Grid (responsive cols prop). Sidebar (collapsible, with nav items). SplitPanel (resizable divider). DashboardLayout (sidebar + main content area).
• Verify: Layout components render; responsive breakpoints work
• Done: 5 layout components exported

Task 1-2-05: Root layout + navigation shell

• Persona: frontend-engineer
• Files: apps/web/app/layout.tsx (update), apps/web/components/navigation-shell.tsx, apps/web/components/role-switcher.tsx, apps/web/components/header.tsx, apps/web/components/footer.tsx
• Action: Update root layout with theme provider (dark mode toggle), Inter font, responsive navigation shell. Create role switcher (learner/employer/admin toggle in header). Create header with logo, nav links, role switcher, dark mode toggle. Create footer with links.
• Verify: Dark mode toggle works; role switcher navigates between surfaces; responsive at 375px/768px/1280px
• Done: Navigation shell renders on all pages; role switcher functional

Task 1-2-06: Route groups with placeholder pages

• Persona: frontend-engineer
• Files: apps/web/app/(learner)/page.tsx, apps/web/app/(learner)/layout.tsx, apps/web/app/(marketplace)/page.tsx, apps/web/app/(marketplace)/layout.tsx, apps/web/app/(employer)/page.tsx, apps/web/app/(employer)/layout.tsx, apps/web/app/(admin)/page.tsx, apps/web/app/(admin)/layout.tsx
• Action: Create route groups with layouts for each surface. Each layout has surface-specific navigation. Placeholder pages with surface name and brief description.
• Verify: Navigation to / (learner), /marketplace, /employer, /admin works
• Done: 4 route groups with layouts and placeholder pages

Must-Haves (Phase 1)

• pnpm install succeeds
• pnpm dev starts Next.js dev server
• pnpm build succeeds
• pnpm typecheck passes
• 12 UI primitives importable from @nextcraft/ui
• Mock data typed and importable from @nextcraft/mock-data
• Types importable from @nextcraft/types
• 4 route groups with layouts
• Dark mode toggle works
• Role switcher navigates between surfaces
• Responsive at 375px, 768px, 1280px

---

Phase 2: Learner Surface UI

Requirements: REQ-006, REQ-007, REQ-008, REQ-009, REQ-010, REQ-011, REQ-012 Persona: frontend-engineer Goal: All 7 learner pages render with mock data; navigation works; responsive

Wave 1: Core learner pages

Task 2-1-01: Landing page

• Persona: frontend-engineer
• Files: apps/web/app/(learner)/page.tsx, apps/web/components/learner/hero.tsx, apps/web/components/learner/how-it-works.tsx, apps/web/components/learner/program-highlights.tsx, apps/web/components/learner/testimonials.tsx
• Action: Build landing page with hero section (headline, subheadline, CTA buttons), how-it-works section (Byte→Build→Demonstrate→Defend visual flow), program highlights (3-4 featured competency stacks), testimonials mockup (3 cards with avatar, quote, name, role), CTA to program catalog.
• Verify: Landing page renders with all sections; CTA links to /catalog
• Done: Landing page complete

Task 2-1-02: Program catalog

• Persona: frontend-engineer
• Files: apps/web/app/(learner)/catalog/page.tsx, apps/web/components/learner/stack-card.tsx
• Action: Build program catalog page. Grid of 5 competency stack cards. Each card: stack name, role description, competency count, estimated duration, microcredential count, "Explore" button linking to stack detail.
• Verify: 5 stack cards render with mock data; clicking "Explore" navigates to stack detail
• Done: Catalog page complete

Task 2-1-03: Competency stack view

• Persona: frontend-engineer
• Files: apps/web/app/(learner)/catalog/[stackId]/page.tsx, apps/web/components/learner/competency-list.tsx, apps/web/components/learner/competency-item.tsx, apps/web/components/learner/microcredential-badge.tsx
• Action: Build competency stack detail page. Header with stack name, role, description. List of 12-18 competencies. Each competency: name, description, status (locked/available/in-progress/mastered), microcredential badge, progress bar. Clicking a competency navigates to byte tutorial viewer.
• Verify: Competencies render with correct status indicators; microcredential badges display
• Done: Stack detail page complete

Task 2-1-04: Learner dashboard

• Persona: frontend-engineer
• Files: apps/web/app/(learner)/dashboard/page.tsx, apps/web/components/learner/dashboard/active-competencies.tsx, apps/web/components/learner/dashboard/progress-graph.tsx, apps/web/components/learner/dashboard/recent-artifacts.tsx, apps/web/components/learner/dashboard/upcoming-defenses.tsx, apps/web/components/learner/dashboard/ai-tutor-chat.tsx, apps/web/components/learner/dashboard/milestone-tracker.tsx
• Action: Build learner dashboard. Active competencies panel (current stack, progress). Progress graph (recharts area chart showing mastery over time). Recent artifacts (cards with artifact name, type, date). Upcoming defenses (list with competency name, date, status). AI tutor chat mockup (chat interface with pre-scripted responses, message input). Milestone tracker (progress through stack).
• Verify: Dashboard renders all panels; AI tutor chat displays scripted responses on "send"
• Done: Dashboard complete

Wave 2: Detail views

Task 2-2-01: Byte tutorial viewer

• Persona: frontend-engineer
• Files: apps/web/app/(learner)/learn/[competencyId]/page.tsx, apps/web/components/learner/byte-viewer/concept-panel.tsx, apps/web/components/learner/byte-viewer/worked-example.tsx, apps/web/components/learner/byte-viewer/viewer-tabs.tsx
• Action: Build byte tutorial viewer. Layout: left panel (concept text, 3-7 minute read), right panel (worked example with code/design/simulation viewer mockup). Tabbed viewer (code, design, simulation). Navigation to build sandbox.
• Verify: Tutorial viewer renders with concept and example panels; tabs switch
• Done: Byte tutorial viewer complete

Task 2-2-02: Build sandbox mockup

• Persona: frontend-engineer
• Files: apps/web/app/(learner)/build/[competencyId]/page.tsx, apps/web/components/learner/sandbox/toolbar.tsx, apps/web/components/learner/sandbox/file-explorer.tsx, apps/web/components/learner/sandbox/editor-area.tsx, apps/web/components/learner/sandbox/telemetry-sidebar.tsx
• Action: Build sandbox mockup IDE UI. Layout: top toolbar (run, save, submit buttons), left sidebar (file explorer tree), center (code editor area with syntax-highlighted mock code), right sidebar (telemetry — process capture indicators showing commits, keystrokes, time spent). No real code execution.
• Verify: Sandbox UI renders with all panels; toolbar buttons are interactive (non-functional)
• Done: Build sandbox mockup complete

Task 2-2-03: Assessment/defense mockup

• Persona: frontend-engineer
• Files: apps/web/app/(learner)/defend/[competencyId]/page.tsx, apps/web/components/learner/assessment/rubric-display.tsx, apps/web/components/learner/assessment/ai-reviewer-panel.tsx, apps/web/components/learner/assessment/oral-defense.tsx, apps/web/components/learner/assessment/process-trace.tsx, apps/web/components/learner/assessment/artifact-viewer.tsx
• Action: Build assessment/defense mockup. Layout: top (artifact viewer — submitted work preview), left (rubric display — competency criteria with checkmarks), right (AI reviewer panel — assessment results), bottom (oral defense interface — mic button mockup, waveform animation, transcript area). Process trace timeline (showing build steps with timestamps).
• Verify: Assessment mockup renders all panels; mic button has hover state; timeline displays mock events
• Done: Assessment/defense mockup complete

Must-Haves (Phase 2)

• Landing page renders with hero, how-it-works, highlights, testimonials, CTA
• Program catalog shows 5 competency stack cards
• Competency stack view shows 12-18 competencies with status and badges
• Learner dashboard shows all 6 panels including AI tutor chat mockup
• Byte tutorial viewer renders with concept and worked example panels
• Build sandbox mockup renders with toolbar, file explorer, editor, telemetry
• Assessment mockup renders with rubric, AI reviewer, oral defense, process trace
• All pages responsive at 375px, 768px, 1280px
• Navigation between all learner pages works

---

Phase 3: Marketplace Surface UI

Requirements: REQ-013, REQ-014, REQ-015, REQ-016, REQ-017 Persona: frontend-engineer Goal: All 5 marketplace pages render with mock data; search/filter interactive

Wave 1: Job board + search

Task 3-1-01: Job board listing

• Persona: frontend-engineer
• Files: apps/web/app/(marketplace)/page.tsx, apps/web/components/marketplace/job-card.tsx, apps/web/components/marketplace/job-listing-grid.tsx
• Action: Build job board listing page. Layout: left sidebar (filters), main area (grid of job cards). Each job card: job title, company name, logo, location, remote badge, salary range, match score (percentage badge), required skills (tag chips), posted date. 20+ mock job listings.
• Verify: 20+ job cards render; match scores display; skill tags show
• Done: Job board listing complete

Task 3-1-02: Search/filter UI

• Persona: frontend-engineer
• Files: apps/web/components/marketplace/filter-sidebar.tsx, apps/web/components/marketplace/search-bar.tsx, apps/web/components/marketplace/saved-searches.tsx
• Action: Build filter sidebar. Semantic search bar at top (with icon, placeholder text). Filters: skills (multi-select chips), seniority (dropdown), location (text input), remote toggle, salary range (min/max inputs). Saved searches mockup section. Client-side filtering of mock jobs using useState.
• Verify: Typing in search filters jobs; selecting skill filters jobs; toggling remote filters jobs
• Done: Search/filter UI functional with client-side filtering

Wave 2: Detail pages

Task 3-2-01: Job detail page

• Persona: frontend-engineer
• Files: apps/web/app/(marketplace)/jobs/[jobId]/page.tsx, apps/web/components/marketplace/job-detail.tsx, apps/web/components/marketplace/skills-breakdown.tsx, apps/web/components/marketplace/related-jobs.tsx
• Action: Build job detail page. Layout: header (job title, company, location, salary, apply button), body (full description, required competencies list, AI-matched skills breakdown with match percentages), sidebar (employer info card, related jobs list).
• Verify: Job detail renders with all sections; apply button is interactive (non-functional)
• Done: Job detail page complete

Task 3-2-02: Employer profile

• Persona: frontend-engineer
• Files: apps/web/app/(marketplace)/employers/[employerId]/page.tsx, apps/web/components/marketplace/employer-header.tsx, apps/web/components/marketplace/employer-openings.tsx, apps/web/components/marketplace/employer-culture.tsx
• Action: Build employer profile page. Header: logo, company name, tagline, industry, size, location, social links. Body: about section, culture section (mock photos grid), open positions list (job cards).
• Verify: Employer profile renders with all sections; social links are clickable (mock URLs)
• Done: Employer profile complete

Task 3-2-03: Pricing page

• Persona: frontend-engineer
• Files: apps/web/app/(marketplace)/pricing/page.tsx, apps/web/components/marketplace/pricing-card.tsx, apps/web/components/marketplace/feature-comparison.tsx
• Action: Build pricing page. Three pricing cards: Job Posting (single — $49, bundle — $399 for 10, enterprise — custom). Talent Access plans (starter, pro, enterprise). Feature comparison table. CTA buttons on each plan.
• Verify: Pricing page renders with 3 tiers and comparison table; responsive
• Done: Pricing page complete

Must-Haves (Phase 3)

• Job board shows 20+ mock job listings with match scores
• Search bar filters jobs client-side
• Filter sidebar filters by skills, seniority, remote, salary
• Job detail page shows full description, competencies, skills breakdown
• Employer profile shows company info, culture, open positions
• Pricing page shows 3 tiers with feature comparison
• All pages responsive at 375px, 768px, 1280px

---

Phase 4: Employer Dashboard UI

Requirements: REQ-018, REQ-019, REQ-020, REQ-021 Persona: frontend-engineer Goal: All 4 employer dashboard pages render with mock data; charts display

Wave 1: Dashboard + talent search

Task 4-1-01: Employer dashboard overview

• Persona: frontend-engineer
• Files: apps/web/app/(employer)/page.tsx, apps/web/components/employer/overview/metric-cards.tsx, apps/web/components/employer/overview/applicant-pipeline.tsx, apps/web/components/employer/overview/talent-matches.tsx, apps/web/components/employer/overview/analytics-charts.tsx
• Action: Build employer dashboard overview. Top row: 4 metric cards (active postings, total applicants, talent matches, placement rate). Middle: applicant pipeline (kanban-style columns: applied, screening, interview, offer, hired). Right: talent matches (list of matched candidates with match score). Bottom: analytics charts (recharts — bar chart for postings over time, donut chart for applicant sources, line chart for placement trends).
• Verify: Dashboard renders with metric cards, pipeline, matches, and 3 chart types
• Done: Employer dashboard overview complete

Task 4-1-02: Talent search

• Persona: frontend-engineer
• Files: apps/web/app/(employer)/talent/page.tsx, apps/web/components/employer/talent/candidate-card.tsx, apps/web/components/employer/talent/talent-filters.tsx
• Action: Build talent search page. Layout: top (search bar + AI-matched filters), main (grid of candidate cards). Each candidate card: avatar, name, headline (competency stack + level), microcredential badges (top 3), artifact count, defense score, match percentage, "View Profile" button. 15+ mock candidates. Client-side filtering.
• Verify: 15+ candidate cards render; filters work client-side; clicking "View Profile" navigates to candidate profile
• Done: Talent search complete

Wave 2: Detail + management

Task 4-2-01: Candidate profile view

• Persona: frontend-engineer
• Files: apps/web/app/(employer)/talent/[candidateId]/page.tsx, apps/web/components/employer/talent-profile/artifact-gallery.tsx, apps/web/components/employer/talent-profile/process-trace-summary.tsx, apps/web/components/employer/talent-profile/defense-transcripts.tsx, apps/web/components/employer/talent-profile/competency-mini-graph.tsx, apps/web/components/employer/talent-profile/microcredential-verification.tsx
• Action: Build candidate profile view. Header: avatar, name, headline, match score, contact button. Body sections: artifact gallery (grid of project artifacts with thumbnails), process trace summary (timeline of build steps), oral defense transcripts (accordion of defense sessions with Q&A), competency mini-graph (react-flow visualization of candidate's competencies), microcredential verification (list of earned credentials with verification badges).
• Verify: All profile sections render; defense transcripts accordion expands; mini-graph renders
• Done: Candidate profile complete

Task 4-2-02: Posting management

• Persona: frontend-engineer
• Files: apps/web/app/(employer)/postings/page.tsx, apps/web/components/employer/postings/posting-list.tsx, apps/web/components/employer/postings/posting-form.tsx, apps/web/components/employer/postings/applicant-list.tsx
• Action: Build posting management page. Layout: left (list of job postings with status badges: active, draft, expired), right (selected posting detail or create/edit form). Form fields: title, description, required competencies (multi-select), seniority, salary range, location, remote toggle. Applicant list per posting (table with name, applied date, status, match score). "Create New Posting" button opens form.
• Verify: Posting list renders; form is interactive (inputs work, non-functional submit); applicant list displays
• Done: Posting management complete

Must-Haves (Phase 4)

• Dashboard overview shows 4 metric cards, applicant pipeline, 3 charts
• Talent search shows 15+ candidate cards with filters
• Candidate profile shows artifact gallery, process trace, defense transcripts, mini-graph, credentials
• Posting management shows posting list, create/edit form, applicant list
• All pages responsive at 375px, 768px, 1280px

---

Phase 5: Admin Surface UI

Requirements: REQ-022, REQ-023, REQ-024, REQ-025 Persona: frontend-engineer Goal: All 4 admin pages render; competency graph viewer interactive

Wave 1: Overview + learner management

Task 5-1-01: Admin overview

• Persona: frontend-engineer
• Files: apps/web/app/(admin)/page.tsx, apps/web/components/admin/overview/platform-metrics.tsx, apps/web/components/admin/overview/activity-feed.tsx, apps/web/components/admin/overview/system-health.tsx
• Action: Build admin overview. Top: platform metric cards (total learners, total employers, placements, completion rate, NPS). Middle: activity feed (timeline of recent platform events — new registrations, completions, job postings, placements). Right: system health mockup (status indicators for services, uptime bars, error rates).
• Verify: Admin overview renders with metrics, activity feed, system health
• Done: Admin overview complete

Task 5-1-02: Learner management

• Persona: frontend-engineer
• Files: apps/web/app/(admin)/learners/page.tsx, apps/web/components/admin/learners/learner-table.tsx, apps/web/components/admin/learners/learner-detail.tsx
• Action: Build learner management page. Layout: searchable learner table (columns: name, email, stack, progress %, status, joined date). Search and filter (by stack, status). Clicking a learner opens detail panel (progress tracking, competency completion, credential issuance log, recent activity).
• Verify: Learner table renders with mock data; search filters; detail panel opens on click
• Done: Learner management complete

Wave 2: Graph viewer + moderation

Task 5-2-01: Competency graph viewer

• Persona: frontend-engineer
• Files: apps/web/app/(admin)/graph/page.tsx, apps/web/components/admin/graph/competency-graph.tsx, apps/web/components/admin/graph/node-detail.tsx
• Action: Build competency graph viewer using @xyflow/react. Interactive node/edge graph showing competency stacks and their relationships. Nodes: competency stacks (colored by category) and individual competencies. Edges: prerequisite relationships. Node click opens detail panel (competency name, description, stack, prerequisites, learners mastering it). Controls: zoom, pan, fit-to-screen. Mock graph data.
• Verify: Graph renders with nodes and edges; nodes are clickable; detail panel opens; zoom/pan works
• Done: Competency graph viewer complete

Task 5-2-02: Marketplace moderation

• Persona: frontend-engineer
• Files: apps/web/app/(admin)/moderation/page.tsx, apps/web/components/admin/moderation/review-queue.tsx, apps/web/components/admin/moderation/verification-queue.tsx, apps/web/components/admin/moderation/flagged-content.tsx
• Action: Build marketplace moderation page. Three tabs: Job Posting Review (queue of pending job postings with approve/reject buttons), Employer Verification (queue of employers awaiting identity verification), Flagged Content (list of reported content with reason, reporter, actions). All buttons non-functional but interactive (hover states, click feedback).
• Verify: Moderation page renders with 3 tabs; queues display mock items; tab switching works
• Done: Marketplace moderation complete

Must-Haves (Phase 5)

• Admin overview shows platform metrics, activity feed, system health
• Learner management shows searchable table with detail panel
• Competency graph viewer renders interactive graph with clickable nodes
• Marketplace moderation shows 3 tabbed queues
• All pages responsive at 375px, 768px, 1280px

---

Phase 6: Polish + Integration

Requirements: REQ-026, REQ-027, REQ-028 Persona: frontend-engineer, design-system-engineer Goal: Cross-surface consistency, dark mode everywhere, Storybook

Wave 1: Navigation + consistency

Task 6-1-01: Cross-surface navigation polish

• Persona: frontend-engineer
• Files: apps/web/components/navigation-shell.tsx (update), apps/web/components/role-switcher.tsx (update), apps/web/components/breadcrumbs.tsx
• Action: Polish cross-surface navigation. Role switcher dropdown with surface-specific sub-navigation. Breadcrumbs on all pages showing current location. Consistent header/footer across all 4 surfaces. Active nav link highlighting.
• Verify: Breadcrumbs show on all pages; role switcher dropdown works; active links highlighted
• Done: Cross-surface navigation polished

Task 6-1-02: Visual consistency audit

• Persona: design-system-engineer
• Files: apps/web/app/globals.css (update), packages/ui/src/tokens/index.ts (update if needed)
• Action: Audit all surfaces for visual consistency. Check: typography scale (all text uses design tokens), color palette (no hardcoded colors), spacing system (all margins/padding use design tokens), dark mode (all pages support dark mode toggle), WCAG AA contrast (all text meets 4.5:1 ratio). Fix any inconsistencies found.
• Verify: No hardcoded colors; dark mode works on all pages; contrast check passes
• Done: Visual consistency audit complete

Wave 2: Storybook

Task 6-2-01: Storybook setup

• Persona: design-system-engineer
• Files: apps/web/.storybook/main.ts, apps/web/.storybook/preview.ts, packages/ui/src/primitives/*.stories.tsx (one per primitive)
• Action: Set up Storybook for the component library. Configure for Next.js + Tailwind. Create stories for all 12 primitives and key composites (JobCard, CandidateCard, CompetencyBadge, MetricCard). Each story: default, variants, sizes, dark mode.
• Verify: pnpm storybook starts; all primitive stories render; dark mode toggle in Storybook
• Done: Storybook documents all primitives + key composites

Must-Haves (Phase 6)

• Breadcrumbs on all pages
• Role switcher dropdown with surface-specific nav
• Active nav link highlighting
• No hardcoded colors — all from design tokens
• Dark mode works on all 4 surfaces
• WCAG AA contrast passes
• Storybook runs with all primitive stories

---

MVP/UX Sections

User-Facing Surface

The primary user-facing surface is the Nextcraft web application at localhost:3000 (dev) with 4 route groups:

• / — Learner surface (landing, catalog, dashboard, learn, build, defend)
• /marketplace — Marketplace surface (jobs, employers, pricing)
• /employer — Employer dashboard (overview, talent, postings)
• /admin — Admin surface (overview, learners, graph, moderation)

Happy Path

1. User visits landing page → sees hero, how-it-works (Byte→Build→Demonstrate→Defend), program highlights
2. User clicks "Explore Programs" → program catalog shows 5 competency stacks
3. User clicks "AI Orchestration Engineer" → competency stack view shows 15 competencies
4. User clicks a competency → byte tutorial viewer shows concept + worked example
5. User clicks "Start Building" → build sandbox mockup shows IDE UI with telemetry
6. User clicks "Submit for Assessment" → assessment/defense mockup shows rubric, AI reviewer, oral defense interface
7. User navigates to marketplace → job board shows AI-era job listings with match scores
8. User searches/filters jobs → results update client-side
9. User clicks a job → job detail page shows full description, required competencies, employer info
10. User switches to employer dashboard → overview shows metrics, pipeline, charts
11. User searches talent → candidate cards with microcredentials, defense scores
12. User clicks a candidate → profile shows artifact gallery, process trace, defense transcripts
13. User switches to admin → overview shows platform metrics, activity feed
14. User opens competency graph viewer → interactive graph with clickable nodes

UX Acceptance Criteria

1. All 4 surfaces are accessible via the role switcher in the header
2. Navigation is consistent across all surfaces (same header, footer, breadcrumb pattern)
3. All pages are responsive at 375px (mobile), 768px (tablet), 1280px (desktop)
4. Dark mode toggle works on all surfaces
5. All interactive elements have hover states and click feedback
6. Form inputs are non-functional but visually complete (placeholders, labels, validation states)
7. Mock data is realistic and typed — no "lorem ipsum" or placeholder text
8. All charts render correctly (recharts) with mock data
9. Competency graph viewer is interactive (zoom, pan, click nodes)
10. AI tutor chat displays pre-scripted responses on message "send"
11. No console errors on any page
12. pnpm build succeeds without warnings