web-design-extractor

Website Design Extractor

Produce faithful design specifications based on visible evidence. Must distinguish observed facts from visual inferences; must not claim to possess source CSS, behavior, or assets that the input materials do not prove.

Choose an evidence path

Probe the environment first, then choose the route — go with the strongest one available, don't fall back to source code right away.

① 用户项目里已有 playwright   → 用它（代码最少，也不让人白装一个浏览器）
② 机器上有 Chrome / Edge      → 用 scripts/browser-extract.mjs（零依赖，Node ≥ 22）
③ 都没有                      → 退源码路线，并强制标注「转录边界」

For specifics on how to do it, how to read the outputs, and what pitfalls exist, see references/browser-route.md。

The two routes are additive, not either-or: source code gives you "which tokens this site defines and what they're called", the browser gives you "which ones are actually in use and what they look like in practice". If you can do both, do both.

Choose by input form:

URL only (with browser): run scripts/browser-extract.mjs, get computed styles, four-viewport measurements, and screenshots. The values obtained this way are [OBSERVED: URL], and can be used directly as replication constraints.
URL only (no browser): fall back to the source code route, see the degraded path below. The values obtained this way are [INFERRED]。
Screenshots only: analyze the images at their original size. Measured values, layout rules, and undisplayed states should all be treated as inferences unless the images can directly prove them.
URL plus screenshots: use the screenshots at the viewport specified by the user as the baseline of visual fact. Use the URL to verify structure and computed styles; when discrepancies are found, mark them explicitly and do not silently merge them.
Multiple screenshots: compare them as samples of different viewports or states. Only when the samples show breakpoint changes can the layout be considered to have responsive behavior.
When there is no browser control capability (degraded path): you can only get the server-returned HTML and the CSS written in it, not the rendered computed styles, breakpoint behavior, or screenshots.In this case you must not pretend to have taken the paths above, and must:
1. At the beginning of design.md , write a section "Evidence Boundaries", listing item by itemwhat is available(HTML structure, declared CSS variables, inline styles, literal hardcoded values) andwhat is not available(computed styles, breakpoint behavior, screenshots, font files, interaction states). Note:this section must be filled in for both routes, and even during normal operation you must clearly state "what was covered / what was not covered this time", and write "none" if there are no gaps — the browser route likewise only covers the first screen and does not capture interaction states;
2. Record literally written token values as [OBSERVED: URL]；"which token is used on which element" must always be recorded as [INFERRED]— just because the source code writes #fffin both places does not mean they use the same thing;
3. Breakpoints, hover, focus, empty states, and error states must all be [UNKNOWN], do not fill one in using "common practice";
4. In the delivery notes, state that this is degraded operation, and give concrete ways to complete the evidence (add a screenshot; or rerun in an environment with browser control capabilities).
Degradation is not the problem,presenting degradation as a complete run is the problem。

When the user does not provide a URL or image, ask them to provide one. Only ask for viewport information when the target viewport would materially affect the result.

Collect evidence

From URL

Open the exact URL provided by the user. By default, only handle publicly accessible content. Whether pages behind login, private, or paywalls can be handledis the user's compliance judgment, not this Skill's judgment—— If the user asks for analysis, analyze it, and when done, note in the "Evidence" section that this part of the content comes from access permissions provided by the user.
Record the final URL, page title, viewport, collection time, and visible page state; capture a page screenshot when it helps preserve visual evidence.
Identify page regions in visual order: global shell, navigation, first screen, main sections, repeated content patterns, calls to action, forms, and footer.
Read representative visible elements and their computed styles. Prioritize recording font, font size, font weight, line height, text/background/border colors, spacing, border radius, shadows, grid or flex layout, and transition or animation properties.
Count and classify recurring visible components, such as buttons, links, input fields, cards, lists, tables, and navigation. Check a small number of representative items; do not scrape the entire page.
Record only interactions or states that have been observed. When hover, focus, loading, empty, error, expanded, or mobile states do not appear, mark them as unknown and do not fabricate them.

From screenshot

Record the file name, original pixel dimensions, and the viewport or device information provided by the user.
First divide the image into regions based on alignment, repetition, contrast, whitespace, and content hierarchy, then name the components.
Infer proportional typographic hierarchy, spacing rhythm, column structure, color roles, border radius, shadows, image treatment, and breakpoints; each inference must be clearly labeled.
Extract only the visible text needed to explain hierarchy or component structure; blurred OCR text must not be presented as authoritative copy.
Do not infer HTML semantics, DOM structure, exact font files, exact CSS values, or interactions not shown from pixels alone.

Write the spec

Before drafting, read references/design-md-template.md. Write the completed result to design.mdin the directory specified by the user; when no location is specified, write to the current project, and do not overwrite an existing design.md, instead use design-extracted.md。

Before writing, look for docs/product/ the product experience baseline corresponding to the current project and current end (c-end/ or admin/). When a baseline exists, in design.md add a "Product Baseline Mapping": list reusable navigation, tokens, components, or page patterns, and flag conflicts between external evidence and the confirmed baseline. External websites or screenshots may only serve as references and must not silently override the current product's brand, domain terminology, information architecture, or core interaction patterns.

When no product baseline exists, record only the current extraction results; do not establish a complete product-level specification based on a single external reference alone. If the user is defining the first version of the product experience, it is recommended to first use product-experience-foundation。

Use the following evidence labels throughout:

[OBSERVED: URL]: rendered DOM, computed styles, or directly visible page facts.
[OBSERVED: SCREENSHOT]: Visible details directly supported by the provided screenshots.
[INFERRED]: Reasonable reconstruction design decisions.
[UNKNOWN]: Substantive implementation details that the input materials fail to establish.

Use exact values only when a URL check can confirm them. Values from screenshots should use relative descriptions or explicit approximations. Explain brand intent, visual tokens, page architecture, components, behavior, accessibility observations, and reconstruction rules separately. Use "must" for non-negotiable replication requirements and "should" for recommendations.

Pre-delivery verification

Include source, collection date, viewport, and evidence type.
Label every non-obvious conclusion as observed, inferred, or unknown.
Every repeated component has clear structure, variants, visible states, and, where evidence supports it, responsive behavior.
Distinguish actually observed accessibility facts from recommended requirements; do not claim WCAG compliance based on visual inspection alone.
Check that typography, color, spacing, corner radius, shadow, and motion rules do not contradict one another.
Only write what the user has given. Do not guess or fill in private data, hidden content, or inaccessible resources that the user has not provided— if the user provided it, write it as given, and note the source in the "Evidence" section.
When a baseline exists, confirm that the "Product Baseline Mapping" and all substantive conflicts have been recorded.
「Evidence Boundary" section is filled in—both routes must be filled in, and if there are no gaps, write "None".
If a redirect occurred, the final URL and region/language impact have been written into the "Evidence" table, and the Hong Kong dollar version has not been described as the US version.
After writing, scan once for garbled Chinese text:grep -rnI $'\xef\xbf\xbd' <design.md 所在目录>

At delivery, briefly state the output files, the evidence used, and the most important remaining unknowns.