codex-visual-builder-guild

codex-visual-builder-guild

Welcome to the Codex Visual Builder Guild: a free, open-source guild of H70-C+ Spark Skill Graphs that helps Codex build better-looking apps with imagegen, screenshots, vision review, and specialist delegation.

Think of it like hiring a tiny fantasy design studio for your Codex Desktop session. One specialist checks spacing. One makes assets. One stress-tests mobile. One guards accessibility. One turns the winning design into reusable rules. Together, they help Codex stop guessing and start looking.

Free community drop. MIT licensed. Fork it, remix it, install it into Spark Skill Graphs, or use the YAML skills directly in your own agent runtime.

30 Seconds, 2 Minutes, 5 Minutes

In 30 seconds: this makes Codex look at the real UI before it claims the design is good.

In 2 minutes: install one Codex skill:

git clone https://github.com/vibeforge1111/codex-visual-builder-guild.git
cd codex-visual-builder-guild
npm install
npm run install:codex

In 5 minutes: restart Codex Desktop, open your app, and paste the first-win prompt. Codex should return before/after screenshots, the biggest visual issue, the fix, what still needs work, and whether any specialist lens was actually useful.

For the shortest path, read QUICKSTART.md.

If You Are New, Choose This Path

Most builders should start with Codex Desktop. You do not need Spark Skill Graphs for the first win.

If you are unsure, choose the Codex wrapper. It is the fastest path from “I saw this on X” to “Codex fixed a rendered UI after looking at screenshots.”

Install For Codex

If you just want to use the guild inside Codex Desktop, install the native Codex wrapper skill:

git clone https://github.com/vibeforge1111/codex-visual-builder-guild.git
cd codex-visual-builder-guild
npm install
npm run install:codex

The installer prints the exact skill folder, verifies that SKILL.md was copied, and gives you the smoke prompt.

Important: restart Codex Desktop or open a new Codex session after installing. Already-open sessions may not see newly installed skills.

Then say:

Use codex-visual-builder-guild to run the visual builder loop on this app.

That gives Codex one easy skill to invoke. The wrapper skill knows the full 19-specialist guild and can route work through the right specialist lens.

The default is intentionally small: one visible win first, at most 1-2 specialist lenses, and screenshot proof before claims.

Your First 5-Minute Win

Use this when you want proof that the guild works, not a long design ceremony:

Use codex-visual-builder-guild on this app.

Run it locally, take desktop, tablet, mobile, and awkward in-between screenshots, inspect the rendered UI with Codex App vision, name the top 3 visual issues, fix the highest-impact one, capture after screenshots, then run a Post-Fix Ruthlessness Check before accepting the result.

End with a plain-English before/after summary and the screenshot paths.

Expected result:

• Codex runs the app instead of guessing from source code.
• You get desktop, tablet, mobile, and fluid breakpoint screenshots.
• Codex records concrete vision observations from those screenshots.
• The guild names the biggest visible problem.
• The guild uses at most 1-2 specialist lenses unless screenshots prove more are needed.
• Codex fixes one high-impact issue and screenshots the result.
• Codex checks whether the first fix left awkward onboarding copy, duplicated actions, box soup, text-first clutter, or responsive regressions.
• The final answer follows the Run Report Contract: goal, viewport matrix, state matrix, screenshots inspected, vision observations, top issues, chosen issue, lens used, exact fix, verification, post-fix ruthlessness, accepted visual change, still weak, reusable rule, automation notes.

Want a disposable target? Open examples/first-run-demo and ask the guild to improve it.

See the shape of a successful result: examples/first-run-demo/PROOF_PACKET.md.

The 10-Second Pitch

Most AI-made UIs fail because the agent writes code once and never really sees the result.

This guild gives Codex a loop:

build -> run -> screenshot -> vision review -> delegate -> fix -> compare -> keep the rules

That means Codex can:

• generate UI-ready image assets instead of waiting on placeholders
• inspect real screenshots with Codex App vision instead of guessing from code
• catch mobile, spacing, contrast, and interaction problems
• check whether the user flow is understandable, low-friction, and not overwhelming
• hand narrow problems to specialist skills
• turn great screens into art-bible rules, component contracts, tokens, and regression baselines
• work standalone or inside Spark Skill Graphs

