Skip to content

ShipfoxHQ/shipfox / .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 md10.4 KB
reference/adapt.mdmarkdown10.1 KB
reference/adapt.native.mdmarkdown3.8 KB
reference/android.mdmarkdown3.2 KB
reference/animate.mdmarkdown4.7 KB
reference/audit.mdmarkdown7.7 KB
reference/audit.native.mdmarkdown8.2 KB
reference/bolder.mdmarkdown3.1 KB
reference/clarify.mdmarkdown4.5 KB
reference/colorize.mdmarkdown4.4 KB
reference/craft-floor.mdmarkdown3.7 KB
reference/craft.mdmarkdown555 B
reference/critique.mdmarkdown39.0 KB
reference/delight.mdmarkdown3.6 KB
reference/distill.mdmarkdown5.5 KB
reference/doctor.mdmarkdown4.6 KB
reference/document.mdmarkdown26.8 KB
reference/extract.mdmarkdown3.3 KB
reference/harden.mdmarkdown8.3 KB
reference/hooks.mdmarkdown11.6 KB
reference/init.mdmarkdown8.6 KB
reference/ios.mdmarkdown2.9 KB
reference/layout.mdmarkdown5.0 KB
reference/live-setup.mdmarkdown7.2 KB
reference/live.mdmarkdown34.8 KB
reference/new-work.mdmarkdown27.2 KB
reference/onboard.mdmarkdown7.6 KB
reference/operate.mdmarkdown4.0 KB
reference/optimize.mdmarkdown7.4 KB
reference/overdrive.mdmarkdown8.6 KB
reference/polish.mdmarkdown5.1 KB
reference/quieter.mdmarkdown4.7 KB
reference/routing.mdmarkdown2.8 KB
reference/shape.mdmarkdown3.5 KB
reference/typeset.mdmarkdown5.1 KB
reference/visualize.mdmarkdown10.2 KB
scripts/command-metadata.jsonconfig7.7 KB
scripts/concept-seed.mjsscript27.0 KB
scripts/context-signals.mjsscript14.0 KB
scripts/context.mjsscript58.4 KB
scripts/critique-storage.mjsscript7.9 KB
scripts/detect-csp.mjsscript6.6 KB
scripts/detect.mjsscript620 B
scripts/detector/browser/injected/index.mjsscript79.6 KB
scripts/detector/cli/main.mjsscript18.8 KB
scripts/detector/design-system.mjsscript34.3 KB
scripts/detector/detect-antipatterns-browser.jsscript358.1 KB
scripts/detector/detect-antipatterns.mjsscript1.8 KB
scripts/detector/engines/browser/detect-url.mjsscript14.1 KB
scripts/detector/engines/regex/detect-text.mjsscript34.5 KB
scripts/detector/engines/static-html/css-cascade.mjsscript42.7 KB
scripts/detector/engines/static-html/detect-html.mjsscript11.7 KB
scripts/detector/engines/visual/screenshot-contrast.mjsscript6.4 KB
scripts/detector/findings.mjsscript766 B
scripts/detector/node/file-system.mjsscript7.6 KB
scripts/detector/profile/profiler.mjsscript4.4 KB
scripts/detector/registry/antipatterns.mjsscript27.2 KB
scripts/detector/rules/checks.mjsscript246.3 KB
scripts/detector/shared/color.mjsscript4.4 KB
scripts/detector/shared/constants.mjsscript4.6 KB
scripts/detector/shared/fonts.mjsscript852 B
scripts/detector/shared/inline-ignores.mjsscript6.0 KB
scripts/detector/shared/page.mjsscript252 B
scripts/doctor.mjsscript11.6 KB
scripts/embed-prompt.mjsscript5.8 KB
scripts/generate-image.mjsscript9.6 KB
scripts/hook-admin.mjsscript28.4 KB
scripts/hook-before-edit.mjsscript18.3 KB
scripts/hook-lib.mjsscript81.4 KB
scripts/hook.mjsscript2.6 KB
scripts/lib/artifact-schema.mjsscript3.8 KB
scripts/lib/composition-catalog.mjsscript10.0 KB
scripts/lib/concept-catalog.mjsscript17.4 KB
scripts/lib/design-parser.mjsscript25.2 KB
scripts/lib/impeccable-config.mjsscript22.2 KB
scripts/lib/impeccable-paths.mjsscript4.9 KB
scripts/lib/is-generated.mjsscript2.2 KB
scripts/lib/provider.mjsscript327 B
scripts/lib/roll-selection.mjsscript16.9 KB
scripts/lib/staleness-deep.mjsscript19.6 KB
scripts/lib/staleness-notice.mjsscript6.5 KB
scripts/lib/staleness.mjsscript19.0 KB
scripts/lib/surface-briefs.mjsscript6.1 KB
scripts/lib/target-args.mjsscript1.1 KB
scripts/lib/target-slug.mjsscript1.0 KB
scripts/lib/template-extensions.mjsscript5.3 KB
scripts/live-accept.mjsscript35.5 KB
scripts/live-browser-dom.jsscript4.2 KB
scripts/live-browser-session.jsscript3.2 KB
scripts/live-browser.jsscript489.1 KB
scripts/live-commit-manual-edits.mjsscript41.2 KB
scripts/live-complete.mjsscript4.7 KB
scripts/live-copy-edit-agent.mjsscript28.2 KB
scripts/live-discard-manual-edits.mjsscript1.6 KB
scripts/live-inject.mjsscript18.1 KB
scripts/live-insert.mjsscript9.8 KB
scripts/live-manual-edit-evidence.mjsscript11.6 KB
scripts/live-poll.mjsscript15.7 KB
scripts/live-resume.mjsscript6.0 KB
scripts/live-server.mjsscript66.1 KB
scripts/live-status.mjsscript2.6 KB
scripts/live-target.mjsscript934 B
scripts/live-wrap.mjsscript38.2 KB
scripts/live.mjsscript13.1 KB
scripts/live/accept-css.mjsscript22.0 KB
scripts/live/accept-verify.mjsscript2.7 KB
scripts/live/browser-script-parts.mjsscript2.1 KB
scripts/live/completion.mjsscript1.4 KB
scripts/live/event-validation.mjsscript9.4 KB
scripts/live/frameworks/astro.mjsscript1.7 KB
scripts/live/frameworks/detect-utils.mjsscript2.1 KB
scripts/live/frameworks/index.mjsscript5.7 KB
scripts/live/frameworks/journal.mjsscript7.0 KB
scripts/live/frameworks/nextjs.mjsscript1.7 KB
scripts/live/frameworks/nuxt.mjsscript5.1 KB
scripts/live/frameworks/script-src.mjsscript699 B
scripts/live/frameworks/static-html.mjsscript656 B
scripts/live/frameworks/sveltekit.mjsscript1.8 KB
scripts/live/frameworks/tag-strategy.mjsscript10.6 KB
scripts/live/frameworks/tanstack-start.mjsscript1.6 KB
scripts/live/frameworks/vite-generic.mjsscript1.3 KB
scripts/live/generation-preflight.mjsscript5.8 KB
scripts/live/insert-ui.mjsscript15.3 KB
scripts/live/instructions.mjsscript12.9 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/poll-lanes.mjsscript759 B
scripts/live/roots.mjsscript20.4 KB
scripts/live/session-store.mjsscript22.4 KB
scripts/live/source-lock.mjsscript3.6 KB
scripts/live/source-search.mjsscript4.2 KB
scripts/live/svelte-ast.mjsscript37.7 KB
scripts/live/svelte-component.mjsscript49.6 KB
scripts/live/sveltekit-adapter.mjsscript11.1 KB
scripts/live/tanstack-adapter.mjsscript9.5 KB
scripts/live/ui-core.mjsscript5.4 KB
scripts/live/vocabulary.mjsscript7.0 KB
scripts/modern-screenshot.umd.jsscript28.6 KB
scripts/palette.mjsscript55.5 KB
scripts/pin.mjsscript6.3 KB
scripts/serve-question.mjsscript60.2 KB
scripts/surface-brief.mjsscript2.5 KB

