# AGNET UI/UX Library — Implementation Plan

**Project:** AGNET Uzbekistan Platform  
**Version:** 1.0.0-plan  
**Created:** 2026-06-27  
**Status:** Draft — awaiting approval  
**Reference mockups:**
- Identity / Farmer Profile → `public/agnet-assets/agnet-identity-dashboard.png`
- Finance / Credit Management → `public/agnet-assets/agnet-finance-dashboard.png`
- Inputs / Supply Chain → `public/agnet-assets/agnet-inputs-dashboard.png`

**Related specs:** [`PROJECT_PLAN.md`](./PROJECT_PLAN.md), [`WIZARD_FIELD_SPEC.md`](./WIZARD_FIELD_SPEC.md), [`AGRI_ACCESS_INTEGRATION_PLAN.md`](./AGRI_ACCESS_INTEGRATION_PLAN.md)

---

## 1. Executive Summary

AGNET currently ships functional farmer dashboard modules (Identity, Finance, Inputs, Trade) built from ad-hoc Tailwind utilities. The three high-fidelity mockups define a **unified product design language** — deep forest-green sidebar, light sage workspace, white card grid, verification-first status system — that is not yet codified as a reusable library.

This plan defines a **SpecKit-compatible phased rollout** to:

1. Establish a canonical design system aligned with mockups (not stale auto-generated tokens)
2. Build a shared `components/ui/` + `components/agnet/` component library
3. Rebuild the three dashboard surfaces to match mockup fidelity
4. Wire data from existing BFF view models and extend APIs where mockups require new fields
5. Preserve i18n, accessibility, and existing E2E test coverage

**Estimated effort:** 6 phases, ~8–12 weeks (1–2 engineers), parallelizable after Phase 1.

---

## 2. SpecKit Integration

SpecKit is **not currently installed** (no `.specify/` directory). This plan is structured so it can be adopted via `/speckit-updater` when approved.

### 2.1 Recommended SpecKit bootstrap

```bash
# After user approval — conversational install via speckit-updater skill
/speckit-updater
# → approve install → creates .specify/ structure
```

### 2.2 Proposed `.specify/` mapping

| SpecKit artifact | AGNET file | Purpose |
|------------------|------------|---------|
| `.specify/memory/constitution.md` | Derived from §3 below | Non-negotiable UX principles |
| `.specify/specs/ui-library/spec.md` | This document §4–8 | Feature specification |
| `.specify/specs/ui-library/plan.md` | This document §9 | Implementation phases |
| `.specify/specs/ui-library/tasks.md` | This document §10 | Task backlog with IDs |
| `.specify/specs/ui-library/checklist.md` | §11 Pre-delivery checklist | QA gate |

### 2.3 Custom commands (post-install)

| Command | Action |
|---------|--------|
| `/speckit.ui.tokens` | Regenerate CSS vars from `design-system/agnet-dashboard/MASTER.md` |
| `/speckit.ui.story` | Scaffold Storybook story for a component |
| `/speckit.ui.audit` | Run axe + visual regression on dashboard routes |

---

## 3. Constitution — UX Principles

These rules override all page-specific overrides.

1. **Verification-first** — Every trust signal (GIS Verified, eKYC Verified, Compliant) must use consistent badge + icon + color semantics; never rely on color alone.
2. **Mockup fidelity, not pixel-perfect** — Match layout, hierarchy, and component patterns from reference PNGs; adapt to real data shapes.
3. **Reuse before rebuild** — Extend `lib/farmer-dashboard.ts` view models; do not duplicate API logic in components.
4. **No emoji icons** — Lucide SVG only (existing convention).
5. **i18n by default** — All new strings go to `lib/i18n/dashboard-labels.ts` (or module-specific label files); no hardcoded English in module bodies.
6. **Accessible by default** — 4.5:1 contrast, 44×44px touch targets, visible focus rings, `prefers-reduced-motion` respected (existing Framer Motion pattern).
7. **Progressive enhancement** — Map/chart widgets degrade to static images + alt text when WebGL or Recharts unavailable.
8. **Light mode primary** — Mockups are light-first; dark mode inherits from `globals.css` tokens, not re-designed separately in v1.

