Design System

The canonical UI decision page. Read this before writing product UI, generated UI, component chrome, or visual-system code. The current default is Sigil-style token constraints: identity lives in DESIGN.md, components consume variables, and visual drift is caught by doctors.

This page compiles the current house design approach across Sigil UI, Sigil Token Architecture, Design Tokens, Taste Enforcement - Anti-Slop Frontend Rules, Deep Black Palette, Interface Micro-Polish, and Design and Animation.

Core Thesis

Kevin's design-system belief is constraints over context. References, screenshots, and inspiration libraries are useful, but they are not enough for agent-authored UI. Agents need enforced surfaces: typed tokens, token-consuming components, project rules, doctors, and skills. The system should make the right design the path of least resistance.

The current mature expression is Sigil UI:

Current Sigil facts to use when writing about the system: 519 tokens, 33 token categories, 46 presets, 350+ components, and 40+ primitives. The older Reticle pages still matter as lineage and aesthetic vocabulary, but new guidance should not repeat the stale 259-token/Reticle-only story.

Personal design language: visible systems

Visible Systems as Design Language is the personal-philosophy owner behind the house implementation rules. Prototemplate makes that language explicit: the construction remains legible, every structural relationship has one owner, the ground can become the seam, expression is earned through a small palette and sanctioned devices, motion preserves identity, and components expose meaningful control without surrendering their geometry.

Treat the philosophy and implementation owner separately. The philosophy says why the work should feel authored and coherent across different visual worlds. This page says how to encode, compose, and verify those decisions in a system. Do not cargo-cult Prototemplate's exact dark plate, blue accent, crosses, or hatch into every product; carry the ownership, constraint, continuity, and audit laws into the product's own direction.

Tokens are not product architecture

Tokens and component primitives standardize parts. The design system also owns the recurring product decisions that tell agents how those parts compose and behave: the canonical settings-page structure, save model, validation and recovery, empty/error/loading states, destructive-action placement and confirmation, responsive hierarchy, and the relationship between list, detail, drawer, modal, and command surfaces. If two competent agents can build two incompatible settings pages from the same token and component library, the system has not yet documented the decision they actually needed.

Use shipped product evidence to discover these macro patterns: compare good existing screens, name the repeated structure and behavior, document its allowed variation and failure states, then make it available as a fixture, template, or typed composition. “Build it, then say it” means the documentation follows demonstrated product architecture rather than inventing a detached taxonomy. The pattern remains revisable, but a later agent may not silently replace it with another reasonable interpretation. Source: Matt Rothenberg, “You Don't Have a Design System,” captured 2026-08-12

Direction: Engineered, Useful, Fast

The house style is structural and product-minded:

• Visible systems: grids, rails, cross marks, alignment lines, clear hierarchy.
• Dense but calm application layouts for operational tools.
• Richer art direction for brand/marketing surfaces, but never generic hero slop.
• Components that feel immediate: interactive feedback resolves around 100ms, and larger transitions stay under 300ms unless they are content choreography.
• Visual constants live in tokens, not in arbitrary class strings.

For SaaS, CRM, agent-console, and wiki surfaces, prioritize quiet density: tables, timelines, drawers, inspectors, command palettes, resilient loading states. For brand surfaces, commit to a real art direction and asset strategy.

Compact Operator Hierarchy

A dense control room should preserve one stable frame while changing the selected object, evidence, and available action. The default scan path is:

scope -> current selection -> state -> evidence -> available action -> proof

Use a compact list or grouped board for scanning, a detail/peek panel for the selected object, and an inspector for evidence or consequences. A command palette may expose context-sensitive navigation and mutations, but it must call the same typed capability and authority checks as the visible interface; it is not a second mutation system.

Filters should be shareable and reconstructable from the URL. Their grammar is versioned and validated by column type, operator, and value shape. Unknown columns, mismatched operators, and malformed values fail closed instead of being silently cast. When filters hide objects, show the hidden count and a clear recovery action so an empty group cannot be mistaken for absent data.

Timelines preserve the date under the viewport while zooming, provide keyboard and visible controls, keep a literal list/detail route, mark the current date, and indicate selected work outside the viewport. Review surfaces may sequence overview -> narrated guide -> exact diff, but reviewed state is durable only when it is stored against the exact content hash. Generated sample diffs, uncontrolled checkboxes, seeded checks, and canned agent answers are visual fixtures, never proof. Source: X/@ln_dev7, 2026-08-03; complete source and build review of ln-dev7/circle@778598503e680b4c658d694dd9f65351ee48b3d3, 2026-08-12

Conversation-derived implementation rules

Recent project sessions converge on four implementation rules. Sigil changes the token specification before components. Sandbox Arena treats a redesign as a full-route laboratory—navigation, dense data surfaces, responsive states, and motion—not a collection of hero mocks. Glyphfield keeps one live production renderer and makes expensive pass invalidation, stable GPU resources, material channels, rapid switching, fallbacks, and export proof visible. Agent-Pets and game projects evaluate the complete direction/state/view matrix so a beautiful cardinal frame cannot hide a broken intermediate angle or closure.

Therefore every design run should freeze its route × viewport × theme × state × motion matrix, edit semantic tokens before leaf styling, use the real production component/renderer path, and attach exact screenshots or recordings plus performance and reduced-motion evidence. Missing matrix cells are explicit not-run results. Iteration galleries and inspiration boards help choose a direction; they never substitute for the matrix or the shipped-path proof. Source: reviewed Sigil UI, Sandbox Arena, Glyphfield, Agent-Pets, PortfolioMon, and Princeton Tower Defense agent-session lineages, 2026-08-12

Operational and narrative time

