@12ui/design 0.2.0

package/skills/design/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: design
+description: "REQUIRED for all visual interface tasks (UI, Web, Mobile). Uses design-search to find high-quality references with strong UX and personality, image generation to explore distinctive directions, and design-convert to turn the chosen design into ready-to-use code quickly. Use for creating, redesigning, or implementing interfaces; it routes finished screenshots directly to conversion and keeps tiny edits code-only."
+---
+
+# Design
+
+Author the visual direction before implementing it. Code-first agents tend to
+settle on safe, generic visual defaults. Corpus-conditioned image generation
+introduces personality and a wider design vocabulary; converting the selected
+image then preserves that direction with near-pixel-perfect fidelity much
+faster than manually recreating it in code.
+
+This skill orchestrates `design-search`, image generation, `design-convert`,
+project integration, and visual verification. It is for UI, web, and mobile
+interfaces.
+
+## Route the request
+
+Inspect the input and the target repository, then choose exactly one route:
+
+- **Finished screenshot or mockup:** invoke the `design-convert` workflow
+  directly. Do not search or generate alternatives.
+- **Small visual edit:** edit the existing project code directly. Do not make a
+  paid corpus, image-generation, or conversion call.
+- **Rough brief, new interface, or major redesign:** run the complete authored
+  workflow below.
+
+If the route is unclear, prefer the least expensive route that can satisfy the
+request. A request changes to the complete workflow only when it needs a new
+visual direction, not merely because design work is involved.
+
+## Complete authored workflow
+
+### 1. Prepare
+
+1. Inspect the repository instructions, framework, routes, styling, reusable
+   components, assets, package manager, validation commands, and current user
+   changes.
+2. Create an isolated run directory, using the repository's scratch convention
+   or `.12ui-design/runs/<run-id>`.
+3. Write `brief.txt` with the product and audience, required content and
+   interactions, exact copy, intended surface and viewport, desired
+   personality, accessibility needs, and prohibited brands or copied text.
+4. Use one CLI installation and one account/origin throughout the run. Verify
+   it with `12ui auth status` and `12ui capabilities --json`.
+
+Never substitute cached examples, invented corpus entries, placeholder images,
+or mock conversion output for a real run.
+
+### 2. Retrieve exactly four references
+
+Invoke `design-search` with `--count 4`, saving its result under
+`<run-dir>/references`. The complete authored workflow always requires four
+distinct, successfully downloaded real corpus images. Preserve the returned
+order and metrics.
+
+If the search request is interrupted or ambiguous, use `12ui corpus resume`
+with the saved output directory and original origin. Do not delete evidence,
+start a replacement request, or spend another search for the same unchanged
+brief.
+
+### 3. Generate exactly four candidates
+
+Create four frozen prompt files, one each for candidates A through D. Every
+prompt must:
+
+- attach and identify all four local corpus reference images;
+- preserve the brief's required content, exact copy, interactions, surface, and
+  viewport;
+- ask for a shippable interface rather than a mood board, wireframe, device
+  scene, or perspective presentation;
+- use abstract composition, spacing, hierarchy, color relationships, material,
+  and typographic energy without copying brands, logos, names, or text;
+- keep controls plausible, text legible, and states accessible; and
+- prohibit watermarks and invented product claims.
+
+Give every candidate all four references. Rotate which ordered reference is the
+primary visual anchor: reference 1 for A, 2 for B, 3 for C, and 4 for D. The
+other three remain active secondary references.
+
+Dispatch the four candidates in parallel. Use the host's built-in imagegen
+tool when it is available. Otherwise, invoke one `12ui image generate`
+operation per candidate with its prompt file, all four repeated reference
+arguments, a unique output path, the project root, an explicit
+`--aspect landscape|portrait|square` matching the target surface, the
+preselected provider, and a stable idempotency key. Check
+`12ui image generate --help` for the installed version's exact flag spelling.
+
+Run the four operations beneath one joinable foreground parent and wait for
+all four to finish before the host turn exits. In a noninteractive coding
+agent, use its supported foreground task-group primitive, `Promise.all`, or a
+shell parent that explicitly `wait`s for every child. Never leave generation
+as detached background work: the host may tear those processes down after the
+turn, leaving dispatched evidence without a recoverable provider result. If
+the host cannot guarantee that join, stop before dispatch and report the
+limitation.
+
+Select the provider before dispatch:
+
+- built-in imagegen when the host exposes it;
+- otherwise authenticated Codex image generation after successful
+  `codex --version` and `codex login status` preflights; or
+- otherwise `gpt-image-2` only when `OPENAI_API_KEY` is available in the
+  process or exactly `<project-root>/.env` and the CLI's safety checks pass.
+
+Never switch providers after dispatch. Preserve attempt evidence and stop on a
+failed or ambiguous operation. Do not replace a candidate generated without
+all four references. Save the original returned bytes under
+`<run-dir>/candidates`, retain their real formats, and hash them immediately.
+
+### 4. Choose the winner
+
+The host agent inspects all four candidates at original detail against the
+brief. Reject any candidate that omits required content, copies reference
+identity or text, has implausible UX, contains illegible output, or cannot be
+implemented on the requested surface.
+
+Choose the strongest eligible direction using visible evidence: fulfillment of
+the brief, hierarchy and usability, distinctiveness and personality,
+accessibility, and feasibility. This is a host-agent design decision; do not
+delegate the decision to an external evaluator.
+
+Before conversion, write `<run-dir>/selection.json` following
+[the selection contract](references/selection-contract.md). It must preserve
+the exact prompts, reference IDs, candidate paths and SHA-256 hashes, selected
+winner, rejection reasons for every non-winner, and a concise rationale tied to
+visible features.
+
+### 5. Convert only the winner
+
+Invoke `design-convert` once for the winning bitmap. Use a stable idempotency
+key derived from the project identity, winner digest, target, viewport, and
+workflow revision. Preserve the base conversion ID and its durable evidence.
+
+If conversion fails or its outcome is ambiguous, diagnose or resume that
+operation. Do not convert another candidate merely to bypass the failure.
+
+### 6. Integrate and verify
+
+1. Inspect generated files and assets before copying them.
+2. Merge the smallest coherent set into the target, preserving its routing,
+   components, tokens, dependency policy, accessibility conventions, and
+   unrelated user changes.
+3. Remove duplicate generated scaffolding after integration.
+4. Run focused typecheck, tests, lint, and build checks in parallel when their
+   outputs do not conflict.
+5. Launch the real interface and exercise its interactions.
+6. Compare the implementation with the winning image at the source viewport
+   and representative narrower and wider viewports. Correct integration defects
+   in project code and retain evidence for conversion defects.
+
+Report the corpus idempotency key, set ID, and reference IDs, four candidate
+paths and hashes, selected winner and rationale, base conversion ID, integrated
+files, launched examples, validation results, and any remaining visual
+differences.

