ux-ui-design

HTML/CSS/JS mockup-first UI/UX design for Claude Code, OpenAI Codex, and Pi.

This plugin makes agents generate standalone single-file HTML mockups in .mockups/ before any UI code is written. Mockups are throwaway artifacts — they exist for alignment, not deployment. You compare options, walk through flows, and lock in a design direction; then the implementer translates the chosen mock into your real stack later.

What's in the box

Skills, all installable in Claude Code, OpenAI Codex, and Pi through the shared skills/ directory:

Skill	Trigger	What it does
ux-ui-principles	auto-loads when UI design comes up	Reference: storage layout, decision matrix, linking convention, tech rule. Installs the rule into project CLAUDE.md on first run.
screens	/ux-ui-design:screens or "give me 4 options for X"	Generates 4 distinct HTML mockups for one screen, opens a 2x2 comparison grid, asks for a pick or hybrid.
flows	/ux-ui-design:flows or "mock the signup flow"	Generates a numbered sequence of HTML pages with prev/next chrome and an index navigator.
palette	/ux-ui-design:palette or "design a palette"	Generates color + typography options as HTML previews, locks the choice into a reusable tokens.css.

Output layout

Every project that uses this plugin gets the same .mockups/ shape:

.mockups/
  design-system/
    palette.html        # color preview with multiple options + WCAG check
    typography.html     # font preview + scale
    tokens.css          # locked-in CSS custom properties for all mocks
  screens/
    <feature-id>/
      option-1.html
      option-2.html
      option-3.html
      option-4.html
      index.html        # 2x2 iframe grid for side-by-side review
  flows/
    <flow-name>/
      01-<step>.html
      02-<step>.html
      ...
      index.html        # linear navigator across the flow

<feature-id> matches the agile-workflow item id when applicable, else a kebab-case slug.

Tech rule

• One .html file per mock. Vanilla CSS in <style>, vanilla JS in <script>.
• No build step, no CDN, no npm packages, no CSS framework.
• Optional <link rel="stylesheet" href="../../design-system/tokens.css"> — that one local CSS is the only allowed external reference.
• Self-contained so the file opens in any browser, offline, years from now.

Mockup-first decision matrix

The ux-ui-principles skill carries the full matrix. TL;DR:

REQUIRED — net-new UI surface, design-system changes, epics with multi-screen user flows.

OPTIONAL — feature-level UI that reuses existing components and patterns (use judgment).

SKIP — bug fixes with no visual change, copy edits, backend-only features, behind-the-scenes refactors.

Integration with agile-workflow (loose)

When agile-workflow is also installed, the design family skills follow a tier-ordering rule — mock at the highest tier where it can land:

• agile-workflow:scope — large UI scope: invokes :palette and :flows for cross-feature journeys clear at scope time.
• agile-workflow:epic-design — primary tier. Invokes palette + screens + flows across the decomposition. --only-questions always runs this pass.
• agile-workflow:feature-design — fallback. Inherits parent-epic mocks; only invokes :screens/:flows for minor surfaces not covered upstream.
• agile-workflow:ideate — recommends :palette after foundation docs for UI projects.

When mocks are generated for a substrate item, a ## Mockups section is added to the item body pointing at the relevant paths. Linking is via path convention + optional mockups: frontmatter field — agile-workflow doesn't parse the field, so no schema coupling.

When agile-workflow is NOT installed, all four skills work fine standalone. Path resolution falls back to kebab-case slugs.

Installation

Claude Code

/plugin marketplace add nklisch/skills
/plugin install ux-ui-design@nklisch-skills

Codex CLI

codex plugin marketplace add https://github.com/nklisch/skills
codex plugin install ux-ui-design

Pi

pi install npm:@nklisch/pi-ux-ui-design

# Local checkout/development install
pi install -l ./plugins/ux-ui-design

All three channels consume the same shared skills/ directory. This plugin has no Pi-only executable extension; Pi receives the same mockup-first skills as Claude Code and Codex.

Bootstrap a project

After install, any of these will trigger the ux-ui-principles skill to offer appending the design-convention block to your project's AGENTS.md, using CLAUDE.md only as a compatibility target when that is the existing agent-instructions file:

• "design the login screen"
• /ux-ui-design:screens login
• /ux-ui-design:palette

The append is idempotent — controlled by a <!-- ux-ui-design:installed --> marker.

When NOT to use this

• Production code generation — these are throwaway mocks, not React/Svelte components.
• Highly interactive prototypes that need real state, fetches, or routing — use a real stack.
• Pixel-perfect comps for handoff to a separate visual designer — use Figma (or the figma MCP) for that.

This plugin sits in the gap: more structured than whiteboard sketches, less work than building a real prototype, opens-in-any-browser portable.