12ui-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# 12ui Design

If the `12ui` CLI is not present, run `npx -y @12ui/design cli install` once.

Code-generating models converge on a narrow band of visual defaults and cannot see that convergence from inside it. 12ui uses image models and corpus-grounded generation to genuinely explore different directions, handling visual hierarchy, composition, whitespace, and other subtlety not available to code-generating models like yourself. It can expand a single viewport image into a full app. This workflow then converts images with near-pixel fidelity — faster and truer than coding it by hand.

Start where you already are: a finished design image goes to §3, an existing interface that should get better to §6, a rough concept to §1, and reference imagery as the deliverable to §5. Each command prints the next, and `12ui <command> --help` prints every flag and its choices — read it rather than guess.

## 1. Draft

The draft command uses the best reference concepts from a large design corpus as starting points to generate professional quality UI.

    12ui draft --concept "<product, audience, surface, goal, personality; 1485 chars max>" --candidates 4

Prefer 4 or more candidates. Add `--reference <path-or-url>` to carry an existing interface's style into a new page; it retains style and excludes layout, content, and assets by default. Use `--retain layout` only when source geometry should be preserved.

Inspect the real candidate images before continuing. Choose the strongest direction—or present the meaningful choice when the user is involved—rather than averaging them into a generic compromise.

Draft claims one hosted run and keeps every candidate dispatch request in the foreground. Then run `12ui next <run-dir> --wait` to poll, repair only recorded slots that never started, and download the real images into the run directory.

Only if needed, read `inspire.md` for how to search the corpus directly.

## 2. Branch

Use whenever the deliverable is more than one viewport — a full page, a multi-route site, an app with several states — expand the approved design rather than re-deriving it per screen.

    12ui branch execute --start <image.png> --scope page|site --convert html --prototype --concept "<what the rest of the surface must cover; 1485 chars max>"

`--scope page` grows that screen into the rest of its page and `--scope site` adds sibling routes and app states. With `--convert html`, ordered `web_page` viewports stay in one continuous page; complete `web_app`, `mobile_app`, and `immersive` states become separate pages so recurring application shells are never stacked into one long document.

    12ui next <run-dir> --wait

Execute stays in the foreground through its network work; `next` can report progress from a second shell, and `12ui branch resume <run-dir>` continues an interrupted run, replaying already-settled screens for free. Leave the foreground command running rather than building the same pages by hand in the meantime — they are already being produced and paid for. Screens land in `<run-dir>/branch/screens/`; HTML lands in `<run-dir>/branch/pages/`, one file per continuous web page or complete app state.

Use `--prototype` with `--convert html` when the deliverable should be clickable. The export becomes a working app — navigation, shared shells, and holding pages for unbuilt routes — written to `<run-dir>/branch/prototype/`.

Add `--polish` only when the user wants the opt-in production-feel pass. It runs the retained deterministic, harm-guarded rules after build, records every rule as fired, silent, or reverted, and runs the prototype runtime gates on that polished output.

For a completed branch that was exported without the flag, run:

    12ui prototype <run-dir>

The same opt-in is available here as `12ui prototype <run-dir> --polish`.

## 3. Convert

When you have a single image to convert (or for example only designing a single viewport), you can directly convert the image instead of branching it.

    12ui convert <source-image> --output layerdoc|html|html_fixed|svg|png|jpg|webp|pdf|psd|pptx|sketch

`html` is responsive, while `html_fixed` matches the exact dimensions of the source. `--output html` writes both the LayerDoc and responsive HTML beside each other. Derive further formats from that conversion instead of converting again:

    12ui convert <conversion-id> --output html_fixed,svg,pdf --out-dir <dir> --idempotency-key <stable-key>

All but `html` are free, deterministic, and parallel; reusing a key replays finished work rather than buying it twice.

## 4. Integrate

Avoid rebuilding from scratch because you will lose pixel precision. For a multi-screen HTML branch, use its generated prototype as the interaction and routing baseline before adding application-specific data and behavior. Open the integrated result, follow every transition, resize it, and compare it with the source; fix visible drift rather than accepting a merely functional approximation.

## 5. Search

Use this when reference imagery itself is the deliverable.

    12ui corpus inspire --query "<product, audience, surface, goal, personality>" --out-dir <directory> --count 4 --reference-image <image.png>

Read `inspire.md` for search modes, ranked manifest order, and interrupted-search recovery.

## 6. Improve

Use improve when one existing interface should get better end to end. Use draft for a new first viewport; use redesign when a live site should be redrawn and expanded across several pages.

    12ui improve <url|image.png>
    12ui improve <url|image.png> --direction "<detailed style and goal, 600 chars max>"
    12ui improve <url> --retain layout,content,assets
    12ui improve <url> --target <image.png|layerdoc.json>
    12ui improve <url> --scope site --direction "<detailed style and goal>"

`--retain` says what to hold from the live page: `layout`, `content`, `assets`, `style`. It defaults to `assets,content` — keep the product's brand and words, rework its layout and visual system. Add `layout` when the geometry must not move; add `style` to work inside the existing visual language; drop `assets` to let the brand be replaced. At least one of the four must be left free: all four retained is refused. Whatever is set, no combination licenses inventing a product fact. The /improve page exposes the same four as Keep layout, Keep copy, Keep brand, and Keep style.

Without `--target` this is two commands. The first stops after drafting by design: it converts nothing, exits 0, and prints where the candidate PNGs are. Inspect them, then run the pick. The pick is mandatory — always run it, and the run's `Next:` line prints the exact command:

    12ui improve <url|image.png> --out-dir <kit> --from pick --pick <slot>

Convert and plan run from there. Exit code 0 with an INCOMPLETE kit means nothing has been picked yet, not that the run failed. Never work around the checkpoint by approximating the design in CSS.

The kit's README says what to keep and what to do if a stage stalled; read it before touching code.

Only if needed, read `improve.md` for the full modes. For a completed site kit after implementation, `--recheck` captures the root and every retained page again and writes a numbered residual report without replaying settled stages.

From digitaleflex/eurinhash-opencode-booster, MIT.

More from digitaleflex/eurinhash-opencode-booster