kite/.planning/milestones/v0.2-phases/11-visual-design-responsive-layout-cleanup/11-CONTEXT.md

Phase 11: Visual Design, Responsive Layout & Cleanup - Context

Gathered: 2026-06-16 Status: Ready for planning

## Phase Boundary

Phase 11 delivers visual consistency and mobile responsiveness across the entire frontend:

1. Visual polish — Remove all arbitrary spacing values, normalize typography to one scale, add consistent hover/focus-visible states and active states to every interactive element, and apply minor visual refinements where things look visibly off (inconsistent shadow, border radius, or color tone drift). The current DocuVault color identity (amber/folders, sky/cloud, indigo/admin) is preserved — no new palette.
2. Responsive layout — Below lg (1024px) both user and admin sidebars are hidden; a mobile-only hamburger button reveals a slide-in overlay drawer. StorageBrowser columns are hidden below md/sm. Touch targets are at least 36×36px below md. All modals are scrollable below 640px.
3. Performance — All non-initial-render routes lazy-loaded; two bundle analysis reports (baseline + post-optimization) committed to .planning/perf/.
4. Dead code — Frontend-only sweep: all unreferenced components, stores, helpers, and unused imports deleted after all other changes are complete.

This phase is purely frontend — no backend changes, no new features.

## Implementation Decisions

Visual Consistency (VISUAL-01..04)

• D-01: Polish + subtle refinements — Fix all VISUAL-01..04 requirements (arbitrary pixel removal, focus-visible rings, typography normalization) AND apply minor visual improvements where things look clearly off (e.g., inconsistent shadow depth, mismatched border radius, color tone drift between sections). This is not a redesign — it is removal of accumulated drift.
• D-02: Researcher does a full systematic audit of all components and views. User did not flag specific known problem areas — full discovery is expected.
• D-03: Preserve current DocuVault color identity: amber for folders/files, sky for cloud, indigo for admin sections. No new colors introduced.

Responsive Layout (RESP-01..05)

• D-04: Hamburger drawer state must not live in AppSidebar.vue or AdminSidebar.vue own data() — this is a ROADMAP pitfall constraint (PITFALLS.md §Pitfall 8). Sidebar state must be hoisted to the layout root or a store.
• D-05: Sidebar state placement (researcher decides) — either local ref() in App.vue + AdminLayout.vue (simpler, resets on route change) or a shared useLayoutStore (Pinia, globally accessible so nav links and back buttons can close the drawer). Choose based on actual component tree and what child components need to close the drawer.
• D-06: The <Teleport to="body"> pattern established in Phase 10 (for modals, toast, dropdowns) is the reference pattern for the hamburger overlay backdrop if it needs to stack above all content.

Dead Code (CODE-07)

• D-07: Frontend only — the backend was cleaned up in Phase 8; no backend dead-code sweep in this phase.
• D-08: Dead code deletion happens last (Plan 11-06), after all new additions are complete. Delete only what is confirmed unreferenced after all Phase 11 code is in place. Never delete ahead of additions.

Performance (PERF-02, PERF-03)

• D-09: Bundle baseline captured in Plan 11-01 (before any changes). Final measurement in Plan 11-06 (after all changes). Both reports committed to .planning/perf/.
• D-10: FileManagerView may stay synchronous for / as the critical first authenticated surface — document the rationale in the router. Auth routes and admin routes are already lazy-loaded. All other authenticated routes (Topics, Document detail, Settings, Cloud) must be lazy.

Claude's Discretion

