Design Documents & Validation

What the Design Document Contains

The design document (.kiro/specs/[feature]/design.md) is the technical architecture for implementing the requirements. It is generated by the AI after requirements are approved, and reviewed by humans before any code is written.

Sections of a design document:

Overview: What this feature does in 2-3 sentences. References the relevant requirements.

Architecture: How the feature fits into the existing system. What layers it touches. What existing code it uses or extends.

Database Schema: New tables, columns, relationships, and indexes. Written as SQL DDL with explanations. References any steering file constraints on naming conventions.

API Routes: Endpoints, HTTP methods, request/response formats, authentication requirements, error responses.

Component Tree: React (or other framework) component hierarchy with props and responsibilities.

Integration Points: External services, existing code modules being extended, and third-party APIs.

Mermaid Diagrams: Data flow diagrams, sequence diagrams for complex interactions, entity relationship diagrams for schema.

Requirements Coverage Matrix: Which design elements satisfy which REQ-xxx items.

The Human Review Gate

The review gate between design and implementation is the highest-value gate in the SDD pipeline. Architectural mistakes caught here cost minutes to fix — in code they can cost days.

At the design review, check:

• Does the schema support all the requirements?
• Are the API routes consistent with existing API conventions (from steering files)?
• Does the component tree match the mockup?
• Are there requirements not covered by any design element?
• Are there design elements that map to no requirement?

Validate-Design for Brownfield Projects

/kiro:validate-design [feature] checks the proposed design against your existing codebase for:

• Naming conflicts: Does a proposed table/column already exist?
• Schema incompatibilities: Does the design assume a column that does not exist?
• Pattern divergences: Does the proposed API style differ from existing endpoints?
• Dependency conflicts: Does the design require a library version incompatible with your lock file?

Example Design Document: Task Management

Feature: Task Management

*Overview:* Allow users to create, assign, label, and track tasks within a project. Satisfies REQ-001 through REQ-012.

*Database Schema:*

CREATE TABLE tasks (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id UUID REFERENCES projects(id),
  title TEXT NOT NULL,
  description TEXT,
  status TEXT DEFAULT 'todo' CHECK (status IN ('todo','in_progress','done')),
  assigned_to UUID REFERENCES users(id),
  due_date TIMESTAMPTZ,
  created_by UUID REFERENCES users(id),
  created_at TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE task_labels (
  task_id UUID REFERENCES tasks(id),
  label_id UUID REFERENCES labels(id),
  PRIMARY KEY (task_id, label_id)
);

CREATE INDEX idx_tasks_project ON tasks(project_id);
CREATE INDEX idx_tasks_assigned ON tasks(assigned_to);

*API Routes:*

• GET /projects/:id/tasks — list tasks (filter by status, assignee, label)
• POST /projects/:id/tasks — create task
• PATCH /tasks/:id — update task (title, description, status, assignee, due date)
• DELETE /tasks/:id — delete task (only creator or admin)
• POST /tasks/:id/labels — add label
• DELETE /tasks/:id/labels/:labelId — remove label

*Components:*

• TaskList — receives tasks[], renders list, handles filtering
• TaskCard — single task with status toggle, assignee avatar, labels
• TaskForm — create/edit form with validation
• TaskFilters — status filter, assignee filter, label filter

*Requirements Coverage:*

• REQ-001 (create task) → POST /tasks + TaskForm
• REQ-003 (assign task) → PATCH /tasks/:id + assignee field in schema
• REQ-005 (filter by status) → GET /tasks?status= + TaskFilters component

Key Takeaways

• Design documents cover schema, API routes, components, integrations, and Mermaid diagrams
• The design review gate catches architectural mistakes before any code is written
• Every design element should trace to at least one requirement — no orphan design decisions
• Every requirement should be covered by at least one design element — no unaddressed requirements
• validate-design checks proposed design against existing code for conflicts before implementation