The five principles are not guidelines — they are constraints. A process that violates any of them is not SDDn, regardless of what tools or templates it uses.
No element exists without prior spec.
In traditional design workflows, the artifact (mockup, prototype, component) comes first. The rationale is reverse-engineered from the output, if it is documented at all. SDDn inverts this: the spec is the primary artifact. Pixels are a rendering of the spec, not the source of truth.
What this means in practice:
- A component cannot enter development without an approved L2 Behavior Spec
- A screen or flow cannot be generated by an AI agent without an approved L3 Delivery Spec
- Exploratory work happens in Track A (Discovery) and is explicitly marked as pre-spec
- "We'll spec it later" is a process violation, not a temporary workaround
What this does not mean:
- You cannot sketch, prototype, or explore before speccing — that is what Track A is for
- Every pixel must be micro-documented — only named, reusable elements require specs
- Specs must be written before any thinking happens — thinking is Track A; speccing is Track B entry
The spec defines the why, not just the how.
A spec that only documents visual properties (color: #3B82F6, border-radius: 4px) is a stylesheet, not a spec. SDDn specs carry intent: why a decision was made, what constraint it satisfies, what problem it solves. This is what makes specs durable across rebrands, screen sizes, and model changes.
What this means in practice:
- Every section in a .dsmd file asks for the reason, not only the output
- Design Principles in L1 are stated as intent statements, not style rules
- The
Do / Don'tsection in L2 explains why a variant is wrong, not just that it is - Token names encode intent (
color-action-primary) rather than appearance (color-blue-500)
What this does not mean:
- Aesthetic decisions are forbidden — aesthetics are documented, just anchored to intent
- Every token needs a philosophical treatise — a brief intent statement per decision is sufficient
- Personal taste is invalid — taste, when articulated as intent, is a valid spec input
L3 inherits from L2, L2 from L1.
When a rule is defined at L1, it does not get restated at L2 or L3. When a component behavior is defined at L2, it does not get repeated in every L3 that uses that component. Inheritance is the mechanism that keeps specs maintainable at scale.
What this means in practice:
- An L3 Delivery Spec references L2 specs by ID — it does not re-describe component behavior
- An L2 Behavior Spec references its L1 Foundation Spec — it does not re-declare tokens or brand rules
- When an L1 spec changes, all L2 specs that inherit from it automatically cascade to STALE
- Contradiction between layers is a validation failure, not a design choice
What this does not mean:
- You can never mention a token value in an L2 or L3 — you can reference it by name
- Every detail must be abstracted into a parent spec — leaf-level specifics belong in their own layer
- Inheritance creates rigid lock-in — STALE → re-review → ACTIVE is the designed update path
Agents generate; designers decide.
AI tools can generate components, layouts, and code from a well-formed spec faster and more consistently than any human. That is their role. The authoring decisions — what a spec says, what intent it encodes, what constraints it enforces — are irreducibly human. SDDn makes this boundary explicit and enforces it structurally.
What this means in practice:
- AI agents operate only on ACTIVE specs — they never interpret DRAFT or STALE material
- Every spec includes an
AI Generation Rulessection that constrains what the agent may and may not do - Output generated by an agent is validated against the spec, not against the agent's judgment
- A spec authored by an AI must be reviewed and approved by a human before becoming ACTIVE
What this does not mean:
- AI cannot help write specs — agents are useful in Track A exploration and as spec drafting assistants
- Human review is a rubber stamp — reviewers are accountable for what they approve
- All AI output is suspect — compliant output is trustworthy; the spec is the compliance definition
A spec without version is dead documentation.
Documentation that has no version number, no state, and no owner becomes unreliable the moment the system evolves. SDDn specs carry version, state, and ownership metadata as mandatory fields. A spec that has drifted from the implemented system is not just wrong — it is actively harmful because teams may act on it.
What this means in practice:
- Every .dsmd file has a
version,status,owner, andlast_reviewedfield - Spec states (DRAFT, ACTIVE, STALE, DEPRECATED) drive workflow — agents check state before generating
- When a parent spec changes, child specs automatically enter STALE — they require re-review, not re-authoring
- Deprecating a spec is a deliberate act with a documented reason, not benign neglect
What this does not mean:
- Every minor wording fix requires a version bump — patch changes within a review cycle are valid
- Specs must be manually synchronized with code on every commit — the health system manages drift detection
- Old versions must be deleted — version history is an asset; DEPRECATED state flags what not to rely on
The five principles are mutually reinforcing:
- Spec before pixels creates the artifact that principles 2–5 operate on
- Intent over aesthetics makes specs worth reading and reviewing
- Inheritance over repetition keeps specs maintainable as the system scales
- AI as executor makes the investment in specs pay dividends through reliable generation
- Living specs ensures the entire structure stays trustworthy over time
Remove any one principle and the framework degrades: specs without intent become style guides; specs without inheritance become unmaintainable; specs without health states become misleading; specs written after the fact violate the foundation.
Next: 01-foundation-spec.md