Developer Guide

Design Philosophy

Premium, purposeful, alive.This is not a docs site. It's an interactive architecture visualization — a living system map that feels like you're navigating something powerful. Every design decision serves two masters: beauty and clarity.

Inspirations

Anti-Patterns — Never Do This

• ✗Boring docs site aesthetics (Docusaurus, GitBook, ReadTheDocs look)
• ✗Cluttered layouts with no breathing room
• ✗Pure black backgrounds (#000000) — too harsh, causes halation
• ✗Neon/oversaturated accent colors — eye strain on dark backgrounds
• ✗Decorative animation with no purpose — every motion must communicate something

Color System

Dark UI uses surface elevation to create depth — lighter greys float above darker greys. One accent color, used sparingly. Status colors are desaturated for dark mode comfort.

Surface Elevation

Text Hierarchy

Use opacity/weight — not color — to create text hierarchy. Never use pure white (#ffffff) for body text.

Borders

Accent Color

One accent color, used sparingly. Desaturated to ~80% saturation for dark mode comfort.

Status Colors

Used for implementation status indicators in diagrams and component cards. Never use for large backgrounds or text.

Typography

Font Families

Geist is installed via the geist npm package and loaded through next/font/local for optimal performance.

Type Scale

Based on a 1.250 ratio (Major Third), anchored at 16px body. All line-heights divisible by 4.

Typography Rules

• —Headlines use --text-primary (zinc-50), weight 600-700
• —Body uses --text-secondary (zinc-400), weight 400
• —Maximum body text width: 65ch (optimal reading length)
• —Negative letter-spacing on headlines (-0.01 to -0.02em) for tighter, more modern feel
• —Positive letter-spacing on captions (+0.02em) for legibility at small sizes

Spacing System

8pt grid with 4pt half-step for fine adjustments. Generous spacing creates the premium feel — when in doubt, add more whitespace, not less.

Spacing Principles

• Internal < External:Padding inside a card should always be less than the gap between cards
• Group by proximity:Related items sit closer together than unrelated items (Gestalt principle)
• Scale with importance:More whitespace around more important elements
• Consistent rhythm:Vertical spacing between sections should follow a predictable pattern

Border Radius

Slightly rounded, never fully circular (except status dots). Consistent across all components.

Shadows & Glow

In dark mode, traditional box-shadows are barely visible. Use subtle borders for card edges, glow effects for interactive/focused elements, and gradient overlays for depth.

Motion & Animation

Motion is communication, not decoration. Every animation should answer: "What just changed?" or "Where should I look?"

Timing Tokens

Easing Functions

Motion Patterns

• Page transitions:Fade + subtle Y-translate (8-12px). Use <AnimatePresence> for route changes.
• Cards entering view:Staggered fade-up on scroll intersection. 50ms stagger between siblings.
• Diagram nodes:Scale from 0.95 + fade on first render. Use spring easing.
• Signal flow dots:CSS offset-path animation along React Flow edge SVG paths. Continuous loop, --duration-dramatic per cycle.
• Hover effects:Scale 1.02 + glow on cards. Immediate response (150ms).
• Sidebar items:Subtle background-color fade on hover (150ms).

Motion Rules

• —Respect prefers-reduced-motion — disable all animations when set
• —No animation should run longer than 1s except ambient loops (signal flows)
• —Stagger delays should never exceed 300ms total for a group
• —Loading states use subtle pulse, never spinners

Layout

Page Structure

Sidebar Specs

• —Width: 240px (fixed, collapsible on mobile)
• —Background: --bg-surface
• —Left border: none. Right border: --border-subtle
• —Items: 36px height, --space-2 vertical gap
• —Active item: --bg-elevated background + --accent left accent (2px)
• —Sections: grouped with caption labels, --space-6 between groups

Top Bar Specs

• —Height: 48px (fixed)
• —Background: --bg-base with subtle bottom border
• —Contains: logo (left), breadcrumb trail (center-left), user/auth info (right)
• —Backdrop blur when content scrolls underneath: backdrop-filter: blur(12px)

Content Area

• —Max width: 1200px, centered
• —Padding: --space-8 on desktop, --space-4 on mobile
• —Full-bleed diagrams can break out of max-width constraint

Responsive Breakpoints

Sidebar collapses to hamburger below lg.

Component Patterns

Architecture Node (React Flow)

• —Background: --bg-surface
• —Border: 1px --border-subtle, left border 3px in status color
• —Border radius: --radius-md, padding: --space-4
• —Min width: 200px, max width: 280px
• —Hover: scale 1.02, border → --border-default, shadow → --glow-accent
• —Click: navigates to drill-down view

Breadcrumb Trail

• —Separator: › in --text-ghost
• —Hover on ancestors: --accent color
• —Smooth text-color transition on hover (150ms)

Status Badge

• —Dot: 8px circle with status color
• —Label: caption size, --text-secondary
• —Inline with metadata, not standalone

Card (Content Section)

• —Background: --bg-surface
• —Border: 1px --border-subtle
• —Border radius: --radius-lg
• —Padding: --space-6
• —Margin bottom: --space-8

Vision Subsection Card (Expandable)

For long vision sections that benefit from progressive disclosure — summary always visible, full narrative behind a chevron click.

• —Background: --bg-surface, border: 1px --border-subtle
• —Border radius: --radius-md (8px), padding: --space-6 (24px)
• —Gap between cards: --space-4 (16px)
• —Title: h3 (22px, font-semibold, --text-primary)
• —Summary: body (16px, --text-secondary)
• —Chevron: --text-muted, rotates 90° on expand (250ms, ease-default)
• —Hover: background shifts to --bg-elevated (150ms)
• —Expand animation: height auto-transition + content fade-in (250ms, ease-default)
• —Top border accent: 2px --accent-muted on left side when expanded
• —Max content width: 65ch (same as vision text)

Changelog Entry

• —Date in mono font, --text-muted
• —Description in body-sm, --text-secondary
• —Subtle left border in --accent-muted
• —Entries stack vertically with --space-3 gap

Diagram Conventions (React Flow)

Color Coding

• —Node background: status color at 10% opacity
• —Node border: status color at 60% opacity
• —Node text: always --text-primary (never colored)

Edge Styling

• —Default: 1.5px stroke, --border-default color
• —Animated: signal dots (4px circles) moving along path, accent-colored
• —Hover: edge thickens to 2px, color shifts to --accent

Layout

• —Horizontal flow for Level 1 (left to right = signal flow direction)
• —Vertical grouping for Level 2 (sections stacked, connections between)
• —Free-form for Level 3 (components within a section)

Interaction

• —Click node → smooth zoom transition to next level (Motion animate layout)
• —Hover node → tooltip with brief description + status
• —Minimap visible at Level 1 and 2, hidden at Level 3+

Accessibility

• ContrastMinimum contrast ratio: 4.5:1 for body text, 3:1 for large text (WCAG AA)
• Status colorsAll status colors paired with text labels or icons (never color-only)
• Focus rings2px --accent outline with 2px offset
• Keyboard navigationFull tab-through for sidebar, breadcrumbs, diagram nodes
• prefers-reduced-motionDisable all CSS/JS animations, show static diagrams
• Screen readerDiagram nodes have descriptive aria-labels

File Organization

The project follows Next.js App Router conventions. All content lives in TypeScript data files — never hardcoded in components.

Data Architecture

All content lives in TypeScript data files under src/lib/data/. Components read from these files — content is never hardcoded in JSX.

Section Page Schema (/blocks/[section])

Each Building Block section page follows a consistent structure:

1. 1.
   Header

   Section title, one-sentence description, overall status badge (live / partial / planned).

2. 2.
   Vision

   What this section does conceptually (from AA-0957) and why it matters in the larger system. Long sections use visionSections (expandable subsections with summary + full content); shorter ones use the vision string directly.

3. 3.
   Components Grid

   Each skill, cron, adapter, or tool — name, one-line description, status (🟢 live / 🟡 partial / 🔴 planned / 🔵 external). Click navigates to the component detail page.

4. 4.
   Notes

   Open ideas and future plans (from AA-0957 📝 Notes sections). Things to build next.

Component Page Schema (/blocks/[section]/[component])

Each component detail page shows:

1. 1.What it doesPurpose and behavior.
2. 2.How it worksBrief technical description.
3. 3.StatusImplementation status with details.
4. 4.ConfigurationKey config and env vars (names only, never values).
5. 5.Connected toWhich other components or sections it interacts with.
6. 6.LinksSkill file path, relevant Case in Dymont DB.

C4 Zoom Navigation

The Building Block View uses C4-inspired progressive zoom — three levels of detail, navigated by clicking deeper.

• —Sidebar always shows all sections for quick jumping
• —Breadcrumbs show current zoom level: Blocks → Section → Component
• —Cards are clickable — click to zoom in. Back / breadcrumbs to zoom out.
• —Level 1 (System Context) is /context — a different view (external boundaries), not part of the Building Block zoom.

Implementation Rules

These rules apply to anyone writing code in this repo. Violating them breaks the site architecture.

1. 1.
   Read this page first

   Before any UI work, the design tokens and patterns above are non-negotiable.

2. 2.
   All content in src/lib/data/

   Never hardcode text in components — structure and content are separated.

3. 3.
   Use CSS custom properties

   From globals.css — never raw hex values or magic numbers.

4. 4.
   Test at 1280px viewport as primary

   Verify 640px mobile works too. Don't ship without checking both.

5. 5.
   Status colors come from data

   Green/amber/red/blue mapped to live/partial/planned/external — never hardcoded per component.

6. 6.
   Don't delete existing components

   Keep unused components — they're for future use.

7. 7.
   Run npm run build after all changes

   Fix all TypeScript and build errors until clean before deploying.

8. 8.
   Respect the arc42 structure

   Don't add pages outside the defined structure without collaborative discussion.

9. 9.
   Use cases go in Runtime, not Building Blocks

   If a scenario touches multiple blocks, it belongs in the Runtime View.

10. 10.
    Building Blocks are containers, not features

    Deliverables go on the Roadmap. Structural components go in Building Blocks.

11. 11.
    When in doubt, more whitespace, less decoration

    Premium feel comes from breathing room and restraint.

Build & Deploy

The local repo on coexo-labs has no git remote — deploys flow over rsync to openclaw-vps, where Docker rebuilds the image and Cloudflare cache is purged.

Local Dev

Runs the Next.js dev server on port 3000.

Check for Errors

Fix all TypeScript errors, import issues, and build warnings until the output is clean.

Deploy to coexo.dymont.ai

deploy.sh rebuilds the Docker image with no cache, recreates the container, and purges Cloudflare so changes appear immediately.

Test Checklist

• ✓Test at 1280px — primary viewport
• ✓Verify 640px mobile works (sidebar collapses, content readable)
• ✓Check all links navigate correctly
• ✓Verify status badge colors render correctly
• ✓Confirm no TypeScript errors in console