---

## 4. Design System — Mockup-Derived Tokens

> **Important:** Auto-generated `design-system/agnet-global/MASTER.md` (gold/purple fintech) and `design-system/agnet-dashboard/MASTER.md` are **superseded** by this section. Update `design-system/agnet-dashboard/MASTER.md` in Phase 1.

### 4.1 Color palette (from mockups)

| Token | Hex | Usage |
|-------|-----|-------|
| `--sidebar-bg` | `#004D40` | Left nav rail (Identity, Finance, Inputs) |
| `--sidebar-bg-deep` | `#003328` | Sidebar hover/active |
| `--brand-green` | `#08733a` | Headings, primary actions (maps to existing `--green-deep`) |
| `--success-green` | `#22C55E` | Verified badges, chart bars, checkmarks |
| `--success-bg` | `#ECFDF5` | Success banners (eKYC verified, Compliant) |
| `--page-bg` | `#F5F7F2` | Main workspace background |
| `--surface` | `#FFFFFF` | Card backgrounds |
| `--ink` | `#102018` | Primary text (existing) |
| `--muted` | `#66766E` | Secondary labels (existing) |
| `--warning-amber` | `#F59E0B` | Equipment KPI, pending SLA |
| `--border` | `rgba(32, 96, 70, 0.12)` | Card borders (existing) |

### 4.2 Typography

| Role | Font | Weight | Size |
|------|------|--------|------|
| App title | Onest | 600–700 | 24–28px |
| Card title | Onest | 600 | 16–18px |
| Body | Inter | 400–500 | 14–16px |
| KPI value | Onest | 700 | 28–32px |
| Badge | Inter | 500 | 12px |

Keep existing Geist/Onest/Inter stack from `app/layout.tsx` — no font migration in v1.

### 4.3 Spacing & shape

| Token | Value | Notes |
|-------|-------|-------|
| `--radius-card` | `12px` | Mockup cards (reduce from current 28px for dashboard-only) |
| `--radius-pill` | `9999px` | Badges, nav pills |
| `--shadow-card` | `0 1px 3px rgba(0,0,0,0.08)` | Subtle elevation |
| Grid gap | `16px` / `24px` | 4-col KPI row, 3-col detail row |

### 4.4 Page overrides

| Page file | Path | Key deviations |
|-----------|------|----------------|
| Identity | `design-system/agnet-dashboard/pages/identity.md` | GIS map hero 60/40 split; 4-col bottom grid |
| Finance | `design-system/agnet-dashboard/pages/finance.md` | Circular gauges; horizontal approval stepper |
| Inputs | `design-system/agnet-dashboard/pages/inputs.md` | 5 KPI cards; dark voucher card; delivery stepper |

---

## 5. Component Library Architecture

### 5.1 Directory structure

```
components/
├── ui/                          # Primitives (new)
│   ├── button.tsx
│   ├── badge.tsx
│   ├── card.tsx
│   ├── tabs.tsx
│   ├── progress-ring.tsx
│   ├── stepper.tsx
│   ├── data-row.tsx
│   ├── kpi-card.tsx
│   ├── status-banner.tsx
│   ├── avatar.tsx
│   ├── dropdown.tsx
│   └── chart/
│       ├── bar-chart.tsx
│       └── chart-container.tsx
├── agnet/                       # AGNET composites (new)
│   ├── layout/
│   │   ├── DashboardSidebar.tsx
│   │   ├── DashboardHeader.tsx
│   │   └── DashboardPageLayout.tsx
│   ├── identity/
│   │   ├── GisMapCard.tsx
│   │   ├── EkycCard.tsx
│   │   ├── FarmProfileCard.tsx
│   │   ├── LandEvidenceList.tsx
│   │   ├── YieldHistoryChart.tsx
│   │   └── ComplianceChecklist.tsx
│   ├── finance/
│   │   ├── CaseHeaderMetrics.tsx
│   │   ├── EligibilityGauge.tsx
│   │   ├── BankRoutingList.tsx
│   │   ├── DocumentChecklist.tsx
│   │   └── ApprovalPathStepper.tsx
│   └── inputs/
│       ├── InputsKpiRow.tsx
│       ├── SupplierRatingList.tsx
│       ├── FeaturedCatalogTabs.tsx
│       ├── VoucherCard.tsx
│       ├── PaymentRouteStepper.tsx
│       └── DeliveryTrackingStepper.tsx
├── farmer/                      # Existing — refactor to consume agnet/*
│   ├── modules/
│   ├── FarmerDashboardShell.tsx → migrate to DashboardSidebar
│   └── ...
```

