iPadOS MVP UI plan

docs/ipados-mvp/README.md

@@ -0,0 +1,40 @@
+# Tablet-First + iPadOS Native Planning Pack
+
+This directory contains the planning artifacts for a phased program:
+
+1. **Phase 1 (first):** Improve the existing web editor for tablet usability.
+2. **Phase 2 (next):** Build the iPadOS native port using Phase 1 validation results.
+
+## Purpose
+
+Reduce native-port risk by first validating tablet-friendly layout, interaction, and information architecture in the existing web app while adhering to general HIG principles (clarity, deference, depth, touch ergonomics, and platform-consistent behaviors).
+
+## Artifacts
+
+- `product-scope.md` — phased goals, non-goals, and release criteria
+- `backlog.md` — epics and user stories (tablet-web first, native second)
+- `sprint-plan.md` — suggested phased execution plan
+- `ui-parity-matrix.md` — source UI surface to tablet-web and native mappings
+- `hig-checklist.md` — HIG compliance checklist used for design and QA gates
+- `raid-log.md` — risks, assumptions, issues, and dependencies
+- `backlog.csv` — import-friendly backlog format
+- `phase1-agent-charter.md` — scope guardrails for implementation agents
+- `phase1-implementation-runbook.md` — recommended code-area execution sequence
+- `phase1-acceptance-gates.md` — story-level and phase-level QA gate checklist
+- `phase1-agent-status-template.md` — daily status and handoff templates
+
+## How to use this pack
+
+1. Review `product-scope.md` and lock **Phase 1** scope first.
+2. Import `backlog.csv` (or copy from `backlog.md`) into your issue tracker.
+3. Execute all `TWEB-*` stories before starting `IPAD-*` implementation stories.
+4. During implementation, update:
+   - `ui-parity-matrix.md` for parity status
+   - `hig-checklist.md` for compliance evidence
+   - `raid-log.md` as new delivery risks appear
+
+## Suggested governance cadence
+
+- Weekly triad review: Product + Design + Web/iPad Engineering leads
+- Twice-weekly backlog grooming
+- End-of-sprint HIG-principles audit checkpoint before demo sign-off

docs/ipados-mvp/backlog.csv

