gholtzap/lintapple

lintapple – UI‑linting tool for developers

What it is – lintapple is a Node‑based command‑line utility that checks a web app’s user interface against a set of visual‑design rules you define in a ui‑policy.json file. It is meant to catch UI problems that an AI might otherwise generate, ensuring “it should be impossible for AI to make a bad UI”.

How you use it

1. Install it as a dev‑dependency (Node 22+). The init command scaffolds a ui‑policy.json file and adds a lint:ui npm script.
2. Run the script while your app is serving (default http://localhost:3000). The tool crawls the page, measures fonts, contrast, control sizes, spacing, alignment, corner radii, etc., and prints a list of findings.
3. Each finding shows the rule that was violated, the element involved, the measured value, and a suggested fix. Exit codes let CI know whether the run passed (0), found issues (1), or failed to complete (2).
4. You can output a JSON report (--json) or point the tool at a different URL.
5. For pages that load asynchronously you can tell lintapple when the page is ready with a CSS selector (--ready).

Integration with Playwright – A small helper (expectUI) can be imported in Playwright tests. After the page is ready, call await expectUI(page, testInfo). Any UI violations cause the test to fail and the JSON report is attached to the test output.

Markup helpers – Most checks work without extra markup, but you can add data attributes to give the linter more layout context:

• data-ui-stack, data-ui-actions, data-ui-container – groups for spacing checks.
• data-ui-number – numbers that should have equal‑width digits.
• data-ui-content – containers whose text must stay inside their bounds.
• data-ui-align / data-ui-align-item – alignment groups.
• data-ui-radius / data-ui-radius-inner – enforce consistent corner radii and inset relationships.

You can also configure controlContainers in the policy file to target existing button containers.

Why it matters – UI consistency is hard to enforce manually, especially when UI code is generated or modified by AI tools. lintapple gives developers an automated way to verify that visual standards (font sizes, contrast ratios, button sizes, alignment, etc.) are respected before code ships, and it plugs directly into existing test pipelines.

License – MIT.

---

All details are taken directly from the repository’s README.