### 5.2 Library strategy decision

| Option | Recommendation | Rationale |
|--------|----------------|-----------|
| **A. Custom primitives** | ✅ **Recommended** | Matches existing stack; no Radix/shadcn migration risk; full control over verification UX |
| B. shadcn/ui + Radix | Defer to v2 | Would require `components.json`, theme bridge, and refactor of all farmer components |

**Dependency additions (Phase 1):**

- `recharts` — Yield history bar chart, optional finance gauges
- `@tanstack/react-table` (optional) — Supplier/catalog lists if sorting needed

### 5.3 Component inventory

#### Primitives (`components/ui/`)

| Component | Mockup source | Priority |
|-----------|---------------|----------|
| `Card` | All dashboards | P0 |
| `Badge` | GIS Verified, Verified, Best Match, Approved | P0 |
| `KpiCard` | Inputs 5-card row; Finance top metrics | P0 |
| `ProgressRing` | Eligibility 78/100, SLA 18/48 hrs | P0 |
| `Stepper` (horizontal) | Approval Path, Delivery Tracking, Payment Route | P0 |
| `StatusBanner` | eKYC success, Compliant all checks | P0 |
| `DataRow` | Farm Profile icon + label + value rows | P0 |
| `Tabs` | Featured Catalog Seed/Fertiliser/Equipment | P1 |
| `Avatar` | eKYC photo, header profile | P1 |
| `BarChart` | Yield History 2020–2024 | P1 |

#### Layout (`components/agnet/layout/`)

| Component | Behavior |
|-----------|----------|
| `DashboardSidebar` | Fixed 64–72px green rail; icon nav; module-specific active state |
| `DashboardHeader` | Module title + subtitle; optional GIS Verified pill; locale/notifications/avatar |
| `DashboardPageLayout` | Sidebar + header + scrollable main; responsive collapse to bottom nav on mobile |

---

## 6. Page Specifications

### 6.1 Identity — Farmer Profile (`/farmers/dashboard/identity`)

**Reference:** `agnet-identity-dashboard.png`

#### Layout zones

```
┌─────────────────────────────────────────────────────────────┐
│ Header: "AGNET Identity"                    [GIS Verified]  │
├──────────────────────────┬──────────────────────────────────┤
│ GIS Map Card (60%)       │ eKYC Card (40%)                  │
│ - Satellite + polygon    │ - Photo, masked Aadhaar/mobile   │
│ - Area label (4.52 ha)   │ - Verified badge                 │
│ - Coordinates overlay    │ - Success banner                 │
├──────────┬──────────┬──────────┬────────────────────────────┤
│ Farm     │ Land     │ Yield    │ Compliance                 │
│ Profile  │ Evidence │ History  │ Profile                    │
└──────────┴──────────┴──────────┴────────────────────────────┘
```

#### Data mapping (extend `IdentityViewModel`)

| UI field | Source | Gap |
|----------|--------|-----|
| GIS polygon + coords | `hasGisMapping`, parcel API | Need geometry + centroid from GIS service |
| eKYC photo, DOB | KYC step data | Extend view model |
| Farmer ID | `AGID-FMR-*` | Add to backend response |
| Land evidence docs | Document service | List with verify status |
| Yield history by crop | Scoring/GIS historical | **New API** or mock in dev |
| Compliance checklist | Rules engine | Map from eligibility rules |

#### Current vs target

| Aspect | Current (`IdentityModule.tsx`) | Target |
|--------|-------------------------------|--------|
| Layout | Stacked text cards | 2-row grid per mockup |
| GIS | Boolean flag | Interactive/static map with polygon |
| eKYC | Text status | Photo card with masked PII |
| Yield | Missing | Bar chart + crop dropdown |
| Compliance | Partial doc status | 6-item checklist + Compliant banner |

