--- name: design-mockups description: Build and present HTML/CSS design mockups with a local preview server. Use when prototyping website designs, iterating on visual concepts, or presenting design options. --- # Design Mockups Rapidly prototype and present HTML/CSS design mockups with a local server. ## Design Phases Design work moves through distinct phases. **Know which phase you're in.** ### Phase 1: Style Exploration **Goal:** Find the right visual direction for the entire site. Create multiple concepts with different aesthetics (terminal, minimal, brutalist, etc.). Each mockup is a complete style — colors, typography, effects, vibe. **Location:** `mockups/*.html` (root level) ``` mockups/ ├── retro-terminal.html # Concept A ├── minimal-stark.html # Concept B ├── warm-organic.html # Concept C └── brutalist-chaos.html # Concept D ``` **Outcome:** Pick a winner (e.g., `terminal-minimal-v2`). --- ### Phase 2: Site Templates **Goal:** Build out all page types in the chosen style. Create a subfolder named after the chosen direction. Build every major page template with shared styles. **Location:** `mockups/{chosen-direction}/` ``` mockups/ ├── terminal-v2-site/ # ← Chosen direction │ ├── styles.css # Shared design system │ ├── home.html │ ├── post.html │ ├── about.html │ ├── project.html │ ├── archive.html │ ├── search.html │ └── 404.html ``` **Outcome:** Complete set of page templates. --- ### Phase 3: Section Explorations **Goal:** Iterate on specific components or sections within the chosen style. When a section needs multiple approaches (e.g., "how should projects be listed?"), create explorations inside the chosen direction folder. **Location:** `mockups/{chosen-direction}/` with descriptive names **Naming convention:** `{section}-{variant}.html` ``` mockups/ ├── terminal-v2-site/ │ ├── styles.css │ ├── home.html │ ├── projects-grid.html # Section exploration │ ├── projects-file-tree.html # Section exploration │ ├── projects-file-tree-v2.html # Iteration on exploration │ └── projects-hybrid.html # Section exploration ``` **Outcome:** Pick the best approach for each section, integrate into templates. --- ## Project Structure ``` {project-name}/ ├── mockups/ │ ├── concept-a.html # Phase 1: Style exploration │ ├── concept-b.html │ ├── concept-c.html │ └── {chosen-direction}/ # Phase 2+3: Templates & explorations │ ├── styles.css # Shared design system │ ├── home.html # Page template │ ├── post.html # Page template │ ├── {section}-v1.html # Section exploration │ └── {section}-v2.html # Section iteration ├── docs/ │ └── logs/ # Session notes ├── server.js ├── package.json └── README.md ``` ## Quick Start ```bash # Reserve a port first portman reserve 3000 --name "{project-name}" --desc "Design mockups" # Create project mkdir -p ~/Developer/Projects/{project-name} cd ~/Developer/Projects/{project-name} mkdir -p mockups docs/logs # Initialize npm init -y npm install express # Copy server template (below) npm start ``` ## Server Template Save as `server.js` — serves mockups with a gallery UI: ```javascript const express = require('express'); const fs = require('fs'); const path = require('path'); const os = require('os'); const app = express(); const PORT = 3000; const MOCKUPS_DIR = path.join(__dirname, 'mockups'); app.use('/mockups', express.static(MOCKUPS_DIR)); function getLocalIP() { const interfaces = os.networkInterfaces(); for (const name of Object.keys(interfaces)) { for (const iface of interfaces[name]) { if (iface.family === 'IPv4' && !iface.internal) { return iface.address; } } } return 'localhost'; } const mockupMeta = { // 'filename-without-extension': { colors: ['#hex1', '#hex2'], desc: 'Description' } }; app.get('/', (req, res) => { const mockups = fs.readdirSync(MOCKUPS_DIR) .filter(f => f.endsWith('.html')) .map(f => { const slug = f.replace('.html', ''); const meta = mockupMeta[slug] || { colors: ['#ccc', '#999', '#666', '#333'], desc: '' }; return { name: slug.replace(/-/g, ' '), file: f, path: `/mockups/${f}`, colors: meta.colors, desc: meta.desc }; }); res.send(` Mockups

