Skip to content
Shell
12.3 KB
Raw Blame

ejb.ventures - Knolling Interface Implementation Plan

Overview

Transform the diagonal split-screen landing page into an immersive knolling photograph interface with clickable object navigation, visual modes (Personal/Pro/Blacklight), and overlay-based content presentation.

Key Decisions

Decision Choice Rationale
Image Strategy Placeholder first Build components with placeholders, swap AI images later
Navigation Overlay modals (SPA) Content opens on top of knolling photo
Mobile Phase 1 together Build mobile grid fallback alongside desktop
Image Generation Gemini Already in package.json (@google/generative-ai)
Stack Keep current Next.js 16 + React 19 + Tailwind v4 + Framer Motion

Architecture

Component Hierarchy

<ModeProvider>                    // Extended from ThemeProvider
  <KnollingCanvas>               // Desktop: full viewport (z-index: 0)
    <BaseImage />                // Knolling photo
    <TimeBasedLighting />        // CSS filter layer (z-index: 1)
    <ModeOverlay />              // Blueprint/HUD/Blacklight (z-index: 2)
    <HotspotLayer>               // SVG interaction layer (z-index: 10)
      <Hotspot />                // Individual clickable objects
    </HotspotLayer>
  </KnollingCanvas>

  <MobileKnollingView />         // Mobile: vertical card grid

  <OverlayManager>               // Content presentation (z-index: 100)
    <ContentOverlay />           // Essays, Work, Bio, etc.
  </OverlayManager>

  <TerminalOverlay />            // CLI popup (z-index: 1000) - Phase 5
</ModeProvider>

State Management

Extend existing ThemeProvider (components/theme/theme-provider.tsx):

interface ModeState {
  mode: 'personal' | 'professional' | 'blacklight';
  activeOverlay: string | null;  // 'essays' | 'work' | 'bio' | etc.
  terminalOpen: boolean;
  timeOfDay: 'dawn' | 'morning' | 'midday' | 'afternoon' | 'dusk' | 'night';
  blacklightUnlocked: boolean;
}

Phase 1: Knolling Foundation

Goal: Working knolling interface with placeholder images, clickable hotspots, and mobile fallback

Skills: frontend-design:frontend-design, ui-builder, nextjs-project-manager

1.1 Placeholder Assets

Create /public/knolling/ with placeholder images:

  • base-composite.webp - Placeholder dark surface (can be gradient)
  • objects/camera.png, laptop.png, notebooks.png, photo-frame.png, books.png, rolodex.png

1.2 Hotspot Configuration

File: lib/hotspots.ts

export interface Hotspot {
  id: string;
  label: string;
  action: 'toggle-mode' | 'open-terminal' | 'overlay';
  target?: string;
  coords: [x: number, y: number, width: number, height: number]; // percentages
}

export const HOTSPOTS: Hotspot[] = [
  { id: 'camera', label: 'Mode Toggle', action: 'toggle-mode', coords: [45, 30, 12, 18] },
  { id: 'laptop', label: 'Terminal', action: 'open-terminal', coords: [60, 45, 18, 12] },
  { id: 'notebooks', label: 'Essays', action: 'overlay', target: 'essays', coords: [25, 55, 15, 20] },
  { id: 'photo-frame', label: 'About', action: 'overlay', target: 'bio', coords: [15, 25, 10, 14] },
  { id: 'books', label: 'Philosophy', action: 'overlay', target: 'philosophy', coords: [75, 60, 12, 16] },
  { id: 'rolodex', label: 'Contact', action: 'overlay', target: 'contact', coords: [80, 30, 10, 12] },
];

1.3 Core Components

Files to create:

  1. components/knolling/KnollingCanvas.tsx - Desktop container with image + hotspots
  2. components/knolling/HotspotLayer.tsx - SVG overlay with clickable regions
  3. components/knolling/Hotspot.tsx - Individual hotspot with hover/focus states
  4. components/knolling/MobileKnollingView.tsx - Card grid for viewport < 768px
  5. components/mode/ModeProvider.tsx - Extended ThemeProvider with tri-state

File to replace:

  • app/page.tsx - Complete replacement with KnollingCanvas + MobileKnollingView

1.4 Phase 1 Deliverables

  • Placeholder knolling image displays full viewport (desktop)
  • 6 hotspots are clickable with hover glow effect
  • Camera hotspot toggles Personal/Pro mode
  • Other hotspots show "Coming soon" toast
  • Mobile shows vertical card grid with same functionality
  • Keyboard navigation (Tab through hotspots)

