Reticle Design System

Reticle is a structural-visibility UI grammar: the interface shows its grid, rails, gutters, spacers, and measurement marks while keeping every line owned by one component.

Design Position

Reticle began as grid lines, margin rails, and cross marks. The current system is broader: page-level rails, full-width section rules, two-line spacer bands, diagonal hatching, square framed controls, tabular operational data, and a hard rule that adjacent components must not redraw the same hairline. Source: dedalus-labs/dedalus PR #2745 apps/website/components/ui/reticle/*, 2026-07-01; Agent-Machines web/components/reticle/*, 2026-07-01

The broader Reticle/Sigil taste direction comes from Kevin's frontend brief: high-signal design references, visible systems, 3D/parallax when earned, GSAP/Three/shader references, and a refusal to let agents pick random Tailwind classes and vibe. Source: raw/obsidian/What websites I like..md, 2026-04-06

When to use this

Use Reticle for operational surfaces where the user is inspecting systems: dashboards, agent consoles, machine fleets, usage charts, onboarding for technical products, docs-like product pages, registries, loadouts, logs, and pricing/usage flows.

Reticle should feel engineered, legible, and fast. It is not a decoration pack. Every rail, cross, hatch, and spacer should explain structure, ownership, sequence, selection, or state.

Current definition

The invariant: one visual structure, one owner.

Reticle's lines form a topology, meaning a map of which component owns each visible boundary and where boundaries meet. Page rails are owned by the page grid. Section separators are owned by the section spacer or header. Grid cell seams are owned by the parent grid through gap-px, divide-*, or sibling borders. Children join those lines; they do not redraw them.

This is the rule that prevents accidental 2px seams, darker shared borders, and jittery variation in line weight.

Color Modes

Reticle dark and light modes should be an inversion of the same offblack/offwhite substrate, not separate art directions. Dark mode uses offblack as the page field and offwhite for foreground, strong controls, selection, and focus. Light mode uses offwhite as the page field and offblack for foreground, strong controls, selection, and focus.

Accent color is subordinate to structure. Keep semantic status colors for errors/success, but do not introduce a new decorative palette just because light mode exists. Theme state should persist before first paint with a document-level attribute such as data-theme, and components should consume semantic tokens rather than branching on mode internally.

Reticle diagrams and schematic art should also be token-aware. Prefer inline SVG or componentized drawing primitives that consume the same semantic tokens as the UI. Avoid static dark-only SVGs for surfaces with a light mode; they make the theme feel like a skin over an old asset.

Reticle shader backgrounds should be routed through a bounded default provider, currently ReticleShaderProvider backed by shaders/react. The default stack is Shader plus FlowingGradient, Grid, and FilmGrain; it belongs behind specimen art and should be non-interactive, clipped to the frame, subordinate to seams/labels, and disabled only as a background layer. It must not replace structural rails, hatching, or the token-aware SVG diagram. Source: Reticle Design System Demo, 2026-07-01

Viewport-height units are structural tools, not defaults. Use 100dvh only for bounded first-viewport shells, modal/workspace canvases, or explicitly viewport-sized panels. Ordinary content sections should remain content-sized. On desktop, cap dvh shells with clamp() or an explicit max block size so tall monitors do not create empty slabs after the real content ends.

Control Bay

Reticle demos should expose their aesthetic primitives as controls when the goal is design-system inspection. The control bay should use persisted document-level state so page attributes, CSS, React motion, and first paint all agree.

The current demo control set is:

Controls are part of the demo surface, not preference clutter. Use Lucide icons, square hit targets, active-state inversion, and compact mono labels. Do not let control labels resize the layout; use stable grid tracks and responsive wrapping. Source: Hark Next 16 Reticle demo control bay, 2026-07-01

Core grammar

Page layout

Reticle has two compatible page-grid implementations:

Both express the same idea: content is constrained, but structure can span the viewport. The rails are part of the page, not each section. A section rendered inside a page grid should detect that context and skip its own gutters/rails. Source: dedalus-labs/dedalus PR #2745 ReticleSection.tsx; Agent-Machines ReticlePageGrid.tsx

