Docs visual elements preview

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.

PropertyList

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

• 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:

reasoningEffortstringdefault: 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.

diffModestringdefault: github

How diffs render in the session. github is side-by-side and higher fidelity (recommended); unified is the traditional single-column format.

syncSessionsbooleandefault: true

Sync sessions to the web app. Set to false to keep sessions local only.

commandBlockliststring[]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.

disableHooksbooleandefault: falsedeprecated

Disables all hooks globally when true. Prefer per-hook enablement.

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 on by default on macOS only; Linux support is in preview. Commands on the blocklist are never run, denylisted commands require approval, and reasoning effort is model dependent.

Kbd

Inline keycaps for shortcuts that today render as plain inline code. Press ⌘K to open search, Ctrl+Shift+P for the command palette, or Esc 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:

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:

1. Private PreviewInvite only

   Available to design partners behind an organization flag. Breaking changes may ship without notice.

2. Public BetaOpen signup

   Open to all organizations. Interfaces are stable but SLAs are not yet enforced.

3. General AvailabilityProduction

   Covered by production support and enterprise billing.

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:

Callouts

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

Inline vars and lifecycle

Shared values render through vars components, so Droid and links like support@factory.ai stay canonical, and 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:

1. 1
   Install the CLI

   Run the install command for your platform.

2. 2
   Authenticate

   Start droid and sign in via the browser prompt.

3. 3
   Run your first task

   Describe the change; review the diff before applying.

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:

Tabs

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

Code surfaces

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

curl -fsSL https://app.factory.ai/cli | sh

Stat strip

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

Checklist

Checklist for requirement and support matrices:

• Runs read-only commands without prompts
• Respects the command allowlist
• Runs blocklisted commands (never, even with approval)
• Network isolation depends on platform

FAQ

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

Mermaid

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

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.