Do not force one timeline treatment onto two different jobs. An operational timeline answers “what is selected, late, blocked, or changing now?” and keeps filters, exact dates, list/detail access, and direct controls visible. A narrative timeline answers “how did this one person, project, product, or company unfold?” and may use a continuous rail, sparse milestones, people, and media to create temporal context. The public wiki may offer the latter for a selected owner’s story; /system defaults to the former for work and proof.

When a horizontal narrative rail translates vertical wheel input, declare whether it owns the page or is embedded. An embedded rail may capture only a gesture that begins inside it, must return control at either boundary, must not capture host-page arrow keys until focused, and must provide ordinary scroll/list access on small screens. Intro choreography starts only when the surface is about to become visible; reduced motion lands directly in an equivalent settled state. Media and effects require native focusable controls, not hover or pointer handlers on prose. Inject the current temporal boundary, validate event identity and dates, preserve source links, and measure long, sparse, resized, touch, keyboard, and low-power cases. Source: X 2085118669609472397; 61-second local demo review; complete source, registry, build, typecheck, lint, and accessibility-boundary review of evilrabbit/lifeline@8ddbb3d, 2026-08-12

Direction Contract Before Tokens

Tokens can faithfully encode a generic direction, so high-ambition greenfield and redesign work needs a direction gate before token authoring:

1. Classify the job as blank slate, redesign, addition, or scoped refinement.
2. For blank slate or redesign, generate grounded directions plus genuinely different challenger worlds. Use an external seed and preserve its key so a rejected roll can be cleared rather than rhetorically repackaged.
3. Commit to one direction. Render a design-system board and representative first surface before building the full UI.
4. State the implementation intent in at most 150 words: thesis, owned visual world, story, first viewport, form, and the seed key.
5. Compile the accepted direction into DESIGN.md, tokens, components, and asset rules; then use a separate finish review to compare the render against the promise.

Challenger worlds are not templates and popularity is not authority. Product truth, incumbent visual evidence, accessibility, platform conventions, and Kevin's explicit direction can defeat the draw. An addition inherits the surrounding world; a scoped refinement may not quietly redesign the product. Source: X/@pbakaus 2079984598105358828; Impeccable skill-v4.0.4 release and current skill, reviewed 2026-08-10

Parameterized visual asset systems

A reusable visual prompt is a controlled asset system when it separates a small set of explicit variables from frozen art direction. Preserve the exact identity geometry first, then fix form, material response, reflection logic, lighting, lens/perspective, composition, background, render quality, and banned tendencies. The variables may change brand/reference and background or another declared input; they may not quietly rewrite the material world.

For every output, retain the prompt revision, input/reference hash, declared variables, model/provider/mode, output hash, rights and trademark basis, selection/rejection reason, and one identity-fidelity comparison. A polished logo render is not permission to use a third party's mark, and a shared prompt does not license its reference images or generated outputs. The reviewed liquid-metal system is useful because two variables sit inside a precise physical brief—shallow relief, pearl-white metal, sparse dichroic transitions, black-flag reflections, front-facing telephoto compression, centered negative space, and explicit anti-chrome/anti-rainbow constraints—not because that finish should become a universal house style. Source: X/@AmirMushich 2084353216666345517; complete prompt thread and four local specimens, 2026-08-12

Specificity before category reassurance

Do not let “tasteful AI” become its own default template. Serif display type, cream neutrals, pastoral photography, paper texture, soft gradients, and vague language about intelligence or humanity can each be valid, but together they now frequently signal category imitation rather than a particular product. Start with the product's mechanism, audience, stakes, place, evidence, and owned point of view. The chosen type, material, image, interaction and copy must explain one of those specifics. Require at least one anti-reference from the category and reject a direction that could accept a competitor's logo without meaningful change. Source: X Article 2084360582254460928 via X 2084728233250185578, “AI slop can look tasteful,” reviewed 2026-08-12

Token System

Use the three-layer model from Design Tokens:

In Sigil, the agent edits DESIGN.md. The compiler emits CSS custom properties, Tailwind v4 @theme, W3C JSON, and TypeScript surfaces. Components consume var(--s-*) or semantic project variables. If a component needs a hardcoded hex, px, shadow string, or font literal, the system is leaking.

Visual Motif Memory

A visual system also needs named motifs: repeated geometry, grid rules, icon construction, and layout primitives that agents can extend without inventing a new brand language. Ayush Soni's reviewed four-image visual-system artifact is a useful example: the system repeats electric-blue connected blocks, cyan accent squares, monoline emblems, diagonal circuit rails, rounded-square modules, and dark/light grid fields. Those motifs should become tokens, component primitives, or DESIGN.md prose constraints before generation begins. Source: X/@ayushsoni_io and local image review, 2026-07-03

Do not hand agents a single moodboard screenshot and ask them to infer the system. Extract the motif grammar: shape vocabulary, stroke weights, grid cadence, allowed color roles, figure/ground behavior, and where the motif is allowed to appear.

Generated icon and 3D custody

For a generated icon family, keep four owners distinct: source/image-family procedure, accepted bitmap, procedural 3D asset, and product integration. Record the source license and hash, palette and module grammar, accepted-versus-rejected variants, reconstruction suitability, named hierarchy, runtime budget, reduced-motion behavior, and export proof. A bitmap is visual evidence—not hidden geometry, interaction, animation, or redistribution permission.