Codex App Native Guardrails

The Codex wrapper is optimized for what Codex App gives you natively:

• Vision is the judge. Every visual claim should come from a real screenshot or rendered state that Codex App inspected with vision.
• The in-app browser is live context. When a URL is open, use that rendered page as the product surface before guessing from files.
• Imagegen is for integrated assets. Generate custom visuals only when they make the product clearer, then put them in the UI and screenshot them in context.
• Screenshots are shareable proof. Final reports should include local screenshot paths and plain-English observations about what changed.
• Metrics support vision. DOM measurements, tests, and screenshot filenames can support a finding, but they should not replace visual inspection.
• Native beats generic. Prefer Codex App vision, local images, clickable files, and screenshot evidence over external wrappers that hide what Codex can already do.

Start With This Prompt

Paste this into Codex Desktop when you want the full guild experience. If you installed the Codex skill, start with Use codex-visual-builder-guild.

Use codex-visual-builder-guild as a visual product team.

Goal: [describe what we are building].

Run the app locally, take screenshots on desktop, tablet, mobile, and an awkward in-between width, inspect the rendered UI with Codex App vision, and delegate issues to the right specialists. Use imagegen when custom assets would improve the product, then integrate and screenshot those assets in context. Focus on hierarchy, spacing, contrast, text fit, responsive layout, interaction states, accessibility, user-flow clarity, overwhelm, and component-system consistency.

Do not stop at the first draft. Iterate until the UI feels polished, compare before/after screenshots, and summarize the final design rules.

More copy-paste prompts live in PROMPTS.md.

No-Ceremony Workflow

The best dogfood runs showed that the guild helps most when it behaves like a compact visual QA loop, not a parade of roles.

Use this order:

1. Start with the minimum useful pass.
2. Route to a specialist only when screenshot evidence proves the failure class.
3. Fix one high-impact issue.
4. Preserve before/after screenshots.
5. Leave a proof packet another builder can inspect.

See WORKFLOW.md for the lens router, stronger proof packet, and optional Playwright, Storybook/Chromatic, axe, and Web Vitals recipes.

You can also scaffold the proof artifacts:

npm run recommend-workflow -- --need "dashboard mobile regression"
npm run create-proof-packet -- --cwd ../my-app
npm run check-proof-packet -- --cwd ../my-app
npm run score-proof-packet -- --cwd ../my-app
npm run scaffold:playwright-visual -- --cwd ../my-app --url http://127.0.0.1:5173 --name dashboard

For honest guild-vs-plain-Codex evals, use benchmarks/RUN_TEMPLATE.md. The benchmark folder is intentionally empty of fake wins; add only runs with real screenshots and proof scores.

How It Works

The guild is not a design theory packet. It is a working loop:

1. Codex builds or changes the app.
2. Codex runs it locally.
3. Codex captures screenshots.
4. Vision inspects what actually rendered.
5. The guild routes problems to specialists.
6. Codex fixes the product and screenshots it again.
7. Winning choices become reusable rules.

Imagegen creates source material. Vision judges the real interface. Specialist lenses make the routing explicit. Spark Skill Graphs are optional unless you want the full graph/dashboard path.

Summon The Right Specialist

Use the full guild prompt when you want the whole team. Use a specialist lens when you already know the problem. For most runs, start with visual-loop-qa and route to at most two lenses.

Delegation Map

visual-loop-qa is the guild captain. It does not try to solve every problem alone. It looks at the screenshot, names the failure class, and sends the right job to the right specialist.

Every handoff uses H70-C+ delegates_version: 2 contracts:

• pass_context: what the specialist receives
• expect_back: what the specialist must return
• sla: whether the handoff is synchronous or async

For native Codex runs, the wrapper now uses the same idea as a visible vision-backed handoff packet. The packet must come from Codex App vision inspecting a real screenshot or rendered state. Filenames, DOM metrics, tests, and source reads can support the packet, but they cannot replace the vision observation.

