lucent-snow/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:

%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:

__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:

__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:

// 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:

__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