Maintain two screenshot contracts. The public presentation capture may include labels, controls, staging, and contact shadows. The diagnostic capture must use fixed camera/viewport, clean background, no chrome, and a map-stripped variant when the gate measures silhouette or geometry. Do not let decorative pixels enter a machine mask. At export, clone the asset root and strip textures plus live runtime references from userData; retain only small portable semantic metadata and probe the exported file. The controlled workflow-router specimen demonstrated why: direct live-graph export reached about 9.6 MB, while the sanitized GLB retained 35 named nodes and 17 meshes in 71,004 bytes. Source: X/@mona_biasia 2084217575412826219; BIAsia/voxel-icon@8bed7e8; reviews/fixtures/voxel-icon-owned-specimen/, reviewed 2026-08-13

Brand-system deployment proof

A logo or moodboard becomes a brand system only when the same authored grammar survives real channels. Before implementation, freeze the proposition and copy spine, mark and motif rules, image/material language, type and color roles, responsive and accessible behavior, production ownership, and asset rights. Then prove the system on at least four materially different surfaces such as a landing page, product UI, social card, presentation, advertisement, or physical application. Preserve the matrix of surface, purpose, motif, copy, source asset, adaptation, and reviewer; a collection of unrelated polished mockups is not cross-channel proof.

For a new identity, make the upstream decision trail inspectable too: evidence brief and anti-references, at least two materially distinct directions, explicit selection and rejected alternatives, then the codified system and deployment matrix. An overview board is a summary artifact, not proof of completion. A portfolio reel is also not one system: decompose it by client/project and by mark, palette, type, copy, web, product, diagram, campaign, and physical artifact before extracting a lesson. Preserve creator attribution and separate rights for expression, media, fonts, code, and generated output. Source: X 2083230040133964214, 2084293211141570717, 2084343196994224458; Drapz, Pixel Orb, and Runline AI primary sites; complete local media review, 2026-08-12

The reviewed Kinect identity demonstrates one useful transfer pattern: a sharp K, flowing light/surface motif, and direct revenue proposition remain recognizable across web, mobile, social, manifesto, advertising, and stage applications. EdgeRun demonstrates another: precise mission language, industrial CAD/exploded geometry, a predominantly monochrome system, and one bounded iridescent accent make the product itself the brand material. These are system-construction lessons, not reusable expression or asset grants. Source: X 2082409501404373292; Kinect; X 2082535317806973083; EdgeRun; saved media and official sites reviewed 2026-08-12

For a generated multi-image identity, also freeze the identity-reference hash, look, palette, aspect, prompt/artifact job, and generator revision. Pass the same identity reference to every render; once one image passes the complete visual bar, use it as the additional style anchor for the rest of the set. Keep the manifest, inspect each output against the locked thesis and literal identity/structure rules, exclude superseded renders, and never let a failed subscription backend silently cross into paid generation. This contract applies to recurring editorial assets; deterministic icons, logos, product UI, and exact diagrams still need their own authored source and semantic proof. Source: illo v0.32.1 SKILL.md, quality-bar.md, and backends.md, reviewed 2026-08-11

Interaction Metaphor Memory

A reference's appearance is downstream of its information job. Before a grid, atlas, room, graph, or physical object enters DESIGN.md, record this compact contract:

entities -> shared attributes -> primary user verb -> narrowing controls -> overview/detail transition -> provenance -> edge states

Use a normalized grid when the job is scanning many comparable objects; an entity atlas when the job is comparing one shared schema; a physical metaphor when it makes an abstract consequence more legible; a room when personal possession and display are themselves meaningful; and a graph when retrieving relationships is the task. Do not borrow the representation when the product's data shape or primary verb differs. Preserve the literal values and accessible controls beneath any expressive metaphor. Source: Creative Web Interaction References; X/@jonaasw1 2079246871063568437; five live sites and four local images reviewed 2026-08-11

Behavioral Interaction Contract

An expressive surface is a state machine with authority, not a screenshot. For input-driven, collaborative, generative, or community UI, DESIGN.md and the acceptance proof must name this chain:

input + permission -> local/remote boundary -> transformation -> visible measurement/state -> output -> explicit share/publish action -> moderation/attribution/takedown -> keyboard/reduced-motion/error proof

Editor interaction and delivery ownership

Canvas-and-panel products need an ownership inventory before implementation. For every operation that could plausibly live on either surface, record the capability, selected primary surface, evidence, rejected duplicate surface, and any complementary operation. Direct selection or spatial manipulation may live on the canvas while exact values, modes, constraints, collections, and commands live in the panel. One capability cannot be mirrored across both surfaces under different labels; both are valid only when the operations are actually different. Keep product output and editor chrome separate so export cannot silently capture controls, handles, or shell UI.

Motion intent and artifact intent are also separate. Classify product motion as playback, keyframes, reference-specific transport, or autonomous decoration. Use a single transport owner rather than adding play/restart controls throughout the panel. Animation does not imply video delivery: image, video, copy, save, and publish are explicit output contracts with their own authority and proof. For a video/GIF/screen reference, study timecoded frames and frame-to-frame state transitions before implementation; a screenshot establishes appearance, not behavior. Source: Toolcraft; Toolcraft control-selection, timeline-animation, setup-export, reference-study, and acceptance contracts at 4b1e415b, reviewed 2026-08-12

For a living gallery, personal graph, or self-organizing information surface, add this second chain:

source objects + relationships -> classify/group/merge evidence -> overview + literal retrieval -> selected-object detail -> proposed action -> target-bound approval -> result + undo/revocation

Spatial or macro/micro representation is an additional retrieval channel, never the sole one. Keep a complete list/search/detail path; expose why an item moved, merged, surfaced, or triggered a nudge; and distinguish read-only classification or summarization from edit, send, delete, and publication authority. People graphs require subject consent and visibility rules. High-authority integrations must show connected scopes, processors, retention, revocation, and recovery in the product—not only in terms. Source: Creative Web Interaction References; X/@jonaasw1 2069135333422166044; Portal, aileenland, Feather, and Knicks Mosaic rendered/policy replay, 2026-08-11

