skillui 1.1.0 → 1.1.2

package/README.md

@@ -0,0 +1,195 @@
+# skillui
+
+**Reverse-engineer any design system. Pure static analysis — no AI, no API keys.**
+
+Point `skillui` at any website, git repo, or local project and get exact colors, fonts, spacing, components, and animations — packaged as a `.skill` file Claude can read.
+
+```bash
+npm install -g skillui
+skillui --url https://yoursite.com --mode ultra
+```
+
+---
+
+## What it does
+
+skillui crawls your target and extracts:
+
+| Output | Contents |
+|--------|----------|
+| `DESIGN.md` | Colors, typography, spacing, border radius, components |
+| `ANIMATIONS.md` | CSS keyframes, scroll triggers, GSAP/Lottie/Three.js detection |
+| `LAYOUT.md` | Flex/grid containers, page structure, spacing relationships |
+| `COMPONENTS.md` | DOM patterns, HTML fingerprints, class analysis |
+| `INTERACTIONS.md` | Hover/focus state diffs with before/after style snapshots |
+| `VISUAL_GUIDE.md` | Master visual reference with all screenshots embedded |
+| `screens/scroll/` | 7 cinematic scroll journey screenshots |
+| `tokens/*.json` | Colors, spacing, typography as JSON tokens |
+| `fonts/` | Google Fonts bundled locally |
+
+Everything is packaged into a `.skill` ZIP file you drop into Claude Code.
+
+---
+
+## Install
+
+```bash
+npm install -g skillui
+```
+
+Requires Node.js 18+.
+
+For ultra mode visual extraction, install Playwright separately:
+
+```bash
+npm install playwright
+npx playwright install chromium
+```
+
+---
+
+## Usage
+
+### Crawl a website
+
+```bash
+skillui --url https://linear.app
+```
+
+### Ultra mode (full cinematic extraction)
+
+```bash
+skillui --url https://linear.app --mode ultra
+```
+
+Ultra mode adds:
+- 7 scroll journey screenshots showing the page at each scroll depth
+- Hover/focus interaction state diffs
+- Full CSS keyframe extraction
+- Animation library detection (GSAP, Lottie, Three.js, AOS, etc.)
+- Video background first-frame capture
+- DOM component fingerprinting
+- Flex/grid layout extraction
+
+### Scan a local project
+
+```bash
+skillui --dir ./my-app
+```
+
+### Clone and scan a git repo
+
+```bash
+skillui --repo https://github.com/org/repo
+```
+
+---
+
+## All flags
+
+```
+skillui --url <url>           Crawl a live website
+skillui --dir <path>          Scan a local project directory
+skillui --repo <url>          Clone and scan a git repository
+
+--mode ultra                  Enable cinematic extraction (requires Playwright)
+--screens <n>                 Pages to crawl in ultra mode (default: 5, max: 20)
+--out <path>                  Output directory (default: ./)
+--name <string>               Override the project name
+--format design-md|skill|both Output format (default: both)
+--no-skill                    Output DESIGN.md only, skip .skill packaging
+```
+
+---
+
+## Use with Claude Code
+
+After running skillui, install the `.skill` file:
+
+```bash
+claude skill install ./linear-design.skill
+```
+
+Then ask Claude:
+
+> "Build me a dashboard that matches the Linear design system"
+
+Claude will read DESIGN.md, ANIMATIONS.md, LAYOUT.md, COMPONENTS.md, and all scroll journey screenshots to reconstruct the exact visual language of the site.
+
+---
+
+## Output structure
+
+```
+linear-design/
+├── SKILL.md                  # Master skill file (loaded by Claude)
+├── DESIGN.md                 # Full design system tokens
+├── references/
+│   ├── DESIGN.md             # Extended design reference
+│   ├── ANIMATIONS.md         # Motion specs and keyframes
+│   ├── LAYOUT.md             # Layout containers and grid
+│   ├── COMPONENTS.md         # DOM component patterns
+│   ├── INTERACTIONS.md       # Hover/focus state diffs
+│   └── VISUAL_GUIDE.md       # All screenshots in sequence
+├── screens/
+│   ├── scroll/               # Scroll journey screenshots
+│   │   ├── scroll-000.png    # Hero / above the fold
+│   │   ├── scroll-017.png
+│   │   ├── scroll-033.png
+│   │   ├── scroll-050.png
+│   │   ├── scroll-067.png
+│   │   ├── scroll-083.png
+│   │   └── scroll-100.png    # Footer
+│   ├── pages/                # Full-page screenshots (ultra)
+│   └── sections/             # Section clip screenshots (ultra)
+├── tokens/
+│   ├── colors.json
+│   ├── spacing.json
+│   └── typography.json
+└── fonts/                    # Bundled Google Fonts (woff2)
+```
+
+---
+
+## Examples
+
+```bash
+# Extract Nothing.tech design system with full ultra mode
+skillui --url https://nothing.tech --mode ultra --screens 10
+
+# Scan a local Next.js app
+skillui --dir ./my-nextjs-app --name "MyApp"
+
+# Clone and analyze a public repo
+skillui --repo https://github.com/vercel/next.js --name "Next.js"
+
+# Output only DESIGN.md, no .skill packaging
+skillui --url https://stripe.com --format design-md
+
+# Save output to a specific directory
+skillui --url https://linear.app --out ./design-systems
+```
+
+---
+
+## How it works
+
+skillui uses pure static analysis — no AI, no API keys, no cloud.
+
+1. **URL mode** — fetches HTML, crawls all linked CSS files, extracts computed styles via Playwright DOM inspection
+2. **Dir mode** — scans all `.css`, `.scss`, `.ts`, `.tsx`, `.js`, `.jsx` files for design tokens, Tailwind config, CSS variables, and component patterns
+3. **Repo mode** — clones the repo to a temp directory and runs dir mode
+4. **Ultra mode** — runs Playwright to capture scroll journey screenshots, detect animation libraries from `window.*` globals, extract `@keyframes` from `document.styleSheets`, capture hover/focus state diffs, and fingerprint DOM components
+
+---
+
+## Requirements
+
+- Node.js 18+
+- For `--mode ultra`: Playwright (`npm install playwright && npx playwright install chromium`)
+
+---
+
+## License
+
+MIT

