stitch-design-md

Source notice: This skill contains content derived from google-labs-code/stitch-skills (Apache License 2.0, full text in the same directory LICENSE.txt; upstream is not an officially supported Google product). This project has adapted and integrated it; copyright for the original content belongs to Google LLC and its contributors.

Stitch Semantic Design System Documentation

Quick start

1. "Extract color roles from the store booking page; give locally reviewable results first."
2. "Organize local HTML into a Stitch design document; preserve the existing scope and sources."
3. "Check whether DESIGN.md can guide the next screen; flag missing inputs and verification status."

For designers, front-end developers, and teams maintaining this process. Designers provide intent and materials, developers provide engineering/tooling, and the team preserves sources and acceptance status during handoff.

Capability boundaries

✅ Good at handling

• Extracting color roles from the store booking page.
• Organizing local HTML into a Stitch design document.
• Checking whether DESIGN.md can guide the next screen.

⚠️ Requires materials

• Actual HTML/screenshots or Stitch identifiers.
• Theme and representative page scope.
• Observation sources and the desired output file path.

❌ Inapplicable scenarios and handoff

• Precise framework source token mining → stitch-extract-design-md.
• New style proposals → stitch-ui-style.
• Publishing the system to a project → stitch-manage-design-system.

Workflow

1. Distinguish local from Stitch sources; local does not force MCP or a fabricated projectId.
2. Extract mood, color value roles, fonts, corner radii, shadows, spacing, and navigation from actual assets.
3. Convert implementation class names into understandable visual descriptions while preserving exact values and sources.
4. Write the six-section DESIGN.md; use Source locally, and mark unknown or inferred values separately.
5. Run the entry point's five semantic lints; verify usability by reconstructing the palette/layout description from the document, and on failure keep the old document and output a list of what is missing.

Order by dependency: source verification → local artifacts → authorized external operations → verification handoff. For multiple tasks, do the current main path first; when information is missing, output an assumption draft first, then precisely list what is missing and what it is for, without using vague prompts like "please provide more context."

Security and result verification

Do not read unrelated account configurations or collect user passwords; credentials are provided only by the environment or authorized connectors. Use only demo data in examples; before uploading, replace customer names, phone numbers, and order numbers with demo values, and check HTML, screenshots, and file metadata. Do not write keys, session cookies, full base64 text, or signed download URLs into reports/repositories. Do not fabricate unverified parameters, visual effects, or business numbers; note sources, decision basis, what was actually executed, and what has not yet been verified in the output.

• Six sections are non-empty, and colors have names/values/roles.
• There are no unresolved placeholders or fabricated project IDs.
• Do not claim visuals are confirmed without screenshot evidence.

Customizable: source mode, theme, component scope, terminology language, output path. Value-added checks: local/remote dual sources; semantic lint; separation of observations and recommendations.

FAQ