Use real input to create meaningful response, not motion for its own sake. Strum Surfer makes the instrument the controller; kern.me tries to make spacing deltas visible; Synesthesia Engine exposes the measured image characteristics that feed an authored cross-modal interpretation. Codex Image Maker demonstrates local creation before optional submission, and the Knicks archive demonstrates governed contribution plus attribution and removal. Jam demonstrates that collaboration expands authority: every participant, credential, repository, terminal stream, sandbox, and public preview needs an explicit boundary.

Keep counterexamples. In the 2026-08-11 replay, kern.me's letter layer did not populate in the inspection browser even though the preserved source image showed the intended state; Midlife Engineering exposed 203 enabled focusable elements, 197 without usable names. The former becomes a loading/runtime regression test, the latter a semantic-control rejection test. A visually excellent reference can change the design system and still fail implementation admission. Source: Creative Web Interaction References; X 2070242834985431293; complete eight-site rendered replay, 2026-08-11

Code-backed design surfaces and critique

When an agent edits an existing product visually, the named semantic DOM and the repository remain the source of truth. Map the selected element to its component, state, token, data, accessibility semantics, and code location; show the visual delta as a proposal; then apply a reviewable source diff and replay the exact fixture. A canvas overlay may annotate, rearrange, or explore, but it must not create a second hidden component model or serialize inaccessible absolute-positioned markup as the final implementation. Source: X 2067626075882983763; DOM design-tool artifact, reviewed 2026-08-12

That mapping needs a traceability receipt rather than a plausible label. Record the stable DOM/capture anchor, framework component name and kind, component hierarchy, source file/line when provable, computed styles and resolved tokens, route/viewport/runtime fixture, and the method, confidence, and unknowns behind each source-derived field. SSR before hydration, production minification, non-React pages, portals, memo/forward-ref wrappers, and missing source maps must degrade to honest DOM or repository anchors instead of invented component identity. An isolated artboard may freeze and manipulate the captured state, but production code changes only through an exact approved source diff and a restored-fixture replay. Source: X/@lukaivanovic 2079178687409279303; benjitaylor/agentation@8158a97, source-location and React-detection tests, reviewed 2026-08-12

Discovery catalogs are not adoption authorities. Their ranks and descriptions create investigation candidates; the selected tool's official repository, license, current package, source, tests, runtime behavior, and target-product proof decide use. The current designtools.fyi entry calls Agentation open source, while the pinned repository is PolyForm Shield 1.0.0 and prohibits competing products or services. The repository license controls. Source: designtools.fyi, reviewed 2026-08-12; benjitaylor/agentation@8158a97 LICENSE

Design critique is multi-axis evidence, not one taste score. Review hierarchy, composition and space, typography, color/material, interaction and motion, content fit, accessibility, responsiveness, performance, and consistency with the chosen world separately. Compare against a frozen intent and real rendered references; state disagreements and decisive failures. Photography and graphic design are legitimate cross-disciplinary training sources for framing, light, rhythm, negative space, typography, print texture, and editorial sequencing, while Vercel's strongest transferable signal is to treat the web as its own material and combine systems discipline with single-frame craft. None of these sources licenses copying protected expression or replacing behavioral proof with an aesthetic ranking. Source: X 2067642363909144932, 2067999346780524753, 2068008743153832264, 2068030598028087788, 2069008589721932251, reviewed 2026-08-12

State, Replay, And Progressive Reward

Hidden system state must first become an explicit state machine and a literal status/control surface. A character, material, scene, or reveal may provide an additional expressive channel; it cannot become the only way to know what a human, agent, timer, generator, or archive is doing.

For ambient status, record event source -> permission -> normalized state -> literal label/control -> optional character/material reaction -> quiet/disable path. Comnyang is the reference: its coding-agent reactions are memorable because thinking and completion become a small desktop character, but a production adaptation must still expose the same state redundantly and cannot hide Accessibility/input authority behind charm.

For generative or stateful experiences, preserve a replay identity:

input/data revision + seed/state + implementation version + viewport + mode + output settings

Preview, save/export, and share are separate states. Retrowave Road's seeded world URL and distinct silent/play/photo/record/share controls demonstrate the shape; the acceptance receipt must prove restoration of the exact state, not merely a similar screenshot.

Progressive reward may reveal meaning rather than fill a generic bar. Paint Pomodoro's artwork reveal is useful only when progress and attribution remain visible; pause, resume, skip, and recovery work; and reduced-motion/static alternatives deliver the same information without the reveal. Reward must not trap the person inside a timer, animation, or full-screen overlay. Source: Creative Web Interaction References; X 2077488853401620893; seven-site rendered replay and exact Paint Pomodoro source review, 2026-08-11

Color

Build the neutral system first. Then choose at most three active colors plus semantic state colors. Prefer OKLCH for authored palettes because perceptual lightness matters more than RGB guessing.

Rules:

• Page background, surface, raised surface, border, and text hierarchy must be semantic tokens.
• Accent color is for action, state, or a deliberate motif; it is not confetti.
• Avoid single-hue UIs that read as one-note purple, beige, dark slate, or espresso.
• Gradients need material logic: light, shader, glass, heat, foil, or depth. A gradient with no material story is decoration.
• Verify dark and light modes separately. Dark mode is not "invert the colors and pray."

Typography

Use a clear triad only when the product earns it: display, body, mono. Do not let all three compete.

Rules:

