# Canopy - Design System

> Machine-readable design + brand guidelines for Canopy. Like `llms.txt`, this
> file is meant for both humans and agents building, theming, or extending
> Canopy surfaces. Canonical: https://canopy.8starlabs.com/design.md

Canopy is a visual operational architecture workspace - **the operating system
for your stack**. _Capture. Visualize. Operate._ By 8StarLabs.

---

## Principles

- **Clean, mostly-white workspace.** Ink-on-paper feel; color used sparingly - edges, accents, the CTA band, highlighter swipes.
- **Technical, but human.** Precise layout softened by hand-drawn (Excalifont) sketch accents.
- **Light by default, full dark mode** via the `.dark` class. Every token has a light _and_ dark value.
- **Structured & legible.** A Stripe-style dashed grid (the "rails") frames content; cards sit flush with the rails.

## Voice & tone

- Direct, developer-to-developer. Confident, never hypey or salesy.
- Verb-forward triad: **Capture. Visualize. Operate.**
- Tagline: _"The operating system for your stack."_
- State what it does plainly; avoid superlatives.

## Logo & brand

- **Mark:** a single-path tree-canopy silhouette. Monochrome (adapts to `currentColor`) or the colored-gradient variant (`public/svg/canopy-logo-colored.svg`).
- **Wordmark:** "Canopy" in the display font.
- **Clearspace:** keep ~1.25rem around the lockup. Don't recolor or distort the mark.
- Brand details live at https://canopy.8starlabs.com/branding.

## Color

Colors are CSS custom properties on `:root` (light) and `.dark` (dark). A subset is exposed as Tailwind utilities: `bg-bg`, `bg-surface`, `text-fog`, `text-fog-dim`, `text-fog-faint`.

### Core (light → dark)

| Token              | Tailwind         | Light   | Dark    | Use               |
| ------------------ | ---------------- | ------- | ------- | ----------------- |
| `--bg`             | `bg-bg`          | #ffffff | #0a0b0d | page background   |
| `--surface`        | `bg-surface`     | #ffffff | #121417 | cards, panels     |
| `--surface-sunken` | -                | #f4f6f8 | #0c0e10 | insets, inputs    |
| `--fg`             | `text-fog`       | #0e1417 | #e9edf0 | primary text      |
| `--fg-dim`         | `text-fog-dim`   | #515c63 | #a6b0b8 | secondary text    |
| `--fg-faint`       | `text-fog-faint` | #8b949c | #828d96 | tertiary / labels |
| `--accent`         | -                | #0e1417 | #f5f7f8 | primary action    |

### Ink gradient (bold mono)

`--grad: linear-gradient(115deg, var(--c-1), var(--c-2) 48%, var(--c-3))` - dark inks in light mode, light inks in dark mode (`--c-1 #2A2F33` → `--c-3 #1A1F24` in light). Drives the primary button and key accents.

### Brand spectrum (the colored logo gradient)

The colored canopy mark + rare brand moments use an 8-stop spectrum, left→right: `#fdba74` peach · `#fda4af` rose · `#5eead4` teal · `#86efac` sage · `#38bdf8` sky · `#f0abfc` lilac · `#818cf8` indigo · `#22d3ee` cyan. Reserve it for the logo - never as UI chrome.

### Glass, borders, grid

- `--glass-border` (subtle 1px) and `--glass-border-hi` (emphasis + focus rings).
- `--chip` (pill / chip background), `--rail` (dashed grid lines), `--dot` (dot-grid), `--edge-base` (map edges).

### Highlighter swipes (marker accents)

Translucent marker tones behind headline words, over base hexes: `--hl-lime` #BAF064 (Capture), `--hl-blue` #7DD3FC (Visualize), `--hl-yellow` #FDE047 (Operate), plus `--hl-pink` #F9A8D4, `--hl-violet` #C4B5FD. ~0.6 alpha in light, lower in dark. Use sparingly.

### Code editor (Shiki github-dark)

`--editor-bg #0d1117`, `--editor-fg #e6edf3`; tokens `--tok-key #79c0ff`, `--tok-str #a5d6ff`, `--tok-fn #d2a8ff`, `--tok-num #79c0ff`, `--tok-comment #8b949e`.

