Skip to content

DESIGN.md

Latest commit

 

History

History
390 lines (317 loc) · 18.9 KB

DESIGN.md

File metadata and controls

390 lines (317 loc) · 18.9 KB
version alpha
name Kilo Cloud
description Dark-first, utilitarian developer surface for Kilo Code — the open-source AI coding agent. Near-black backgrounds, white-at-low-alpha borders. The Kilo yellow-green is the primary action color — it's the brand and the CTA at once. Blue is a legacy link/inline-accent role only.
colors
background surface surface-raised muted foreground foreground-muted foreground-subtle foreground-on-red border border-strong input-bg primary primary-hover primary-ring on-primary secondary secondary-hover on-secondary brand brand-dim on-brand link link-hover blue-500 blue-400 purple-500 purple-400 emerald-500 emerald-400 zinc-500 zinc-400 orange-500 orange-400 green-500 green-400 yellow-500 yellow-400 red-500 red-400
#121212
#2B2B2B
#333333
#3D3D3D
#FAFAFA
#A3A3A3
#7A7A7A
#FFFFFF
#FFFFFF1A
#FFFFFF2E
#FFFFFF0A
#EDFF00
#D6E600
#EDFF0059
#1F1F1F
#3D3D3D
#4D4D4D
#FAFAFA
#EDFF00
#B8C800
#1F1F1F
#3B82F6
#60A5FA
#3B82F6
#60A5FA
#A855F7
#C084FC
#10B981
#34D399
#71717A
#A1A1AA
#F97316
#FB923C
#22C55E
#4ADE80
#EAB308
#FACC15
#EF4444
#F87171
typography
display h1 h2 h3 body body-strong label eyebrow code terminal
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter
3rem
700
1.15
-0.015em
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter
1.875rem
700
1.15
-0.015em
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter
1.5rem
600
1.3
-0.015em
fontFamily fontSize fontWeight lineHeight
Inter
1.25rem
600
1.3
fontFamily fontSize fontWeight lineHeight
Inter
0.875rem
400
1.5
fontFamily fontSize fontWeight lineHeight
Inter
0.875rem
500
1.5
fontFamily fontSize fontWeight lineHeight
Inter
0.75rem
500
1.3
fontFamily fontSize fontWeight lineHeight letterSpacing
Inter
0.6875rem
600
1.3
0.06em
fontFamily fontSize fontWeight lineHeight
Roboto Mono
0.8125rem
400
1.5
fontFamily fontSize fontWeight lineHeight fontFeature
Roboto Mono
0.8125rem
400
1.5
"calt", "ss01"
rounded
none sm md lg xl full
0
6px
8px
10px
14px
9999px
spacing
0-5 1 1-5 2 3 4 5 6 8 10 12
2px
4px
6px
8px
12px
16px
20px
24px
32px
40px
48px
components
button-primary button-primary-hover button-secondary button-secondary-hover button-ghost button-destructive card input badge-status badge-brand sidebar topbar popover dialog terminal
backgroundColor textColor typography rounded height padding
{colors.primary}
{colors.on-primary}
{typography.body-strong}
{rounded.sm}
36px
0 14px
backgroundColor
{colors.primary-hover}
backgroundColor textColor typography rounded height padding
{colors.secondary}
{colors.on-secondary}
{typography.body-strong}
{rounded.sm}
36px
0 14px
backgroundColor
{colors.secondary-hover}
backgroundColor textColor rounded height padding
transparent
{colors.foreground}
{rounded.sm}
36px
0 4px
backgroundColor textColor typography rounded height padding
{colors.red-500}
{colors.foreground-on-red}
{typography.body-strong}
{rounded.sm}
36px
0 14px
backgroundColor borderColor rounded padding
{colors.surface}
{colors.border}
{rounded.xl}
24px
backgroundColor textColor rounded height padding
{colors.input-bg}
{colors.foreground}
{rounded.sm}
36px
0 12px
backgroundColor textColor typography rounded padding
{colors.blue-500}
{colors.blue-400}
{typography.label}
{rounded.sm}
2px 8px
backgroundColor textColor typography rounded padding
{colors.brand}
{colors.on-brand}
{typography.label}
{rounded.sm}
2px 8px
backgroundColor textColor width padding
{colors.surface}
{colors.foreground-muted}
256px
12px 8px
backgroundColor textColor height padding
{colors.background}
{colors.foreground}
56px
0 16px
backgroundColor textColor rounded padding
{colors.surface-raised}
{colors.foreground}
{rounded.md}
12px
backgroundColor textColor rounded padding
{colors.surface}
{colors.foreground}
{rounded.xl}
24px
backgroundColor textColor typography rounded padding
{colors.background}
{colors.foreground}
{typography.terminal}
{rounded.lg}
16px