---

### 6.2 Finance — Credit Management (`/farmers/dashboard/finance`)

**Reference:** `agnet-finance-dashboard.png`

#### Layout zones

```
┌──────────┬──────────┬──────────┬──────────┐
│ Case ID  │ Eligib.  │ Routed   │ SLA      │
│ + GIS ✓  │ 78/100   │ Agrobank │ 18/48hrs │
├──────────┴──────────┴──────────┴──────────┤
│ Farmer & Farm │ Bank Routing │ Doc Checklist │
├─────────────────────────────────────────────┤
│ Approval Path (full-width horizontal stepper)│
└─────────────────────────────────────────────┘
```

#### Data mapping (extend `FinanceViewModel`)

| UI field | Source | Gap |
|----------|--------|-----|
| Eligibility score /100 | Scoring service | Wire `CreditScoreArc` pattern |
| Bank routing matches | Case routing API | **New** — top matches with % |
| SLA countdown | Case metadata | **New** — due date + remaining hrs |
| Document checklist | Documents service | Per-doc verified/pending |
| Approval stages | Case status history | Map existing `stages[]` to stepper |

#### Reuse existing

- `components/scoring/CreditScoreArc.tsx` → refactor into `ProgressRing`
- `FinanceModule` satellite carousel → embed in Farmer & Farm card map slot
- `getFarmerExplanationText` → collapsible panel below stepper (not in mockup; keep as enhancement)

---

### 6.3 Inputs — Supply Chain Dashboard (`/farmers/dashboard/inputs`)

**Reference:** `agnet-inputs-dashboard.png`

#### Layout zones

```
┌─────┬─────┬─────┬─────┬─────┐
│Seed │Fert.│Equip│Vouch│Deliv│  KPI row
├──────────┬─────────────┬──────┤
│ Top      │ Featured    │Input │
│ Suppliers│ Catalog     │Vouch.│
│          │ (tabs)      │ card │
├──────────┴─────────────┴──────┤
│ Delivery Tracking Stepper + Map│
└───────────────────────────────┘
```

#### Data mapping (extend `InputsViewModel`)

| UI field | Source | Gap |
|----------|--------|-----|
| KPI counts | Catalog/supplier APIs | **New** — aggregate endpoints |
| Supplier ratings | Supplier registry | **New** |
| Featured catalog | Product catalog | **New** |
| Voucher + payment route | Voucher service | **New** |
| Delivery tracking | Logistics service | **New** |

> **Note:** Inputs mockup is the most API-heavy surface. Phase 5 ships UI with `dev-api-mock.ts` fixtures first; backend contracts follow in Phase 6.

---

## 7. Responsive & Accessibility Matrix

| Breakpoint | Sidebar | Grid behavior |
|------------|---------|---------------|
| ≥1280px | Fixed rail | Full mockup grids (4-col, 3-col) |
| 768–1279px | Collapsed icons | 2-col grids, stacked hero |
| <768px | Bottom tab bar (existing shell pattern) | Single column; steppers scroll horizontally |

| Requirement | Implementation |
|-------------|----------------|
| Focus rings | `ring-2 ring-green-deep ring-offset-2` on interactive elements |
| Chart alt | `<table className="sr-only">` summary for yield data |
| Map alt | Descriptive alt + coordinates as text |
| Motion | `useReducedMotion()` disables stepper/chart animations |
| i18n | uz / ru / en via extended `dashboard-labels.ts` |

---

## 8. Data Layer Changes

### 8.1 View model extensions (`lib/farmer-dashboard.ts`)

