Planton Design System

The Planton platform uses a monochrome visual language across every surface — marketing website, web console, micro-apps, and CLI — where color is reserved exclusively for semantic status and provider brand identity. Dark mode is the default. Hierarchy comes from luminance and borders, never from decorative hue.

Purpose and Audience

This document is the canonical reference for the Planton visual language. It covers every user-facing surface of the platform and establishes the rules that all implementations must follow.

Who this is for:

• Contributors — Engineers and AI agents building on the Planton codebase. Every pattern here must exist in code, and every pattern in code must trace back here.
• Partners and integrators — Anyone building experiences that sit alongside or within Planton's UI.
• LLM agents — This document is available as raw markdown at /branding/design-system.md for programmatic consumption.

Planton is a 61+ package monorepo developed primarily by AI agents. The code is the documentation — there are no separate Figma files or design handoffs. If a pattern exists in this document, it must exist in the codebase, and vice versa.

Design Philosophy

Monochrome, Data-Dense, Dark-First

The visual language is inspired by GitHub Dark Default and the density of tools like Cursor. The rationale:

• No colored chrome. Navigation, headers, sidebars, buttons, tabs, and interactive elements use neutral grays. Color is reserved for semantic status (success, error, warning) and provider brand logos.
• Dark as default. New users start in dark mode across all surfaces. Light mode is available and persists via cookie/localStorage.
• Hierarchy by luminance. Visual priority is established through brightness steps in the gray ramp, not through competing hues. A reader should understand information hierarchy without learning a color code.
• Borders, not backgrounds. Cards and sections are separated by borders, not by contrasting background colors. This is the GitHub pattern (unified canvas) rather than the VS Code pattern (dark frame).
• Honest semantics. Green, red, and amber appear only where they carry meaning — deployment status, validation errors, capacity warnings. They are never decorative.

What Was Removed

The monochrome system was established by removing: purple/sky/cyan gradient text and buttons, tinted cards, colored navigation dropdowns, rainbow compliance badges, gradient orbs, and decorative accent colors. Legacy hex values like #7c3aed (purple), #0ea5e9 (sky), #0099FF (pricing blue), #FDA935 (gold), and #6665D2 (Discord purple) were all replaced with the neutral palette.

The Dual-Surface Model

Planton has two primary web surfaces that share the same visual language but use different implementation stacks:

Why Different Background Shades

The website uses #0a0a0a (near-black) for a marketing-appropriate depth. The console uses #0d1117 (GitHub's canvas color) because it provides better contrast ratios for data-dense UI — tables, code viewers, graphs, and nested panels — where WCAG compliance matters at every text size.

Both surfaces share the same design principles: monochrome chrome, semantic-only color, border-based separation, and Inter typography. The implementation differs because each surface optimizes for its use case.

Color System

Website Palette

The website palette is defined once, in the website-shell package's tokens.ts, and projected into both the MUI theme and Tailwind. Components use the role-named Tailwind classes below and never type a hex; the hex column is for the reader, not for code.

Two card surfaces exist on purpose. Marketing cards are #151515, one step above the canvas, separated from it by a border rather than a fill; the lighter #1a1a1a is the surface that sits on a card (an input, a pill, a tooltip, a code block) so it reads as raised. An earlier revision of this table listed cards as #1a1a1a while every card on the site painted #151515; the palette now records what the pixels do.

The Tailwind white token is overridden to #ededed for body text. Call-to-action buttons use bg-cta to retain true white contrast.

Console Palette (Dark Mode)

The console uses a GitHub Dark Default-aligned token ramp.

Console Palette (Light Mode)

Semantic Color Budget

Status colors are identical in spirit across both surfaces. They are reserved exclusively for functional severity — never decoration.

Info is gray, not blue. This is intentional. In a monochrome system, blue would be the only hue-based accent in the chrome, breaking the visual language. Info severity uses neutral gray; decorative uses of info.main are replaced with text.secondary or divider.

Provider Brand Colors

Provider logos (AWS, GCP, Azure, Kubernetes, GitHub, GitLab) always render in their original brand colors. They are never converted to monochrome. In data contexts — org graphs, connection panels, resource lists — provider color serves a functional identification purpose.

Providers with poor contrast on dark backgrounds (AWS, GitHub) have dedicated dark-mode SVG variants.

Typography

Font Stack

Inter is the sole typeface across all Planton surfaces — website, console, micro-apps, and documentation.

font-family: 'Inter', system-ui, -apple-system, sans-serif;

Loaded via next/font/google with weights 300, 400, 500, 600, and 700. The CSS variable --font-inter is set on the root element.

Weight Scale

Heading Hierarchy (Website)

Content pages (docs, tutorials, blog) use a calmer brightness tier than marketing pages. All headings, section titles, sidebar labels, table headers, and contributor names use #b0b0b0 (secondary.80) — ~10% brighter than body text (#a0a0a0). Size and weight carry the structural hierarchy; the subtle brightness lift aids scanning without creating visual fatigue in dense documentation. Marketing page headings (features, pricing, solutions, landing) continue to use #ededed.

