style-extractor

# Style Extractor (Web Style + Motion)

Extract a reusable design system from **web UIs**: colors, typography, spacing, components, states, and, when relevant, motion (timings, keyframes, delay chains, JS-driven behavior).

Core principle:
- Extract **visual language and interaction rules**, not the source product's information architecture.
- Keep what is reusable: tokens, component patterns, state changes, layout tendencies, motion cadence.
- Strip what is product-specific: business copy, app logic, navigation tree, feature taxonomy, marketing claims.

## Output location (REQUIRED)

- Save all generated deliverables under: `%USERPROFILE%\\style-extractor\\`
- Never write generated outputs under the skill folder (`.codex/skills/...`)
- Never dump screenshots, CSS, JS, and Markdown side-by-side in the root output directory

Each extraction must create a dedicated project folder:

```text
%USERPROFILE%\style-extractor\
  <project>-<style>\
    guides\
      style-guide.md
      motion-guide.md
      evidence-manifest.md
    evidence\
      screenshots\
      assets\
      notes\
```

Required deliverables for every extraction:
- `%USERPROFILE%\\style-extractor\\<project>-<style>\\guides\\style-guide.md`
- `%USERPROFILE%\\style-extractor\\<project>-<style>\\guides\\evidence-manifest.md`
- `%USERPROFILE%\\style-extractor\\<project>-<style>\\evidence\\`

Required when motion is meaningful:
- `%USERPROFILE%\\style-extractor\\<project>-<style>\\guides\\motion-guide.md`

Subdirectory rules:
- `guides/` only for final Markdown deliverables
- `evidence/screenshots/` only for PNG/JPG/WebP captures
- `evidence/assets/` only for downloaded CSS/JS/SVG/font stylesheets
- `evidence/notes/` only for raw dumps, runtime notes, traces, or helper text files
- Root project folder should contain folders only; no loose screenshots or loose guide files

Use these reference files:
- `references/output-contract.md` — required output structure and anti-patterns
- `references/style-guide-template.md` — required sections for the style guide
- `references/motion-guide-template.md` — required sections for the motion appendix
- `references/evidence-manifest-template.md` — required sections for the evidence manifest

## References (quality bar)

- `references/9nine-visual-novel/` — best-practice **style + motion** reference package
- `references/motherduck-design-system-reference/` — strong **static style** reference package

What to learn from these references:
- keep the document dense enough to feel like a real reference manual
- preserve semantic token tables with representative raw values
- preserve component state matrices with concrete observed values
- preserve copy-paste examples and practical implementation notes when they materially help reuse

What not to copy blindly:
- long generic filler or repeated product intro
- raw-value dumping without semantic grouping
- excessive product-specific branding or IA detail
- sections that exist only to make the document look long, without adding reuse value

## Required reference read-through (MANDATORY)

Before starting any extraction, read in this order:
1) `references/output-contract.md`
2) `references/style-guide-template.md`
3) `references/motion-guide-template.md`
4) `references/evidence-manifest-template.md`
5) all files under `references/9nine-visual-novel/guides/`
6) all files under `references/motherduck-design-system-reference/guides/`

Reference package selection rule:
- motion-heavy, media-heavy, or section-transition-driven source → use `references/9nine-visual-novel/` as the primary quality bar
- static-structure-heavy source → read `references/motherduck-design-system-reference/`

Do not start evidence collection, screenshotting, script execution, or drafting until both reference packages have been reviewed.
Extraction is incomplete if the final deliverable does not explicitly state:
- that both reference packages were reviewed before extraction
- which package was used as the primary quality bar for the current target

---

## Workflow

### Phase 0 — Inputs

1) Project name + style/variant name
2) Sources: URL / web repo / both
3) Motion assessment: does the site have meaningful motion? (determines whether Phase 1B is needed)
4) Reuse target: web app / marketing site / desktop app / design reference only
5) Primary reference package selected: 9nine / MotherDuck

Before gathering evidence, decide which source traits belong in the reusable style and which should be excluded. Use this simple filter:
- Keep: tokens, spacing rhythm, typography hierarchy, density, component language, state treatment, motion cadence
- Adapt carefully: layout primitives, panel structure, navigation patterns, content density
- Discard: product copy, feature-specific flows, brand story, app-specific IA, domain-specific labels

### Phase 0.5 — Read the reference package (REQUIRED)

