# ICP-Aligned E2E Test Projects

## Purpose

Define 4 test projects that simulate real-world high-value business cases, each targeting a different ICP segment. Each project exercises the full CMS-aiChemist pipeline end-to-end: ADW spec → design tokens → shared UI component → surface integration → CSA delivery artifact. Success means the platform can demonstrably serve these customer segments with a repeatable, traceable workflow.

## ICP Segments Targeted

| # | ICP Segment | Business Case | Test Project |
|---|-------------|---------------|--------------|
| 1 | **Digital Agency** (multi-client) | Brand-specific theming with shared components | TestimonialWall — client social proof component |
| 2 | **SaaS Product Team** | Interactive product feature with data-driven UI | MetricsPanel — KPI dashboard widget |
| 3 | **Content Publisher** | Editorial content surface with CMS integration | AuthorBioCard — contributor profile component |
| 4 | **Enterprise Design System** | Accessible, governed component expansion | FeatureComparisonTable — accessible data table |

## Test Project Definitions

### Project 1: TestimonialWall (Digital Agency ICP)

**Business scenario**: A digital agency client needs a social-proof section for their marketing site. Testimonials render on the Next.js interactive surface, using client-specific brand tokens. (Astro/EmDash integration is a future extension, not tested here.)

**What gets built**:
- 8-10 new DTCG tokens under `components.testimonial` (avatar border, quote style, star color, card variant)
- `TestimonialWall` component in `packages/ui/src/` — responsive grid of testimonial cards with avatar, quote, name, role, star rating
- New `/testimonials` route in Next.js surface
- Design system catalog entry
- CSA briefing artifact: "Client Social Proof Module — Delivery Report"

**Pipeline path exercised**:
1. ADW: spec file → GitHub issue → agent dispatch
2. Tokens: new DTCG group → build.py → CSS custom properties
3. UI: new React component → barrel export
4. Surface: Next.js route + design system catalog update
5. Stats: landing page + dashboard token/component count sync
6. CSA: briefing artifact generation + dashboard entry
7. Brain: push milestone status

**Acceptance criteria**:
- [ ] `components.testimonial` group exists in tokens.json with 8+ tokens
- [ ] `build.py` reports token count increased (121 → ~131)
- [ ] `TestimonialWall` component renders in `/testimonials` route
- [ ] Design system catalog shows TestimonialWall
- [ ] Landing page stats reflect new counts
- [ ] CSA briefing artifact deployed
- [ ] Brain push confirms milestone

---

### Project 2: MetricsPanel (SaaS Product Team ICP)

**Business scenario**: A SaaS product team needs an embeddable KPI metrics widget showing key performance indicators with trend arrows, sparkline-style indicators, and color-coded status thresholds. This is the kind of interactive, data-driven component product teams build constantly.

**What gets built**:
- 10-12 new DTCG tokens under `components.metricsPanel` (status colors, trend indicators, threshold zones, panel layout)
- `MetricsPanel` component in `packages/ui/src/` — grid of metric cards with value, label, trend direction, status color
- New `/metrics` route in Next.js surface with mock SaaS data
- Design system catalog entry
- CSA briefing artifact: "SaaS KPI Dashboard Widget — Feature Spec"

**Pipeline path exercised**:
1. ADW: spec → issue → dispatch
2. Tokens: new DTCG group with semantic status colors → build
3. UI: data-driven component with typed props (MetricItem interface)
4. Surface: Next.js route with realistic mock data
5. Stats sync
6. CSA: feature spec artifact
7. Brain: push

**Acceptance criteria**:
- [ ] `components.metricsPanel` group with 10+ tokens
- [ ] Token count increased
- [ ] `MetricsPanel` renders with 4+ mock KPIs at `/metrics`
- [ ] Trend indicators (up/down/flat) render correctly
- [ ] Status colors derive from tokens (not hardcoded)
- [ ] Design system catalog shows MetricsPanel
- [ ] CSA artifact deployed
- [ ] Brain push confirms milestone

---

### Project 3: AuthorBioCard (Content Publisher ICP)

**Business scenario**: A content publisher needs author profile cards for their editorial platform. Cards display author photo, bio, social links, and article count. This validates the CMS-to-component pipeline — the kind of component EmDash content schema drives.

**What gets built**:
- 6-8 new DTCG tokens under `components.authorBio` (avatar size, social link colors, bio text styling)
- `AuthorBioCard` component in `packages/ui/src/` — profile card with avatar, name, role, bio text, social links, article count badge
- New `/authors` route in Next.js surface with mock author profiles
- Design system catalog entry
- CSA briefing artifact: "Editorial Author Profiles — Content Module Report"

**Pipeline path exercised**:
1. ADW: spec → issue → dispatch
2. Tokens: new DTCG group → build
3. UI: component with rich content props (AuthorProfile interface)
4. Surface: Next.js route with 3-4 mock author profiles
5. Stats sync
6. CSA: content module report
7. Brain: push

