docs(11): capture phase context
This commit is contained in:
curo1305
@@ -0,0 +1,135 @@
|
||||
# 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*
|
||||
@@ -0,0 +1,83 @@
|
||||
# Phase 11: Visual Design, Responsive Layout & Cleanup - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-06-16
|
||||
**Phase:** 11-visual-design-responsive-layout-cleanup
|
||||
**Areas discussed:** Sidebar state, Visual polish depth, Dead code scope
|
||||
|
||||
---
|
||||
|
||||
## Existing Plans Gate
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| View existing plans | Show what plans were created before deciding | ✓ |
|
||||
| Continue and replan after | Capture context now, then replan | |
|
||||
| Cancel | Stop here | |
|
||||
|
||||
**User's choice:** Viewed plans first, then chose "Continue and replan after"
|
||||
**Notes:** User reviewed all 6 existing plans (11-01 through 11-06) before proceeding. Plans looked solid in structure; user wants context captured so plans can be rebuilt with decisions locked in.
|
||||
|
||||
---
|
||||
|
||||
## Sidebar State
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| App.vue / AdminLayout.vue refs | Local ref() in layout root. Simple, no store overhead. | |
|
||||
| Shared useLayoutStore (Pinia) | One store, two fields. Any component can close the drawer. | |
|
||||
| You decide | Researcher picks cleanest option given actual component tree | ✓ |
|
||||
|
||||
**User's choice:** You decide (Claude's discretion)
|
||||
**Notes:** ROADMAP.md pitfall constraint (§Pitfall 8) is locked — state must not live in AppSidebar/AdminSidebar own data(). Researcher will read actual component tree and choose between Pinia store or layout-root ref based on whether child components (e.g., nav links, "Back to app" button) need to close the drawer.
|
||||
|
||||
---
|
||||
|
||||
## Visual Polish Depth
|
||||
|
||||
**Question 1: Ambition level**
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Discipline only | Fix VISUAL-01..04 only. No visual redesign. | |
|
||||
| Polish + subtle refinements | Fix requirements AND allow minor improvements where things look off (shadows, border radius, color tone drift). Still no new palette. | ✓ |
|
||||
|
||||
**User's choice:** Polish + subtle refinements
|
||||
**Notes:** User wants things to look noticeably better where there's clear visual drift, not just mechanically compliant.
|
||||
|
||||
**Question 2: Known problem areas**
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| No, let the researcher find them | Systematic full audit | ✓ |
|
||||
| Yes, I have specific complaints | User would specify targets | |
|
||||
|
||||
**User's choice:** Researcher does full audit
|
||||
**Notes:** No specific components flagged by user. Full discovery expected.
|
||||
|
||||
---
|
||||
|
||||
## Dead Code Scope
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Frontend only | Stick to 6 existing plans. Backend was cleaned in Phase 8. | ✓ |
|
||||
| Frontend + backend | Also sweep backend for unused routes, dead utilities, stale imports. | |
|
||||
|
||||
**User's choice:** Frontend only
|
||||
**Notes:** Backend was decomposed and cleaned in Phase 8. No backend dead-code sweep needed in this phase.
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- **Sidebar state implementation** — Pinia store vs. layout refs; researcher decides based on actual component tree
|
||||
- **Focus ring color** — pick one consistent color for focus-visible rings (recommendation: `ring-amber-500` or neutral `ring-blue-500`)
|
||||
- **Typography scale definition** — enumerate actual sizes found in codebase, normalize to smallest consistent set, document in plan verification
|
||||
- **Minor visual refinement scope** — researcher flags specific items during audit; apply only what has clear improvement value
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
None — discussion stayed within phase scope.
|
||||
Reference in New Issue
Block a user