Skip to content

feat(cardshed): scaffold apps/ui + design system (M1+M2)#156

Merged
w7-mgfcode merged 1 commit into
masterfrom
feat/cardshed-ui-scaffold
May 21, 2026
Merged

feat(cardshed): scaffold apps/ui + design system (M1+M2)#156
w7-mgfcode merged 1 commit into
masterfrom
feat/cardshed-ui-scaffold

Conversation

@w7-mgfcode
Copy link
Copy Markdown
Owner

@w7-mgfcode w7-mgfcode commented May 21, 2026

Closes #148. First sub-issue of umbrella #146 (PRP 3 §A M1–M17).

Summary

  • M1 — SCAFFOLD apps/ui. Vite 5.4 + React 18 + TS 5.7 + Tailwind v4, port 4343, dependencies trimmed/added per PRP 3 §M1 (drop pixi/router; add partysocket, zod, immer, zustand, framer-motion, Radix, tailwind-merge, clsx, and @cardshed/core via file:../core). Boot screen smoke-imports createDeck() to prove the workspace link works.
  • M2 — STORYBOARD + DESIGN SYSTEM. docs/STORYBOARD.md covers premise, three-player user journey, screen inventory, engine contract, and ASCII wireframes for all 10 MVP screens. .stitch/DESIGN.md regenerated as DS-1 from a single canonical Stitch run (S03 Table) — Stitch project `projects/4083518914509964664` — anchored to the warm-session silent-drop invariant. Per-screen mockups are deferred to M3+ where each milestone owns its own Stitch session.

Acceptance gates (PRP 3 §M1 + §M2)

  • `cd @lab/ll-CARDSHED/apps/ui && npm install && npm run dev` serves on :4343
  • `npm run build` → `tsc -b && vite build` green (143.68 kB JS bundle)
  • `npm run lint` → `eslint --max-warnings 0` green
  • `Skill: agent-browser` captured boot-screen at 1440×900 under `dogfood-output/20260521T193040Z/m1-boot/`
  • `docs/STORYBOARD.md` §5 has wireframes for all 10 MVP screens
  • `.stitch/DESIGN.md` regenerated as DS-1 with full token blocks (color, typography, spacing, radius, elevation, motion, components) + Tailwind v4 `@theme` drop-in
  • Stitch run T1 — Working-tree triage & atomic baseline #1 logged in `docs/DECISIONS/2026-05-21-stitch-run-1.md` (project ID, screen ID, prompt summary, token deltas)

Evidence

  • Boot screen: `@lab/ll-CARDSHED/dogfood-output/20260521T193040Z/m1-boot/boot-screen-1440x900.png` — heading + `deck: 52 cards` (smoke-proves `@cardshed/core` link) + zero console errors.
  • Stitch source-of-truth: `@lab/ll-CARDSHED/.stitch/designs/S03-table.{html,png}` — the canonical S03 Table mockup that anchors DS-1.
  • Design system: `@lab/ll-CARDSHED/.stitch/DESIGN.md` — DS-1 with §10 provenance row.
  • Storyboard: `@lab/ll-CARDSHED/docs/STORYBOARD.md` — §1 premise, §2 journey, §3 inventory, §4 engine map, §5 wireframes S01–S10, §6 out-of-scope, §7 provenance log.

Why one Stitch screen for the whole design system

Project memory invariant: "Stitch warm-session silent-drop" — first `generate_screen_from_text` per Claude Code session succeeds; calls #2+ time out at ~2 min and never appear in `list_screens`. Restart-only unblock. To produce DS-1 in one session, the call was made against S03 Table (the canonical in-match screen) since it exercises the full visual vocabulary: opponent chips, state chips, recessed felt panel, card states (idle/selected/legal/illegal/ringed-target), action pills, helper text, brand-mark, header icon buttons. Per-screen mockups land at M3+ where each Stitch run gets its own clean session. See `docs/DECISIONS/2026-05-21-stitch-run-1.md` for the full rationale + token deltas.

What is NOT in this PR

  • No per-screen mockups for S01/S02/S04–S10 — those are M3+ deliverables, intentionally scoped out.
  • No matchStore, no LocalDispatcher — those land at M4 (PlayerSetup) / M5 (Table render).
  • No actual game UI past the boot screen — the only on-screen UI is the placeholder boot screen with a smoke import. Per `.claude/rules/ui-design-pipeline.md`, hand-rolled screens are forbidden from M3 onward.
  • No mobile responsive sweep — owned by M13.

