# Docs visual elements preview

Draft gallery of new docs components for dense content pages, each shown against the bullet or card pattern it replaces.

This draft page previews five new visual elements for dense docs pages, plus the
existing components they pair with. Each section converts real content from a
current page so the comparison is honest: same information, different surface.

<LabeledDivider label='New components' />

## PropertyList

Replaces `- **term** - description` bullet runs (the dominant pattern on
[CLI settings](/droid-cli/settings), exit codes, and config enumerations).
Today that content renders like this:

{/* sweep-allow: term-bullets */}

- **`off` / `none`**: no structured reasoning (fastest).
- **`minimal`**, **`low`**, **`medium`**, **`high`**: progressively more deliberation.
- **`extra high`**, **`max`**: the deepest reasoning, where a model offers it.

The same content as a `PropertyList`, with room for meta chips the bullets
cannot carry:

<PropertyList>
  <Property name='reasoningEffort' type='string' defaultValue='medium'>
    How much structured reasoning the model applies before acting. `off` and
    `none` disable it entirely (fastest); `minimal` through `high` add
    progressively more deliberation; `extra high` and `max` request the deepest
    reasoning where a model offers it.
  </Property>
  <Property name='diffMode' type='string' defaultValue='github'>
    How diffs render in the session. `github` is side-by-side and higher
    fidelity (recommended); `unified` is the traditional single-column format.
  </Property>
  <Property name='syncSessions' type='boolean' defaultValue='true'>
    Sync sessions to the web app. Set to `false` to keep sessions local only.
  </Property>
  <Property name='commandBlocklist' type='string[]' required>
    Commands that can never run. Unlike the denylist there is no prompt and no
    way to approve them: the block applies even under full autonomy, auto-run,
    or `--skip-permissions-unsafe`.
  </Property>
  <Property name='disableHooks' type='boolean' defaultValue='false' deprecated>
    Disables all hooks globally when `true`. Prefer per-hook enablement.
  </Property>
</PropertyList>

## Badge

An inline status pill for prose annotations: defaults, platform support,
availability, risk levels. Generalizes the lifecycle pill already used next to
page titles.

Sandboxing is <Badge variant='success' dot>on by default</Badge> on
<Badge>macOS only</Badge>; Linux support is in
<Badge variant='accent'>preview</Badge>. Commands on the blocklist are
<Badge variant='danger'>never run</Badge>, denylisted commands
<Badge variant='warning'>require approval</Badge>, and reasoning effort is
<Badge variant='info'>model dependent</Badge>.

## Kbd

Inline keycaps for shortcuts that today render as plain inline code. Press
<Kbd>⌘K</Kbd> to open search, <Kbd keys='Ctrl+Shift+P' /> for the command
palette, or <Kbd>Esc</Kbd> to dismiss.

## LabeledDivider

The hairline rules zoning this page are the component itself: a mono caption
plus rule that breaks a long page into scannable regions without spending a
card or a heading. Left-aligned by default, centered below:

<LabeledDivider label='Advanced configuration' icon='gear' align='center' />

## Timeline

A status-oriented milestone rail for lifecycle and rollout content, distinct
from `Steps` (which stays reserved for procedural instructions). Converted from
the feature-maturity narrative:

<Timeline>
  <TimelineItem title='Private Preview' meta='Invite only' status='done'>
    Available to design partners behind an organization flag. Breaking changes
    may ship without notice.
  </TimelineItem>
  <TimelineItem title='Public Beta' meta='Open signup' status='active'>
    Open to all organizations. Interfaces are stable but SLAs are not yet
    enforced.
  </TimelineItem>
  <TimelineItem title='General Availability' meta='Production'>
    Covered by production support and enterprise billing.
  </TimelineItem>
</Timeline>

## ComparisonTable

A decision surface between raw markdown tables and CardGroups: bordered frame,
mono header row, optional recommended-column highlight. Converted from the
"pick a surface" bullets on the exec overview:

<ComparisonTable label='Choosing a surface' highlightColumn={3}>

| Capability          | Droid CLI        | Droid Exec |
| ------------------- | ---------------- | ---------- |
| Interactive session | Yes              | No         |
| CI/CD pipelines     | Partial          | Yes        |
| Structured output   | Text             | Text, JSON |
| Autonomy control    | Prompted         | Flag-based |
| Best for            | Development work | Automation |

</ComparisonTable>

<LabeledDivider label='Retained palette' />

## Callouts

The five callout variants, unchanged. They stay the tool for asides; the new
components exist so callouts stop carrying enumerations.

<Note>Sessions sync to the web app unless `syncSessions` is `false`.</Note>
<Tip>Add low-risk utilities to the command allowlist to skip prompts.</Tip>
<Warning>Blocklisted commands never run, even under full autonomy.</Warning>
<Info>Reasoning effort trades latency for deliberation.</Info>
<Check>Your CLI is authenticated and ready.</Check>

## Inline vars and lifecycle

Shared values render through vars components, so
Droid and links like [support@factory.ai](mailto:support@factory.ai) stay canonical,
and <LifecycleTag tag='Private Preview' /> pills annotate feature maturity
inline and next to page titles.

## Steps

Numbered `Steps` stay reserved for procedural instructions the reader performs
(`Timeline` above covers status). Unchanged:

