226 lines
9.0 KiB
Markdown
226 lines
9.0 KiB
Markdown
# 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
|