Corner crosses are optional structural markers, not the boundary itself. If a page needs to inspect the design with markers on and off, gate them with a persistent document-level switch such as data-reticle-crosses="visible|hidden". Hiding crosses should remove only the marker pseudo-elements or ReticleCross primitives; it must not remove borders, rails, hatching, schematic art, or seam declarations. Source: Hark Next 16 landing page corner-cross switch, 2026-07-01

Margins and gutters

Reticle margins are visible but low-priority. They can show:

• half-cell horizontal rail ticks in the outer margin
• narrow vertical gutters between margin and content
• diagonal hatch in the strip hugging the content edge
• empty gutter strips outside the hatched margin

The topology is margin | gutter | main content | gutter | margin. Gutters and margins are outside the main content measure; they are not decorative bands drawn over the content rail. The key is ownership. Page margins and gutters are continuous across the page. Sections may paint their content background so hatching stops cleanly at the rails, but they should not create a second rail system unless they are outside ReticlePageGrid.

When margin/gutter visibility is used for inspection or design debugging, expose it as a persistent switch rather than permanent page chrome. The overlay should be fixed, non-interactive, token-colored, and excluded from seam ownership. It may label margin and gutter, but it must not capture pointer events, draw competing component borders, create horizontal overflow, or place gutters inside the central content rail. Source: Hark Next 16 landing page layout overlay, 2026-07-01

Lines and spacers

Reticle has three separator classes:

The Agent Machines ReticleSpacer is the canonical section transition primitive: it renders a full-width bounded strip, optional hatch fill, and cross marks at content-edge intersections. Source: Agent-Machines web/components/reticle/ReticleSpacer.tsx, 2026-07-01

For dense dashboard surfaces, whitespace-only section separation can be correct. Dedalus PR #2745 uses DashboardSection with padding and a ReticleFrame wrapper so related panels read as one operational workspace rather than a stack of boxed cards. Source: dedalus-labs/dedalus PR #2745 DashboardHero.tsx, machines/usage/page.tsx, 2026-07-01

Avoiding double lines

Reticle fails when a shared boundary is painted twice.

Use these rules:

1. If a parent uses gap-px bg-[var(--ret-border)], child cells use bg-[var(--ret-bg)] and no adjacent border.
2. If rows use divide-y, row children do not add border-t or border-b.
3. If a section uses ReticleSpacer, nearby sections set their own borderTop/borderBottom off or rely on the spacer.
4. If a page grid owns vertical rails, nested sections only paint content boundaries.
5. If two borders meet on the same pixel, delete one and move the semantic ownership upward.

This is the practical Reticle version of line topology: shared seams must be single-source.

Reticle components should make seam ownership machine-checkable. The current contract:

The guard is intentionally responsive-aware: if CSS removes a border at a breakpoint, the computed border is not counted as an owned seam. A production surface should be considered visually clean only when rendered desktop and mobile checks both report zero seam conflicts. Source: Hark Next 16 landing page seam guard, 2026-07-01

Diagonal lines

Diagonal hatching should be geometric, sparse, and structural.

Recommended default: repeating-linear-gradient(45deg, var(--ret-rail) 0 1px, transparent 1px 8px). Use --ret-rail rather than --ret-border so hatching sits below real boundaries in visual weight. Source: Agent-Machines ReticleHatch.tsx; ReticleHRule.tsx

Component catalog

The current Dedalus product branch adds practical dashboard components: DashboardHero, DashboardSection, MachinesComingSoonPanel, MetricRail, machine filters, tabbed quickstart panels, and usage charts. They are Reticle-compatible even when not named Reticle* because they consume --ret-*, square controls, shared hairlines, and tabular operational data. Source: dedalus-labs/dedalus PR #2745, 2026-07-01

Product style

Reticle's product aesthetic is quiet and operational:

• square edges and low shadows
• real data over decorative blocks
• direct hero headlines that name the user action or product job
• tabular numerals for usage, billing, IDs, and machine resources
• mono uppercase labels for structure, not prose
• command/code surfaces with copy affordances
• segmented controls as one shared-border object
• active states around 100-160ms
• skeletons that preserve final dimensions
• no visible scrollbars on core panels
• hovers that change border/color/background without resizing layout

