recipe-manager/.harness/styling-stabilization-execution-board.md

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