Overview

The @directededges/specs-schema package defines the TypeScript types and JSON Schema for a component spec — a structured, platform-agnostic description of a design-system component.

Spec Architecture

Every generated spec follows this tree — from a single-element icon to a complex composite with dozens of variants.

components:
└─ {component name}                        → Component
  ├─ anatomy:
  │ └─ {element name}: { type, slot }
  ├─ props:
  │ └─ {prop name}: { type, default, … }
  ├─ default:                              → Variant
  │ ├─ layout:
  │ │ └─ - {parent}:
  │ │   └─ - {child}
  │ └─ elements:
  │   └─ {element name}:
  │     ├─ content                         → PropBinding
  │     ├─ children                        → PropBinding
  │     └─ styles:                      (48 properties)
  │       ├─ color                         → TokenReference, GradientValue
  │       ├─ spacing, size                 → TokenReference, Conditional
  │       ├─ layout                        → TokenReference, Conditional
  │       ├─ typography                  → TokenReference
  │       ├─ effects                     → TokenReference
  │       ├─ cornerRadius                  → Corners
  │       ├─ padding, strokeWeight         → Sides
  │       ├─ visibility                    → PropBinding
  │       └─ …                             see full list
  ├─ variants:                             → Variant[]
  │ └─ - configuration:
  │     layout:
  │     elements:                      (overrides only)
  ├─ invalidVariantCombinations:           → PropConfigurations[]
  ├─ subcomponents:
  │ └─ {name}: { …same shape as above }
  └─ metadata:
    └─ config:

Start at default. The default variant is the complete baseline — every element fully described with styles, content, and layout. This is the component at rest.

Variants are deltas. Each entry in variants carries a configuration (which prop values activate it) and only the properties that change. Consumers resolve the final state by merging applicable overrides onto the default, in order. See Variants and the Variant Layering guide.

Style values can be rich. Any style property might be a raw literal, a TokenReference pointing to a design token, a PropBinding driven by a prop, or a Conditional that switches on prop state. Composite values like Typography, Effects, GradientValue, Corners, and Sides have their own shapes.

Conventions

• Style — A value that can be a literal (string | number | boolean | null), a TokenReference, a PropBinding, or a Conditional.
• Record<string, T> — An object keyed by user-defined names (element names, prop names, etc.) with values of type T.
• $ref — A JSON Pointer or URI reference linking to another part of the spec or an external definition.
• $binding — A JSON Pointer to a prop (e.g. #/props/label), creating a dynamic link between a prop value and a style or element property.

Package Exports

The package exports TypeScript types for every node in the schema, plus one runtime value:

import type { Component } from '@directededges/specs-schema';
import { DEFAULT_CONFIG } from '@directededges/specs-schema';

DEFAULT_CONFIG is the only runtime export. All other exports are type-only.