<Steps>
  <Step title='Install the CLI'>
    Run the install command for your platform.
  </Step>
  <Step title='Authenticate'>
    Start `droid` and sign in via the browser prompt.
  </Step>
  <Step title='Run your first task'>
    Describe the change; review the diff before applying.
  </Step>
</Steps>

## Lists

Top-level bullets keep the orange square marker; nested levels now get a 1px
indent guide and a hollow marker so depth stays legible:

- Deterministic controls run first
  - Command allowlist skips prompts for trusted utilities
  - Command blocklist never runs, even with approval
- Model-led review runs second
  - The risk model catches misses
  - The downgrade model clears false alarms

## Cards

`Card`/`CardGroup` are retained for navigation and genuine feature summaries,
where the blueprint surface and brackets earn their weight:

<CardGroup cols={2}>
  <Card title='Droid CLI' icon='terminal' href='/droid-cli/overview'>
    The agent in your terminal: sessions, autonomy levels, and IDE hooks.
  </Card>
  <Card title='Skills' icon='rocket' href='/harness/skills'>
    Package procedures Droid loads on demand across your team.
  </Card>
</CardGroup>

## Tabs

`Tabs` for parallel platform or option branches currently written as bullets:

<Tabs>
  <Tab title='macOS'>
    Sandboxing uses the system sandbox profile and is on by default.
  </Tab>
  <Tab title='Linux'>
    Sandboxing uses namespaces and is available in preview builds.
  </Tab>
  <Tab title='Windows'>
    Sandboxing is not yet available; auto-run policies still apply.
  </Tab>
</Tabs>

## Code surfaces

`CodeGroup` switches between equivalent snippets, and `Terminal` gives shell
commands window chrome:

<CodeGroup>

```bash title="macOS / Linux"
curl -fsSL https://app.factory.ai/cli | sh
```

```powershell title="Windows"
irm https://app.factory.ai/cli/windows | iex
```

</CodeGroup>

<Terminal title='bash' command={`cd /path/to/your/project
droid`} />

## Stat strip

The Software Factory dashboard kit (`StatStrip`, `Stat`, and the `Radar` and
`Gauge` instruments) for numeric claims on overview pages:

<StatStrip>
  <Stat value='24' label='Validators' caption='Run on every PR' />
  <Stat value='996' label='Tests' caption='Vitest, jsdom' />
  <Stat label='Coverage'>
    <Gauge value={0.72} label='72% of pages' />
  </Stat>
  <Stat label='Monitoring'>
    <Radar size={72} label='Docs sweep' />
  </Stat>
</StatStrip>

## Checklist

`Checklist` for requirement and support matrices:

<Checklist>
  <ChecklistItem status='pass'>Runs read-only commands without prompts</ChecklistItem>
  <ChecklistItem status='pass'>Respects the command allowlist</ChecklistItem>
  <ChecklistItem status='fail'>Runs blocklisted commands (never, even with approval)</ChecklistItem>
  <ChecklistItem status='neutral'>Network isolation depends on platform</ChecklistItem>
</Checklist>

## FAQ

`FAQ` and `Troubleshooting` rows carry schema.org FAQPage markup, the one
sanctioned disclosure surface:

<FAQ>
  <FAQItem title='Does the blocklist apply under full autonomy?'>
    Yes. Blocklisted commands never run; there is no prompt and no override.
  </FAQItem>
  <FAQItem title='Can I approve a denylisted command?'>
    Yes. Denylisted commands always ask first but run once you approve.
  </FAQItem>
</FAQ>

## Mermaid

Architecture and flow diagrams use `mermaid` fences with the Factory theme
init block, never one-off SVG components:

```mermaid
%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Geist Mono, monospace", "fontSize": "13px", "primaryColor": "#161413", "primaryBorderColor": "#342F2D", "primaryTextColor": "#FAFAFA", "lineColor": "#4D4947", "textColor": "#D6D3D2"}}}%%
flowchart LR
    a["Authored MDX"] --> v["Velite build"]
    v --> r["Registry components"]
    r --> d["docs.factory.ai"]
```

Not demoed here: the media family (markdown images, `FrameGroup`, `DocsVideo`)
needs real assets; the install surfaces (`InstallPanel`,
`CliInstallCommands`, `DesktopDownloadCards`) and the hand-authored API kit
(`Endpoint`, `ApiField`, ...) are specialized page kits. The general-purpose
disclosure family (`Accordion`, `Expandable`) is deliberately banned by
`docs:check:components`; compress with `PropertyList` and `ComparisonTable`
instead of hiding content.

## RelatedLinks

The `RelatedLinks` component is the single sanctioned docs page footer: a
compact row of curated cross-group links under the standardized "Related
resources" mono caption (omit the `label` attribute; the validator rejects
overrides). Every docs page closes with at most one `<RelatedLinks>` block,
and it must be the final element of the page body.

<RelatedLinks>
  <RelatedLink href='/harness/skills' title='Skills'>
    Package procedures Droid loads on demand.
  </RelatedLink>
  <RelatedLink href='/droid-cli/settings' title='CLI settings'>
    Configure models, tools, and behavior.
  </RelatedLink>
  <RelatedLink href='/droid-exec/overview' title='Droid Exec'>
    Run Droid headless in scripts and CI.
  </RelatedLink>
  <RelatedLink href='/autonomy-and-safety/sandbox' title='Sandbox'>
    Isolate execution for riskier work.
  </RelatedLink>
</RelatedLinks>