# V1 Block 18 — UI Foundation and Design Spike

Status: Planned, blocked until Chunk 17.4 passes

Purpose: Start a minimal Flutter UI foundation against the completed application
facade without finalizing the visual design or re-implementing backend rules in
widgets.

## Chunk 18.1 — Flutter workspace and dependency boundary

Recommended Codex level: high

Tasks:

- Add a Flutter application/workspace structure while preserving the pure Dart
  scheduling core as an independently testable package/module.
- Select and document the smallest state-management/navigation approach needed
  for the V1 screens; avoid framework churn and speculative architecture.
- Define dependency injection/composition for the in-memory application facade
  first and the selected trusted runtime boundary second.
- Ensure Flutter does not import MongoDB adapter/client types or receive database
  credentials.
- Add app startup, theme/token placeholders, localization scaffold, and test
  harness.
- Add compile/analyze/widget-test commands without moving domain behavior into
  the UI.

Rules:

- The visual design is provisional.
- Do not redesign the backend during UI setup; file a targeted backend defect if
  a contract is genuinely insufficient.
- Do not add drag-and-drop, week/month views, reports, shield, or history UI.
- Keep the core runnable/testable without Flutter.
- Prefer reversible structural choices.

Acceptance criteria:

- Flutter starts with the in-memory composition root.
- Core tests still run independently.
- UI code depends on application/read DTOs, not repositories or scheduler
  internals.
- No MongoDB secret/client enters the Flutter bundle.
- Flutter analyze and starter widget tests pass.

BREAKPOINT: Stop here. Confirm `medium` mode before adding provisional navigation
and component contracts.

## Chunk 18.2 — Provisional V1 navigation and screen-state skeleton

Recommended Codex level: medium

Tasks:

- Add placeholder routes/shells for Today, Backlog, Quick Capture, and basic
  project/locked/settings management.
- Bind screens to application queries/commands through state controllers.
- Implement loading, empty, typed error, conflict, and retry states.
- Keep Today full/compact mode and locked reveal as state transitions using the
  backend read model.
- Add calm placeholder copy mapped from structured backend codes.
- Add navigation/state tests without committing to final card layout.

Rules:

- Do not duplicate scheduling logic in controllers.
- Do not use raw English backend debug messages as the only UI contract.
- Keep locked overlays hidden by default.
- Avoid broad animation/branding work.
- Every state must remain usable with keyboard/screen-reader navigation later.

Acceptance criteria:

- All provisional screens can load from the in-memory facade.
- Typed backend errors have explicit UI states.
- Compact/reveal toggles use backend/read-state contracts.
- Navigation tests pass.
- No final visual-design claim is made.

## Chunk 18.3 — UI component contracts and accessibility test harness

Recommended Codex level: medium

Tasks:

- Create provisional reusable component interfaces for timeline task card,
  locked overlay, Free Slot, compact current/next panels, backlog row, quick
  capture form, and one-tap action menu.
- Map project color, task-type background, reward icon, and difficulty icon from
  backend tokens.
- Add semantic labels, focus order, text scaling, minimum tap-target, and contrast
  test hooks.
- Keep components token-driven so final visual design can change without changing
  backend/read models.
- Add golden tests only for structural regressions that are safe before design
  finalization; avoid freezing colors/spacing prematurely.
- Add widget tests for hidden locked state and action availability by task type.

Rules:

- Accessibility semantics are not deferred just because visual design is open.
- Do not hard-code project/task-type policy in widgets.
- Avoid shame/red-alert visual language.
- Do not implement V2 components.
- Keep placeholder styling intentionally neutral and easy to replace.

Acceptance criteria:

- Each V1 read-model category has a provisional component contract.
- Token mappings are centralized.
- Structural/accessibility widget tests pass.
- Hidden locked time stays hidden unless explicitly revealed.
- Components can be restyled without backend changes.

BREAKPOINT: Stop here. Confirm `high` mode before building the first vertical UI
slice.

## Chunk 18.4 — One vertical smoke slice and design handoff

Recommended Codex level: high

Tasks:

- Implement one end-to-end provisional flow:
  - quick capture a title-only task
  - view it in Backlog
  - schedule it into the next available slot after supplying duration
  - view it in Today
  - mark it done
  - verify refreshed persisted/read state
- Run the flow against in-memory wiring and the selected development runtime
  boundary where safe/configured.
- Add widget/integration tests for the vertical slice and typed failure states.
- Record UI contract questions that require actual design decisions, including
  spacing, typography, color palette, motion, density, and responsive targets.
- Produce a design-handoff checklist rather than expanding every screen with
  placeholder visuals.
- Stop before broad UI implementation.

Rules:

- Do not bypass public application use cases for the demo flow.
- Do not embed database credentials.
- Do not treat placeholder visuals as approved design.
- Do not expand scope into V2.
- Backend defects found here must receive focused regression tests before fixes.

Acceptance criteria:

- The vertical flow succeeds through public UI/application contracts.
- Failure/conflict states are testable.
- No scheduling rules are implemented in widgets.
- A concrete design-decision checklist exists.
- The project stops at a stable foundation awaiting UI design direction.

Commit suggestion:

```text
feat(ui): add provisional flutter foundation and v1 smoke slice
```