Complete all of the following before Phase 1A:
- read `references/output-contract.md`
- read `references/style-guide-template.md`
- read `references/motion-guide-template.md`
- read `references/evidence-manifest-template.md`
- read `references/9nine-visual-novel/guides/style-guide.md`
- read `references/9nine-visual-novel/guides/motion-guide.md`
- read `references/9nine-visual-novel/guides/evidence-manifest.md`
- read `references/motherduck-design-system-reference/guides/style-guide.md`
- read `references/motherduck-design-system-reference/guides/motion-guide.md`
- read `references/motherduck-design-system-reference/guides/evidence-manifest.md`
- choose one of the two packages as the primary quality bar for the current extraction

If both packages are not read first, the extraction is invalid.

### Phase 1A — Static evidence gathering

#### Step 1 — Open page & screenshots

Use Chrome MCP tools:
- `new_page` / `select_page` / `navigate_page`
- `take_screenshot` (fullPage when helpful)

Minimum screenshot set:
1) baseline (full page/section)
2) navigation visible + active state
3) primary CTA: default + hover + pressed (if possible)
4) form controls: default + focus-visible (+ invalid if present)
5) modal/dialog open (if any)

#### Step 2 — Extract computed styles

Use `evaluate_script` to pull:
- CSS Variables (`:root` and scoped)
- Colors, typography, spacing from `getComputedStyle`
- Component state matrices (default / hover / active / focus-visible / disabled)

#### Step 3 — Pull CSS/JS bodies

- `list_network_requests` / `get_network_request` to download CSS files
- Useful for extracting `@keyframes`, CSS variables, and media queries offline

Minimum static evidence to keep in `...\\evidence\\`:
- screenshots under `evidence/screenshots/`
- downloaded CSS/JS under `evidence/assets/`
- notes and selector inventories under `evidence/notes/`

---

### Phase 1B — Motion evidence gathering (when site has meaningful motion)

> Static and motion are independent paths. Skip this phase if the site has no meaningful animation.

Follow these steps **in priority order**. Each level captures more; stop when you have enough evidence.

#### Level 1 — @keyframes extraction (no interaction needed)

Paste `scripts/transition-scanner.js`, then call:
```js
__seTransition.keyframes()
```
Returns all `@keyframes` definitions from stylesheets. This is deterministic and complete—no timing issues.

#### Level 2 — CSS transition scan (no interaction needed)

Same script, call:
```js
__seTransition.scan()            // scan entire page
__seTransition.scan('.my-section') // scan specific section
```
Returns every element's `transition-property / duration / easing / delay` + clusters by pattern. This shows **what can animate** even if nothing is animating yet.

#### Level 3 — Interaction diff (requires triggering interactions)

This captures the dominant pattern on modern sites: **JS sets inline style → CSS transition interpolates**.

Paste `scripts/interaction-diff.js`, then:
```js
// 1. Watch elements you care about
__seDiff.watch([
  '[class*="sectionContainer"]',
  '[class*="illustration"]',
  '[class*="navItem"]',
  'button, a[class*="cta"], a[class*="CTA"]'
])

// 2. Trigger interaction and capture diff
__seDiff.triggerAndCapture(
  () => document.querySelector('.nav-item-2').click(),
  { captureAt: 50, settleAt: 500 }
)
```
Returns:
- `diffs` — per-element before/after inline style + computed style changes
- `duringAnimations` — `document.getAnimations()` captured within the 50ms transition window
- `afterAnimations` — what's still running after settle

**Key insight**: `document.getAnimations()` only returns results during active CSS transitions. The capture window is typically <300ms. This script captures within that window automatically.

Repeat for 3+ key interactions (section change, component switch, hover, scroll).

#### Level 4 — JS library extraction

Paste `scripts/library-detect.js` to detect third-party animation libraries.

Returns `{ globals, instances, dom, fingerprints, assets }`.

Key: many modern sites bundle libraries as modules, so `window.Swiper` etc. may be undefined. The script also checks:
- `el.swiper` — Swiper instance on DOM elements (works when bundled)
- `[data-aos-*]` — AOS attributes on elements
- `[data-framer-*]` — Framer Motion attributes
- Asset URL hints (script/stylesheet URLs containing library names)

When instances are found, configs are extracted directly (Swiper params, AOS settings, etc.).

#### Level 5 — rAF sampling (fallback for opaque JS motion)

When the above levels don't capture enough (e.g., hand-written `requestAnimationFrame` loops), use `scripts/motion-tools.js`:
```js
__seMotion.sample('.animated-element', { durationMs: 800, include: ['transform', 'opacity'] })
```
Records computed style values every frame. Useful for inferring duration and property ranges, but cannot capture easing or intent.

#### Level 6 — Performance trace (optional, complex motion)

