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 .css files
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.txt

Or directly:

pip install requests beautifulsoup4

requirements.txt:

requests>=2.31.0
beautifulsoup4>=4.12.0

Location: 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 documentation

Important: Always run Python scripts from the tools/ folder:

cd .agents/skills/design-system-extractor/tools/
python design_system_extractor.py <URL>

</setup_and_metadata>