mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-17 16:46:31 +03:00
Paul BakausandClaude Fable 5
90f9eeb99b
The public repo keeps the OSS promise surface: skill, CLI, extension, tests, and the provider build. The site, labs, concept/composition catalogs, image pipeline, Cloudflare functions, and authoring guide move to pbakaus/impeccable-site. concept-seed tests run against a synthetic fixture catalog; the plugin icon and skill categories moved in-repo; build validation narrows to README prose and non-site counts; release notes read from a sibling impeccable-site checkout. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
519 lines
35 KiB
HTML
519 lines
35 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>/impeccable craft | Impeccable</title>
|
|
<meta name="description" content="Shape the design, then build it, all in one flow.">
|
|
<meta name="theme-color" content="#fafafa">
|
|
<link rel="canonical" href="https://impeccable.style/docs/craft">
|
|
<link rel="icon" type="image/svg+xml" href="../favicon.svg">
|
|
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
<link href="https://fonts.googleapis.com/css2?family=Cormorant+Garamond:ital,wght@0,400;0,600;1,400&family=Instrument+Sans:wght@400;500;600;700&family=Space+Grotesk:wght@400;500;600&display=swap" rel="stylesheet">
|
|
<link rel="stylesheet" href="../css/sub-pages.css">
|
|
|
|
</head>
|
|
<body class="sub-page skills-layout-page">
|
|
<a href="#main" class="skip-link">Skip to content</a>
|
|
<!-- site-header v1 -->
|
|
<header class="site-header" data-site-header>
|
|
<a href="/" class="site-header-brand" aria-label="Impeccable home">
|
|
<svg class="site-header-brand-logo" viewBox="0 0 32 32" aria-hidden="true"><rect width="32" height="32" rx="6" fill="#1a1a1a"/><text x="16" y="24" font-family="system-ui, -apple-system, sans-serif" font-size="22" font-weight="500" fill="#f5f3ef" text-anchor="middle">/</text></svg>
|
|
<span class="site-header-brand-name">Impeccable</span>
|
|
</a>
|
|
<div class="site-header-right">
|
|
<nav class="site-header-nav" aria-label="Primary">
|
|
<a href="/" data-nav="home">Home</a>
|
|
<a href="/designing" data-nav="designing">Designing</a>
|
|
<a href="/docs" data-nav="docs" aria-current="page">Docs</a>
|
|
<a href="/slop" data-nav="slop">Slop</a>
|
|
<a href="/live-mode" data-nav="live">Live</a>
|
|
</nav>
|
|
<a href="https://github.com/pbakaus/impeccable" class="site-header-github" target="_blank" rel="noopener" aria-label="Impeccable on GitHub, 21k stars">
|
|
<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z"/></svg>
|
|
<span class="site-header-github-label">21k</span>
|
|
<svg class="site-header-github-star" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M12 2l2.76 6.36L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l7.24-.91L12 2z"/></svg>
|
|
</a>
|
|
</div>
|
|
</header>
|
|
<main id="main">
|
|
|
|
<div class="skills-layout">
|
|
|
|
<aside class="skills-sidebar" aria-label="Documentation">
|
|
<button class="skills-sidebar-toggle" type="button" aria-expanded="false" aria-controls="skills-sidebar-inner">
|
|
<span class="skills-sidebar-toggle-label">/craft</span>
|
|
<svg class="skills-sidebar-toggle-chevron" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" aria-hidden="true"><path d="M6 9l6 6 6-6"/></svg>
|
|
</button>
|
|
<div class="skills-sidebar-inner" id="skills-sidebar-inner">
|
|
<p class="skills-sidebar-label">Docs</p>
|
|
|
|
<div class="skills-sidebar-group" data-category="tutorials">
|
|
<p class="skills-sidebar-group-title">Tutorials</p>
|
|
<ul class="skills-sidebar-list">
|
|
<li><a href="/tutorials/getting-started">Getting started</a></li>
|
|
<li><a href="/tutorials/iterate-live">Iterate on UI with Live Mode</a></li>
|
|
<li><a href="/tutorials/brand-vs-product">Brand vs product, pick a register</a></li>
|
|
<li><a href="/tutorials/critique-with-overlay">Critique with the visual overlay</a></li>
|
|
</ul>
|
|
</div>
|
|
<hr class="skills-sidebar-divider">
|
|
|
|
<div class="skills-sidebar-group" data-category="create">
|
|
<p class="skills-sidebar-group-title">Create</p>
|
|
<ul class="skills-sidebar-list">
|
|
<li><a href="/docs/impeccable">/impeccable</a></li>
|
|
<li><a href="/docs/craft" aria-current="page">craft</a></li>
|
|
<li><a href="/docs/shape">shape</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="skills-sidebar-group" data-category="evaluate">
|
|
<p class="skills-sidebar-group-title">Evaluate</p>
|
|
<ul class="skills-sidebar-list">
|
|
<li><a href="/docs/audit">audit</a></li>
|
|
<li><a href="/docs/critique">critique</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="skills-sidebar-group" data-category="refine">
|
|
<p class="skills-sidebar-group-title">Refine</p>
|
|
<ul class="skills-sidebar-list">
|
|
<li><a href="/docs/animate">animate</a></li>
|
|
<li><a href="/docs/bolder">bolder</a></li>
|
|
<li><a href="/docs/colorize">colorize</a></li>
|
|
<li><a href="/docs/delight">delight</a></li>
|
|
<li><a href="/docs/layout">layout</a></li>
|
|
<li><a href="/docs/overdrive">overdrive</a></li>
|
|
<li><a href="/docs/quieter">quieter</a></li>
|
|
<li><a href="/docs/typeset">typeset</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="skills-sidebar-group" data-category="simplify">
|
|
<p class="skills-sidebar-group-title">Simplify</p>
|
|
<ul class="skills-sidebar-list">
|
|
<li><a href="/docs/adapt">adapt</a></li>
|
|
<li><a href="/docs/clarify">clarify</a></li>
|
|
<li><a href="/docs/distill">distill</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="skills-sidebar-group" data-category="harden">
|
|
<p class="skills-sidebar-group-title">Harden</p>
|
|
<ul class="skills-sidebar-list">
|
|
<li><a href="/docs/harden">harden</a></li>
|
|
<li><a href="/docs/onboard">onboard</a></li>
|
|
<li><a href="/docs/optimize">optimize</a></li>
|
|
<li><a href="/docs/polish">polish</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="skills-sidebar-group" data-category="system">
|
|
<p class="skills-sidebar-group-title">System</p>
|
|
<ul class="skills-sidebar-list">
|
|
<li><a href="/docs/document">document</a></li>
|
|
<li><a href="/docs/extract">extract</a></li>
|
|
<li><a href="/docs/live">live</a></li>
|
|
<li><a href="/docs/teach">teach</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
</div>
|
|
</aside>
|
|
<div class="skills-main">
|
|
|
|
<article class="skill-detail">
|
|
<div class="skill-detail-hero">
|
|
<header class="skill-detail-header">
|
|
<p class="skill-detail-eyebrow"><a href="/docs">Docs</a> / Create</p>
|
|
<h1 class="skill-detail-title"><span class="skill-detail-title-namespace"><span class="skill-detail-title-slash">/</span>impeccable</span>craft</h1>
|
|
<p class="skill-detail-tagline">Shape the design, then build it, all in one flow.</p>
|
|
|
|
<div class="skill-meta-strip">
|
|
<span class="skill-meta-chip skill-meta-category" data-category="create">Create</span>
|
|
<span class="skill-meta-chip">User-invocable</span>
|
|
<span class="skill-meta-chip skill-meta-args">[feature description]</span>
|
|
</div>
|
|
</header>
|
|
|
|
</div>
|
|
|
|
<section class="skill-detail-editorial prose">
|
|
<div class="docs-viz-hero">
|
|
<div class="docs-viz-flow">
|
|
<div class="docs-viz-flow-step">
|
|
<span class="docs-viz-flow-num">01</span>
|
|
<span class="docs-viz-flow-name">Shape</span>
|
|
<span class="docs-viz-flow-hint">Discovery interview. Purpose, users, constraints, direction.</span>
|
|
</div>
|
|
<div class="docs-viz-flow-step">
|
|
<span class="docs-viz-flow-num">02</span>
|
|
<span class="docs-viz-flow-name">Load references</span>
|
|
<span class="docs-viz-flow-hint">Spatial, typography, motion, color, interaction.</span>
|
|
</div>
|
|
<div class="docs-viz-flow-step">
|
|
<span class="docs-viz-flow-num">03</span>
|
|
<span class="docs-viz-flow-name">Build</span>
|
|
<span class="docs-viz-flow-hint">Structure, hierarchy, type, color, states, motion, responsive.</span>
|
|
</div>
|
|
<div class="docs-viz-flow-step docs-viz-flow-step--accent">
|
|
<span class="docs-viz-flow-num">04</span>
|
|
<span class="docs-viz-flow-name">Iterate visually</span>
|
|
<span class="docs-viz-flow-hint">Check in browser, refine until it matches the brief.</span>
|
|
</div>
|
|
</div>
|
|
<p class="docs-viz-caption">Every phase is non-skippable. The discovery step is where most AI output fails: by the time code exists, the thinking is locked in.</p>
|
|
</div>
|
|
|
|
<h2 id="when-to-use-it">When to use it</h2>
|
|
<p><code>/impeccable craft</code> is the end-to-end build command. Give it a feature description and it runs the whole pipeline: structured discovery, reference loading, implementation, visual iteration. Use it when you are starting a new feature from zero and want the whole workflow in one invocation.</p>
|
|
<p>Reach for it when:</p>
|
|
<ul>
|
|
<li><strong>You are building a new feature and want the full flow.</strong> You do not want to manage the steps yourself.</li>
|
|
<li><strong>You know what you are building but not how it should look.</strong> The discovery phase forces the design thinking before implementation locks it in.</li>
|
|
<li><strong>You want visual iteration by default.</strong> <code>craft</code> checks the result in a browser and refines until the polish is high, instead of shipping the first working version.</li>
|
|
</ul>
|
|
<p>If you only want the thinking without the code, use <code>/impeccable shape</code> standalone. If you already have a clear vision and just want to build, call <code>/impeccable</code> directly with your feature description. <code>craft</code> sits in between: structured, complete, opinionated.</p>
|
|
<h2 id="how-it-works">How it works</h2>
|
|
<p><code>craft</code> runs four phases in order:</p>
|
|
<ol>
|
|
<li><strong>Shape the design.</strong> Runs <code>/impeccable shape</code> internally: a short discovery conversation about purpose, users, content, constraints, and goals. The output is a design brief you can read and push back on.</li>
|
|
<li><strong>Load references.</strong> Based on the brief, pulls in the right reference files (spatial, typography, motion, color, interaction, responsive, UX writing) so the model has the relevant principles loaded before it starts coding.</li>
|
|
<li><strong>Build.</strong> Implements the feature in a deliberate order: structure first, then spacing and hierarchy, then type and color, then states, then motion, then responsive. Every decision traces back to the brief.</li>
|
|
<li><strong>Visual iteration.</strong> Opens the result in a browser, checks it against the brief and the anti-pattern catalog, and refines until it matches the intent. This step is critical. The first working version is never the shipped version.</li>
|
|
</ol>
|
|
<p>The discovery phase is non-skippable and that is the point. Most AI-generated UIs fail because nobody asked what the user was trying to accomplish before the model started writing JSX. <code>craft</code> inverts that.</p>
|
|
<h2 id="try-it">Try it</h2>
|
|
<div class="code-block-wrap"><pre class="code-block"><code>/impeccable craft a pricing page for a developer tool</code></pre><button class="code-block-copy" type="button" data-copy="/impeccable craft a pricing page for a developer tool" aria-label="Copy to clipboard"></button></div>
|
|
<p>Expect a 5 to 10 question discovery interview first. Questions about your audience, the product's personality, the emotional tone you want, anti-references, and constraints. Then a design brief. Then implementation, with the browser checked at each stage. Expect multiple iteration rounds in the visual polish phase.</p>
|
|
<p>The whole run is longer than a typical command because it includes the thinking, the building, and the refining. That is the trade: more upfront structure, less cleanup afterwards.</p>
|
|
<h2 id="pitfalls">Pitfalls</h2>
|
|
<ul>
|
|
<li><strong>Using it for small changes.</strong> <code>craft</code> is for new features, not touch-ups. For existing code, reach for <code>/impeccable polish</code>, <code>/impeccable critique</code>, or a specific refinement command instead.</li>
|
|
<li><strong>Rushing the discovery phase.</strong> The interview feels slow compared to "just start coding". It is not. Answering the questions carefully produces a sharper brief, which produces a sharper build, which produces fewer rewrites.</li>
|
|
<li><strong>Skipping the visual iteration.</strong> The phase exists for a reason. The gap between "technically works" and "feels right" is closed with visual polish, not code review. Let it run.</li>
|
|
</ul>
|
|
|
|
</section>
|
|
|
|
|
|
<aside class="craft-case-callout" aria-labelledby="craft-case-title">
|
|
<div class="craft-case-copy">
|
|
<span class="craft-case-eyebrow">Real example</span>
|
|
<h2 id="craft-case-title">Neo Mirai: generated reference to shipped page.</h2>
|
|
<p>A retro-futurist AI design conference moved through the full loop: brand toolkit, hi-fi mock, semantic implementation, regenerated assets, responsive fixes, and browser polish.</p>
|
|
<div class="code-block-wrap craft-case-command">
|
|
<pre class="code-block code-block--bash"><code>npx impeccable craft retro-futurist AI design conference website</code></pre>
|
|
<button class="code-block-copy" type="button" data-copy="npx impeccable craft retro-futurist AI design conference website" aria-label="Copy to clipboard"></button>
|
|
</div>
|
|
<p class="craft-case-link-row">
|
|
<a href="/cases/neo-mirai">Read the case</a>
|
|
<a href="/neo-mirai/">Open the build</a>
|
|
</p>
|
|
</div>
|
|
<div class="craft-case-images" aria-hidden="true">
|
|
<img src="../assets/openai_image_2_hifi.jpg" alt="" loading="lazy" width="864" height="1821" />
|
|
<img src="../assets/cases/neo-mirai/home.png" alt="" loading="lazy" width="1440" height="1100" />
|
|
</div>
|
|
</aside>
|
|
|
|
<section class="skill-source-card">
|
|
<header class="skill-source-card-header">
|
|
<span class="skill-source-card-label">reference/craft.md</span>
|
|
<span class="skill-source-card-subtitle">Loaded when the impeccable skill routes to this command.</span>
|
|
</header>
|
|
<div class="skill-source-card-body prose">
|
|
<h1 id="craft-flow">Craft Flow</h1>
|
|
<p>Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar.</p>
|
|
<h2 id="build-gate">Build Gate</h2>
|
|
<p>Craft cannot build until all of these are true:</p>
|
|
<ol>
|
|
<li>PRODUCT context is valid and current.</li>
|
|
<li>The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief.</li>
|
|
<li>Implementation references from the brief are loaded.</li>
|
|
<li>The shape visual probe decision is recorded: generated, skipped with reason, or already resolved.</li>
|
|
<li>The north-star mock decision is recorded: generated, skipped with reason, or not applicable.</li>
|
|
</ol>
|
|
<p>PRODUCT.md and <code>teach</code> answers do <strong>not</strong> satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. <code>shape=pass</code> requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user.</p>
|
|
<p>Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets.</p>
|
|
<h2 id="craft-contract">Craft Contract</h2>
|
|
<p>Craft is not a first pass. It is a loop with these required artifacts:</p>
|
|
<ol>
|
|
<li>Confirmed design brief from <code>shape</code>.</li>
|
|
<li>Approved visual direction, from generated probes / mocks when image generation is available.</li>
|
|
<li>Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code.</li>
|
|
<li>Semantic, functional implementation using the project's real stack and conventions.</li>
|
|
<li>Browser evidence across relevant viewports.</li>
|
|
<li>At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects.</li>
|
|
</ol>
|
|
<p>Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood."</p>
|
|
<h2 id="step-1-shape-the-design">Step 1: Shape the Design</h2>
|
|
<p>Run /impeccable shape, passing along whatever feature description the user provided.</p>
|
|
<p>Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it.</p>
|
|
<p>If this craft run resumed after <code>teach</code> created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation.</p>
|
|
<p>If the user has already run /impeccable shape and has a confirmed design brief, skip this step and use the existing brief.</p>
|
|
<h2 id="step-2-load-references">Step 2: Load References</h2>
|
|
<p>Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult:</p>
|
|
<ul>
|
|
<li><a href="spatial-design.md">spatial-design.md</a> for layout and spacing</li>
|
|
<li><a href="typography.md">typography.md</a> for type hierarchy</li>
|
|
</ul>
|
|
<p>Then add references based on the brief's needs:</p>
|
|
<ul>
|
|
<li>Complex interactions or forms? Consult <a href="interaction-design.md">interaction-design.md</a></li>
|
|
<li>Animation or transitions? Consult <a href="motion-design.md">motion-design.md</a></li>
|
|
<li>Color-heavy or themed? Consult <a href="color-and-contrast.md">color-and-contrast.md</a></li>
|
|
<li>Responsive requirements? Consult <a href="responsive-design.md">responsive-design.md</a></li>
|
|
<li>Heavy on copy, labels, or errors? Consult <a href="ux-writing.md">ux-writing.md</a></li>
|
|
</ul>
|
|
<h2 id="step-3-land-the-visual-direction-capability-gated">Step 3: Land the Visual Direction (Capability-Gated)</h2>
|
|
<p>Before implementation, generate high-fidelity visual comps when all of these are true:</p>
|
|
<ul>
|
|
<li>The work is <strong>net-new</strong> or visually open-ended enough that composition exploration will improve the build.</li>
|
|
<li>The brief's scope is <strong>mid-fi, high-fi, or production-ready</strong>.</li>
|
|
<li>The current harness has <strong>built-in image generation capability</strong> (for example, Codex with a native image tool). Do <strong>not</strong> ask the user to set up external APIs, shell scripts, or one-off tooling just to do this.</li>
|
|
</ul>
|
|
<p>When those conditions are met, this step is mandatory for <strong>both brand and product work</strong> in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in <code>image_gen</code> tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed.</p>
|
|
<p>Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.</p>
|
|
<h3 id="purpose">Purpose</h3>
|
|
<p>Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone.</p>
|
|
<h3 id="what-to-generate">What to generate</h3>
|
|
<p>Generate <strong>1 to 3</strong> high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration.</p>
|
|
<ul>
|
|
<li>For brand work, push visual identity, composition, and mood aggressively.</li>
|
|
<li>For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states.</li>
|
|
<li>For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero.</li>
|
|
</ul>
|
|
<p>The comps must be genuinely different in primary visual direction, not just color variants.</p>
|
|
<h3 id="approval-loop">Approval loop</h3>
|
|
<p>Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice.</p>
|
|
<p>If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste.</p>
|
|
<p>Before moving to implementation, summarize:</p>
|
|
<ul>
|
|
<li>What to carry into code</li>
|
|
<li>What <strong>not</strong> to literalize from the mock</li>
|
|
</ul>
|
|
<p>This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation.</p>
|
|
<h3 id="mock-fidelity-inventory">Mock fidelity inventory</h3>
|
|
<p>Before building, inventory the approved mock's major visible ingredients:</p>
|
|
<ul>
|
|
<li>Hero silhouette and dominant composition.</li>
|
|
<li>Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects.</li>
|
|
<li>Nav and primary CTA treatment.</li>
|
|
<li>Section sequence visible in the mock, especially the second fold.</li>
|
|
<li>Image-native content the concept depends on.</li>
|
|
<li>Typography, density, color/material treatment, and motion cues.</li>
|
|
</ul>
|
|
<p>For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change.</p>
|
|
<p>Treat the mock as a <strong>north star</strong>, not a screenshot to trace. Do <strong>not</strong> rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong.</p>
|
|
<h2 id="step-4-asset-extraction-need-gated">Step 4: Asset Extraction (Need-Gated)</h2>
|
|
<p>If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building.</p>
|
|
<p>Good candidates:</p>
|
|
<ul>
|
|
<li>stickers</li>
|
|
<li>badges</li>
|
|
<li>seals</li>
|
|
<li>tickets</li>
|
|
<li>graphic labels</li>
|
|
<li>textures</li>
|
|
<li>abstract objects</li>
|
|
<li>decorative marks</li>
|
|
<li>non-semantic scene elements</li>
|
|
</ul>
|
|
<p>For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes.</p>
|
|
<p>Do <strong>not</strong> export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code.</p>
|
|
<p>Usually <strong>1 to 5</strong> extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional.</p>
|
|
<h2 id="step-5-build-to-production-quality">Step 5: Build to Production Quality</h2>
|
|
<p>Implement the feature following the design brief. Build in passes so structure, visual system, states, motion/media, and responsive behavior each get deliberate attention. The list below is the definition of done, not inspiration.</p>
|
|
<h3 id="production-bar">Production bar</h3>
|
|
<ul>
|
|
<li>Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting.</li>
|
|
<li>Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change.</li>
|
|
<li>Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed.</li>
|
|
<li>Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment.</li>
|
|
<li>Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes.</li>
|
|
<li>Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant.</li>
|
|
<li>Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality.</li>
|
|
<li>Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles.</li>
|
|
<li>Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive <code>srcset</code> / <code>picture</code> for raster assets, and no project-referenced asset left outside the workspace.</li>
|
|
<li>Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects when they improve the experience; avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion.</li>
|
|
<li>Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists.</li>
|
|
<li>Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path.</li>
|
|
<li>If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing.</li>
|
|
</ul>
|
|
<h2 id="step-6-browser-based-iteration">Step 6: Browser-Based Iteration</h2>
|
|
<p><strong>This step is critical.</strong> Do not stop after the first implementation pass.</p>
|
|
<p>Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output.</p>
|
|
<h3 id="required-viewport-pass">Required viewport pass</h3>
|
|
<p>Check the experience at the viewports that matter for the brief. Default minimum:</p>
|
|
<ul>
|
|
<li>Mobile narrow</li>
|
|
<li>Tablet or small laptop</li>
|
|
<li>Desktop wide</li>
|
|
</ul>
|
|
<p>For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow.</p>
|
|
<h3 id="critique-and-fix-loop">Critique and fix loop</h3>
|
|
<p>After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist:</p>
|
|
<ol>
|
|
<li><strong>Does it match the brief?</strong> Compare the live result against every section of the design brief. Fix discrepancies.</li>
|
|
<li><strong>Does it match the approved mock?</strong> Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects.</li>
|
|
<li><strong>Does it pass the AI slop test?</strong> If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention.</li>
|
|
<li><strong>Check against impeccable's DON'T guidelines.</strong> Fix any anti-pattern violations.</li>
|
|
<li><strong>Check every state.</strong> Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought.</li>
|
|
<li><strong>Check responsive behavior.</strong> The design should adapt compositionally, not merely shrink.</li>
|
|
<li><strong>Check craft details.</strong> Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment.</li>
|
|
<li><strong>Check performance basics.</strong> No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason.</li>
|
|
</ol>
|
|
<p>The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review.</p>
|
|
<h2 id="step-7-present">Step 7: Present</h2>
|
|
<p>Present the result to the user:</p>
|
|
<ul>
|
|
<li>Show the feature in its primary state</li>
|
|
<li>Summarize the browser/viewports checked and the most important fixes made after inspection</li>
|
|
<li>Walk through the key states (empty, error, responsive)</li>
|
|
<li>Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients.</li>
|
|
<li>Note any remaining limitations or follow-up risks honestly</li>
|
|
<li>Ask: "What's working? What isn't?"</li>
|
|
</ul>
|
|
<p>Iterate based on feedback. Good design is rarely right on the first pass.</p>
|
|
|
|
</div>
|
|
</section>
|
|
|
|
|
|
</article>
|
|
|
|
</div>
|
|
</div>
|
|
</main>
|
|
<script>
|
|
// Copy buttons on rendered code blocks
|
|
document.addEventListener('click', (e) => {
|
|
const btn = e.target.closest('[data-copy]');
|
|
if (!btn) return;
|
|
const text = btn.getAttribute('data-copy');
|
|
if (!text) return;
|
|
navigator.clipboard.writeText(text).then(() => {
|
|
btn.classList.add('is-copied');
|
|
setTimeout(() => btn.classList.remove('is-copied'), 1500);
|
|
}).catch(() => {});
|
|
});
|
|
|
|
// Mobile sidebar toggle (shown on narrow viewports, hidden on desktop).
|
|
document.addEventListener('click', (e) => {
|
|
const toggle = e.target.closest('.skills-sidebar-toggle');
|
|
if (!toggle) return;
|
|
const expanded = toggle.getAttribute('aria-expanded') === 'true';
|
|
toggle.setAttribute('aria-expanded', String(!expanded));
|
|
});
|
|
|
|
// Before/after split-compare: drag on touch, hover OR drag on mouse.
|
|
// Pointer events attach to the padded .split-comparison wrapper so
|
|
// there is a ~20px invisible buffer around the visible box. The
|
|
// divider only snaps back when the pointer leaves that outer buffer.
|
|
(function initSplitCompare() {
|
|
const wrappers = document.querySelectorAll('.split-comparison');
|
|
if (wrappers.length === 0) return;
|
|
const hasHover = matchMedia('(hover: hover)').matches;
|
|
const DEFAULT_POSITION = 50;
|
|
|
|
for (const wrapper of wrappers) {
|
|
const container = wrapper.querySelector('.split-container');
|
|
const splitAfter = wrapper.querySelector('.split-after');
|
|
const splitDivider = wrapper.querySelector('.split-divider');
|
|
if (!container || !splitAfter || !splitDivider) continue;
|
|
|
|
const tanAngle = Math.tan(10 * Math.PI / 180);
|
|
let skewOffset = 8;
|
|
const recalcSkew = () => {
|
|
const r = container.getBoundingClientRect();
|
|
if (r.width > 0 && r.height > 0) {
|
|
skewOffset = 50 * r.height * tanAngle / r.width;
|
|
}
|
|
};
|
|
recalcSkew();
|
|
window.addEventListener('resize', recalcSkew, { passive: true });
|
|
|
|
let targetX = DEFAULT_POSITION;
|
|
let currentX = DEFAULT_POSITION;
|
|
let rafId = null;
|
|
|
|
const paint = (pct) => {
|
|
const x = Math.max(-skewOffset, Math.min(100 + skewOffset, pct));
|
|
splitAfter.style.clipPath =
|
|
`polygon(${x + skewOffset}% 0%, 100% 0%, 100% 100%, ${x - skewOffset}% 100%)`;
|
|
splitDivider.style.left = `${x}%`;
|
|
};
|
|
|
|
const step = () => {
|
|
currentX += (targetX - currentX) * 0.2;
|
|
if (Math.abs(targetX - currentX) < 0.1) {
|
|
currentX = targetX;
|
|
rafId = null;
|
|
} else {
|
|
rafId = requestAnimationFrame(step);
|
|
}
|
|
paint(currentX);
|
|
};
|
|
|
|
const setTarget = (pct) => {
|
|
targetX = pct;
|
|
if (rafId === null) rafId = requestAnimationFrame(step);
|
|
};
|
|
|
|
paint(DEFAULT_POSITION);
|
|
|
|
// Percentage is always relative to the VISIBLE .split-container,
|
|
// not the padded .split-comparison wrapper. The pointer event
|
|
// target is the wrapper but the clip-path math uses the inner box.
|
|
const pctFromClientX = (clientX) => {
|
|
const rect = container.getBoundingClientRect();
|
|
return ((clientX - rect.left) / rect.width) * 100;
|
|
};
|
|
|
|
let hovering = false;
|
|
let dragging = false;
|
|
|
|
wrapper.addEventListener('pointerenter', (e) => {
|
|
if (hasHover && e.pointerType === 'mouse') {
|
|
hovering = true;
|
|
}
|
|
});
|
|
|
|
wrapper.addEventListener('pointerdown', (e) => {
|
|
dragging = true;
|
|
wrapper.setPointerCapture(e.pointerId);
|
|
setTarget(pctFromClientX(e.clientX));
|
|
});
|
|
|
|
wrapper.addEventListener('pointermove', (e) => {
|
|
if (dragging || hovering) {
|
|
setTarget(pctFromClientX(e.clientX));
|
|
}
|
|
});
|
|
|
|
const endDrag = (e) => {
|
|
if (dragging) {
|
|
dragging = false;
|
|
try { wrapper.releasePointerCapture(e.pointerId); } catch {}
|
|
}
|
|
};
|
|
|
|
wrapper.addEventListener('pointerup', endDrag);
|
|
wrapper.addEventListener('pointercancel', endDrag);
|
|
|
|
wrapper.addEventListener('pointerleave', (e) => {
|
|
endDrag(e);
|
|
if (hovering) {
|
|
hovering = false;
|
|
setTarget(DEFAULT_POSITION);
|
|
}
|
|
});
|
|
}
|
|
})();
|
|
</script>
|
|
</body>
|
|
</html>
|