Phase 2: Overlay System & Content

Goal: Portal-based overlays for content presentation

Skills: ui-builder, state-management

2.1 Components

Files to create:

  1. components/overlays/OverlayManager.tsx - Portal container with AnimatePresence
  2. components/overlays/ContentOverlay.tsx - Glassmorphism modal with MDX content

2.2 Content Mapping

Hotspot Content Source
Essays content/essays/*.mdx (existing)
Work content/work/*.mdx (existing)
Bio content/personal/bio.mdx (create)
Philosophy content/personal/philosophy.mdx (create)
Contact Contact form component

2.3 Phase 2 Deliverables

  • Overlays open with slide-up + fade animation
  • Backdrop blur on knolling image when overlay open
  • Close on backdrop click, Escape key, or X button
  • MDX content styled within overlays
  • Deep-linking via URL hash (#essays, #bio)

Phase 3: Mode Visual Treatments

Goal: Blueprint overlay (Personal) and Cinema HUD overlay (Pro)

Skills: frontend-design:frontend-design, ui-builder Subagent: frontend-developer for complex SVG animations

3.1 Components

Files to create:

  1. components/knolling/overlays/BlueprintOverlay.tsx

    • Orange graph paper grid (SVG pattern, 10% opacity)
    • Hand-drawn annotation lines to hotspots
    • Monospace labels, dotted dimension lines
  2. components/knolling/overlays/CinemaHUDOverlay.tsx

    • 12% letterbox bars (top/bottom)
    • rec709 color grade (CSS filter)
    • Film grain texture, live timecode
    • REC indicator with pulsing dot
    • Focus brackets on hover

3.2 Mode Transition Animation

Camera click triggers rack focus effect:

  1. Blur to 12px, scale 1.05 (0.6s)
  2. Old overlay fades, new begins (0.6s)
  3. Sharpen back, scale 1.0 (1.3s)

3.3 Phase 3 Deliverables

  • Blueprint overlay renders in Personal mode
  • HUD overlay renders in Pro mode
  • Smooth 2.5s mode transition animation
  • Hotspot glow color matches mode (orange/cyan)

Phase 4: Time-Based Lighting

Goal: Automatic lighting changes based on user's local time

Skills: state-management

4.1 Hook

File: hooks/useTimeOfDay.ts

Time periods: dawn (5-7), morning (7-11), midday (11-16), golden (16-19), night (19-5)

4.2 CSS Filters

.lighting-dawn { filter: brightness(0.8) contrast(1.1) hue-rotate(-10deg); }
.lighting-morning { filter: brightness(1.1) saturate(1.1) hue-rotate(5deg); }
.lighting-midday { filter: brightness(1.15) contrast(1); }
.lighting-golden { filter: brightness(1.05) saturate(1.2) sepia(0.15); }
.lighting-night { filter: brightness(0.6) contrast(1.15) hue-rotate(-20deg); }

4.3 Phase 4 Deliverables

  • Automatic lighting based on local time
  • 30-second CSS transitions between periods
  • Override option via CLI command

Phase 5: CLI Terminal

Goal: Working command-line interface popup

Skills: ui-builder, state-management

5.1 Components

Files to create:

  1. components/terminal/CLITerminal.tsx - Draggable terminal window
  2. components/terminal/CommandInput.tsx - Input with history
  3. lib/terminal/commands.ts - Command definitions
  4. lib/terminal/parser.ts - Command parsing

5.2 Commands

const COMMANDS = {
  help: () => 'Available commands: help, about, projects, github, contact, mode, clear, exit',
  about: () => BIO_CONTENT,
  projects: () => formatProjectList(PROJECTS),
  github: () => openGitHubDashboard(),
  contact: () => CONTACT_INFO,
  mode: (arg) => setMode(arg), // 'personal' | 'pro'
  clear: () => clearTerminal(),
  exit: () => closeTerminal(),
};

5.3 Phase 5 Deliverables

  • Terminal opens via laptop hotspot or Cmd/Ctrl + K
  • All v1 commands working
  • Command history (up/down arrows)
  • Tab autocomplete for commands

Phase 6: Blacklight Easter Egg

Goal: Hidden UV mode unlockable at night

Skills: frontend-design:frontend-design, ui-builder

6.1 Unlock Methods (7pm-6am only)

  1. Click hidden brass coin in image
  2. Type blacklight or uv in CLI
  3. Konami code: ↑↑↓↓←→←→BA

6.2 Visual Treatment

File: components/knolling/overlays/BlacklightOverlay.tsx

  • Dark UV filter (brightness 0.3, hue-rotate 240deg)
  • Neon glow elements (cyan #06B6D4, magenta #EC4899, purple #8B5CF6)
  • Hidden messages revealed with screen blend mode
  • 2s pulsing glow animation

6.3 Hook

File: hooks/useKonamiCode.ts

6.4 Phase 6 Deliverables

  • All three unlock methods working
  • Only available 7pm-6am local time
  • Hidden content revealed in blacklight mode
  • Smooth enter/exit transitions

Phase 7: Polish & Performance

Goal: Mobile refinement, accessibility, performance optimization

Skills: performance-optimization, testing-qa Subagents: performance-engineer, test-engineer Commands: /nextjs-vercel-pro:nextjs-performance-audit, /testing-suite:generate-tests

7.1 Performance

  • Lazy load overlay content
  • Preload critical images
  • GPU-accelerated animations only
  • Bundle analysis and optimization
  • Target: Lighthouse 90+ all metrics

7.2 Accessibility

  • Full keyboard navigation
  • Screen reader support (ARIA labels)
  • prefers-reduced-motion respect
  • Focus indicators on all interactive elements

7.3 Testing

  • Playwright E2E tests for all interactions
  • Visual regression tests for mode overlays
  • Cross-browser testing (Chrome, Safari, Firefox)

7.4 Phase 7 Deliverables

  • Lighthouse 90+ all categories
  • WCAG 2.1 AA compliant
  • E2E test coverage > 80%
  • Zero layout shift on mode transitions

File Structure

components/
├── knolling/
│   ├── KnollingCanvas.tsx
│   ├── HotspotLayer.tsx
│   ├── Hotspot.tsx
│   ├── TimeBasedLighting.tsx
│   ├── MobileKnollingView.tsx
│   └── overlays/
│       ├── BlueprintOverlay.tsx
│       ├── CinemaHUDOverlay.tsx
│       └── BlacklightOverlay.tsx
├── overlays/
│   ├── OverlayManager.tsx
│   └── ContentOverlay.tsx
├── terminal/
│   ├── CLITerminal.tsx
│   └── CommandInput.tsx
└── mode/
    └── ModeProvider.tsx

hooks/
├── useTimeOfDay.ts
├── useKonamiCode.ts
└── useHotspotInteraction.ts

lib/
├── hotspots.ts
└── terminal/
    ├── commands.ts
    └── parser.ts

public/knolling/
├── base-composite.webp
├── grain-texture.png
└── objects/
    ├── camera.png
    ├── laptop.png
    └── ...

content/personal/
├── bio.mdx
└── philosophy.mdx

Critical Files to Modify

  1. app/page.tsx - Complete replacement with KnollingCanvas
  2. components/theme/theme-provider.tsx - Extend to ModeProvider with tri-state
  3. app/globals.css - Add mode-specific styles, time-based filters
  4. hooks/use-theme.ts - Extend for mode state management

Files to Delete (after Phase 1)

  • components/theme/theme-toggle.tsx
  • components/theme/mode-selector.tsx
  • components/theme/circle-toggle.tsx

Execution Workflow

Phase Start
    │
    ├─► Invoke relevant Skill (frontend-design, ui-builder, etc.)
    │
    ├─► Build components with /nextjs-component-generator boilerplate
    │
    ├─► Test with Playwright MCP (browser_snapshot, browser_click)
    │
    ├─► Code review with code-reviewer subagent
    │
    ├─► Commit with /commit-commands:commit
    │
    └─► PR review with /pr-review-toolkit:review-pr

Success Criteria

  • Knolling photo loads and displays correctly
  • All 6 objects are clickable with appropriate actions
  • Mode toggle works (camera click)
  • Blueprint overlay renders in Personal mode
  • HUD overlay renders in Pro mode
  • Time-based lighting changes automatically
  • Content overlays open/close smoothly
  • CLI terminal functional with core commands
  • Blacklight easter egg works (night only)
  • Mobile adaptation provides full functionality
  • Lighthouse score 90+ all categories
  • WCAG 2.1 AA compliant