Install & get started

Install, confirm it works, then go through one full loop in your project: generate, compare, refine, undo, integrate.

00. Before you start

Git, to install and update the complete directory.
Node.js 22 or later for the bundled preview, snapshot and quality-check scripts.
A local agent that can read and write files and run commands: Codex, Claude Code or another.
A real project directory. An empty folder works too and produces standalone HTML.

01. Install the complete directory

Run this in your local terminal. Copying SKILL.md alone is not enough; keep the skills, scripts and references directories. If the target exists, inspect it instead of cloning over it.

git clone https://github.com/YuqingNicole/variant-design-skill.git ~/.codex/skills/variant-design

Use your configured skills root if different. Or run npx skills add YuqingNicole/variant-design-skill -a codex inside a project to install it there only. Reopen your Codex session after installing.

Confirm it works

First check your Node version and the installed skill version:

node --version   # requires v22+
cat ~/.codex/skills/variant-design/VERSION

Then open a fresh session in your project and send the prompt below. If the agent restates your page scope and constraints, the skill was found:

Use Variant Design to inspect this project read-only: restate the page scope, core task and brand constraints. Do not generate yet.

Repository installation notes ↗

02. Start in a real project

Open your code project in your agent and paste this prompt. Start with one page or hero. Your agent provides the model; this website does not edit your project.

Use the complete Variant Design skill. Inspect my project's structure and design system, then generate three directions A/B/C preserving core tasks. Preserve existing brand fonts and tokens; explore distinct styles if there is no brand constraint. Open previews, explain benefits, tradeoffs and fit, and give a reasoned recommendation without selecting a winner.

What you get

Three complete versions A/B/C sharing the same core task, data and necessary functions.
A comparison page and a preview URL per version. Without browser control the agent returns the exact URL.
What each version optimizes, sacrifices and suits, plus a reasoned recommendation, without picking for you. Before delivery the agent runs delivery-check.mjs on these records and on any locked brand fonts and colors.
Output goes to variant-output/ in your project: .tsx for React projects, dependency-free HTML otherwise.

03. Compare, try, undo

The comparison shows previews first, with expandable direction details. Trying an edit on a version does not select it. Send these shorthands to your agent, or describe the same intent in plain language.

Preview rebuilds and cleanup preserve existing files and your later edits. If a conflict occurs, ask your agent to keep the old files and use a fresh preview path, and include cleanup instructions with the handoff.

compare

Reopen the side-by-side comparison.

open B

Reopen B in the browser.

B vary subtle — hero

Refine only B’s hero. Snapshots first, keeps other regions and brand tokens, and does not select B.

B vary strong

Push B’s direction to its extreme.

B remix colors

Generate three alternative palettes for B.

C → mobile

Show C’s mobile view.

Mix A + B

Merge two versions and explain tradeoffs where they conflict.

undo B

Restore B’s previous files and tokens. A/C and the final selection stay unchanged.

show context

Show the remembered palette, fonts, direction and revisions.

04. Pick and integrate

pick B

Record B as the final choice, then derive a complete design system from it: palette, type scale, spacing, radius, elevation, motion, and every component B uses in all its states, with usage rules in DESIGN.md. After ds confirm, later pages build on it, and it is exported as a DTCG tokens file that Figma variables can import. Edits and selection are tracked separately.

react B

Export B as a React .tsx component.

tokens B

Export B’s design tokens as CSS variables.

Design-system checks list measured color pairs, failures and unverified coverage, and check component token layers. Brand files keep their naming. Static checks do not replace rendered page review; the token export lists values it cannot express. Confirmation preserves the original page; explicit adoption aligns code and tokens together, and undo restores both. Artifact evidence automatically tracks registered system and extension files and adoption state; changes invalidate old evidence, while other shared dependencies must be declared. Integration baselines also bind extensions and adoption state; old plans missing coverage must be prepared again.

Verification records and integration plans bind tracked shared source, styles, assets and configuration. Changes require fresh checks or plans; unresolved dependencies and missing tools must remain explicitly unverified. Online HTML and strict CLI checks share a static gate policy; passing it still does not verify rendered behavior.

Ask your agent to derive checks from the task and original brand, retain real observations before editing, then compare the result. Review which checks actually ran; missing tools or expectations remain unverified. Existing and new errors can be listed individually within a check; an existing error still fails.

Ask your agent for a delivery receipt listing the integrated files, revision, actual check results and recovery steps. File or preview changes make old receipts stale; a complete inventory does not mean every check passed. If integration or rollback stops midway, ask it to retain backups and follow recovery steps. Unknown later edits are protected, and unfinished operations cannot establish delivery acceptance.

After picking, integrate with:

Integrate B into the project. Prepare source and target baselines before staging, back up before overwriting, run the existing typecheck and build, return a working preview URL, and list changed files and how to roll back.

When integration finishes, confirm the agent reported

Which files changed and where the code lives.
How to run it and the preview URL.
The rollback command. The skill backs up the previous files in variant-output/.integrations/ and will not overwrite files you edited afterwards.
Which checks actually ran (typecheck, build, tests) and their results. Records bind the artifact revision; browser checks can reuse a plan for named elements and interactions. Anything not run should be stated.

See this site go through the whole loop ↗

05. Beyond three directions

The same skill also reviews, audits existing sites and builds components:

ux review

Heuristic usability review with issues rated by severity.

accessibility

Check WCAG 2.1 AA, keyboard navigation and contrast.

audit

Scan an existing site and report style consistency.

tokens

Extract design tokens from existing CSS.

new page pricing

Add a /pricing page that follows the current design system.

design a sign-up form component with validation

Generate a component with complete states in your project’s style.

Questions

Why is the skill missing?

Check the complete folder is in the skills root your agent uses, then open a fresh session. You can also provide the absolute SKILL.md path.

What if Node is too old?

Bundled scripts need Node.js 22+. Upgrade and reopen the session. Without Node the agent can still produce candidates, but should say snapshots and preview verification did not run.

What if a preview does not open?

Sandboxed agents such as Codex often cannot start a local server. The skill then builds a static preview you can open by double-click (variant-output/_static/), using an isolated preview package when Vite is absent and components are portable. Native Next features may still need a server. You can also run the preview command in your own terminal. Otherwise, ask the agent to check dependencies, preview routes and port, and confirm all three pages open.

Can I resume after a session ends?

Yes. The skill reads variant-output/.variant-context.json in your project and restores palette, fonts, direction and revisions. Use show context to inspect it, or reset context to start over.

How do I update?

Git clone: run git -C <install path> pull --ff-only. npx skills install: run npx skills update variant-design. You can also ask the agent to “check for Variant Design updates”; it checks at most every 24 hours and only notifies.

Does uninstalling delete my designs?

No. Designs, history and snapshots live in your project’s variant-output/. Removing the skill folder leaves them intact. reset context removes only .variant-context.json.

Is it listed in the plugin directory?

Not yet. Install the complete open-source skill today; the repository contains a plugin release candidate and readiness notes.

Your project could be next.

See the A/B/C cases ↗Explore plans & pricing →