<!-- SPDX-FileCopyrightText: 2026 FocusFlow contributors -->
<!-- SPDX-License-Identifier: AGPL-3.0-only -->

# UI Plan 2 Block 04 — Board Columns and Task Cards

**Goal:** Render the four finalized Backlog board columns and task cards from Backlog board read models.

---

## Block outcome

After this block, the default Backlog board displays all four columns, counts, visible tasks, card metadata, child previews, and add-task footers.

---

## Chunk 4.1 — Add board visual tokens

### Tasks

Add or extend Flutter visual tokens for Backlog-specific accents:

- Do Next green.
- Need Time Block orange/yellow.
- Break Up First purple.
- Not Now blue.
- High priority red flag.
- Medium priority yellow/orange flag.
- Low priority green flag.
- Project dot colors matching seed projects.
- Tag chip colors for drawer later.

Prefer central token/mapping files over inline colors.

### Acceptance criteria

- Colors are centralized.
- Existing Today color mappings remain unchanged.
- No one-off hardcoded color scatter in card widgets.

---

## Chunk 4.2 — Build column header widget

### Tasks

Create a reusable `BacklogBoardColumn` and `BacklogColumnHeader`.

Header content:

- bucket icon,
- bucket title,
- count pill,
- add icon button on the far right,
- subtitle line.

Icon suggestions:

- Do Next: check circle.
- Need Time Block: clock.
- Break Up First: target/radio button/segmented circle.
- Not Now: cloud outline.

### Acceptance criteria

- Header count is read from `BacklogBoardColumnReadModel.count`.
- Header add icon calls the same create-task flow as the footer with bucket preselection if available.
- Header does not compute bucket counts in Flutter.

---

## Chunk 4.3 — Build board layout

### Tasks

1. Render columns in stable order:
   - Do Next
   - Need Time Block
   - Break Up First
   - Not Now
2. Use horizontal layout at desktop width.
3. Make board horizontally scrollable if width becomes constrained.
4. Make column card stacks vertically scrollable or allow the whole board body to scroll, whichever best matches current app ergonomics.
5. Keep the summary panel fixed on the right in default state.

Sizing guidance at 1672 px mockup width:

- board starts after left content gutter,
- 4 columns fit before summary panel,
- column width around 270–300 px,
- column gap around 8–12 px,
- column border/fill tinted by bucket accent.

### Acceptance criteria

- Four columns are visible at mockup-like desktop width.
- Board can be used at narrower desktop widths without overflow exceptions.
- Summary panel does not overlap default board state.

---

## Chunk 4.4 — Build backlog task card widget

### Tasks

Create `BacklogTaskCard` with:

- leading checkbox/selection square,
- title,
- subtitle/notes preview,
- metadata row:
  - duration icon and minutes,
  - project color dot/name,
  - priority flag/label,
- footer:
  - difficulty label and five bars,
  - reward label and solid reward icons.

Use existing `DifficultyBars` and reward icon widgets where possible. If existing widgets are Today-specific, extract reusable versions without breaking Today.

Difficulty requirements:

- exactly five bars,
- `veryEasy` = 1 filled,
- `easy` = 2 filled,
- `medium` = 3 filled,
- `hard` = 4 filled,
- `veryHard` = 5 filled,
- unfilled bars are outline/subtle.

Reward requirements:

- display 1–5 solid sparkle/bolt-style marks matching the mockup language,
- no line-only star outlines.

### Acceptance criteria

- Card content is read from `BacklogBoardItemReadModel`.
- Card supports selected state with magenta outline.
- Card click selects task and opens drawer in Block 7.
- Card does not mutate task status by itself.

---

## Chunk 4.5 — Build child preview card section

### Tasks

For tasks with child previews, render nested child rows inside the parent card, as shown under:

- `Plan next week`
- `Complete online course`

Child row content:

- checkbox-like icon,
- child title,
- optional duration at right.

Interaction for this block:

- Child rows may be non-interactive or select the parent unless a public child-detail model already exists.
- Do not implement child completion from the Backlog board unless command wiring is explicitly available and tested.

### Acceptance criteria

- Parent card remains visually coherent with child preview rows.
- Child previews come from read model, not title parsing.
- No scheduling/child completion rules are duplicated in Flutter.

---

## Chunk 4.6 — Add column footer Add Task buttons

### Tasks

Footer content:

- `+ Add task`, colored by bucket accent.

Behavior for this block:

- Calls a callback with intended bucket.
- Actual create drawer/command wiring happens in Block 8.

### Acceptance criteria

- Footer is visible in every column.
- Footer does not throw when pressed before Block 8 wiring; it can open a placeholder or no-op with a TODO callback in tests.

---

## Chunk 4.7 — Tune board visuals against default mockup

### Tasks

Tune:

- background fills,
- border opacities,
- column corner radius,
- card height,
- card vertical spacing,
- title and metadata font sizes,
- count pill styling,
- icon sizes,
- card selected/hover states.

### Acceptance criteria

- Default board content closely matches `mockups/backlog_board_default.png`.
- Visible mockup tasks are present in the expected columns.
- No white surfaces or accidental Material default cards.

BREAKPOINT: Stop here for visual review if card density or column spacing is substantially off.

---

## Block acceptance criteria

- Backlog board renders from read models.
- All four columns, counts, visible task cards, child previews, difficulty bars, reward icons, and add footers are present.
- Board layout is responsive enough for desktop width changes.
- No domain mutations happen from basic card rendering.

## Validation after block

```sh
cd apps/focus_flow_flutter
flutter analyze
flutter test
```