package/skills/design/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "12UI Design"
+  short_description: "Author distinctive interfaces from visual references"
+  default_prompt: "Use $design to create and implement a distinctive interface from this brief."
+policy:
+  allow_implicit_invocation: true

package/skills/design/references/selection-contract.md

@@ -0,0 +1,44 @@
+# Selection evidence contract
+
+Write `selection.json` before converting a candidate. Use absolute candidate
+paths so a resumed run cannot select the wrong file. Keep exact prompt text and
+SHA-256 digests; do not replace them with summaries.
+
+The document has this shape:
+
+```json
+{
+  "version": 1,
+  "createdAt": "<ISO-8601 timestamp>",
+  "briefSha256": "<SHA-256>",
+  "corpus": {
+    "idempotencyKey": "<stable corpus inspiration key>",
+    "setId": "<returned set ID>",
+    "referenceIds": ["<id-1>", "<id-2>", "<id-3>", "<id-4>"]
+  },
+  "candidates": [
+    {
+      "id": "A",
+      "path": "<absolute original-image path>",
+      "sha256": "<SHA-256>",
+      "prompt": "<exact generation prompt>",
+      "referenceIds": ["<id-1>", "<id-2>", "<id-3>", "<id-4>"],
+      "primaryReferenceId": "<id-1>",
+      "provider": "<selected provider>",
+      "idempotencyKey": "<stable key>",
+      "attemptEvidencePath": "<absolute path when CLI-generated>",
+      "rejectionReasons": []
+    }
+  ],
+  "winner": "A",
+  "rationale": "<concise rationale based on visible features>"
+}
+```
+
+Include exactly four candidate objects and four reference IDs in endpoint
+order. Copy `corpus.idempotencyKey` and `corpus.setId` from the completed
+inspiration manifest; neither value may be invented or replaced by an internal
+request identifier. For each non-winner, `rejectionReasons` must contain at
+least one specific visible reason. The winner must have an empty
+`rejectionReasons` array. Record provider and attempt evidence for auditability;
+do not store API keys or other secrets.

