kite/.planning/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

<domain>
## 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.

</domain>

<decisions>
## 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:** Login/Register route (`/login`, `/register`) may stay synchronous if needed for first-paint — document the rationale in the router. All other authenticated routes (Topics, Document detail, Settings, Cloud, admin subtree) 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).

</decisions>

<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` — add `@tailwindcss/forms` plugin (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` — add `@tailwindcss/forms` plugin; 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>

<specifics>
## 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: install plugin, audit all form elements for conflicting per-component reset styles, normalize to smallest consistent Tailwind class set already used in the app.

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope.

</deferred>

---

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