• Reserve display type for true hero or brand moments.
• Application panels, dashboards, sidebars, and cards use tighter, smaller hierarchy.
• Use text-wrap: balance on short headings.
• Use tabular-nums for changing or comparative numeric UI.
• Avoid viewport-scaled font sizes. Use stable type scales and container-aware layout.
• Avoid default Inter/Roboto as the whole personality unless the project has intentionally chosen anonymous software neutrality.
• If Inter is intentionally selected, use Inter Font as the source rule: rsms/inter, official CSS, or inter-ui; Google Fonts is only a fallback distribution.
• Do not add an eyebrow merely to make a section look designed, and do not use widely tracked uppercase as generic visual filler. A compact mono label is allowed only when it names real structure, state, provenance, a command, or an identifier that helps the operator scan; ordinary headings and prose should carry the hierarchy themselves. This preserves Reticle's operational language without turning every section into templated agent chrome. Source: X/@benhylak and X/@Neesh774, 2026-08-12

Typography and layout are not complete until they survive localization. Test plural categories, dates/numbers/currencies, interpolation, RTL mirroring, CJK font and line-breaking behavior, longer and shorter strings, component reorder, truncation, zoom, and missing-key/offline states. If AI is allowed to rearrange a JSX tree for translation, preserve semantic order, focus order, stable identity, event bindings, and source-to-output provenance; language adaptation does not authorize arbitrary UI generation. Source: json-render directives, GT complete-tree translation, and Takumi v2 localization signals; current generaltranslation/gt@240a65e9 and kane50613/takumi@28edb816 evidence

Spacing, Layout, and Radius

Use 4px granularity for component internals and 8px rhythm for layout. Stable dimensions are part of polish: boards, grids, toolbars, counters, and tiles should not resize when labels, hover states, icons, or loading text appear.

Default ladder: 4, 8, 12, 16, 24, 32, 48, 64, 80, 96.

Radius:

• Cards: 8px or less unless the existing system says otherwise.
• Nested surfaces obey the concentric rule: outer radius = inner radius + padding.
• Radius should express the material. Operational surfaces want restraint; playful or consumer surfaces can round more.

Motion

Motion is a feedback system, not seasoning.

Rules:

• High-frequency controls use little or no animation.
• Hover/press feedback should be immediate and interruptible.
• Animate transform and opacity; avoid transition: all.
• Enter/exit asymmetry: exits are shorter and travel less than enters.
• Popovers open from the trigger origin, not the center of the universe.
• Respect prefers-reduced-motion.
• Do not mix multiple animation engines in one component tree unless the boundary is explicit.
• In development and review surfaces, motion must be inspectable: identify its owning element, trigger, duration, easing or spring parameters, library, and reduced-motion replacement. Prefer implementations that can be paused, replayed, slowed, and scrubbed; record an adapter gap when they cannot.
• Animation acceptance proof should compare the relevant interaction at normal speed, reduced speed, a meaningful timeline position, and reduced motion.
• LCP content must be present and legible in the server-rendered HTML. Do not hide the hero headline behind opacity: 0 or wait for hydration to reveal it.
• Separate essential content motion from decorative scene choreography. The latter loads after the first paint and cannot delay the former.
• Keep the interactive client boundary around the smallest element that needs browser state. Prefer native HTML and server-rendered SVG when interaction is unnecessary, and isolate 3D, editors, charts, maps, and video by route or explicit user action.

Use GSAP/ScrollTrigger or Motion when choreography is actually part of the experience. Use CSS transitions for local controls.

Entrance order follows information importance, not DOM position. Shimmer, scroll-fade, noise, animated icons, WebGL text, and shader-over-DOM treatments must each earn a named informational or material role. Review every effect in an atomic fixture with normal, paused/scrubbed when possible, reduced-motion, keyboard/focus, touch/coarse-pointer, slow-loading, and performance states. Then compare the composed page against a no-animation control; a collection of individually attractive effects can still destroy hierarchy.

These rules preserve art direction while protecting the critical path. They come from a production PageSpeed 100 case with custom fonts, animation, charts, documentation, and 3D—not an empty-page benchmark. Source: X/@pontusab, 2026-07-21

Sensory state mapping

Audio, haptics, motion, color, text, and controls must describe one underlying state machine rather than behaving as independent decoration. For a realtime voice surface, define the legal states—ready, connecting, listening, user-speaking, processing, tool use, assistant-speaking, interrupted, stopped, and error—then map every state to visible text and controls before adding motion or sound.

The reviewed HF Realtime Voice direction provides a strong bounded example: reserve saturated color for the active voice/state and tiny role echoes; let actual microphone or playback energy drive the hero motion; use mono for terse machine identifiers rather than human prose; and keep the rest of the interface quiet enough that the speaking object remains the center of gravity. These are transferable sensory rules, not permission to copy its orb, palette, CSS, or UI; the current Space repository declares no reuse license. Source: HF Realtime Voice DESIGN.md@03a43b2 and local 104.7-second demo review, 2026-08-11

Every sensory mapping needs redundant and accessible fallbacks: state text, partial/final transcripts, visible stop and mute, keyboard focus, 44 px targets, 360 px layout, silent operation, and prefers-reduced-motion. Barge-in must clear buffered playback and stale visual output together. Use Realtime Voice Agent Workflow for the runtime, latency, privacy, and failure proof behind the design.

Optional interaction sound

The default interface remains silent. Add synthesized interaction sound only when it disambiguates state or materially improves a named product workflow. Cuelume is the retained small-library route: current 0.2.2 exposes 17 Web Audio cues, one lazy AudioContext, delegated attribute bindings, global enable/volume controls, SSR-safe imports, and no runtime dependencies. It is MIT, but its single test file and absent CI mean the host application owns acceptance proof.

