# Recipe Manager — Styling Stabilization Execution Board

Created: 2026-03-27  
Owner: Main Orchestrator  
Status: READY

## Objective
Stabilize frontend styling so recipe-manager has a single, predictable styling system (tokens + reusable UI primitives + clear usage rules) before any further visual redesign work.

## Current Repo Reality (Baseline)

### recipe-manager (frontend)
- Stack is **React + Vite + Tailwind v4** (`frontend/package.json`).
- There is an existing token layer in CSS variables (`src/styles/tokens.css`) and Tailwind mapping (`tailwind.config.js`).
- A reusable utility-class layer exists in `src/index.css` (`.ui-btn`, `.ui-card`, `.ui-input`, `.ui-chip`, `.ui-page`, `.ui-section`).
- A parallel TS token file exists (`src/theme.ts`) with overlapping values (colors/radius/shadows/typography) duplicated from CSS tokens.
- Styling is currently mixed:
  - some components use the `ui-*` classes and CSS variable tokens,
  - some use Tailwind utility colors directly (`bg-blue-*`, `text-slate-*`, `border-gray-*` etc.),
  - some use inline style objects from `theme.ts` (`style={{ boxShadow: shadows.card, borderRadius: radius.lg }}`),
  - `src/App.css` still contains legacy scaffold/demo styles not aligned with the current design system,
  - `MissionControlPanel.tsx` uses older gray utility styling and does not follow `ui-*` primitives.
- Result: design drift risk is high because there is no enforced “one true path” for styling.

### Fintrove (packages/fintrove-app)
- Uses **Next.js + Tailwind v3 + shadcn/ui pattern**.
- Evidence:
  - `components.json` configured for shadcn (`style: "new-york"`, aliases, cssVariables true).
  - `src/components/ui/*` contains shadcn-style primitives (Button, Card, Input, etc.).
  - `@radix-ui/*`, `class-variance-authority`, `clsx`, `tailwind-merge` are installed and actively used.
  - `src/lib/utils.ts` exposes `cn()` pattern (`twMerge(clsx(...))`).
  - App pages/modules heavily import `@/components/ui/*` components.
- Practical note: Fintrove still has some custom CSS for layout edge cases (sidebar), but **core UI is standardized through primitives**.

## Release Gate (Done Definition)
- [ ] recipe-manager has one canonical token source (CSS variables) with no drift between CSS and TS token constants.
- [ ] Base UI primitives are centralized and used across pages/components for buttons, cards, inputs, chips/badges, section shells.
- [ ] No new feature UI uses raw ad-hoc color classes outside tokenized/theme-approved set.
- [ ] Legacy/unused styling artifacts are removed or documented as intentionally retained.
- [ ] A lightweight styling governance doc/checklist exists so future changes remain consistent.

---

## Recommendation Decision

### Recommended direction
**Keep current Tailwind + tokenized CSS variables + shared UI components (Fintrove-inspired discipline), optionally adopting selective shadcn patterns later.**

### Why (repo-specific)
1. recipe-manager already has a strong token foundation (`tokens.css` + `ui-*` classes) and visual language in flight.
2. A full migration to Mantine/Chakra now would add heavy churn and force broad rewrites for limited short-term value.
3. Full shadcn adoption now is possible, but it also introduces migration overhead (Radix + CVA component rewiring) while the current app can be stabilized faster by consolidating what already exists.
4. Best immediate leverage from Fintrove is **process and component architecture**, not a wholesale framework switch:
   - centralized primitives,
   - strict use of shared components,
   - `cn()` utility + variant patterns where helpful.

### Option stance
- **Keep Tailwind + shared UI components:** ✅ **Recommended now**
- **Adopt shadcn/ui immediately:** ⚠️ optional phase-2 enhancement, not first move
- **Adopt Mantine/Chakra:** ❌ not recommended for current phase
- **Borrow Fintrove patterns:** ✅ yes — especially primitives + usage discipline

---

## Task Backlog

### T01 — Styling Inventory + Drift Map
Priority: P0  
Owner: agent-style-audit  
Dependencies: none

Deliverables:
- Component/page inventory tagged by styling mode:
  - `ui-*` primitives,
  - raw Tailwind utilities,
  - inline `theme.ts` styles,
  - legacy CSS (`App.css`) usage.
- Drift report listing top inconsistency hotspots (starting with `App.tsx`, `MissionControlPanel.tsx`, major pages).

Acceptance:
- [ ] Written inventory committed under `.harness/docs/styling-inventory.md`.
- [ ] Every top-level page and shared component classified.
- [ ] Explicit “first conversion targets” list produced.

---

### T02 — Canonical Token Source Lock
Priority: P0  
Owner: agent-design-system  
Dependencies: T01

