tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
auth-yes/tasks/complete/2026-0824.04.gem.feat.ui-shell.design-tokens-and-adaptive-nav-2215.md

3.3 KiB
Raw Blame History

TASK METADATA

  • Target Files: ui/components/Layout.tsx, ui/components/AuthenticatedLayout.tsx, ui/components/AdminLayout.tsx
  • Core Objective: Implement a unified CSS custom property design token layer, dark/light theme adaptation, and dual-mode responsive layout shell (fixed mobile bottom navigation + desktop sticky header).
  • Dependencies: docs/superpowers/specs/2026-08-24-mobile-first-ui-revamp-design.md
  • Additional Important Notes: Must remain 100% pure Hono SSR JSX (zero React runtime dependencies) and support mobile safe-area insets (env(safe-area-inset-bottom)).

1. TASK METADATA

The header block specifies the target layout templates, core objective, dependencies, and constraints.

2. Architectural Considerations & Risks

Risks

  • Content Clipping Behind Fixed Bottom Navigation: If the bottom navigation bar is fixed to the bottom of the viewport on mobile without sufficient padding on the <main> container, page content (such as action buttons or footer links) could be obscured.
    • Mitigation: Explicitly set padding-bottom: calc(4.5rem + env(safe-area-inset-bottom)) on the main layout container.
  • Flash of Unstyled Content / Layout Shift: Inlining the design system tokens into SSR JSX <style> tags ensures zero-latency stylesheet loading and eliminates FOUC on mobile connections.
  • Theme Inconsistency: Hardcoded colors across sub-components can cause visual defects when switching between light and dark modes.
    • Mitigation: Standardize all colors to CSS custom properties (var(--surface-canvas), var(--text-primary), var(--border-subtle), etc.).

Alternatives

  • External CSS Bundle vs Inline SSR Style Block: Using an external stylesheet requires extra HTTP roundtrips and cache-busting logic. Embedding the design tokens directly in the root layout preserves the zero-dependency, ultra-low-latency SSR architecture of Auth-Yes.

3. Proposed Implementation

Phase 1: Global CSS Design Tokens & Base Theme

  1. Define :root and @media (prefers-color-scheme: dark) CSS custom properties in ui/components/Layout.tsx and ui/components/AuthenticatedLayout.tsx.
  2. Include color tokens (--primary, --surface-canvas, --surface-card, --border-subtle, --text-primary), elevation shadows (--shadow-sm, --shadow-md), and touch geometries (--touch-target-min: 48px, --radius-md: 10px).

Phase 2: Dual-Mode Navigation Shell

  1. In ui/components/AuthenticatedLayout.tsx:
    • On screens < 768px: Render fixed bottom navigation bar containing 4 primary destinations (Launchpad, Sessions, Passkeys, and conditionally Admin Console).
    • Render compact top app bar with Auth-Yes glyph, current screen title, and quick logout button.
    • On screens ≥ 768px: Hide bottom navigation and render full desktop sticky header with active pill tabs.
  2. In ui/components/AdminLayout.tsx:
    • Implement horizontal scrolling segmented pill sub-navigation for mobile admin tools (Users, Invites, Apps, Roles, Audit Logs).

Phase 3: Verification & Quality Gates

  1. Run deno fmt ui/**/*.tsx.
  2. Run deno task lint and deno task check.
  3. Run deno task test to ensure zero SSR regressions.