style-extractor
从 URL、截图或前端项目源码中逆向提取 UI 视觉风格,产出三层 Design Token 系统(Primitive → Semantic → Component),封装为可复用的 WorkBuddy 通用风格技能。
Style Extractor
Extract a complete design system from any web page, image, or codebase and package it as a reusable WorkBuddy style skill.
Overview
This skill provides a multi-phase pipeline with optional mode splitting:
| Phase | Mode | Output |
|---|---|---|
| Phase 1 — Audit | Audit-only mode | Evidence inventory, raw values, duplicates, drift, exceptions |
| Phase 2 — Design | Design mode | Three-layer tokens (Primitive → Semantic → Component), naming, theme mappings |
| Phase 3 — Package | Generate mode | Complete WorkBuddy style skill with all references |
| Phase 4 — Verify | Verify mode | Format, reference, theme, and state validation + optional demo page |
By default, run all phases. The user can request audit-only, design-only, or verify-only mode.
Core Principles
Evidence Grading
Every extracted value MUST be tagged with one of four evidence levels:
| Grade | Label | Meaning |
|---|---|---|
| D | 已定义 (Defined) | Found in existing CSS variables, theme config, or design token files |
| M | 已测量 (Measured) | Confirmed from source code references, browser computed styles, or rendered output |
| I | 有依据的归纳 (Inferred) | Reasonably deduced from repeated patterns across multiple pages/components |
| A | 暂时假设 (Assumed) | Best guess based on limited data; MUST be explicitly flagged for user review |
Never present an assumed value as a confirmed fact. The evidence grade determines how aggressively the token can be used in migration.
Three-Layer Token Architecture
Tokens are organized into three layers, NOT a flat list:
Primitive (原材料) → color.blue.600, space.4, radius.md, font.size.lg
↑ reference only — do not use in components directly
Semantic (设计角色) → color.action.primary, color.bg.surface, space.container.padding
↑ components use these
Component (组件特化) → button.primary.bg.default, input.border.focus, dialog.shadow
↑ only when semantic tokens are insufficient
Why three layers matters:
#FFFFFFin light theme = page background; in dark theme = inverse text. Same primitive value, DIFFERENT semantic roles. If merged into one flat--white, theme switching breaks.color.blue.600could be used for buttons, links, and focus rings. If a component references the primitive directly, changing the brand color requires hunting down every usage. If it referencescolor.action.primary(which maps tocolor.blue.600), it changes everywhere at once.
Layer decision rules:
- Primitive: Raw materials (color scales, spacing steps, font sizes, radius steps, duration values). Named by what they ARE, not where they're used.
- Semantic: Design roles (backgrounds, text levels, borders, actions, statuses). Named by what they DO. Must reference primitives, never copy values.
- Component: Per-component overrides that can't be expressed by semantic tokens alone. Only create when a component has a genuinely independent design decision.
Do NOT create a component token when:
- The component value equals a semantic token → just use the semantic token directly
- The component value could be expressed by combining existing semantic tokens
- You're creating an alias that adds no governance value (e.g.,
card.background.defaultwhen it's alwayscolor.bg.surface)
Quick Start
When the user provides an input, determine the type and follow the corresponding workflow:
| Input Type | Detection | Workflow Section |
|---|---|---|
| URL | starts with http:// or https:// | URL Extraction |
| Screenshot / Image | file path ending in .png, .jpg, .jpeg, .webp, .gif | Screenshot Extraction |
| Project Directory | local folder path | Project Source Extraction |
If input type is ambiguous, ask the user to clarify.
Phase 0 — Determine Output Name and Mode
Before extraction:
- Ask the user: "What should I name this style? (e.g.,
notion,stripe,my-brand)" - The output skill directory will be named
brand-style-{name} - If only one style is being extracted and the user doesn't specify, infer from the source
- If the user wants audit-only, stop after Phase 2. If verify-only, start from Phase 4.
Phase 1 — Audit: Ingest and Inventory
URL Extraction
When input is a URL:
- Fetch the page: Use WebFetch to retrieve the HTML content of the target URL
- Fetch CSS: Use WebFetch on any linked CSS file URLs found in the HTML
- Catalog raw values with evidence grades:
- Colors: All hex/rgb/hsl values, noting which come from
--*variables (grade D), which are inline (grade M), and which are computed (grade M) - Typography: Font families, sizes, weights, line-heights, letter-spacing — note
@font-facevs system stack vs Google Fonts - Spacing: Padding/margin patterns, gap values, typical container widths
- Shadows: box-shadow values with color, offset, blur, spread
- Border Radius: All border-radius values, noting which elements use them
- Layout: Flex/grid patterns, column counts, responsive breakpoints
- Components: Recurring patterns with their CSS properties
- Colors: All hex/rgb/hsl values, noting which come from
Tailwind Detection: If the page uses Tailwind CSS, map utility classes to computed values and document both the class name and the equivalent CSS. Grade these as D (defined in config) or M (observed in DOM).
CSS Variable Detection: If the page uses CSS custom properties, extract the full variable hierarchy. These are grade D. Note any variables that reference other variables (e.g., --color-text-primary: var(--gray-900)).
Screenshot Extraction
When input is a screenshot/image:
- Read the image: Use the Read tool to analyze the screenshot visually
- Extract visual properties (all grade I or A — inferred from visual, not exact):
- Color palette: Dominant colors, accent colors, background/surface colors, text colors
- Typography: Font styles observed, size hierarchy, weight usage
- Spacing: Visual spacing patterns, content density
- Shape language: Rounded vs sharp corners, shadow usage, border treatment
- Component patterns: Cards, buttons, navigation, forms
- Explicitly flag that screenshot extraction yields inferred values (grade I/A). Invite the user to refine exact hex codes and font names.
Project Source Extraction
When input is a local project directory:
- Discover style files: Use Glob to find:
**/*.css,**/*.scss,**/*.less→ grade D/Mtailwind.config.{js,ts,mjs,cjs}→ grade D**/theme.{js,ts,tsx},**/tokens.{js,ts,json}→ grade D**/GlobalStyles.{js,ts,tsx},**/styled.{js,ts,tsx}→ grade M
- Read key files: Prioritize theme/config files (grade D), then component styles (grade M)
- Parse and catalog:
- Tailwind config:
theme.extend.colors,theme.extend.fontFamily, etc. → grade D - CSS variables: All
:root { }blocks → grade D, but note if variables reference other variables - Theme objects: JS/TS theme definitions → grade D
- Global styles: body defaults, heading resets → grade M
- Tailwind config:
- If the project can run, open key pages and record computed styles (upgrade M → D where confirmed)
- If the project cannot run, explicitly state this and keep browser-dependent values at grade I
Phase 2 — Design: Identify Patterns, Drift, and Exceptions
After cataloging raw values, analyze them. See references/common-pitfalls.md for what to avoid.
Step 1: Find Duplicates and Conflicts
Output a structured issues list:
- 同值异名 (Same value, different names): Multiple variable names resolving to the same value and same semantic role — candidates for merging
- 同名异值 (Same name, different values): Same variable name expressing different meanings across themes, scopes, or files — these MUST stay separate
- 近似重复 (Near duplicates): Values like 15px/16px/17px or similar grays — investigate whether the difference is intentional (font metrics, component sizing, responsive) or drift
- 语义误绑 (Semantic misbinding): Same current value but different semantic roles (e.g.,
#FFFFFFas both page background and inverse text) — these MUST become separate semantic tokens - 硬编码逃逸 (Hardcoded escapes): Raw values used in components even though variables exist — flag for migration
- 组件漂移 (Component drift): Same component type with different sizing/colors/spacing across pages — identify the canonical version
Step 2: Build Three-Layer Tokens
Primitive tokens — raw materials only:
color.blue.50 → #E8F3FF color.blue.500 → #165DFF color.blue.900 → #001B4D
color.gray.50 → #F7F8FA color.gray.500 → #86909C color.gray.900 → #1D2129
space.1 → 4px space.2 → 8px space.4 → 16px space.6 → 24px
radius.sm → 2px radius.md → 4px radius.lg → 8px
font.size.sm → 12px font.size.base → 14px font.size.lg → 16px
Semantic tokens — design roles referencing primitives:
color.action.primary → color.blue.500
color.action.primary.hover → color.blue.400
color.bg.page → color.gray.50 (light) / color.gray.900 (dark)
color.bg.surface → white (light) / color.gray.800 (dark)
color.text.primary → color.gray.900 (light) / white (dark)
color.text.secondary → color.gray.500
color.border.default → color.gray.200
space.container.padding → space.6
shadow.overlay → {specific shadow}
Show theme mappings for light/dark if applicable. When the same primitive maps to different semantics in different themes, this is exactly why the three-layer system exists — document it explicitly.
Component tokens — only where necessary:
button.primary.bg.default → color.action.primary
button.primary.bg.hover → color.action.primary.hover
input.border.focus → color.action.primary (with alpha)
dialog.shadow → shadow.overlay
table.row.height.compact → 36px
If a component token simply equals a semantic token (e.g., card.bg → color.bg.surface), do NOT create it — just document that cards use color.bg.surface.
Step 3: Handle Exceptions
Some values are genuinely local and should NOT become tokens:
- One-off decorative gradients
- Chart/dataviz algorithm-generated colors
- Third-party component internal styles
- Experimental/A-B test variants
Document these in the output's Known Gaps / Exceptions section with justification.
Phase 3 — Package: Generate the Output Style Skill
Generate the output style skill using the templates in assets/style-skill-template/.
Output Skill Structure
brand-style-{name}/
├── SKILL.md # YAML frontmatter + three-layer overview + quick reference
├── references/
│ ├── colors.md # Primitive color scales + Semantic color roles + theme mappings
│ ├── typography.md # Primitive font scale + Semantic text roles
│ ├── spacing.md # Primitive spacing/radius/shadow scales + Semantic layout tokens
│ ├── components.md # Component tokens and patterns
│ └── known-gaps.md # Unresolved discrepancies, exceptions, assumptions
Output Format
See references/output-format.md for the detailed specification. Key requirements:
SKILL.md: Must include YAML frontmatter with structured token data. See the template.
All reference files: Every token table must include an Evidence column (D/M/I/A).
known-gaps.md: Required. Documents:
- Conflicts between documentation and source code (and which was chosen)
- Values that couldn't be confirmed
- Assumptions that need user review
- Genuine exceptions with justification
Post-Generation Validation
After generating all files, run the validations in references/validation-checklist.md:
- Format: YAML parses cleanly; all required frontmatter fields present
- References: Every
{colors.xxx}style reference resolves to a defined token - Color validity: All hex values are legitimate 3/6/8-digit hex
- Layer consistency: Semantic tokens reference primitives (not copy values); component tokens reference semantics (not primitives directly)
- No cross-contamination: No tokens, brand names, or rules from other design systems
- Section completeness: All required sections present and in order
Report: file path, total lines, token counts per layer, grades distribution, validation results, and remaining Known Gaps.
Phase 4 — Verify: Demo and Refine
After generating the skill, optionally validate it's actually usable:
- Generate a demo page that exercises the tokens: background layers, text hierarchy, buttons (all variants), form elements, cards, navigation, and data display
- Check: Does the demo look like the source? Are any values clearly wrong?
- Offer to refine: "Would you like me to adjust any colors, fonts, or values?"
Common Pitfalls to Avoid
These are the five most common extraction mistakes. See references/common-pitfalls.md for full details.
- Treating frequency as correctness. A value appearing 50 times may just be copy-paste legacy. A value appearing once (e.g., brand title font) may be critical.
- Force-merging near-duplicates. 15px/16px/17px differences may come from font metrics, component sizing, or responsive breakpoints. Investigate before averaging.
- Skipping browser rendering. Source code values can be overridden by specificity, theme scopes, or runtime injection. Static analysis alone is incomplete.
- Renaming without aliasing. Changing
#165DFFtocolor-blue-500is just a rename. The real value is mapping it to semantic roles that survive theme changes. - Mass-replacing the entire codebase. Start with one representative page. Verify it handles all states and themes. Then expand.
References
references/extraction-checklist.md— Comprehensive token extraction checklist with evidence gradingreferences/output-format.md— Detailed specification for output file format and three-layer structurereferences/validation-checklist.md— Post-generation validation steps and criteriareferences/common-pitfalls.md— The five most common extraction mistakes and how to avoid themassets/style-skill-template/— Template directory for generated style skills
Related skills
- Downloads
- 1.3kAll time
- Security audit
- Review
- Last updated
- 3mo ago
- Current version
- v0.1.0
- License
- MIT-0
