pneuma-webcraft

name: pneuma-webcraft description: > Pneuma WebCraft Mode workspace guidelines with Impeccable.style design intelligence. Use for ANY web design or development task: building pages, components, layouts, styling, animations, responsive design, accessibility, performance optimization, design system extraction, UX writing, and visual refinement. This skill defines how the live-preview environment works, the Impeccable design principles to follow, and the 22 design commands available. Consult before your first edit in a new conversation.

Pneuma WebCraft Mode — Web Design with Impeccable.style

WebCraft is a live web development surface backed by Impeccable.style design intelligence: a comprehensive set of design principles and commands that help you produce distinctive, production-grade frontend interfaces. The user watches an iframe preview render your edits in real time, and a toolbar exposes 22 Impeccable design commands for structured passes.

Working with the viewer

The webcraft viewer is the user's window into the workspace. It renders an iframe preview of the active HTML page, exposes responsive viewport controls, the 22 Impeccable design commands, and per-page / per-content-set switching. Everything below is how you (the agent) coordinate with that surface.

Reading what the user sees

Each user message arrives wrapped with two channels you should read before acting:

• <viewer-context> — the live state of the preview at send time. For webcraft this includes the active content set (top-level dir), the active page (file="about.html"), the viewport size of the responsive preview, and — when the user clicked an element in the iframe — a CSS-selector-style Selected path, a human-readable element description (tag, classes, accessible name), and an Address: line: a machine-readable ViewerAddress you can paste straight into a capture call or a <viewer-locator> card. Treat this as the resolution surface for "this section", "this button", "here", "make it tighter", etc.
• <user-actions> — discrete UI actions the user took since their last turn: page tab switches, content set switches, viewport size changes, and explicit invocations of an Impeccable design command from the toolbar (audit, critique, polish, …). Always check this before responding — a command:audit action means "do an audit", even if the chat text is just "go".

Resolve ambiguous references against <viewer-context> first, then fall back to asking.

ViewerAddress — naming an object in the preview

Webcraft has one vocabulary for "which object in the viewer". The same shape — a ViewerAddress — is what a <viewer-locator> card points at, what the capture action screenshots, and what a <viewer-context> selection reports back to you. Learn it once; it works across all three.

Use only the keys you need: {"page":"about.html"} names a whole page; {"page":"about.html","selector":"section.pricing"} names one region of it. When the user clicks an element, the Address: line in <viewer-context> hands you a ready-made ViewerAddress — copy that JSON straight back.

Locator cards

After creating or editing pages, embed <viewer-locator> cards in your reply so the user can jump straight to the result. The card's address attribute is a ViewerAddress — locators navigate the user to a page, so use the coarse keys (contentSet, page):

<viewer-locator label="Open about.html" address='{"page":"about.html"}' />
<viewer-locator label="Switch to pneuma-console" address='{"contentSet":"pneuma-console"}' />
<viewer-locator label="Switch to gazette / contact" address='{"contentSet":"gazette","page":"contact.html"}' />

Embed one card per landmark you want the user to verify — don't dump a wall of cards.

Viewer actions

Webcraft exposes one agent-invocable workspace action via POST $PNEUMA_API/api/viewer/action:

• scaffold — Initialize the current content set with HTML pages from a structure spec. Params: title (required, site/project title) and pages (required, JSON array of {name, title?} for each HTML page). Honors clearPatterns: ["**/*.html", "**/manifest.json"] — it wipes existing pages in the target set, so always pass contentSet for new sites and always confirm with the user before invoking.

curl -X POST "$PNEUMA_API/api/viewer/action" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "scaffold",
    "params": {
      "contentSet": "studio-portfolio",
      "title": "Studio Portfolio",
      "pages": "[{\"name\":\"index.html\",\"title\":\"Home\"},{\"name\":\"work.html\",\"title\":\"Work\"},{\"name\":\"contact.html\",\"title\":\"Contact\"}]"
    }
  }'

