Codewalkers/.planning/phases/16-frontend-scaffold/16-01-PLAN.md

---
phase: 16-frontend-scaffold
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [packages/web/package.json, packages/web/vite.config.ts, packages/web/tsconfig.json, packages/web/tsconfig.app.json, packages/web/index.html, packages/web/src/main.tsx, packages/web/src/App.tsx, packages/web/src/index.css, packages/web/postcss.config.js, packages/web/components.json, packages/web/tailwind.config.ts, packages/web/src/lib/utils.ts, package.json, tsconfig.json]
autonomous: true
---

<objective>
Create the Vite + React project with Tailwind CSS and shadcn/ui component library.

Purpose: Establish the frontend build toolchain and component foundation for all subsequent UI work. This is the bare-bones project that compiles and serves an empty page with styling ready.
Output: A working `packages/web/` directory with Vite dev server, Tailwind CSS, and shadcn/ui configured.
</objective>

<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md

# Existing project structure - this is currently a single package
@package.json
@tsconfig.json
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create Vite + React + TypeScript project</name>
  <files>packages/web/package.json, packages/web/vite.config.ts, packages/web/tsconfig.json, packages/web/tsconfig.app.json, packages/web/index.html, packages/web/src/main.tsx, packages/web/src/App.tsx, packages/web/src/index.css, package.json, tsconfig.json</files>
  <action>
1. Create `packages/web/` directory.
2. Initialize a new Vite project with React + TypeScript template files manually (do NOT use `npm create vite` interactively):
   - `packages/web/package.json` with name `@codewalk-district/web`, type `module`, scripts: `dev`, `build`, `preview`, `lint`. Dependencies: `react`, `react-dom`. Dev dependencies: `@types/react`, `@types/react-dom`, `@vitejs/plugin-react`, `typescript`, `vite`.
   - `packages/web/vite.config.ts` with react plugin. Set server proxy: `/trpc` → `http://127.0.0.1:3847/trpc` to avoid CORS issues during development.
   - `packages/web/tsconfig.json` extending `tsconfig.app.json` with references.
   - `packages/web/tsconfig.app.json` targeting ES2020, module ESNext, moduleResolution bundler, strict mode, jsx react-jsx, include `src`.
   - `packages/web/index.html` standard Vite entry pointing to `/src/main.tsx`.
   - `packages/web/src/main.tsx` rendering `<App />` into `#root`.
   - `packages/web/src/App.tsx` minimal component returning `<div>Codewalkers</div>`.

3. Update root `package.json`:
   - Add `"workspaces": ["packages/*"]` for npm workspaces.
   - Add script `"dev:web": "npm run dev --workspace=packages/web"`.
   - Keep all existing scripts and dependencies unchanged.

4. Run `npm install` from root to link workspaces.

Do NOT modify any existing source files in `src/`. Only touch root package.json and tsconfig.json for workspace config.
  </action>
  <verify>
cd packages/web && npx vite build succeeds without errors.
npm run dev:web starts dev server (verify it starts, then kill).
  </verify>
  <done>Vite dev server starts and builds. Root workspace config links packages/web.</done>
</task>

<task type="auto">
  <name>Task 2: Configure Tailwind CSS and shadcn/ui</name>
  <files>packages/web/tailwind.config.ts, packages/web/postcss.config.js, packages/web/src/index.css, packages/web/components.json, packages/web/src/lib/utils.ts, packages/web/package.json</files>
  <action>
1. Install Tailwind CSS v3 in packages/web:
   - Dev dependencies: `tailwindcss`, `postcss`, `autoprefixer`, `@tailwindcss/typography`
   - `postcss.config.js` with tailwindcss and autoprefixer plugins.
   - `tailwind.config.ts` with content paths pointing to `./src/**/*.{ts,tsx}`, extend theme as needed.

2. Update `packages/web/src/index.css` with Tailwind directives:
   ```css
   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   ```
   Plus CSS custom properties for shadcn theming (the standard shadcn/ui CSS variables for colors, radius, etc.).

3. Install shadcn/ui dependencies:
   - Dependencies: `class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`
   - Dev dependency: `tailwindcss-animate`
   - Add tailwindcss-animate plugin to tailwind.config.ts

4. Create `packages/web/components.json` (shadcn/ui config):
   ```json
   {
     "$schema": "https://ui.shadcn.com/schema.json",
     "style": "default",
     "rsc": false,
     "tsx": true,
     "tailwind": {
       "config": "tailwind.config.ts",
       "css": "src/index.css",
       "baseColor": "neutral",
       "cssVariables": true
     },
     "aliases": {
       "components": "@/components",
       "utils": "@/lib/utils"
     }
   }
   ```

5. Create `packages/web/src/lib/utils.ts`:
   ```typescript
   import { type ClassValue, clsx } from "clsx"
   import { twMerge } from "tailwind-merge"

   export function cn(...inputs: ClassValue[]) {
     return twMerge(clsx(inputs))
   }
   ```

6. Configure path aliases in `vite.config.ts` and `tsconfig.app.json`:
   - `@/` → `./src/` (standard shadcn convention)
   - Install `@types/node` as dev dependency for path resolution in vite config.

7. Update `packages/web/src/App.tsx` to use a Tailwind class (e.g., `<div className="text-2xl font-bold p-8">Codewalkers</div>`) to verify Tailwind works.

8. Run `npm install` from root after adding dependencies.
  </action>
  <verify>
npx vite build in packages/web succeeds.
The built output includes Tailwind styles (check dist/assets/*.css contains Tailwind resets).
  </verify>
  <done>Tailwind CSS compiles. shadcn/ui configured with components.json and utils.ts. Path alias `@/` resolves.</done>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] `cd packages/web && npx vite build` succeeds
- [ ] Root `npm install` completes without errors
- [ ] `npm run dev:web` starts Vite dev server
- [ ] Tailwind classes render in built output
- [ ] `@/` path alias resolves in imports
</verification>

<success_criteria>

- Vite + React + TypeScript project builds in packages/web/
- Tailwind CSS configured and compiling
- shadcn/ui components.json and utils ready
- Root npm workspaces configured
- Dev server starts with proxy to backend
  </success_criteria>

<output>
After completion, create `.planning/phases/16-frontend-scaffold/16-01-SUMMARY.md`
</output>