stitch-manage-design-system

Manage Stitch project design systems

Quick start

1. "Create the store back-office DESIGN.md as a project system; first give a locally reviewable result."
2. "Apply the existing system to the appointment list and detail screens; preserve the existing scope and source."
3. "Read-only check the project's current design system and screen instances; flag missing inputs and verification status."

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

Capability boundaries

✅ Good at handling

• Create the store back-office DESIGN.md as a project system.
• Apply the existing system to the appointment list and detail screens.
• Read-only check the project's current design system and screen instances.

⚠️ Requires materials

• A real projectId and an available MCP schema.
• A shareable DESIGN.md or an existing assetId.
• The instance id/sourceScreen of the screens to apply to and the scope of changes.

❌ Inapplicable scenarios and handoff

• Writing only a local design document → stitch-design-md.
• Extracting styles from source code → stitch-extract-design-md.
• Modifying business APIs or databases → the target project's development workflow, with the design system's mapping to components attached.

Workflow

1. Query get_project, list_design_systems, and the required screens, preserving real resource ID strings.
2. Check DESIGN.md's name/colors, color roles, fonts, and corner radii; when there are no source materials, generate only a local draft marked as a suggestion.
3. When upload is already authorized and covered, upload the document and record the returned sourceScreen and screenInstance.id; otherwise submit a specific asset list.
4. Call create_design_system_from_design_md according to the current schema, or use an existing system; do not treat the existence of a local file as remotely applied.
5. apply_design_system passes only the id/sourceScreen of the selected instances, filtering DESIGN_SYSTEM_INSTANCE; read the receipt and update the target project metadata.

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, first output an assumption draft, 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, and do not collect user passwords; credentials are provided only by the environment or authorized connectors. Examples use demo data only; before uploading, replace customer names, phone numbers, and order numbers with demo values, and check HTML, screenshots, and file metadata. Writing keys, session cookies, full base64 text, or signed download URLs into reports/repositories is prohibited. Unverified parameters, visual effects, and business figures must not be fabricated; outputs must note the source, basis for decisions, what was actually executed, and what has not yet been verified.

• selectedScreenInstances does not include x/y/width/height.
• The system assetId comes from list_design_systems.
• Upload, create, and apply each have their own status; on failure, do not continue serially.

Customizable: system name, theme, specified instance list, query-only/create/apply modes. Value-added checks: instance filtering; phased status of system and screen; project-level token deduplication.

FAQ

Q1: What are the main deliverables? Offline input instance {id:'demo-i',sourceScreen:'projects/123/screens/a',x:9} → the request instance retains only id/sourceScreen; apply was not called.

Q2: When should a different entry point be used instead? Local design document only → stitch-design-md; extract styles from source code → stitch-extract-design-md; modify business APIs or database → target project development workflow, with the design system's mapping to components attached.

Q3: What happens when inputs are missing? First provide a clearly marked draft of local assumptions, and list "Needs to be supplemented: real projectId and available MCP schema; shareable DESIGN.md or existing assetId; instance id/sourceScreen of the screen to be applied and modification scope". Write operations that depend on these inputs are not executed.

Q4: How is completion determined? selectedScreenInstances does not contain x/y/width/height; the system assetId comes from list_design_systems; upload, creation, and application each have their own status, and a failure does not continue serially.

Q5: How to customize? System name, theme, specified instance list, query-only/create/apply modes; when not provided, use existing project values and indicate 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, and 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 fixed upstream snapshot; the structure follows the Agent Skills specification. The tool's current behavior is subject to the actual schema; when not connected, do not claim to have verified online behavior.

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: query, create, update, or apply a Stitch project-level design system; triggered when an existing DESIGN.md needs to be associated with a remote project, or when an existing system needs to be applied to a specified screen. Extracting source code tokens alone does not trigger remote writes..

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 phase status; when results are unclear, query first and do not retry blindly.
• 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 prechecks

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 to be called, the objects that will be changed, the success criteria, and the safe exit method after failure.

Step 4: Execute actions

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

Step 5: Verify delivery

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

Validation checklist

• The skill trigger conditions are consistent with the user's intent, and no adjacent task was misrouted to this skill.
• The inputs, target objects, versions, and output locations are all clear, and no guessed values were used to replace required values.
• All write, paid, publish, or irreversible actions are within the scope of user authorization.
• The results have been verified with independent checks; "the command succeeded" or "the 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 the same as actual execution; the actual execution level must be stated.
2. Incorrect retry: A timeout or lost response may already have produced remote state; query first before deciding whether to retry.
3. Implicit scope expansion: Batch, full-scale, publish, overwrite, and paid operations are not natural extensions 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, paid, publish, and irreversible actions require explicit authorization. If the request requires another skill, do not copy its body text; hand off by skill name and retain the current task context.

Progressive disclosure

• When inputs/outputs, state, 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 overreach, and failure recovery, refer respectively to examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。