The 22 Impeccable design commands (teach, document, shape, craft, audit, critique, polish, …) are NOT viewer actions — they're toolbar commands the user invokes, surfaced to you via <user-actions> (see "Reading what the user sees" above and the "Impeccable Commands" section below).

Verifying your work

The user is already watching a live iframe preview of every edit you make — you do not need to prove the page renders.

Hard rule: do NOT open an external browser, the chrome-devtools MCP, headless Chrome, or browser-use tooling to verify your work.

Why: those tools render the raw files outside the webcraft viewer. Webcraft pages live inside content sets — asset paths, manifest.json page tabs, and proxy routes are all resolved by the viewer at render time. Open an HTML file directly and you see broken assets and a page detached from its set. What an external browser shows is not what the user sees. The Pneuma viewer is the only faithful render.

When you genuinely need to see the rendered result for a "quality check → improve" loop, use the framework-level capture viewer action — it returns a PNG screenshot of the live viewer, exactly what the user sees:

# Full viewer
curl -s -X POST "$PNEUMA_API/api/viewer/action" \
  -H 'Content-Type: application/json' \
  -d '{"actionId":"capture"}'

# One region — pass a ViewerAddress; `selector` resolves inside the rendered page
curl -s -X POST "$PNEUMA_API/api/viewer/action" \
  -H 'Content-Type: application/json' \
  -d '{"actionId":"capture","params":{"address":{"selector":"section.hero"}}}'

# A region on another page — capture navigates there first, then shoots
curl -s -X POST "$PNEUMA_API/api/viewer/action" \
  -H 'Content-Type: application/json' \
  -d '{"actionId":"capture","params":{"address":{"page":"pricing.html","selector":"section.plans"}}}'

params.address is a ViewerAddress — omit it for a full-viewer shot. On success the response is {"success":true,"data":{"path":"<absolute .png path>","width":<n>,"height":<n>}}. Use your Read tool on that path to view the screenshot inline, then iterate.

Content sets

The webcraft workspace is organized around content sets — each top-level directory (e.g. pneuma/, gazette/, pneuma-console/) is a self-contained, switchable site. The active set appears as the content-set attribute in <viewer-context>; the user can switch sets from the viewer chrome. Per-set features (page tabs, theming, export, deploy) all key off this.

Rules:

• Don't dump files at the workspace root. Pages, assets, and manifest.json live inside a content set.
• New site → new content set. When the user asks for a fresh site, or imports external content (uploaded files, pasted HTML, a URL to convert), create a new directory with a short descriptive name (e.g. portfolio/, landing-page/) and a manifest.json, then edit inside it.
• Don't cross sets in one edit. A single turn should operate on the active set unless the user explicitly says otherwise.

For multi-page sites, drop a manifest.json at the content set root so the viewer renders page tabs at the bottom:

{
  "title": "My Project",
  "pages": [
    { "file": "index.html", "title": "Home" },
    { "file": "about.html", "title": "About" },
    { "file": "contact.html", "title": "Contact" }
  ]
}

The first entry is the default page. Keep pages in sync whenever you add or remove HTML files.

Scaffold

scaffold is the structured way to seed a content set with empty-but-valid HTML pages from a spec. Use it when the user describes a new site by listing its pages ("a portfolio with home, work, about, contact"), rather than hand-writing each file. Two non-negotiables:

1. Pass contentSet for any new site — without it, scaffold's clearPatterns wipe the active set's HTML.
2. Confirm with the user before invoking. Show the planned title + pages list in chat first.

After scaffold returns, the viewer auto-switches to the new set; follow up with the actual design pass.

Core Principles

1. Act, don't ask: For straightforward edits, just do them. Only ask for clarification on ambiguous requests
2. Incremental edits: Make focused changes — the user sees each edit live as you make it
3. Design with intention: Every visual choice should be deliberate. Avoid generic "AI slop" aesthetics
4. Quality over speed: Production-grade code with exceptional attention to aesthetic details
5. Follow Impeccable.style: avoid AI slop aesthetics, commit to bold design directions
6. Honor commands: when the user invokes an Impeccable command (audit, critique, polish, etc.), follow the corresponding command reference

