cuozg/html-prototype

HTML Prototype

Generate a complete, interactive app prototype as a single self-contained HTML file. The prototype should feel like a real app — smooth screen transitions, clickable navigation, realistic fake data, and polished visual design. Every screen the user needs, wired together with working navigation.

The output is always a single HTML file that opens in any browser. No build tools, no dependencies beyond CDN fonts. The user clicks buttons, navigates between screens, and experiences the app flow exactly as it would work in production — except the data is fake and the backend doesn't exist.

Supports two modes:

• App Prototype: Multi-screen app with navigation, transitions, and fake data (mobile or desktop)
• Landing Page: Single-scroll marketing site with sections, CTAs, and scroll animations

Workflow

1. Analyze the Concept

Extract from the user's description:

• App purpose: What problem does it solve? Who uses it?
• Product type: What industry/category? (fintech, health, SaaS, e-commerce, social, etc.)
• Prototype mode: Is this a multi-screen app or a landing page? If unclear, default to app prototype.
• Screen inventory: Every screen the app needs — don't skip secondary screens (settings, profile, empty states, error states, onboarding). For landing pages: every section needed.
• Navigation flow: How screens connect — which button leads where
• Key interactions: Forms, toggles, search, filters, swipe gestures
• Data model: What entities exist (users, posts, products, books, etc.)

If the description is vague, ask ONE clarifying question about the core use case. But err toward assumptions — prototypes thrive on reasonable defaults.

2. Design Intelligence — Choose the Visual System

Before mapping screens, determine the visual identity based on the product type. Read references/design-intelligence.md and look up the user's product category to get:

• Recommended visual style (Minimalism, Glassmorphism, Soft UI, Brutalism, etc.)
• Color palette with specific hex values matched to the industry
• Font pairing from Google Fonts that fits the app's personality
• Anti-patterns specific to this product type (what to avoid)
• Navigation pattern (bottom tabs, sidebar, top bar)

This step prevents the common failure of defaulting to generic blue/white for every prototype. A fintech app should feel different from a wellness app — the design intelligence reference encodes those differences.

If the product type doesn't match any category exactly, pick the closest one and adapt.

3. Map the Screens

Before writing HTML, map every screen. Each screen needs:

| Field | Description | |-------|-------------| | ID | Machine name: login, dashboard, book-detail | | Title | Human-readable name | | Components | What's on the screen: nav bar, card list, form, fab button | | Entry points | Which screens navigate TO this one | | Exit points | Which screens this one navigates TO | | Data | What fake data this screen displays |

Read references/app-archetypes.md for common app types and their typical screen maps. This saves time — most apps share patterns (auth flow → home → list → detail → settings). For landing pages, read references/landing-patterns.md instead.

4. Apply the Visual Direction

With the design intelligence recommendations in hand, make the final visual decisions. Read references/css-system.md for CSS implementations of each style.

Decisions already made by design intelligence (step 2):

• Color palette (use the hex values from the lookup)
• Font pairing (use the Google Fonts from the lookup)
• Visual style (Minimalism, Glassmorphism, etc.)

Decisions still needed:

1. Layout frame — Mobile-first (390px viewport, bottom tab bar) or desktop-first (sidebar nav, wide content area). For landing pages: always desktop-first with responsive stacking.
2. Transition style — Default: slide-left forward, slide-right back, fade for tabs, slide-up for modals. For landing pages: scroll-triggered fade-in.

5. Generate the Prototype

Read templates/spa-shell.html first — it's a complete working BookShelf app that demonstrates every pattern. Use it as your reference architecture. Don't copy it verbatim; adapt its router, transitions, and data patterns for the user's app.

Architecture overview:

┌─ <section class="screen" data-screen="screen-id"> ─── one per screen
│   Full-viewport content with its own layout
└─ JavaScript router handles hash-based navigation
   CSS transitions animate between screens
   APP_DATA object holds all fake data
   APP_STATE object holds auth and UI state

Key implementation patterns (all demonstrated in the template):

• SVG Icons: Define a const SVG = { home: '...', search: '...', back: '...' } object with inline SVG strings for all icons. Never use emoji.
• Screen Hooks: Use a SCREEN_HOOKS object mapping screen IDs to render functions. The router calls the hook when a screen becomes active, so content is populated dynamically from APP_DATA.
• Transition Trick: After adding the enter class, call element.offsetHeight to force a reflow before adding .active. Without this, CSS transitions won't animate — the browser batches the class changes.
• Tab Bar: Render the tab bar inside each tabbed screen (not globally), so it travels with the screen during transitions. Use a shared renderTabBar() function.

The prototype MUST include:

• Every screen from the screen map — no shortcuts
• Working navigation between every connected screen pair
• Smooth CSS transition animations (300-400ms, ease-out curves)
• Responsive layout that works at 390px (mobile) and 1200px+ (desktop)
• Light/dark mode via prefers-color-scheme
• Status bar or navigation chrome appropriate to the app type
• Realistic fake data — real names, real dates, real numbers (never "Lorem ipsum" or "Test User")
• Interactive form elements — inputs accept text, toggles switch visually, dropdowns open
• Loading/empty states where appropriate

6. Deliver

Output location: Save to ~/.agent/prototypes/ with a descriptive filename based on the app concept: book-reader-app.html, fitness-tracker.html, recipe-manager.html.

Open in browser:

• macOS: open ~/.agent/prototypes/filename.html
• Linux: xdg-open ~/.agent/prototypes/filename.html

Tell the user the file path so they can re-open, share, or iterate.

---

Screen Transition System

The router supports directional transitions that feel natural — forward navigation pushes content left, back navigation pulls it right, modals slide up from the bottom.

| Transition | When to use | Feel | |-----------|-------------|------| | slide-left | Navigate deeper (list → detail, home → subpage) | Moving forward | | slide-right | Navigate back (detail → list, subpage → home) | Returning | | slide-up | Open modal, bottom sheet, overlay | Revealing | | slide-down | Close modal, dismiss overlay | Dismissing | | fade | Switch tabs, same-level navigation | Lateral movement | | scale-up | Open detail from card (zoom into content) | Focusing | | none | Initial load, auth redirect | Instant |

The router tracks navigation history to automatically choose forward vs. back transitions. Explicitly set transitions for modals and special cases.

Timing: 300ms for screen transitions, 150ms for micro-interactions (button press, toggle). Use cubic-bezier(0.4, 0, 0.2, 1) for natural deceleration.

---

Fake Data & Auth

Auth flow: Use APP_STATE.isLoggedIn boolean. The login screen validates that both fields are non-empty (no real validation), sets isLoggedIn = true, and navigates forward. Protected screens check the flag on entry and redirect to login if false. A logout button resets the flag and navigates to login.

Generating realistic fake data is critical — the prototype should look like a screenshot of a real app. Guidelines by domain:

| Domain | Examples | |--------|----------| | Books | "The Great Gatsby" by F. Scott Fitzgerald, 4.2★, 218 pages | | E-commerce | "Wireless Noise-Cancelling Headphones" — $149.99, 4.7★ (2,341 reviews) | | Social | "Sarah Chen" posted 2h ago, 47 likes, 12 comments | | Fitness | 8,432 steps today, 3.2 km, 247 cal burned | | Finance | Checking ••••4829: $3,247.50, +$1,200.00 on Mar 15 | | Food/Recipe | "Spicy Thai Basil Chicken" — 25 min, 4 servings, 380 cal | | Productivity | "Q2 Marketing Plan" — 3/7 tasks done, due Apr 15, assigned to Alex |

Store data in const APP_DATA = { ... } at the top of the script section. Components read from this object to render lists, cards, and detail views.

---

Visual Design Principles

The goal is an app that looks designed, not generated. A real designer would never ship flat gray cards with Inter font and purple accents — so neither should this skill.

Typography

Pick a font pairing that matches the app's personality. Load via Google Fonts CDN.

Recommended pairings:

• Professional/Finance: Inter + JetBrains Mono (yes, Inter is fine for apps — it's overused in diagrams, not in app UIs)
• Editorial/Reading: Merriweather + Source Sans 3 (serif body for reading apps)
• Modern/Social: Plus Jakarta Sans + DM Mono (rounded, friendly)
• Bold/E-commerce: Bricolage Grotesque + Space Mono (characterful, punchy)
• Clean/Productivity: DM Sans + Fira Code (precise, reliable)
• Playful/Lifestyle: Nunito + Space Mono (soft, approachable)

Color

Build the palette from the app's domain, not from defaults. Use CSS custom properties for everything.

Curated app palettes:

| Name | Primary | Accent | Surface | Use for | |------|---------|--------|---------|---------| | Ocean | #0c4a6e | #0ea5e9 | #f0f9ff | Finance, productivity, professional | | Forest | #14532d | #22c55e | #f0fdf4 | Health, fitness, nature | | Sunset | #7c2d12 | #f97316 | #fff7ed | Food, social, lifestyle | | Berry | #581c87 | #a855f7 | #faf5ff | Creative, music, entertainment | | Slate | #1e293b | #64748b | #f8fafc | Minimal, tools, developer | | Rose | #881337 | #f43f5e | #fff1f2 | Shopping, fashion, dating |

Always define both light and dark variants via prefers-color-scheme.

Micro-interactions

Small animations that make the prototype feel alive:

• Button press: transform: scale(0.97) on :active, 100ms transition
• Card tap: Subtle shadow lift on hover/active
• Toggle switch: Smooth slide with background color change
• Screen entrance: Staggered fade-in for list items using --i CSS variable
• Pull-to-refresh indicator: Rotating spinner (CSS only)
• Floating action button: Scale-in on screen enter, pulse shadow on hover

Anti-Slop Rules

These patterns signal "AI made this" — avoid them:

• Neon dashboard aesthetic (cyan + magenta + purple on dark background)
• Gradient text on headings
• Animated glowing box-shadows
• Emoji as navigation icons (use inline SVG or CSS shapes instead)
• Uniform card grid where every card has identical styling
• "Lorem ipsum" or "Test User 1" placeholder text
• Perfectly symmetrical layouts with no visual hierarchy
• Three-dot window chrome on any element

---

File Structure

Every prototype is a single self-contained .html file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
  <title>App Name — Prototype</title>
  <link href="https://fonts.googleapis.com/css2?family=...&display=swap" rel="stylesheet">
  <style>
    /* CSS custom properties, themes, screen layouts, transitions, components */
  </style>
</head>
<body>
  <div id="app">
    <section class="screen" data-screen="splash">...</section>
    <section class="screen" data-screen="login">...</section>
    <section class="screen" data-screen="home">...</section>
    <!-- More screens -->
  </div>

  <script>
    // APP_DATA — all fake data
    // APP_STATE — auth, selections, UI state
    // Router — hash-based navigation with transition support
    // Screen init functions — populate screens from APP_DATA
    // Event handlers — button clicks, form submits, toggles
  </script>
</body>
</html>

---

Quality Checks

Before delivering, run through references/ux-checklist.md for the full checklist. At minimum, verify:

• [ ] Every screen from the screen map is present and reachable
• [ ] Every navigation path works — click button → correct screen with smooth transition
• [ ] Back navigation works — browser back button or in-app back arrows
• [ ] Fake auth works — login with any non-empty fields, protected screens redirect, logout works
• [ ] Fake data looks real — no placeholders, no "Lorem ipsum"
• [ ] Forms are interactive — text inputs accept typing, toggles switch visually, dropdowns open
• [ ] Transitions are smooth — no flicker, no layout jump, correct direction (forward=slide-left, back=slide-right)
• [ ] Mobile layout — works at 375px width with touch-friendly targets (44px minimum)
• [ ] Desktop layout — uses the extra space well (wider cards, sidebar nav, multi-column)
• [ ] Both themes — light and dark mode both look intentional, not broken
• [ ] Self-contained — opens cleanly with no console errors, no broken fonts
• [ ] No emoji icons — all icons use inline SVG, never emoji characters
• [ ] Cursor pointer — every clickable element has cursor:pointer
• [ ] Hover states — all interactive elements respond to hover with smooth transition
• [ ] Design coherence — palette, typography, and style match the product type (use design intelligence reference)
• [ ] File is saved to ~/.agent/prototypes/ and opened in browser

---

References

Load on demand — don't read all at once:

• references/design-intelligence.md — Industry-to-design mapping: 30+ product types with recommended style, palette, typography, anti-patterns, and navigation patterns. Read this first when building any prototype to make informed design decisions.
• references/css-system.md — Full design system: CSS variables, theme setup, visual styles (glassmorphism, neumorphism, brutalism, bento grid, aurora), extended palettes (20+ industry-specific), transition CSS, component patterns, responsive breakpoints, scroll animations
• references/screen-patterns.md — HTML/CSS patterns for common app screens: auth, dashboard, list/detail, settings, onboarding, modals, empty states
• references/app-archetypes.md — Screen maps for common app types: what screens each type needs, navigation flows, data models. Covers 13 types including SaaS dashboards and landing pages.
• references/landing-patterns.md — HTML/CSS patterns for landing page sections: hero variants, feature grids, testimonials, pricing tables, FAQ accordions, CTA sections, footers, scroll animations
• references/ux-checklist.md — Pre-delivery UX quality checklist: accessibility, touch targets, hover states, transitions, form patterns. Run through this before delivering any prototype.

Load via read_skill_file("html-prototype", "references/<file>").

The template at templates/spa-shell.html is a complete working example demonstrating all patterns. Read it as a reference architecture — don't copy it verbatim, but follow its router pattern and transition system.

Escalation

| From | To | When | |------|----|------| | html-prototype | flutter-code + flutter-ui | User wants to build the real app in Flutter | | html-prototype | nextjs-backend | User wants to build the actual backend | | html-prototype | visual-explainer | User needs a static diagram, not an interactive app | | html-prototype | frontend-design | User wants production-quality frontend code | | html-prototype | phaser-coder | User wants a game prototype | | html-prototype | unity-prototype | User wants a Unity game prototype |