Map cues to semantics, not elements: press/release may confirm direct manipulation; success only follows actual completion; error must not sound before a recoverable error is visible; loading/ready must follow the same state machine as text and motion. Never attach sound to every hover. Require a visible and keyboard-reachable sound toggle, persisted preference owned by the app, conservative volume, no playback before user activation, interruption and rapid repeat tests, silent-browser fallback, screen-reader checks, and a long-session annoyance review. A product that is understandable and satisfying while muted passes; sound is redundant reinforcement, never the only state signal. Source: X 2075914817471209790, X 2077695569317802384, Danilaa1/cuelume@b879b72, 2026-08-12

Component States

Every interactive component needs the states a real user will hit:

For agent UI, add tool-call state, approval state, retry state, provenance, and stop/cancel controls. See AI-Native Design Patterns.

Demo components do not define runtime truth. For each loading, streaming, thinking/status, tool, task, recommendation, diff, or approval treatment, bind the visual state to a named domain event and replay fixture. Replace showcase timers with real transitions, preserve the last confirmed event, and keep completion impossible until the underlying receipt exists. A page-level reduced-motion override is useful defense in depth, but each copied component still needs an information-equivalent static state and local motion ownership. Source: Beautiful UI 19-pattern source and rendered replay, 2026-08-11

AI-Native System Layer

Copilot Design System adds a design-system requirement that ordinary component catalogs miss: the system must define how an agent's presence, memory, attention, and focus handoff work across surfaces. Components alone cannot solve this. The design system needs named surfaces for global memory/chat, local canvas execution, contextual suggestions, and visible handoffs when the active focus moves. Source: Microsoft Design, 2026; Copilot Design System

Agent-ready means one predictable system for both operators

Astryx is a useful external reference for making a design system legible to people and coding agents at the same time. Its strongest transferable ideas are not its visual defaults: typed and consistently named component APIs, open compositional internals, a CLI that exposes the same docs/templates/themes/codemods humans use, CSS-variable theming, swizzling when a project must own the source, and conventions tested by measurement rather than asserted as taste. Those are direct evidence for Sigil's DESIGN.md + tokens + components + doctors model.

Astryx is currently beta, requires React 19+, authors internals with StyleX, and ships a broad 150+ component system. It therefore does not replace Sigil/Reticle or authorize a second visual language. Borrow its API/documentation/measurement patterns; evaluate an Astryx component only for a concrete React product, then retokenize it, verify accessibility and all states, and keep house identity in the local system. Source: X 2076504402308047281; facebook/astryx README and repository snapshot at d790582, reviewed 2026-08-10

Component Source Layer

Vocabulary before source selection

Do not choose or implement a component while its interaction pattern is still being described as “the little thing,” “a dropdown-like box,” or “make it feel native.” Run ui-vocabulary first. Freeze the observed platform, placement, trigger, lifetime, job, focus/modality, anatomy, and DOM/API clues; rank no more than three names; state the decisive difference from the nearest confusable pattern; and verify the winning semantics or symbol against the platform's primary documentation.

NameThatUI is a discovery bridge for generic public clues, not design-system authority. Its query API records the literal search, so private project language stays local. Component Gallery then helps compare how named patterns appear across systems. Only after that does Component Library Sources choose an implementation. The resulting vocabulary receipt—user-facing name and aliases, exact semantic/API names, confusable difference, primary source, prompt-ready behavior, and unresolved facts—travels with the component's design and browser proof. Source: X/@argofowl 2076284369883615555; NameThatUI methodology and rendered focus-ring replay, 2026-08-11; UI Component Vocabulary

Before hand-rolling a component, load Component Library Sources. The design-system stack should route in this order:

Imported or copied components are starting points. Retokenize them into the local semantic token system, replace demo copy/data, verify states, and run browser screenshots before treating them as design-system code. Source: Component Library Sources; User request, 2026-06-26

Icon System Contract

Interface icons are a design-system dependency, not interchangeable decoration. Before changing a project's incumbent family, run the coverage and admission procedure in UI Design Defaults (Cheatsheets): render the actual high-frequency product concepts at shipping sizes, compare optical voice and state coverage, verify the exact asset/package license, and measure the production bundle. A social post or the desire to look less generic is discovery evidence, not sufficient reason to rewrite every icon import.

Every adopted system records one owner-controlled contract:

• exact family, style, package/source revision, license, grid, size tokens, and stroke/fill policy;
• an AppIcon wrapper plus semantic icon map, with direct named imports and a documented custom-icon extension grid;
• decorative versus meaningful semantics, accessible names for icon-only controls, RTL behavior, high-contrast behavior, and redundant selected/error cues;
• default, hover, pressed, selected, focus-visible, disabled, loading, and reduced-motion proof at the smallest shipping size;
• output-bundle comparison and rollback to the incumbent.

One product surface uses one coherent grammar. Fill or weight may encode state inside that grammar; it does not license mixing unrelated packs. Brand marks route through The SVG, not the interface-glyph family. Source: X 2030310771326861336; Phosphor, Heroicons, Tabler, Iconoir, Hugeicons, Lineicons, Streamline, and Solar exact-source review, 2026-08-11

Enforcement

Design quality must be structural:

• Tailwind v4 @theme and CSS variables for tokens.
• Project rules like CSS UI Enforcement and taste-enforcement.mdc.
• Browser verification for rendered behavior.
• Visual doctors for high-stakes surfaces.
• DESIGN.md / token diffs for identity changes.

Ban hardcoded hex colors, arbitrary spacing, random z-index values, one-off shadow strings, generic 3-card feature grids, decorative blobs, default icon-in-circle cards, and visible instructional copy that explains the app instead of letting the interface work.

Visual Proof Ladder

A screenshot critic does not get to collapse seeing, implementation checks, and taste into one score. High-stakes visual review proceeds through four explicit layers:

