Output

Controls where and how to write generated specifications. Configured via the output field in specs.config.yaml or CLI flags.

output:
  splitComponents: false    # Create separate file per component
  splitConcerns: false      # Separate API from variants
  useSubfolders: false      # Use component subdirectories
  defaultFormat: yaml       # Output format (yaml|json)

Output Modes

The CLI supports four output modes based on flag combinations:

Mode	--split-components	--split-concerns	Output Structure
Single-file	-	-	library.yaml (all components)
Per-component	yes	-	button.yaml, alert.yaml, …
Per-concern	-	yes	api.yaml + variants.yaml
Combined	yes	yes	button/api.yaml, button/variants.yaml, …

splitComponents

Create separate file per component.

• Type: boolean
• Default: false (single library file)
• CLI Flag: --split-components

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

output:
  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 from variant configuration.

• Type: boolean
• Default: false (complete component data)
• CLI Flag: --split-concerns

output:
  splitConcerns: true

API file (api.yaml):

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

Variants file (variants.yaml):

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

useSubfolders

Create component subdirectories when splitting by component.

• Type: boolean
• Default: false (flat structure)
• Effect: Only applies when splitComponents: true
• CLI Flag: --use-subfolders

Without subfolders (flat):

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

With subfolders:

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

defaultFormat

Default output format for stdout only.

• Type: string
• Default: yaml
• Options: yaml, json
• Override: CLI --format flag takes precedence
• Note: File output is always YAML. This setting controls stdout format only.
• Note: Different from config.format.output (controls serialization, not file format)

output:
  defaultFormat: yaml  # stdout format (files use YAML)

Combined Mode

Using both splitComponents and splitConcerns creates component directories with concern files:

output:
  splitComponents: true
  splitConcerns: true
  useSubfolders: false  # Component dirs created automatically

specs/
├── button/
│   ├── api.yaml       # Anatomy + props
│   └── variants.yaml  # Default + variants
├── alert/
│   ├── api.yaml
│   └── variants.yaml
└── card/
    ├── api.yaml
    └── variants.yaml

CLI Flag Priority

Output configuration follows the standard priority system:

1. CLI flags (highest): --split-components, --split-concerns, --use-subfolders
2. Config file: output field in specs.config.yaml
3. Defaults (lowest): Single-file mode, YAML format

# Config has splitComponents: false
# CLI overrides to true
specs generate --split-components