design-mockups

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

# 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:

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('/',  {
   mockups = fs.()
    .( f.())
    .( {
       slug = f.(, );
       meta = mockupMeta[slug] || { : [, , , ], :  };
       { : slug.(, ), : f, : , : meta., : meta. };
    });

  res.();
});

app.(, ,  .());

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:

// 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:

:root {
  --bg: #0d120d;
  --text: #6b8c5a;
  --accent: #9DFF20;
  --muted: #3d5a30;
}

Common Effects

CRT Scanlines:

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:

.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