```typescript
// IdentityViewModel additions
interface IdentityViewModel {
  // existing fields...
  farmerId?: string;
  farmName?: string;
  ekyc?: { photoUrl?: string; dob?: string; aadhaarMasked?: string; mobileMasked?: string };
  gis?: { areaHa: number; lat: number; lng: number; polygonGeoJson?: GeoJSON.Polygon };
  landEvidence?: Array<{ name: string; type: 'pdf' | 'doc'; verified: boolean }>;
  yieldHistory?: Array<{ year: number; yieldTHa: number; crop: string }>;
  compliance?: Array<{ key: string; label: string; passed: boolean }>;
}

// FinanceViewModel additions
interface FinanceViewModel {
  // existing fields...
  eligibilityScore?: number;
  eligibilityLabel?: string;
  routedInstitution?: { name: string; priority: string; isBestMatch: boolean };
  sla?: { remainingHours: number; totalHours: number; dueAt: string };
  bankMatches?: Array<{ name: string; score: number; status: 'routed' | 'view' }>;
  documents?: Array<{ name: string; status: 'verified' | 'pending' }>;
}

// InputsViewModel additions
interface InputsViewModel {
  // existing fields...
  kpis?: { seed: number; fertiliser: number; equipment: number; vouchers: number; inTransit: number };
  suppliers?: Array<{ name: string; logoUrl?: string; rating: number }>;
  catalog?: Array<{ category: string; items: CatalogItem[] }>;
  voucher?: VoucherDetail;
  delivery?: DeliveryTracking;
}
```

### 8.2 Mock fixtures

Extend `lib/dev-api-mock.ts` with mockup-faithful fixtures for all new fields (mirroring PNG content: Ramesh Pradhan / Islomjon Abdullaev / Burkina Faso catalog as configurable dev personas).

---

## 9. Implementation Phases

```mermaid
gantt
    title AGNET UI/UX Library Rollout
    dateFormat  YYYY-MM-DD
    section Phase1
    Design tokens + ui primitives     :p1, 2026-07-01, 10d
    section Phase2
    Layout shell refactor             :p2, after p1, 7d
    section Phase3
    Identity dashboard                :p3, after p2, 10d
    section Phase4
    Finance dashboard                 :p4, after p2, 10d
    section Phase5
    Inputs dashboard                  :p5, after p2, 14d
    section Phase6
    API integration + i18n + QA       :p6, after p3, 14d
```

### Phase 1 — Foundation (Week 1–2) `UI-001`

**Goal:** Canonical tokens + primitive component library.

| Task | Deliverable |
|------|-------------|
| UI-001a | Rewrite `design-system/agnet-dashboard/MASTER.md` with §4 tokens |
| UI-001b | Add page overrides: `pages/identity.md`, `pages/finance.md`, `pages/inputs.md` |
| UI-001c | Extend `tailwind.config.ts` with sidebar, success, KPI tokens |
| UI-001d | Create `components/ui/*` primitives (Card, Badge, KpiCard, ProgressRing, Stepper, StatusBanner, DataRow) |
| UI-001e | Add Storybook or Ladle (optional) — `npm run storybook` for visual QA |
| UI-001f | Unit tests for Stepper states, Badge variants, ProgressRing a11y |

**Exit criteria:** Storybook/docs page renders all primitives; axe scan passes.

---

### Phase 2 — Layout Shell (Week 2–3) `UI-002`

**Goal:** Shared dashboard chrome matching mockup sidebar + header.

| Task | Deliverable |
|------|-------------|
| UI-002a | `DashboardSidebar` — green rail, Lucide icons, active pill |
| UI-002b | `DashboardHeader` — module title, GIS Verified slot, settings |
| UI-002c | `DashboardPageLayout` — composes sidebar + header + main |
| UI-002d | Refactor `FarmerDashboardShell.tsx` to use new layout (keep mobile bottom nav) |
| UI-002e | Update E2E `farmer-dashboard.spec.ts` for new nav selectors |

**Exit criteria:** All four module routes render inside new shell; no visual regression on hub page.

---

### Phase 3 — Identity Dashboard (Week 3–4) `UI-003`

**Goal:** Match `agnet-identity-dashboard.png`.

