Feature: Component.description

CLAUDE.md

@@ -8,7 +8,7 @@
 
 | Package | Path | Description |
 |---------|------|-------------|
-| `@directededges/specs-schema` | `packages/schema/` | TypeScript types and JSON schema definitions for component specifications. Exports are type-only except for `DEFAULT_CONFIG`. |
+| `@directededges/specs-schema` | `packages/schema/` | TypeScript types and JSON schema definitions for component specifications. Exports are type-only except for `DEFAULT_CONVENTIONS`, `DEFAULT_SETTINGS`, and `DEFAULT_PIPELINE`. |
 | `@directededges/specs-cli` | `packages/cli/` | CLI for design system operations: generate, scan, and fetch component specs from the Figma REST API. |
 
 ## Dependency Flow
@@ -32,7 +32,9 @@ packages/
 │   ├── types/                   # TypeScript type definitions (source of truth)
 │   │   ├── index.ts             # Barrel export
 │   │   ├── Component.ts         # Top-level component spec shape
-│   │   ├── Config.ts            # Config interface + DEFAULT_CONFIG
+│   │   ├── Conventions.ts       # Conventions interface + DEFAULT_CONVENTIONS
+│   │   ├── Settings.ts          # Settings interface + DEFAULT_SETTINGS
+│   │   ├── Pipeline.ts          # Pipeline interface + DEFAULT_PIPELINE
 │   │   └── ...                  # Anatomy, Props, Element, Styles, etc.
 │   ├── schema/                  # JSON Schema definitions (for validation)
 │   │   ├── component.schema.json
@@ -67,7 +69,7 @@ npm run build --workspace=packages/cli      # Build CLI only
 - **Test framework**: Vitest with globals enabled
 - **Path alias**: `@` → `./src` (used in CLI package)
 - **Deterministic output**: Same input produces identical output. No side effects in the processing pipeline.
-- **Config type** (from `@directededges/specs-schema`): Controls output shape — `DETAILS`, `FORMAT_KEYS`, `FORMAT_COLOR`, `DATA_LAYOUT`, `VARIANT_DEPTH`, etc.
+- **Conventions / Settings / Pipeline types** (from `@directededges/specs-schema`): `Conventions` declares facts about the Figma library (`figma.naming`, `figma.glyphs`, `figma.states`, etc. — a wrong value produces incorrect output); `Settings` controls output shape (`spec.details`, `spec.keys`, `spec.color`, `spec.layout`, `spec.variantDepth`, etc. — a different value produces different output); `Pipeline` declares `transformers` and `analyses`
 
 ## Schema Governance
 
@@ -88,7 +90,7 @@ Each step is a separate skill; run them in order. The ADR stays `DRAFT` until al
 The documentation site is built with Astro (port 4323) from `site/src/content/docs/`. Content sections:
 
 - `schema/` — one page per schema type (Component, Styles, Props, etc.)
-- `config/` — one page per config option (color, keys, layout, tokens, etc.)
+- `settings/` — one page per convention or setting (color, keys, layout, tokens, states, etc.)
 - `guides/` — how-to guides for specific features (slot constraints, variant depth, token format, etc.)
 - `cli/` — CLI overview, getting started, and per-command reference
 - `overview/` — product overview, licensing, releases

README.md

@@ -49,9 +49,9 @@ Command-line interface (CLI) for generating component specifications from Figma
 ```sh
 # 1. Install cli globally to run with the command `specs`
 npm install -g @directededges/specs-cli
-# 2. Initialize a specs.config.yaml file
+# 2. Initialize the config/ directory (conventions.yaml, settings.yaml, pipeline.yaml)
 specs init
-# 3. Edit the config for your Figma file key and preferred settings 
+# 3. Edit config/settings.yaml for your Figma file key and preferred settings 
 # 4. Set up an .env file with a Figma PAT and – if subscribed - license key
 # 5. Fetch raw Figma data (file, variables, styles)
 specs fetch
@@ -65,7 +65,7 @@ specs generate
 Helpful documentation includes:
 - [Overview](https://www.specsplugin.com/cli/)
 - [Getting started](https://www.specsplugin.com/cli/getting-started/)
-- [Configuration file](https://www.specsplugin.com/cli/configuration/) details
+- [Configuration reference](https://www.specsplugin.com/settings/) for conventions and settings
 - Per [command](https://www.specsplugin.com/cli/commands/) instructions and flags
 
 
@@ -80,8 +80,8 @@ npm install @directededges/specs-schema
 Exports include:
 
 - [JSON Schema](packages/schema/schema/root.schema.json) — the canonical schema for component spec output
-- [TypeScript types](packages/schema/types/) — complete type definitions for all schema entities (`Component`, `Config`, `Styles`, `Element`, `AnyProp`, etc.)
-- `DEFAULT_CONFIG` — a runtime configuration object controlling output shape (format, token resolution, variant depth, etc.)
+- [TypeScript types](packages/schema/types/) — complete type definitions for all schema entities (`Component`, `Conventions`, `Settings`, `Pipeline`, `Styles`, `Element`, `AnyProp`, etc.)
+- `DEFAULT_CONVENTIONS`, `DEFAULT_SETTINGS`, `DEFAULT_PIPELINE` — runtime default objects: a library declaring no conventions, run settings controlling output shape (format, token resolution, variant depth, etc.), and an empty pipeline
 
 Learn more in the [Schema docs](https://www.specsplugin.com/schema/), including details on each property including component, variants, styles, props and more.
 

adr/030-subcomponent-refs.md

@@ -11,7 +11,7 @@
 
 ## Context
 
-When a component contains subcomponents, anatomy items and elements that are instances of those subcomponents currently record `instanceOf` as a plain formatted string (e.g., `"egdsRadioButtonFormLabel"`). This is opaque — a consumer cannot distinguish a subcomponent reference from an arbitrary component name, nor can tooling follow the relationship programmatically.
+When a component contains subcomponents, anatomy items and elements that are instances of those subcomponents currently record `instanceOf` as a plain formatted string (e.g., `"dsRadioButtonFormLabel"`). This is opaque — a consumer cannot distinguish a subcomponent reference from an arbitrary component name, nor can tooling follow the relationship programmatically.
 
 The `$ref` pattern already exists in this package: `ElementTypeRef` uses `{ $ref: string }` on `AnatomyElement.type` to express a machine-followable pointer to an external definition. The same pattern should apply to `instanceOf` when the target is a sibling subcomponent within the same spec.