unship

# Unship

## Overview

Unship is a local workflow for comparing AI-generated UI alternatives in the real application instead of accepting one generated version at a time. It adds temporary source-level variants, shows a local browser picker, and then cleans up the unused options after the user chooses.

This skill is for frontend iteration with coding agents. It is not production A/B testing, analytics, feature flagging, or a hosted experiment service.

## When to Use This Skill

- Use when the user wants to compare multiple UI, layout, copy, state, flow, or design-system alternatives.
- Use when a coding agent should create several temporary options in real source code and let the user judge them in the running local app.
- Use when the user chooses a visible option and wants the losing temporary code removed before shipping.

## Do Not Use This Skill When

- The user needs production experiments, traffic splitting, analytics, or feature flags.
- The app cannot safely render inactive hidden variants because of duplicate active IDs, global scripts, analytics triggers, focus traps, destructive actions, or autoplay side effects.
- The user has not authorized local source edits.

## How It Works

### 1. Install or reuse Unship

Prefer the project-local binary when it exists:

```bash
./node_modules/.bin/unship doctor --json --no-update-check
```

Otherwise use the npm package without assuming a global binary:

```bash
npx -y @unship/cli@latest doctor --json --no-update-check
```

If setup is needed for the local picker, run:

```bash
npx -y @unship/cli@latest setup --json
```

Patch only the smallest development-only mount point required to load the picker in the local preview.

### 2. Create temporary variants

Inspect the relevant page, component, route, or rendered artifact. Add the smallest source-level comparison that lets the user judge real options in context.

Use Unship markup:

```html
<section data-unship-pick="Hero">
  <div data-unship-option="Current">...</div>
  <div data-unship-option="Proof-led" hidden>...</div>
  <div data-unship-option="Visual" hidden>...</div>
</section>
```

Keep option labels short and visible. Prefer 2-4 meaningful alternatives unless the user asked for a specific count.

### 3. Verify comparison readiness

Before handing off to the user, check that:

- the expected `data-unship-pick` group exists;
- the expected option labels exist;
- options are direct children of the group;
- exactly one option is initially visible;
- hidden inactive options remain hidden.

### 4. Let the user choose

Tell the user the group label, option labels, setup status, and any detected local preview server hints. The user chooses by naming a visible option label in chat.

### 5. Clean up after selection

When the user picks a winner, keep that option's real source and remove losing options for that group. Remove temporary `data-unship-*` attributes from settled source.

For final cleanup before shipping, remove all Unship artifacts and run:

```bash
npx -y @unship/cli@latest check --json
```

Do not claim cleanup is complete until the check reports clean.

## Best Practices

- Keep Unship work local and temporary.
- Preserve the existing app design language unless the user explicitly asks for a different direction.
- Avoid unrelated refactors while variants are temporary.
- Do not put custom tabs, app preferences, or permanent switchers into product UI for Unship comparisons.
- Keep inactive options safe: avoid duplicate active IDs, submit controls, global scripts, analytics triggers, focus traps, destructive side effects, and stateful providers.

## Limitations

- Unship does not decide which variant wins; the human chooses.
- Unship does not replace design review, browser QA, accessibility checks, or production release validation.
- Unship is not intended for production traffic, remote analytics, or persistent product experiments.

## Security & Safety Notes

- Run commands only in a local project the user has authorized you to modify.
- Treat generated variants as temporary code that must be cleaned before release.
- Before destructive cleanup, confirm the selected option label when the user's choice is ambiguous.
- If a baseline build or typecheck already fails before Unship edits, report that baseline state and keep variant work isolated.

## Common Pitfalls

- **Problem:** Hidden variants override `hidden` with CSS.
  **Solution:** Preserve `[hidden] { display: none !important; }` near variant-specific CSS when needed.

- **Problem:** The user says "keep the second one" after more changes.
  **Solution:** Confirm the exact group and option label before editing source.

- **Problem:** The comparison grows into a broad redesign.
  **Solution:** Reduce scope to the smallest section, state, or flow that can be judged in the running app.

## Related Skills

- `@webapp-testing` - Use for browser-based functional checks after frontend changes.
- `@mobile-design` - Use when comparing mobile-specific UI patterns and platform constraints.