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.

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.

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.

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.

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.

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

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.

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

Component Source Layer

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

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.

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.
• Icons are optically aligned and use a known icon library when appropriate.
• Motion is purposeful, interruptible, and reduced-motion aware.
• Browser screenshots confirm the rendered result.

---

Timeline

• 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