@@ -0,0 +1,28 @@
+id,type,phase,epic,summary,priority,story_points,depends_on,sprint_target,acceptance_criteria
+TWEB-001,Story,Phase 1,TWEB-EPIC-1,Build tablet-focused UI inventory from current web editor,P0,3,,TW1,"Inventory covers all major surfaces and documents tablet pain points per surface."
+TWEB-002,Story,Phase 1,TWEB-EPIC-1,Define tablet breakpoints and adaptive behavior contract,P0,5,TWEB-001,TW1,"Landscape/portrait breakpoint behavior is specified and approved."
+TWEB-003,Story,Phase 1,TWEB-EPIC-1,Publish HIG-principles interpretation for web-tablet context,P0,3,TWEB-001,TW1,"Design principles are documented with explicit tablet-web guidance."
+TWEB-010,Story,Phase 1,TWEB-EPIC-2,Implement tablet-responsive workspace shell in web app,P0,8,TWEB-002,TW1-TW2,"Workspace adapts for tablet portrait/landscape and keeps canvas dominant."
+TWEB-011,Story,Phase 1,TWEB-EPIC-2,Tablet-optimize panel system (Properties/Layers/Data),P0,8,TWEB-010,TW2,"Panels remain touch-usable and non-blocking to core canvas workflow."
+TWEB-012,Story,Phase 1,TWEB-EPIC-2,Tablet-optimize document control bar and tool shelf,P0,8,TWEB-010,TW2,"Tool controls and viewport controls are reachable and legible on tablet."
+TWEB-013,Story,Phase 1,TWEB-EPIC-2,Replace persistent desktop status bar usage with contextual hints,P1,3,TWEB-010,TW3,"Hint model is contextual and unobtrusive on compact tablet layouts."
+TWEB-020,Story,Phase 1,TWEB-EPIC-3,Define tablet web input contract (touch/pencil/pointer/keyboard),P0,3,TWEB-002,TW2,"Input priority and gesture behavior rules are documented and testable."
+TWEB-021,Story,Phase 1,TWEB-EPIC-3,Improve viewport touch gestures (pan/zoom/rotate policy),P0,8,TWEB-020|TWEB-012,TW2,"Pan/zoom are stable and do not interfere with core controls."
+TWEB-022,Story,Phase 1,TWEB-EPIC-3,Improve Apple Pencil behavior in web workflow,P1,5,TWEB-020|TWEB-012,TW3,"Pencil behavior is intentional and browser limitations are documented."
+TWEB-023,Story,Phase 1,TWEB-EPIC-3,Improve pointer/trackpad affordances on tablet web,P1,5,TWEB-020|TWEB-011,TW3,"Hover/target feedback improves pointer UX without regressing touch."
+TWEB-030,Story,Phase 1,TWEB-EPIC-4,Rework command access model for tablet web,P0,8,TWEB-003|TWEB-012,TW3,"High-frequency commands are discoverable without desktop menu dependency."
+TWEB-031,Story,Phase 1,TWEB-EPIC-4,Tablet-optimize dialogs/popovers,P0,5,TWEB-010,TW2-TW3,"Dialogs/popovers are tablet-safe with consistent cancel/confirm behavior."
+TWEB-032,Story,Phase 1,TWEB-EPIC-4,Add context-aware action menus for layer/document operations,P1,5,TWEB-011|TWEB-030,TW3,"Context actions are available via long-press/secondary click."
+TWEB-040,Story,Phase 1,TWEB-EPIC-5,Run HIG-principles audit on tablet web implementation,P0,3,TWEB-010|TWEB-011|TWEB-012|TWEB-030,TW3-Gate,"Checklist completed and high-severity issues resolved or tracked."
+TWEB-041,Story,Phase 1,TWEB-EPIC-5,Accessibility baseline pass for tablet web core flows,P0,5,TWEB-010|TWEB-011,TW3-Gate,"Core controls meet touch-size, labeling, and contrast baseline."
+TWEB-042,Story,Phase 1,TWEB-EPIC-5,Conduct tablet usability sessions (5 to 8 users),P0,5,TWEB-040,Gate Week,"Task-based findings are logged and blockers resolved or accepted."
+TWEB-043,Story,Phase 1,TWEB-EPIC-5,Produce native handoff package from validated web patterns,P0,3,TWEB-042,Gate Week,"Validated IA and interaction decisions are documented for native build."
+TWEB-099,Story,Phase 1,TWEB-EPIC-5,Phase 1 gate sign-off,P0,2,TWEB-041|TWEB-042|TWEB-043,Gate Week,"All Phase 1 gates pass and native implementation stories are unblocked."
+IPAD-001,Story,Phase 2,IPAD-EPIC-1,Translate validated tablet IA into native navigation model,P0,5,TWEB-099,IP1,"Native IA reuses validated Phase 1 patterns and documents adaptations."
+IPAD-002,Story,Phase 2,IPAD-EPIC-1,Build native app shell and scene baseline,P0,8,IPAD-001,IP1,"Native shell and scene baseline are functional with no navigation dead-ends."
+IPAD-003,Story,Phase 2,IPAD-EPIC-1,Establish native modal/popup infrastructure,P0,5,IPAD-002,IP1,"Native sheets/popovers/confirmations are consistent and test-covered."
+IPAD-010,Story,Phase 2,IPAD-EPIC-2,Implement native workspace and inspector surfaces,P0,8,IPAD-002,IP2,"Adaptive native canvas+inspector surfaces match validated UX intent."
+IPAD-011,Story,Phase 2,IPAD-EPIC-2,Implement native command model and shortcuts,P0,8,IPAD-002,IP2,"Native commands are discoverable with MVP shortcut parity."
+IPAD-012,Story,Phase 2,IPAD-EPIC-2,Implement native input behaviors (touch/pencil/pointer),P0,8,IPAD-010,IP3,"Native interaction model is stable and follows input contract."
+IPAD-020,Story,Phase 2,IPAD-EPIC-3,Run native HIG and accessibility compliance pass,P0,5,IPAD-010|IPAD-011|IPAD-012,IP4,"No unresolved high-severity HIG issues and accessibility baseline passes."
+IPAD-021,Story,Phase 2,IPAD-EPIC-3,Native usability validation and release readiness,P0,5,IPAD-020,IP4,"Core flows validated and release readiness sign-off recorded."

docs/ipados-mvp/backlog.md