Deliverables:
- Decide and document canonical token authority (CSS variable tokens in `tokens.css`).
- Align/trim `theme.ts` so it becomes a typed accessor/mirror (or remove overlapping hardcoded values where possible).
- Add a short token usage guide (when to use class vs CSS var vs helper constant).

Acceptance:
- [ ] No conflicting duplicate token values between CSS and TS token surfaces.
- [ ] Token mapping doc exists (`.harness/docs/styling-token-contract.md`).
- [ ] New token additions have one defined source-of-truth path.

---

### T03 — UI Primitive Contract (Recipe Manager UI Kit)
Priority: P0  
Owner: agent-ui-foundation  
Dependencies: T02

Deliverables:
- Formalize minimal primitives (Button/Card/Input/Badge/Section/Page shell) using existing `ui-*` base.
- Add composable wrappers/components where needed to reduce repeated class strings.
- Introduce `cn()` utility (Fintrove pattern) if class composition complexity requires it.

Acceptance:
- [ ] Shared primitive surface exists and is documented.
- [ ] At least 3 high-traffic screens consume primitives instead of duplicated class blocks.
- [ ] No regression in behavior/accessibility for converted areas.

---

### T04 — High-Drift Screen Conversions
Priority: P1  
Owner: agent-core-ui  
Dependencies: T03

Deliverables:
- Convert highest inconsistency files first:
  - `src/App.tsx` nav/header/footer,
  - `src/components/MissionControlPanel.tsx`,
  - one primary page (`RecipeListPage` or `RecipeDetailPage`) where mixed style patterns are most visible.
- Replace raw color utility classes with token-aware variants/primitives where practical.

Acceptance:
- [ ] Converted files show clear reduction in ad-hoc style usage.
- [ ] Visual parity maintained (or intentionally improved with notes).
- [ ] No TypeScript/runtime regressions.

---

### T05 — Legacy Style Debt Cleanup
Priority: P1  
Owner: agent-style-cleanup  
Dependencies: T04

Deliverables:
- Remove or quarantine stale scaffold styles in `src/App.css`.
- Remove dead class names/selectors no longer referenced.
- Add comments for any intentionally retained exceptions.

Acceptance:
- [ ] `App.css` no longer contains unrelated starter/template styling.
- [ ] Dead style selectors removed.
- [ ] Build output CSS size/change reviewed and documented.

---

### T06 — Guardrails + Lightweight Governance
Priority: P1  
Owner: agent-qa-polish  
Dependencies: T04, T05

Deliverables:
- Add a concise styling contribution checklist (`.harness/docs/styling-governance.md`).
- Add lightweight guardrail command in frontend (`npm run style:guardrails`) for scoped app-shell/primitive checks.
- PR checklist items for token/primitive usage and accessibility checks.

Acceptance:
- [ ] Governance doc exists and is referenced by board/task workflow.
- [ ] At least one automated or semi-automated guardrail in place.
- [ ] Team can explain “how to style new UI here” in <2 minutes.

---

### T07 — Stabilization QA Pass
Priority: P1  
Owner: agent-qa-polish  
Dependencies: T06

Deliverables:
- Before/after screenshots of converted surfaces.
- Keyboard focus + contrast spot-check on converted components.
- Regression notes and signoff summary.

Acceptance:
- [ ] QA notes committed under `.harness/docs/styling-stabilization-qa.md`.
- [ ] No critical visual regressions on mobile/desktop.
- [ ] Release gate checklist completed.

---

## Wave Plan (Execution Order)

### Wave 1 — Discovery + Rules
- T01 (inventory/drift map)
- T02 (token source lock)

### Wave 2 — Foundation
- T03 (primitive contract)

### Wave 3 — Conversion + Cleanup
- T04 (high-drift screens)
- T05 (legacy style debt)

### Wave 4 — Prevent Regressions + Signoff
- T06 (guardrails/governance)
- T07 (stabilization QA)

## Dependencies Summary
- T02 depends on T01 so token decisions are based on real usage.
- T03 depends on T02 to avoid rebuilding primitives on unstable tokens.
- T04/T05 follow T03 for consistent rollout.
- T06/T07 close the loop and keep drift from reappearing.

## First Task to Launch
**Launch T01 — Styling Inventory + Drift Map.**

Reason: this repo already has multiple parallel styling paths. Without an explicit inventory, refactor work will be noisy and may increase inconsistency. T01 gives the concrete map needed to sequence low-risk, high-impact stabilization.

## Reporting Protocol (for each task)
1) task id  
2) files changed  
3) before/after evidence (screenshots or diffs)  
4) blockers/risks  
5) ready-for-review flag