Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(tooling): add lintapple UI lint with a repo policy and a lint:ui script so layout, contrast and ARIA regressions are checkable against a running page

nirholas568162d8d90e
diff --git a/docs/ui-lint.md b/docs/ui-lint.md
new file mode 100644
index 000000000..c93990d0c
--- /dev/null
+++ b/docs/ui-lint.md
@@ -0,0 +1,17 @@
+# UI lint (lintapple)
+
+[lintapple](https://github.com/gholtzap/lintapple) loads a running page in a browser and checks it against `ui-policy.json` at the repo root: font family and size, contrast, control size and gaps, viewport overflow, content clipping, root background, and ARIA state.
+
+```
+npm run dev # app on :3000
+npx lintapple http://localhost:3000/gallery --ready main
+npm run lint:ui # same, against the home URL
+```
+
+Exit codes: 0 pass, 1 findings, 2 the check could not finish (pages over 5000 elements, such as `/marketplace`, need a component-level target).
+
+## Notes
+
+- The policy ships with Apple system fonts and a 12 to 64px type scale. three.ws uses Inter, Space Grotesk and JetBrains Mono and a denser scale, so the font and size rules are noisy until the policy is tuned to our design tokens. The rules that carry signal today are `viewport-bounds`, `content-clipping`, `control-gap`, `root-background` and `control-state`.
+- The home page is a windowed-desktop canvas with a plain HTML fallback behind it. Lint content pages (`/gallery`, `/create`) and pass `--ready` so the app has mounted.
+- A passing run means the configured rules held. It is not a design review.
diff --git a/package-lock.json b/package-lock.json
index e5bca1b3e..355dd377b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -264,6 +264,7 @@
"i18n-iso-countries": "^7.14.0",
"jsdom": "30.0.1",
"json5": "^2.2.3",
+ "lintapple": "^0.1.20",
"playwright": "^1.63.0",
"prettier": "^3.9.8",
"puppeteer": "^25.10.0",
@@ -42464,6 +42465,34 @@
"version": "1.2.4",
"license": "MIT"
},
+ "node_modules/lintapple": {
+ "version": "0.1.20",
+ "resolved": "https://registry.npmjs.org/lintapple/-/lintapple-0.1.20.tgz",
+ "integrity": "sha512-n5wXJQci3ygYTvTI5eyX4otVVkOzEpkZnH5b+PBtciivnROaH4ZhDmb4nBeJ8Nhbm+SXggRLrccIShmqOSHV8w==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "axe-core": "4.14.0",
+ "playwright": "1.63.0"
+ },
+ "bin": {
+ "lintapple": "bin/lintapple.js",
+ "ui-lint": "bin/lintapple.js"
+ },
+ "engines": {
+ "node": ">=22"
+ }
+ },
+ "node_modules/lintapple/node_modules/axe-core": {
+ "version": "4.14.0",
+ "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.14.0.tgz",
+ "integrity": "sha512-9WTZxEjsZ7b13TH8JPmbV2z8CHbl80/2hm3XPEG4JgNdQLK81IBRXmSxHfMAOkSqQeRxT/0dwNDz2GOm3zzpcQ==",
+ "dev": true,
+ "license": "MPL-2.0",
+ "engines": {
+ "node": ">=4"
+ }
+ },
"node_modules/listenercount": {
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/listenercount/-/listenercount-1.0.1.tgz",
diff --git a/package.json b/package.json
index e8fc3e2e0..f580c9e83 100644
--- a/package.json
+++ b/package.json
@@ -427,6 +427,7 @@
"format:check": "prettier --check .",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
+ "lint:ui": "lintapple http://localhost:3000",
"check:dist": "node scripts/check-dist.mjs",
"check:pages": "node scripts/check-pages.mjs",
"check:tutorials": "node scripts/sync-tutorial-pages.mjs",
@@ -741,6 +742,7 @@
"i18n-iso-countries": "^7.14.0",
"jsdom": "30.0.1",
"json5": "^2.2.3",
+ "lintapple": "^0.1.20",
"playwright": "^1.63.0",
"prettier": "^3.9.8",
"puppeteer": "^25.10.0",
diff --git a/ui-policy.json b/ui-policy.json
new file mode 100644
index 000000000..654bd6bbe
--- /dev/null
+++ b/ui-policy.json
@@ -0,0 +1,85 @@
+{
+ "fonts": [
+ "Inter",
+ "system-ui",
+ "-apple-system",
+ "BlinkMacSystemFont",
+ "SF Pro Text",
+ "SF Pro Display"
+ ],
+ "fontSizes": [
+ 12,
+ 14,
+ 16,
+ 18,
+ 20,
+ 24,
+ 32,
+ 40,
+ 48,
+ 64
+ ],
+ "typeRules": [
+ {
+ "selector": "h1",
+ "sizes": [
+ 24,
+ 32,
+ 40,
+ 48,
+ 64
+ ]
+ },
+ {
+ "selector": "h2",
+ "sizes": [
+ 20,
+ 24,
+ 32
+ ]
+ },
+ {
+ "selector": "h3",
+ "sizes": [
+ 18,
+ 20,
+ 24
+ ]
+ },
+ {
+ "selector": "button, [role=button]",
+ "sizes": [
+ 14,
+ 16
+ ]
+ }
+ ],
+ "minControlSize": 15,
+ "controlSizeRules": [],
+ "minControlGap": 8,
+ "minControlInset": 8,
+ "controlContainers": [
+ "[data-ui-container]"
+ ],
+ "minLayoutGap": 8,
+ "bannedCopy": [
+ "unlock your potential",
+ "seamlessly",
+ "game-changing"
+ ],
+ "viewports": [
+ {
+ "width": 390,
+ "height": 844
+ },
+ {
+ "width": 1440,
+ "height": 900
+ }
+ ],
+ "colorSchemes": [
+ "light",
+ "dark"
+ ],
+ "exceptions": []
+}