3.6 KiB
Implementation Plan: UI Baseline
Branch: 010-ui-baseline | Date: 2026-03-05 | Spec: spec.md
Input: Feature specification from /specs/010-ui-baseline/spec.md
Summary
Establish a modern UI baseline for the encounter screen by integrating Tailwind CSS v4 and shadcn/ui into the existing Vite + React 19 web app. Replace all unstyled HTML with a consistent design system: structured combatant rows with aligned columns, active turn highlight, grouped action bar, icon remove buttons, and consistent typography. No domain or application layer changes — all work is in the apps/web adapter layer.
Technical Context
Language/Version: TypeScript 5.8 (strict mode, verbatimModuleSyntax) Primary Dependencies: React 19, Vite 6, Tailwind CSS v4, shadcn/ui, Lucide React (icons) Storage: N/A (no storage changes — localStorage persistence unchanged) Testing: Vitest (existing layer boundary tests must pass; no new visual tests in MVP baseline) Target Platform: Modern browsers (desktop-first, not broken on mobile) Project Type: Web application (monorepo: apps/web + packages/domain + packages/application) Performance Goals: No perceptible rendering delay; encounter screen usable during live tabletop play Constraints: UI-only changes; domain and application layers untouched Scale/Scope: Single screen (encounter tracker), ~6 component areas to restyle
Constitution Check
GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.
| Principle | Status | Notes |
|---|---|---|
| I. Deterministic Domain Core | PASS | No domain changes |
| II. Layered Architecture | PASS | All changes in adapter layer (apps/web) only |
| III. Agent Boundary | N/A | No agent features involved |
| IV. Clarification-First | PASS | Spec is fully specified, no ambiguities |
| V. Escalation Gates | PASS | Feature stays within spec scope |
| VI. MVP Baseline Language | PASS | Dark theme, full responsive noted as "not in MVP baseline" |
| VII. No Gameplay Rules | PASS | No gameplay logic involved |
Project Structure
Documentation (this feature)
specs/010-ui-baseline/
├── plan.md # This file
├── research.md # Phase 0: Tailwind v4 + shadcn/ui setup research
├── data-model.md # Phase 1: UI component model (no domain changes)
├── quickstart.md # Phase 1: Developer quickstart
├── contracts/ # Phase 1: UI component contracts
│ └── ui-components.md
└── tasks.md # Phase 2 output (created by /speckit.tasks)
Source Code (repository root)
apps/web/
├── src/
│ ├── main.tsx # Add global CSS import
│ ├── index.css # NEW: Tailwind directives + CSS variables
│ ├── lib/
│ │ └── utils.ts # NEW: cn() helper (clsx + twMerge)
│ ├── components/
│ │ └── ui/ # NEW: shadcn/ui primitives (Button, Input, Card, etc.)
│ ├── App.tsx # Refactored: use new components + Tailwind classes
│ └── hooks/
│ └── use-encounter.ts # UNCHANGED
└── package.json # Updated: new dependencies
packages/domain/ # UNCHANGED
packages/application/ # UNCHANGED
Structure Decision: Follows existing monorepo layout. New UI components live in apps/web/src/components/ui/ following shadcn/ui convention. No new packages or layers introduced.
Complexity Tracking
No constitution violations. No complexity justifications needed.