**Acceptance criteria**:
- [ ] `components.authorBio` group with 6+ tokens
- [ ] Token count increased
- [ ] `AuthorBioCard` renders with 3+ mock profiles at `/authors`
- [ ] Avatar, social links, bio text all render from props
- [ ] Design system catalog shows AuthorBioCard
- [ ] CSA artifact deployed
- [ ] Brain push confirms milestone

---

### Project 4: FeatureComparisonTable (Enterprise Design System ICP)

**Business scenario**: An enterprise platform team needs an accessible feature comparison table — the kind used on "which plan fits you?" pages, product comparison sheets, and internal feature matrices. Must meet WCAG 2.1 AA. This validates the platform's ability to deliver governed, accessible components.

**What gets built**:
- 8-10 new DTCG tokens under `components.comparisonTable` (header bg, row stripe, check/cross icons, tooltip styling)
- `FeatureComparisonTable` component in `packages/ui/src/` — responsive table with column headers, feature rows, check/cross/partial indicators, optional tooltips
- New `/compare` route in Next.js surface with mock product comparison data
- Design system catalog entry
- CSA briefing artifact: "Enterprise Feature Comparison — Accessibility Compliance Report"

**Pipeline path exercised**:
1. ADW: spec → issue → dispatch
2. Tokens: new DTCG group with accessible contrast ratios → build
3. UI: accessible component with ARIA labels, keyboard navigation, semantic HTML table
4. Surface: Next.js route with realistic feature matrix
5. Stats sync
6. CSA: accessibility-focused delivery report
7. Brain: push

**Acceptance criteria**:
- [ ] `components.comparisonTable` group with 8+ tokens
- [ ] Token count increased
- [ ] `FeatureComparisonTable` renders at `/compare` with semantic `<table>` markup
- [ ] ARIA attributes present (role, scope, labels)
- [ ] Check/cross/partial indicators use tokens not hardcoded colors
- [ ] Design system catalog shows FeatureComparisonTable
- [ ] CSA artifact deployed
- [ ] Brain push confirms milestone

---

## E2E Execution Flow (Per Project)

Each project follows this exact sequence:

```
1. SPEC     — Write ADW spec file to specs/adw-feat-{N}-{name}.md (N starts at 4, continuing from existing #3)
2. PUSH     — Push spec to git
3. ISSUE    — Create GitHub issue via /adw-submit
4. TOKENS   — Add DTCG token group to tokens.json, run build.py
5. COMPONENT— Create React component in packages/ui/src/components/
6. STYLES   — Add CSS to packages/ui/src/styles.css
7. EXPORT   — Update packages/ui/src/index.ts barrel
8. ROUTE    — Create Next.js route in apps/web/src/app/{route}/
9. CATALOG  — Update design system catalog in DesignSystem.tsx
10. STATS   — Sync token/component counts in landing + dashboard
11. BUILD   — Run next build, verify all routes 200
12. CSA     — Generate briefing artifact via /csa-pipeline
13. BRAIN   — Push milestone to NotebookLM via brain-push.sh
14. VERIFY  — Run acceptance criteria checks
```

## Execution Order

Projects execute sequentially: 1 → 2 → 3 → 4. Each project's token count builds on the previous:

| After Project | Token Count | Component Count | Routes |
|---------------|-------------|-----------------|--------|
| Baseline | 121 | 5 | 6 |
| 1 (TestimonialWall) | 133 (+12) | 6 | 7 |
| 2 (MetricsPanel) | 145 (+12) | 7 | 8 |
| 3 (AuthorBioCard) | 158 (+13) | 8 | 9 |
| 4 (FeatureComparisonTable) | 171 (+13) | 9 | 10 |

## Success Criteria (Full Suite)

The test suite passes when ALL of the following are true:

1. All 4 components render correctly on their routes (HTTP 200)
2. All 4 appear in the design system catalog
3. Token pipeline reports final count of 171 tokens
4. Landing page and dashboard show accurate counts
5. `next build` completes with 0 errors for all 10 routes
6. 4 CSA briefing artifacts deployed
7. 4 brain pushes completed
8. 4 GitHub issues created and closable

## Non-Goals

- No Penpot design work (tokens defined directly in DTCG JSON)
- No Stitch ideation (components designed in spec)
- No EmDash/Astro integration (Next.js surface only for these tests)
- No automated test framework (build + grep validation)
- No production deploy (dev build verification only)

## Risk Mitigation

- **Token conflicts**: Each project uses a unique DTCG namespace (`components.testimonial`, `components.metricsPanel`, etc.) — no overlap
- **Build failures**: Each project builds and verifies before the next begins
- **Count drift**: Stats sync is an explicit step, verified via grep
- **CSA failures**: CSA artifacts are independent — one failure doesn't block the next project