Dedalus PR #2745 is the restrained version: dashboards use ReticleFrame, square controls, dense tables, usage rails, line/bar charts, and short product copy. Agent Machines is the expressive version: page rails, spacer bands, hatch strips, circuit art, Reticle frames, and 3D/console surfaces. Source: dedalus-labs/dedalus PR #2745; Agent-Machines web/app/page.tsx, web/components/reticle/*

Icon, Loading, and Motion Standards

Reticle's interaction layer should be boring in code and sharp in the viewport.

Lucide is the default icon set for actions, status, navigation, labels, and tool controls. Import individual lucide-react icons so bundlers can tree-shake unused symbols; Lucide React exports typed, customizable inline SVG components. Do not hand-draw generic action SVGs when Lucide already has the symbol. Reticle-specific brand marks, schematics, circuit art, charts, and diagrams may still use custom inline SVG because those are identity or data artifacts rather than generic icons. Source: Lucide React docs, 2026-07-01

Loading defaults to skeletons for layout-bearing regions and Unicode/Braille animation for small inline pending states. The unicode-animations package provides raw spinner frame data as { frames, interval }, which keeps loading indicators asset-free, token-colored, and compact. Avoid Lucide Loader, Loader2, CSS ring spinners, and spinner-only blank screens. Loading should preserve the final component dimensions and expose accessible status text. Source: Frontend and Design Skills; Spinners Collection; unicode-animations README, 2026-07-01

Motion uses the Emil/animations.dev vocabulary: stagger, direction-aware entrance, crossfade, and layout animation. Name the motion's job before adding it. Frequent actions should resolve in roughly 100ms and avoid ornamental motion; page or component entrances can use 180-260ms ease-out timing. Use CSS transitions for hover, focus, press, theme, and simple opacity/transform. Use Motion for React when component state, layout, gestures, or shared motion needs a real animation runtime. Use GSAP only for timeline-heavy scroll or choreography; use Lottie only for supplied vector assets; use Three/WebGL only when a real 3D scene carries product meaning. Source: Animation Vocabulary (Animations.dev); Animations.dev; Motion for React docs, 2026-07-01

View transitions are progressive enhancement. The CSS pseudo-elements and timing hooks can live in global CSS, but Next's experimental.viewTransition flag should be enabled only when route/shared-element transitions are a product requirement and the team accepts the experimental support boundary. React/Next view transitions are not the default for ordinary one-route product pages. Source: CSS View Transitions API; React View Transitions; Next.js View Transitions docs, 2026-07-01

Global CSS hacks belong in one base layer: hidden scrollbars, scroll-padding-top for anchored navigation, overscroll-behavior, antialiasing, tokenized durations/easings, prefers-reduced-motion, and platform-specific view-transition hooks. Do not copy scrollbar, motion, or focus hacks into every component. Components should consume tokens such as --ret-duration-base, --ret-ease-out, --ret-icon-size, --ret-border, and --ret-focus. Source: CSS UI Enforcement; Jhey CSS Techniques

Token model

Reticle tokens should be split by role:

Component code consumes semantic tokens, not raw primitives. One exception is chart SVG output where literal colors may be necessary because third-party chart libraries can resolve scoped CSS variables late during screenshots. When that exception exists, document it near the chart color list. Source: dedalus-labs/dedalus PR #2745 usage/stack.tsx

DESIGN.md format

Reticle needs a markdown source of truth with both tokens and prose constraints. A minimal project DESIGN.md should include:

---
name: reticle
tokens:
  reticle:
    hairline: 1px
    contentMax: 1400px
    railOffset: 4rem
    gridCell: 48px
    railGap: 24px
    crossArm: 10px
    radius: 0px
  color:
    background: "#09090b"
    surface: "#111113"
    text: "rgba(255,255,255,0.9)"
    border: "rgba(255,255,255,0.16)"
    rail: "rgba(255,255,255,0.14)"
    cross: "rgba(255,255,255,0.22)"
    accent: "#ededed"
  motion:
    press: 140ms
    hover: 160ms
    page: 320ms
