Skip to content

balsm-health/website / .github/skills/impeccable

impeccable

Flagged

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

FileKindSize
SKILL.mdskill md19.2 KB
reference/adapt.mdmarkdown9.9 KB
reference/animate.mdmarkdown10.1 KB
reference/audit.mdmarkdown7.1 KB
reference/bolder.mdmarkdown6.3 KB
reference/brand.mdmarkdown10.2 KB
reference/clarify.mdmarkdown10.4 KB
reference/codex.mdmarkdown6.8 KB
reference/colorize.mdmarkdown13.2 KB
reference/craft.mdmarkdown11.7 KB
reference/critique.mdmarkdown35.4 KB
reference/delight.mdmarkdown9.5 KB
reference/distill.mdmarkdown5.5 KB
reference/document.mdmarkdown27.2 KB
reference/extract.mdmarkdown3.3 KB
reference/harden.mdmarkdown8.4 KB
reference/hooks.mdmarkdown7.4 KB
reference/init.mdmarkdown12.4 KB
reference/interaction-design.mdmarkdown6.4 KB
reference/layout.mdmarkdown8.5 KB
reference/live.mdmarkdown58.3 KB
reference/onboard.mdmarkdown7.6 KB
reference/optimize.mdmarkdown7.4 KB
reference/overdrive.mdmarkdown8.8 KB
reference/polish.mdmarkdown12.7 KB
reference/product.mdmarkdown3.7 KB
reference/quieter.mdmarkdown4.7 KB
reference/shape.mdmarkdown11.1 KB
reference/typeset.mdmarkdown13.9 KB
scripts/command-metadata.jsonconfig7.8 KB
scripts/context-signals.mjsscript7.9 KB
scripts/context.mjsscript10.3 KB
scripts/critique-storage.mjsscript8.8 KB
scripts/detect-csp.mjsscript6.6 KB
scripts/detect.mjsscript620 B
scripts/detector/browser/injected/index.mjsscript75.0 KB
scripts/detector/cli/main.mjsscript10.8 KB
scripts/detector/design-system.mjsscript24.1 KB
scripts/detector/detect-antipatterns-browser.jsscript211.7 KB
scripts/detector/detect-antipatterns.mjsscript1.8 KB
scripts/detector/engines/browser/detect-url.mjsscript9.7 KB
scripts/detector/engines/regex/detect-text.mjsscript23.9 KB
scripts/detector/engines/static-html/css-cascade.mjsscript33.6 KB
scripts/detector/engines/static-html/detect-html.mjsscript9.7 KB
scripts/detector/engines/visual/screenshot-contrast.mjsscript6.4 KB
scripts/detector/findings.mjsscript363 B
scripts/detector/node/file-system.mjsscript6.7 KB
scripts/detector/profile/profiler.mjsscript4.4 KB
scripts/detector/registry/antipatterns.mjsscript18.2 KB
scripts/detector/rules/checks.mjsscript113.1 KB
scripts/detector/shared/color.mjsscript4.4 KB
scripts/detector/shared/constants.mjsscript4.1 KB
scripts/detector/shared/page.mjsscript252 B
scripts/hook-admin.mjsscript22.8 KB
scripts/hook-before-edit.mjsscript16.2 KB
scripts/hook-lib.mjsscript54.7 KB
scripts/hook.mjsscript2.0 KB
scripts/lib/design-parser.mjsscript25.2 KB
scripts/lib/impeccable-config.mjsscript21.0 KB
scripts/lib/impeccable-paths.mjsscript3.8 KB
scripts/lib/is-generated.mjsscript2.2 KB
scripts/live-accept.mjsscript29.6 KB
scripts/live-browser-dom.jsscript4.2 KB
scripts/live-browser-session.jsscript3.2 KB
scripts/live-browser.jsscript423.7 KB
scripts/live-commit-manual-edits.mjsscript41.1 KB
scripts/live-complete.mjsscript2.9 KB
scripts/live-copy-edit-agent.mjsscript28.2 KB
scripts/live-discard-manual-edits.mjsscript1.6 KB
scripts/live-inject.mjsscript22.1 KB
scripts/live-insert.mjsscript8.9 KB
scripts/live-manual-edit-evidence.mjsscript11.4 KB
scripts/live-poll.mjsscript13.2 KB
scripts/live-resume.mjsscript4.4 KB
scripts/live-server.mjsscript41.5 KB
scripts/live-status.mjsscript2.1 KB
scripts/live-wrap.mjsscript35.1 KB
scripts/live.mjsscript8.3 KB
scripts/live/browser-script-parts.mjsscript1.7 KB
scripts/live/completion.mjsscript969 B
scripts/live/event-validation.mjsscript6.2 KB
scripts/live/insert-ui.mjsscript15.3 KB
scripts/live/manual-apply.mjsscript34.1 KB
scripts/live/manual-edit-routes.mjsscript14.6 KB
scripts/live/manual-edits-buffer.mjsscript5.0 KB
scripts/live/session-store.mjsscript10.4 KB
scripts/live/svelte-component.mjsscript27.2 KB
scripts/live/sveltekit-adapter.mjsscript9.1 KB
scripts/live/ui-core.mjsscript5.4 KB
scripts/live/vocabulary.mjsscript3.2 KB
scripts/modern-screenshot.umd.jsscript28.6 KB
scripts/palette.mjsscript56.9 KB
scripts/pin.mjsscript6.0 KB

