First-Principles UI

Deterministic UI Layout, Contrast, Typography & Spatial-Density Verifier A bi-directional neuro-symbolic engine and AI agent skill that eliminates generative frontend slop.

The AI Slop Problem  •  Core Invariants  •  3-Step Closed Loop  •  Benchmarks  •  56 Laws  •  Quickstart  •  Agent Setup

Why AI UI Defaults to "Slop"

Language models generate interfaces sequentially from token probabilities, completely blind to 2D spatial physics, optical weight, and physical touch ergonomics. Without mathematical constraints, agents chronically output five predictable flaws:

• Hierarchy Flatness: 3 identical boxes side-by-side with equal visual weight ($D_{\text{Zipf}} < 0.48$), forcing random eye saccades.
• Shannon Garnish: Repetitive green "Active" or "Popular" badges on every card, reducing information entropy to zero.
• Boundary Energy Stacking: Thick 2px borders stacked on top of outer drop-shadows and colored accent bars ($E_b > 1.25$).
• Washed-Out Contrast: Dim #8b9098 body text failing APCA readability ($|L_c| < 75$) or raw saturated neons causing chromatic glare.
• Mobile Viewport Crushing: Desktop grids crushing cards below 145px on mobile, flex blowouts, and 13px inputs triggering forced iOS Safari auto-zoom.

First-Principles UI replaces heuristic guessing with 56 automated mathematical laws across 25 topic detectors, combining sub-15ms forward calculation oracles with in-page Playwright geometry verification.

The Core Invariants

| Invariant | Empirical Law | What Base Agents Output | What First-Principles UI Enforces | | :--- | :--- | :--- | :--- | | Visual Hierarchy | Zipf–Lorenz Power-Law Anchor | 3 equal-sized boxes ($D_{\text{Zipf}} < 0.48$) | Dominant flagship hero anchor commanding $\ge 35%\text{--}48%$ stage area | | Boundary Physics | 4-Edge Energy Exclusivity ($E_b$) | Borders stacked on heavy drop-shadows ($E_b > 1.25$) | Single hairline elevation ($E_b \le 1.00$) & concentric inner radii ($r_{\text{in}} = r_{\text{out}} - \text{pad}$) | | Perceptual Contrast | W3C APCA & OKLCH Perceptual Scale | Washed out #8b9098 text ($|L_c| < 45$) | Calibrated tokens ($|L_c| \ge 75$ body / $\ge 60$ secondary) + dark-mode GRAD -25 | | Touch Ergonomics | Fitts's Law & iOS Input Zoom Floor | 28px buttons and 13px inputs | $\ge 36\times 36\text{px}$ targets (44px recommended) + 16px mobile input floor | | Subtractive Copy | Rachel's 4-Rung Ladder (LAW_32) | Worry-planting & label-restating captions | Deletes defensive hedging, scar tissue, and zero-bit helper fluff from the DOM |

The 3-Step Closed Loop

Step 1: Pre-Flight Forward Math (< 15ms, Zero-Browser)

Before writing any HTML, CSS, or SVG, agents solve non-linear perceptual equations using pure Node calculators:

# Foundation scaffold with pre-cleared dual-theme tokens
node check-ui-math.mjs init --mode workspace --primary-hue 250

# Solve dual-theme OKLCH/APCA tokens with native Tailwind CSS v4 @theme export
node check-ui-math.mjs calc palette --primary-hue 250 --export tailwind >> src/app/globals.css

# Solve Bento grid tracks, Zipf area distribution, and mobile card floors
node check-ui-math.mjs calc layout --mode workspace --regions 3 --bento-cells 4

# Solve W3C interruptible spring physics (stiffness, damping, duration)
node check-ui-math.mjs calc spring --intent gesture-release --velocity 800

Step 2: Build with 7 Core Invariants & Progressive L1 References

Agents construct layouts guided by the compact SKILL.md (capped at 46 lines to avoid context window pollution), loading at most one progressive reference when specialized domains arise:

• charts-data-viz.md: Zero-baseline bars (LAW_20), bubble area $\sqrt{v}$ (LAW_21), CVD separability (LAW_24), spaghetti cap $\le 5$ (LAW_25).
• motion-and-gestures.md: GPU properties (LAW_05), command palette gate (LAW_29), interruptible springs (LAW_30), FLIP uniform scale (LAW_31).
• stress-and-mobile.md: 100dvh, flex text min-width: 0, card floor $\ge 145\text{px}$ (LAW_18), media aspect ratio (LAW_27), hover gating (LAW_28).
• tables-and-forms.md: .table-scroll, right-aligned tabular-nums (LAW_16), 16px iOS input floor (LAW_18), Rachel's 4-Rung Ladder (LAW_32).
• typography-and-orthography.md: Log tracking $\tau(s)$ (LAW_13), Sentence case UI (LAW_33), smart quotes, non-breaking unit spaces.

Step 3: In-Page Verification & Lexicographical Auto-Repair

node check-ui-math.mjs http://localhost:3000 --agent-loop --fix ./src

