Output

Controls where and how to write generated specifications. Run choices, configured via the spec block in config/settings.yaml or CLI flags — any split arrangement carries the same spec data.

The split layout is the default: one folder per component, holding one file per concern. Downstream commands — transform, analyze, render — read that layout, so most workspaces never set these at all.

spec:
  splitComponents: true    # One file per component (default)
  splitConcerns: true      # Separate API, variants, and examples (default)
  useSubfolders: true      # Nest each component in its own folder (default)

Output Modes

Four output modes, reached by turning parts of the default split off:

Mode	splitComponents	splitConcerns	Output Structure
Combined (default)	true	true	button/api.yaml, button/variants.yaml (+ button/examples.yaml if examples), …
Per-component	true	false	button.yaml, alert.yaml, …
Per-concern	false	true	api.yaml + variants.yaml (+ examples.yaml if any examples)
Single-file	false	false	library.yaml (all components)

splitComponents

Write one file per component rather than a single combined library file.

• Type: boolean
• Default: true
• CLI Flag: --combine-as-library turns it off

spec:
  splitComponents: true
  useSubfolders: false  # button.yaml, alert.yaml (flat)

spec:
  splitComponents: true
  useSubfolders: true   # button/button.yaml, alert/alert.yaml

File naming converts display names to camelCase (e.g., "DS Alert" → dsAlert.yaml).

splitConcerns

Separate API specification, variant configuration, and examples.

• Type: boolean
• Default: true
• CLI Flag: --combine-concerns turns it off

spec:
  splitConcerns: false

API file (api.yaml):

components:
  - name: Button
    anatomy: ...
    props: ...

Variants file (variants.yaml):

components:
  - name: Button
    default: ...
    variants: ...

Examples file (examples.yaml):

components:
  - name: Alert
    slotContentExamples: ...
    instanceExamples: ...

examples.yaml is written only when at least one component has slotContentExamples or instanceExamples; components without examples are omitted from it. Without this file the $slotContent references in default/variants would have no target.

Example output is a Pro feature — on the free tier no example data is produced, so examples.yaml is never written.

useSubfolders

Nest each component’s files in a subfolder named for the component.

• Type: boolean
• Default: true
• Effect: Only applies when splitComponents: true
• CLI Flag: --no-subfolders turns it off

With subfolders (default):

specs/
├── button/
│   └── button.yaml
├── alert/
│   └── alert.yaml
└── card/
    └── card.yaml

Without subfolders (flat):

specs/
├── button.yaml
├── alert.yaml
└── card.yaml

Combined Mode

The default. Both splitComponents and splitConcerns on gives component directories of concern files:

spec:
  splitComponents: true
  splitConcerns: true

specs/
├── button/
│   ├── api.yaml       # Anatomy + props
│   └── variants.yaml  # Default + variants
├── alert/
│   ├── api.yaml
│   ├── variants.yaml
│   └── examples.yaml  # slotContentExamples + instanceExamples (only if present)
└── card/
    ├── api.yaml
    └── variants.yaml

CLI Flag Priority

Output configuration follows the standard priority system:

1. CLI flags (highest): --combine-as-library, --combine-concerns, --no-subfolders
2. Config file: spec block in config/settings.yaml
3. Defaults (lowest): the full split layout, YAML format

Each flag only ever turns a split off, so an absent flag defers to the configured value rather than overriding it.

# Config leaves splitConcerns at its default of true
# CLI overrides to false for this run
specs generate --combine-concerns

In the pre-split specs.config.yaml, these flags lived in a root-level output block and defaulted to false. That file is no longer read — specs migrate config converts it, moving them to spec. Because the defaults inverted, the migration writes all three out explicitly so a migrated workspace keeps emitting what it emits today; delete those three lines to adopt the new default.