Content
<p align="right">English</p>
# Tool List
**Enter a website URL to effortlessly generate its web style.**
Just provide a website URL, and HTML2Style will automatically analyze its colors, fonts, spacing, layout, images, icons, and responsive rules. It generates a style package that you can directly view, hand over to an Agent, or apply to a new webpage.
```text
Website URL → HTML2Style → Web Style Package
├─ STYLE.md: Style Rules
├─ style-board.html: Visual Style Board
└─ design-package/: Complete folder for direct reuse
```
## Understanding in 30 Seconds
HTML2Style primarily helps you accomplish three things:
1. **Extract Web Style:** Automatically organizes a website's colors, fonts, spacing, border radius, layout, images, and responsive features.
2. **Understand Web Style:** Generates an HTML style board that can be directly opened, eliminating the need to find patterns in extensive code.
3. **Reuse Web Style:** Hands over the generated folder to any Agent, allowing it to design new pages according to this style.
It doesn't just take a screenshot or generate a few color values. Instead, it extracts a more comprehensive set of style rules from a real webpage that can be reused.
## Simple Usage: Hand Over to Agent
### 1. Open the Project
```bash
git clone https://github.com/jackguihx-alt/html2style.git
cd html2style
npm install
```
### 2. Instruct Your Agent
```text
Please read this repository's SKILL.md, extract the web style of https://example.com,
generate a complete design-package/, use English, and do not start replicating the website.
```
When migrating styles, you can say:
```text
Please read SKILL.md, extract the web style of https://example.com,
and use this style to design a new page for my product. Do not copy the original site's brand, text, or images.
```
Codex, Claude Code, Cursor, Copilot, or other Agents with terminal capabilities can run this process using Playwright or a local Chrome / Chromium / Edge, independent of a specific Agent's proprietary browser.
## What You Get
The final result is a single folder that needs to be saved and moved:
```text
design-package/
├── START-HERE.html # Human Entry: Double-click to view
├── START-HERE.md # GitHub / Markdown Entry
├── AGENT-HANDOFF.md # New Agent Session Entry
├── manifest.json # Automation Entry
├── STYLE.md # Migratable Design Rules
├── style-profile.json # Deterministic Measurement Results
├── style-board.html # Visual Style Board
├── advanced/ # Optional: Complete Design System, Icon Library
└── evidence/ # Optional: Browser Evidence, Screenshots
```
Different roles can open the corresponding entry:
| Who Uses It | What to Open |
| --- | --- |
| Product, Design, Reviewers | `START-HERE.html` |
| New Agent Session | `AGENT-HANDOFF.md` |
| Developers | `STYLE.md` |
| Automation Programs | `manifest.json` |
Below is an example of the generated `style-board.html`. It showcases design rules and the sources supporting these rules, rather than just a reference screenshot.
<p align="center">
<img src="docs/assets/style-board.png" alt="HTML2Style Generated Visual Style Board" width="920">
</p>
Check out the [complete example package](examples/product-editorial/design-package/) in the repository. After cloning the repository, you can double-click `START-HERE.html` locally; the example uses fictional content and does not redistribute real website brands or materials.
## Three Typical Scenarios
### 1. Extract Website Style
Suitable for competitor research, design review, and design system organization. Outputs colors, fonts, hierarchy, density, shape, image strategy, animation, and responsive rules, along with evidence and confidence levels.
### 2. Migrate Style to New Product
Suitable for requests like "design an Apple-style page for my product." HTML2Style retains measured hierarchy, rhythm, and layout logic while requiring the replacement of the original site's brand, content, information architecture, and protected assets.
### 3. Verify Webpage Replication
Suitable for refactoring, migration, and visual regression with permissions. It checks if the page is complete, image sources and cropping are correct, icons are not missing, repeated component sizes are consistent, and desktop and mobile match.
## Running CLI Yourself
Environment Requirements: Node.js 20+, and Chrome, Chromium, Edge, or Playwright Chromium.
### 1. Check Browser
```bash
npm run doctor
```
### 2. Collect and Measure
```bash
node bin/html2style.mjs extract https://example.com evidence.json --profile full
node bin/html2style.mjs profile evidence.json style-profile.json \
--markdown STYLE-measurements.md
cp assets/STYLE.template.md STYLE.md
```
Let the Agent complete `STYLE.md` based on `STYLE-measurements.md` and `assets/STYLE.template.md`. Deterministic measurements and the Agent's design interpretation are saved separately.
### 3. Generate Style Board and Package
```bash
node bin/html2style.mjs preview STYLE.md style-board.html
node bin/html2style.mjs bundle design-package \
--style STYLE.md \
--profile style-profile.json \
--board style-board.html \
--measurements STYLE-measurements.md \
--evidence evidence.json \
--locale en
```
## Cross-Session Reuse
Move the entire `design-package/` to a new project and instruct the new Agent:
```text
Read design-package/AGENT-HANDOFF.md and apply this design language to my new task.
Unless the handoff package explicitly indicates missing evidence, do not re-collect the reference website.
```
This is why `AGENT-HANDOFF.md` exists: the new Agent doesn't need the original chat history or reopen the reference website.
## Why It's More Reliable Than Just Giving a Screenshot
- **Real Browser Evidence:** Collects DOM, computed styles, CSS variables, SVG, network resources, and actually selected responsive images.
- **Covers Different Viewports:** By default, checks desktop (high/short), tablet (high/short), and mobile, not just verifying one desktop screen.
- **Measurement and Interpretation Separation:** `style-profile.json` saves deterministic data, while `STYLE.md` saves readable design rules.
- **Explicit Migration Boundaries:** Design principles can be migrated, but the original site's logo, text, images, and brand identity cannot be automatically inherited.
- **Results Can Be Verified:** Resource checks, page audits, and screenshot comparisons can discover missing images, misplacements, and incomplete areas.
## Compatible with Different Agents
| Integration Method | Suitable For |
| --- | --- |
| CLI | Any user or Agent with terminal access |
| MCP stdio server | Any MCP-compatible client |
| `SKILL.md` | Agents supporting Skills |
| `AGENTS.md` | Codex and similar Agents reading repository instructions |
| `CLAUDE.md` | Claude Code |
| `.cursor/rules` | Cursor |
| Copilot instructions | GitHub Copilot |
| Portable prompt | Other Agents receiving project instructions |
### English and Chinese
- Chinese users generate `zh-CN` documentation by default.
- English users use `--locale en`.
- `START-HERE.md`, `START-HERE.html`, and `AGENT-HANDOFF.md` are generated according to the language.
- Commands, filenames, MCP tool names, and JSON fields remain in English to ensure automation and international collaboration stability.
- Original website content and measurement evidence remain in the original language unless explicitly requested to be translated.
<details>
<summary><strong>MCP Integration</strong></summary>
```bash
npm run mcp
```
```json
{
"mcpServers": {
"html2style": {
"command": "node",
"args": ["/absolute/path/to/html2style/mcp/server.mjs"]
}
}
}
```
See [`integrations/mcp.example.json`](integrations/mcp.example.json) for configuration examples.
</details>
<details>
<summary><strong>Login Page and Browser Installation</strong></summary>
If no browser is detected:
```bash
npx playwright install chromium
```
If a page requires login, open a temporarily visible browser and manually log in:
```bash
node bin/html2style.mjs extract https://example.com evidence.json \
--headed --login-wait 60
```
HTML2Style does not request or save account passwords.
</details>
<details>
<summary><strong>Replication Audit Command</strong></summary>
Use only if you have the authority to replicate the target website:
```bash
node bin/html2style.mjs assets replica.html --base-url https://example.com
node bin/html2style.mjs extract ./replica.html replica-evidence.json --profile full
node bin/html2style.mjs audit evidence.json replica-evidence.json --mode complete
node bin/html2style.mjs compare original.png replica.png comparison.html
```
</details>
## Project Boundaries
HTML2Style does not import webpages into Figma nor claims ownership of collected third-party content. The MIT License covers only the project code and templates, not the original website's images, fonts, logos, icons, text, or brand assets.
Complex Canvas / WebGL, closed shadow root, anti-scraping challenges, video timelines, and all interactive states currently cannot be guaranteed for complete collection. These cases are recorded as evidence gaps rather than guessed by the Agent.
## Related Projects
- [Website to Design](https://websitetodesign.com/): Import websites into editable Figma designs.
- [DesignDNA](https://www.designdna.site/): Export design system files via browser extensions.
- [Dembrandt](https://github.com/thevangelist/dembrandt): Extract design tokens and brand signals via CLI and MCP.
- [brandmd](https://github.com/yuvrajangadsingh/brandmd): Extract multi-page design systems into Agent-readable formats.
HTML2Style focuses more on responsive browser evidence, design migration boundaries, cross-session handoffs, and integrity verification.
## Development
```bash
npm test
npm run validate
```
Read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting changes, and report security issues according to [SECURITY.md](SECURITY.md).
## License
MIT. The content and assets of the collected website remain with the original rights holders.