1. Deterministic state: route, viewport, DPR, fixture, DOM/scene identity, computed tokens, accessibility tree, responsive state, and screenshot hash.
2. Atomic perception: applicable localization, attribute, counting, relation, depth/3D, OCR, comparison, fine-detail, context-integration, and hallucination/absence questions with short falsifiable answers.
3. Design judgment: hierarchy, identity, composition, rhythm, affordance, motion, accessibility, and product fit, using the verified facts rather than an imagined surface.
4. Human/product verdict: approve, revise, reject, or hold with the exact accepted evidence and residual disagreement.

Use deterministic checks for machine-readable facts and vision models for the remaining rendered evidence. Repeat a model observation when it controls the verdict; record pass consistency, abstentions, model/revision/effort, prompt digest, and fallbacks. A second critic is independent only when it does not share the first critic's hidden transcript or answer. If perception conflicts with DOM, data, scene, or repeat evidence, the item stays unresolved. One beautiful critique or a high aggregate benchmark score is never proof that the model actually saw the relevant detail.

PerceptionBench supplies the failure-derived atomic taxonomy and the evidence that stable aggregate scores can conceal unstable per-sample perception. It does not measure design taste or end-to-end product quality, and its categories are conditioned on current models. Re-induce or revise local visual-doctor cases from actual Fieldwork failures rather than freezing the taxonomy forever. Source: PerceptionBench v1, especially sections 2.1, 2.2, 3.5, and limitations; X/@Kimi_Moonshot 2081813202514681878; local launch-image review

Quick Checklist

Before shipping a component:

• Colors, spacing, radii, shadows, typography, and motion use tokens.
• Layout has stable dimensions and mobile behavior.
• Text fits its container on mobile and desktop.
• Loading, empty, error, disabled, hover, focus, and active states exist.
• Hit targets are comfortable.
• Mobile-web surfaces pass the native-fit checklist on real hardware; hover, tap flash, dynamic viewport, input zoom, gesture, overscroll, safe-area, selection, theme-color, keyboard and notch behavior are explicit rather than inherited from a blanket reset.
• Experimental corner-shape/superellipse() styling has an ordinary border-radius fallback and preserves clipping, focus, zoom, contrast and concentric nesting across supported browsers.
• Icons follow the recorded family/style contract, are optically aligned at the smallest shipping size, and have accessibility, RTL, state, license, import, and bundle proof.
• Motion is purposeful, interruptible, and reduced-motion aware.
• Decorative eyebrows and widely tracked uppercase labels have been removed; any remaining mono uppercase text conveys real system structure or state.
• Browser screenshots confirm the rendered result.

---

Timeline

• 2026-08-12 | Added the conversation-derived route × viewport × theme × state × motion proof matrix and same-production-path rule from the reviewed Sigil UI, Sandbox Arena, Glyphfield, Agent-Pets, and game-project cohorts. Source: contract-v4 agent-session lineage review

• 2026-08-12 | Converted the paired “never use eyebrows / spaced-out uppercase” posts into a testable anti-template rule. Decorative kickers are out; terse mono labels remain only for actual operational structure, state, provenance, commands, or identifiers. This challenges generated-interface habits without erasing the established Reticle visual language. Source: X/@benhylak 2087624444495921644; X/@Neesh774 2087625917094899781

• 2026-08-12 | Added real-hardware mobile-web and progressive native-corner gates from two visual CSS sources, with MDN support status preventing a Chromium-only effect from becoming a system default. Source: X 2087150812761858367, 2087247200464068629; MDN

• 2026-08-12 | Added the anti-generic AI-brand rule: category reassurance cannot substitute for product-specific mechanism, audience, stakes, place, evidence and point of view; every direction now needs an anti-reference and competitor-logo substitution check. Source: X 2084728233250185578; complete X Article

• 2026-08-12 | Expanded the design-system boundary from tokens/components to canonical product composition and behavior patterns, using incompatible agent-built settings pages as the failure fixture. Source: Matt Rothenberg, “You Don't Have a Design System”; X 2084262814940602583

• 2026-08-12 | Added parameterized visual-asset contracts: freeze the art direction, expose only declared variables, preserve identity and rights, and retain prompt/input/model/output provenance and fidelity proof. Source: X/@AmirMushich 2084353216666345517; complete prompt and local images

• 2026-08-12 | Tightened the code-backed design rule with a semantic-capture traceability receipt, honest SSR/non-React/source-map fallbacks, isolated artboard boundaries, and a catalog-versus-primary-source authority rule. The Agentation catalog/license contradiction is retained as the concrete counterexample. Source: X 2079178687409279303; benjitaylor/agentation@8158a97; designtools.fyi, 2026-08-12

• 2026-08-12 | Split operational time from narrative time and added the interaction-ownership contract for embedded temporal rails: gesture origin, boundary release, focus-gated keyboard input, mobile/list equivalence, viewport-armed intros, reduced-motion settlement, focusable media, injected current time, and data/performance proof. Lifeline remains the recommended narrative source but not a wholesale dependency because its current live registry lags source and the pinned repository has no tests/CI and failing lint. Source: X 2085118669609472397; evilrabbit/lifeline@8ddbb3d

• 2026-08-12 | Added the compact operator hierarchy after source-level review of Circle: stable scan/detail/inspector framing, validated URL-backed filters, context-sensitive commands over one capability path, anchor-preserving timelines, explicit hidden-state recovery, and content-bound review proof. Circle remains an interface reference rather than a backend or agent architecture because its data, diffs, checks, and agent replies are deterministic mocks and the repository has no tests. Source: X 2084328572160704943; ln-dev7/circle@778598503e680b4c658d694dd9f65351ee48b3d3

