Overview
The Wyrding Way is a contract-first design system. Authors record design intent and public UI obligations in stable, target-neutral artifacts. Validation joins those artifacts before generators and target implementations carry them into products.
The mental model begins with authority, not repository layout. Each fact has one owner; generated files and packages carry that fact but do not become a second owner.
Sources for block 1: product-component-contract-term, product-catalog-term
Design language
| Concept | Meaning | Authority |
|---|---|---|
| Brand | A complete design identity containing token primitives, identity assets, and design-language choices. | Brand source artifacts, including DESIGN.md and token sources. |
| Semantic token | A stable name for design intent, such as surface, accent, or danger, which resolves through a Brand. | Token source and its generated W3C Design Tokens projections. |
| Component contract | The public properties, slots, events, states, parts, tokens, obligations, and target availability of one reusable UI type. | The Component's basename YAML contract in its Catalog-owned directory. |
Sources for block 1: product-brand-term, product-semantic-token-term, product-component-contract-term, design-tokens-format
UI structure
| Concept | Meaning | Identity rule |
|---|---|---|
| Component | A reusable, contract-backed UI type. Its implementation can be direct target code or an embedded Composition. | Its Component contract owns identity and public surface. |
| Composition | A target-neutral declarative assembly with stable layout nodes, behavior bindings, context, and namespaced extensions. | A Screen or Shell document owns its identity; a Component embeds a Composition body and keeps contract identity. |
| Screen | An application-owned Composition that is a navigation destination. | Its discovered Screen document. |
| Shell | An application-owned Composition that persists across navigation and is intended to host Screens through the planned Outlet primitive. Until Outlet exists in the schema, Shells are describable but not machine-expressible. | Its discovered Shell document. |
| Behavior | A reusable declarative statechart with typed inputs, events, context, states, actions, and outputs. | Its Behavior contract in a Catalog. |
Sources for block 1: product-composition-term, product-component-contract-term, product-screen-term, product-shell-term, product-outlet-term, product-behavior-term, studio-composition
Collections and tools
A Catalog is the authoritative collection of Component contracts, direct or Composition implementations, reusable Behaviors, and generated projections. Shared and product-private Catalogs use the same concepts and validation rules.
Studio is a visual workbench over the same artifacts. It edits governed source surfaces and previews projections; it does not become the owner of Composition, Component, or Brand truth.
Sources for block 1: product-catalog-term, studio-composition
Sources for block 2: catalog-bundle