• Sidebar state implementation (Pinia store vs. layout refs) — researcher reads actual App.vue, AdminLayout.vue, and nav link component trees, then picks the cleanest approach respecting D-04/D-05 above.
• Focus ring color — pick one consistent color for focus-visible: rings across the whole app (suggestion: ring-amber-500 to match the app's primary accent, or ring-blue-500 for a more neutral a11y convention). Document the chosen color.
• Typography scale definition — enumerate the actual heading/body/label/caption sizes found in the codebase and normalize to the smallest consistent set. Define in a comment in tailwind.config.js or as a convention documented in the plan's verification section.
• Minor visual refinements scope — researcher flags specific items during audit; apply only what has clear improvement value (no second-guessing the palette or layout structure).

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Phase Requirements and Goal

• .planning/ROADMAP.md §"Phase 11: Visual Design, Responsive Layout & Cleanup" — goal, implementation notes (sidebar pitfall, RESP column rules, touch target size, modal scroll, @tailwindcss/forms, CODE-07 ordering, PERF-02 timing), success criteria
• .planning/REQUIREMENTS.md §VISUAL-01..04, RESP-01..05, CODE-07, PERF-02, PERF-03 — formal requirement definitions

Responsive Layout

• .planning/research/PITFALLS.md §Pitfall 8 — sidebar open/close state must not live in AppSidebar's own data(); placement constraint for hamburger drawer implementation

Frontend Architecture

• .planning/codebase/ARCHITECTURE.md — component responsibilities, data flow, View→Smart→Presentational layering
• .planning/codebase/CONVENTIONS.md — Vue/JS style (Composition API, store patterns, import order, no Prettier/ESLint)
• CLAUDE.md §"Frontend: shared module map" — canonical shared components (StorageBrowser.vue, TreeItem.vue, formatters.js)
• CLAUDE.md §"Component architecture" — Views are thin data-providers; smart components own layout; presentational components receive props only

Files Being Modified

• frontend/src/App.vue — user layout root; hamburger button and sidebar overlay integration point
• frontend/src/layouts/AdminLayout.vue — admin layout root; same responsive treatment as App.vue (RESP-05)
• frontend/src/components/layout/AppSidebar.vue — user sidebar; hidden below lg, slides in as drawer
• frontend/src/components/admin/AdminSidebar.vue — admin sidebar; same responsive behavior
• frontend/src/components/storage/StorageBrowser.vue — responsive column hiding: Size below md, Modified below sm; touch targets (RESP-03)
• frontend/src/router/index.js — add () => import(...) lazy loading for non-initial routes (PERF-03)
• frontend/tailwind.config.js — verify @tailwindcss/forms plugin remains active (VISUAL-02)
• frontend/vite.config.js — add rollup-plugin-visualizer behind ANALYZE=true env flag (PERF-02)

Phase 10 Patterns (carry forward)

• .planning/phases/10-ux-interaction/10-CONTEXT.md §"Drag-and-Drop (D-16)" — <Teleport to="body"> established as the pattern for overlays that must stack above all content; sidebar backdrop should follow this
• .planning/phases/10-ux-interaction/10-CONTEXT.md §"Toast Notifications (D-03)" — same Teleport pattern reference

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• frontend/src/components/ui/TreeItem.vue — generic expand/collapse tree node; sidebar drawer nav links should wrap this where applicable
• frontend/src/components/ui/AppSpinner.vue — existing spinner; keep it — this phase adds no new loading patterns
• Phase 10 <Teleport to="body"> pattern — already in use for toast container and drag-drop overlay; hamburger backdrop follows the same pattern

Established Patterns

• Composition API with <script setup> — ALL Vue components in this codebase use Composition API (confirmed at 2026-06-02 codebase analysis). Researcher should verify current state before assuming Options API.
• Tailwind utility classes inline — no scoped <style> blocks. All spacing/color fixes applied as class changes in template.
• No @/ alias — relative paths throughout frontend imports.
• <Teleport to="body"> for overlays — Phase 10's pattern for stacking contexts; use for sidebar backdrop.

Integration Points

• App.vue — user layout root; hamburger button + sidebar drawer mount here. Phase 10 already added <Teleport>-based toast container and drag overlay here.
• AdminLayout.vue — admin layout root; separate hamburger button needed for admin nav drawer (RESP-05); same structural pattern as App.vue
• frontend/src/router/index.js — lazy-load additions happen here; preserve all existing meta: { requiresAuth, requiresAdmin } guards
• frontend/tailwind.config.js — @tailwindcss/forms is already active; do not break existing utility classes

PERF-02 Bundle Workflow

• Plan 11-01 adds rollup-plugin-visualizer behind ANALYZE=true and captures baseline in .planning/perf/phase11-baseline.html
• Plan 11-06 captures final report in .planning/perf/phase11-final.html
• Both files committed to repo as required evidence

</code_context>

## Specific Ideas

• Sidebar drawer animation: translate-x-0 / -translate-x-full transition (from ROADMAP.md) — no JavaScript-driven animation, pure Tailwind transition classes.
• Backdrop for drawer: semi-transparent overlay, tap to close. Use <Teleport to="body"> consistent with existing overlay pattern.
• Touch target minimum: min-w-[36px] min-h-[36px] or equivalent padding on icon action buttons below md.
• Modal scroll: max-h-[90vh] overflow-y-auto pattern on modal content container for viewports below 640px.
• @tailwindcss/forms strategy: verify plugin remains active, audit all form elements for conflicting per-component reset styles, normalize to smallest consistent Tailwind class set already used in the app.

## Deferred Ideas

None — discussion stayed within phase scope.

---

Phase: 11-visual-design-responsive-layout-cleanup Context gathered: 2026-06-16