SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsdesign-spec-prototyper

design-spec-prototyper

Design & creation

View repository

Updated 10-16 01:17

About this skill

Design Specification Prototype Generator

Build prototypes that can go directly into the implementation phase.Both types of input must be referenced simultaneously: the design specifications provide brand tokens and rules, while the design mockup images provide the actual composition of this page. Values already observed in the specifications have higher evidence priority than generic design suggestions.

Inputs and Defaults

  1. Find both types of input; when unspecified, search within the current project:

    Input What to provide What to do if missing
    design.md / DESIGN.md Brand tokens, component rules, typography, evidence boundaries—continuously accumulated product facts Only images, no specifications → first go through web-design-extractor to turn the images into specifications
    Design mockup images / screenshots The actual composition of this page: sections, element order, hierarchy, spacing rhythm Only specifications, no images → use the "composition evidence within the specifications" (see below), and state the evidence source and its limits in the delivery notes
    Reference images (not belonging to this page, e.g., competitor page screenshots) Visual language reference: color tendencies, texture, motion style Cannot be used as composition evidence—see below

    When neither is available, ask the user to provide them.

    When there are only specifications and no images, the composition evidence is borne by the specifications themselves, but it must be made clear which kind it is:

  • If the section order in the specifications was originally extracted frompage DOM order or API data order, then it is [OBSERVED] -level composition evidence, and the sections can be arranged directly according to it. When going through web-design-extractor 's URL route (rather than the screenshot route), this is usually the case.
  • If the order in the specifications is merelysummarized by the person writing the specifications, then it is [INFERRED], and following it is acceptable, but it must be pointed out in the delivery notes.
  • In both cases, the followingcannot be obtained: the visual weight of each section (which is more eye-catching), the specific values of the spacing rhythm, and breakpoint behavior. All of these must be marked as unknown; do not fill one in based on "common practice".

The difference lies inwhether the source can be traced back. If it can be traced, follow it; if not, mark it as unknown—do not pretend to know just to make the page look good.

When the images are not of this page—this is the step most easily done wrong.

