# Explore document directions

> Compare structure, visual treatment, or both for one artifact, then choose before applying a direction.

## When to use Explore

Use Artifact Explore when you want to compare structures, visual treatments, or both for one document. You can start with source material or an existing HTML file. Ask for different layouts, palettes, typography, or reference themes according to the decision you need to make.

```text
Use visualize to explore three artifact directions for ./report.html.
Keep our content, facts, assets, and actions fixed. Compare the reading structure
and visual treatment; keep our logo and approved primary color.
```

The explicit form is `visualize explore artifact <topic-or-path>`. Ordinary requests such as “show three layouts for this report” or “compare two visual treatments on this layout” route to the same task.

If you already know which reference to use, ask to [apply a theme directly](/docs/design-systems). Exploration is optional.

## Start without a layout or profile

You do not need an existing layout. The agent proposes a structure from your content. A focused palette or typography comparison can keep that structure fixed; a layout comparison can vary it.

A missing `DESIGN.md` does not force you to run `teach` first. The agent reads available project guidance and approved artifact references. When no usable visual direction exists, it can propose a temporary visual starting point through the normal creation workflow. This does not create project design authority. Use [teach](/docs/teach) when you want to record or refresh that authority.

## What stays fixed

Content, facts, quotations, citations, actions, required states, accessibility outcomes, and factual assets stay fixed. Existing project styling remains binding except for flexibility it permits or an explicit exception you approve for this artifact. Applying a theme does not change project design files.

Only the dimensions named in the brief vary. A structural comparison can change reading order, grouping, density, and responsive composition. A visual comparison can vary palette, typography, surfaces, or component treatment while retaining the same layout.

For an existing HTML file, the agent first identifies the behavior that must survive. If it cannot reproduce important behavior safely in a self-contained comparison, it explains the limitation rather than silently flattening it.

## Approve the brief once

Before creating initial directions, the agent shows a brief naming the reader and decision, source, fixed content and behavior, open design choices, project constraints and artifact exceptions, output file, direction count, review widths, and imagery needs. About three directions is the default.

Candidate work starts after you approve that brief, unless you already supplied an approved brief. The target and design-authority files stay unchanged during exploration. A specific follow-up authorizes the changes it names without repeating the initial approval exchange.

## Explore color and typography explicitly

Name what should stay and what is still open:

```text
Keep the Coral primary, layout, content, and Georgia typography.
Compare our current blue secondary with a lower-chroma version and with the
same blue covering less space. Keep an unchanged baseline for comparison.
```

“Quieter” can mean lower chroma, a different lightness, less coverage, or different placement. “Opposite” might mean a hue complement, warm versus cool, or light versus dark. The agent uses context and asks when the distinction would change an approved choice.

Palette character can be pale, muted, vivid, or deep. Colors and roles are separate: a hue may supply identity, emphasis, atmosphere, or a data category. Red identities, neutral gray, and multiple accents are valid. Meaningful category colors are not removed just because there are several hues. Actual text/background contrast and non-color cues still matter.

For typography, ask to compare type families, hierarchy, weight, scale, or reading rhythm while keeping the palette and other settled choices fixed. Alternatives appear on representative content; swatches and font samples can help explain them but do not replace the document comparison.

## Compare responsive directions

Explore writes one self-contained HTML file with separate review controls. You can switch directions, compare Wide and Phone widths, copy a direct review URL, and reset the view. Width controls never crop the document: each direction keeps its natural height and the page scrolls normally. Without JavaScript, every labeled direction remains readable.

The agent checks each direction at wide and 390 px in light and dark, including system preference and explicit theme overrides. It verifies fixed content, assets, approved constraints, meaningful differences, console errors, and overflow. Screenshots remain disposable review evidence rather than runtime dependencies.

Where permitted, a fresh subagent may draft each direction. The coordinator assembles the final file. Without subagents, the agent uses isolated serial passes without reducing the approved direction count.

## Choose before anything changes

The agent explains each direction's design idea and trade-off, then stops. You can select one, shortlist, reject all and revise the brief, or request a synthesis. A synthesis is another round, not automatic application.

When you explicitly select and ask to apply a direction, the agent rechecks the target and design authority, applies the selected structure and/or visual treatment, and verifies the result. Review controls and alternate directions do not enter the final document. A preference for one trait is not approval to apply the whole direction.

Artifact Explore does not create or replace a project design system. System Explore remains planned and is not available in this release.

## Generated imagery

Imagery is optional. Factual assets stay fixed across directions. Expressive imagery may vary only when that dimension is open in the approved brief. The agent uses a released route and inspects generated images before including them. The route and recovery rules are the same as [ordinary creation](/docs/create) and [supported hosts](/docs/supported-hosts).