# Implementation Plan: UI Baseline

**Branch**: `010-ui-baseline` | **Date**: 2026-03-05 | **Spec**: [spec.md](./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)

```text
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)

```text
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.