# CSS Extractor Tool — Operational README

This tool is designed for **CSS and HTML extraction** when you need to analyze how a website’s styles and structure are built. It renders the page, collects all CSS sources, downloads font assets, and produces an organized report plus an HTML snapshot (body‑only) for agent‑friendly analysis.

Use it when you need:
- A complete, local CSS export for a live website
- A readable HTML snapshot to correlate structure with styles
- A compact summary of large CSS files

---

## Quick Start

```bash
python CSS-EXTRACTOR.py --url https://example.com
```

### First-Time Setup

**Always try running the tool first** — dependencies may already be installed. If you get import errors, install the missing packages:

```bash
# Install Python dependencies
pip install playwright httpx beautifulsoup4 cssutils rich

# Install browser for Playwright (required for JS rendering)
playwright install chromium
```

**Common issues:**
- `No module named 'playwright'` → Run `pip install playwright`
- `Browser closed` or browser errors → Run `playwright install chromium`
- `No module named 'cssutils'` → Run `pip install cssutils`
- Permission errors → Try `pip install --user <package>` or use a virtual environment

---

## Output Layout (Authoritative)

Output is always saved inside the `CSS-EXTRACTOR/` folder, regardless of where you run the command from:

```
CSS-EXTRACTOR/CSS-EXTRACT-RESULTS/
└── EXAMPLE.COM/
    ├── REPORT.md
    ├── CLEANED-HTML.html
    └── ASSETS/
        ├── CSS/
        │   ├── INLINE-STYLES.css
        │   ├── THIRD-PARTY__main.css
        │   └── SUMMARIES/
        │       └── THIRD-PARTY__main.css.summary.md
        └── FONTS/
            └── example-font.woff2
```

**Key notes:**
- All domain folders are **UPPERCASE**.
- All assets live inside `ASSETS/`.
- Vendor/CDN CSS is saved inside `ASSETS/CSS/` with a `THIRD-PARTY__` prefix.
- Large CSS files (≥ **5,000 lines**) get a summary in `ASSETS/CSS/SUMMARIES/`.
- The tool **overwrites** the domain folder on each run (no suffixes).

---

## What the Tool Produces

### 1) `REPORT.md`
A structured summary for agents that includes:
- CSS file inventory (with sources, line counts, and summary links)
- Font inventory (categorized as Icon / Typography / Other)
- HTML snapshot link (body‑only)
- Notes about data being auto‑generated

### 2) `CLEANED-HTML.html`
Body‑only HTML, prettified for readability. It removes:
- `<script>`, `<noscript>`, `<iframe>`, `<style>`, and `<link>` tags

This is meant to provide **structure for CSS correlation** without analytics or tracking noise.

### 3) `ASSETS/CSS/`
All CSS sources, including inline styles merged into `INLINE-STYLES.css`.

### 4) `ASSETS/CSS/SUMMARIES/`
Auto‑generated summaries for large CSS files (>= 5,000 lines). The summary focuses on:
- Design tokens and token families
- Layout & spacing literal values
- Shadows and borders
- Breakpoints
- Motion & transitions
- Typography assets and styles

### 5) `ASSETS/FONTS/`
Downloaded font files referenced in CSS.

---

## Commands

### Basic usage
```bash
python CSS-EXTRACTOR.py --url https://example.com
```

### Custom output location
```bash
python CSS-EXTRACTOR.py --url https://example.com --output /path/to/custom/output/
```

### Render timeout
```bash
python CSS-EXTRACTOR.py --url https://example.com --timeout 25
```

### Quiet mode
```bash
python CSS-EXTRACTOR.py --url https://example.com --quiet
```

### Include errors in report
```bash
python CSS-EXTRACTOR.py --url https://example.com --show-errors
```

### Custom summary threshold
```bash
python CSS-EXTRACTOR.py --url https://example.com --summary-threshold 8000
```

---

## Flags

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--url` | `-u` | Required | Target URL to extract CSS from |
| `--output` | `-o` | `CSS-EXTRACT-RESULTS/` (inside CSS-EXTRACTOR folder) | Output directory |
| `--timeout` | `-t` | `15` | JS render timeout (seconds) |
| `--quiet` | `-q` | `false` | Suppress verbose output |
| `--show-errors` | - | `false` | Include errors section in REPORT.md |
| `--summary-threshold` | - | `5000` | Line count threshold for CSS summaries |

---

## Operational Notes

- **JS rendering is supported** via Playwright; CSS loaded dynamically is captured.
- **CSS parsing is best‑effort** and will not block downloads.
- **Summaries are heuristic** and designed for AI context—full CSS is always saved.
- **Folder overwrite is intentional** to avoid stale data and suffix clutter.

---

## Creating a Style Reference Project

After extracting CSS, you can create a **reusable style reference project** for future development. When the user requests it, create a project in:

```
/PROJECTS/[PROJECT-NAME]/
├── STYLE.md          # Complete style reference document
├── FONTS/            # Local copies of typography fonts (not icon fonts)
└── REFERENCE/        # Optional: key screenshots or assets
```

### STYLE.md Template

See **[STYLE-EXAMPLE.md](./STYLE-EXAMPLE.md)** for the complete template.

The `STYLE.md` file must be **precise, data-rich, and self-contained**. It should allow anyone to replicate the exact visual style without accessing the original CSS files.

**Required sections:**
- **Typography** — Font families, weights, local files, CSS imports, type scale
- **Colors** — All color tokens with hex values, CSS variables, usage notes
- **Spacing** — Spacing scale with common usage
- **Border Radius** — By element type
- **Shadows** — Named shadows with exact values
- **Components** — Complete CSS for buttons, cards, badges, dividers
- **Layout** — Container, grid, section spacing, breakpoints
- **Transitions** — Duration, easing, common patterns
- **Base Styles** — Reset, body defaults, link styles

### Workflow for Creating a Project

1. **Extract CSS** using the CSS Extractor tool
2. **Read the REPORT.md** and CSS summaries
3. **Read the main CSS file** to identify exact values
4. **Duplicate `STYLE-EXAMPLE.md`** to `/PROJECTS/[NAME]/STYLE.md`
5. **Read and fill in** each section with the extracted data
6. **Copy typography fonts** (not icon fonts) to `/PROJECTS/[NAME]/FONTS/`
7. **Document everything** — colors, spacing, radii, shadows, components, breakpoints

The goal: **anyone reading STYLE.md can replicate the exact visual style without accessing the original source.**
