Agent Authored UI Style

When LLMs write UI, constrain them with tokens, lint, and doctor passes so output matches human taste without hand-fixing every class list.

Enforcement stack

1. Tailwind + cn() for all ordinary layout and chrome. Source: CSS UI Enforcement
2. Sigil / Reticle tokens (var(--s-*), --ret-*) instead of one-off hex values. Source: Sigil Token Architecture
3. Ultracite + oxlint on save via agent hooks. Source: Ultracite & Fast Validation Recipe
4. react-doctor after multi-file React edits. Source: React Doctor

Constraint stack

Agent-authored UI works when the agent is boxed into a good system:

The agent should not invent the system while building the screen. It should discover the system, then compose inside it.

Anti-slop rules

Reject AI-purple gradients, cards nested in cards, and generic hero templates. Route creative work through Frontend and Design Skills or taste-* skills per Frontend and Design Skills. Source: skills/engineering/taste-skills-playbook/SKILL.md

Kevin's brief: high-signal frontier references, visible grids, GSAP/Three when earned, not "pick Tailwind and vibe." Source: Reticle Design System

Additional defaults:

• No decorative gradient orbs, bokeh blobs, or one-note palettes.
• No marketing hero when the user asked for an app, tool, dashboard, or game.
• No visible instructional copy explaining how the UI works unless the product genuinely needs it.
• No card-in-card layout except repeated items, modals, or framed tools.
• Adjacent components must not both draw the seam between them; parent grids own shared seams whenever possible.
• Buttons use icons when the action has a familiar symbol.
• Use Lucide icons for generic action, status, navigation, label, and tool symbols. Import individual icons and reserve custom SVG for brand, charts, diagrams, and product-specific illustration.
• Hero headlines should start with a product noun, user action, named object, or direct claim. Avoid generic article-led starts like "The", "A", or "An".
• Avoid "The [abstract noun] for ..." headline patterns. They read as generic model-written marketing copy.
• Hero type should scan as interface hierarchy, not poster-scale stacked slabs.
• Text must fit its container on mobile and desktop.
• Display headings must stay word-intact. Do not use overflow-wrap: anywhere, word-break: break-all, or hyphenation to force hero text to fit; reduce the type scale, change the measure, or rewrite the copy.
• Dark/light modes should be one semantic token system, not two palettes. For Reticle-like work, invert offblack/offwhite and persist mode before paint.
• Diagrams and schematic art in themed UI must use semantic tokens or theme-aware variants; avoid static dark-only assets.
• Shader backgrounds in Reticle-like UI should route through a bounded provider, stay pointer-inert, and sit behind structural SVG/rails rather than becoming wallpaper.
• Use 100dvh selectively for bounded first-viewport shells and controlled panels. Do not apply viewport height globally or to ordinary content sections.
• Loading uses skeletons for layout-bearing regions and Unicode/Braille animation for small inline pending states. Avoid Lucide Loader/Loader2, CSS ring spinners, and spinner-only blank screens.
• Motion must have a job: feedback, continuity, hierarchy, sequence, or state. CSS owns hover/focus/press/theme transitions; Motion for React owns component/layout/gesture motion; GSAP/Lottie/Three are opt-in for timeline/vector/3D surfaces that earn them.
• Global CSS owns scrollbar suppression, scroll padding, reduced-motion handling, view-transition hooks, antialiasing, and tokenized transition durations. Do not paste these hacks per component.
• Primary interactions need loading, disabled, empty, error, and cancellation states.

Reticle-specific constraints

When the local visual language is Reticle, the agent must treat line ownership as a layout decision:

