docs(ui): Add UI layout refactor plan and OpenSpec changes
- Update decision-log with UI layout decisions (Feb 18, 2026) - Update architecture with frontend layout patterns - Update config.yaml with TDD, documentation, UI standards rules - Create p00-api-documentation change (Scribe annotations) - Create p01-ui-foundation change (types, stores, Lucide) - Create p02-app-layout change (AppLayout, Sidebar, TopBar) - Create p03-dashboard-enhancement change (PageHeader, StatCard) - Create p04-content-patterns change (DataTable, FilterBar) - Create p05-page-migrations change (page migrations) - Fix E2E auth tests (11/11 passing) - Add JWT expiry validation to dashboard guard
This commit is contained in:
@@ -796,6 +796,120 @@ For month M:
|
||||
|
||||
---
|
||||
|
||||
## UI Layout Decisions
|
||||
|
||||
**Date:** February 18, 2026
|
||||
**Context:** After initial authentication implementation, reviewed login page UI and decided to establish a comprehensive layout system.
|
||||
|
||||
### Problem Statement
|
||||
|
||||
The initial UI implementation used a simple top-navbar pattern without a standardized layout system. For a data-dense resource planning application, this approach would not scale well.
|
||||
|
||||
### Design Direction
|
||||
|
||||
**Aesthetic Spectrum Decision:**
|
||||
- Target: **70% Data-Dense | 30% Utilitarian**
|
||||
- Reference Apps: **Obsidian** (minimal chrome, content-first) + **Jira** (hierarchical sidebar, dense tables)
|
||||
|
||||
### Core Layout Decisions
|
||||
|
||||
| Decision | Choice | Rationale |
|
||||
|----------|--------|-----------|
|
||||
| **Sidebar** | Collapsible (full ↔ icons-only ↔ hidden) | Preserves screen real estate for low-resolution displays; sidebar should not eat productive space |
|
||||
| **Month Selector** | Global (in top bar) | Allocation and actuals views are month-centric; affects all views |
|
||||
| **Default Theme** | Light mode | Starting simple; dark mode available as toggle |
|
||||
| **Icon Library** | **Lucide Svelte** | Modern, more icon variety, consistent with Svelte ecosystem |
|
||||
| **UI Framework** | **DaisyUI-first** (no shadcn-svelte) | Already have it, excellent for business apps, use ~80% of its potential |
|
||||
| **Navigation Pattern** | Persistent sidebar + top bar | Obsidian/Jira style; sectioned navigation (Planning, Reports, Admin) |
|
||||
|
||||
### Sidebar Specifications
|
||||
|
||||
```
|
||||
EXPANDED (240px) COLLAPSED (64px) HIDDEN (0px)
|
||||
┌────────────────┐ ┌────────┐ ┌──────────────────┐
|
||||
│ ◀ ▶ │ │ ▶ │ │ │
|
||||
│ ────────────── │ │ ────── │ │ Full width │
|
||||
│ PLANNING │ │ │ │ content │
|
||||
│ 📊 Dashboard │ │ 📊 │ │ │
|
||||
│ 👥 Team Mem │ │ 👥 │ │ (toggle via │
|
||||
│ 📁 Projects │ │ 📁 │ │ Cmd/Ctrl+\) │
|
||||
│ 📅 Allocations │ │ 📅 │ │ │
|
||||
│ ✅ Actuals │ │ ✅ │ │ │
|
||||
│ ────────────── │ │ ────── │ │ │
|
||||
│ REPORTS │ │ │ │ │
|
||||
│ 📈 Forecast │ │ 📈 │ │ │
|
||||
│ 📉 Utilization │ │ 📉 │ │ │
|
||||
│ 💰 Costs │ │ 💰 │ │ │
|
||||
│ 📋 Variance │ │ 📋 │ │ │
|
||||
│ ────────────── │ │ ────── │ │ │
|
||||
│ ADMIN* │ │ │ │ │
|
||||
│ ⚙️ Settings │ │ ⚙️ │ │ │
|
||||
│ ────────────── │ │ ────── │ │ │
|
||||
│ 🌙 Dark [tgl] │ │ 🌙 │ │ │
|
||||
└────────────────┘ └────────┘ └──────────────────┘
|
||||
|
||||
* Admin section visible only to superuser role
|
||||
```
|
||||
|
||||
### Responsive Behavior
|
||||
|
||||
| Breakpoint | Sidebar Behavior | Toggle |
|
||||
|------------|------------------|--------|
|
||||
| ≥1280px (xl) | Expanded by default | Manual toggle only |
|
||||
| 1024-1279px (lg) | Collapsed by default | Manual toggle only |
|
||||
| 768-1023px (md) | Hidden (drawer overlay) | Hamburger menu |
|
||||
| <768px (sm) | Hidden (drawer overlay) | Hamburger menu |
|
||||
|
||||
### Implementation Approach
|
||||
|
||||
**Phased Changes:**
|
||||
1. `p00-api-documentation` — Add Scribe annotations to all controllers
|
||||
2. `p01-ui-foundation` — Types, stores, Lucide setup, theme system
|
||||
3. `p02-app-layout` — AppLayout, Sidebar, TopBar, Breadcrumbs
|
||||
4. `p03-dashboard-enhancement` — Dashboard with stat cards
|
||||
5. `p04-content-patterns` — DataTable, StatCard, FilterBar, EmptyState, LoadingState
|
||||
6. `p05-page-migrations` — Migrate remaining pages incrementally
|
||||
|
||||
### Files to Create
|
||||
|
||||
```
|
||||
frontend/src/lib/
|
||||
├── types/layout.ts # SidebarState, NavItem, NavSection
|
||||
├── stores/
|
||||
│ ├── layout.ts # sidebarState, theme
|
||||
│ └── period.ts # selectedMonth (global)
|
||||
├── config/navigation.ts # Navigation sections config
|
||||
└── components/layout/
|
||||
├── AppLayout.svelte # Main layout wrapper
|
||||
├── Sidebar.svelte # Collapsible navigation
|
||||
├── TopBar.svelte # Search, month, user menu
|
||||
├── Breadcrumbs.svelte # Navigation context
|
||||
└── PageHeader.svelte # Page title + actions
|
||||
```
|
||||
|
||||
### DaisyUI Table Density
|
||||
|
||||
| View | Classes |
|
||||
|------|---------|
|
||||
| Allocation Matrix | `table-compact table-pin-rows table-pin-cols` |
|
||||
| Projects List | `table-zebra table-pin-rows` |
|
||||
| Team Members | `table-zebra` |
|
||||
| Reports | `table-compact table-pin-rows` |
|
||||
|
||||
### Key Quotes from Discussion
|
||||
|
||||
> "I like a collapsible sidebar, because some people use very low screen resolution which will limit the real estate to play around with. Sidebar should not eat up the productive space."
|
||||
|
||||
> "Make [month selector] global."
|
||||
|
||||
> "Light mode for now."
|
||||
|
||||
> "I lean more towards data-dense. How about keeping it 30-70 (utilitarian-data-dense)?"
|
||||
|
||||
> "Use Lucide."
|
||||
|
||||
---
|
||||
|
||||
## Next Steps (Post-Documentation)
|
||||
|
||||
### Immediate Actions
|
||||
|
||||
Reference in New Issue
Block a user