v1.2.0 to v1.3.0

---

name: opendesign

description: "Generate polished single-file HTML design artifacts using the nexu-io/open-design catalog of production skills and brand-grade design systems. Use when the user asks to design, mock up, prototype, draft, build, or render a visual web artifact, chooses a brand/style direction, requests a deck/PPT, hero, section, component, marketing page, dashboard, email, doc page, or GitHub README/repo banner. Auto-opens the result for review. Produces editable HTML/CSS; use vd:marketing-design for AI-generated raster brand imagery."

license: MIT

argument-hint: "<design prompt> [--style <design-system>] [--no-open]"

metadata:

author: vanducng

---

# opendesign

Compose a single self-contained HTML artifact from the upstream `nexu-io/open-design` catalog: pick the closest **skill** (workflow + seed template + section layouts), apply a **design system** (color tokens, typography, components), produce the artifact, open it in the browser.

## Scope

**This skill handles:** static HTML/CSS/SVG artifacts (landings, marketing pages, dashboards, mobile screens, decks, posters, emails, e-guides, internal docs).

**Does NOT handle:** live React/Vue apps or backend wiring (use `vd:uiuxdesign` or `vd:fastreact`), AI-generated raster brand imagery (use `vd:marketing-design`), multimodal media (use `vd:omnimedia`), production release work (use `vd:ship`).

**Special case - GitHub README / repo hero banner:** the catalog has no banner template (`search` returns social-cards that override the repo's brand). Skip the catalog and follow `references/github-readme-banner.md` - author/evolve a brand-locked `banner.html`, render to PNG at 2× via headless Chrome, and **verify the render (measure margins + view) before shipping**.

## Dependencies

## Workflow

### Step 0 - Resolve the bundled CLI path (do this once)

```bash

OPENDESIGN_BIN="<dir-of-this-SKILL.md>/scripts/opendesign"

```

All subsequent commands use `"$OPENDESIGN_BIN"`.

### Step 1 - Sync the catalog (first run, or when user asks for fresh content)

```bash

"$OPENDESIGN_BIN" sync

```

This clones (first time) or `git pull --ff-only`s the upstream sparse checkout of `skills/` + `design-systems/`. Offline-tolerant: falls back to existing cache silently.

### Step 2 - Search for the best matching skill + design system

Pass the user's full design prompt verbatim:

```bash

"$OPENDESIGN_BIN" search "<user's prompt>"

```

- **One skill** - usually the top-ranked. If user mentioned a surface explicitly (deck, dashboard, email, mobile), bias toward that.

- **One design system** - top-ranked, OR honor an explicit user request (e.g. "in Linear's style" → `linear-app`).

State the picked pair to the user in one sentence before reading files. They can redirect cheaply now.

### Step 3 - Resolve cache paths

```bash

SKILL_PATH=$("$OPENDESIGN_BIN" show <skill-name>)

DS_PATH=$("$OPENDESIGN_BIN" show <design-system-name>)

```

### Step 4 - Read the upstream files

Two package shapes exist; check which one your picks resolved to (`ls "$SKILL_PATH" "$DS_PATH"`) and follow the matching path.

**A - Skill + seed template** (classic; most catalog *skills*):

1. `$SKILL_PATH/SKILL.md` - the chosen skill's own workflow. **Follow it literally.** It names the classes, layouts, and checks to use.

2. `$SKILL_PATH/assets/template.html` - the seed (pre-built tokens + class system + chrome). Always use this; never write CSS from scratch.

3. `$SKILL_PATH/references/layouts.md` - paste-ready section skeletons (don't invent sections; pick the closest).

4. `$SKILL_PATH/references/checklist.md` - the P0/P1/P2 self-review (run before emitting).

5. `$SKILL_PATH/example.html` - exemplar output (skim for visual reference).

6. `$DS_PATH/DESIGN.md` - color palette, typography stack, spacing, component patterns.

**B - Design System 2.0 package** (modern *design-systems* like `dashboard`, `linear-app`; and the fallback when the picked **skill has no `assets/template.html`** - many catalog skills ship only `SKILL.md`). The design-system package stands alone - read it in this order and compose from it directly, no skill template needed:

1. `$DS_PATH/USAGE.md` - the package contract + read order.

2. `$DS_PATH/DESIGN.md` - visual intent, constraints, anti-patterns.

3. `$DS_PATH/tokens.css` - **paste verbatim into the artifact's first `<style>` block**; this is the design system. (`tailwind-v4.css` / `design-tokens.json` are the same tokens in other formats for a React/Tailwind port.)

4. `$DS_PATH/components.manifest.json` - the component inventory; compose **only** from these recipes. Open `$DS_PATH/components.html` (often large - `grep` it) when you need exact selectors/states.

5. `$DS_PATH/preview/` - visual sanity check.

### Step 5 - Compose the artifact

**Path A (skill + template):** copy `template.html` → `<output>.html`; replace `:root` vars with `DESIGN.md` tokens; swap `<title>` + brand; paste `layouts.md` sections into `<main>`, replace every `[REPLACE]` with real copy (no filler); run `checklist.md` - every P0 must pass.

**Path B (Design System 2.0 - the winning pattern for app/dashboard/console surfaces):**

1. Start the file with `tokens.css` pasted verbatim into `<style>`. **Preserve every token *name* exactly** (cross-brand switching depends on it).

2. **Re-skin only the *values*** in the `:root` block to the user's brand - pick one accent and use it at most twice per region, derive hovers via `color-mix()` on tokens (no new raw hex outside `:root`), set surface ramp + radii + font stack. Everything else stays token-driven.

3. Build the layout **only** from `components.manifest.json` recipes; semantic primitives the spec demands but the manifest lacks (`<table>`, `<nav>`) are fine, invented decorative components are not.

4. Fill with real domain data from the brief - no lorem.

5. Self-review (P0): token names preserved (diff against the source `tokens.css`), no off-palette hex outside `:root`, one-accent-per-region holds, no invented components, no filler, a11y landmarks + visible focus + AA contrast.

### Step 6 - Preview the result

Unless the user passed `--no-open` or explicitly said not to open it:

```bash

"$OPENDESIGN_BIN" preview <output>.html

```

### Step 7 - Iterate to a quality bar (optional, high-stakes artifacts)

A single composition rarely clears a "hatchet.dev/Linear-grade" or ">9/10" bar - first drafts land ~8.5-8.8. When the user sets a bar, loop: render to PNG (headless Chrome / `browse screenshot --full-page`) → score it against concrete lenses (visual craft, information design, brand distinctiveness, implementability) → apply **every** defect including nits (at this band the nits *are* the gap) without breaking the Path-B contract → re-render → re-score. Independent scorers (a judge panel) beat self-review; budget 2-3 rounds. Treat remaining minors that belong to the eventual React build (responsive recipes, aria-live, drill-ins) as carry-forward notes, not blockers on the static mock.

## Hard rules

- **Never invent CSS classes** the upstream `template.html` doesn't define. If a class is missing, add it to `<style>` once, never inline.

- **Never write a section from scratch.** Use `layouts.md` skeletons. If none fit, pick the closest and adapt copy.

- **Never use design tokens not in the chosen `DESIGN.md`.** No off-palette colors, no off-stack fonts.

- **One accent per screen, used at most twice** (per upstream convention).

- **Single self-contained HTML file.** No external CSS/JS imports, no build step. Inline SVGs, base64 images only if the user provides them.

- **No filler copy.** If a layout slot has no real content from the user's brief, drop the section.

## Security