• Page grids own page rails and gutters.
• Spacers own section transitions.
• Parent grids own shared cell seams.
• Children join existing seams instead of adding their own matching border.
• Diagonal hatching is allowed only for margins, substrate/foundation areas, spacer strips, disabled/empty panels, or technical illustration.
• Square controls are the default; radius comes from --ret-card-radius, not ad hoc rounded utilities.
• Segmented controls should be one shared-border object, usually grid plus sibling borders, not separate pills.
• Usage/billing/resource values use tabular numerals and compact mono labels.
• Full-width rules and two-line spacer bands should be named primitives, not one-off div stacks.
• Avoid page-wide decorative grid wallpaper. Reticle grids are structure, not a background texture; use rails, seams, spacers, margins, or schematic art with clear ownership.
• Keep Reticle theme modes as offblack/offwhite inversions. Strong controls, focus, and selection should invert with the substrate instead of introducing a new accent palette.
• Make Reticle diagrams token-aware when the page has dark/light modes. Inline SVG components are preferred because they inherit the page token system.
• Bound any Reticle first-viewport shell that uses 100dvh with clamp() or a max block size so tall desktop viewports do not create empty slabs.
• Reticle controls, nav links, form labels, status rows, and metric labels should use Lucide icons where a standard symbol exists, with fixed icon dimensions to prevent layout shift.
• Reticle pending states use skeletons or Unicode/Braille inline loading, never generic ring spinners.
• Reticle motion uses named duration/easing tokens and the CSS/Motion routing rule from Reticle Design System; gratuitous animation is a style failure.
• Reticle scrollbar, reduced-motion, focus, smoothing, and view-transition CSS belongs in the base layer or primitives, not ad hoc component class lists.
• Reticle hero copy should be concrete and interface-scaled. Do not use "The [abstract noun] for..." or huge stacked display text.
• Reticle touching panels should use the seam-grid contract: parent paints the shared seam with gap: var(--ret-hairline), children use data-reticle-cell, visible edge owners declare data-reticle-edges, and rendered checks should show data-reticle-seam-conflicts="0".
• Reticle margin/gutter visibility should be a persistent switch when used for inspection. The overlay is diagnostic chrome: fixed, token-aware, pointer-events: none, excluded from seam ownership, and verified for zero seam conflicts plus no horizontal overflow.
• Reticle page topology is margin | gutter | main content | gutter | margin. Gutters and margins are outside the main content measure; do not draw gutter overlays inside the central content rail.
• Reticle corner crosses may be user-toggleable when marker density needs inspection. Gate optional crosses with persistent document-level state and hide only the markers, never the underlying borders, rails, diagrams, or seam ownership.
• Reticle design-system demos should include a control bay for aesthetic primitives: theme, density, rails, gutters, crosses, hatching, schematic art, mono labels, and motion. Each control should use persisted document-level state and have a visible rendered effect.
• Reticle shader-backed specimen art should use ReticleShaderProvider or the local equivalent. The provider owns shaders/react backgrounds and keeps them clipped, non-interactive, and visually subordinate to seams, hatching, labels, and token-aware SVG.

Before adding a border-* class, answer: which primitive owns this visible line? If the answer is "this child because it looks okay," move the line up. Source: Reticle Design System; dedalus-labs/dedalus PR #2745; Agent-Machines web/components/reticle/*

Reference implementations

