File Location: All Python files are in the tools/ folder of this skill:.agents/skills/design-system-extractor/tools/ ├── design_system_extractor.py ├── extract_tokens.py └── requirements.txt
Required Flow:
# Navigate to the tools folder
cd .agents/skills/design-system-extractor/tools/
# Install dependencies (first time only)
pip install -r requirements.txt
# Run the Python pre-processor
python design_system_extractor.py <URL>What the Python script does: Step A: HTML Sanitization
- Removes ALL
<svg>,<path>,<script>,<noscript>,<iframe>,<style>tags - Removes base64 data (
src="data:image...") - Keeps only structure:
<header>,<main>,<section>,<h1>-<h6>,<p>,<a>,<button>, and CSS classes
Step B: External CSS Extraction
- Identifies
<link rel="stylesheet">tags in<head> - Fetches
.cssfiles - Uses regex to extract ONLY:
- :root {...} block (90% of Design Tokens) - @font-face rules - Important global classes (.btn, .card, .container, h1, h2, h3)
Step C: Utility Framework Detection
- Detects Tailwind patterns:
text-[16px],bg-[#RRGGBB],leading-tight - Spacing patterns:
m-4,p-8,gap-16,w-full - Typography:
font-bold,text-xl,tracking-wide
</data_collection_and_sanitization>
<data_analysis> Using the JSON returned by Python, analyze:
Colors:
- Prioritize colors from CSS variables (:root)
- If no:root exists, use colors detected in HTML/Tailwind
- Classify into: Brand, Black, White, Gray (light/medium/dark/text/muted/social)
- Detect gradients and opacities
- Document usage of each color (CTAs, text, background, borders)
Typography:
- Font-family from CSS variables or @font-face
- If Google Fonts are used, extract from the tag in HTML
- Font-size: mega (130px), hero (86px), display (66px), h1-h6, body, small
- Font-weight: 400, 500, 600, 700
- Line-height: tight (0.94), snug (1.03), normal (1.2), relaxed (1.25), loose (1.65)
- Letter-spacing: tighter (-0.05em), tight (-0.035em), normal (-0.03em), wide (0.175em)
Spacing:
- Based on a 4px unit
- Space system: 1(4px), 2(8px), 4(12px), 6(16px), 8(20px), 10(24px), 16(40px), 24(60px), 40(90px), 75(150px), 100(200px), 125(250px)
- Container widths: max (1920px), content (1400px), narrow (1360px), small (1200px), text (800px), tight (780px)
</data_analysis>
<component_catalog> Use the components detected by Python and expand:
Buttons (Minimum 4 types):
- Primary: brand background, pill radius (100px), height 40px
- Chip: gray background, pill radius, hover/active states
- Link: text only, with animated arrow suffix
- FAB: fixed position, backdrop-filter, pulse animation
- Padding, border-radius, font-size, font-weight, transitions
Cards (Minimum 3 types):
- Project Card: media with image, content, title, subtitle
- Partner Card: image left, content right, max-width 310px
- Pane Card: index number, title, subtitle with divider line
- Borders (15-20px radius), shadows, hover effects, image aspect ratios
Forms:
- Textfield: animated underline, large label, height 56px
- Selectbox: underline + chevron suffix
- Filebox: dashed border, drag & drop style
- Checkbox: custom control with checkmark
- Input styles, labels, validation states, focus states
Navigation:
- Sticky header with transition
- Logo + horizontal menu + CTA button
- Dropdown with arrow animation
- Scroll-based color change
</component_catalog>
<assets_and_media> CRITICAL FOR VISUAL IMMERSION:
- Capture and USE the real image URLs from the site (original logo, banners, profile photos, card images).
- The generated HTML MUST incorporate these "real pieces" of the site in tags and component backgrounds. Do not use only solid colors if the original site uses rich imagery.
- This ensures the generated documentation has the look and feel of the original site.
Images:
- Extract URLs from src (always use the originals from the site)
- Identify format (WebP, JPG, PNG, SVG)
- Document aspect ratios (e.g. 55% padding-top for cards)
- Note border-radius and effects (hover scale, etc.)
Icons and Logos:
- Insert the exact URL of the original site's logo in the sidebar and headers.
- Library (FontAwesome, Material, Phosphor, custom SVG)
- Style (filled, outline, duotone)
- Extract inline SVGs when possible, or use the original URLs
</assets_and_media>
<animations_and_interactions>
- Transition durations: fast (0.15s), normal (0.25s), slow (0.5s)
- Timing functions: ease-smooth cubic-bezier(0.65, 0.05, 0.36, 1)
- Keyframe animations: heartbeat, fade, slide, scale, pulse, ticker
- Scroll-based animations (GSAP, ScrollMagic, AOS)
- Hover effects: transform, opacity, background-color </animations_and_interactions>
<grid_and_layout>
- Container max-widths
- Grid system (CSS grid, flexbox)
- Breakpoints (1024px, 768px)
- Gaps and gutters
- Z-index scale: base (1), dropdown (2), header (3), sticky (10), fixed (55), overlay (100) </grid_and_layout>
<anti_hallucination_guidelines> CRITICAL: To avoid fabricating data:
Base tokens STRICTLY on the data from the JSON returned by Python.
If the site uses heavy minification (classes.a,.b,.c) and no CSS is mapped:
- Infer the Design System by analyzing numeric patterns
- Use industry defaults (4px grid, 1.25 type scale)
NEVER invent colors or fonts that are not present in the analyzed data.
If information is missing, use default values documented as "Default".
NO EMPTY PLACEHOLDERS: Instead of leaving [URL] or generic gray images, ALWAYS inject the REAL image, photo, and logo URLs extracted from the site into the HTML. The documentation should look like a piece of the real site. </anti_hallucination_guidelines>
<output_format> HTML file (design_pattern.html) Generate ONLY the final HTML code. Do not add explanations before or after the code. Use the template below and REPLACE the [Site Name], #HEX, and value placeholders with the actual extracted properties. IMPORTANT: Replace ALL placeholders such as,, or text reading "LOGO" with the REAL image URLs captured from the site. Keep all CSS boilerplate exactly as provided, only modifying the:root block. <html_template>
</html_template> </output_format>
<validation_checklist> Before delivering, verify: Design Tokens:
All primary colors extracted (brand, black, white, 6+ gray shades)
Font-family identified and imported from Google Fonts
Complete type scale (minimum 10 levels: mega, hero, display, h1-h6, body)
Line-heights documented (tight, snug, normal, relaxed, loose)
Letter-spacing documented (tighter, tight, normal, wide)
Complete spacing system (minimum 10 values)
Container widths defined
Border radius system (sm, md, lg, full, pill)
Shadows documented
Transitions (fast, normal, slow) + easing
Z-index scale
Components and Visuals:
Real logos and images from the site have been injected into the final HTML (no empty placeholders)
Minimum 4 button types (primary, chip, link, fab)
Minimum 3 card types populated with REAL EXTRACTED IMAGES (project, partner, pane)
Form elements (textfield, selectbox, filebox, checkbox)
Navigation example (sticky nav with real logo + menu + CTA)
Badges & Chips with states
Icons documented (inline SVG)
Numbers & Stats with mega typography
Awards list with animation
Footer example (4 columns)
Animations demonstrated (fade, slide, scale, pulse)
Structure:
CSS variables in:root (all categories)
Functional sidebar navigation
Scroll progress indicator
Smooth scroll navigation
Active navigation on scroll
Responsive (media queries: 1024px, 768px)
Code examples in each section
Utility classes (margin, color, text-align) </validation_checklist>
<required_tools>
Python 3.x — For pre-processing
requests — Python library for HTTP requests
beautifulsoup4 — Python library for HTML parsing
write — To create the HTML file
Location: All files are in tools/ inside this skill. </required_tools>
<usage_example> User Input: "Extract the design system from this site: https://example.com"
Execution Flow:
Navigate to the tools folder and install dependencies: cd.agents/skills/design-system-extractor/tools/ pip install -r requirements.txt
Run the Python pre-processor: python design_system_extractor.py https://example.com
Analyze the returned JSON: {"url": "https://example.com", "fonts": ["Inter", "Roboto"], "css_variables": {"color-brand": "#0070F3", "color-black": "#000000"}, "colors": ["#0070F3", "#000000", "#FFFFFF"], "components": [{"type": "button", "count": 5}, {"type": "card", "count": 12}], "images": "[https://example.com/logo.png", "https://example.com/banner.jpg"]}
Generate HTML with extracted data, replacing tags with real image URLs from the JSON.
Save file as design_pattern.html
Deliver with a summary of the main elements (Colors, Fonts, Components, and the generated file). </usage_example>
<section_templates>
Color Card Template
Type Item Template
Spacing Item Template
Icon Card Template
Button Card Template
Project Card Template
Partner Card Template
Pane Card Template
Form Elements Template
Number Stats Template
Award Item Template
Animation Card Template
Code Block Template
Utility Classes.ds-mb-0 {margin-bottom: 0;}.ds-mb-8 {margin-bottom: var(--space-8);}.ds-mb-16 {margin-bottom: var(--space-16);}.ds-mb-24 {margin-bottom: var(--space-24);}.ds-mb-40 {margin-bottom: var(--space-40);}
.ds-text-brand {color: var(--color-brand);}.ds-text-gray {color: var(--color-gray-text);}.ds-text-center {text-align: center;}
.ds-bg-black {background-color: var(--color-black);}.ds-bg-white {background-color: var(--color-white);}.ds-bg-gray {background-color: var(--color-gray-light);} </section_templates>
<best_practices> Always use CSS variables for consistency Always inject REAL images from the site (logos, banners, card photos) into the generated HTML to create a visual catalog identical to the original, functioning as literal pieces of the site Always document states (hover, active, focus, disabled) Always include code examples in each section Maintain fidelity to the original design Use descriptive token names (brand, gray-light, etc.) Document responsive breakpoints (1024px, 768px) Include animations and transitions with timing functions Follow the layout structure: sidebar + main content Implement scroll progress indicator Add smooth scroll and active navigation Use utility classes for margins and colors Include at least 10 spacing levels Document line-heights and letter-spacing for typography Create at least 4 button types and 3 card types populated with real media </best_practices>
<required_css_structure> Base Layout.ds-layout {display: grid; grid-template-columns: 280px 1fr; min-height: 100vh;}
.ds-sidebar {position: sticky; top: 0; height: 100vh; background-color: var(--color-black); color: var(--color-white); padding: var(--space-40) var(--space-24); overflow-y: auto;}
.ds-main {padding: var(--space-50) var(--space-75); max-width: var(--container-max);}
Header.ds-header {margin-bottom: var(--space-100); padding-bottom: var(--space-50); border-bottom: 1px solid var(--color-gray-light);}
.ds-title {font-size: var(--text-mega); font-weight: var(--font-weight-bold); line-height: var(--leading-tight); letter-spacing: var(--tracking-tighter);}
.ds-subtitle {font-size: var(--text-5xl); font-weight: var(--font-weight-medium); color: var(--color-gray-text);}
Sections.ds-section {margin-bottom: var(--space-100);}
.ds-section-title {font-size: var(--text-5xl); font-weight: var(--font-weight-bold); margin-bottom: var(--space-40); padding-bottom: var(--space-16); border-bottom: 3px solid var(--color-brand); display: inline-block;}
.ds-section-description {font-size: var(--text-lg); color: var(--color-gray-text); margin-bottom: var(--space-40); max-width: var(--container-text);}
Scroll Indicator.ds-scroll-indicator {position: fixed; top: 0; left: 0; height: 3px; background-color: var(--color-brand); z-index: var(--z-fixed); width: 0%; transition: width 0.1s;} </required_css_structure>
<setup_and_metadata> Python Dependencies: Install before using:
# Navigate to the tools folder
cd .agents/skills/design-system-extractor/tools/
# Install dependencies
pip install -r requirements.txtOr directly:
pip install requests beautifulsoup4requirements.txt:
requests>=2.31.0
beautifulsoup4>=4.12.0Location: tools/requirements.txt inside this skill.
Versioning: Version: 2.0.0 (Optimized with Python) Last updated: 2026-03-19
v2.0 Improvements:
- Python pre-processing — Prevents context window overflow
- HTML sanitization — Removes SVGs, scripts, base64
- Selective CSS extraction — Focuses on:root, ignores the rest
- Tailwind detection — Token inference from utility classes
- Anti-hallucination — Strict guidelines to prevent fabricated data
- Optimized output — Generates only HTML with real image injection
File Structure:
.agents/skills/design-system-extractor/
├── SKILL.md # This skill (you are here)
└── tools/
├── design_system_extractor.py # Main Python script
├── extract_tokens.py # Standalone CSS token extractor
├── requirements.txt # Python dependencies
└── README.md # Tools documentationImportant: Always run Python scripts from the tools/ folder:
cd .agents/skills/design-system-extractor/tools/
python design_system_extractor.py <URL></setup_and_metadata>