# Design > Generate system architecture, machine-readable schemas, and UI mockups. Spawns planner + ui-designer concurrently. - Skill: `cwijayasundara/design-3` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add cwijayasundara/design-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/cwijayasundara/design-3/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: cwijayasundara (https://skillmd.com/u/cwijayasundara) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/cwijayasundara/design-3 --- # Design Skill — System Architecture & UI Mockups ## Usage ``` /design ``` No arguments. Reads from `specs/stories/` and produces architecture documents, machine-readable schemas, and HTML mockups concurrently. --- ## Overview This is the third gate in the SDLC pipeline. Two agents run concurrently in a single message: a `planner` agent produces system architecture and machine-readable schemas, while a `ui-designer` agent produces self-contained HTML mockups. After both complete, a post-completion validation step verifies that UI data shapes align with API contracts. --- ## Prerequisites `specs/stories/` must exist and contain story files. If it does not, halt and tell the human to run `/spec` first. --- ## Step 1 — Spawn Two Agents Concurrently In a single message, invoke both agents using the Agent tool. Do not wait for the planner to finish before starting the ui-designer. --- ### Agent 1 — planner **Prompt:** > Read all files in specs/stories/. Design the full system architecture for this project. > > Write the following files to specs/design/: > > 1. **system-design.md** — High-level architecture overview: components, data flows, infrastructure topology, key design decisions and rationale. > > 2. **api-contracts.md** — Every API endpoint in detail: method, path, request schema (headers, params, body), response schema (success and error shapes), authentication requirements, rate limits. Use a consistent format for each endpoint. > > 3. **api-contracts.schema.json** — OpenAPI 3.0 JSON Schema representing all endpoints defined in api-contracts.md. Must be valid and parseable. > > 4. **data-models.md** — Every data entity: field names, types, constraints, relationships, indexes, and example records. > > 5. **data-models.schema.json** — JSON Schema (draft-07 or later) for every entity in data-models.md. Must be valid and parseable. > > 6. **folder-structure.md** — Full proposed directory tree for the implementation, with a one-line annotation for each directory explaining its purpose. > > 7. **component-map.md** — A table mapping every story ID (from specs/stories/) to the specific files that will be created or modified to implement it. > > 8. **deployment.md** — Deployment architecture: environments (dev/staging/prod), CI/CD pipeline steps, infrastructure-as-code approach, secrets management strategy, rollback procedure. --- ### Agent 2 — ui-designer **Prompt:** > Read all files in specs/stories/ and specs/design/api-contracts.md (if it exists; wait or proceed with story context if not yet available). > > For every story with layer "UI", create a self-contained HTML mockup: > > - The mockup must be a single .html file with all CSS and JavaScript inlined (no external dependencies). > - Use realistic mock data that matches the field names and types defined in api-contracts.md. > - Show the primary happy-path state. Include at least one empty/error state as a toggle or commented section. > - Label each interactive element with its API call (e.g., "POST /api/auth/register"). > - The filename must match the story ID: E{n}-S{n}.html > > Write all mockups to specs/design/mockups/. --- ## Step 2 — Post-Completion Validation After both agents complete, perform a validation pass: 1. Read `specs/design/api-contracts.md` 2. Read all HTML files in `specs/design/mockups/` 3. For each mockup, extract field names used in forms and displayed data 4. Compare against the corresponding API endpoint schemas in `api-contracts.md` 5. Flag any divergence: field present in mockup but missing from API contract, or vice versa Report the validation results: - List any mismatches found (mockup file, field name, expected vs. actual) - If all shapes align, confirm: "All UI data shapes validated against API contracts." --- ## New Artifacts vs forge_v2 | Artifact | Purpose | |----------|---------| | `api-contracts.schema.json` | OpenAPI 3.0 schema — machine-readable by the evaluator for contract testing | | `data-models.schema.json` | JSON Schema — used by builder agents to generate type-safe code | | `component-map.md` | Maps stories to implementation files — used by builder agents for routing | These are new in this pipeline. forge_v2 produced only markdown documents. The `.schema.json` files enable automated validation in later pipeline stages. --- ## Output | File | Purpose | |------|---------| | `specs/design/system-design.md` | Architecture overview | | `specs/design/api-contracts.md` | Human-readable API contracts | | `specs/design/api-contracts.schema.json` | OpenAPI 3.0 machine-readable schema | | `specs/design/data-models.md` | Human-readable data model definitions | | `specs/design/data-models.schema.json` | JSON Schema for all data entities | | `specs/design/folder-structure.md` | Proposed directory tree with annotations | | `specs/design/component-map.md` | Story ID → implementation files mapping | | `specs/design/deployment.md` | Deployment architecture and CI/CD plan | | `specs/design/mockups/E{n}-S{n}.html` | One self-contained HTML mockup per UI story | --- ## Gate **Human approval is required before proceeding to `/build`.** After presenting all artifacts and validation results, ask: "Does this architecture and these mockups look correct? Approve to proceed to `/build`, or provide corrections." --- ## Gotchas - **API shape divergence.** The planner and ui-designer run concurrently and may independently invent field names. The post-completion validation step exists specifically to catch this. Never skip it. - **Missing deployment.md.** Builder agents need to know the target environment. This file is required, not optional. - **Mock data must match API contracts.** If a mockup shows a `user_name` field but the API contract defines `username`, the downstream evaluator will flag a mismatch. - **No folder structure means builder agents guess.** The `folder-structure.md` and `component-map.md` are the routing instructions for the build phase. Missing or vague entries cause agents to create files in wrong locations. - **Schema files must be valid JSON.** Run a syntax check on both `.schema.json` files before presenting for human review. - **Concurrent execution requires a single message.** Both Agent tool calls must appear in the same response. Do not run them sequentially.