Agent Machines is the expressive Reticle exemplar: page rails, diagonal margin hatch, ReticleSpacer two-line section bands, ReticleFrame corner crosses, circuit art, and agent-console surfaces. Use it when a product can afford more visible structure. Source: Agent-Machines web/components/reticle/*; Agent Machines

Dedalus PR #2745 is the restrained production-dashboard exemplar: ReticleFrame, dense machine tables, square segmented controls, usage charts, metric rails, Nacelle typography, and onboarding volume scenes without over-decorating every panel. Use it when the UI is operational and customer-facing. Source: dedalus-labs/dedalus PR #2745 codex/final-dashboard-onboarding-ui

Loop is the exemplar for operational SaaS: dense enough to manage skills, versions, sources, automations, diffs, and sandbox sessions without turning the first viewport into a marketing page. Source: Loop

Sigil UI is the constraint-system proof: one token document drives hundreds of components and presets, letting agents modify identity by editing the system rather than sprinkling classes. Source: Sigil UI

Verification loop

Screenshot diff via agent-browser, browser-harness, Playwright, or Chrome DevTools before claiming UI complete. Codify regressions as Playwright when stable. Source: config/cursor/rules/tool-hierarchy.mdc Browser Automation section

Minimum proof:

1. Desktop screenshot of the changed surface.
2. Mobile screenshot when layout is responsive or public-facing.
3. Seam audit for Reticle surfaces: no doubled borders, no darker shared seams, no floating spacer lines.
4. Interaction proof for any menu, form, modal, drag/drop, command palette, canvas, or realtime surface.
5. Pixel sanity check for canvas/3D surfaces so nonblank render is proven.
6. Fast lint/type check.

If a visual bug is found, fix the system if possible: token, primitive, layout rule, or style page. Patch-only class changes are acceptable for one-off bugs, not recurring patterns.

Agent Rule Contract

This is the UI equivalent of typed boundaries: constrain the output before generation, then verify the rendered artifact. Otherwise the model performs confidence, which is a gorgeous way to ship purple soup.

Proof

Agent-authored UI is done only after the actual viewport has been rendered, core controls have been clicked or typed into, text fit has been checked on mobile and desktop, and the diff uses the local token/component system rather than invented one-off styling.

Style Rule Contract

This page follows Style Rule Contract: name the default pattern, banned pattern, reason, exception, proof, and codification path clearly enough that the next agent can apply the rule without asking Kevin again. If a local repo has a stricter rule, follow the local rule and update the wiki when the decision becomes durable.

---

Timeline

• 2026-07-01 | Added a Reticle gutter topology guardrail after the demo overlay treated gutters as inside the content rail. Future Reticle pages should model margin | gutter | main content | gutter | margin and shrink the content rail on narrow viewports instead of drawing gutters over content. Source: User request, 2026-07-01; Reticle Design System
• 2026-07-01 | Added a Reticle control-bay guardrail after the Hark-inspired landing page became a Reticle Design System Demo. Future Reticle demos should expose aesthetic primitives through persisted document-level controls instead of scattered ad hoc switches. Source: User request, 2026-07-01; Reticle Design System
• 2026-07-01 | Added a Reticle corner-cross toggle guardrail after the Hark landing page needed a switch to show/hide optional corner markers. Future implementations should persist document-level state and hide only markers, not structural borders or seam ownership. Source: User request, 2026-07-01; Reticle Design System
• 2026-07-01 | Added a Reticle margin/gutter overlay guardrail after the Hark landing page needed a switch to show page topology. Future diagnostic overlays should persist state, avoid pointer capture, stay out of seam ownership, and verify zero seam conflicts plus no horizontal overflow. Source: User request, 2026-07-01; Reticle Design System
• 2026-07-01 | Added a Reticle seam ownership rule after the Hark landing page still had double borders between adjacent components. Future touching panels should use parent-owned seam grids plus rendered seam-guard checks rather than sibling borders. Source: User screenshot/request, 2026-07-01; Reticle Design System
• 2026-07-01 | Added a hero-copy and type-scale guardrail after the Hark landing page showed a generic "The execution surface for..." headline with oversized stacked display text. Future hero H1s should avoid article-led generic starts and stay interface-scaled. Source: User screenshot/request, 2026-07-01
• 2026-07-01 | Added agent-authored UI defaults for Lucide icons, Unicode/Braille loading, CSS-vs-Motion animation routing, and centralized scrollbar/reduced-motion/view-transition CSS after the Hark Reticle landing page needed these standards built into the design system. Source: User request, 2026-07-01; Reticle Design System
• 2026-07-01 | Added dark/light mode guardrails for Reticle-like UI: use one semantic token system, invert offblack/offwhite, persist mode before paint, and avoid separate light-mode palettes. Source: User request, 2026-07-01
• 2026-07-01 | Added a guardrail against static dark-only schematic assets after the Hark landing page diagram had to become token-aware for light/dark mode. Source: User request, 2026-07-01
• 2026-07-01 | Added the Reticle shader-provider guardrail after the demo adopted a shaders/react FlowingGradient/Grid/FilmGrain background behind the isometric logo specimen. Source: User request, 2026-07-01; Reticle Design System
• 2026-07-01 | Added a bounded 100dvh guardrail after the Hark landing page first viewport created large empty space on tall desktop screenshots. Source: User screenshot/request, 2026-07-01
• 2026-07-01 | Aligned this page with Style Rule Contract so style guidance names default behavior, banned patterns, exceptions, proof, and codification expectations. Source: User request, 2026-07-01
• 2026-07-01 | Added guardrails against mid-word hero/display heading breaks and page-wide decorative Reticle grid wallpaper after the Hark landing page mobile screenshot exposed both failures. Source: User screenshot/request, 2026-07-01
• 2026-07-01 | Added an agent rule contract for discover, constrain, build, verify, and codify phases of agent-authored UI. Source: User request, 2026-07-01
• 2026-07-01 | Made UI proof explicit: render real viewports, exercise controls, check text fit, and use local tokens/components. Source: User request, 2026-07-01
• 2026-07-01 | Added Reticle-specific generation constraints and updated reference implementations from Agent Machines and Dedalus PR #2745. Source: Reticle Design System; dedalus-labs/dedalus PR #2745; Agent-Machines
• 2026-05-11 | CSS UI enforcement marked always-on for agent sessions. Source: CSS UI Enforcement
• 2026-05-12 | Agent Machines UI cited as Sigil port exemplar. Source: Agent Machines
• 2026-05-31 | Agent authored UI style page compiled. Source: compiled from wiki graph