# 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`.

---

## License & attribution

This design reference is published by **8StarLabs** for **Canopy** and shared openly. You're welcome to read it, quote it, and take inspiration from it, including in slide decks, talks, articles, and personal sites.

If you reuse this document (in whole or in substantial part) or the design system it describes, please **credit Canopy** with a visible attribution and a link back to the canonical source:

> Design system by **Canopy**, https://canopy.8starlabs.com/design.md

What this permission does **not** cover: the **Canopy** and **8StarLabs** names, the logo, and the logo's gradient are trademarks of 8StarLabs. Don't use them as your own brand chrome, or in any way that implies endorsement or affiliation (see **Do / Don't** above). Third-party brand marks referenced here (via simple-icons, CC0) remain the property of their respective owners.

Want to use this without attribution, or not sure whether your use needs it? Reach out at hello@8starlabs.com.