• 2026-08-12 | Added the code-backed DOM design rule, multi-axis critique, and retained pmndrs UI, Shader Lab, Dither Kit, and Blume as guarded source factories rather than a new global design language. Source: nine saved X signals; repository evidence at dc196190, 4ed3de2e, 1e7faee9, and 0e0c39cb

• 2026-08-12 | Kept Cuelume as the optional synthesized interaction-sound route and converted the two high-engagement demonstrations into a semantic, opt-in, interruptible, mute-complete acceptance contract. Source: X 2075914817471209790, X 2077695569317802384, Danilaa1/cuelume@b879b72

• 2026-08-11 | Added AI-native component admission: showcase timers never define progress, every visible state binds to domain events and replay fixtures, completion requires a receipt, and global reduced-motion CSS does not replace component-level static equivalence. Source: Beautiful UI 19-pattern rendered/source replay; X 2082479500944904432

• 2026-08-11 | Added the icon-system contract: incumbent-first challenger admission, product-concept coverage probes, exact license/revision, one family/style grammar, owned wrapper and semantic map, direct imports, state/accessibility/RTL proof, bundle comparison, and rollback. Source: X 2030310771326861336; exact repository, npm, rendered-doc, and local image replay

• 2026-08-11 | Added the generated-identity consistency contract: freeze reference/look/palette/job/revision, pass the identity reference on every render, use only a fully QA-passed set anchor, preserve manifests, exclude superseded outputs, and fail closed before paid fallback. Source: X 2065232610335641667; tmchow/illo-skill v0.32.1; exact release replay

• 2026-08-11 | Added the state/replay/progressive-reward contract: ambient characters are redundant event-driven representations with explicit permissions and quiet paths; generative UI preserves a complete replay identity and separate preview/export/share states; progressive reveals expose control, recovery, attribution, and reduced/static alternatives. Source: X 2077488853401620893; Comnyang, Retrowave Road, and Paint Pomodoro rendered/source replay

• 2026-08-11 | Added the behavioral interaction contract for sensory input, collaborative rooms, generators, and community surfaces: permission and processing boundary, visible transformation, local output custody, separate public transition, moderation/attribution/takedown, and operability proof. Retained kern.me's failed live render and Midlife's 197 unnamed focus targets as acceptance tests rather than discarding otherwise useful references. Source: X 2070242834985431293; complete eight-site rendered replay

• 2026-08-11 | Added a four-layer visual-proof ladder: deterministic state, atomic perception, design judgment, then human/product verdict. High-stakes model observations now require repeat consistency and machine-readable corroboration; PerceptionBench informs verifier cases without becoming a design-quality score or dependency. Source: X/@Kimi_Moonshot 2081813202514681878; arXiv:2607.24957v1; repository/dataset and image

• 2026-08-10 | Added Astryx as an agent-ready design-system reference. Its reusable signal is shared predictable APIs, docs, CLI, open internals, themes, and measured conventions for humans and agents; beta React 19 components do not replace Sigil/Reticle or its visual identity. Source: X 2076504402308047281; facebook/astryx at d790582, 2026-08-10

• 2026-08-10 | Added a pre-token direction contract for greenfield and redesign work: job classification, externally seeded challenger worlds, one committed rendered direction, a short reproducible intent contract, and separate finish comparison. Additions/refinements preserve the incumbent world. [Sources: X/@pbakaus 2079984598105358828; Impeccable skill-v4.0.4 release and skill]

• 2026-08-10 | Added animation inspectability to the standing design contract after correlating DialKit's visual timeline controls with Kevin's Fieldwork testing instruction. Motion review now requires ownership, trigger/timing evidence, controllability when feasible, and reduced-motion comparison. [Sources: X/@joshpuckett 2079014450712203291, 2026-07-20; private Discord capture, 2026-07-20]

• 2026-08-10 | Added the performance-preserving motion boundary: visible server-rendered LCP content, deferred decorative choreography, minimal client islands, and route/interaction isolation for expensive experiences. Source: X/@pontusab X Article, 2026-07-21

• 2026-07-03 | Added visual motif memory after reviewing @ayushsoni_io's blue-grid visual-system artifact: repeated geometry, grid rules, stroke weights, color roles, and motif placement should become tokens or DESIGN.md constraints before agents extend the system. Source: X/@ayushsoni_io, 2026-04-09

• 2026-06-29 | Added Inter Font as the canonical Inter source rule so design-system typography guidance distinguishes intentional Inter usage from lazy default typography, and routes implementation to rsms/inter rather than Google Fonts. Source: User correction, 2026-06-29

• 2026-06-30 | Added Copilot Design System as the AI-native system layer: design systems for agents must define presence, memory, attention, and focus handoff, not only tokens/components. Source: Microsoft Design, 2026; X bookmark artifact review, 2026-06-30

• 2026-06-26 | Added the component-source layer so the canonical design-system page routes agents to Radix, shadcn, Blocks.so, Chanh Dai, Evil Charts, Skiper, Cult, React Bits, Fancy Components, Origin UI, and Shaders.com before hand-rolling UI. Source: User request, 2026-06-26; Component Library Sources

• 2026-06-18 | Rewrote as the current canonical design-system article. Updated from Reticle-only guidance to Sigil's DESIGN.md/519-token/46-preset model, added agent constraints, component states, enforcement, and current product UI defaults. Source: User request, 2026-06-18; Sigil UI; Sigil Token Architecture

• 2026-05-13 | Exemplar public brand guidelines: Cash App's design site (design.cash.app) covering logo, color, typography, motion, iconography, cards, 3D, and tokens. Source: X/@Aurelien_Gz, 2026-05-13