scripts/detector/cli/main.mjs

View on GitHub
import fs from 'node:fs';
import path from 'node:path';

import { loadDesignSystemForCwd } from '../design-system.mjs';
import { createBrowserDetector, detectUrl } from '../engines/browser/detect-url.mjs';
import { detectHtml } from '../engines/static-html/detect-html.mjs';
import { detectText } from '../engines/regex/detect-text.mjs';
import {
  filterDetectionFindings,
  readDetectionConfig,
  shouldIgnoreDetectionFile,
} from '../../lib/impeccable-config.mjs';
import {
  HTML_EXTENSIONS,
  buildImportGraph,
  detectFrameworkConfig,
  isPortListening,
  walkDir,
} from '../node/file-system.mjs';

// ---------------------------------------------------------------------------
// Output formatting
// ---------------------------------------------------------------------------

function formatFindings(findings, jsonMode) {
  if (jsonMode) return JSON.stringify(findings, null, 2);

  const grouped = {};
  for (const f of findings) {
    if (!grouped[f.file]) grouped[f.file] = [];
    grouped[f.file].push(f);
  }
  const out = [];
  for (const [file, items] of Object.entries(grouped)) {
    const importNote = items[0]?.importedBy?.length ? ` (imported by ${items[0].importedBy.join(', ')})` : '';
    out.push(`\n${file}${importNote}`);
    for (const item of items) {
      out.push(`  ${item.line ? `line ${item.line}: ` : ''}[${item.antipattern}] ${item.snippet}`);
      out.push(`    → ${item.description}`);
    }
  }
  out.push(`\n${findings.length} anti-pattern${findings.length === 1 ? '' : 's'} found.`);
  return out.join('\n');
}

// ---------------------------------------------------------------------------
// Stdin handling
// ---------------------------------------------------------------------------

async function handleStdin(options = {}) {
  const chunks = [];
  for await (const chunk of process.stdin) chunks.push(chunk);
  const input = Buffer.concat(chunks).toString('utf-8');
  try {
    const parsed = JSON.parse(input);
    const fp = parsed?.tool_input?.file_path;
    if (fp && fs.existsSync(fp)) {
      return HTML_EXTENSIONS.has(path.extname(fp).toLowerCase())
        ? detectHtml(fp, options) : detectText(fs.readFileSync(fp, 'utf-8'), fp, options);
    }
  } catch { /* not JSON */ }
  return detectText(input, '<stdin>', options);
}


// ---------------------------------------------------------------------------
// CLI
// ---------------------------------------------------------------------------

