Plan mode: If you are planning work, this entire skill is ONE plan step: "Invoke /vibes:design-reference". Do not decompose the steps below into separate plan tasks.

Display this ASCII art immediately when starting:

░▒▓███████▓▒░░▒▓████████▓▒░░▒▓███████▓▒░▒▓█▓▒░░▒▓██████▓▒░░▒▓███████▓▒░ ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░ ░▒▓█▓▒░ ░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░ ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░ ░▒▓█▓▒░ ░▒▓█▓▒░▒▓█▓▒░ ░▒▓█▓▒░░▒▓█▓▒░ ░▒▓█▓▒░░▒▓█▓▒░▒▓██████▓▒░ ░▒▓██████▓▒░░▒▓█▓▒░▒▓█▓▒▒▓███▓▒░▒▓█▓▒░░▒▓█▓▒░ ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░ ░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░ ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░ ░▒▓█▓▒░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░ ░▒▓███████▓▒░░▒▓████████▓▒░▒▓███████▓▒░░▒▓█▓▒░░▒▓██████▓▒░░▒▓█▓▒░░▒▓█▓▒░

Design Reference Transformer

Transform a complete design reference HTML file into a working Vibes app with Fireproof data persistence.

Core Principle

Preserve and adapt, don't interpret and recreate.

The design reference is source code to transform, not inspiration to interpret. When given a complete HTML file with styles, your job is to make minimal surgical changes to connect it to React/Fireproof—not to recreate it from your understanding of its aesthetic.

When to Use This Skill

Use this skill when:

• User provides a design.html , mockup, or static prototype file

• User says "match this design exactly" or "use this as a reference"

• User wants their existing HTML converted to a Vibes app

• A previous implementation didn't match the design reference

The Transformation is Mechanical

The conversion from design HTML to React/Fireproof is deterministic, not creative:

Transformation Rule Example

Attributes class → className

class="btn" → className="btn"

Attributes for → htmlFor

for="email" → htmlFor="email"

Attributes kebab-case → camelCase stroke-width → strokeWidth

Self-closing Add explicit close <input> → <input />

Comments HTML → JSX <!-- x --> → {/* x */}

Inline styles String → Object style="color: red" → style={{ color: 'red' }}

Event handlers Lowercase → camelCase onclick → onClick

CSS requires NO changes. Copy the entire <style> block verbatim.

Workflow

Step 1: Read the Design Reference

Read the design file completely

Read design.html

Note the structure:

• <style> block (copy verbatim)

• HTML structure (preserve exactly)

• Any vanilla JavaScript (will be replaced with React)

Step 2: Identify Dynamic Content

Ask: "What content comes from the database?"

Typical dynamic elements:

• List items that repeat (.map() )

• Text that users enter (controlled inputs)

• Counts, totals, timestamps

• User-specific content

Everything else stays static.

Step 3: Create the React Component

import React from "react"; import { useFireproofClerk } from "use-fireproof";

export default function App() { const { database, useLiveQuery, useDocument } = useFireproofClerk("app-db");

// Hooks for dynamic data const { doc, merge, submit } = useDocument({ /* initial shape */ }); const { docs } = useLiveQuery("type", { key: "item" });

return ( <> {/* CSS copied VERBATIM from design.html */} <style>{ /* Paste entire <style> block here unchanged */ }</style>

  {/* HTML structure preserved, only syntax converted */}
  {/* Dynamic content replaced with {expressions} */}
</>

); }

Step 4: Handle Dark Mode Override (If Needed)

The Vibes template has dark mode support. If your design is light-only, add this CSS override:

/* Force light theme regardless of system preference */ html, body, #container, #container > div { background-color: var(--your-bg-color) !important; }

Note: Avoid targeting [style*="position: fixed"] as this will style the VibesSwitch toggle button.

Step 4b: Scope CSS to Avoid VibesSwitch/VibesPanel Conflicts

The template includes a VibesSwitch toggle button and VibesPanel admin menu that sit outside your app container. Broad CSS selectors can accidentally style these components.

Watch for these problematic patterns:

Problematic Why Safe Alternative

button { ... }