| Task | Deliverable |
|------|-------------|
| UI-003a | `GisMapCard` — static map image v1; MapLibre/Leaflet v2 |
| UI-003b | `EkycCard` — avatar, masked fields, success banner |
| UI-003c | Bottom 4-col grid: FarmProfile, LandEvidence, YieldHistory, Compliance |
| UI-003d | Rewrite `IdentityModule.tsx` as composition of agnet/identity/* |
| UI-003e | Extend mock + view model; wire `/api/farmer/dashboard` |
| UI-003f | i18n keys for all identity strings |
| UI-003g | Visual regression snapshot vs reference PNG |

**Exit criteria:** Side-by-side review with mockup ≥90% layout match; E2E identity route passes.

---

### Phase 4 — Finance Dashboard (Week 3–5) `UI-004`

**Goal:** Match `agnet-finance-dashboard.png`.

| Task | Deliverable |
|------|-------------|
| UI-004a | `CaseHeaderMetrics` — 4 KPI cards top row |
| UI-004b | `EligibilityGauge` — refactor from `CreditScoreArc` |
| UI-004c | `BankRoutingList` + `DocumentChecklist` |
| UI-004d | `ApprovalPathStepper` — map `FinanceViewModel.stages` |
| UI-004e | Rewrite `FinanceModule.tsx` |
| UI-004f | Integrate Agri-Access enrichment hooks (per AA-012–AA-023) |

**Exit criteria:** Stepper reflects case state transitions; gauges show mock scores.

---

### Phase 5 — Inputs Dashboard (Week 4–6) `UI-005`

**Goal:** Match `agnet-inputs-dashboard.png`.

| Task | Deliverable |
|------|-------------|
| UI-005a | `InputsKpiRow` — 5 metric cards |
| UI-005b | `SupplierRatingList` + `FeaturedCatalogTabs` |
| UI-005c | `VoucherCard` (dark green) + `PaymentRouteStepper` |
| UI-005d | `DeliveryTrackingStepper` + map widget |
| UI-005e | Rewrite `InputsModule.tsx` |
| UI-005f | Mock catalog/supplier/voucher/delivery fixtures |

**Exit criteria:** Full page renders with mock data; tab switching works; steppers animate.

---

### Phase 6 — Integration, i18n, QA (Week 6–8) `UI-006`

**Goal:** Production-ready library.

| Task | Deliverable |
|------|-------------|
| UI-006a | OpenAPI additions for new dashboard fields (BFF + core-api tickets) |
| UI-006b | Replace mock fixtures with real APIs where available |
| UI-006c | Complete uz/ru/en translations for all three modules |
| UI-006d | axe-core E2E on all dashboard routes |
| UI-006e | Performance: LCP < 2.5s on 3G for dashboard pages |
| UI-006f | Developer docs: `docs/ui-library.md` — usage examples |
| UI-006g | Deprecate duplicate styles in `globals.css` marketing block where safe |

**Exit criteria:** All E2E green; i18n complete; API contract published.

---

## 10. Task Backlog (SpecKit tasks.md)

| ID | Phase | Task | Owner | Deps | Status |
|----|-------|------|-------|------|--------|
| UI-001a | 1 | Rewrite dashboard MASTER.md tokens | — | — | ⬜ |
| UI-001b | 1 | Create page override markdown files | — | UI-001a | ⬜ |
| UI-001c | 1 | Extend tailwind.config.ts | — | UI-001a | ⬜ |
| UI-001d | 1 | Build ui/ primitives | — | UI-001c | ⬜ |
| UI-001e | 1 | Storybook setup (optional) | — | UI-001d | ⬜ |
| UI-002a | 2 | DashboardSidebar | — | UI-001d | ⬜ |
| UI-002b | 2 | DashboardHeader | — | UI-001d | ⬜ |
| UI-002c | 2 | DashboardPageLayout | — | UI-002a,b | ⬜ |
| UI-002d | 2 | Refactor FarmerDashboardShell | — | UI-002c | ⬜ |
| UI-003a | 3 | GisMapCard | — | UI-002c | ⬜ |
| UI-003b | 3 | EkycCard | — | UI-001d | ⬜ |
| UI-003c | 3 | Identity bottom grid cards | — | UI-001d | ⬜ |
| UI-003d | 3 | Rewrite IdentityModule | — | UI-003a-c | ⬜ |
| UI-004a | 4 | CaseHeaderMetrics | — | UI-001d | ⬜ |
| UI-004b | 4 | EligibilityGauge | — | UI-001d | ⬜ |
| UI-004c | 4 | BankRouting + DocChecklist | — | UI-001d | ⬜ |
| UI-004d | 4 | ApprovalPathStepper | — | UI-001d | ⬜ |
| UI-004e | 4 | Rewrite FinanceModule | — | UI-004a-d | ⬜ |
| UI-005a | 5 | InputsKpiRow | — | UI-001d | ⬜ |
| UI-005b | 5 | Suppliers + Catalog | — | UI-001d | ⬜ |
| UI-005c | 5 | VoucherCard + PaymentRoute | — | UI-001d | ⬜ |
| UI-005d | 5 | DeliveryTracking + Map | — | UI-001d | ⬜ |
| UI-005e | 5 | Rewrite InputsModule | — | UI-005a-d | ⬜ |
| UI-006a | 6 | OpenAPI dashboard extensions | — | UI-003–005 | ⬜ |
| UI-006b | 6 | Real API wiring | — | UI-006a | ⬜ |
| UI-006c | 6 | i18n completion | — | UI-003–005 | ⬜ |
| UI-006d | 6 | axe E2E suite | — | UI-003–005 | ⬜ |
| UI-006f | 6 | ui-library.md docs | — | UI-001–005 | ⬜ |

---

## 11. Pre-Delivery Checklist (from ui-ux-pro-max)

### Visual quality
- [ ] No emojis as icons — Lucide SVG only
- [ ] Consistent icon sizing (`w-5 h-5` nav, `w-4 h-4` inline)
- [ ] Hover states use color/opacity transitions (150–300ms), no layout shift
- [ ] Cards use `--radius-card` (12px) within dashboard surfaces

### Interaction
- [ ] All clickable elements have `cursor-pointer`
- [ ] Buttons disabled during async operations
- [ ] Focus rings visible on keyboard navigation

### Accessibility
- [ ] Text contrast ≥ 4.5:1 on light backgrounds
- [ ] Charts have screen-reader table fallback
- [ ] `prefers-reduced-motion` disables stepper/chart animation

### Layout
- [ ] No horizontal scroll at 375px
- [ ] Sidebar collapses gracefully on tablet/mobile
- [ ] Content not hidden behind sticky header

### i18n
- [ ] uz / ru / en complete for Identity, Finance, Inputs modules
- [ ] RTL not required for v1 (Uzbekistan/CIS Latin/Cyrillic)

---

## 12. Risks & Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Inputs APIs don't exist | Phase 5 blocked on backend | Ship with mock fixtures; define OpenAPI first |
| GIS map integration complexity | Identity hero delayed | Static map + polygon SVG in v1; MapLibre in v1.1 |
| Design doc drift | Inconsistent UI | Single source: `design-system/agnet-dashboard/MASTER.md` |
| shadcn migration pressure | Scope creep | Explicit deferral to v2; custom primitives only |
| E2E breakage on shell refactor | CI red | Phase 2 includes selector updates before merge |

---

## 13. Success Metrics

| Metric | Target |
|--------|--------|
| Layout match vs mockups (design review) | ≥90% |
| Component reuse ratio in modules | ≥80% from `ui/` + `agnet/` |
| axe violations on dashboard routes | 0 critical |
| i18n coverage (module strings) | 100% |
| E2E pass rate | 100% on `farmer-dashboard.spec.ts` + new module specs |

---

## 14. Next Steps

1. **Approve this plan** — confirm phase order and custom-primitives strategy (vs shadcn).
2. **Install SpecKit** (optional) — run `/speckit-updater` to materialize `.specify/` structure from §2.
3. **Start Phase 1** — assign UI-001a–f; first PR rewrites tokens + ships `Card`, `Badge`, `Stepper`.
4. **Design review gate** — after Phase 3 Identity rebuild, compare against `agnet-identity-dashboard.png` before proceeding to Finance/Inputs parallel work.

---

*Generated with ui-ux-pro-max design intelligence workflow. Mockup tokens manually derived from reference PNGs supersede auto-generated fintech palette.*