async function confirm(question) {
  const rl = (await import('node:readline')).default.createInterface({
    input: process.stdin, output: process.stderr,
  });
  return new Promise((resolve) => {
    rl.question(`${question} [Y/n] `, (answer) => {
      rl.close();
      resolve(!answer || /^y(es)?$/i.test(answer.trim()));
    });
  });
}

function printUsage() {
  console.log(`Usage: impeccable detect [options] [file-or-dir-or-url...]

Scan files or URLs for UI anti-patterns and design quality issues.

Options:
  --json              Output results as JSON
  --gpt               Also report GPT-specific provider tells (off by default)
  --gemini            Also report Gemini-specific provider tells (off by default)
  --no-config         Do not apply project config, detector ignores, or DESIGN.md
  --no-design-system  Do not load local DESIGN.md / .impeccable/design.json context
  --help              Show this help message

Project config:
  Respects .impeccable/config.json and .impeccable/config.local.json detector
  settings: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues,
  and detector.designSystem.enabled.

Detection modes:
  HTML files     Static HTML/CSS analysis (default, catches linked CSS)
  Non-HTML files Regex pattern matching (CSS, JSX, TSX, etc.)
  URLs           Puppeteer full browser rendering (auto-detected)

Examples:
  impeccable detect src/
  impeccable detect index.html
  impeccable detect https://example.com
  impeccable detect --json .
  impeccable detect --no-config src/`);
}