Q1: What are the main deliverables? Source: demo/theme.css; primary action blue (#2563eb) used for "Confirm appointment"; layout is top bar + appointment list; unobserved hover states are marked as recommendations.

Q2: When should a different entry point be used instead? Precise framework source token mining → stitch-extract-design-md; new style proposals → stitch-ui-style; publishing the system to a project → stitch-manage-design-system.

Q3: What happens when inputs are missing? First provide a clearly marked draft of local assumptions, and list "Needed: actual HTML/screenshots or Stitch identifiers; theme and representative page scope; observation sources and desired output file paths". Write operations that depend on these inputs are not performed.

Q4: How is completion determined? Six sections are non-empty, colors have names/values/roles; no unresolved placeholders or fabricated project IDs; without screenshot evidence, do not claim visuals are confirmed.

Q5: How to customize? Source mode, theme, component scope, terminology language, output path; when not provided, use existing project values and mark assumptions.

Q6: Does it automatically upload, install, or go live? Only perform actions covered by the current request and existing authorization; without a remote receipt, do not claim upload success; without runtime verification, do not claim it is live. Additional installation or scope expansion requires explaining the specific impact first.

Reference as needed

• When performing detailed mapping, API, or templates, read Extended workflow。
• When encountering failures/abnormal inputs, read Anti-patterns and Gotchas。
• When involving edge cases, compatibility, customization, and authorization, read In-depth FAQ。
• When complete input/output and verification scenarios are needed, read Local application examples。
• The local implementation basis is the source code accompanying the current skill and pinned upstream snapshot; the structure follows Agent Skills specification. The tool's current behavior is subject to the actual schema; when not connected, do not claim online behavior has been verified.

When to use

Load this skill when the user needs to select and execute a verifiable, recoverable professional workflow for the current request . First extract the goal, inputs, constraints, delivery format, and acceptance criteria from the request; the description summary is: organize and verify a semantic DESIGN.md from Stitch screens or user-provided HTML/screenshots; trigger when a reusable visual language and source notes are needed. For precise source extraction use stitch-extract-design-md; for prompts and screen generation use their respective entry points..

Rules

• Read before write: first confirm the current state and real capabilities, then perform actions that change external state.
• Least privilege: use only the files, tools, accounts, and network scope required to complete the current step.
• Evidence first: when run results, resource IDs, versions, hashes, or test outputs are missing, clearly mark them as NOT_VERIFIED。
• Idempotency first: retain request identifiers and stage status; when results are unclear, query first rather than blindly retrying.
• Privacy and security: logs, examples, receipts, and error messages must not contain tokens, cookies, keys, or personally sensitive data.

Workflow

Step 1: Clarify intent

Confirm whether this skill matches the goal; if it is only an adjacent need, hand it off to a more precise skill.

Step 2: Perform pre-checks

Confirm the goal, inputs, constraints, available tools, success criteria, and failure boundaries; if any key condition is unknown, stop at the read-only stage.

Step 3: Form a plan

List the tools that will be called, the objects that will be changed, the success criteria, and the safe exit method after failure.

Step 4: Execute actions

Execute in minimal sufficient steps, and record evidence at key state changes; every external call retains an associable state or receipt.

Step 5: Verify delivery

Output the results, verification evidence, incomplete items, risks, and clear next steps, and state facts, inferences, and unverified items separately.

Validation checklist

• The skill trigger conditions are consistent with user intent, and no adjacent task was misrouted to this skill.
• Inputs, target objects, versions, and output locations are all clear, and no guessed values were used in place of required values.
• All write, payment, publication, or irreversible actions are within the scope of user authorization.
• Results have been verified with independent checks; "command succeeded" or "file exists" alone does not count as complete acceptance.
• The output includes actual evidence, failed/skipped items, remaining risks, and executable next steps.

Gotchas

1. Mistaking the plan for the result: Documentation or prompts are not equivalent to actual execution; the actual execution level must be indicated.
2. Retrying on error: A timeout or lost response may already have produced remote state; query first before deciding whether to retry.
3. Implicit scope expansion: Batch, full-volume, publication, overwrite, and paid operations are not a natural extension of ordinary reads and writes.
4. Version drift: When referencing external resources, record the version, tag, or commit; do not treat a mutable branch as release evidence.
5. Stale evidence: Caches, old screenshots, and historical tests cannot prove the current environment; refresh key evidence before delivery.

Non-applicability and boundaries

Do not exceed the scope given by the user; write, payment, publication, and irreversible actions require explicit authorization. If the request requires another skill, do not copy its body; hand off by skill name and preserve the current task context.

Progressive disclosure

• When inputs/outputs, states, and authorization points need to be determined, read references/workflow-contract.md。
• When self-checking before delivery is needed, read references/validation-checklist.md。
• When encountering timeouts, partial success, or recovery scenarios, read references/error-recovery.md。
• For first runs, refusal of privilege escalation, and failure recovery, refer respectively to examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。