From 89876b18621012621314e78e9eda311b5d802d45 Mon Sep 17 00:00:00 2001
From: zenchantlive <jordanlive121@gmail.com>
Date: Wed, 11 Feb 2026 21:27:01 -0800
Subject: [PATCH] Preserve recovered design-plan doc and ignore local beads
 lock artifact

---
 .gitignore                                    |   3 +
 .../2026-02-12-kanban-design-foundation.md    | 134 ++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 docs/plans/2026-02-12-kanban-design-foundation.md

diff --git a/.gitignore b/.gitignore
index 596f42a..ee7bef2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,3 +6,6 @@ worktrees/
 
 # bv (beads viewer) local config and caches
 .bv/
+
+# beads lock artifact
+.beads/.bv.lock
diff --git a/docs/plans/2026-02-12-kanban-design-foundation.md b/docs/plans/2026-02-12-kanban-design-foundation.md
new file mode 100644
index 0000000..0e304f8
--- /dev/null
+++ b/docs/plans/2026-02-12-kanban-design-foundation.md
@@ -0,0 +1,134 @@
+# BeadBoard Kanban Design System Plan
+
+**Goal**
+Ship a production-ready baseline visual system for Tracer Bullet 1 (Kanban) before further feature expansion.
+
+**Primary decision**
+Use **Tailwind CSS v4 + CSS tokens (`@theme`) + Framer Motion**.
+
+## 1. Why This Stack
+
+### Tailwind v4 is the right baseline
+- Fastest path to a coherent, reusable system in Next.js 15.
+- CSS-first token model (`@theme`) fits our need for semantic design tokens.
+- Lets us avoid scattered inline styles and ad-hoc CSS files.
+
+### Framer Motion should be scoped
+- Use for state transitions (card changes, panel enter/exit, filtered results).
+- Avoid decorative over-animation that hurts readability in a dense dashboard.
+
+### Risks and mitigations
+- Risk: “generic Tailwind look”
+  - Mitigation: strict token palette + component contracts + typography rules.
+- Risk: visual inconsistency
+  - Mitigation: no direct color literals in component markup except token definitions.
+
+## 2. Baseline-First Sequencing
+
+This should happen **now**, not later.
+
+1. Foundation (tokens, layout, core components)
+2. Motion and interaction polish
+3. Accessibility and responsive hardening
+4. Continue other tracer bullets
+
+## 3. Visual Language (v1)
+
+### Product feel
+- High-signal operations UI.
+- Calm neutral surfaces with sharp status accents.
+- Dense information without visual clutter.
+
+### Typography
+- Primary UI: `DM Sans` (or `Inter` fallback decision at implementation time)
+- Metadata/IDs: `JetBrains Mono`
+
+### Color model
+- Semantic tokens only:
+  - `background`, `foreground`, `surface`, `muted`
+  - `status-open`, `status-in-progress`, `status-blocked`, `status-deferred`, `status-closed`
+  - `priority-p0` ... `priority-p4`
+- Contrast target: at least WCAG AA for normal text.
+
+## 4. Component Contract
+
+Required first-class components:
+- `KanbanPageShell`
+- `KanbanControls`
+- `KanbanBoard`
+- `KanbanColumn`
+- `KanbanCard`
+- `KanbanDetailPanel`
+- shared: `Badge`, `Chip`, `StatPill`
+
+Rules:
+- Component variants defined via class composition (CVA optional but preferred).
+- No inline style objects for production components.
+- All spacing/radius/shadow/color come from tokens/utilities.
+
+## 5. Layout Contract
+
+### Desktop
+- Sticky top header with filters + stats.
+- Main grid: board + detail panel.
+- Columns scroll horizontally as needed.
+
+### Mobile
+- Stacked controls.
+- Board in horizontal swipe/scroll mode.
+- Detail panel becomes full-screen drawer.
+
+## 6. Motion Contract (Framer Motion)
+
+Use motion for:
+- Card appear/disappear on filtering.
+- Detail panel slide-in/out.
+- Subtle status count transitions.
+
+Do not animate:
+- Global page container on every render.
+- Constant hover effects that reduce legibility/performance.
+
+## 7. Tailwind v4 Implementation Plan
+
+### Phase A: Design System Foundation (P0)
+- Add Tailwind v4 pipeline with `@import "tailwindcss"` in global stylesheet.
+- Define `@theme` token set (colors, radius, spacing aliases, shadows, motion tokens).
+- Add base layer typography/background defaults.
+- Replace inline styles in tracer-1 components with tokenized Tailwind classes.
+
+Acceptance criteria:
+- No inline style usage in `src/components/kanban/*` and shared primitives (except truly dynamic edge cases).
+- UI at `localhost:3000` has coherent baseline styling.
+
+### Phase B: Motion + Interaction Polish (P1)
+- Integrate Framer Motion transitions for board and panel.
+- Improve visual hierarchy of card metadata.
+- Add polished empty/loading/error states.
+
+Acceptance criteria:
+- Motion communicates state changes without jitter.
+- Filtering and detail interactions feel intentional.
+
+### Phase C: Accessibility + Responsive Hardening (P1)
+- Keyboard focus and traversal for cards/panel.
+- Verify color contrast and focus visibility.
+- Tune mobile breakpoints and touch targets.
+
+Acceptance criteria:
+- Keyboard-only flow works for core Kanban actions.
+- Mobile experience is usable and visually consistent.
+
+## 8. Technical Boundaries
+
+- Read path remains `.beads/issues.jsonl` / `.beads/issues.jsonl.new`.
+- No direct write path to JSONL.
+- Styling changes must not alter read/write boundary behavior.
+
+## 9. Definition of Done (Tracer-1 Design Baseline)
+
+- Tailwind v4 configured and used as primary styling framework.
+- Tokenized design system applied across tracer-1 Kanban components.
+- Framer Motion integrated for key transitions.
+- Tests/typecheck pass, app runs on `localhost:3000`.
+- Visual result is clearly beyond prototype/demo quality.