async function detectCli() {
  let args = process.argv.slice(2).map(arg => {
    if (arg === '-json') return '--json';
    if (arg === '-fast') return '--fast';
    return arg;
  });
  if (args[0] === 'detect') args = args.slice(1);
  const jsonMode = args.includes('--json');
  const helpMode = args.includes('--help');
  // --fast (regex-only) is deprecated: since the jsdom removal, the static
  // HTML/CSS analysis is fast and covers every rule, so the regex-only path
  // only loses coverage for no real speed win. Accept the flag for back-compat
  // but ignore it and run the full scan.
  if (args.includes('--fast')) {
    process.stderr.write(
      'Note: --fast is deprecated and ignored. The full scan is fast now and runs every rule.\n',
    );
  }
  const configEnabled = !args.includes('--no-config');
  const detectionConfig = configEnabled
    ? readDetectionConfig(process.cwd())
    : { ignoreRules: [], ignoreFiles: [], ignoreValues: [] };
  const providers = [];
  if (args.includes('--gpt')) providers.push('gpt');
  if (args.includes('--gemini')) providers.push('gemini');
  const designSystemEnabled = configEnabled && !args.includes('--no-design-system') && detectionConfig.designSystem?.enabled !== false;
  const designSystem = designSystemEnabled ? loadDesignSystemForCwd(process.cwd()) : null;
  const scanOptions = designSystem ? { providers, designSystem } : { providers };
  const targets = args.filter(a => !a.startsWith('--'));

  if (helpMode) { printUsage(); process.exit(0); }

  let allFindings = [];

  if (!process.stdin.isTTY && targets.length === 0) {
    allFindings = await handleStdin(scanOptions);
  } else {
    const paths = targets.length > 0 ? targets : [process.cwd()];
    const urlTargetCount = paths.filter(target => /^https?:\/\//i.test(target)).length;
    const browserDetector = urlTargetCount > 1 ? await createBrowserDetector() : null;

    try {
      for (const target of paths) {
        if (/^https?:\/\//i.test(target)) {
          try {
            const scanner = browserDetector
              ? (url) => browserDetector.detectUrl(url, scanOptions)
              : (url) => detectUrl(url, scanOptions);
            allFindings.push(...await scanner(target));
          } catch (e) { process.stderr.write(`Error: ${e.message}\n`); }
          continue;
        }

        const resolved = path.resolve(target);
        let stat;
        try { stat = fs.statSync(resolved); }
        catch { process.stderr.write(`Warning: cannot access ${target}\n`); continue; }

        if (stat.isDirectory()) {
          // Check for framework dev server config (skip in JSON mode to avoid polluting output)
          if (!jsonMode) {
            const fwConfig = detectFrameworkConfig(resolved);
            if (fwConfig) {
              const probe = await isPortListening(fwConfig.port, fwConfig.fingerprint);
              if (probe.listening && probe.matched) {
                process.stderr.write(
                  `\n${fwConfig.name} dev server detected on localhost:${fwConfig.port}.\n` +
                  `For more accurate results, scan the running site:\n` +
                  `  npx impeccable detect http://localhost:${fwConfig.port}\n\n`
                );
              } else if (probe.listening && !probe.matched) {
                process.stderr.write(
                  `\n${fwConfig.name} project detected (${path.basename(fwConfig.configPath)}).\n` +
                  `Port ${fwConfig.port} is in use by another service. Start the ${fwConfig.name} dev server and scan via URL for best results.\n\n`
                );
              } else {
                process.stderr.write(
                  `\n${fwConfig.name} project detected (${path.basename(fwConfig.configPath)}).\n` +
                  `Start the dev server and scan via URL for best results:\n` +
                  `  npx impeccable detect http://localhost:${fwConfig.port}\n\n`
                );
              }
            }
          }

          const files = walkDir(resolved)
            .filter(file => !shouldIgnoreDetectionFile(file, process.cwd(), detectionConfig));
          const htmlCount = files.filter(f => HTML_EXTENSIONS.has(path.extname(f).toLowerCase())).length;

          // Warn and confirm if scanning many files (static HTML/CSS processes each HTML file)
          if (files.length > 50 && process.stdin.isTTY && !jsonMode) {
            process.stderr.write(
              `\nFound ${files.length} files (${htmlCount} HTML) in ${target}.\n` +
              `Scanning may take a while${htmlCount > 10 ? ' (static HTML/CSS processes each HTML file individually)' : ''}.\n` +
              `Target a specific subdirectory to narrow scope.\n`
            );
            const ok = await confirm('Continue?');
            if (!ok) { process.stderr.write('Aborted.\n'); process.exit(0); }
          }

          // Build import graph for multi-file awareness
          const graph = buildImportGraph(files);
          // Build reverse map: file -> set of files that import it
          const importedByMap = new Map();
          for (const [importer, imports] of graph) {
            for (const imported of imports) {
              if (!importedByMap.has(imported)) importedByMap.set(imported, new Set());
              importedByMap.get(imported).add(importer);
            }
          }

          for (const file of files) {
            const ext = path.extname(file).toLowerCase();
            let fileFindings;
            if (HTML_EXTENSIONS.has(ext)) {
              fileFindings = await detectHtml(file, scanOptions);
            } else {
              fileFindings = detectText(fs.readFileSync(file, 'utf-8'), file, scanOptions);
            }
            // Annotate findings with import context
            const importers = importedByMap.get(file);
            if (importers && importers.size > 0) {
              const importerNames = [...importers].map(f => path.basename(f));
              for (const f of fileFindings) {
                f.importedBy = importerNames;
              }
            }
            allFindings.push(...fileFindings);
          }
        } else if (stat.isFile()) {
          if (shouldIgnoreDetectionFile(resolved, process.cwd(), detectionConfig)) continue;
          const ext = path.extname(resolved).toLowerCase();
          if (HTML_EXTENSIONS.has(ext)) {
            allFindings.push(...await detectHtml(resolved, scanOptions));
          } else {
            allFindings.push(...detectText(fs.readFileSync(resolved, 'utf-8'), resolved, scanOptions));
          }
        }
      }
    } finally {
      if (browserDetector) await browserDetector.close();
    }
  }

  allFindings = filterDetectionFindings(allFindings, detectionConfig);

  if (allFindings.length > 0) {
    if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
    else process.stderr.write(formatFindings(allFindings, false) + '\n');
    process.exit(2);
  }
  if (jsonMode) process.stdout.write('[]\n');
  process.exit(0);
}

export { formatFindings, handleStdin, confirm, printUsage, detectCli };
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall