ui-artifact-workspace

# ui-artifact-workspace

Use this skill for every standalone UIDesigner artifact, regardless of final format, and for every follow-up that revises a previously created artifact. It is the continuity and packaging contract around the visual skills; it does not decide the visual direction itself.

The goal is one canonical artifact, one stable directory, and small traceable revisions. Do not scatter HTML, images, notes, and data across the workspace root. Do not make the user identify the same artifact again on every turn.

## Follow-Up Non-Negotiable

Every revision response must preserve all three proof groups together; missing any group blocks delivery:

1. **Canonical reuse**: read the current manifest/entry/assets and patch the same directory in place.
2. **Preservation**: explicitly say `fork/v2: forbidden` and preserve named user edits plus unrelated hooks, interactions, tokens, and asset paths.
3. **Revision acceptance**: requested visual change or state plus non-blank first render, requested viewport behavior, and local asset/reference resolution; increment the manifest once only after all pass.

When tools are off, emit the Revision Executor Contract near the start of the response. Every check remains `not run` but still includes its future action and concrete pass criterion. Do not output a replacement manifest with guessed fields or a reduced `files` list; describe the pending revision delta until the existing manifest has been read.

## Choose The Canonical Workspace

Resolve the mode before editing:

1. **Follow-up to an existing artifact**: reuse the exact artifact directory from the user's path, the current conversation, or its `artifact.json`. Inspect it before changing anything.
2. **Implementation inside an existing app repo**: the real app source remains canonical. Edit the existing components, tokens, and routes in place; do not create a parallel copy that can drift. Create a standalone `ui-artifacts/<task-slug>/` preview only when the user also asks for a shareable design artifact.
3. **New standalone artifact**: create `ui-artifacts/<task-slug>/` under the current writable workspace or supplied repo root. Use a short stable kebab-case slug derived from the product or feature, not a timestamp.

Never put a new standalone artifact directly in the workspace root. Never create `-v2`, `-final`, `-final-final`, or a timestamped sibling for an ordinary revision. A new sibling is valid only when the user explicitly asks to preserve the old version, compare alternatives, or fork the direction.

If several plausible prior artifact directories exist and the conversation does not identify one, inspect their manifests first. Ask one focused question only when the choice remains genuinely ambiguous.

## Resolve The Final Format

- Default to `html` when the user does not specify a format.
- Honor an explicit alternate format such as SVG, PDF, React, Vue, PNG, or Markdown instead of forcing an HTML final.
- The independent directory rule still applies to alternate formats.
- For target-repo implementation, follow the existing framework and file types. Do not wrap a requested React/Vue implementation in a separate HTML export unless the user also wants a standalone preview.

The manifest `format` and `entry` must match the actual deliverable. Supporting HTML previews may accompany an explicitly requested non-HTML final, but must not silently replace it.

## Minimal Directory Contract

For a default standalone HTML artifact:

```text
ui-artifacts/<task-slug>/
  index.html
  artifact.json
  assets/              # only when local assets exist
```

Add files only when the task needs them:

- `DESIGN.md` for reusable multi-screen/system/brand work, formal handoff, or an explicit user request. Do not create it for an ordinary single-screen fast-path artifact.
- `data/` and provenance files for a live-ready artifact, following `ui-live-artifact`.
- Local CSS/JavaScript modules when a self-contained `index.html` would become fragile or hard to edit.
- Source-specific entry files for an explicit alternate format.

Prefer a self-contained `index.html` for small and medium one-off designs. Split files when doing so materially improves maintainability, multi-screen structure, or incremental edits. Do not add a build system, dependency lockfile, or package manager just to render a standalone artifact.

## Artifact Manifest

Every standalone artifact directory must contain valid `artifact.json`. Keep it compact and machine-readable:

```json
{
  "schema_version": 1,
  "artifact_id": "ui-renewal-risk-workbench",
  "title": "Renewal risk workbench",
  "format": "html",
  "entry": "index.html",
  "revision": 1,
  "created_at": "<ISO-8601>",
  "updated_at": "<ISO-8601>",
  "design": {
    "system_source": "existing-repo | supplied-reference | contract | one-off",
    "direction": "<short visual thesis>",
    "fixed_decisions": ["<decisions later revisions should preserve>"]
  },
  "files": ["artifact.json", "index.html"]
}
```

Keep the fenced manifest strict JSON. Put a path label before the fence; never put `// path`, comments, trailing commas, or Markdown inside the JSON block.

Rules:

- Keep `artifact_id`, directory name, `created_at`, and entry path stable across normal revisions.
- A new artifact starts at revision 1 in its first valid manifest; initial validation and preview keep it at revision 1. For a follow-up, keep baseline revision N while editing, then move exactly once to N+1 after acceptance; update `updated_at` and refresh `files` with that transition.
- Treat `files` as the complete sorted package inventory. It must include `artifact.json` itself, the entry, and every shipped relative asset/source file; omit only generated ZIPs and temporary QA files.
- Record only compact design continuity facts. Do not store full prompts, chat transcripts, secrets, credentials, cookies, auth headers, or raw provider responses.
- Prefer relative paths. Do not embed machine-specific absolute paths