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:
components/knolling/KnollingCanvas.tsx- Desktop container with image + hotspotscomponents/knolling/HotspotLayer.tsx- SVG overlay with clickable regionscomponents/knolling/Hotspot.tsx- Individual hotspot with hover/focus statescomponents/knolling/MobileKnollingView.tsx- Card grid for viewport < 768pxcomponents/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:
components/overlays/OverlayManager.tsx- Portal container with AnimatePresencecomponents/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:
components/knolling/overlays/BlueprintOverlay.tsx- Orange graph paper grid (SVG pattern, 10% opacity)
- Hand-drawn annotation lines to hotspots
- Monospace labels, dotted dimension lines
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:
- Blur to 12px, scale 1.05 (0.6s)
- Old overlay fades, new begins (0.6s)
- 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:
components/terminal/CLITerminal.tsx- Draggable terminal windowcomponents/terminal/CommandInput.tsx- Input with historylib/terminal/commands.ts- Command definitionslib/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)
- Click hidden brass coin in image
- Type
blacklightoruvin CLI - 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-motionrespect- 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
app/page.tsx- Complete replacement with KnollingCanvascomponents/theme/theme-provider.tsx- Extend to ModeProvider with tri-stateapp/globals.css- Add mode-specific styles, time-based filtershooks/use-theme.ts- Extend for mode state management
Files to Delete (after Phase 1)
components/theme/theme-toggle.tsxcomponents/theme/mode-selector.tsxcomponents/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