You have a pile of screenshots, but they are fromreference sites / competitor pages(web-design-extractor 's input), not the design mockups of this page. In this case, the composition evidencefalls back to prd.md：

Which takes precedence
Section order, element order, hierarchy Only based on prd.md the user flow in Section 5
Color tendencies, texture, motion style You may refer to the image, butthe page structure must never be copied

In the delivery notes,the source of the composition must be stated(PRD Section 5 / design mockup / spec).

Copying the composition of a reference site will produce a page that completely fails to match the PRD—and it won't be apparent during review, because the page itself looks quite good. This is one of the few "beautifully wrong" failure modes in this pipeline.

One more thing: when reading the spec, if it contains sections such as "Applicability / Boundaries / Rebuild Rules",you must read them to the end. The spec's author may have already stated that "this page cannot be used as a template"—and no step in the process will automatically read that conclusion. 2. Look up docs/product/ for the product experience baseline corresponding to the current project and current platform (c-end/ or admin/), as well as available prototype page shells or component patterns; when there is no baseline, record the gap and do not fabricate product-level rules. 3. Extract the page type, product context, target route, visual tokens, layout rules, components, responsive notes, accessibility requirements, and explicit unknowns. 4. Use the tech stack requested by the user; when unspecified, default to a standalone prototype.htmlwith Tailwind. 5. Determine the font source:google、local or system. Online standalone prototypes default to google; the user or design spec may directly specify the font family, weight, and italics from Google Fonts. When the project already has a brand font, the user requires offline display, or the network is uncontrollable, prefer local or system. 6. Determine the feature name and requirements directory. Prefer inferringdesign.md from the specified PRD, the directory containing <feature-name>, or the user's requirements; when it cannot be uniquely determined, ask the user to specify it, and do not create a generalized outputs/ directory. 7. All standalone review artifacts must be archived to docs/prd/<feature-name>/: the default output is docs/prd/<feature-name>/prototype.html。prd.md、design.md、prototype.html、demo.md are optional assets belonging to the same feature; create only the files needed for the current task, and do not overwrite existing files.

Requirements Asset Archiving

A standalone prototype is a requirements review asset, not a temporary file in the project root directory. Use the following structure:

docs/prd/<feature-name>/
├── prd.md             # 如已有或本次需要
├── design.md          # 设计依据，如已有或本次需要
├── prototype.html     # 本 Skill 的默认独立原型产物
└── demo.md            # 可选：项目内演示的评审结论
  • When docs/prd/<feature-name>/ already exists, use the same directory and do not create a duplicate feature folder.
  • When the output path specified by the user is not in the corresponding feature directory, explain the archiving convention and ask for confirmation; without explicit approval, do not scatter standalone prototypes into outputs/, the project root directory, or unrelated directories.
  • Only when the user explicitly needs a high-fidelity prototype within the project, switch to pm-frontend-prototype; that Skill's output is an isolated prototype entry point in the project source code, not the default replacement for this directory.

Font Strategy

  • google (online default): use only when there is no higher-priority brand font. The user may directly specify the font family, weight, and style from Google Fonts; generate the corresponding Google Fonts CSS2 link,preconnect , and a complete system fallback. Request only the weights and styles actually used, and use display=swap。
  • local: for scenarios where the user has provided font files, offline review is required, or the layout must be reproduced reliably. Place font files in docs/prd/<feature-name>/assets/fonts/, referenced via the relative path @font-face .If the user provided it, use it; don't ask about the source— Font licensing is for the user to judge, not this Skill; if the user hasn't provided one, use the closest fallback, and don't go looking for font files online yourself.
  • system: For scenarios with no reliable font source, primarily Chinese content, and uncontrollable network, or where the user requires no dependence on external resources. Explicitly write out the cross-platform fallback stack.
  • Design specs, product experience baselines, or fonts the user has explicitly specified take precedence over these defaults. When there is only screenshot evidence, mark the font name as [INFERRED]; when there is no usable source, do not pretend to have restored the brand font.
  • Chinese fonts must have a Chinese fallback; only introduce CJK fonts such as Noto Sans SC from Google Fonts when explicitly specified or supported by design evidence. Do not convert text to SVG or images to circumvent font issues.

Determine design authority

Follow this priority order:

  1. Explicit user requirements: Including explicitly approved product experience changes.
  2. Confirmed product experience baseline: The current frontend's product terminology, page shell, component patterns, and global interaction rules.
  3. Evidence already observed in the design spec: Recorded tokens, component rules, and visible structure—the spec is continuously accumulated product fact.
  4. Composition directly visible in the design mockup image: Page sections, element order, hierarchy. The image is used to restorethis time'spage appearance, not to overturn the tokens in the spec.
  5. Spec inference rules: Choices recorded as [INFERRED] are reasonable defaults, not immutable facts.
  6. Design-related skills you have installed (optional): Only when the spec is incomplete, provide usability, responsive behavior, alternative typography, accessibility, and tech stack guidance.

Information read from the image is annotated according to this repository's unified convention: directly visible is marked [OBSERVED: SCREENSHOT], what needs inference is marked [INFERRED], states not shown in the image are marked [UNKNOWN]——Do not fill in for the image what it did not draw。

When the spec and the image conflict, which takes precedence

What the conflict is about Which takes precedence Why
Token type— Colors, fonts, corner radius, spacing baselines Spec The spec is accumulated product fact; the image may just be a temporary choice from one particular delivery
Composition type— Page sections, element order, hierarchy Image That is exactly what needs to be restored this time
The image does not belong to this page(reference site / competitor page screenshot) prd.md Section 5 Reference images can only serve as visual language references; their page structure is not what needs to be restored this time

Substantive conflicts must bepointed outin the delivery notes, not silently resolved by choosing one—otherwise the next iteration will have no way to judge why it was decided this way at the time.

Do not replace recorded color palettes, typography systems, or visual directions with generic design suggestions. When the design spec or external references substantively conflict with the product baseline, retain the baseline by default; change it only when the user explicitly approves the deviation, and state in the delivery whether the baseline should be written back.

Design research phase

When the spec is complete, go straight into the build; no extra retrieval is needed.

When the spec lacks usability, responsive, typography, or accessibility guidance,recommendeduse ui-ux-pro-max to fill the gaps (for installation, see "Companion recommendations" in the repository README). Once installed, use it to retrieve guidance on the design system and the corresponding tech stack:

# <UIUX_DIR> 换成你本机的实际安装目录，不要照抄任何写死的绝对路径
python3 <UIUX_DIR>/scripts/search.py "<产品> <行业> <页面类型> <风格>" --design-system -p "<项目名>" -f markdown
python3 <UIUX_DIR>/scripts/search.py "<页面类型> 响应式 无障碍" --stack <技术栈>

It still works without installing it: make your own judgments based on the product experience baseline and design spec, and note in the delivery notes which decisions lack a basis—do not pretend you retrieved anything.

The goal at this stage is to fill the gaps in the spec, not to replace it: if the design spec already provides token values, you must not write a generic palette into the prototype.

Build the prototype

Before implementing, read references/prototype-contract.md。

  1. Create semantic document structure and explicit page titles; provide real labels for form fields and accessible names for icon-only controls.
  2. Before writing component styles, define design spec tokens as CSS custom properties or as design tokens for the target tech stack.
  3. Establish font sources before writing typography styles.google use a Google Fonts CSS2 link and system fallbacks;local use the relative @font-face；system from the feature directory; do not introduce external fonts. Use only fonts specified by the user or the spec, or, when the spec is missing, record the basis for the choice.
  4. First implement the desktop layout recorded in the spec, then derive mobile behavior from the spec; when the spec provides no breakpoint evidence, adopt conservative responsive behavior and note in the delivery notes that it is an implementation inference.
  5. Build only the components relevant to the current page; prefer reusing the prototype page shell, component patterns, and spacing, color, corner radius, typography, surface elevation, and motion values from the product experience baseline.
  6. Use one consistent SVG icon set or inline SVGs; do not use emoji as UI icons. For the brand logo, usethe asset files provided by the user—anything drawn from memory neither looks like it nor is actually ours.
  7. Add only the interactions the prototype can truthfully demonstrate; unless the user asks for an integration, login, payment, or third-party actions should use non-functional links or clearly marked demo handlers.
  8. Add visible keyboard focus states, hover feedback that does not cause layout shift, reduced-motion support, and mobile-safe overflow handling.
  9. Before outputting, confirm that prototype.html is located in the corresponding docs/prd/<feature-name>/ directory; if the design spec comes from that directory, link to it in the prototype delivery notes rather than copying out a second spec.

Validate and deliver

  1. Run static checks + four-tier preview checks：

    node <this-skill>/scripts/preview-check.mjs <prototype.html> <截图目录>

    covering in one pass: U+FFFD garbled characters,id whether it is unique,aria-controls whether it is dangling, whether decorative SVGs are marked aria-hidden、<h1> count, doctype / lang / viewport, horizontal overflow at the four tiers 375/768/1024/1440, actual font loading, and take a screenshot of each.If there is a FAIL, fix it before delivering; don't carry it into the delivery notes as a "known issue."

  2. When a browser is unavailable, the script exits with exit code 3 (no Chrome/Edge, or Node < 22). In that case you must not claim visual validation was completed—write truthfully in the delivery notes that "the preview check could not be run." "Validated" and "not validated" must be distinguishable at a glance, otherwise reviewers will mistake unvalidated for validated.

  3. Things scripts cannot check and that require human eyes: whether text is clipped when online font fallback takes effect, whether the hierarchy is weak, and whether the focus state is visible.

  4. Deliver the feature directory and prototype file paths, font source/font family/font weight/fallback (when the brand font is unavailable, see prototype-contract.md for the replacement relationship declaration requirements), composition source, the design specification sections and product experience baseline sections used, supplementary design guidance that has a substantive impact on the results, and remaining assumptions; mark recurring but unconfirmed new patterns as candidates, and do not automatically write them as global rules.

  5. After modifying the files, scan separately once more for garbled Chinese characters: grep -rnI $'\xef\xbf\xbd' <原型所在目录>