Skip to content
Specs

init

Initialize the config/ directory — one conventions file per platform plus settings.yaml — with production-ready defaults.

Usage

Terminal window
specs init [options]

Purpose

The init command scaffolds the split configuration (ADR-071, ADR-078), each file answering one question:

  • config/conventions/figma.yaml — facts about the Figma library: naming patterns, glyph and subcomponent matching, how images are expressed. See Conventions.
  • config/conventions/specs.yaml — conventions about the spec itself: the states classification and the props carrying accessibility and value semantics. See Conventions.
  • config/conventions/react.yaml and config/conventions/web-components.yaml — commented stubs for the code platforms; a file of pure comments declares nothing until you opt in.
  • config/settings.yaml — choices about this run: sources, spec output, assets. See Settings.

Each file ships with sensible defaults and inline documentation with links to the full configuration reference. settings.yaml includes an empty data.sources object ready for your Figma file keys.

This is the recommended way to get started with Specs in a new project.

What Gets Created

config/
  conventions/
    figma.yaml           # what the Figma library is
    specs.yaml           # what the spec declares about itself
    react.yaml           # code-platform stub, commented out
    web-components.yaml  # code-platform stub, commented out
  settings.yaml          # how output behaves, and where it goes

config/conventions/figma.yaml declares how the library is authored — most conventions start commented out, since absence means the library declares no such convention:

# Facts about the Figma library — every consumer of that library declares the same values.
# naming: NONE


# glyphs:
#   match: 'DS Icon Glyph / {i}'


subcomponents:
  # scope: NESTED
  match:
    - '{C} / _ / {S}'
  # exclude:
  #   - '{C} / Examples / {S}'


slotConstraints: false

config/conventions/specs.yaml declares conventions about the spec itself — every member names a prop or enum value the spec declares:

# states:
#   hover:
#     prop: state
#     value: hover
#   disabled:
#     prop: disabled   # boolean prop — value defaults to "true"

config/settings.yaml declares run choices, grouped by concern:

# Choices about this run — sources, spec output, assets.
author: <Your Name Here>


data:
  directory: ./data
  sources: {}


spec:
  directory: ./specs
  format: JSON
  keys: SAFE
  layout: LAYOUT
  tokens: TOKEN
  color: HEX
  variantDepth: 9999
  details: LAYERED
  # splitComponents: true
  # splitConcerns: true
  # useSubfolders: true

Each section includes inline comments with references to the full documentation.

Options

--force

Overwrite existing config files without prompting.

By default, if any of the files exists, init prompts before overwriting. Use --force to skip the prompt.

Terminal window
# Prompt before overwrite (default)
specs init


# Overwrite without prompting
specs init --force

--config <path> / -c <path>

Custom directory to write the config/ folder into (default: current directory).

Terminal window
# Scaffold config/ inside a workspace subdirectory
specs init --config ./workspaces/library
# Creates ./workspaces/library/config/conventions/*.yaml and settings.yaml

Examples

Example 1: Basic Initialization

Terminal window
cd my-design-system
specs init


# Output:
# ✓ Created config/conventions/figma.yaml
# ✓ Created config/conventions/specs.yaml
# ✓ Created config/conventions/react.yaml
# ✓ Created config/conventions/web-components.yaml
# ✓ Created config/settings.yaml
# 📚 Next steps:
#    1. Edit the config file to add your Figma file keys
#    2. Run: specs fetch
#    3. Run: specs scan
#    4. Run: specs generate

Example 2: Multiple Workspaces

Terminal window
# One config/ directory per workspace
specs init --config ./workspaces/dev --force
specs init --config ./workspaces/prod --force


# Use with --config flag on other commands
specs fetch --config ./workspaces/dev/config
specs generate data/library.file.json -c "Button" --config ./workspaces/prod/config

Example 3: Force Overwrite

Terminal window
# If you accidentally delete your config, recreate it
specs init --force

Upgrading from a single config file

A pre-split specs.config.yaml (or .json) is no longer read (ADR-071), and init refuses to run while one is present — scaffolding defaults over it would quietly replace whatever the workspace actually declared:

Error: found specs.config.yaml — a pre-split configuration (ADR-071).
  Run `specs migrate config` to convert it, keeping what this workspace declares.
  To scaffold fresh defaults instead, remove specs.config.yaml first.

Run specs migrate config to convert the file into the split layout — the Settings and Conventions references show where each former member now lives. Use init only for a workspace with no existing configuration.

See Also: