Menu
Guidelines for generating self-contained HTML mockups that look professional and are easy to iterate on.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Behavioral rules that make AI coding agents more reliable — verification, self-correction, and scope discipline.
Debugging guidance and structured report template for thorough bug investigation, evidence gathering, and root cause documentation.
Cold-audit a completed delivery — verify the spec was actually delivered, challenge performative claims, and produce a what-landed report.
Shared implementation guidance for making minimal, correct, maintainable code changes that fit existing systems.
The doctrine for `/roadmap-review` — interactive triage of roadmap-shape drift, walked one item at a time, with paste-ready resolution phrasing for the active sizing lens.
When work would produce 2+ related specs, prefer initiative-first composition over `/design` × N siblings. Carries the canonical "multiple related specs" phrasing that both interactive triage (`/roadmap-review`) and design-time routing (`/design`) quote.
| name | html-mockup-generation |
| description | Guidelines for generating self-contained HTML mockups that look professional and are easy to iterate on. |
Guidelines for generating self-contained HTML mockups that look professional and are easy to iterate on.
When this skill runs inside a subagent (the usual case via ui-designer or /mock), the subagent's narrative return text is not shown directly to the user — the orchestrator surfaces a parseable file list. The last thing the subagent emits MUST be a <MOCKUP_FILES> block listing every file written:
<MOCKUP_FILES>
.hero/mocks/{slug}/index.html|{Mockup name}|primary
.hero/planning/features/{slug}/spec.md|Spec (Mockups section updated)|spec
</MOCKUP_FILES>
One file per line, pipe-separated path|label|kind. Include every variant when generating multiple options in one run. Skip this block and the user sees no links. See the ui-designer agent definition for full rules.
Selection is now driven by hero spec mock detect (see hero spec mock detect --help). The agent does not decide — the CLI does. This skill is loaded whenever the detect output's renderer field is "html", which fires when no Swift signals are detected, when --renderer=html was explicit, when hero.json mockups.renderer: "html" overrides auto-detect, or as a fallback when Swift signals are present but swiftc is missing.
<!DOCTYPE html>
<!-- Hero Mock: {slug} | Generated: {date} -->
<!-- Description: {one-line description} -->
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{Title} — Mock</title>
<style>
/* All CSS here — no external stylesheets */
</style>
</head>
<body>
<!-- All markup here -->
<script>
/* All JS here — no external scripts */
</script>
</body>
</html>
Use these as defaults. Adjust per-project if the team has brand guidelines.
:root {
--bg: #ffffff;
--bg-secondary: #f8f9fa;
--bg-tertiary: #e9ecef;
--text: #212529;
--text-secondary: #6c757d;
--text-muted: #adb5bd;
--border: #dee2e6;
--primary: #4a9eff;
--primary-hover: #3a8eef;
--success: #28a745;
--warning: #ffc107;
--danger: #dc3545;
--info: #17a2b8;
--shadow: 0 1px 3px rgba(0,0,0,0.1);
--shadow-lg: 0 4px 12px rgba(0,0,0,0.15);
--radius: 6px;
--radius-lg: 12px;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
font-size: 14px;
line-height: 1.5;
color: var(--text);
background: var(--bg);
margin: 0;
padding: 0;
}
h1 { font-size: 24px; font-weight: 600; margin: 0 0 16px; }
h2 { font-size: 18px; font-weight: 600; margin: 0 0 12px; }
h3 { font-size: 16px; font-weight: 600; margin: 0 0 8px; }
Use multiples of 4px: 4, 8, 12, 16, 24, 32, 48, 64.
Buttons:
.btn {
display: inline-flex;
align-items: center;
gap: 6px;
padding: 8px 16px;
border-radius: var(--radius);
font-size: 14px;
font-weight: 500;
border: 1px solid var(--border);
background: var(--bg);
color: var(--text);
cursor: pointer;
transition: all 0.15s ease;
}
.btn-primary {
background: var(--primary);
color: white;
border-color: var(--primary);
}
.btn-primary:hover { background: var(--primary-hover); }
.btn-danger { background: var(--danger); color: white; border-color: var(--danger); }
Cards:
.card {
background: var(--bg);
border: 1px solid var(--border);
border-radius: var(--radius-lg);
padding: 24px;
box-shadow: var(--shadow);
}
Tables:
table { width: 100%; border-collapse: collapse; }
th, td { padding: 12px 16px; text-align: left; border-bottom: 1px solid var(--border); }
th { font-weight: 600; color: var(--text-secondary); font-size: 12px; text-transform: uppercase; letter-spacing: 0.5px; }
tr:hover { background: var(--bg-secondary); }
Forms:
.form-group { margin-bottom: 16px; }
.form-label { display: block; font-weight: 500; margin-bottom: 4px; font-size: 13px; }
.form-input {
width: 100%;
padding: 8px 12px;
border: 1px solid var(--border);
border-radius: var(--radius);
font-size: 14px;
box-sizing: border-box;
}
.form-input:focus { outline: none; border-color: var(--primary); box-shadow: 0 0 0 3px rgba(74,158,255,0.15); }
Badges/Tags:
.badge {
display: inline-block;
padding: 2px 8px;
border-radius: 12px;
font-size: 12px;
font-weight: 500;
}
.badge-success { background: #d4edda; color: #155724; }
.badge-warning { background: #fff3cd; color: #856404; }
.badge-danger { background: #f8d7da; color: #721c24; }
.badge-info { background: #d1ecf1; color: #0c5460; }
<div style="display: flex; min-height: 100vh;">
<nav style="width: 240px; background: var(--bg-secondary); border-right: 1px solid var(--border); padding: 24px 16px;">
<!-- sidebar nav -->
</nav>
<main style="flex: 1; padding: 32px;">
<!-- main content -->
</main>
</div>
<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 24px;">
<div class="card"><!-- metric card --></div>
<div class="card"><!-- metric card --></div>
<div class="card"><!-- metric card --></div>
</div>
<div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 24px;">
<div>
<h1>Page Title</h1>
<p style="color: var(--text-secondary); margin: 0;">Brief description</p>
</div>
<div style="display: flex; gap: 8px;">
<button class="btn">Secondary</button>
<button class="btn btn-primary">Primary Action</button>
</div>
</div>
Keep JS minimal. Common patterns:
Tab switching:
document.querySelectorAll('[data-tab]').forEach(tab => {
tab.addEventListener('click', () => {
document.querySelectorAll('[data-tab]').forEach(t => t.classList.remove('active'));
document.querySelectorAll('[data-panel]').forEach(p => p.style.display = 'none');
tab.classList.add('active');
document.querySelector(`[data-panel="${tab.dataset.tab}"]`).style.display = 'block';
});
});
Modal toggle:
function toggleModal(id) {
const modal = document.getElementById(id);
modal.style.display = modal.style.display === 'flex' ? 'none' : 'flex';
}
Dropdown:
function toggleDropdown(id) {
const dd = document.getElementById(id);
dd.style.display = dd.style.display === 'block' ? 'none' : 'block';
}
document.addEventListener('click', (e) => {
if (!e.target.closest('.dropdown')) {
document.querySelectorAll('.dropdown-menu').forEach(d => d.style.display = 'none');
}
});
Use realistic-looking placeholder data:
When invoked against a spec slug (not free-text), after saving the mockup, link it back from the originating spec so delivery agents can find it.
Locate the spec. Try in order:
.hero/planning/features/{slug}/spec.md.hero/planning/bugs/{slug}/spec.md.hero/specs/{slug}/spec.md (archive fallback)If a ## Mockups section does not exist, append one near the end of the spec body. Place it before ## Validation if that section exists; otherwise at the end of the file.
Add an entry in this format:
- [{Mockup name}](.hero/mocks/{slug}/index.html) — YYYY-MM-DD — one-line description of what the mockup shows
Hero landing page). Use something more specific when the spec has multiple mockups or iteration variants (e.g. Hero landing page — dense variant).On --iterate, match the existing entry by path. If the path is unchanged (the common case — overwriting index.html), update the date in place and rewrite the description only if the iteration meaningfully changed what's depicted. Don't append a duplicate row. If the iteration produces a new file (e.g. dense.html alongside index.html), append a new entry instead.
When /mock is invoked with free-text rather than a spec slug, there is no spec to write back to. Save the mockup under .hero/mocks/_adhoc/{kebab-case-summary}/index.html and skip the write-back step entirely. This keeps the .hero/mocks/ root clean — slug-keyed dirs match real specs; _adhoc/ clearly doesn't.