134 lines
4.5 KiB
Markdown
134 lines
4.5 KiB
Markdown
# 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.
|