Design Mockups

${mockups.map(m => `
${m.colors.map(c => `
`).join('')}
${m.name}
${m.desc}
`).join('')}
Local: http://localhost:${PORT} · Network: http://${getLocalIP()}:${PORT}
`); }); app.listen(PORT, '0.0.0.0', () => console.log(`Mockup server: http://localhost:${PORT} | http://${getLocalIP()}:${PORT}`)); ``` ## Naming Conventions | Phase | Pattern | Example | |-------|---------|---------| | Style exploration | `{style-name}.html` | `retro-terminal.html` | | Style iteration | `{style-name}-v2.html` | `terminal-minimal-v2.html` | | Page template | `{page-type}.html` | `post.html`, `about.html` | | Section exploration | `{section}-{variant}.html` | `projects-file-tree.html` | | Section iteration | `{section}-{variant}-v2.html` | `projects-file-tree-v2.html` | ## Workflow Rules 1. **Know your phase** — Don't put section explorations in the root mockups folder 2. **Never overwrite** — Create new files for iterations (`-v2`, `-v3`) 3. **Shared styles in Phase 2+** — Use a `styles.css` for the chosen direction 4. **Document decisions** — Log sessions in `docs/logs/` 5. **Check port before answering** — `portman check {port}` to verify server state 6. **Update the index** — When adding/moving mockups, update `server.js` listings 7. **Restart after changes** — Kill and restart the server after updating `server.js` ## Updating the Gallery Index The `server.js` file contains arrays that define what appears in the gallery: ```javascript // Page templates in the chosen direction const terminalV2Pages = [ { name: 'Home', file: 'home.html', desc: 'Homepage with recent posts' }, // ... add new pages here ]; // Section explorations const projectsExplorations = [ { name: 'File Tree', file: 'projects-file-tree.html', desc: 'ls -la style' }, { name: 'File Tree v2', file: 'projects-file-tree-v2.html', desc: 'With icons' }, // ... add new explorations here ]; ``` **When you add a mockup:** 1. Create the HTML file in the correct location 2. Add an entry to the appropriate array in `server.js` 3. Restart the server: kill the process, run `npm start` **When you move mockups:** 1. Move the files 2. Update the paths in `server.js` (e.g., `/mockups/terminal-v2-site/...`) 3. Restart the server ## Mockup Best Practices ### Phase 1 Mockups (Style Exploration) - Self-contained HTML with embedded CSS - Show the full vibe: colors, typography, effects - Include enough content to judge the aesthetic - No external dependencies (except fonts) ### Phase 2+ Mockups (Templates & Sections) - Link to shared `styles.css` - Focus on layout and content structure - Real-ish content (not lorem ipsum if possible) - Mobile-responsive ### Color Palette Define 4-5 key colors: ```css :root { --bg: #0d120d; --text: #6b8c5a; --accent: #9DFF20; --muted: #3d5a30; } ``` ### Common Effects **CRT Scanlines:** ```css body::before { content: ''; position: fixed; inset: 0; background: repeating-linear-gradient(0deg, rgba(0,0,0,0.15), rgba(0,0,0,0.15) 1px, transparent 1px, transparent 2px); pointer-events: none; z-index: 1000; } ``` **Blinking Cursor:** ```css .cursor { display: inline-block; width: 0.6em; height: 1em; background: var(--accent); animation: blink 1s step-end infinite; } @keyframes blink { 0%, 50% { opacity: 1; } 51%, 100% { opacity: 0; } } ``` ## Tips - **Iterate fast** — Don't perfect, explore - **Test on phone** — Use network URL - **Commit often** — Git tracks your exploration - **Reserve ports** — Use `portman` to avoid conflicts - **Update README** — Keep project docs current with the chosen direction