• Micro-Orthography Auto-Fixer: Fixes straight quotes, ASCII hyphens, unit spaces, and decorative AI emojis in <40ms with zero LLM tokens.
• Lexicographical Throttling: Repairs are sorted by TIER_1 $\to$ TIER_4, then Stage 1 $\to$ 5.
• Top 3 Active Targets: Only the top 3 repairs are surfaced at once, preventing circular repair oscillation.
• Circuit Breaker: Automatically stops when STATUS: PASS or after $\le 2$ rounds.

Benchmarks

Two full-featured pages built with identical data: one generated by a frontier LLM with default prompting, and one generated with the first-principles-ui skill.

1. CloudScale SaaS Pricing & Quota Calculator

2. Aura ANC Headphones E-Commerce Flow

BSI Governance & 56 Laws

Every law is scored under the Bloat & Signal Index (BSI) to separate non-negotiable physical laws from subjective opinions:

$$\text{BSI} = \frac{\text{Failure Impact } (S_{\text{fail}}) \times \text{Empirical Authority } (G_{\text{prov}}) \times \text{Fix Determinism } (A_{\text{det}})}{\text{False Positive Risk } (R_{\text{fp}}) + \text{Aesthetic Bias } (R_{\text{aes}}) + 0.5}$$

| Essentiality Tier | BSI Score | Rules | Default Enforcement | Core Guarantees | | :--- | :---: | :---: | :--- | :--- | | Tier 1: Critical Invariants | $\ge 0.80$ | 14 | HARD_ERROR | WCAG 2.2 AA ($\ge 4.5:1$), mobile horizontal overflow guard, non-colliding text bounding boxes, flex avatar squish protection, 16px iOS input zoom floor. | | Tier 2: High-Signal Ergonomics | $0.65\text{--}0.79$ | 12 | HARD_ERROR (10)SOFT_WARN (2) | W3C APCA perceptual contrast ($|L_c| \ge 75$), Viénot 1999 Deuteranopia CVD separability ($\Delta E \ge 0.080$), split-pane card crush, multi-column table scroll containment. | | Tier 3: Anti-Slop Discipline | $0.50\text{--}0.64$ | 23 | HARD_ERROR (21)SOFT_WARN (2) | Zipf stage dominance ($D_{\text{Zipf}} \ge 0.48$), Shannon garnish elimination ($< 25%$ badge repetition), Rachel's 4-Rung Subtractive Copy Ladder, spring interruptibility. | | Tier 4: Watchlist / Advisory | $< 0.50$ | 7 | SOFT_WARN | Demoted to advisory warnings so they never break valid bespoke builds: concentric radius, 8px grid modulo, linear easing ban, optical centering. (Re-enabled via --strict-aesthetic). |

See the complete directory in UI_MATH_INDEX.md and docs/RULES.md.

Quickstart

Run the verifier CLI against any URL, local HTML file, or framework dev server:

# 1. Forward Math Oracle: dual-theme tokens & Tailwind CSS v4 @theme export (<15ms)
node check-ui-math.mjs calc palette --primary-hue 220 --export tailwind >> src/app/globals.css

# 2. Forward Math Oracle: Bento layout tracks & Zipf hierarchy
node check-ui-math.mjs calc layout --mode workspace --regions 3 --bento-cells 4

# 3. Forward Math Oracle: W3C physics-based spring parameters
node check-ui-math.mjs calc spring --intent gesture-release --velocity 800

# 4. Zero-Token AST Micro-Orthography Auto-Fixer (<40ms across codebase)
node check-ui-math.mjs fix ./src

# 5. Live In-Page Verification across 3 viewports (1280px, 680px, 390px)
node check-ui-math.mjs http://localhost:3000 --agent-loop

# 6. Structured Machine-Readable Multi-Agent Execution Plan
node check-ui-math.mjs http://localhost:3000 --emit-plan

Exit Codes

• 0: PASS (Zero HARD_ERROR violations and Heuristic Score $Q_{\text{UI}}^* \ge 2.0$)
• 1: FAIL (One or more HARD_ERROR violations or $Q_{\text{UI}}^* < 2.0$)
• 2: FATAL (Browser launch failure or unreachable target)

Agent Setup

Install globally or add to your repository for any AI coding assistant:

# Universal install via npm
npm install -g first-principles-ui-verifier

# Or run directly with npx
npx first-principles-ui-verifier init --mode workspace

Multi-Agent Global Synchronization

Any AI coding agent (Claude Code, Cursor, Windsurf, Codex, Gemini, Antigravity) can synchronize the skill across all installed agent harnesses:

git clone https://github.com/chama-x/first-principles-ui-verifier.git
cd first-principles-ui-verifier
npm install
npm run setup:agents

Running npm run setup:agents automatically installs or updates SKILL.md and references across:

• Project-local .agents/skills/first-principles-ui/
• Global ~/.agents/skills/first-principles-ui/
• Global ~/.claude/skills/first-principles-ui/
• Global ~/.codex/skills/first-principles-ui/
• Global ~/.gemini/skills/first-principles-ui/

Fast Verification Suite

npm run test:unit    # 170ms - Scoped kernel math, color, and forward oracles
npm run check:bsi    # 250ms - 56-law governance intake gate and skill QA
npm test             # <5s   - Fast unit suite + edge cases
npm run test:full    # 110s  - Full Playwright multi-viewport browser regression