---

# Reticle

## Grammar

One component owns each visible hairline. Page grids own rails. Spacers own section transitions. Grids own cell seams.

## Layout

Use a centered content column with visible rails/gutters. Let separators span the viewport when they define the page rhythm.

## Components

- ReticlePageGrid
- ReticleSection
- ReticleSpacer
- ReticleFrame
- ReticleHatch
- ReticleLabel
- ReticleButton

## Do

- Use `gap-px` plus child backgrounds for shared seams.
- Use tabular numbers for resource and billing data.
- Use diagonal hatch only for structural fills.

## Do not

- Stack two borders on the same seam.
- Nest cards inside cards.
- Add rounded controls unless the project preset changes the radius token.
- Hardcode colors outside chart-library escape hatches.

This is the bridge between DESIGN.md as an agent-readable format and Sigil Token Architecture as Kevin's local token compiler.

Agent rules

When an agent builds Reticle UI:

1. Read the local DESIGN.md or Reticle page first.
2. Identify the line owner before adding any border.
3. Use layout primitives before composing ad hoc div wrappers.
4. Keep controls square, dense, and token-driven.
5. Use diagonal hatch and cross marks only at structural boundaries.
6. Verify screenshots for seam thickness, text fit, mobile overflow, and hidden scrollbars.
7. If a pattern repeats, promote it into a Reticle component or token.
8. Keep display headings word-intact. If a heading does not fit, reduce the type scale, adjust the measure, or rewrite the copy; do not use overflow-wrap: anywhere, word-break: break-all, or hyphenation on hero/display text.
9. Keep dark and light modes as offblack/offwhite inversions. Persist the selected mode before paint and avoid separate mode-specific palettes.
10. Make Reticle diagrams token-aware when they appear in themed UI; use inline SVG/components instead of static dark-only assets.
11. Apply 100dvh selectively. Bound first-viewport shells with clamp()/max block size; do not put viewport height on body, every section, or repeated content panels.
12. Use Lucide icons for generic actions, status, navigation, labels, and controls; reserve custom SVG for brand, diagrams, charts, and product-specific illustration.
13. Use skeletons or Unicode/Braille loading states; avoid Lucide/CSS ring spinners and spinner-only blank screens.
14. Route motion deliberately: CSS for simple UI feedback, Motion for React for component/layout/gesture state, GSAP/Lottie/Three only when the surface truly needs them.
15. Put scrollbar, reduced-motion, view-transition, focus, and smoothing hacks in global CSS once, then consume tokens from components.
16. Avoid hero headlines that start with generic articles such as "The", "A", or "An". Prefer a direct action, product noun, or named object.
17. Avoid the "The [abstract noun] for ..." headline pattern. It reads like generic agent-written marketing copy and forces large stacked text.
18. Keep Reticle hero type interface-scaled. If a heading becomes poster-scale stacked slabs, reduce size/weight or rewrite the headline.
19. Use seam-grid parents and edge declarations for touching Reticle panels; verify data-reticle-seam-conflicts="0" at desktop and mobile widths.
20. Use a persistent non-interactive margin/gutter overlay switch when page topology needs debugging. The overlay should show structure without resizing content or declaring owned seams.
21. Use a persistent document-level corner-cross switch when marker density needs inspection. The switch should hide only optional crosses, not borders, rails, diagrams, or seam ownership.
22. Use a control bay for design-system demos. Each aesthetic primitive should map to a document-level attribute, a persisted storage key, and a visible rendered effect.
23. Keep Reticle gutters and margins outside the main content measure. If the viewport is narrow, shrink the central content rail rather than drawing gutters over it.
24. Use ReticleShaderProvider for shader-backed Reticle specimen art; keep the shader clipped to the frame, pointer-inert, and behind the token-aware SVG.

Failure modes

---

Timeline

