Website Design System
Turn a URL into a usable, traceable design-system website. A written audit, palette, screenshot gallery, or static component collage alone does not finish the task. Deliver running examples built from the same tokens and components that the documentation describes.
This skill is self-contained. Never assume access to the skill author's repositories, localhost routes, prior conversations, preferred framework, or private design files. Treat the current request, the supplied URLs or files, the inspected source, and the active workspace rules as the complete source of truth.
Establish the target
- Read references/cold-start.md when the request provides only a URL, the destination is unclear, or the skill is being evaluated in a new environment.
- Separate the source website to analyze from any reference documentation website whose presentation the user likes. A reference supplies documentation depth and interaction patterns; its brand, dimensions, and colors do not become the source's design language.
- With one source URL, inspect that page from top to bottom and the distinct same-origin page families reachable through its navigation. Start with one representative of each family; expand when another page exposes new components, variants, or layout rules. Record unvisited URLs and inaccessible states. Do not call a sampled crawl “every element on the entire site.”
- If the only URL is explicitly a documentation reference and no source is supplied, ask for the source before claiming to extract its system.
- Default to the user's language for documentation and the source's language for faithful specimens. Keep observed source copy separate from labeled fictional demo content.
- Use an existing project's framework only when the user names that project or route as the destination, or the source URL is that project's local preview. Mere presence in an application repository is not permission to modify it. Otherwise create an isolated output directory and runnable local documentation site; plain HTML/CSS/JS is sufficient when no app stack is established. Follow any required site-building workflow in the active environment. Do not introduce a backend for extraction unless requested.
- State the crawl boundary, evidence method, output location, and acceptance criteria briefly, then work. Ask only for information that changes the work and cannot be inferred. URL input in conversation is enough; a hosted crawler, URL-entry product, deployment, or Figma write is additional scope.
1. Observe before designing
Read references/inspection.md. Inspect the rendered site with available, documented browser tools, then inspect local source/CSS when available and authorized. Screenshots establish composition; computed styles and source declarations establish values. Neither alone proves a complete system.
Create a structured evidence ledger and coverage matrix before implementation. Each finding links to a URL, element or component, viewport, state, method, and capture time. Record source revision when local code is available. A screenshot estimate must never be labeled a measured CSS value.
Use these distinct evidence labels throughout the site and exports:
| Label | Meaning |
|---|---|
| Observed / 实测 | Directly inspected in source or rendered behavior, with method and location recorded |
| Inferred / 推断 | Generalized from repeated evidence; state the reasoning and uncertainty |
| Proposed / 补全提案 | New rule, state, correction, or component added for usability/completeness |
| Unknown / 未知 | Not inspectable or not verified; no fabricated value |
Evidence status is separate from owner approval. Observed does not mean approved, accessible, reusable, or correct. Mark blocked routes, unobserved modes, and coverage gaps explicitly. Continue supported work when some routes fail.
2. Reconstruct the system
Read references/system-model.md. Inventory all unique visual families within the inspected scope, including distinctive source-specific elements. Use the coverage matrix to account for foundations, components, composition, behavior, and governance; mark missing categories as absent, blocked, or proposed rather than silently skipping them.
For each candidate value:
- Retain raw observations, including exceptions and breakpoint differences.
- Merge only values with the same meaning and compatible evidence. Equal hex values do not imply equal semantic roles.
- Promote repeated values into primitives, roles into semantic aliases, and demonstrated component-specific needs into component aliases. Record naming as inferred when the original token names are unavailable.
- Keep one-off hero treatments, shaders, illustration styles, or choreography local unless repeated evidence supports reuse.
- Fill gaps needed for a coherent usable system with visibly Proposed additions. Do not invent a full 50–950 palette, dark mode, icon library identity, exact breakpoint, or timing curve from one screenshot.
- Keep observed defects visible in the source comparison; use a separately labeled correction in functional examples when necessary for accessibility. A repair must not silently rewrite the extraction.
3. Build the reference website
Read references/site-contract.md. Build foundations → components → compositions → handoff from one structured registry. Values shown in tables, CSS consumed by specimens, and exported tokens must agree.
Produce a site with section navigation, live specimens, usage and avoidance guidance, anatomy and state documentation, real composition examples, motion replay, responsive/stress controls, evidence details, and downloadable implementation data. Match the source's visual character while keeping documentation legible. Do not impose a universal SaaS dashboard or copy the reference site's brand.
Use reusable components in both the component gallery and composed examples. Forced state samples are labeled as samples and supplement actual keyboard/pointer behavior. Document which parts are observed and which are proposed at the item level, not only in one footer disclaimer.
Keep output styles scoped. In an existing application, add an isolated route or output directory; do not replace production pages or global tokens. The generated system remains a proposal until adopted. For later comment-driven edits, freeze unmentioned elements and change only the requested targets.
4. Verify and hand off
Use the checks in the site contract. Run supported project checks after reading their scripts; check the running website at desktop, narrow mobile, and source breakpoints, plus keyboard, focus, reduced motion, long content, missing media, and export behavior. Compare representative specimens to source evidence at matching viewports. Report skipped or blocked checks without claiming conformance.
The optional scripts/export_tokens.py validates the local registry contract in system-model.md and generates scoped CSS plus a resolved JSON export. Run it when using that contract. It validates alias/data consistency, not CSS semantics, accessibility, or third-party importer compatibility. Other typed registries are acceptable if they enforce equivalent invariants.
Finish with the verified running preview URL, output location, inspected coverage, material gaps, and verification result. Preserve any existing development service; use an isolated route or another available port. If the environment cannot leave a service running, verify the URL during the run, state that it stopped, and provide the exact restart command. Download links must return the generated files. Never describe a local custom JSON manifest as a universal Figma/Tokens Studio import, or claim design-tool synchronization without testing that destination.
