atomic-visual-options

Files (1)

• SKILL.md

SKILL.md (first lines)

> Adapted from [Atomic Claude](https://github.com/damusix/atomic-claude) at `b4ca195cae6022464b0cc5c07273b3fa9602da17`. Invoke in Codex CLI as `$atomic-visual-options`. Commands beginning with `atomic` require the Atomic CLI; Atomic Claude slash commands and hooks are specific to Claude Code.



Render the visual in the browser; make the decision in the terminal.

<trigger>

Auto-fire on:

- "show me a few options", "show me some options"
- "mock up some variants", "mock up some options"
- "let me see this side by side"
- "visual options for …", "compare these layouts"
- "wireframe some choices", "show layout options"
- "what would X look like", "can you visualize …"

Also fires when `/atomic-plan` encounters a design question that passes the see-it-over-read-it gate (see below).

</trigger>

## The gate (just-in-time, see-it-over-read-it)

Only render visuals when the question is genuinely visual. The test: *would the user understand it better seeing it than reading it?*

A question that is merely **about** a UI topic is not automatically visual:

- "What should the settings wizard do?" — conceptual, answer in the terminal.
- "Which of these three settings wizard layouts works?" — visual, render in the browser.

Apply this test per question, not per session. A planning conversation might have five conceptual questions and one visual one; only the visual question gets a rendered file. When the answer is "no," stay in the terminal with a plain list or prose.

## Workflow

<workflow>

### 1. Compose

Identify the decision dimensions. Each dimension becomes a **panel** (e.g. Layout, Color scheme, Navigation placement). For each panel:

- Assign a letter starting at A (panel A, panel B, panel C…).
- Generate 2–4 options. Label each with the panel letter + option number: `A1`, `A2`, `A3`. No more than four options per panel — beyond four the comparison stops being useful.
- Assign each option a short, descriptive title (e.g. "A2 — Two-column with sidebar").

### 2. Write

Write ONE self-contained HTML file to the scratchpad bundle:

```
$(atomic scratchpad path <topic>)/options.html
```

Paths come from `atomic scratchpad` / `atomic where --json`; if what you find on disk does not match, run `atomic migrate --show-log` for the change history.

The file must satisfy these constraints:

- Starts with `<!DOCTYPE html>`.
- All CSS inline in a `<style>` block — no external stylesheets.
- No external requests: no CDN links, no web fonts loaded from a remote host, no remote images. Default to CSS geometry and SVG for wireframe placeholders so the file renders fully offline. If a real raster image is genuinely required for fidelity, embed it as a base64 `data:` URI — the file must remain self-contained and work without a network connection.
- No client-side JavaScript. The selection is typed in the terminal; the page is pure display.
- Honors `prefers-color-scheme` for light and dark mode via a `@media (prefers-color-scheme: dark)` block.

### 3. Hand off

Print the `file://` path to the file. Do not auto-open the browser. End the turn.

Tell the user: open the file, pick one code per panel (e.g. `A2 B3`), and reply with those codes.

### 4. Read the pick

Next turn, parse the codes the user typed. Accept space- or comma-separated, one code per panel. Map each code back to its option title and description.

### 5. Iterate

If the user wants a panel changed or wants to see a different variant, overwrite the same file and tell them to refresh the browser. No versioning — the file is throwaway scratch.

### 6. Record

**Inside a `/atomic-plan` session:** write the chosen codes and what each option meant into `docs/design/<topic>.md`. Example entry:

```
Chose A2 (two-column layout with sidebar), B3 (high-contrast blue/white palette), C1 (top navigation bar).
```

**Standalone (not inside a plan):** state the chosen codes and what each option meant directly in the terminal so the decision is captured in the conversation history. If a `docs/design/<topic>.md` for the topic already exists, append the decision there too.

The HTML file is disposable and will be cleaned up with the scratchpad. The decision is what persists.

</workflow>

## HTML scaffold reference

Adapt the following structure for each new options file. It is intentionally compact while remaining genuinely functional — two panels, two or three options each, a usage instruction header, inline CSS with light/dark support, and a large readable code badge per option. Replace the SVG placeholders and descriptive text with content appropriate to the specific decision.

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Visual Options</title>
<style>
    /* ── Base ────────────────────────────────────────── */
    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
    body {
        font-family: system-ui, sans-serif;
        background: #f5f5f5;
        color: #111;
        padding: 2rem;
    }
    h1 { font-size: 1.1rem; margin-bottom: 0.4rem; }
    .instruction {
        font-size: 0.95rem;
        background: #fffbe6;
        border: 1px solid #e0c800;
        border-radius: 6px;
        padding: 0.6rem 1rem;
        margin-bottom: 2rem;
        max-width: 680px;

From Shamanbenny/agent-tools, MIT.

More from Shamanbenny/agent-tools