package/skills/design-convert/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: design-convert
+description: "Convert a PNG, JPEG, or WebP image into a structured LayerDoc with associated assets, then export responsive HTML, web or native app code, PDF, PSD, PPTX, Sketch, SVG, PNG, JPEG, or WebP. Use to recreate a finished design or turn a visual reference into production-ready output quickly."
+---
+
+# Design Convert
+
+Convert one finished source image once, preserve its base LayerDoc conversion,
+then export every required representation from that same structured source.
+Integrate code output into the target repository and verify fidelity and
+behavior.
+
+## Prepare
+
+1. Accept a static, non-interlaced PNG, JPEG, or WebP source.
+2. Inspect its dimensions and intended CSS viewport. For a high-density mobile
+   capture, use the intended layout width rather than device pixels.
+3. Inspect the target repository's instructions, framework, styling, language,
+   routes, package manager, components, assets, and validation commands.
+4. Run `12ui auth status` and `12ui capabilities --json`.
+5. Select only capabilities and exact project profiles the installed CLI
+   reports.
+6. Derive a stable idempotency key from the project, source-image SHA-256,
+   viewport, model, and conversion revision.
+
+Never invent output, substitute cached results, or repeat extraction to produce
+another format. If an operation fails or is ambiguous, preserve its conversion
+ID and evidence, then diagnose or resume it.
+
+## Create one base LayerDoc conversion
+
+Create the structured source once:
+
+```bash
+12ui convert <source-image> \
+  --output layerdoc \
+  --model standard \
+  --width <intended-css-width> \
+  --idempotency-key <stable-key> \
+  --out <run-dir>/base.layerdoc.json
+```
+
+Preserve the returned source conversion ID, LayerDoc, associated asset
+directory and manifest, request evidence, and exact source digest. This
+conversion ID is the source for all later exports.
+
+Use `--detach` for long operations and finish the same operation with
+`12ui resume <conversion-id>`. Do not submit a new conversion when resume can
+unambiguously continue the existing one.
+
+## Export from the base conversion
+
+Export one or more supported outputs with:
+
+```bash
+12ui export <source-conversion-id> \
+  --output <format> \
+  --out-dir <destination-directory> \
+  --idempotency-key <stable-export-key>
+```
+
+Supported formats are responsive HTML, web or native app code, PDF, PSD, PPTX,
+Sketch, SVG, PNG, JPEG, and WebP. Request only formats reported by
+`12ui capabilities --json`.
+
+Independent exports may run in parallel because they all reference the same
+immutable base conversion. Reuse the source conversion ID; never repeat image
+extraction for export fan-out.
+
+Web and native project exports require an exact capabilities-derived profile:
+
+```bash
+12ui export <source-conversion-id> \
+  --output web_project \
+  --web-profile '{"version":1,"framework":"react","styling":"tailwind","language":"typescript","packaging":"page"}' \
+  --out-dir <run-dir>/web-export \
+  --idempotency-key <stable-web-export-key>
+```
+
+```bash
+12ui export <source-conversion-id> \
+  --output app_project \
+  --app-profile '{"version":1,"framework":"expo","styling":"native","language":"typescript","packaging":"screen"}' \
+  --out-dir <run-dir>/native-export \
+  --idempotency-key <stable-native-export-key>
+```
+
+Never guess a profile or silently change it after dispatch. Preserve every
+export conversion ID and its relationship to the one base source conversion.
+
+## Integrate code output
+
+1. Extract generated project archives into an isolated temporary directory.
+2. Inspect files and dependencies before copying them.
+3. Merge the smallest coherent set into the target repository. Preserve
+   existing routing, tokens, components, accessibility patterns, dependency
+   policy, and unrelated user changes.
+4. Reuse repository-owned assets and primitives where they are the source of
+   truth.
+5. Remove duplicate generated scaffolding after integration.
+
+## Verify
+
+- Run focused typecheck, tests, lint, and build checks in parallel when their
+  outputs do not conflict.
+- Launch every generated web or native example and exercise its interactions.
+- Compare the launched result with the source at the intended viewport plus
+  representative narrower and wider viewports.
+- Render or open PDF, PSD, PPTX, and Sketch artifacts with appropriate tooling;
+  inspect their structure, dimensions, assets, and visible fidelity.
+- Inspect SVG and raster exports at original resolution.
+- Correct integration defects in project code. For a conversion defect,
+  preserve the conversion ID and visible evidence before deciding whether a
+  changed source or conversion revision warrants a new base conversion.
+
+Report the source digest and base conversion ID, associated assets, every
+export format/profile/conversion ID, integrated files, launches and
+interactions, validation results, and remaining visual differences.