from lens -> to lens
vision source: screenshot path plus viewport/state inspected
vision observation: what Codex actually saw in the image
supporting evidence: optional DOM metric, test result, or source-code fact
finding: the visible problem or rule discovered from vision
decision: fix now, verify after fix, or keep as residual risk
next vision check: the screenshot, interaction, or content case the next lens must inspect with vision

This keeps the guild from becoming ceremony. A responsive finding can hand off to interaction-state checks, ugly real content can hand off to responsive review, onboarding/workflow changes can hand off to interaction review, and accepted visual changes can hand off to screenshot-regression guardrails. If the next lens would not change a decision, screenshot, vision observation, test, or rule, stop.

Specialist Wing

The delegation map shows the core routing. The specialist wing rounds out the full 19-skill roster with the skills that tend to activate after a visual issue becomes more specific.

The point is simple: one big vague prompt like “make it look better” becomes a team of smaller, sharper jobs.

Three Ways To Use It

Codex Desktop: install codex/codex-visual-builder-guild as a native Codex skill with npm run install:codex, then invoke it by name. This is the easiest path for most people.

Standalone YAML: load any file in design/*.yaml directly into an agent, prompt system, CLI tool, or custom runtime. Each H70-C+ skill is self-contained. This is the lightest path for agent builders.

Spark Skill Graphs: copy the same files into a Spark Skill Graphs checkout. design/*.yaml become graph nodes, delegates become graph edges, and bundles/codex-visual-builder-loop.yaml becomes the recommended guild load order. This is the full graph/dashboard path.

You can ignore the Spark section if you only want the Codex Desktop skill. Spark is for people who want visible graph routing, dashboard inspection, or to reuse the H70-C+ YAML directly.

Install Into Spark Skill Graphs

From this repo root:

Copy-Item -Recurse -Force .\design\*.yaml C:\Users\USER\Desktop\spark-skill-graphs\design\
Copy-Item -Force .\bundles\codex-visual-builder-loop.yaml C:\Users\USER\Desktop\spark-skill-graphs\bundles\

Then validate from spark-skill-graphs:

$env:NODE_PATH='C:\Users\USER\Desktop\spawner-ui\node_modules'
$env:SPAWNER_H70_SKILLS_DIR='C:\Users\USER\Desktop\spark-skill-graphs\design'
node C:\Users\USER\Desktop\spark-skill-graphs\tools\validate-h70-cplus.js

If you use the Spark MCP server or dashboard, restart/re-index it after copying the files. Already-running MCP/dashboard processes may keep an older in-memory skill index and return Skill not found until restarted.

Tested Before Ship

This package includes local checks for the parts that matter most:

• H70-C+ structure
• required 12-section coverage
• embedded disaster detection commands
• embedded anti-pattern detection
• delegate contract completeness
• bundle load order resolution
• common Codex visual-loop invocation cues
• Codex wrapper install and invocation coverage
• beginner first-run documentation coverage
• demo app presence

Validate this package:

npm install
npm test

Expected result:

Valid H70-C+: 19
Invalid: 0
With warnings: 0
Smoke test passed
Usage audit passed

What Is Inside

• design/*.yaml: 19 H70-C+ design skills
• QUICKSTART.md: the 30-second, 2-minute, 5-minute path for new users
• codex/codex-visual-builder-guild/SKILL.md: native Codex wrapper skill
• bundles/codex-visual-builder-loop.yaml: recommended guild load order
• tools/validate-h70-cplus.js: H70-C+ structure validator
• tools/smoke-test.cjs: practical package smoke test
• tools/usage-audit.cjs: Codex install and invocation coverage audit
• tools/install-codex-skill.cjs: one-command Codex skill installer
• PROMPTS.md: copy-paste prompts for the whole guild and each specialist
• assets/*.png: README and X-ready visual explainers

Infographic Set

• assets/hero-guild-banner.png: X and README hero
• assets/what-you-get.png: install value
• assets/how-it-works.png: visual builder loop
• assets/delegation-map.png: specialist routing
• assets/specialist-wing.png: remaining specialist roster
• assets/use-it-two-ways.png: Codex, standalone YAML, and Spark dashboard usage
• assets/tested-before-ship.png: validation and trust