Interface Proof

A local UI quality gate that helps AI coding agents catch frontend polish, accessibility, and responsive issues before review.

Interface Proof is for developers, indie hackers, AI app builders, and Codex users who generate or refactor frontend code and need a fast sanity gate before asking a human to review screenshots.

Problem

AI-generated frontends often look plausible in a single preview but fail in the details: missing labels, icon buttons without names, desktop-only layout, weak focus states, generic card styling, one-note palettes, placeholder copy, and text that breaks on mobile.

Interface Proof gives agents a deterministic pre-review gate so the obvious issues are fixed before visual review.

Features

• Static audit for HTML, CSS, JSX, TSX, JS, and TS files.
• Checks accessibility basics: language, alt text, input labels, button names, heading order.
• Checks responsive readiness: viewport metadata, fluid layout signals, fixed-width traps.
• Checks polish signals: focus states, negative letter spacing, extreme radii, placeholder copy, one-hue palettes.
• Generates Markdown or JSON reports with Codex remediation prompts.
• Includes screenshot review checklist and realistic mockups.
• No API key, no browser, no runtime dependencies.

Quick Start

npm install
npm test
node src/cli.mjs audit examples/sample-app --out validation/sample-app-report.md

Generate the standalone checklist:

node src/cli.mjs checklist --out docs/VISUAL_CHECKLIST.md

Example Workflow

1. Ask Codex to implement or polish a frontend change.
2. Run Interface Proof against the app or component folder.
3. Fix the highest-severity findings.
4. Capture desktop, small-laptop, and mobile screenshots.
5. Include the report and screenshot notes in the PR or delivery packet.

Use With Codex

Tell Codex:

Read AGENTS.md, docs/USAGE.md, and docs/VISUAL_CHECKLIST.md. Run Interface Proof against the frontend folder, fix the highest-severity findings, then describe which screenshots still need human review.

Files Codex should read first:

• AGENTS.md
• docs/USAGE.md
• docs/VISUAL_CHECKLIST.md
• docs/PREMIUM_UI_PRINCIPLES.md
• src/core.mjs

Commands Codex should run:

npm test
node src/cli.mjs audit examples/sample-app --out validation/sample-app-report.md

Expected outputs:

• UI quality score.
• Findings with file evidence.
• Markdown report with remediation prompt.
• Screenshot checklist for human review.

Codex should not:

• Replace the design system to satisfy a small finding.
• Claim visual approval without screenshots.
• Make broad rewrites when targeted fixes are enough.

Example Prompts

Use Interface Proof to audit this frontend change and fix only the findings that affect accessibility, responsiveness, or obvious polish.

Run the UI quality gate, generate the report, and prepare a screenshot checklist for desktop and mobile review.

Review this AI-generated landing page for generic UI patterns, missing labels, fixed-width layout, and keyboard focus issues.

Folder Structure

interface-proof/
  src/                 CLI and audit engine
  tests/               Node test suite
  docs/                Setup, usage, architecture, checklist, roadmap
  examples/            Sample app and before/after review notes
  validation/          Generated audit reports
  screenshots/         Report mockup
  mockups/             Example UI mock screenshots

Configuration

The MVP is convention-driven and does not require a config file. Use --threshold to choose the minimum passing score:

node src/cli.mjs audit examples/sample-app --threshold 85

Future versions may support interface-proof.config.json for project-specific design tokens, ignored paths, and scoring weights.

Output Example

review-ready: 88/100 (2 findings)

Markdown reports include:

• Score and grade.
• Findings grouped by category.
• Screenshot review checklist.
• Codex remediation prompt.

Roadmap

• Playwright screenshot capture and viewport automation.
• Optional Lighthouse/axe integration.
• Design-token config for Tailwind and CSS variables.
• GitHub Action annotation output.
• Before/after report comparison.

License

MIT. See LICENSE.