SDDn (Spec Driven Design) is a framework that transforms design — a historically interpretive discipline — into a system of structured, versionable, and AI-executable specifications, without sacrificing creative intent.

Design decisions live in Figma comments, Slack threads, and designers' heads. When a developer builds from a mockup, they interpret. When an AI agent generates UI, it guesses. When a spec exists, it lives in a PDF that no one updates.

The result: inconsistency at scale, rework on every handoff, and AI tools that produce plausible output with no guarantee of intent alignment.

SDDn exists because a design without a spec is a wish, not a contract.

Every SDDn-governed system is defined by three nested layers of specification:

┌─────────────────────────────────────────────────────┐
│  L1 — Foundation Spec                               │
│  What are the immutable rules of the system?        │
│  tokens · brand · accessibility · AI constraints    │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │  L2 — Behavior Spec                          │  │
│  │  How does each piece of the system behave?   │  │
│  │  states · variants · interactions · rules    │  │
│  │                                               │  │
│  │  ┌─────────────────────────────────────────┐ │  │
│  │  │  L3 — Delivery Spec                    │ │  │
│  │  │  What is delivered and how validated?  │ │  │
│  │  │  flows · edge cases · definition done  │ │  │
│  │  └─────────────────────────────────────────┘ │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Each layer inherits from the one above. An L3 Delivery Spec cannot contradict an L2 Behavior Spec. An L2 cannot override an L1 Foundation. Inheritance is enforced, not assumed.

Step 1 — Define your system foundation (L1)

Copy templates/foundation-spec.dsmd and fill in your design tokens, brand constraints, and accessibility baseline. This is your L1 Foundation Spec. It governs everything below it.

Step 2 — Spec each component (L2)

For every component your system needs, create an L2 Behavior Spec from templates/behavior-spec.dsmd. Define its states, variants, and interaction contract. Reference your L1 in the inherits_from field.

Step 3 — Specify every delivery (L3)

Before building any screen or flow, write an L3 Delivery Spec from templates/delivery-spec.dsmd. Reference the L2 specs your flow uses. This is the document your AI agent and your developer both work from.

See docs/getting-started.md for a complete walkthrough.

sddn-framework/
├── framework/          Core methodology documents
├── templates/          .dsmd spec templates (copy and fill)
├── ai-rules-starter-pack/  Ready-to-use AI generation rules by component
├── examples/           Complete, realistic filled .dsmd examples
└── docs/               Role-specific guides

1 - STALE-ADVISORY: a fifth spec state between ACTIVE and STALE

The previous 4-state model treated all parent spec changes equally: any version increment made a child spec STALE and blocked AI generation. v0.2.0 introduces STALE-ADVISORY for minor parent changes (additive only, no breaking changes). Specs in STALE-ADVISORY remain operational - agents continue to generate, but all output carries a mandatory warning. A fixed timebox (5 business days for L2, 3 for L3) gives spec owners a window to verify impact and re-approve. Only if the timebox expires does the spec degrade to STALE. Major parent changes still go directly to STALE.

2 - SemVer cascade semantics for L1

A 4-question checklist in framework/08-cascade-radar.md gives the Design Lead an objective method for classifying every L1 change as patch (no cascade), minor (STALE-ADVISORY), or major (STALE). The cascade message format is typed - [STALE-ADVISORY] and [STALE] messages have distinct fields so spec owners and CI tooling can parse and act on them reliably.

3 - Closed Dual-Track with Minimum Viable Spec Checklist

The original Track A had no hard stop. A spec could cycle through review indefinitely. v0.2.0 defines a maximum of two async review iterations before mandatory live session escalation. Review Gates use a 5-point objective checklist (the Minimum Viable Spec) to replace subjective completeness judgments. Specs that pass 5/5 but have known gaps are promoted to ACTIVE with observations, which become spec-observation GitHub Issues - traceable and owned, not invisible.

SDDn v0.2.0 adds the STALE-ADVISORY state, SemVer cascade semantics, and the closed Dual-Track model with Minimum Viable Spec Checklist. See CHANGELOG.md for the full diff from v0.1.0.

The framework is published under a Community RFC model: read it, use it, and open issues to challenge or extend it. See CONTRIBUTING.md for how to contribute. No backward-compatible contract exists until v1.0.0 locks the schema.

Francisco Javier Saavedra González Creator and principal author of SDDn.

MIT — use freely, credit appreciated.