package/skills/design-convert/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "12UI Design Convert"
+  short_description: "Turn a finished design into structured output"
+  default_prompt: "Use $design-convert to convert this finished interface image and integrate the result."
+policy:
+  allow_implicit_invocation: true

package/skills/design-search/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: design-search
+description: "Search the 12UI Design Corpus from a rough UI, web, or mobile concept and return a pre-explored, ranked, diverse set of reference images. Use before visual generation or implementation when the design needs high visual quality, sound UX, and more personality."
+---
+
+# Design Search
+
+Turn a rough interface concept into real, local visual-reference files using
+the authenticated 12UI Design Corpus. The service has already explored,
+ranked, and diversified the design space. Preserve its result order and
+metrics; do not invent a second ranking.
+
+## Prepare the query
+
+Write a concise query file that describes:
+
+- product, audience, and user goal;
+- surface: UI, web, or mobile;
+- required content and interactions;
+- desired personality, visual energy, and useful contrasts; and
+- target viewport when known.
+
+Do not name brands to imitate or ask to copy logos, names, or text. Corpus
+images are inspiration rather than templates. Preserve the usage notice
+returned by the service.
+
+Verify the account with `12ui auth status`. Keep one CLI installation and one
+origin for the entire request and any resume.
+
+## Search
+
+Standalone search defaults to four references. Respect an explicit requested
+count instead of forcing four:
+
+```bash
+12ui corpus inspire \
+  --query-file <query.txt> \
+  --out-dir <references-dir>
+```
+
+For an explicit count:
+
+```bash
+12ui corpus inspire \
+  --query-file <query.txt> \
+  --count <requested-count> \
+  --out-dir <references-dir>
+```
+
+Add `--origin <origin>` only when targeting a specific verified deployment.
+Use `--wildness` only when the user or orchestrating workflow requests it. Do
+not add guessed filters that could turn a metered request into an empty set.
+
+`corpus inspire` reserves the output directory, saves request and response
+evidence, downloads full images, and writes `manifest.json`. Confirm the
+manifest count, unique IDs, decodable image files, and digest receipts.
+
+Return references in the exact endpoint order. Report the endpoint-provided
+rank, distance, diversity, quality, or other metrics exactly as returned. Do
+not recalculate, reorder, average, normalize, or silently discard entries.
+
+## Resume without another search
+
+If an attempt is interrupted, ambiguous, or only partly downloaded, retain its
+directory and run:
+
+```bash
+12ui corpus resume --out-dir <references-dir>
+```
+
+Pass the exact original `--origin` when the attempt recorded one. Resume reuses
+the saved idempotency key and completes the same operation or downloads. Do not
+delete evidence, start a replacement request, or overwrite bytes that disagree
+with their saved digest.
+
+If `manifest.json` already exists, verify and reuse it. If the response is
+underfilled, duplicated, corrupt, or still ambiguous after resume, report the
+stable idempotency key and evidence path and stop. Never fill missing slots
+with cached or invented references.
+
+## Handoff
+
+Provide the manifest path, stable idempotency key, returned set ID, ordered
+reference IDs, local image paths, exact returned metrics, usage notice, and
+resume evidence. When called by `design`, it must hand back exactly four valid
+references before generation can begin.

package/skills/design-search/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "12UI Design Search"
+  short_description: "Find ranked, distinctive UI reference images"
+  default_prompt: "Use $design-search to find diverse visual references for this interface concept."
+policy:
+  allow_implicit_invocation: true