### Install skillui globally Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Installs the skillui CLI globally. Requires Node.js 18+. ```bash npm install -g skillui ``` -------------------------------- ### Quick start: extract and build with Claude Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Quick start workflow: extract a design system from a URL, open the output folder in Claude Code, and ask Claude to build a matching UI. Claude automatically reads CLAUDE.md and SKILL.md. ```bash # 1. Extract a design system from any URL skillui --url https://notion.so # 2. Open the output folder in Claude Code cd notion-design && claude # 3. Ask Claude to build your UI "Build me a landing page that matches this design system" ``` -------------------------------- ### Install Playwright for ultra mode Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Required setup for SkillUI's ultra mode, which uses Playwright for scroll screenshots, animation detection, and DOM fingerprinting. Run this before using --mode ultra. ```bash npm install playwright && npx playwright install chromium ``` -------------------------------- ### Usage example for detectFrameworks and getProjectName Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-framework.md Usage example for detectFrameworks and getProjectName. Shows iterating over detected frameworks and logging id, name, and version, and resolving the project name with and without an override. ```ts import { detectFrameworks, getProjectName } from './extractors/framework'; const frameworks = detectFrameworks('./my-app'); for (const f of frameworks) { console.log(`${f.id} — ${f.name}${f.version ? ' ' + f.version : ''}`); } const name = getProjectName('./my-app', 'MyApp'); // 'MyApp' (override wins) const auto = getProjectName('./my-app'); // package.json name, else folder basename console.log(name, auto); ``` -------------------------------- ### skillui CLI usage examples Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Five command-line examples showing how to run the skillui CLI with different flags: --url for a website URL, --dir for a local directory, --repo for a GitHub repository, --format to output only DESIGN.md, and --out to specify an output directory. Each command is a separate invocation. ```bash skillui --url https://nothing.tech --mode ultra --screens 10 ``` ```bash skillui --dir ./my-nextjs-app --name "MyApp" ``` ```bash skillui --repo https://github.com/vercel/next.js --name "Next.js" ``` ```bash skillui --url https://stripe.com --format design-md ``` ```bash skillui --url https://linear.app --out ./design-systems ``` -------------------------------- ### startSpinner Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Starts a spinner with a message and returns a spinner instance for lifecycle management. ```APIDOC ## `startSpinner` ### Description Starts a spinner with the given message. Returns a spinner instance for later success or failure updates. ### Method `startSpinner` ### Parameters - **message** (`string`) - Required - The message to display next to the spinner. ### Returns - Spinner instance - Used with `succeedSpinner` or `failSpinner`. ### Usage Example ```ts import { startSpinner, succeedSpinner, failSpinner } from './ui'; const sp = startSpinner('Scanning...'); try { const result = await doWork(); succeedSpinner(sp, 'Scan complete', `${result.length} items`); } catch (e: any) { failSpinner(sp, 'Scan failed', e.message); throw e; } ``` ``` -------------------------------- ### Usage example: captureScreenshot with import (TypeScript) Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/screenshot.md Shows how to import and call captureScreenshot, handling the returned relative path or null. The example logs the screenshot path or a failure message when microlink.io is unreachable or blocked. ```typescript import { captureScreenshot } from './screenshot'; const rel = await captureScreenshot('https://linear.app', './linear-design'); if (rel) { console.log(`homepage screenshot: ./linear-design/${rel}`); } else { console.log('no screenshot captured (microlink.io unreachable or blocked)'); } ``` -------------------------------- ### Install Playwright for ultra mode Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Installs Playwright and the Chromium browser for ultra mode, which enables full visual extraction with scroll screenshots and interaction diffs. ```bash npm install playwright npx playwright install chromium ``` -------------------------------- ### package.json main and bin configuration Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/cli.md Configures the package entry point and the `skillui` binary in package.json. The CLI is bundled to `dist/cli.js` and invoked through the `skillui` binary or `node dist/cli.js` / `npm start`. ```json // package.json "main": "dist/cli.js", "bin": { "skillui": "dist/cli.js" } ``` -------------------------------- ### Basic repo analysis with runRepoMode Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/modes-repo.md Basic usage example: imports runRepoMode, calls it with a public repository URL and an optional name override, then logs the project name and frameworks from the returned DesignProfile. ```ts import { runRepoMode } from './modes/repo'; const profile = await runRepoMode('https://github.com/vercel/next.js', 'Next.js'); console.log(profile.projectName); console.log(profile.frameworks.map(f => `${f.name} ${f.version || ''}`).join(', ')); ``` -------------------------------- ### Generate components and interactions markdown strings Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/writers-markdown.md Imports the components and interactions markdown writers and uses them to generate markdown strings. Logs boolean checks to verify the output starts with '# Component Reference' and includes '## Interaction Rules'. The example assumes 'ultraResult' and 'profile' are defined elsewhere. ```typescript import { generateComponentsMd } from './writers/components-md'; import { generateInteractionsMd } from './writers/interactions-md'; const compMd = generateComponentsMd(ultraResult.domComponents, profile); const interMd = generateInteractionsMd(ultraResult.interactions, profile); // Each is a self-contained markdown document; no I/O or state console.log(compMd.startsWith('# Component Reference'), interMd.includes('## Interaction Rules')); ``` -------------------------------- ### Generate skill with design MD and ultra animations Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/writers-skill.md Example of generating a skill package using generateSkill with a design MD and ultra animations. Logs the resulting skill file and folder. ```ts import { generateSkill } from './writers/skill'; import { generateDesignMd } from './writers/design-md'; const designMd = generateDesignMd(profile, 'screenshots/homepage.png'); const { skillDir, skillFile } = await generateSkill(profile, designMd, './', null, ultraAnimations); console.log(`package: ${skillFile} (folder: ${skillDir})`); ``` -------------------------------- ### Basic directory scan with runDirMode Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/modes-dir.md Basic usage example: scans a project directory with an explicit name and logs the number of colors, typography tokens, theme darkness, and spacing base from the resulting profile. ```ts import { runDirMode } from './modes/dir'; const profile = await runDirMode('/path/to/my-app', 'MyApp'); console.log(`${profile.colors.length} colors, ${profile.typography.length} type tokens`); console.log(profile.designTraits.isDark ? 'dark theme' : 'light theme'); console.log(`spacing base: ${profile.spacing.base}px`); ``` -------------------------------- ### createPageBar Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Creates and returns a started cli-progress SingleBar with a specific format for crawling pages. ```APIDOC ## createPageBar ### Description Returns a started `cli-progress` `SingleBar` (`Presets.shades_classic`) with format `Crawling pages [{bar}] {value}/{total} {percentage}%`. ### Signature ```ts export function createPageBar(total: number): SingleBar ``` ### Parameters - **total** (number) - Required - The total number of pages to crawl. ### Returns - **SingleBar** - A started progress bar instance. ``` -------------------------------- ### Error-handling example for detectFrameworks Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-framework.md Error-handling example: detectFrameworks does not throw on a malformed package.json; it returns an empty array, which is safe to feed into normalize. ```ts import { detectFrameworks } from './extractors/framework'; const frameworks = detectFrameworks('/path/with/broken-package-json'); // does not throw; frameworks may be [] and the CLI reports "none detected" ``` -------------------------------- ### runInteractivePrompts Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Interactive prompt function that guides users through selecting source, target, mode, and output directory. ```APIDOC ## `runInteractivePrompts` ### Description Dynamically imports `prompts` and asks four questions: **source** (select: url/dir/repo), **target** (text, message depends on source), **mode** (select: default/ultra), **out** (text, initial `'./'`). `onCancel` calls `process.exit(0)`. Returns `null` when `source` or `target` is missing, otherwise the answers object. ### Method `runInteractivePrompts` ### Parameters None ### Returns - `Promise` - The answers object or `null` if cancelled or missing required fields. ### InteractiveAnswers Interface - **source** (`'url' | 'dir' | 'repo'`) - Required - The source type selected by the user. - **target** (`string`) - Required - The target URL, directory, or repository. - **mode** (`'default' | 'ultra'`) - Required - The extraction mode. - **out** (`string`) - Required - The output directory (initial `'./'`). ### Usage Example ```ts import { runInteractivePrompts } from './ui'; const answers = await runInteractivePrompts(); if (!answers) { console.log('cancelled'); process.exit(0); } console.log(`extracting ${answers.target} with mode ${answers.mode}`); const out = ( answers.source === 'url' ? `--url ${answers.target}` : answers.source === 'dir' ? `--dir ${answers.target}` : `--repo ${answers.target}` ); ``` ``` -------------------------------- ### Load Playwright and handle null Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/playwright-loader.md Usage example showing how to load Playwright and handle the null case with a warning and fix instruction. When non-null, launches a headless Chromium browser. ```ts import { loadPlaywright } from './playwright-loader'; const playwright = loadPlaywright(); if (!playwright) { console.warn('Playwright not installed — computed style extraction skipped'); console.warn('Fix: npm install playwright && npx playwright install chromium'); } else { const browser = await playwright.chromium.launch({ headless: true }); // ... browser automation await browser.close(); } ``` -------------------------------- ### Usage example for extractComputedTokens with Playwright check Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-tokens-web.md Usage example showing how to call extractHttpCSSTokens as a baseline and conditionally call extractComputedTokens only when loadPlaywright() returns true. The example logs the number of colors and component names from the HTTP extraction, and the computed colors when available. ```ts import { extractHttpCSSTokens } from './extractors/tokens/http-css'; import { extractComputedTokens } from './extractors/tokens/computed'; import { loadPlaywright } from './playwright-loader'; // Baseline — always works, no browser const http = await extractHttpCSSTokens('https://linear.app', 5); console.log(http.tokens.colors.length, 'css colors', http.components.map(c => c.name)); // Enhancement — only when Playwright is present if (loadPlaywright()) { const computed = await extractComputedTokens('https://linear.app', 3); console.log(computed.colors.length, 'computed colors'); } else { console.warn('Playwright not installed — computed style extraction skipped'); } ``` -------------------------------- ### Basic crawl usage example Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/modes-url.md Calls runUrlMode with a URL and name override, then logs color counts, Playwright status, and page section types. Requires importing runUrlMode from './modes/url'. ```ts import { runUrlMode } from './modes/url'; const result = await runUrlMode('https://stripe.com', 'Stripe'); console.log(`${result.cssColorCount} CSS colors · ${result.computedColorCount} computed`); console.log(result.hadPlaywright ? 'computed pass ran' : 'Playwright not installed'); console.log(result.profile.pageSections.map(s => s.type)); ``` -------------------------------- ### Generate and write design, animations, and layout markdown files Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/writers-markdown.md Imports the design, animations, and layout markdown writers and uses them to generate markdown strings, then writes them to DESIGN.md, references/ANIMATIONS.md, and references/LAYOUT.md using fs.writeFileSync. The example assumes 'profile' and 'ultraResult' are defined elsewhere. ```typescript import { generateDesignMd } from './writers/design-md'; import { generateAnimationsMd } from './writers/animations-md'; import { generateLayoutMd } from './writers/layout-md'; import * as fs from 'fs'; const designMd = generateDesignMd(profile, 'screenshots/homepage.png'); const animMd = generateAnimationsMd(ultraResult.animations, profile); const layoutMd = generateLayoutMd(ultraResult.layouts, profile); fs.writeFileSync('DESIGN.md', designMd, 'utf-8'); fs.writeFileSync('references/ANIMATIONS.md', animMd, 'utf-8'); fs.writeFileSync('references/LAYOUT.md', layoutMd, 'utf-8'); ``` -------------------------------- ### createPageBar function signature Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Returns a started cli-progress SingleBar with Presets.shades_classic and format 'Crawling pages [{bar}] {value}/{total} {percentage}%'. Use for progress display during page crawling. ```ts export function createPageBar(total: number): SingleBar { ``` -------------------------------- ### Graceful degradation without Playwright Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-ultra.md Demonstrates graceful degradation when Playwright is not installed: captureAnimations returns empty arrays. The example checks for empty keyframes and scrollFrames and logs a message with the command to install Playwright and Chromium. ```ts import { captureAnimations } from './extractors/ultra/animations'; const anim = await captureAnimations('https://linear.app', './out'); if (anim.keyframes.length === 0 && anim.scrollFrames.length === 0) { console.log('No Playwright — animation data empty (run: npm install playwright && npx playwright install chromium)'); } ``` -------------------------------- ### showUltraPlaywrightError function signature Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Prints a red boxed panel: 'Ultra mode requires Playwright' with install command 'npm install -g playwright && npx playwright install chromium'. Use when ultra mode is requested but Playwright is not available. ```ts export function showUltraPlaywrightError(): void { ``` -------------------------------- ### Layout-only with --dir and --format, plus error case Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/cli.md Layout-only crawl with design-md format, followed by a directory verification error example showing exit code 1. ```bash skillui --dir ./my-nextjs-app --format design-md ``` ```bash skillui --dir ./missing-dir # prints "Error: Directory not found: ..." and exits 1 ``` -------------------------------- ### captureScreenshot Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/screenshot.md Documentation for the captureScreenshot function, including parameters, return value, behavior, and usage example. ```APIDOC ## captureScreenshot ### Description Captures a best-effort homepage screenshot of a given URL using the free microlink.io API. Returns the relative path to the saved screenshot or null on failure. ### Method Function call ### Endpoint `captureScreenshot(url: string, skillDir: string): Promise` ### Parameters - `url` (string) - Required - Target URL to screenshot - `skillDir` (string) - Required - Output folder; `screenshots/` subdirectory created here ### Return Value `Promise` - Relative path (`screenshots/homepage.png` for image content-type responses, `screenshots/homepage.jpg` otherwise), or `null` when the request fails, returns non-OK, returns a body < 1000 bytes, or unparses. ### Behavior 1. Creates the `screenshots` subdirectory under `skillDir`. 2. Sends a request to `https://api.microlink.io?url=&screenshot=true&meta=false&embed=screenshot.url&waitFor=2000` with UA `skillui/1.0` and a 25-second timeout. 3. If the response content-type starts with `image/`, saves the bytes directly as `homepage.png` (if content-type contains `png`) or `homepage.jpg`; returns the relative path. 4. Otherwise, parses the JSON body, reads `json.data.screenshot.url`, fetches it (20-second timeout), validates ≥ 1000 bytes, and saves as `homepage.jpg`. 5. Every step is try/catch-guarded; any failure returns `null`. ### Usage Example ```ts import { captureScreenshot } from './screenshot'; const rel = await captureScreenshot('https://linear.app', './linear-design'); if (rel) { console.log(`homepage screenshot: ./linear-design/${rel}`); } else { console.log('no screenshot captured (microlink.io unreachable or blocked)'); } ``` ``` -------------------------------- ### Write token files directly Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/writers-skill.md Example of writing token files directly using writeTokensJson after running URL mode. Outputs to ./stripe-design/tokens/{colors,spacing,typography}.json. ```ts import { writeTokensJson } from './writers/tokens-json'; import { runUrlMode } from './modes/url'; const urlResult = await runUrlMode('https://stripe.com', 'Stripe'); writeTokensJson(urlResult.profile, './stripe-design'); // -> ./stripe-design/tokens/{colors,spacing,typography}.json ``` -------------------------------- ### showUltraPlaywrightError Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Prints a red boxed panel indicating that Ultra mode requires Playwright, with installation instructions. ```APIDOC ## showUltraPlaywrightError ### Description Prints a red boxed panel: "Ultra mode requires Playwright" with install command `npm install -g playwright && npx playwright install chromium`. ### Signature ```ts export function showUltraPlaywrightError(): void ``` ### Parameters None. ### Returns - **void** - No return value. ``` -------------------------------- ### Partial bundling fallback example Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/font-resolver.md Handles partial bundling for custom or proprietary fonts that may be absent from Google Fonts. If the CDN is unreachable, the original remote src is preserved and bundledCount is 0. ```ts import { bundleFonts } from './font-resolver'; const custom = [{ family: 'delight', src: 'https://cdn.site.com/delight.woff2', format: 'woff2' }]; const result = await bundleFonts(custom, ['delight'], './out'); // If the CDN is unreachable, updatedSources keeps the original remote src: console.log(result.bundledCount === 0 ? result.updatedSources[0].src : 'local'); ``` -------------------------------- ### Detect project libraries with null-safe handling Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-components.md Usage example for detectProjectLibraries with null-safe handling. It logs the detected icon, state, and animation libraries, using fallback strings when null. The comment notes that a missing or invalid package.json results in all three fields staying null and the function never throws. ```ts import { detectProjectLibraries } from './extractors/components'; const libs = detectProjectLibraries('./my-app'); console.log(libs.iconLibrary ?? 'no icon library'); console.log(libs.stateLibrary ?? 'no state library'); console.log(libs.animationLibrary ?? 'no animation library'); // Missing/invalid package.json -> all three stay null (never throws) ``` -------------------------------- ### Error handling with runDirMode Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/modes-dir.md Error handling example: checks if the directory exists before scanning, exits with code 1 if not, and catches any errors thrown by runDirMode, logging the error message. ```ts import { runDirMode } from './modes/dir'; import * as fs from 'fs'; const dir = './does-not-exist'; if (!fs.existsSync(dir)) { console.error(`Directory not found: ${dir}`); process.exit(1); } try { const profile = await runDirMode(dir); // ... } catch (err: any) { console.error(`scan failed: ${err.message}`); } ``` -------------------------------- ### Basic bundleFonts usage Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/font-resolver.md Basic usage example: calls bundleFonts with a single font source and additional families, then logs the bundled count and each updated source. The output shows a local path like 'fonts/InterRegular.ttf' when bundled. ```ts import { bundleFonts } from './font-resolver'; const { updatedSources, bundledCount } = await bundleFonts( [{ family: 'Inter', src: 'https://fonts.gstatic.com/.../inter.woff2', format: 'woff2', weight: '400' }], ['Inter', 'JetBrains Mono'], './my-design' ); console.log(`bundled ${bundledCount} font files`); for (const src of updatedSources) { console.log(`${src.family} ${src.weight} -> ${src.src}`); // 'fonts/InterRegular.ttf' when bundled } ``` -------------------------------- ### Generate skill without optional annotations Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/writers-skill.md Example of generating a skill package with null screenshot and null ultraResult. SKILL.md renders without Visual Reference or scroll-journey sections, but packaging still happens. ```ts import { generateSkill } from './writers/skill'; // null screenshot + null ultraResult: SKILL.md renders without // the Visual Reference / scroll-journey sections; packaging still happens const result = await generateSkill(profile, designMd, './out', null, null); ``` -------------------------------- ### Handling missing-Playwright fallback Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/modes-ultra.md Checks if Playwright is available and warns with install instructions if not. Calls runUltraMode with screens: 10, noting that result is empty but tokens and stubs are still written. ```typescript import { runUltraMode } from './modes/ultra'; import { loadPlaywright } from './playwright-loader'; if (!loadPlaywright()) { console.warn('Fix: npm install playwright && npx playwright install chromium'); } const result = await runUltraMode(url, profile, skillDir, { screens: 10 }); // result is fully empty ({ pageScreenshots: [], ... }) when Playwright is absent, // but tokens/*.json and stub reference files are still written ``` -------------------------------- ### Extract and log components with extractComponents Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-components.md Usage example for extractComponents and detectProjectLibraries. It extracts components from a Next.js app directory and logs the first five components' name, category, variants, props, and JSX snippet. This demonstrates the typical workflow of scanning a project for components. ```ts import { extractComponents, detectProjectLibraries } from './extractors/components'; const components = extractComponents('./my-nextjs-app'); for (const c of components.slice(0, 5)) { console.log(`${c.name} [${c.category}] variants=${c.variants.join(',')}`); console.log(` props: ${c.props.join(', ')}`); console.log(c.jsxSnippet); } ``` -------------------------------- ### Error-aware crawl with extractHttpCSSTokens Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-tokens-web.md Error-aware crawl example demonstrating that extractHttpCSSTokens never throws on invalid or unreachable targets. It checks if the result has zero colors and logs a message accordingly. ```ts import { extractHttpCSSTokens } from './extractors/tokens/http-css'; const result = await extractHttpCSSTokens('https://not-a-site.invalid', 2); // Never throws: invalid/unreachable targets yield empty tokens and components if (result.tokens.colors.length === 0) { console.log('No tokens extracted — target unreachable or returned no CSS'); } ``` -------------------------------- ### Check CLI exit code with echo $? Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/errors.md Shows how to observe the CLI exit code when a command fails. The example uses a URL and a directory together, which triggers exit code 1 because more than one of --dir, --repo, or --url is provided. ```bash skillui --url https://x.com --dir ./y; echo $? # 1 ``` -------------------------------- ### Error handling for runRepoMode Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/modes-repo.md Error handling example: an invalid or unreachable repository causes the promise to reject. The simple-git error propagates and the temporary directory is cleaned up automatically by the finally block before the error reaches the caller. ```ts import { runRepoMode } from './modes/repo'; try { const profile = await runRepoMode('https://github.com/not-a-real-org/nope.git'); } catch (err: any) { // simple-git error propagates; temp dir already removed by finally block console.error(`clone failed: ${err.message}`); } ``` -------------------------------- ### Usage with screenshot and Playwright degradation Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/modes-url.md Calls runUrlMode without a name override but with a skill directory for screenshot capture. Warns if Playwright is not installed, and logs the screenshot path or a fallback message. ```ts import { runUrlMode } from './modes/url'; const result = await runUrlMode('https://stripe.com', undefined, './stripe-design'); if (!result.hadPlaywright) { console.warn('Playwright not installed — computed style extraction skipped'); } // screenshotPath may still be set (microlink.io works without Playwright) console.log(result.screenshotPath ?? 'no screenshot captured'); ``` -------------------------------- ### Extract and log Tailwind, token file, and CSS tokens Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-tokens-local.md Use to extract design tokens from Tailwind config files, token files (theme.json/tokens.json), and CSS/SCSS/LESS files in a project using the extractors API. The snippet shows the import paths and how to access common properties like colors, breakpoints, and CSS variables, plus an example of logging them. ```ts import { extractTailwindTokens } from './extractors/tokens/tailwind'; import { extractCSSTokens } from './extractors/tokens/css'; import { extractTokensFile } from './extractors/tokens/tokens-file'; import { normalize } from './normalizer'; const tailwind = extractTailwindTokens('./app'); // from tailwind.config.* const tokenFile = extractTokensFile('./app'); // theme.json / tokens.json const css = extractCSSTokens('./app'); // every .css/.scss/.less console.log(tailwind.colors.length, 'tailwind colors'); console.log(css.breakpoints.map(b => `${b.name}:${b.value}`).join(', ')); console.log(tokenFile.cssVariables.length, 'token file css vars'); ``` -------------------------------- ### Clone-and-scan with --repo and --no-skill Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/cli.md Clones and scans a repository, skipping .skill packaging with --no-skill. ```bash skillui --repo https://github.com/vercel/next.js --name "Next.js" --no-skill ``` -------------------------------- ### Custom launcher using runInteractivePrompts Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Shows how to use runInteractivePrompts in a custom launcher. If answers is null, logs 'cancelled' and exits. Otherwise logs the extraction target and mode, and builds a CLI flag string based on the source type. ```ts import { runInteractivePrompts } from './ui'; const answers = await runInteractivePrompts(); if (!answers) { console.log('cancelled'); process.exit(0); } console.log(`extracting ${answers.target} with mode ${answers.mode}`); const out = ( answers.source === 'url' ? `--url ${answers.target}` : answers.source === 'dir' ? `--dir ${answers.target}` : `--repo ${answers.target}` ); ``` -------------------------------- ### Basic crawl with --url and --out Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/cli.md Runs the default static-analysis crawl on a URL, saving output to the specified directory. ```bash skillui --url https://linear.app --out ./design-systems ``` -------------------------------- ### Output directory structure Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Shows the directory tree generated by the tool, including the packaged .skill ZIP, markdown documentation, references, screenshots, tokens, and bundled fonts. ```text notion-design/ ├── notion-design.skill # Packaged .skill ZIP (contains everything) ├── SKILL.md # Master skill file (auto-loaded by Claude) ├── CLAUDE.md # Claude Code project context ├── DESIGN.md # Full design system tokens ├── references/ │ ├── 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 embedded in sequence ├── screens/ │ ├── scroll/ # 7 scroll journey screenshots │ ├── pages/ # Full-page screenshots (ultra) │ └── sections/ # Section clip screenshots (ultra) ├── tokens/ │ ├── colors.json │ ├── spacing.json │ └── typography.json └── fonts/ # Bundled Google Fonts (woff2) ``` -------------------------------- ### Run ultra mode Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Runs ultra mode, which uses Playwright to capture scroll screenshots, interaction diffs, animation detection, layout analysis, and DOM component fingerprinting. ```bash skillui --url https://linear.app --mode ultra ``` -------------------------------- ### Typical integration from CLI orchestration Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/modes-ultra.md Shows how to call runUltraMode after runUrlMode, passing the profile and options. Logs keyframes count, library names, and DOM component count. ```typescript import { runUltraMode } from './modes/ultra'; import { runUrlMode } from './modes/url'; const url = 'https://linear.app'; const skillDir = './linear-design'; const urlResult = await runUrlMode(url, 'Linear', skillDir); const ultraResult = await runUltraMode(url, urlResult.profile, skillDir, { screens: 5 }); console.log(ultraResult.animations.keyframes.length, 'keyframes'); console.log(ultraResult.animations.libraries.map(l => l.name).join(', ')); console.log(ultraResult.domComponents.length, 'DOM components'); ``` -------------------------------- ### loadPlaywright Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/playwright-loader.md Documentation for the loadPlaywright function, which resolves the optional playwright peer dependency from three possible installation locations. ```APIDOC ## loadPlaywright ### Description Resolves the optional `playwright` peer dependency from three possible installation locations. This is the single gateway every Playwright-based extractor uses; returning `null` triggers graceful degradation throughout the pipeline. ### Method Function call ### Endpoint `loadPlaywright()` ### Parameters None. ### Return Value `any | null` — the `playwright` CommonJS module object (with `chromium`, `browser.newContext`, etc.) or `null` when not resolvable. ### Resolution Order (try → fall through) 1. Standard `require('playwright')` — works when Playwright shares the CLI's `node_modules` tree. 2. `require(path.join(process.cwd(), 'node_modules', 'playwright'))` — covers a user-level install inside the project the CLI runs in. 3. Global npm prefix: `execSync('npm root -g', { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 })` then `require(path.join(globalRoot, 'playwright'))` — covers `npm install -g playwright`. Every step is wrapped in `try/catch { /* fall through */ }`; a 5-second timeout protects the `npm root -g` subprocess call. ### Usage Example ```ts import { loadPlaywright } from './playwright-loader'; const playwright = loadPlaywright(); if (!playwright) { console.warn('Playwright not installed — computed style extraction skipped'); console.warn('Fix: npm install playwright && npx playwright install chromium'); } else { const browser = await playwright.chromium.launch({ headless: true }); // ... browser automation await browser.close(); } ``` Direct guard before expensive work: ```ts import { loadPlaywright } from './playwright-loader'; import { captureInteractions } from './extractors/ultra/interactions'; const records = loadPlaywright() ? await captureInteractions('https://linear.app', './out') : []; // extractors already handle this, the guard is just an optimization console.log(records.length, 'interaction records'); ``` ``` -------------------------------- ### Ultra mode with --mode, --screens, --name Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/cli.md Uses ultra mode with Playwright, captures 10 screens, and names the skill 'Nothing'. ```bash skillui --url https://nothing.tech --mode ultra --screens 10 --name "Nothing" ``` -------------------------------- ### Run default mode Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Runs default mode, which performs pure static analysis to extract HTML, CSS, fonts, color tokens, spacing, and typography. Works on any site without a browser. ```bash skillui --url https://linear.app ``` -------------------------------- ### Spinner lifecycle with startSpinner, succeedSpinner, failSpinner Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Demonstrates the spinner lifecycle: startSpinner creates a spinner, succeedSpinner marks success with a message and detail, and failSpinner marks failure with an error message before rethrowing the error. ```ts import { startSpinner, succeedSpinner, failSpinner } from './ui'; const sp = startSpinner('Scanning...'); try { const result = await doWork(); succeedSpinner(sp, 'Scan complete', `${result.length} items`); } catch (e: any) { failSpinner(sp, 'Scan failed', e.message); throw e; } ``` -------------------------------- ### Run dir mode Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Runs dir mode, which scans local project files (.css, .scss, .ts, .tsx, .js, .jsx) for design tokens, Tailwind config, CSS variables, and component patterns. ```bash skillui --dir ./my-app ``` -------------------------------- ### runDirMode(projectDir, nameOverride?) Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/modes-dir.md Scans a local project directory and returns a normalized DesignProfile. It detects frameworks, libraries, tokens, components, and animations, then normalizes them into a single profile. ```APIDOC ## runDirMode(projectDir, nameOverride?) ### Description Scans a local project directory and returns a normalized DesignProfile. It orchestrates a deterministic pipeline of detection and extraction steps, merging raw tokens and normalizing the result. ### Method Function call (async) ### Signature ```ts export async function runDirMode(projectDir: string, nameOverride?: string): Promise ``` ### Parameters - **projectDir** (string) - Required - Absolute or relative path to the project root to scan. - **nameOverride** (string) - Optional - Project name; falls back to package.json `name`, then `path.basename` of the resolved dir (via `getProjectName`). ### Return Value `Promise` — the fully normalized design profile (`src/types.ts:3`). On success it carries `colors`, `typography`, `spacing`, `shadows`, `components`, `frameworks`, `animations`, etc. ### Pipeline (deterministic, in order) 1. `detectFrameworks(projectDir)` + `getProjectName(projectDir, nameOverride)`. 2. `detectProjectLibraries(projectDir)` → `{ iconLibrary, stateLibrary, animationLibrary }`. 3. Raw token extraction, merged with source priority: `extractTailwindTokens` → `extractTokensFile` → `extractCSSTokens` (merged via internal `mergeRawTokens`). 4. `extractComponents(projectDir)`. 5. Per-component token pass: `extractComponentTokens` scans each `jsxSnippet` for hex colors (`#RGB`/`#RRGGBB`, 4-digit hex expanded), incrementing frequency or appending with `source: 'component'`. 6. Animation token collection: `comp.animationDetails` prefixed with `framer-motion`, `spring:`, or `tw-animate-` are mapped to `AnimationToken`s of type `framer-motion`, `spring`, or `css-keyframe` respectively. 7. `normalize(projectName, frameworks, merged, components, libraries)`. ### Merge Semantics (`mergeRawTokens`, internal) - Colors dedupe by exact hex (`value`), merging `frequency`; first `name` wins. - Fonts dedupe by `family + size`. - Shadows, CSS variables, dark-mode vars, page sections dedupe by identity field. - Breakpoints dedupe by `value`; border radii, z-index, gradients, durations/easings dedupe as scalars. - `containerMaxWidth`: first non-null wins. - `fontVarMap`: `Object.assign` (later sources overwrite keys). ### Error Behavior Throws only if a file/dir read fails in an unguarded path; most extraction is internally guarded (`try/catch` returning empty `RawTokens`). The CLI wraps the call in a spinner and rethrows (`failSpinner` + `throw e`), terminating with exit code 1 (`src/cli.ts`). ### Usage Examples Basic scan with an explicit name: ```ts import { runDirMode } from './modes/dir'; const profile = await runDirMode('/path/to/my-app', 'MyApp'); console.log(`${profile.colors.length} colors, ${profile.typography.length} type tokens`); console.log(profile.designTraits.isDark ? 'dark theme' : 'light theme'); console.log(`spacing base: ${profile.spacing.base}px`); ``` Error handling when the directory is invalid: ```ts import { runDirMode } from './modes/dir'; import * as fs from 'fs'; const dir = './does-not-exist'; if (!fs.existsSync(dir)) { console.error(`Directory not found: ${dir}`); process.exit(1); } try { const profile = await runDirMode(dir); // ... } catch (err: any) { console.error(`scan failed: ${err.message}`); } ``` **Source:** `src/modes/dir.ts:12` (`runDirMode`), `:70` (`mergeRawTokens`), `:211` (`extractComponentTokens`). ``` -------------------------------- ### skillui commander program definition Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/cli.md Defines the `skillui` commander program with all CLI flags. Options include `--dir`, `--repo`, `--url`, `--out`, `--name`, `--no-skill`, `--format`, `--mode`, and `--screens`. Defaults are `'./'` for out, `'both'` for format, `'default'` for mode, and `'5'` for screens. ```typescript const program = new Command(); program .name('skillui') .description('Reverse-engineer design systems from any project. Pure static analysis — no AI, no API keys.') .version(VERSION) .option('--dir ', 'Scan a local project directory') .option('--repo ', 'Clone and scan a git repository') .option('--url ', 'Crawl a live website') .option('--out ', 'Output directory', './') .option('--name ', 'Override project name') .option('--no-skill', 'Output DESIGN.md only, skip .skill packaging') .option('--format ', 'Output format: design-md | skill | both', 'both') .option('--mode ', 'Extraction mode: default | ultra', 'default') .option('--screens ', 'Ultra mode: max pages to crawl (default: 5)', '5'); ``` -------------------------------- ### extractComputedTokens function signature Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-tokens-web.md Signature of the extractComputedTokens function. It takes a start URL and an optional maxPages parameter (default 5) and returns a Promise of RawTokens. The function is designed to be called after checking loadPlaywright() because it returns an empty skeleton when Playwright is unavailable. ```ts export async function extractComputedTokens(url: string, maxPages = 5): Promise { ``` -------------------------------- ### showResults Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Prints three boxen panels: Extraction Complete, Output files, and Next steps, based on the provided results data. ```APIDOC ## showResults ### Description Prints three `boxen` panels: "Extraction Complete" (colors, fonts, grid, components, animations, framework, dark mode, plus optional ultra rows), "Output files" (relative paths of `DESIGN.md` / `.skill`), and "Next steps" (`cd -design && claude`). ### Signature ```ts export function showResults(data: ResultsData): void ``` ### Parameters #### Request Body (data object) - **profile** (DesignProfile) - Required - Drives the extracted-count rows. - **animations** (FullAnimationResult) - Optional - Adds keyframes/scroll-frames/library/video rows when present. - **skillFilePath** (string) - Optional - Printed in the output-files box. - **designMdPath** (string) - Optional - Printed in the output-files box. - **projectName** (string) - Required - Used for the `.skill` filename display and next-steps `cd -design` hint. - **skillInstalled** (boolean) - Optional - Accepted but not rendered in any panel in the current implementation. ### Returns - **void** - No return value. ``` -------------------------------- ### skillui CLI flags Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Lists all CLI flags for the skillui command, including source selection (--url, --dir, --repo) and options like --mode ultra, --screens, --out, --name, --format, and --no-skill. ```text skillui --url Crawl a live website skillui --dir Scan a local project directory skillui --repo Clone and scan a git repository --mode ultra Enable cinematic extraction (requires Playwright) --screens Pages to crawl in ultra mode (default: 5, max: 20) --out Output directory (default: ./) --name Override the project name --format design-md|skill|both Output format (default: both) --no-skill Output DESIGN.md only, skip .skill packaging ``` -------------------------------- ### runInteractivePrompts interface and function signature Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Defines the InteractiveAnswers interface and the signature of runInteractivePrompts. The function dynamically imports 'prompts' and asks four questions: source (select: url/dir/repo), target (text, message depends on source), mode (select: default/ultra), and out (text, initial './'). onCancel calls process.exit(0). Returns null when source or target is missing, otherwise the answers object. ```ts export interface InteractiveAnswers { source: 'url' | 'dir' | 'repo'; target: string; mode: 'default' | 'ultra'; out: string; } export async function runInteractivePrompts(): Promise { ``` -------------------------------- ### Run repo mode Source: https://github.com/amaancoderx/npxskillui/blob/main/README.md Runs repo mode, which clones any public git repository and automatically runs dir mode on it. ```bash skillui --repo https://github.com/org/repo ``` -------------------------------- ### Using Ultra extractors with Playwright Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-ultra.md Shows how to use the Ultra extractors (captureAnimations, capturePageScreenshots, extractLayouts, detectDOMComponents) after ensuring Playwright is loaded via loadPlaywright(). Throws an error if Playwright is unavailable. Logs keyframes, scroll frame count, page slugs/file paths, section clip count, first layout selector, and DOM component names/instances. ```ts import { captureAnimations } from './extractors/ultra/animations'; import { detectDOMComponents } from './extractors/ultra/components-dom'; import { capturePageScreenshots } from './extractors/ultra/pages'; import { extractLayouts } from './extractors/ultra/layout'; import { loadPlaywright } from './playwright-loader'; if (!loadPlaywright()) throw new Error('Ultra extractors require Playwright'); const anim = await captureAnimations('https://linear.app', './output/design'); console.log(anim.keyframes.map(k => k.name), anim.scrollFrames.length); const { pages, sections } = await capturePageScreenshots('https://linear.app', './output/design', 5); console.log(pages.map(p => `${p.slug}: ${p.filePath}`)); console.log(sections.length, 'section clips'); const layouts = await extractLayouts('https://linear.app'); const dom = await detectDOMComponents('https://linear.app'); console.log(layouts[0]?.selector, dom.map(d => `${d.name}×${d.instances}`).join(', ')); ``` -------------------------------- ### showResults function and ResultsData interface Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/ui.md Defines the ResultsData interface and showResults function signature. Prints three boxen panels: 'Extraction Complete', 'Output files', and 'Next steps'. The skillInstalled property is accepted but not rendered in any panel. ```ts interface ResultsData { profile: DesignProfile; animations?: FullAnimationResult; skillFilePath?: string; designMdPath?: string; projectName: string; skillInstalled?: boolean; } export function showResults(data: ResultsData): void { ``` -------------------------------- ### Catch runRepoMode rejection Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/errors.md Demonstrates catching a rejection from runRepoMode. The error message is tested against a regex for ENOTFOUND or 'Could not read from remote repository' to detect an unreachable repository. ```ts import { runRepoMode } from './modes/repo'; try { await runRepoMode('https://github.com/nonexistent-org/nope.git'); } catch (err: any) { if (/ENOTFOUND|Could not read from remote repository/i.test(err.message)) { console.error('repo unreachable'); } } ``` -------------------------------- ### detectProjectLibraries function signature Source: https://github.com/amaancoderx/npxskillui/blob/main/_autodocs/api-reference/extractors-components.md Signature of the detectProjectLibraries function. It takes a project directory path and returns an object with iconLibrary, stateLibrary, and animationLibrary fields, each either a string label or null. The function reads package.json from the project root and uses a first-match-wins priority order for each category. ```ts export function detectProjectLibraries(projectDir: string): { iconLibrary: string | null; stateLibrary: string | null; animationLibrary: string | null; } { ```