For very complex orchestrated animations:
- `performance_start_trace` / `performance_stop_trace`
- Analyze via `performance_analyze_insight`

---

### Phase 2 — Abstraction and de-productization (REQUIRED)

Do not write the guide as a product teardown. Convert evidence into reusable rules.

For each major finding, classify it explicitly:
- `Reusable`: can be copied directly as a token, component rule, state rule, or motion primitive
- `Adapted`: useful idea, but needs reshaping for the target product type
- `Discarded`: source-specific structure or content that should not be copied

Examples:
- A cloud-blue surface palette: `Reusable`
- A docs sidebar + article rail layout: `Adapted`
- An AI chat app's prompt-library IA: `Discarded`
- A marketing hero with video background: `Adapted` or `Discarded`, depending on target

### Phase 3 — Semantic tokenization (REQUIRED)

Do not stop at raw values. Convert repeated values into **semantic tokens**:
1) cluster repeated values (colors/radii/durations/easings/shadows)
2) map usage (CTA/text/border/overlay/active/etc.)
3) name by intent (e.g., `--color-accent`, `--motion-300`, `nav.switch.iconColor`)
4) keep evidence alongside tokens (raw values + element/selector/screenshot)

### Phase 4 — Write the deliverables

Start from the reference templates. Do not improvise the top-level structure unless the source clearly requires one.

#### Deliverable A — Style guide (REQUIRED)

Follow `references/style-guide-template.md`.

This file must answer:
- what the style feels like
- which tokens define it
- how components behave across states
- what layout tendencies are reusable
- how to rebuild the visual language without copying the product itself

#### Deliverable B — Motion guide (REQUIRED when dynamic)

Follow `references/motion-guide-template.md`.

This file must answer:
- what moves
- what triggers motion
- durations, delays, easing, and keyframes
- whether motion is CSS-driven, transition-driven, or JS/library-driven
- which motion primitives are reusable in another product

#### Deliverable C — Evidence manifest (REQUIRED)

Follow `references/evidence-manifest-template.md`.

Include:
- source URLs / repo refs / date captured
- screenshot list
- downloaded CSS/JS files or notes
- scripts used
- interactions tested
- gaps, blockers, and confidence notes
- reference package reviewed and which package files were read before extraction

Component state matrix must include at least:
- default / hover / active(pressed) / focus-visible / disabled
- include loading / selected / invalid when those states exist

---

## Scripts reference

| Script | Namespace | Purpose |
|--------|-----------|---------|
| `scripts/transition-scanner.js` | `__seTransition` | Scan CSS transitions + extract @keyframes |
| `scripts/interaction-diff.js` | `__seDiff` | Before/after inline style diff + instant getAnimations |
| `scripts/motion-tools.js` | `__seMotion` | getAnimations snapshot + rAF sampling |
| `scripts/library-detect.js` | (returns directly) | Library detection + instance config extraction |
| `scripts/extract-keyframes.py` | CLI | Offline @keyframes extraction from downloaded CSS files |

---

## Quality checklist

### Static
- [ ] tokens include usage intent (not just lists)
- [ ] examples are copy-pasteable (HTML+CSS)
- [ ] 5+ copy-paste component examples
- [ ] reusable vs adapted vs discarded source traits are called out
- [ ] product-specific IA/copy is stripped from the final guide

### Motion (when dynamic)
- [ ] all @keyframes extracted from stylesheets (Level 1)
- [ ] CSS transition patterns documented with durations/easing (Level 2)
- [ ] 3+ key interactions with before/after diff evidence (Level 3)
- [ ] JS libraries detected and configs extracted when present (Level 4)
- [ ] at least one documented "delay chain" if present
- [ ] motion semantic tokens defined (duration scale + easing scale)

### Self-check (run after completing the guide)
1. Does every color token have a usage mapping? (not just a hex list)
2. Does every component have a state matrix with actual computed values?
3. Can someone reproduce the motion from the documentation alone?
4. Are all copy-paste examples self-contained (HTML + CSS in one block)?
5. If the original product disappeared, would this guide still be useful as a design reference?
6. Did the guide extract style without accidentally cloning the source product's information model?

### Failure conditions

Do not consider the extraction complete if any of the following are true:
- output is only one prose-heavy markdown file with no evidence manifest
- tokens are raw lists without semantic naming or usage mapping
- the document describes the source product more than the reusable style
- dynamic sites have no motion appendix despite meaningful motion
- examples cannot be implemented directly
- screenshots and downloaded assets are dumped loose in the project root instead of grouped into subfolders