@@ -0,0 +1,314 @@
+# Tablet-Web First + Native iPad Backlog
+
+This backlog is intentionally sequenced:
+
+1. **Phase 1:** Tablet usability improvements in the existing web app.
+2. **Phase 2:** Native iPad implementation after Phase 1 gate.
+
+## Epic summary
+
+| Epic ID | Phase | Epic | Goal |
+|---|---|---|---|
+| TWEB-EPIC-1 | Phase 1 | Tablet UX Inventory & Principles | Baseline current UI, define tablet constraints, and align to HIG-inspired principles |
+| TWEB-EPIC-2 | Phase 1 | Responsive Workspace & Panels | Make workspace, panel layout, and controls tablet-usable in web |
+| TWEB-EPIC-3 | Phase 1 | Tablet Input & Interaction (Web) | Improve touch/pencil/pointer/keyboard behavior in browser context |
+| TWEB-EPIC-4 | Phase 1 | Tablet Commanding & Dialog UX (Web) | Improve command discoverability, menus, and dialogs for tablet users |
+| TWEB-EPIC-5 | Phase 1 | Validation & Native Handoff | Complete HIG-principles audit, usability testing, and native handoff package |
+| IPAD-EPIC-1 | Phase 2 | Native Foundation & IA Reuse | Stand up native shell reusing validated tablet-web IA patterns |
+| IPAD-EPIC-2 | Phase 2 | Native Surface Implementation | Implement prioritized native surfaces and interactions |
+| IPAD-EPIC-3 | Phase 2 | Native Quality & Readiness | Complete native HIG/accessibility/usability gates |
+
+---
+
+## Phase gating rule
+
+All `IPAD-*` implementation stories are blocked until `TWEB-099` is complete (Phase 1 gate passed).
+
+---
+
+## Stories
+
+### Phase 1 — TWEB stories
+
+### EPIC: TWEB-EPIC-1 — Tablet UX Inventory & Principles
+
+#### TWEB-001 — Build tablet-focused UI inventory from current web editor
+- Priority: P0
+- Estimate: 3 SP
+- Depends on: None
+- Acceptance Criteria:
+  - Inventory includes title/menu area, workspace, document controls, tool shelf, viewport, layers/properties/data panels, status hints, floating surfaces.
+  - For each surface, current tablet pain points are documented.
+  - Inventory is reviewed by product, design, and frontend lead.
+
+#### TWEB-002 — Define tablet breakpoints and adaptive behavior contract
+- Priority: P0
+- Estimate: 5 SP
+- Depends on: TWEB-001
+- Acceptance Criteria:
+  - Landscape and portrait tablet breakpoints are documented.
+  - Surface behavior for each breakpoint is defined (show/hide/collapse/reflow).
+  - Contract is referenced by implementation stories.
+
+#### TWEB-003 — Publish HIG-principles interpretation for web-tablet context
+- Priority: P0
+- Estimate: 3 SP
+- Depends on: TWEB-001
+- Acceptance Criteria:
+  - Defines how clarity/deference/depth and touch ergonomics apply in web.
+  - Includes explicit "do not emulate desktop-only chrome on tablet" guidance.
+  - Signed off by design and product.
+
+---
+
+### EPIC: TWEB-EPIC-2 — Responsive Workspace & Panels
+
+#### TWEB-010 — Implement tablet-responsive workspace shell in web app
+- Priority: P0
+- Estimate: 8 SP
+- Depends on: TWEB-002
+- Acceptance Criteria:
+  - Workspace layout adapts to tablet portrait and landscape.
+  - Primary canvas region remains visually dominant.
+  - No critical controls are unreachable at common tablet widths.
+
+#### TWEB-011 — Tablet-optimize panel system (Properties/Layers/Data)
+- Priority: P0
+- Estimate: 8 SP
+- Depends on: TWEB-010
+- Acceptance Criteria:
+  - Panels can be shown/hidden/paged without blocking canvas use.
+  - Layers and Properties stay usable with touch targets and scrolling.
+  - Data panel remains accessible as secondary/debug surface.
+
+#### TWEB-012 — Tablet-optimize document control bar and tool shelf
+- Priority: P0
+- Estimate: 8 SP
+- Depends on: TWEB-010
+- Acceptance Criteria:
+  - Tool controls and viewport controls are reachable on tablet.
+  - Tool shelf supports reduced-width presentation without breaking workflows.
+  - Working colors UI remains accessible and readable.
+
+#### TWEB-013 — Replace persistent desktop status bar usage with contextual hints
+- Priority: P1
+- Estimate: 3 SP
+- Depends on: TWEB-010
+- Acceptance Criteria:
+  - Hints are contextual and unobtrusive on tablet.
+  - Compact layouts avoid permanent low-value chrome.
+  - Updated copy reviewed by design.
+
+---
+
+### EPIC: TWEB-EPIC-3 — Tablet Input & Interaction (Web)
+
+#### TWEB-020 — Define tablet web input contract (touch/pencil/pointer/keyboard)
+- Priority: P0
+- Estimate: 3 SP
+- Depends on: TWEB-002
+- Acceptance Criteria:
+  - Input priority and conflict rules are documented.
+  - Gesture glossary covers pan/zoom/select/context actions.
+  - Contract is testable via QA checklist.
+
+#### TWEB-021 — Improve viewport touch gestures (pan/zoom/rotate policy)
+- Priority: P0
+- Estimate: 8 SP
+- Depends on: TWEB-020, TWEB-012
+- Acceptance Criteria:
+  - Pan and zoom are stable and discoverable.
+  - Rotation behavior is explicit and documented.
+  - Gestures do not interfere with critical controls.
+
+#### TWEB-022 — Improve Apple Pencil behavior in web workflow
+- Priority: P1
+- Estimate: 5 SP
+- Depends on: TWEB-020, TWEB-012
+- Acceptance Criteria:
+  - Pencil actions are intentional and distinct where possible.
+  - Pencil-first editing flow is documented.
+  - Known browser limitations are recorded.
+
+#### TWEB-023 — Improve pointer/trackpad affordances on tablet web
+- Priority: P1
+- Estimate: 5 SP
+- Depends on: TWEB-020, TWEB-011
+- Acceptance Criteria:
+  - Hover/target feedback appears for key interactive controls.
+  - Pointer interactions do not regress touch usability.
+  - Context affordances are discoverable.
+
+---
+
+### EPIC: TWEB-EPIC-4 — Tablet Commanding & Dialog UX (Web)
+
+#### TWEB-030 — Rework command access model for tablet web
+- Priority: P0
+- Estimate: 8 SP
+- Depends on: TWEB-003, TWEB-012
+- Acceptance Criteria:
+  - High-frequency commands are accessible without desktop-style menu dependence.
+  - Action grouping is clear and consistent.
+  - Keyboard shortcuts remain available where appropriate.
+
+#### TWEB-031 — Tablet-optimize dialogs/popovers (new/open/export/preferences/about)
+- Priority: P0
+- Estimate: 5 SP
+- Depends on: TWEB-010
+- Acceptance Criteria:
+  - Dialogs and popovers render correctly at tablet breakpoints.
+  - Confirmation/cancel behavior is consistent and reversible.
+  - Form controls remain touch-friendly.
+
+#### TWEB-032 — Add context-aware action menus for layer/document operations
+- Priority: P1
+- Estimate: 5 SP
+- Depends on: TWEB-011, TWEB-030
+- Acceptance Criteria:
+  - Long-press/secondary click reveals context actions.
+  - Menu content varies by selection context.
+  - No conflict with primary edit gestures.
+
+---
+
+### EPIC: TWEB-EPIC-5 — Validation & Native Handoff
+
+#### TWEB-040 — Run HIG-principles audit on tablet web implementation
+- Priority: P0
+- Estimate: 3 SP
+- Depends on: TWEB-010, TWEB-011, TWEB-012, TWEB-030
+- Acceptance Criteria:
+  - Checklist completed with severity tags.
+  - High severity issues converted to stories or resolved.
+  - Audit evidence linked in `hig-checklist.md`.
+
+#### TWEB-041 — Accessibility baseline pass for tablet web core flows
+- Priority: P0
+- Estimate: 5 SP
+- Depends on: TWEB-010, TWEB-011
+- Acceptance Criteria:
+  - Core controls meet target-size baseline.
+  - Primary controls have appropriate labels/semantics.
+  - Contrast issues are tracked and remediated for P0 flows.
+
+#### TWEB-042 — Conduct tablet usability sessions (5 to 8 users)
+- Priority: P0
+- Estimate: 5 SP
+- Depends on: TWEB-040
+- Acceptance Criteria:
+  - Scripted tasks cover open/edit/inspect/export flows.
+  - Findings include severity, owner, and resolution disposition.
+  - No unresolved blocker remains for Phase 1 gate.
+
+#### TWEB-043 — Produce native handoff package from validated web patterns
+- Priority: P0
+- Estimate: 3 SP
+- Depends on: TWEB-042
+- Acceptance Criteria:
+  - Includes validated IA, interaction decisions, and known anti-patterns.
+  - Includes parity matrix updates and de-scope decisions.
+  - Reviewed by native engineering lead.
+
+#### TWEB-099 — Phase 1 gate sign-off
+- Priority: P0
+- Estimate: 2 SP
+- Depends on: TWEB-041, TWEB-042, TWEB-043
+- Acceptance Criteria:
+  - Phase 1 gates in `product-scope.md` are all satisfied.
+  - Product/design/engineering sign-off recorded.
+  - Native implementation stories are unblocked.
+
+---
+
+### Phase 2 — IPAD stories (post-gate)
+
+### EPIC: IPAD-EPIC-1 — Native Foundation & IA Reuse
+
+#### IPAD-001 — Translate validated tablet IA into native navigation model
+- Priority: P0
+- Estimate: 5 SP
+- Depends on: TWEB-099
+- Acceptance Criteria:
+  - Native IA references Phase 1 validated patterns.
+  - Required native-specific adaptations are documented.
+  - Stakeholder sign-off captured.
+
+#### IPAD-002 — Build native app shell and scene baseline
+- Priority: P0
+- Estimate: 8 SP
+- Depends on: IPAD-001
+- Acceptance Criteria:
+  - Native shell launches into document-centric flow.
+  - Scene/multiwindow baseline is functional.
+  - No dead-end navigation states.
+
+#### IPAD-003 — Establish native modal/popup infrastructure
+- Priority: P0
+- Estimate: 5 SP
+- Depends on: IPAD-002
+- Acceptance Criteria:
+  - Sheet/popover/confirmation patterns are consistent.
+  - Modal behavior aligns with HIG and test scenarios.
+  - Core dialogs can be hosted.
+
+---
+
+### EPIC: IPAD-EPIC-2 — Native Surface Implementation
+
+#### IPAD-010 — Implement native workspace and inspector surfaces
+- Priority: P0
+- Estimate: 8 SP
+- Depends on: IPAD-002
+- Acceptance Criteria:
+  - Canvas + inspector architecture is adaptive.
+  - Prioritized panels are reachable and usable.
+  - Behavior is consistent with Phase 1 validated UX intent.
+
+#### IPAD-011 — Implement native command model and shortcuts
+- Priority: P0
+- Estimate: 8 SP
+- Depends on: IPAD-002
+- Acceptance Criteria:
+  - Commands are grouped and discoverable in native command systems.
+  - Shortcut set for MVP actions is available.
+  - Command behavior remains context-aware.
+
+#### IPAD-012 — Implement native input behaviors (touch/pencil/pointer)
+- Priority: P0
+- Estimate: 8 SP
+- Depends on: IPAD-010
+- Acceptance Criteria:
+  - Core gestures and interactions are stable and predictable.
+  - Pencil and pointer behaviors are intentional.
+  - Conflicts are resolved per input contract.
+
+---
+
+### EPIC: IPAD-EPIC-3 — Native Quality & Readiness
+
+#### IPAD-020 — Run native HIG and accessibility compliance pass
+- Priority: P0
+- Estimate: 5 SP
+- Depends on: IPAD-010, IPAD-011, IPAD-012
+- Acceptance Criteria:
+  - High-severity HIG issues are resolved or explicitly waived.
+  - Accessibility baseline passes for core flows.
+  - Evidence is captured in checklist artifacts.
+
+#### IPAD-021 — Native usability validation and release readiness
+- Priority: P0
+- Estimate: 5 SP
+- Depends on: IPAD-020
+- Acceptance Criteria:
+  - Task-based validation confirms core workflow viability.
+  - Remaining gaps are documented and triaged.
+  - MVP readiness sign-off recorded.
+
+---
+
+## Story point reference (lightweight)
+
+- 2-3 SP: Small scoped artifact or contained UI mapping task
+- 5 SP: Moderate feature slice touching multiple surfaces
+- 8 SP: Complex cross-surface implementation with interaction implications