scripts/detector/engines/browser/detect-url.mjs

View on GitHub
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

import { finding } from '../../findings.mjs';
import { profileFindingsAsync, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
import { captureVisualContrastCandidate } from '../visual/screenshot-contrast.mjs';
import { checkContentHiddenAtRest } from '../../rules/checks.mjs';

// On Windows, puppeteer's bundled Chrome lives in a user-writable cache
// directory. Its GPU process can be denied (STATUS_ACCESS_DENIED) by security
// software or the GPU sandbox because it launches from an untrusted path.
// Chrome then crash-loops the GPU process, and each relaunch briefly flashes a
// compositor surface, the black window users report during `detect <url>`
// (issue #372). The system-installed Chrome runs from a trusted location with a
// healthy GPU, so channel:'chrome' avoids the crash entirely; both use hardware
// GPU, so contrast measurement is unaffected. Scope this to Windows only: other
// platforms do not have the bug, so they keep the pinned bundled build for
// consistent measurement across machines. Fall back to bundled when the switch
// fails (Chrome not installed, or channel resolution fails). If the bundled
// launch then also fails, surface the original system-Chrome error as the
// cause so the real failure is not lost.
async function launchBrowser(puppeteer, { headless = true, args = [] } = {}) {
  let channelError;
  if (process.platform === 'win32') {
    try {
      return await puppeteer.default.launch({ channel: 'chrome', headless, args });
    } catch (err) {
      // System Chrome unavailable or unlaunchable; fall through to the bundled
      // browser, but keep the error in case the fallback fails too.
      channelError = err;
    }
  }
  try {
    return await puppeteer.default.launch({ headless, args });
  } catch (err) {
    if (channelError && err && err.cause === undefined) err.cause = channelError;
    throw err;
  }
}

// Reveal sweep + invisible-text measurement for the content-hidden-at-rest
// rule. Scrolls through the document with instant jumps (bypasses CSS
// scroll-behavior: smooth) so IntersectionObserver / scroll reveal handlers
// get every chance to fire, returns to the top, lets transitions settle,
// then measures how much text still renders invisible. A healthy
// reveal-on-scroll page drops to ~0 after the sweep; a page whose reveal
// script died keeps most of its text at opacity 0.
async function measureContentHiddenAfterReveal(page) {
  await page.evaluate(async () => {
    const step = Math.max(200, Math.floor(window.innerHeight * 0.7));
    const max = Math.max(
      document.documentElement.scrollHeight || 0,
      document.body?.scrollHeight || 0,
    );
    for (let y = 0; y <= max; y += step) {
      window.scrollTo({ top: y, left: 0, behavior: 'instant' });
      await new Promise(resolve => requestAnimationFrame(() => setTimeout(resolve, 40)));
    }
    window.scrollTo({ top: 0, left: 0, behavior: 'instant' });
    await new Promise(resolve => setTimeout(resolve, 700));
  });
  return page.evaluate(() => {
    if (typeof window.impeccableMeasureHiddenText !== 'function') return null;
    return window.impeccableMeasureHiddenText();
  });
}

function serializeDesignSystemForBrowser(designSystem) {
  if (!designSystem?.present) return null;
  return {
    present: true,
    hasFonts: designSystem.hasFonts === true,
    allowedFonts: Array.from(designSystem.allowedFonts || []),
    hasColors: designSystem.hasColors === true,
    allowedColors: Array.from(designSystem.allowedColorKeys?.values?.() || [])
      .map(entry => entry?.color)
      .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
      .map(color => ({ r: color.r, g: color.g, b: color.b })),
    hasRadii: designSystem.hasRadii === true,
    allowedRadii: (designSystem.allowedRadii || [])
      .map(entry => Number(entry?.px))
      .filter(px => Number.isFinite(px)),
    hasPillRadius: designSystem.hasPillRadius === true,
  };
}

async function runVisualContrastFallback(page, serializedGroups, options, profile, target) {
  if (options?.visualContrast === false) return [];
  const maxCandidates = Number.isFinite(options?.visualContrastMaxCandidates)
    ? options.visualContrastMaxCandidates
    : 12;
  const scrollOffscreen = options?.visualContrastScrollOffscreen !== false;
  const existingLowContrastSelectors = new Set(
    serializedGroups
      .filter(group => group.findings?.some(f => f.type === 'low-contrast'))
      .map(group => group.selector)
      .filter(Boolean)
  );

  let browserAnalyses = [];
  const findings = [];
  if (options?.visualContrastBrowser !== false) {
    const browserFindings = await profileFindingsAsync(profile, {
      engine: 'browser',
      phase: 'visual-contrast',
      ruleId: 'browser-fallback',
      target,
    }, async () => {
      browserAnalyses = await page.evaluate(async ({ maxCandidates, scrollOffscreen }) => {
        if (typeof window.impeccableAnalyzeVisualContrast !== 'function') return [];
        return window.impeccableAnalyzeVisualContrast({ maxCandidates, scrollOffscreen });
      }, { maxCandidates, scrollOffscreen });
      return browserAnalyses
        .filter(result => result.finding && !existingLowContrastSelectors.has(result.selector))
        .map(result => result.finding);
    });
    findings.push(...browserFindings);
  }

  let candidates = browserAnalyses.length > 0 ? browserAnalyses : [];
  if (candidates.length === 0) {
    candidates = await profileStepAsync(profile, {
      engine: 'browser',
      phase: 'visual-contrast',
      ruleId: 'collect-candidates',
      target,
    }, () => page.evaluate(({ maxCandidates }) => {
      if (typeof window.impeccableCollectVisualContrastCandidates !== 'function') return [];
      return window.impeccableCollectVisualContrastCandidates({ maxCandidates });
    }, { maxCandidates }));
  }

  const viewport = options?.viewport || { width: 1280, height: 800 };
  const browserResolvedSelectors = new Set(
    browserAnalyses
      .filter(result => result.status === 'fail' || result.status === 'pass')
      .map(result => result.selector)
      .filter(Boolean)
  );
  const filtered = candidates.filter(candidate =>
    !existingLowContrastSelectors.has(candidate.selector) &&
    !browserResolvedSelectors.has(candidate.selector)
  );
  if (options?.visualContrastPixel === false) return findings;
  for (const candidate of filtered) {
    const result = await profileFindingsAsync(profile, {
      engine: 'browser',
      phase: 'visual-contrast',
      ruleId: 'pixel-diff',
      target,
    }, async () => {
      const finding = await captureVisualContrastCandidate(page, candidate, viewport);
      return finding ? [finding] : [];
    });
    findings.push(...result);
  }
  return findings;
}

// ---------------------------------------------------------------------------
// Puppeteer detection (for URLs)
// ---------------------------------------------------------------------------

async function detectUrl(url, options = {}) {
  const profile = options?.profile;
  const waitUntil = options?.waitUntil || 'networkidle0';
  const settleMs = Number.isFinite(options?.settleMs) ? options.settleMs : 0;
  const viewport = options?.viewport || { width: 1280, height: 800 };
  const externalBrowser = options?.browser || null;
  let puppeteer;
  if (!externalBrowser) {
    try {
      puppeteer = await profileStepAsync(profile, {
        engine: 'browser',
        phase: 'setup',
        ruleId: 'import-puppeteer',
        target: url,
      }, () => import('puppeteer'));
    } catch {
      throw new Error('puppeteer is required for URL scanning. Install: npm install puppeteer');
    }
  }

  // Read the browser detection script — reuse it instead of reimplementing
  const browserScriptPath = path.resolve(
    path.dirname(fileURLToPath(import.meta.url)),
    '..',
    '..',
    'detect-antipatterns-browser.js'
  );
  let browserScript;
  try {
    browserScript = profileStep(profile, {
      engine: 'browser',
      phase: 'setup',
      ruleId: 'read-browser-script',
      target: url,
    }, () => fs.readFileSync(browserScriptPath, 'utf-8'));
  } catch {
    throw new Error(`Browser script not found at ${browserScriptPath}`);
  }

  // CI runners (GitHub Actions Ubuntu) block unprivileged user namespaces, so
  // Chrome can't initialize its sandbox there. Disable the sandbox only when
  // running in CI; local users keep the default hardened launch.
  const launchArgs = process.env.CI ? ['--no-sandbox', '--disable-setuid-sandbox'] : [];
  const browser = externalBrowser || await profileStepAsync(profile, {
    engine: 'browser',
    phase: 'load',
    ruleId: 'launch-browser',
    target: url,
  }, () => launchBrowser(puppeteer, { headless: options?.headless ?? true, args: launchArgs }));
  const page = await profileStepAsync(profile, {
    engine: 'browser',
    phase: 'load',
    ruleId: 'new-page',
    target: url,
  }, () => browser.newPage());

  // Uncaught exceptions and parse errors surface as pageerror events. The
  // listener must attach before goto: a syntax error fires during the
  // initial parse, long before the load event. Dedupe by message; a single
  // broken loop can otherwise throw hundreds of identical errors.
  const pageErrors = [];
  if (options?.scriptErrors !== false) {
    page.on('pageerror', (err) => {
      const message = String(err?.message || err).split('\n')[0].trim().slice(0, 160);
      if (message && !pageErrors.includes(message)) pageErrors.push(message);
    });
  }

  let results = [];
  try {
    await profileStepAsync(profile, {
      engine: 'browser',
      phase: 'load',
      ruleId: 'set-viewport',
      target: url,
    }, () => page.setViewport(viewport));
    await profileStepAsync(profile, {
      engine: 'browser',
      phase: 'load',
      ruleId: `goto:${waitUntil}`,
      target: url,
    }, () => page.goto(url, { waitUntil, timeout: 30000 }));
    if (settleMs > 0) {
      await profileStepAsync(profile, {
        engine: 'browser',
        phase: 'load',
        ruleId: 'settle',
        target: url,
      }, () => new Promise(resolve => setTimeout(resolve, settleMs)));
    }

    // Inject the browser detection script and collect results
    const browserDesignSystem = serializeDesignSystemForBrowser(options?.designSystem);
    await profileStepAsync(profile, {
      engine: 'browser',
      phase: 'scan',
      ruleId: 'configure-pure-detect',
      target: url,
    }, () => page.evaluate((designSystem) => {
      window.__IMPECCABLE_CONFIG__ = {
        ...(window.__IMPECCABLE_CONFIG__ || {}),
        autoScan: false,
        ...(designSystem ? { designSystem } : {}),
      };
    }, browserDesignSystem));
    await profileStepAsync(profile, {
      engine: 'browser',
      phase: 'scan',
      ruleId: 'inject-browser-script',
      target: url,
    }, () => page.evaluate(browserScript));
    let serializedGroups = [];
    results = await profileFindingsAsync(profile, {
      engine: 'browser',
      phase: 'scan',
      ruleId: 'browser-scan',
      target: url,
    }, async () => {
      serializedGroups = await page.evaluate(() => {
        if (!window.impeccableDetect) return [];
        return window.impeccableDetect({ decorate: false, serialize: true });
      });
      return serializedGroups.flatMap(({ findings }) =>
        findings.map(f => ({ id: f.type, snippet: f.detail, ignoreValue: f.ignoreValue || '', severity: f.severity || '' }))
      );
    });
    // Content invisible at rest: reveal sweep, then re-measure. Runs after
    // the main scan (which must see the true at-rest state) and before the
    // visual contrast fallback (the sweep restores scroll to the top).
    if (options?.contentHidden !== false) {
      const hiddenFindings = await profileFindingsAsync(profile, {
        engine: 'browser',
        phase: 'scan',
        ruleId: 'content-hidden-at-rest',
        target: url,
      }, async () => {
        const measured = await measureContentHiddenAfterReveal(page);
        return measured ? checkContentHiddenAtRest(measured) : [];
      });
      results.push(...hiddenFindings);
    }

    for (const message of pageErrors.slice(0, 3)) {
      results.push({ id: 'script-error', snippet: message });
    }

    const visualFindings = await runVisualContrastFallback(page, serializedGroups, options, profile, url);
    results.push(...visualFindings);
  } finally {
    await profileStepAsync(profile, {
      engine: 'browser',
      phase: 'load',
      ruleId: 'close-page',
      target: url,
    }, () => page.close().catch(() => {}));
    if (!externalBrowser) {
      await profileStepAsync(profile, {
        engine: 'browser',
        phase: 'load',
        ruleId: 'close-browser',
        target: url,
      }, () => browser.close());
    }
  }
  return results.map(f => {
    const item = finding(f.id, url, f.snippet);
    if (f.ignoreValue) item.ignoreValue = f.ignoreValue;
    // Per-finding severity promotion (e.g. hero-region pulsing dot)
    // overrides the registry default carried by finding().
    if (f.severity && f.severity !== item.severity) item.severity = f.severity;
    return item;
  });
}

async function createBrowserDetector(options = {}) {
  let puppeteer;
  try {
    puppeteer = await import('puppeteer');
  } catch {
    throw new Error('puppeteer is required for URL scanning. Install: npm install puppeteer');
  }
  const launchArgs = options.launchArgs || (process.env.CI ? ['--no-sandbox', '--disable-setuid-sandbox'] : []);
  const browser = options.browser || await launchBrowser(puppeteer, {
    headless: options.headless ?? true,
    args: launchArgs,
  });
  const ownsBrowser = !options.browser;
  const defaults = {
    waitUntil: options.waitUntil || 'load',
    settleMs: Number.isFinite(options.settleMs) ? options.settleMs : 100,
    viewport: options.viewport || { width: 1280, height: 800 },
  };
  return {
    browser,
    async detectUrl(url, scanOptions = {}) {
      return detectUrl(url, {
        ...defaults,
        ...scanOptions,
        browser,
      });
    },
    async close() {
      if (ownsBrowser) await browser.close().catch(() => {});
    },
  };
}

export { runVisualContrastFallback, detectUrl, createBrowserDetector, launchBrowser };
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