beadboard/docs/plans/2026-02-12-kanban-design-foundation.md

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.