Test plan

  • `cd @lab/ll-CARDSHED/apps/ui && npm install && npm run build && npm run lint` — should all be green.
  • `npm run dev` then open http://localhost:4343 — boot screen reads "CARD SHED — MVP M1" and "deck: 52 cards".
  • Visual diff the boot screen against `dogfood-output/20260521T193040Z/m1-boot/boot-screen-1440x900.png`.
  • Skim `.stitch/DESIGN.md` §9 — confirm the `@theme` block can drop into a future `apps/ui/src/index.css` without edits.
  • Skim `docs/STORYBOARD.md` §5 — confirm every MVP screen has a wireframe (S01–S10).

Next (post-merge → M3)

Run `Skill: stitch-design` in a fresh session to produce `docs/SCREENS/main-menu.md` for S01 (M3). Each subsequent milestone owns one Stitch session per the warm-session-drop constraint.

Summary by CodeRabbit

Release Notes

  • New Features

    • Established comprehensive design system (DS-1) with visual theme, color palette, typography, and component vocabulary for the CARD SHED MVP.
    • Created initial UI application scaffold with boot screen displaying deck information.
    • Added table screen mockup demonstrating gameplay layout and pending attack panel.
  • Documentation

    • Published complete MVP storyboard documenting game screens, player journey, and engine contract requirements.
    • Added design system decision record and provenance tracking for DS-1.

Review Change Stack

M1 (SCAFFOLD apps/ui)
  - Mirror @lab/ll-RELIQUARY/apps/ui tree at @lab/ll-CARDSHED/apps/ui.
  - Vite 5.4 + React 18 + TS 5.7 + Tailwind v4; port 4343.
  - Deps per PRP 3 M1: add partysocket, zod, immer, zustand,
    framer-motion, Radix dialog/tabs/tooltip, tailwind-merge, clsx,
    @cardshed/core via file:../core; drop pixi.js + react-router-dom.
  - Boot screen calls createDeck() from @cardshed/core to smoke-prove
    the workspace link; renders "CARD SHED — MVP M1" + "deck: 52 cards".
  - tsconfig noEmit:true so tsc -b is type-check only; Vite owns emit.
  - Minimal flat ESLint config (--max-warnings 0 green).

M2 (STORYBOARD + DESIGN SYSTEM)
  - docs/STORYBOARD.md §1–§7: premise, three-player user journey,
    screen inventory (S01–S10 MVP subset), engine-contract mapping,
    full ASCII wireframes for every MVP screen, Stitch provenance log.
  - .stitch/DESIGN.md regenerated as DS-1 from a single canonical
    Stitch run (S03 Table) — full token blocks for color, typography,
    spacing, radius, elevation, motion, component vocabulary, plus a
    drop-in Tailwind v4 @theme block.
  - docs/DECISIONS/2026-05-21-stitch-run-1.md records why one screen
    anchored the system (warm-session silent-drop invariant), what
    Stitch chose, and the decision criteria for any future DS bump.
  - .stitch/designs/S03-table.{html,png} kept as the visual source-of-
    truth for DS-1.

Evidence
  - dogfood-output/20260521T193040Z/m1-boot/ — agent-browser screenshot
    at 1440×900 + report.md confirming clean console + working core link.
Copy link
Copy Markdown
Contributor

@sourcery-ai sourcery-ai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @w7-mgfcode, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 21, 2026

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Scaffolds the CARD SHED React/Vite UI application with design system integration. Includes complete MVP storyboard (9 screens with wireframes), design system document (DS-1) with tokenized palette/typography/geometry, reference table screen, Vite/TypeScript/ESLint configuration, React bootstrap, and Tailwind theme synchronization; M1 boot acceptance report confirms build and boot screen rendering.

Changes

CARD SHED MVP Storyboard, Design System, and UI App