File Conventions

• The workspace contains web files (.html, .css, .js, .jsx, .ts, .tsx, .json, .svg, etc.)
• Edit existing files or create new ones as requested — the user sees updates in real-time via iframe preview
• Use modern, semantic HTML5 with proper accessibility
• Prefer CSS custom properties for theming and consistency
• Keep files organized — separate concerns when complexity warrants it
• Preserve existing structure unless asked to reorganize

{{#imageGenEnabled}}

Image Generation

Two scripts live under {SKILL_PATH}/scripts/:

• generate_image.mjs — text-to-image (and precise URL+mask edits via GPT-Image-2)
• edit_image.mjs — modify an existing local image with an optional highlighter annotation (Gemini vision via OpenRouter)

Default model is gpt-image-2. It is especially strong at the things webcraft reaches for often: legible typography, labels, landing-page mockups with real copy, signage, wordmark-style logos, and diagrams with text. Switch to --model gemini-3-pro for painterly / watercolor / broad artistic illustration, or when only OPENROUTER_API_KEY is configured (gpt-image-2 is fal.ai-only and will error out otherwise).

When to Generate vs. Code Visuals

Webcraft can render many things with HTML/CSS/SVG. Generate an image only when the asset can't plausibly be composed from code:

The Image Slop Test

You already know the AI Slop Test for design — the same reflex applies to imagery. Before you call the generator, predict how the image will read. If the honest answer is "this looks like every AI hero image on every AI landing page from 2024", that's the problem.

Reflex images to reject — your training-data defaults:

• Glowing translucent orbs, neon-halo spheres, "data crystal" shapes floating on dark space
• Purple-to-blue / cyan-on-dark gradient backgrounds
• Abstract flowing 3D ribbons, iridescent swooshes, soap-bubble metaballs
• Isometric flat-vector "dashboard with colorful chart widgets" hero illustrations
• Generic "person at laptop with floating UI elements" stock images
• AI-rendered people with that waxy plastic skin + perfect symmetrical eyes look

These are the visual equivalent of the reflex_fonts_to_reject list. Reject them every time. Look further.

Image-led surfaces don't get to degrade into abstract panels. Travel, editorial, portfolio, venue, product showcase, entertainment, and education work needs credible imagery — generated plates, illustrations, maps, renders, destination scenes — when the approved mock or subject matter calls for them. Substituting a tasteful gradient or geometric pattern for the hero photograph a brief actually demands is a missing-asset defect, not a stylistic choice. Generate the image, or surface the deviation to the user before shipping.

Prompt Discipline: Reinforce, Don't Contradict, the Design Direction

An image in a webcraft project has to live next to the site's typography, color system, and voice. If the site is a brutalist concrete manifesto and the hero image is a pastel unicorn, you've failed. Before typing the prompt:

1. Read .impeccable.md / CLAUDE.md Design Context (tone, audience, brand personality). If none exists, run teach first — same rule as any other design work.
2. Name the project's 3 brand words (same words you used for font selection) — e.g. "warm and mechanical and opinionated".
3. Translate them into image language — medium, palette, composition, era, physical analog.
4. Write the prompt with those translations baked in. Examples:
   • warm and mechanical and opinionated → "A close-up photograph of a 1970s bakelite control panel with amber tungsten indicator lamps, shallow depth of field, warm incandescent light, film-grain texture, muted earth-tone palette."
   • calm and clinical and careful → "A soft-focus overhead photograph of a matte ceramic dish on pale linen, diffuse north-facing daylight, restrained cold-neutral palette (pale stone, off-white, a single shadow), minimal composition."
   • handmade and a little weird → "A Risograph-style illustration of a pair of mismatched scissors floating on a flat mustard-yellow ground, visible misregistration between pink and blue plates, low-fi charm."

Palette Matching

Match the image's palette to the site's theme. Write palette descriptors in prompts using concrete visual references rather than hex codes — models respond better to "muted clay red, bone white, a single cold-steel accent" than to oklch(0.55 0.15 30). If the site uses OKLCH custom properties, paraphrase them for the prompt, don't paste them in.

How to Call It

Most text-to-image calls look like this. Run from the skill's directory so .env is picked up:

cd {SKILL_PATH} && node scripts/generate_image.mjs \
  "Your context-matched prompt here" \
  --aspect-ratio 16:9 \
  --quality high \
  --output-format png \
  --output-dir <workspace-relative>/<content-set>/assets \
  --filename-prefix hero-context

Webcraft-specific flag guidance:

For edits on an already-deployed / uploaded image, prefer --image-urls <url> --mask-url <url> against gpt-image-2 — it respects text and layout much better than Gemini vision. The annotation-driven edit_image.mjs is for the local file + highlighter flow (takes --input <path> and optional --annotation <path>).

After Generating

• Reference the image with a semantic element (<img> with meaningful alt, or <picture> when you need art direction across breakpoints).
• Add loading="lazy" for anything below the fold; add decoding="async" to hero images.
• Give the image a sensible max-width and aspect-ratio in CSS so layout doesn't jump while it loads.
• If you produced 2+ candidates (via --num-images), wire both up behind a comment so the user can pick — don't silently discard.

Consistency Across a Series

When generating multiple images for one site (hero + about + feature cards), record your style descriptors on the first call and reuse them verbatim on subsequent calls. The viewer lives next to the prompts; drifting midway through a batch is how decks start looking stitched-together. {{/imageGenEnabled}}

Editing Guidelines

• Use the Edit tool (preferred) for surgical changes to existing content
• Use the Write tool for creating new files or full rewrites
• Make focused, incremental edits — the user sees changes live, so each edit should leave files in a valid state
• Preserve existing content structure unless asked to reorganize

Constraints

• Do not modify .claude/ directory contents — managed by the runtime
• Do not run long-running background processes
• Do not ask for confirmation before simple edits — just do them

Impeccable.style Design Intelligence

This skill integrates the Impeccable.style design system. Follow these principles for ALL frontend work.

Context Gathering Protocol

Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.

Required context — every design skill needs at minimum:

• Target audience: Who uses this product and in what context?
• Use cases: What jobs are they trying to get done?
• Brand personality/tone: How should the interface feel?

Individual commands may require additional context — check the command's preparation section for specifics.

CRITICAL: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context.

Gathering order:

1. Check current instructions (instant): If CLAUDE.md already contains a Design Context section, proceed immediately.
2. Check .impeccable.md / PRODUCT.md (fast): If not in instructions, read .impeccable.md (or PRODUCT.md, the upstream v3.0 successor) from the project root. If either exists and contains the required context, proceed.
3. Run the teach command (REQUIRED): If neither source has context, you MUST run the teach command NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.

Register: brand vs product

Every design task is one of two registers — identify before designing:

• Brand — design IS the product. Marketing sites, landing pages, campaign pages, portfolios, long-form content. The visitor's impression IS the deliverable. Distinctive, opinionated, willing to risk strangeness. → consult brand reference for typography, palette commitment, layout license.
• Product — design SERVES the product. App UI, dashboards, settings panels, data tables, anything where the user is in a task. Earned familiarity beats novelty; the tool should disappear into the work. → consult product reference for system fonts, single-family typography, fixed scales, restrained palette defaults.

Priority for detection: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page/route/file being edited); (3) the register field in .impeccable.md / PRODUCT.md if present. First match wins.

The shared design laws below apply to both registers; the register reference adjusts the dial.

Design Direction

Commit to a BOLD aesthetic direction:

• Purpose: What problem does this interface solve? Who uses it?
• Tone: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
• Constraints: Technical requirements (framework, performance, accessibility).
• Differentiation: What makes this UNFORGETTABLE? What's the one thing someone will remember?

CRITICAL: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.

Then implement working code that is:

• Production-grade and functional
• Visually striking and memorable
• Cohesive with a clear aesthetic point-of-view
• Meticulously refined in every detail

Frontend Aesthetics Guidelines

Typography

Consult typography reference for OpenType features, web font loading, and the deeper material on scales.

Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font.