README: Structured Design Documents

SDD-Text is a compact language for describing software product design as a structured map. SDD-Text is easy to read and write, for people and for LLMs.

Quick Start

Prerequisites: Git, Node.js 22 LTS, and pnpm. Install Node.js 22 first; pnpm will be activated via Corepack in the steps below.

git clone https://github.com/knutopia/Structured-Design-Documents.git
cd Structured-Design-Documents
scripts/setup-corepack.sh       # Mac, WSL, Linux
# .\scripts\setup-corepack.ps1  # on Windows, use this instead (in Powershell)
pnpm install
pnpm run build
pnpm sdd --help
pnpm sdd show docs/doc_site/small_app_example/small_app.sdd --profile simple --view ia_place_map --out my_first_ia.svg

Notes:

• The setup scripts activate the repo-pinned pnpm version declared in package.json.
• In WSL, if future shells route Corepack through /mnt/c/..., run scripts/setup-corepack.sh --write-profile or add export COREPACK_HOME="$HOME/.cache/corepack" to ~/.profile.
• If you hit temp-directory permission errors in some WSL setups, rerun commands with TMPDIR=/tmp. For more environment details, see docs/toolchain/development.md. See bundle/v0.1/examples/ for additional sample .sdd inputs.

Orientation

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

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

Learn More

• Using SDD-Skill with an LLM: SDD Skill Guide

• SDD CLI Guide ("sdd show" etc): SDD CLI User Guide

• SDD Helper Guide (JSON-first companion for the skill): SDD Helper Guide

• Authoring Spec: SDD-Text v0.1 — Authoring Spec (Type-first DSL)

• Initial Concepts 1: a 6-Diagram Suite v0.1

• Initial Concepts 2: One-page Schema v0.1

• Original document outlining the idea: Structured Design Artifacts to Advance the Software Product Design Practice

• Strategic Potential of SDD in the Product Lifecycle

Current Status

Working Now

• Solid v0.1 SDDT spec bundle
• Completed initial compile-validate-render pipeline.
• Completed usable staged SVG renderers for IA / Place Map, UI Contract, Service Blueprint, Scenario Flow, Outcome-Opportunity Map, and Journey Map
• sdd-helper app available to assist agentic skills

Known Limitations

• Dense or highly connected Journey Maps can remain difficult to trace; residual crossings use deterministic continuity bridges and emit renderer.routing.journey_map_unavoidable_crossing warnings.
• Across staged renderers, connectors between unobstructed horizontally adjacent nodes can still use multi-segment doglegs and distracting vertical offsets instead of one straight horizontal segment; a global routing simplification is deferred.
• Styling for renderers lives in TypeScript source and should be in CSS files
• Example corpus is spotty
• No "simple" non-technical user guidance available yet

Current Focus

• LLM integration (Skills, MCP Server)

Planned Additions

• Solve renderers for more diagram types
• Possibly standalone SDDT file server?

License And Contributions

• License: this project is available under the MIT License.
• Contributing: please read CONTRIBUTING.md before opening an issue or pull request. This repository is currently coordination-first and is not accepting unsolicited pull requests.
• Contributor License Agreement: accepted outside contributions also require written acceptance of the CLA before implementation or merge.