Styles VibesSwitch toggle .app button { ... } or #container button { ... }

• { ... } (with colors/backgrounds) Cascades everywhere Scope to specific containers

[style*="position: fixed"]

Targets VibesSwitch Target by class/ID instead

body > div

May match menu wrapper Use #container > div

If your design has global button/element styles:

• Wrap your app content in a container with a class: <div className="app">...</div>

• Scope broad rules: button { } → .app button { }

• Or use #container which is the template's app root

The template already protects components with:

button[aria-controls="hidden-menu"] { background: transparent !important; } #hidden-menu { /* menu-specific variable resets */ }

But defense-in-depth is better—scope your CSS to avoid conflicts.

Step 5: Assemble and Test

node "/path/to/vibes-skill/scripts/assemble.js" app.jsx index.html

Open in browser and visually diff against the design reference. They should be pixel-identical except for dynamic content.

Anti-Patterns (DO NOT DO THESE)

Anti-Pattern Why It's Wrong Correct Approach

Translate colors to OKLCH Changes the design Use exact hex values from reference

Restructure HTML "for React" Breaks layout Preserve structure, only change syntax

"Improve" the CSS Not your job Copy verbatim

Add your own classes Introduces drift Use exact classes from reference

Interpret the "vibe" Creates divergence Be literal, not interpretive

Skip vanilla JS analysis Miss functionality Understand what it does, then React-ify

Transformation Checklist

Before writing code, verify:

• Read the entire design.html file

• Identified all <style> blocks (will copy verbatim)

• Identified dynamic content (lists, inputs, user data)

• Identified vanilla JS functionality (will convert to React)

• Noted any custom fonts (add to imports if needed)

• Checked for dark/light theme assumptions

During transformation:

• CSS pasted unchanged (no "improvements")

• HTML structure preserved exactly

• Only syntax converted (class→className, etc.)

• Dynamic content uses {expressions} and .map()

• Vanilla JS replaced with React hooks and handlers

• Dark mode override added if design is light-only

After assembly:

• Visual comparison with design reference

• All interactive elements work

• Data persists on refresh

• No console errors

• VibesSwitch toggle (bottom-right) displays correctly with no background box

• VibesPanel menu opens when toggle is clicked

• Menu buttons are correctly styled (not inheriting app button styles)

Example: Static List → Dynamic List

Design HTML:

<ul class="item-list"> <li class="item">First item</li> <li class="item">Second item</li> </ul>

React with Fireproof:

const { docs } = useLiveQuery("type", { key: "item" });

<ul className="item-list"> {docs.map(item => ( <li key={item._id} className="item">{item.text}</li> ))} </ul>

Note: Only the content changed. The classes, structure, and styling are identical.

Example: Static Form → Controlled Form

Design HTML:

<form> <input type="text" class="input" placeholder="Enter text..."> <button class="btn">Submit</button> </form>

React with Fireproof:

const { doc, merge, submit } = useDocument({ text: "", type: "item" });

<form onSubmit={submit}> <input type="text" className="input" placeholder="Enter text..." value={doc.text} onChange={(e) => merge({ text: e.target.value })} /> <button type="submit" className="btn">Submit</button> </form>

Note: Same structure, same classes, same placeholder. Only added React bindings.

Integration with Vibes Assembly

This skill produces an app.jsx that works with the standard Vibes assembly:

In the working directory

node "/path/to/vibes-skill/scripts/assemble.js" app.jsx index.html

The assembly script:

• Inserts your JSX into the Vibes template

• Handles Clerk authentication wrapper

• Sets up import maps for React and Fireproof

• Configures Connect if .env is present

What's Next?

After transforming a design reference, present these options using AskUserQuestion:

Question: "Design reference transformed! What's next?" Header: "Next" Options:

• Label: "Test locally" Description: "Open index.html in browser to verify it matches the design exactly"

• Label: "Deploy to Cloudflare (/cloudflare)" Description: "Push the app live to Cloudflare Workers"

• Label: "Make adjustments" Description: "Fine-tune specific elements while preserving the design"

• Label: "I'm done" Description: "Wrap up - files are saved locally"