Overview

Trustworthy infra tool, not a marketing site. Kilo Cloud is the developer-facing web product around Kilo Code, an open-source AI coding agent that lives primarily as a VS Code / JetBrains extension. The cloud surface manages organizations, usage and billing, headless agent sessions, and developer ops. The aesthetic is dark-first, near-black, utilitarian — dense tables, calm chrome, low ornamentation. Speak to developers in second person, plain English, with concrete nouns.

The single concession to atmosphere is the cloud-agent chat surface — terminal-styled mono, a thin yellow-green focus glow, glass on sticky chrome. Everywhere else: utility over delight.

Three rules to ground every screen.

  1. Never pure black, never a gradient. Background is #121212. Cards step up to #2B2B2B. The lift comes from a one-step background change plus a 10%-white border, not from drop shadows or blur.
  2. Borders are white at low alpha. This is the single most characteristic move. #FFFFFF1A on every card, #FFFFFF2E on every input. No solid grey borders.
  3. Yellow acts. Greys carry everything else. The Kilo yellow-green (#EDFF00) is the primary action color — brand and CTA collapsed into one swatch. Use it exactly once per surface for the thing the user is here to do, and again atmospherically for the logo tile, focus ring, text selection, and agent-surface glow. Secondary actions are dark gray. Blue is a legacy link role only — never a button background.

Colors

Foundations are a four-step near-black ladder. background → surface → surface-raised → muted. Compose UI by stacking surfaces against background; the visual hierarchy is built from value steps, not color shifts. Cards sit on background. Popovers sit on cards. Inputs sit inside cards but drop down into translucency (input-bg is white-on-card at 4% — a recess, not a lift).

  • background (#121212) — the app canvas. Always behind everything. Never gradient, never patterned.
  • surface (#2B2B2B) — cards, sidebar, dialogs, sticky chrome. The default container.
  • surface-raised (#333333) — popovers, tooltips, menus. One step above cards.
  • muted (#3D3D3D) — hover states on rows and ghost buttons. Inactive tab backgrounds.

Foreground is a three-step white ladder. Body text is near-white (#FAFAFA), not pure white — pure white vibrates against #121212. Use foreground-muted (#A3A3A3) for secondary text, captions, and metadata. foreground-subtle (#7A7A7A) is for disabled and tertiary copy only.

Borders carry the elevation. White at 10% alpha for the default border, 18% for inputs and focused chrome. Because borders are translucent, they read correctly on every surface step without needing per-context overrides. Never use a solid grey for borders.

Action hierarchy is colored, not sized.

  • primary (#EDFF00) — the Kilo yellow-green. The primary action color and the brand mark — they're the same swatch. Used exactly once per surface for the thing the user is here to do (Create session, Save, Install, Continue). Hover darkens to #D6E600 (not lighter, not translucent). The on-color is near-black (#1F1F1F); white text on yellow fails AA.
  • secondary (#3D3D3D) — dark-gray with white text and a 10%-white border. The workhorse. Use freely.
  • ghost — underlined white text, no chrome at rest. The decoration is the affordance: text-decoration-color: rgba(255,255,255,0.35) at rest, opaque on hover. For inline links, table-row actions, and dialog Cancel buttons.
  • destructive (red-500) — red fill, white text. Only inside dialogs and confirm flows. Never on a primary listing screen.
  • link (#3B82F6) — legacy blue, inline only. Used for links inside running prose. Never a button background, never a section accent.

Status colors follow one rigid pattern. Every status badge is bg-{color}-500/20 text-{color}-400 ring-1 ring-{color}-500/20. The translucent fill + matching ring + brighter foreground is the system's most recognizable micro-pattern. Color assignments are fixed by domain, not by mood:

Color Domain
Blue Cloud sessions (neutral default)
Purple VS Code Extension
Zinc CLI
Emerald Slack
Orange Agent Manager
Green Success, "new" badges
Yellow Warnings
Red Destructive, errors

Do not invent new status hues. Do not use status colors outside this badge pattern (e.g. don't use red-500 as a button background — use destructive semantics through the dialog system).

Typography

Two faces, with discipline. Inter for all UI. Roboto Mono for code, terminal output, agent tool readouts, dollar amounts in dense tables, and timestamps. Never mix mono into prose UI for emphasis — emphasis is weight (500/600), not face.

Default body is 14px / 1.5. This is the floor for everything that isn't a heading or a label. Page titles use tracking-tight (-0.015em) — Inter at 24px+ is too wide-set without it. Eyebrows are uppercase + tracking-wide (0.06em).

Heading scale is compact. This is a dashboard, not a marketing page. Page-level h1 is 30px / 700. The display size (48px) is reserved for empty-state hero moments and onboarding — not normal app chrome.

Casing is sentence case for everything user-visible. Buttons, nav, section titles, badges. Title Case is wrong. The exceptions are the eyebrow style (uppercase tracking-wide) and the rare role badge (KILO ADMIN).

Numbers in dense data lean mono. Dollar amounts, latencies, token counts, timestamps in the audit log — all Roboto Mono. This is functional, not decorative: mono digits align across rows.

Layout

Shell is sidebar + main, both dark, with a sticky topbar. Sidebar is fixed 256px expanded, 48px icon-only collapsed. The toggle is cmd/ctrl+B. State persists via cookie.

  • Topbar — 56px tall, border-b (the 10%-white border), single breadcrumb on the left, sidebar toggle on the right. Sticky.
  • Page content — w-full flex-1 under the topbar. Page-level padding is 24px.
  • Card stacks — dashboards are vertical stacks of Card components with gap-y-6 (24px). No multi-column page-level grids; multi-column lives inside a card.

Spacing is a 4px ladder. Pull from the spacing scale; do not invent intermediate values. 2/3/4/6 (8/12/16/24px) covers ~90% of layout decisions. 8/10/12 (32/40/48px) is for section gaps and empty-state breathing room. Anything tighter than 2 is a bug — except for 0-5 (2px) which exists for icon-text optical alignment.

Density is compact. Buttons are 36px tall by default, 32px for the small variant. Inputs match buttons at 36px. Table rows are 48px. Cards get 24px of inner padding. This is a tool that admins live in for hours; sparseness wastes their time.

Elevation & Depth

Lift is a value step, not a shadow. Cards aren't elevated by drop-shadow — they're elevated by being one step lighter than background plus a 10%-white border. This is the system's signature. Reach for shadows only when an element genuinely floats above the page (popover, tooltip, dialog).

  • shadow-xs — used on inputs to suggest a recessed depth. Whisper-soft.
  • shadow — used on default cards in rare cases (focus, drag).
  • shadow-md — popovers, tooltips, dropdowns.
  • shadow-lg — dialogs over the bg-black/80 overlay.

Glass is reserved for sticky chrome. backdrop-blur-xl only on the topbar lockup or persistent overlays. Never on cards or content surfaces — translucent content surfaces become unreadable in dense tables.

The agent surface gets one extra move: the brand glow. A thin yellow-green inner shadow on focused composers and live-streaming chrome (0 0 24px {colors.brand}/35%). Does not appear in dashboards, billing, or admin.

Shapes

Five radii, applied by role.

  • rounded.sm (6px) — controls. Buttons, inputs, badges, status pills, menu items.
  • rounded.md (8px) — popovers, dropdowns, secondary surfaces.
  • rounded.lg (10px) — cards in non-dashboard contexts (auth, marketing).
  • rounded.xl (14px) — the dashboard Card. The most common surface.
  • rounded.full — avatars and the rare pill nav.

Never round above xl for a card; never round below sm for a control. The system gets its calm cohesion from radius consistency.

Components

The token table above defines the canonical surface. Notes on application:

Buttons. button-primary is the yellow CTA with near-black text — one per surface. button-secondary is the dark-gray workhorse on cards. button-ghost is underlined white text with no chrome at rest — for inline links, table-row actions, and dialog Cancel. button-destructive is red, only inside dialogs. Press states are not represented by transforms — buttons don't shrink or scale. Disabled is opacity-50 + pointer-events-none. Focus is the brand-glow ring (#EDFF00 at 35% alpha) on :focus-visible only — never on hover.

Card. Always surface background, always 10%-white border, always rounded.xl, always 24px padding. The header gets pb-2 (less bottom padding) so the title sits closer to its content.

Input. Translucent fill (input-bg), 18%-white border, rounded.sm, 36px tall. Focus state adds the brand yellow-green halo via :focus-visible — never via hover. Errors flip the border to destructive and surface a description below.

Status badges. The translucent /20 pattern is non-negotiable. Layout: gap-1 between icon and label, label in sentence case, icon in size-3 (12px) — smaller than other inline icons because the badge itself is small.

Sidebar. Fixed 256px. Section headers are eyebrow-style uppercase + tracking-wide. Active row gets accent background, inactive rows get accent only on hover. Icon at size-4, label at body-strong. The Kilo logo lives at the top in a 40×40 brand tile.

Topbar. Single breadcrumb, no logo (the logo lives in the sidebar). Right side gets the sidebar toggle, a search omnibox, and an avatar. Never put primary actions in the topbar — those belong in the page body.

Dialog. bg-black/80 overlay, centered card, max width 28rem for confirms / 40rem for forms. Close button is a ghost icon button in the top-right. Primary action is on the right of the footer, secondary on the left of that; cancel is a ghost button on the left of the footer.

Terminal / agent. background color (not surface — terminals stay flush with the canvas), Roboto Mono, text-sm. Streaming output is rendered with a blinking caret. Tool-call cards inside the chat are surface cards with a 12-px icon + tool name eyebrow + a one-line summary.

Do's and Don'ts

Do

  • Stack value, not color. Build hierarchy by stepping background → surface → surface-raised, not by tinting.
  • Use the brand yellow for the primary action. One per surface. Earn it.
  • Use translucent borders everywhere. White at 10% / 18% — never solid grey.
  • Use Roboto Mono for numbers in dense data. Tables, billing, audit logs, latencies.
  • Stick to sentence case for all user-visible copy. Including buttons.
  • Use Lucide for every icon. 1.5–2px stroke, 16px in buttons / badges, 16–20px elsewhere.
  • Apply the translucent /20 pattern for every status badge. No exceptions.
  • Let cards lift via border + value step. Reach for shadows only for floating chrome.

Don't

  • Don't use pure black or gradients for backgrounds. Always #121212, always flat.
  • Don't put more than one yellow button on a screen. If you feel the urge, the second one is a button-secondary. The yellow has to stay scarce to keep its meaning.
  • Don't use blue as a button background. Blue is reserved for inline links inside running prose. The primary action is yellow.
  • Don't introduce new status hues. The eight assigned colors cover the entire taxonomy.
  • Don't use emoji in product chrome. Lucide only. Emoji are reserved for user-authored content.
  • Don't add per-element drop shadows to cards. The border + value step does the lift.
  • Don't mix Inter and Roboto Mono in the same line of running text. Mono in tables, code, terminals — never as inline emphasis.
  • Don't use Title Case anywhere user-facing. Sentence case throughout.
  • Don't tint borders to convey state. State changes background (muted on hover), not the border color.