### Status

Success `#22c55e` · Warning `#f59e0b` · Danger / destructive `#ef4444` · Rate-limit (violet) `#a78bfa` · Method/info (blue) `#38bdf8`.

## Typography

| Role        | Family                      | Tailwind       | Weights | Use                         |
| ----------- | --------------------------- | -------------- | ------- | --------------------------- |
| Display     | Bricolage Grotesque         | `font-display` | 400–700 | headlines                   |
| Body / UI   | Hanken Grotesk              | `font-sans`    | 400–600 | default text                |
| Mono / Code | JetBrains Mono              | `font-mono`    | 400–500 | code, tokens, IDs, numbers  |
| Sketch      | Excalifont (local, SIL OFL) | `font-sketch`  | 400     | hand-drawn labels / accents |

- **Headlines:** tight tracking (`-0.035em`), leading ~1.04, fluid `clamp()` sizing.
- **Body:** relaxed leading; 13–16px in UI.

## Spacing, radius, elevation

- **Gutter:** `px-6` (24px) - matched exactly by the dashed rails (a centered `max-w-6xl` frame, lines at the 24px inset). Cards align flush to the rails.
- **Radius:** `--radius: 18px` for cards; controls use `rounded-lg` / `rounded-xl`.
- **Shadows:** `--shadow-sm`, `--shadow`, `--shadow-lg` - soft, low-spread.

## Surfaces - glassmorphism

`.card` = translucent surface + 1px `--glass-border` + `--radius` + `--shadow` + `backdrop-filter: blur(16px) saturate(1.3)`. Dropdowns/menus reuse the blur with a translucent `--surface` (`color-mix(... 72%, transparent)`) and `--glass-border-hi`.

## The grid / "rails"

A fixed, centered `max-w-6xl` frame draws dashed vertical guide lines (`--rail`) at the `px-6` inset (`BackgroundRails`). Content cards sit flush to these on every breakpoint. The background also carries a faint dot-grid and hand-drawn sketch doodles (desktop only).

## Components

- **Button** (`@/components/8starlabs-ui/button`): primary = ink gradient on `--btn-fg`; `variant="ghost"` for secondary; `withArrow` adds the brand arrow; smooth opacity transition on enable/disable (`transition-btn`).
- **Card:** the `.card` glass surface.
- **Badge / Chip:** `--chip` background, pill, `text-fog-dim`.
- **Inputs:** `--surface-sunken` background, `--glass-border`, focus → `--glass-border-hi`; capped width (`max-w-md`) so they stay within the rails.
- **Code blocks:** github-dark surface, optional light toggle (`.docs-code-light`); copy + theme controls are visible on touch, hover-revealed on `sm`+.

## Iconography

- **Brand marks:** `BrandIcon` - from simple-icons (CC0) plus a few multicolor raw SVGs. Mono marks adapt to `currentColor`; colored marks keep their brand hex. ~485 integrations are covered 1:1.
- **UI icons:** `lucide-react`, rendered at `h-3.5`/`h-4` with a 1.5px stroke.

## Motion

Framer Motion (`motion/react`). Reveal-on-load (opacity + ~18px rise), eased `[0.2, 0.8, 0.2, 1]`, ~0.7s. Highlighter swipes wipe in via `scaleX`. Keep motion subtle and honor reduced-motion.

## Accessibility

- Contrast-tiered text (`fog` / `fog-dim` / `fog-faint`) checked on `bg` and `surface` in both themes.
- Full dark mode (`.dark`); `color-scheme` set per theme.
- Visible focus via `--glass-border-hi` rings; every interactive element gets `cursor: pointer`.
- Hover-only affordances (copy / theme toggles) stay visible on touch devices.

## Do / Don't

- **Do** keep surfaces mostly white/ink; reserve color for edges, accents, the CTA band, and highlighter swipes.
- **Do** align content to the `px-6` rails.
- **Don't** oversaturate or use the logo's gradient as UI chrome.
- **Don't** reproduce third-party brand marks as your own.

---

Canopy is built by **8StarLabs** (@8starlabs). Machine-readable companions: `/llms.txt`, `/sitemap.xml`, `/robots.txt`.