stitch-extract-design-md

Extract a design system from source code

Quick start

1. "Extract primary colors and spacing from the CSS of a WeCom appointment Web page; provide locally reviewable results first."
2. "When the build fails, read the Angular templates and theme; preserve the existing scope and sources."
3. "Compare the light and dark theme differences of a store admin backend and record the sources; flag missing inputs and validation status."

For designers, frontend developers, and teams maintaining this process. Designers provide intent and assets, developers provide engineering/tools, and the team preserves sources and acceptance status during handoff.

Capability boundaries

✅ Good at

• Extracting primary colors and spacing from the CSS of a WeCom appointment Web page.
• Reading Angular templates and themes when the build fails.
• Comparing light and dark theme differences of a store admin backend and recording sources.

⚠️ Requires assets

• Frontend source root directory.
• Theme, CSS, or component files.
• The target theme and whether a compatible YAML needs to be uploaded.

❌ Inapplicable scenarios and handoff

• Only looking at screenshots to extract semantics → stitch-design-md.
• Creating an entirely new visual style → stitch-ui-style.
• Remotely creating or applying a system → stitch-manage-design-system, delivering DESIGN.md as input.

Workflow

1. Read package.json and the directory to determine the framework and CSS toolchain.
2. Read the extraction guide in the existing references according to the framework; theme first, then components, recording specific files and selectors.
3. Extract color roles, fonts, spacing, border radius, component states, and responsive conditions, distinguishing facts from suggestions.
4. Write .stitch/DESIGN.md: YAML name/colors plus a six-section semantic document; omit unknown Project IDs and use Source.
5. Verify the source, override relationships, and patterns of each token; mark mood as inferred when not rendered.

Order by dependency: source verification → local artifacts → authorized external operations → validation 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 its purpose, without vague prompts like "please provide more context".

Security and result validation

Do not read unrelated account configurations, do not 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; the output should note sources, decision basis, what was actually executed, and what has not yet been verified.

• Color values can be traced back to the source code, and similar colors have not been silently merged.
• The name/colors YAML is parseable.
• Breakpoints and interaction states distinguish observed from suggested.

Customizable: theme mode, component scope, language, and paths; for example, extract only dark-mode buttons/forms. Value-added checks: token traceability table; similar color difference list; framework on-demand routing.

FAQ

Q1: What is the main deliverable? name: Store appointment; colors.primary: '#2563eb' (demo input); Source: --brand-primary in src/theme.css; the atmosphere is inferred from source code and has not yet been rendered.

Q2: When should a different entry point be used instead? Extract semantics from screenshots only → stitch-design-md; create a brand-new visual style → stitch-ui-style; remotely create or apply a system → stitch-manage-design-system, delivering DESIGN.md as input.

Q3: What happens if inputs are missing? First provide a clearly marked draft of local assumptions and list "Needed additions: frontend source root directory; theme, CSS, or component files; target theme and whether a compatible YAML needs to be uploaded." Write operations that depend on these inputs are not executed.

Q4: How is completion judged? Color values can be traced back to the source and approximate colors have not been silently merged; the name/colors YAML can be parsed; breakpoints and interaction states distinguish observed from suggested.

Q5: How is it customized? Theme mode, component scope, language, and paths; for example, extract only dark-mode buttons/forms; 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 a successful upload, 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 executing detailed mappings, APIs, or templates, read Extended workflow。
• When encountering failures or abnormal input, read Anti-patterns and Gotchas。
• When edge cases, compatibility, customization, and authorization are involved, read In-depth FAQ。
• When complete input/output and verification scenarios are needed, read Local application examples。
• The local implementation basis is this skill's accompanying source code and fixed 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 that 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: extract a traceable DESIGN.md from frontend source code; use when the application cannot be built, when visual tokens of React/Vue/Svelte/Angular/CSS need to be audited, or when migrating the design language to Stitch. Use stitch-design-md only for summarizing screenshot semantics..

Rules

• Read before writing: first confirm the current state and actual capabilities, then execute 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 output are missing, clearly mark them as NOT_VERIFIED。
• Idempotency first: retain request identifiers and stage status; when results are unclear, query first and do not blindly retry.
• 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: Run 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 minimal sufficient steps, and record evidence at key state changes; retain an associable state or receipt for every external call.

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 adjacent tasks were not misrouted to this skill.
• The inputs, target objects, versions, and output locations are all clear, and no guessed values were used in place of required values.
• All write, payment, publishing, or irreversible actions are within the scope authorized by the user.
• 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: A document or prompt is not the same as actual execution; the actual execution level must be indicated.
2. Retrying on error: A timeout or lost response may already have created remote state; query first before deciding whether to retry.
3. Implicit scope expansion: Batch, full-scale, publishing, overwrite, and payment 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, publishing, and irreversible actions require explicit authorization. If the request requires another skill, do not copy its body text; hand off by skill name and preserve the current task context.

Progressive disclosure

• When inputs/outputs, state, and authorization points need to be determined, read references/workflow-contract.md。
• When a pre-delivery self-check is needed, read references/validation-checklist.md。
• When encountering timeout, partial success, or recovery scenarios, read references/error-recovery.md。
• For first runs, refusing overreach, and failure recovery, refer respectively to examples/happy-path.md、examples/boundary-refusal.md、examples/failure-recovery.md。