package/dist/extractors/ultra/animations.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.captureAnimations = captureAnimations;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const playwright_loader_1 = require("../../playwright-loader");
 /**
  * Ultra mode — Full Animation Extractor
  *
@@ -67,13 +68,9 @@ async function captureAnimations(url, skillDir) {
         webglDetected: false,
         lottieCount: 0,
     };
-    let playwright;
-    try {
-        playwright = require('playwright');
-    }
-    catch {
+    const playwright = (0, playwright_loader_1.loadPlaywright)();
+    if (!playwright)
         return empty;
-    }
     const scrollDir = path.join(skillDir, 'screens', 'scroll');
     fs.mkdirSync(scrollDir, { recursive: true });
     const browser = await playwright.chromium.launch({ headless: true });

package/dist/extractors/ultra/components-dom.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectDOMComponents = detectDOMComponents;
+const playwright_loader_1 = require("../../playwright-loader");
 /**
  * Ultra mode — DOM Component Detector
  *
@@ -12,13 +13,9 @@ exports.detectDOMComponents = detectDOMComponents;
  * Requires Playwright (optional peer dependency).
  */
 async function detectDOMComponents(url) {
-    let playwright;
-    try {
-        playwright = require('playwright');
-    }
-    catch {
+    const playwright = (0, playwright_loader_1.loadPlaywright)();
+    if (!playwright)
         return [];
-    }
     const browser = await playwright.chromium.launch({ headless: true });
     try {
         const context = await browser.newContext({

package/dist/extractors/ultra/interactions.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.captureInteractions = captureInteractions;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const playwright_loader_1 = require("../../playwright-loader");
 const TRACKED_PROPS = [
     'backgroundColor',
     'color',
@@ -67,13 +68,9 @@ const INTERACTIVE_SELECTORS = [
  * Returns InteractionRecord[] for INTERACTIONS.md generation.
  */
 async function captureInteractions(url, skillDir) {
-    let playwright;
-    try {
-        playwright = require('playwright');
-    }
-    catch {
+    const playwright = (0, playwright_loader_1.loadPlaywright)();
+    if (!playwright)
         return [];
-    }
     const statesDir = path.join(skillDir, 'screens', 'states');
     fs.mkdirSync(statesDir, { recursive: true });
     const records = [];

package/dist/extractors/ultra/layout.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractLayouts = extractLayouts;
+const playwright_loader_1 = require("../../playwright-loader");
 /**
  * Ultra mode — DOM Layout Extractor
  *
@@ -13,13 +14,9 @@ exports.extractLayouts = extractLayouts;
  * Requires Playwright (optional peer dependency).
  */
 async function extractLayouts(url) {
-    let playwright;
-    try {
-        playwright = require('playwright');
-    }
-    catch {
+    const playwright = (0, playwright_loader_1.loadPlaywright)();
+    if (!playwright)
         return [];
-    }
     const browser = await playwright.chromium.launch({ headless: true });
     try {
         const context = await browser.newContext({

package/dist/extractors/ultra/pages.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.capturePageScreenshots = capturePageScreenshots;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const playwright_loader_1 = require("../../playwright-loader");
 /**
  * Ultra mode — Page & Section Screenshots
  *
@@ -47,13 +48,9 @@ const path = __importStar(require("path"));
  * Requires Playwright (optional peer dependency).
  */
 async function capturePageScreenshots(originUrl, skillDir, maxPages) {
-    let playwright;
-    try {
-        playwright = require('playwright');
-    }
-    catch {
+    const playwright = (0, playwright_loader_1.loadPlaywright)();
+    if (!playwright)
         return { pages: [], sections: [] };
-    }
     const pagesDir = path.join(skillDir, 'screens', 'pages');
     const sectionsDir = path.join(skillDir, 'screens', 'sections');
     fs.mkdirSync(pagesDir, { recursive: true });

package/dist/modes/ultra.js

@@ -46,6 +46,7 @@ const interactions_md_1 = require("../writers/interactions-md");
 const components_md_1 = require("../writers/components-md");
 const animations_md_1 = require("../writers/animations-md");
 const tokens_json_1 = require("../writers/tokens-json");
+const playwright_loader_1 = require("../playwright-loader");
 /**
  * Ultra mode orchestrator.
  *
@@ -72,15 +73,10 @@ async function runUltraMode(url, profile, skillDir, opts) {
     fs.mkdirSync(path.join(skillDir, 'screens', 'scroll'), { recursive: true });
     fs.mkdirSync(path.join(skillDir, 'references'), { recursive: true });
     fs.mkdirSync(path.join(skillDir, 'tokens'), { recursive: true });
-    let hasPlaywright = false;
-    try {
-        require.resolve('playwright');
-        hasPlaywright = true;
-    }
-    catch { /* not installed */ }
+    const hasPlaywright = (0, playwright_loader_1.loadPlaywright)() !== null;
     if (!hasPlaywright) {
-        process.stdout.write('\n  ⚠  Playwright not installed — ultra visual features skipped\n');
-        process.stdout.write('     Run: npm install playwright && npx playwright install chromium\n\n');
+        process.stdout.write('\n  ⚠  Playwright not found — ultra visual features skipped\n');
+        process.stdout.write('     Fix: npm install -g playwright && npx playwright install chromium\n\n');
         (0, tokens_json_1.writeTokensJson)(profile, skillDir);
         writeStubs(skillDir);
         const emptyAnim = emptyAnimResult();

package/dist/playwright-loader.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Loads playwright from any location it might be installed:
+ * 1. Bundled with the CLI (peer dep)
+ * 2. In the user's cwd node_modules (local project install)
+ * 3. In the global npm prefix (npm install -g playwright)
+ *
+ * Returns the playwright module or null if not found anywhere.
+ */
+export declare function loadPlaywright(): any | null;
+//# sourceMappingURL=playwright-loader.d.ts.map

package/dist/playwright-loader.js

@@ -0,0 +1,71 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPlaywright = loadPlaywright;
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+/**
+ * Loads playwright from any location it might be installed:
+ * 1. Bundled with the CLI (peer dep)
+ * 2. In the user's cwd node_modules (local project install)
+ * 3. In the global npm prefix (npm install -g playwright)
+ *
+ * Returns the playwright module or null if not found anywhere.
+ */
+function loadPlaywright() {
+    // 1. Try standard require (works when playwright is in same node_modules tree)
+    try {
+        return require('playwright');
+    }
+    catch { /* fall through */ }
+    // 2. Try from cwd (user ran: npm install playwright in their project)
+    try {
+        const cwdPath = path.join(process.cwd(), 'node_modules', 'playwright');
+        return require(cwdPath);
+    }
+    catch { /* fall through */ }
+    // 3. Try from global npm prefix (npm install -g playwright)
+    try {
+        const globalRoot = (0, child_process_1.execSync)('npm root -g', {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        }).trim();
+        return require(path.join(globalRoot, 'playwright'));
+    }
+    catch { /* fall through */ }
+    return null;
+}
+//# sourceMappingURL=playwright-loader.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillui",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Reverse-engineer design systems from any website, repo, or project. Extracts colors, fonts, spacing, animations, and components — packaged as a .skill file for Claude. Pure static analysis, zero AI, zero API keys.",
   "main": "dist/cli.js",
   "bin": {
@@ -30,13 +30,13 @@
   ],
   "author": "Amaan",
   "license": "MIT",
-  "homepage": "https://github.com/amaanbuilds/skillui#readme",
+  "homepage": "https://skillui.vercel.app/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/amaanbuilds/skillui.git"
+    "url": "https://github.com/amaancoderx/skillui.git"
   },
   "bugs": {
-    "url": "https://github.com/amaanbuilds/skillui/issues"
+    "url": "https://github.com/amaancoderx/skillui/issues"
   },
   "dependencies": {
     "@babel/parser": "^7.24.0",
@@ -73,6 +73,7 @@
   },
   "files": [
     "dist/**/*.js",
-    "dist/**/*.d.ts"
+    "dist/**/*.d.ts",
+    "README.md"
   ]
 }