Body text is 16px #a0a0a0 with tracking-tight in prose contexts. Heading class constants are centralized in src/theme/docs.ts.

The #b0b0b0 treatment extends beyond headings to all content-area chrome: markdown table headers, sidebar section titles ("Planton Documentation", "Tutorials", "On this page", "Contributors"), tutorial list entry titles, sort controls, and author names. Interactive states (hover, active/selected) remain text-white for feedback contrast.

Console Typography

The console inherits Inter through the MUI theme. MUI's default typography scale applies, with textTransform: 'none' and letterSpacing: '-0.011em' on buttons to match the website's density.

Surface Hierarchy

Both surfaces use a unified canvas approach where the header, sidebar, and content area share the same base background. Visual hierarchy comes from borders and subtle surface-level differentiation, not from competing background shades.

Website Surfaces

Console Surfaces (Dark)

Console Surfaces (Light)

Card Separation

Cards are separated by borders, not background color differences. The console applies a global MuiCard override with border: 1px solid ${theme.palette.divider}. The website uses border-[#2a2a2a] on card elements. Individual components do not declare their own borders — the system provides them.

MUI's dark-mode elevation overlay (backgroundImage: linear-gradient(rgba(255,255,255,...))) is disabled globally via backgroundImage: 'none' on MuiPaper.root and MuiAppBar.root. All surfaces render at their exact backgroundColor with no hidden gradients.

Button Hierarchy

Website Buttons

Primary CTAs use true #ffffff (not the #ededed text override) to maintain maximum contrast. The black text on white surface inverts the page's dark-on-light relationship, drawing the eye.

Console Buttons

The CTA inversion pattern: containedPrimary button text uses background.default (the page background color). This creates dark-on-light in dark mode and white-on-dark in light mode, and automatically adapts if the page background changes.

Icon Rules

Monochrome overrides for navigation icons are applied at the consumption site (e.g., in header actions), not in the icon library. Colored variants remain available for data contexts where color serves a functional purpose.

Provider icons with poor contrast on dark backgrounds have dark-mode SVG variants in public/connectors/. A utility function handles selection based on the current theme mode. For library packages that cannot import console utilities, an inline dark icon map constant is used.

Dark and Light Mode

Dark as Default

All Planton surfaces default to dark mode. The resolution chain for determining the active theme is:

1. Cookie (planton_theme)
2. localStorage
3. Fallback: 'dark'

System prefers-color-scheme is not used. Dark is the brand default; users who prefer light mode persist their choice via the toggle.

Flash Prevention

Both the website and console use an inline <script> in the root layout that executes before React hydration:

1. Reads theme from cookie → localStorage → defaults to 'dark'
2. Sets document.documentElement.style.backgroundColor to the appropriate canvas color
3. Sets document.documentElement.style.colorScheme for native browser element styling (scrollbars, autofill)

This prevents a white flash on dark-mode pages during the hydration gap.

The console's error boundary (global-error.tsx) has its own independent theme detection using the same resolution chain, because it renders without ThemeProvider access.

Console Token Pipeline

The console's color system flows through a strict five-layer pipeline. There are no alternative styling systems.

Token ramps           →  Palette config        →  createTheme()     →  ThemeProvider      →  Components
(dark-colors.ts)         (dark.tsx)                (theme.ts)           (appContext.tsx)       (styled.ts)
(light-colors.ts)        (light.tsx)

Layer 1: Token Ramps

Files dark-colors.ts and light-colors.ts each export 9 color ramps (objects with numeric keys 0–100). These are the single source of truth for every hex code in the console.

Layer 2: Palette Config

Files dark.tsx and light.tsx map raw ramp slots to MUI semantic roles (palette.background.default, palette.text.primary, palette.divider, etc.) and define component overrides. The palette config uses direct ramp imports. Component overrides use theme.palette.* exclusively — never direct ramp imports.

Layer 3: Theme Creation

File theme.ts exports appTheme(type, font) which calls createTheme() with the appropriate ThemeOptions. Also exports shared helpers consumed by both dark and light overrides.

Layer 4: ThemeProvider

File appContext.tsx manages theme state with the 3-step resolution chain (cookie → localStorage → dark) and wraps the app in MUI's ThemeProvider.

Layer 5: Cross-Package Theme Access

The console's 61+ library packages access the theme through two mechanisms:

• useTheme() — MUI's built-in hook for theme.palette.* in styled-components.
• PlantonThemeContext — A lightweight context providing { mode: 'light' | 'dark' } for cases where a library component needs the current mode explicitly (e.g., selecting a dark variant of a provider icon).

Graph and Visualization Colors

Centralized in graph-colors.ts, these use desaturated tinted grays (~25–40% saturation) that harmonize with the monochrome chrome while preserving hue families for functional differentiation.

Code Syntax Highlighting

Code blocks are content islands where muted hue differentiation serves a functional purpose — readability — similar to how provider logos keep brand colors and graph nodes use desaturated tints. The principle is the same as the console's graph-colors.ts: preserve hue families at low saturation so tokens remain distinguishable without breaking the monochrome chrome.

Philosophy

Syntax tokens use ~25% saturation. Each hue family is preserved as a tinted gray rather than a bright color. The overall impression should be subtly warm or cool grays, not a rainbow. Diff markers (deletion/addition) stay slightly more saturated because they carry semantic meaning.

This approach matches how Cursor, Vercel, and Linear handle code in monochrome contexts.

Muted Syntax Palette

On background #1a1a1a (bgTertiary), base text #c8c8c8:

Code Block Chrome

Mermaid Diagrams

Mermaid diagrams use the surface palette for all chrome — node fills, borders, edge colors, text. Git graph and pie chart retain functional colors for branch/segment differentiation, consistent with the console's graph-colors.ts approach.

Callouts (Blockquotes)

Markdown blockquotes (> **Tip:** ..., > **Note:** ..., > **Warning:** ...) render as callouts. The blockquote renderer inspects the HAST node for a bold type prefix and applies the appropriate variant.

Design rationale:

• Background is #111 (bgSecondary), distinct from both page canvas (#0a0a0a) and code blocks (#1a1a1a). Each surface level is visually separable.
• Border is border-l-2 (2px) rather than 4px — thinner but brighter (#3a3a3a) creates a cleaner, more refined signal.
• No italic. The bold type prefix ("Tip:") and the distinct background surface are sufficient callout signals. Italic reduces readability, especially when mixed with inline code.
• Warning uses semantic red at low opacity — consistent with the "honest semantics" principle.

Console Follow-Up

The console uses react-syntax-highlighter with bundled themes (darcula, vsc-dark-plus, material-light) — a different rendering pipeline from the website's CSS-based hljs. Aligning the console to the same muted philosophy requires building custom react-syntax-highlighter theme objects from the token pipeline. This is flagged as a separate effort in the console design system document.

Website Theme Tokens

The website centralizes its design tokens in src/theme/docs.ts as Tailwind class strings. This is intentional — Tailwind class strings in TypeScript, not CSS variables — for consistency with the rest of the codebase.

Sidebar badge colors preserve semantic meaning: Popular uses green (#10b981), Deprecated uses red (#ef4444). All other badges use white with opacity variations.

Rules for Contributors

These rules apply to all Planton surfaces. Every component, every styled file, every new feature must follow them.

Always Do

1. Use the theme system for all colors. On the website, use Tailwind classes from the established palette. In the console, use theme.palette.* for every color in styled-components and sx props.

2. Use semantic tokens first. Prefer text.primary, background.paper, divider (console) or text-white, bg-[#0a0a0a], border-[#2a2a2a] (website) over raw values.

3. Use alpha() from @mui/material for opacity variations in the console. Never write raw rgba() with theme colors.

4. Use theme callbacks in MUI component overrides. All overrides use ({ theme }) => ({...}).

5. Use background.default for CTA inversion in the console. When text sits on a primary.main background, use background.default for the text color — not common.white.

6. Preserve backgroundImage: 'none' on Paper overrides in the console. Without this, MUI's dark-mode elevation overlay reactivates.

7. Import graph/chart colors from graph-colors.ts. Never define inline hex values for visualization colors.

8. Use true #fff for website CTAs. The Tailwind white override (#ededed) is for body text. CTAs must use bg-[#fff] explicitly.

Never Do

1. Never hardcode hex values in component files. No '#0d1117', '#e6edf3', '#30363d' in console components. No arbitrary hex outside the established website palette.

2. Never use CSS named colors. No 'white', 'black', 'red'. Use 'common.white', 'common.black', theme.palette.error.main (console) or the corresponding Tailwind classes (website).

3. Never import from token ramp files in console component code. dark-colors.ts and light-colors.ts are consumed only by dark.tsx and light.tsx.

4. Never use info.main for decoration. Info is reserved for informational severity status only.

5. Never use if (mode === 'dark') conditionals in console styling. The theme system handles mode resolution. Styled-components access theme.palette.* which resolves correctly for both modes.

6. Never add elevation-based background differentiation. Cards are separated by borders. If a Card needs visual separation, it inherits the global border override.

7. Never use SCSS or CSS Modules for theming in the console. The legacy SCSS layer has been eliminated. All styling uses MUI styled-components and sx props.

8. Never add new design system primitives without flagging. If a styling need is not covered by existing tokens, flag it as a gap — do not invent a new token.

9. Never add decorative color to chrome elements. No colored backgrounds on headers, sidebars, or navigation. If you are reaching for a hue, ask whether it carries semantic meaning.

Key File Inventory

Website (planton.ai repo)

Console (planton monorepo, client-apps/web/console/)