Structured Design Documents

Appearance

SDDStructured Design Documents

Semantically Defined Structural Design for Better Products

Example
Repo
Impact

Product Design Graph

Nodes and edges, from high-level opportunities to low-level details, prepared to evolve

Simple Markup, Rendered Diagrams

Easy to read, easy to write, validated and rendered to diagrams as output

For Us and for Our Machines

Use SDD to talk to an LLM about structural design

SDD (Structured Design Documents) is a compact language for describing software product design as a structured map. SDD is easy to read and write, for people and for LLMs.

SDD makes design elements and their relationships explicit, in a unified "Product Design Graph", which captures a variety of product design perspectives as a single, interconnected set of nodes. In technical terms, it is a DSL (Domain Specific Language) for authoring a structured graph of design information.

The project includes tools for compiling and validating SDD source files and for generating diagrams from them. Different parts of the unified graph can be rendered as distinct diagrams: IA / Place Map, UI Contracts, Scenario Flow, Journey Map, Outcome-Opportunity Map, and Service Blueprint. See Diagram Types.

Why It Exists ​

  • To provide a structured source of truth for product design instead of fragmented diagrams and documents.
  • To make design structure machine-readable for validation, tooling, and deterministic rendering.
  • To create design artifacts that AI and LLM workflows can consume without relying on image interpretation.
  • To provide a means to AI and LLM workflows to "speak design", so they can create structural design information outside blobs of code.
  • To give "traditional" product, design, and diagramming tools a shared semantic layer they can integrate with.

Example: Small App Simple Profile ​

Here is a small SDD example showing a dashboard, a project area, and a few linked places and view states. From this source file, an Information Architecture / Place Map and a UI Contracts diagram are generated.

small app information architecture diagram

See also: Service Blueprint Slice example, connecting customer steps to frontstage, backstage, support, system, and policy lanes. This example also shows how to create the diagram from an SDD file on the command line.

Using SDD ​

The SDD Skill helps when using SDD with an LLM: SDD Skill Guide

Using SDD command line tools manually ("sdd show" etc): SDD CLI User Guide

Technical Core ​

Two folders define the language:

  • The bundle/v0.1/ folder houses the tight, machine-readable specifications for version 0.1. These specifications are the source of truth for tooling. bundle/v0.1/ repo folder

  • The definitions/v0.1/ houses explanatory definitions and rationale for version 0.1 and should stay consistent with the bundle. definitions/v0.1/ repo folder

The Authoring Spec guides changes to the language: SDD-Text v0.1 — Authoring Spec (Type-first DSL)

The SDD Helper Guide describes how the sdd-helper supports the sdd-skill behind the scenes: SDD Helper Guide

Background / Origins ​