From 224fd59196468e5bd2d0fff209436ca91a38b2ad Mon Sep 17 00:00:00 2001 From: Schalli Date: Thu, 18 Jun 2026 10:31:16 +0200 Subject: [PATCH] docs(01-02): complete Portal Shell plan with SUMMARY, state updates - SUMMARY.md documenting design tokens, i18n, layout components - STATE.md advanced to plan 2/3, decisions recorded - ROADMAP.md updated to 2/3 plans complete - REQUIREMENTS.md: PRTAL-01, PRTAL-04, UI-01, UI-02, UI-03 marked complete --- .planning/REQUIREMENTS.md | 20 +-- .planning/ROADMAP.md | 4 +- .planning/STATE.md | 38 ++-- .../01-02-SUMMARY.md | 163 ++++++++++++++++++ 4 files changed, 196 insertions(+), 29 deletions(-) create mode 100644 .planning/phases/01-foundation-portal-shell/01-02-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 00f786a..ef46537 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -24,10 +24,10 @@ Requirements for initial release. Each maps to roadmap phases. ### Portal Shell -- [ ] **PRTAL-01**: Schmale Kopfzeile mit Branding und Benutzer-Menu +- [x] **PRTAL-01**: Schmale Kopfzeile mit Branding und Benutzer-Menu - [ ] **PRTAL-02**: Linke Seitenleiste zeigt Kategorien und aktivierte Module - [ ] **PRTAL-03**: Ausgewaehltes Modul oeffnet sich im Hauptbereich (Mitte) -- [ ] **PRTAL-04**: Responsive Layout fuer verschiedene Bildschirmgroessen +- [x] **PRTAL-04**: Responsive Layout fuer verschiedene Bildschirmgroessen - [ ] **PRTAL-05**: Module koennen in der Seitenleiste durchsucht und gefiltert werden ### Marketplace @@ -68,9 +68,9 @@ Requirements for initial release. Each maps to roadmap phases. ### UI & Internationalisierung -- [ ] **UI-01**: Light/Dark Theme umschaltbar pro Benutzer -- [ ] **UI-02**: Zweisprachig: Deutsch und Englisch mit Sprachwahl -- [ ] **UI-03**: i18n-Framework von Anfang an integriert (alle Strings ueber t('key')) +- [x] **UI-01**: Light/Dark Theme umschaltbar pro Benutzer +- [x] **UI-02**: Zweisprachig: Deutsch und Englisch mit Sprachwahl +- [x] **UI-03**: i18n-Framework von Anfang an integriert (alle Strings ueber t('key')) ### Infrastruktur @@ -134,10 +134,10 @@ Which phases cover which requirements. Updated during roadmap creation. | TNNT-01 | Phase 2 | Pending | | TNNT-02 | Phase 2 | Pending | | TNNT-03 | Phase 2 | Pending | -| PRTAL-01 | Phase 1 | Pending | +| PRTAL-01 | Phase 1 | Complete | | PRTAL-02 | Phase 4 | Pending | | PRTAL-03 | Phase 4 | Pending | -| PRTAL-04 | Phase 1 | Pending | +| PRTAL-04 | Phase 1 | Complete | | PRTAL-05 | Phase 4 | Pending | | MRKT-01 | Phase 4 | Pending | | MRKT-02 | Phase 4 | Pending | @@ -160,9 +160,9 @@ Which phases cover which requirements. Updated during roadmap creation. | DCHK-01 | Phase 3 | Pending | | DCHK-02 | Phase 3 | Pending | | DCHK-03 | Phase 3 | Pending | -| UI-01 | Phase 1 | Pending | -| UI-02 | Phase 1 | Pending | -| UI-03 | Phase 1 | Pending | +| UI-01 | Phase 1 | Complete | +| UI-02 | Phase 1 | Complete | +| UI-03 | Phase 1 | Complete | | INFRA-01 | Phase 1 | Complete | | INFRA-02 | Phase 1 | Complete | | INFRA-03 | Phase 1 | Complete | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 5b998af..6543c80 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -43,7 +43,7 @@ Decimal phases appear between their surrounding integers in numeric order. **Wave 2** *(blocked on Wave 1 completion)* -- [ ] 01-02-PLAN.md -- Portal Shell: Design tokens, i18n (DE/EN), theme switching, responsive layout with header + sidebar +- [x] 01-02-PLAN.md -- Portal Shell: Design tokens, i18n (DE/EN), theme switching, responsive layout with header + sidebar **Wave 3** *(blocked on Wave 2 completion)* @@ -138,7 +138,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 | Phase | Plans Complete | Status | Completed | |-------|----------------|--------|-----------| -| 1. Foundation & Portal Shell | 0/3 | Planned | - | +| 1. Foundation & Portal Shell | 2/3 | In Progress | - | | 2. Authentication & Multi-Tenancy | 0/TBD | Not started | - | | 3. Module System & Domaincheck | 0/TBD | Not started | - | | 4. Marketplace & Portal Navigation | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index fa3fcf3..1c5cf61 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,15 +3,15 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone status: executing -stopped_at: Completed 01-01-PLAN.md (Walking Skeleton) -last_updated: "2026-06-18T08:18:00Z" -last_activity: 2026-06-18 -- Plan 01-01 Walking Skeleton complete +stopped_at: Completed 01-02-PLAN.md (Portal Shell) +last_updated: "2026-06-18T08:28:41Z" +last_activity: 2026-06-18 -- Plan 01-02 Portal Shell complete progress: total_phases: 6 completed_phases: 0 total_plans: 3 - completed_plans: 1 - percent: 5 + completed_plans: 2 + percent: 10 --- # Project State @@ -26,30 +26,30 @@ See: .planning/PROJECT.md (updated 2026-06-18) ## Current Position Phase: 1 of 6 (Foundation & Portal Shell) -Plan: 1 of 3 in current phase (completed) +Plan: 2 of 3 in current phase (completed) Status: Executing phase 1 -Last activity: 2026-06-18 -- Plan 01-01 Walking Skeleton complete +Last activity: 2026-06-18 -- Plan 01-02 Portal Shell complete -Progress: [█░░░░░░░░░] 5% +Progress: [██░░░░░░░░] 10% ## Performance Metrics **Velocity:** -- Total plans completed: 1 -- Average duration: 16 min -- Total execution time: 0.27 hours +- Total plans completed: 2 +- Average duration: 12 min +- Total execution time: 0.38 hours **By Phase:** | Phase | Plans | Total | Avg/Plan | |-------|-------|-------|----------| -| 01-foundation-portal-shell | 1/3 | 16 min | 16 min | +| 01-foundation-portal-shell | 2/3 | 23 min | 12 min | **Recent Trend:** -- Last 5 plans: 01-01 (16 min) -- Trend: first plan +- Last 5 plans: 01-01 (16 min), 01-02 (7 min) +- Trend: improving *Updated after each plan completion* @@ -65,6 +65,10 @@ Recent decisions affecting current work: - [01-01]: Used Traefik v2.11 instead of v3.4 due to Docker API version incompatibility on host - [01-01]: Traefik placed on frontend-net + backend-net for routing to both web and api services - [01-01]: API Dockerfile copies full monorepo node_modules structure for pnpm workspace compatibility +- [01-02]: OKLCH color space for all design tokens (Tailwind v4 native, perceptually uniform) +- [01-02]: Dark mode uses oklch(0.17 0.01 260) dark gray-blue for comfortable contrast with yellow primary +- [01-02]: Cookie-based locale (NEXT_LOCALE) instead of URL routing for portal app +- [01-02]: CSS custom property --current-sidebar-width for responsive main content margin ### Pending Todos @@ -84,6 +88,6 @@ Items acknowledged and carried forward from previous milestone close: ## Session Continuity -Last session: 2026-06-18T08:18:00Z -Stopped at: Completed 01-01-PLAN.md -Resume file: .planning/phases/01-foundation-portal-shell/01-02-PLAN.md +Last session: 2026-06-18T08:28:41Z +Stopped at: Completed 01-02-PLAN.md (Portal Shell) +Resume file: .planning/phases/01-foundation-portal-shell/01-03-PLAN.md diff --git a/.planning/phases/01-foundation-portal-shell/01-02-SUMMARY.md b/.planning/phases/01-foundation-portal-shell/01-02-SUMMARY.md new file mode 100644 index 0000000..7789227 --- /dev/null +++ b/.planning/phases/01-foundation-portal-shell/01-02-SUMMARY.md @@ -0,0 +1,163 @@ +--- +phase: 01-foundation-portal-shell +plan: 02 +subsystem: ui +tags: [next-intl, next-themes, zustand, tailwindcss, oklch, i18n, theming, responsive-layout, portal-shell] + +# Dependency graph +requires: + - phase: 01-01 + provides: "Monorepo scaffold, Next.js app, Tailwind CSS v4, build tooling" +provides: + - OKLCH design token system with yellow #ffed00 primary and dark gray-blue dark mode + - i18n framework with DE/EN translations via next-intl cookie-based locale + - Theme switching (light/dark/system) via next-themes with persistence + - Sticky header with logo, breadcrumb, theme toggle, locale switcher, user avatar placeholder + - Collapsible sidebar (240px to 64px) with Dashboard/Marketplace nav and accordion categories + - Mobile responsive layout with hamburger menu and overlay sidebar + - Empty dashboard state with "Keine Widgets aktiv" placeholder and add widget button + - AppShell layout composition component for all future pages + - Zustand sidebar store with localStorage persistence +affects: [01-03-portal-shell, phase-2-auth, phase-3-modules, phase-4-marketplace, phase-5-dashboard] + +# Tech tracking +tech-stack: + added: [next-intl@4.13, next-themes@0.4.6, zustand@5.0.14] + patterns: [design-tokens-oklch, cookie-based-locale, zustand-persist-store, provider-wrapped-layout, responsive-sidebar-overlay] + +key-files: + created: + - apps/web/src/app/globals.css + - apps/web/src/i18n/request.ts + - apps/web/src/messages/de.json + - apps/web/src/messages/en.json + - apps/web/src/lib/stores/sidebar-store.ts + - apps/web/src/components/layout/app-shell.tsx + - apps/web/src/components/layout/header.tsx + - apps/web/src/components/layout/sidebar.tsx + - apps/web/src/components/layout/sidebar-footer.tsx + - apps/web/src/components/theme-toggle.tsx + - apps/web/src/components/locale-switcher.tsx + modified: + - apps/web/package.json + - apps/web/next.config.ts + - apps/web/src/app/layout.tsx + - apps/web/src/app/page.tsx + +key-decisions: + - "Used OKLCH color space for all design tokens per Tailwind v4 best practice" + - "Dark mode uses oklch(0.17 0.01 260) dark gray-blue for comfortable contrast with yellow primary" + - "Cookie-based locale (NEXT_LOCALE) instead of URL routing since portal is a logged-in app" + - "Zustand with persist middleware for sidebar state to survive page refreshes" + - "CSS custom property --current-sidebar-width for responsive main content margin" + - "Added Inter font-family as --font-sans variable for clean modern style" + +patterns-established: + - "Design tokens: All colors as CSS custom properties at :root, theme variants via .dark selector" + - "i18n: Every user-visible string through useTranslations() hook, German as default locale" + - "State management: Zustand stores in src/lib/stores/ with persist middleware" + - "Layout composition: AppShell wraps Header + Sidebar + main content area" + - "Component organization: layout/ for structural components, root for reusable UI" + - "Responsive: md breakpoint (768px) separates mobile overlay from desktop sidebar" + +requirements-completed: [PRTAL-01, PRTAL-04, UI-01, UI-02, UI-03] + +# Metrics +duration: 7min +completed: 2026-06-18 +--- + +# Phase 1 Plan 02: Portal Shell Summary + +**Responsive portal shell with OKLCH design tokens (yellow #ffed00 primary), collapsible sidebar, sticky header, DE/EN i18n via next-intl cookies, and light/dark/system theme switching via next-themes** + +## Performance + +- **Duration:** 7 min +- **Started:** 2026-06-18T08:21:15Z +- **Completed:** 2026-06-18T08:28:41Z +- **Tasks:** 2 +- **Files modified:** 15 + +## Accomplishments +- Full design token system with OKLCH colors, sidebar/header layout tokens, and light/dark theme variants +- Bilingual interface (DE/EN) with 24 translation keys and cookie-based locale persistence +- Complete portal layout: sticky header with branding/actions, collapsible sidebar with nav and categories, responsive main area +- Theme toggle cycling light/dark/system with localStorage persistence and SSR-safe mounted guard +- Empty dashboard state showing "Keine Widgets aktiv" with add widget button per D-16 + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Design token system + i18n framework + theme provider setup** - `f3791c6` (feat) +2. **Task 2: Portal layout components -- header, sidebar, app shell, interactions** - `6039387` (feat) + +## Files Created/Modified +- `apps/web/src/app/globals.css` - OKLCH design tokens with @theme inline block, light/dark variants, sidebar tokens, layout dimensions +- `apps/web/next.config.ts` - Wrapped with createNextIntlPlugin for i18n support +- `apps/web/src/app/layout.tsx` - Async root layout with ThemeProvider and NextIntlClientProvider wrappers +- `apps/web/src/i18n/request.ts` - Locale resolution from NEXT_LOCALE cookie, dynamic message import +- `apps/web/src/messages/de.json` - German translations (24 keys across 6 namespaces) +- `apps/web/src/messages/en.json` - English translations (matching 24 keys) +- `apps/web/src/lib/stores/sidebar-store.ts` - Zustand store with isCollapsed, isMobileOpen, persist to localStorage +- `apps/web/src/components/layout/header.tsx` - Sticky header: logo left, breadcrumb center, theme/locale/user right, mobile hamburger +- `apps/web/src/components/layout/sidebar.tsx` - Collapsible sidebar: Dashboard (active), Marketplace, accordion categories, collapse toggle, mobile overlay +- `apps/web/src/components/layout/sidebar-footer.tsx` - Settings icon and user info placeholder +- `apps/web/src/components/layout/app-shell.tsx` - Layout composition with responsive main content margin +- `apps/web/src/components/theme-toggle.tsx` - Three-state theme cycle with SVG icons and hydration guard +- `apps/web/src/components/locale-switcher.tsx` - Cookie-based DE/EN toggle with router.refresh +- `apps/web/src/app/page.tsx` - Dashboard page with empty state: grid icon, translated text, add widget button +- `apps/web/package.json` - Added next-intl, next-themes, zustand dependencies + +## Decisions Made +- **OKLCH color space**: Used OKLCH for all design tokens (Tailwind v4 native support) rather than hex/hsl -- provides perceptually uniform color manipulation +- **Dark gray-blue dark mode**: Used oklch(0.17 0.01 260) -- comfortable with yellow primary, avoids harsh true-black per user recommendation in D-14 +- **Cookie-based locale**: NEXT_LOCALE cookie with 1-year max-age, read server-side by next-intl -- avoids URL routing complexity for portal app +- **CSS custom property for main margin**: Used --current-sidebar-width CSS variable with @media query rather than inline style -- cleanly handles responsive breakpoint +- **Inter font-family**: Selected Inter as primary font per discretion recommendation for clean modern style + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 2 - Missing Critical] Added i18n for hardcoded strings in mobile sidebar and sidebar footer** +- **Found during:** Task 2 (Portal layout components) +- **Issue:** Mobile sidebar header had hardcoded "Tessera" text and sidebar footer had hardcoded "User" placeholder -- violated UI-03 requirement +- **Fix:** Added tCommon('appName') in sidebar mobile header, t('userPlaceholder') in sidebar footer, common.menu key for hamburger aria-label +- **Files modified:** sidebar.tsx, sidebar-footer.tsx, de.json, en.json +- **Verification:** grep for hardcoded strings returns no results +- **Committed in:** 6039387 (Task 2 commit) + +--- + +**Total deviations:** 1 auto-fixed (1 missing critical -- i18n compliance) +**Impact on plan:** Essential fix for UI-03 requirement compliance. No scope creep. + +## Issues Encountered +None - both tasks executed cleanly with type-check and build verification passing. + +## User Setup Required + +None - no external service configuration required. + +## Known Stubs + +- `apps/web/src/components/layout/header.tsx` line 67 - User avatar is a placeholder div (will be wired to auth in Phase 2) +- `apps/web/src/components/layout/sidebar-footer.tsx` line 52 - User name shows translation placeholder (will be wired to auth in Phase 2) +- `apps/web/src/app/page.tsx` line 40 - Add widget button is non-functional (dashboard implementation in Phase 5) + +## Next Phase Readiness +- Portal shell is fully functional with theme, i18n, and responsive layout +- AppShell component ready to wrap all future page routes +- Sidebar navigation entries ready for dynamic population from module registry (Phase 3-4) +- Design token system provides consistent theming foundation for all future components +- Message file structure supports additional namespaces for future modules + +## Self-Check: PASSED + +All 15 key files verified present. Both commit hashes (f3791c6, 6039387) verified in git log. + +--- +*Phase: 01-foundation-portal-shell* +*Completed: 2026-06-18*