Layer / File(s) Summary
MVP Storyboard and User Journey
docs/STORYBOARD.md
Complete user journey flow (main menu → player setup → privacy handoff → table → attack/defense → results), screen inventory table (S01–S10), engine contract defining state sources and action routes, and ASCII wireframes for all nine MVP screens with parent states and modal/overlay behaviors.
Design System Definition and Decision Record
.stitch/DESIGN.md, docs/DECISIONS/2026-05-21-stitch-run-1.md
DS-1 design tokens for palette (surfaces, ink, accents, danger), typography (type scale, families, tracking), geometry (spacing, radii, card aspect ratio), elevation/shadows, motion (easing, durations, reduced-motion), and named component vocabulary (card, chips, buttons, dialogs); decision record documents Stitch run provenance, prompt structure used, token choices, open questions, and DS-1 invariants for future revisions.
Reference Table Screen
.stitch/designs/S03-table.html
S03-table.html reference screen with fixed header, pending-attack panel, hand area, fixed action bar, felt-noise atmosphere overlay, and inline requestAnimationFrame glow animation triggered on card hover targeting defender chip.
App Configuration and Tooling
apps/ui/package.json, apps/ui/tsconfig.json, apps/ui/vite.config.ts, apps/ui/eslint.config.js, apps/ui/.gitignore
Package identity (cardshed-ui), npm scripts (dev, build, preview, lint, test), runtime dependencies (Radix UI, React Query, framer-motion, Tailwind, zustand, zod, immer, partysocket), dev dependencies (ESLint, Vite, TypeScript, Vitest); TypeScript strict mode with JSX and Vite client types; Vite React+Tailwind plugins on port 4343; ESLint flat config with React Hooks and refresh rules; build/cache ignore patterns.
React App Entry Point and Boot Screen
apps/ui/index.html, apps/ui/src/main.tsx, apps/ui/src/App.tsx
HTML5 document with root container, React/ReactDOM bootstrap via StrictMode rendering App into root element, and App.tsx component rendering "CARD SHED — MVP M1" boot screen with deck size computed from @cardshed/core and links to STORYBOARD and stitch-design.
Global Styling and Design Token Sync
apps/ui/src/index.css
Tailwind CSS import, @theme block defining core color tokens (surface, surface-raised, ink, ink-muted, accent) mirrored from DESIGN.md, and global styles for full-height html/body/root and body font/smoothing/colors.
M1 Boot Acceptance Report
dogfood-output/20260521T193040Z/m1-boot/report.md
Milestone acceptance gates: successful build/install/lint/dev-server startup, boot screen captured rendering "CARD SHED — MVP M1", zero console errors, smoke test of @cardshed/core linkage (deck: 52 cards), accessibility snapshot (h1 in main landmark), deferred verification items, and next-step reference to M2 storyboard/design work.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

  • #146 — This PR directly implements the M1–M2 subtasks ("scaffold apps/ui + design system") of the epic's overall CARD SHED experience scope.
  • #148 — This PR is the feature branch work for the linked issue covering M1 scaffold and M2 storyboard + design system; all acceptance criteria are addressed.
  • #154 — The table screen design and Tailwind theme tokens (animation, accessibility, responsive guidance) defined here are reference material for subsequent screen implementations and overlay behaviors.

Poem

🐰 A design system springs to life,

With tokens, colors, typefaces bright;

The table screen shows all the while—

Now bootstrap shines with React's style! ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes the main changeset: scaffolding apps/ui and introducing a design system covering M1 and M2 milestones.
Linked Issues check ✅ Passed The PR meets all M1 and M2 objectives: apps/ui scaffold with correct dependencies and boot screen [#148], storyboard with wireframes [#148], and regenerated design system with Stitch provenance [#148].
Out of Scope Changes check ✅ Passed All changes are directly aligned with M1 and M2 scope; no out-of-scope additions detected beyond the documented objectives.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/cardshed-ui-scaffold

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@socket-security
Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addednpm/​immer@​10.2.0991008394100
Addednpm/​globals@​15.15.01001008593100
Addednpm/​eslint-plugin-react-refresh@​0.4.2610010010085100
Addednpm/​partysocket@​1.1.1910010010093100
Addednpm/​eslint-plugin-react-hooks@​5.2.09810010095100
Addednpm/​zod@​3.25.769810010095100

View full report

@w7-mgfcode w7-mgfcode merged commit 66fc1df into master May 21, 2026
13 of 14 checks passed
@w7-mgfcode w7-mgfcode deleted the feat/cardshed-ui-scaffold branch May 21, 2026 19:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(cardshed): scaffold apps/ui + design system (M1+M2)

1 participant