focus-flow/Codex Documentation/Archived plans/V1_BLOCK_18_UI_Foundation_Design_Spike.md

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:

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