OpenStyle
Overview
OpenStyle is a Python CLI tool that parses CSS stylesheets and DOM structures from HTML website templates, automatically identifies design tokens (colors, typography, spacing, border-radius, shadows), and outputs:
| Output File | Description |
|---|
DESIGN.md | Nine-section design specification (visual theme, color palette, typography, components, layout, elevation, best practices, responsive behavior, AI prompt guide) |
preview.html | Light-mode interactive design token catalog (colors, typography, buttons, cards, forms, spacing, radius, elevation) |
preview-dark.html | Dark-mode interactive design token catalog (auto-mapped dark tokens) |
README.md | English documentation (auto-generated in batch mode) |
Key Features
- Semantic Color Naming — HSL-based analysis generates semantic names (Deep Navy, Vivid Amber, Soft Green)
- Intelligent Dark Mode — Auto-maps light tokens to dark scheme (bg/fg inversion, shadow/border adaptation)
- Typography Hierarchy — Extracts font families, sizes, weights, line-heights, letter-spacing; classifies as Display → Body → Caption
- Component Detection — HTML DOM analysis identifies navigation, buttons, cards, forms, hero sections
- Interactive Previews — Generated HTML includes Google Fonts, responsive layout, anchor navigation
- Multilingual Translation — Auto-translates Chinese directory names to English slugs (MyMemory / Google API, pinyin fallback)
- Batch Categorized Processing — 52 industry/type categories with automatic classification
Installation
cd openstyle
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
pip install -r requirements.txt
Dependencies
| Package | Purpose |
|---|
beautifulsoup4 | HTML DOM parsing & component detection |
cssutils | CSS stylesheet parsing |
jinja2 | Template rendering (DESIGN.md / preview.html) |
colormath | Color space conversion (HSL analysis, luminance calculation) |
click | CLI command framework |
deep-translator | Chinese → English translation (MyMemory / Google) |
pypinyin | Pinyin fallback (when translation fails) |
pytest | Unit testing |
Quick Start
Single Template Analysis
python -m openstyle analyze "E:\OpenStyle\3C数码电子产品网站模板_www.mobancss.com\moban2603"
Specify Output Directory
python -m openstyle analyze "E:\OpenStyle\...\moban2603" -o "E:\OpenStyle\UI"
Batch Processing
# Scan all templates under root directory
python -m openstyle batch "E:\OpenStyle" -o "E:\OpenStyle\UI"
# Batch export with English directory names + README
python -m openstyle batch-openstyle "E:\OpenStyle" -o "E:\OpenStyle\UI" --skip-existing
# Offline mode (no translation API, pinyin-based naming)
python -m openstyle batch-openstyle "E:\OpenStyle" -o "E:\OpenStyle\UI" --no-translate
Preview Only
python -m openstyle preview "E:\OpenStyle\UI\sample\DESIGN.md" -o "E:\OpenStyle\UI\sample"
Project Structure
openstyle/
├── src/openstyle/
│ ├── __init__.py # Package entry, exports OpenStylePipeline
│ ├── __main__.py # python -m openstyle entry point
│ ├── cli.py # Click CLI commands (analyze / batch / batch-openstyle / preview)
│ ├── pipeline.py # Core pipeline: analyze → generate DESIGN.md → generate preview
│ ├── models.py # Data models (ColorToken / TypographyToken / DesignTokens / ComponentSpec)
│ ├── naming.py # Directory name cleaning, translation cache, pinyin conversion, slug dedup
│ ├── readme_en.py # English README generator
│ ├── analyzer/
│ │ ├── css_parser.py # CSS parser: colors, fonts, spacing, radius, shadows, media queries
│ │ ├── html_parser.py # HTML parser: component detection, layout inference
│ │ └── color_extractor.py # Color classifier: HSL-based primary/accent/neutral/semantic grouping
│ ├── generators/
│ │ ├── design_md.py # DESIGN.md generator (Jinja2 rendering + semantic color naming)
│ │ ├── preview_html.py # preview.html generator
│ │ └── token_mapper.py # Token mapping: HSL semantic naming, dark mode conversion, role descriptions
│ └── templates/
│ ├── design_template.md # DESIGN.md Jinja2 template
│ └── preview_template.html # preview.html Jinja2 template
├── tests/
│ ├── conftest.py
│ ├── test_pipeline.py
│ └── fixtures/
├── batch_run.py # Batch processing script (root-level)
├── batch_category.py # Categorized batch processing script
├── requirements.txt
├── README.md # Chinese documentation
└── README_EN.md # English documentation (this file)
Processing Pipeline
HTML Template Directory
│
▼
┌─────────────────────────────┐
│ 1. CSS Parsing (CSSParser) │ ← Extract colors, fonts, spacing, radius, shadows, breakpoints
│ 2. HTML Parsing (HTMLParser)│ ← Detect components (nav/buttons/cards/forms/hero), layout patterns
│ 3. Color Classification │ ← HSL analysis → primary / accent / neutral / semantic
│ (ColorExtractor) │
└──────────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ 4. Token Building (Pipeline)│ ← DesignTokens data model
│ - Semantic color naming │ ← "Vivid Amber", "Deep Navy", "Mid Gray"
│ - Typography hierarchy │ ← Display → Heading → Body → Caption
│ - Spacing/Radius/Shadow │
└──────────┬──────────────────┘
│
▼
┌─────────────────────────────┐
│ 5. Output Generation │
│ - DESIGN.md (Jinja2) │ ← Nine-section design specification
│ - preview.html │ ← Light-mode interactive preview
│ - preview-dark.html │ ← Dark-mode interactive preview (auto-mapped)
│ - README.md │ ← English documentation
└─────────────────────────────┘
Category Reference
OpenStyle supports categorized template processing across 52 categories, covering 270+ template design systems.
Full Category List
| Category | Directory Name | Description | Example Output |
|---|
| Advertising | Advertising | Ad agencies, marketing promotions | marketing_agency_digital-promotion |
| Agriculture | Agriculture | Farming, agricultural products | — |
| Animals & Pets | Animal | Pet shops, animal welfare | pet_shop_animal |
| App Landing | App | Mobile app landing pages | app_landing_mobile |
| Automobile | Automobile | Car sales, auto repair | automotive_website_car-sales |
| Backend / Admin | Backend | Admin panels, dashboards | backend_admin_dashboard |
| Beauty & Salon | Beauty | Beauty salons, hair studios | beauty_website_salon |
| Blog | Blog | Personal blogs, content sites | blog_website_personal |
| Brand Showcase | Brand | Brand websites, VI displays | brand_website_showcase |
| Business Consulting | Business | Business services, consulting firms | business_website_consulting |
| Cartoon Style | Cartoon | Cartoon illustrations, fun design | cartoon_website_illustration |
| Charity | Charity | Non-profits, foundations | charity_foundation_donation |
| Corporate | Company | Company websites, corporate profiles | company_website_enterprise |
| Construction | Construction | Building companies, engineering | construction_company_building |
| E-Commerce | |