• 2026-07-01 | Clarified the Reticle page topology after the demo gutter overlay incorrectly placed gutters inside the main content measure. Reticle page geometry should be margin | gutter | main content | gutter | margin, and narrow viewports should shrink the content rail rather than drawing gutters over content. Source: User request, 2026-07-01
• 2026-07-01 | Added the Reticle control-bay rule after the Hark-inspired page became a Reticle Design System Demo. Reticle demo controls should expose aesthetic primitives through persisted document-level attributes for theme, density, rails, gutters, crosses, hatching, schematic art, labels, and motion. Source: User request, 2026-07-01
• 2026-07-01 | Added the Reticle corner-cross switch rule after the Hark landing page needed optional corner markers. Corner crosses should be controlled by persistent document-level state and hiding them should not remove structural borders, rails, hatching, diagrams, or seam ownership. Source: User request, 2026-07-01
• 2026-07-01 | Added the Reticle margin/gutter overlay rule after the Hark landing page needed a switch to show page topology while preserving layout and seam ownership. Diagnostic overlays should be persistent, fixed, pointer-events-none, token-aware, and verified with zero seam conflicts and no horizontal overflow. Source: User request, 2026-07-01
• 2026-07-01 | Added the machine-checkable Reticle seam ownership contract after the Hark landing page still showed double borders between adjacent hero panels. The system uses seam-grid parents, child cells without adjacent borders, data-reticle-edges declarations, and a responsive ReticleSeamGuard that verifies zero duplicate seam ownership in rendered viewports. Source: User screenshot/request, 2026-07-01
• 2026-07-01 | Added a Reticle hero-copy guardrail after the Hark landing page used a generic "The execution surface for..." headline with oversized stacked type. Reticle hero headlines should avoid article-led "The/A/An" starts, avoid "The [abstract noun] for..." patterns, and stay interface-scaled. Source: User screenshot/request, 2026-07-01
• 2026-07-01 | Added Reticle standards for Lucide icons, Unicode/Braille loading, Emil/Motion animation routing, progressive view-transition hooks, and centralized CSS platform hacks after the Hark landing page needed those decisions codified into the design system. Source: User request, 2026-07-01; Lucide React docs; Motion for React docs; unicode-animations README; Next.js View Transitions docs
• 2026-07-01 | Added the Reticle color-mode rule: dark and light modes should be offblack/offwhite inversions using semantic tokens, with persisted pre-paint theme state and no separate light-mode palette. Source: User request, 2026-07-01
• 2026-07-01 | Added the Reticle diagram theming rule after replacing the Hark landing page's hardcoded dark SVG with a token-aware inline schematic. Source: User request, 2026-07-01
• 2026-07-01 | Added the default Reticle shader provider rule after the Reticle demo added a shaders/react background stack behind the isometric logo diagram. Shader backgrounds should be bounded, pointer-inert, and subordinate to structural SVG. Source: User request, 2026-07-01
• 2026-07-01 | Added the bounded viewport-height rule after the Hark landing page showed how unbounded first-viewport sections can create large empty slabs on tall desktop viewports. Source: User screenshot/request, 2026-07-01
• 2026-07-01 | Design category refresh added this page to the Identity, tokens, and visual grammar family, linked it to Design System Map, and kept it standalone because Reticle Design System owns a distinct design decision surface in this family. Source: User request, 2026-07-01
• 2026-07-01 | Added a Reticle guardrail against page-wide decorative grid wallpaper and mid-word display heading breaks after the Hark landing page mobile hero split "execution" and "everyday" across lines. Source: User screenshot/request, 2026-07-01
• 2026-07-01 | Rewrote Reticle as a full structural-visibility grammar after inspecting Dedalus PR #2745 and the Agent Machines Reticle implementation. Added page-grid, margin/gutter, spacer-band, diagonal-hatch, line-topology, component-catalog, and DESIGN.md format rules. Source: dedalus-labs/dedalus PR #2745 codex/final-dashboard-onboarding-ui; Agent-Machines web/components/reticle/*
• 2026-05-12 | Reticle cited as the Agent Machines UI exemplar: five-column grid, cross marks, mono labels, and Sigil constraints. Source: Agent Authored UI Style; Agent Machines
• 2026-04-06 | Initial Reticle page created from the website Reticle component folder and Kevin's frontend brief. Source: apps/website/components/ui/reticle/; raw/obsidian/What websites I like..md