DESIGN.md

version	0.2.0
name	Kilo Cloud
description	Dark-first, utilitarian developer surface for Kilo Code. Near-black layered surfaces and low-alpha white borders carry hierarchy. Kilo yellow-green is both brand and primary action color. Blue is reserved for links and the Cloud status domain.
color	brand status surface foreground border syntax diff primary primaryHover primaryRing foreground #F7F586 #E6E475 #F7F58659 #1F1F1F blue300 blue400 blue500 blue600 purple300 purple400 purple500 purple600 teal300 teal400 teal500 teal600 gray300 gray400 gray500 gray600 orange300 orange400 orange500 orange600 green300 green400 green500 green600 yellow300 yellow400 yellow500 yellow600 red300 red400 red500 red600 #93C5FD #60A5FA #3B82F6 #2563EB #D8B4FE #C084FC #A855F7 #9333EA #4CE7D7 #00D4C2 #00BAA9 #009689 #D4D4D8 #A1A1AA #71717A #52525B #FDBA74 #FB923C #F97316 #EA580C #86EFAC #4ADE80 #22C55E #16A34A #FDD94A #FBC51C #F0A900 #D28100 #FCA5A5 #F87171 #EF4444 #DC2626 inset background raised overlay hover selected #101010 #151515 #202020 #333333 #3A3A3A #454545 default muted subtle onSecondary onDestructive #FAFAFA #A3A3A3 #7A7A7A #FAFAFA #FFFFFF default strong inputBg #FFFFFF1A #FFFFFF2E #FFFFFF0A plain comment keyword string number function type property constant operator #E8E8E8 #7A7A7A #FF9AE2 #ECF58C #F2B36B #93E9F6 #00CEB9 #9CDCFE #C792EA #A3A3A3 addText addSurface deleteText deleteSurface #9BCD97 #1A2919 #FC533A #42120B
statusDomain	cloud vscode cli slack agentManager success warning destructive blue purple gray teal orange green yellow red
typography	title heading bodyLg body label eyebrow code fontFamily fontSize fontWeight lineHeight letterSpacing Inter 1.5rem 600 1.2 -0.015em fontFamily fontSize fontWeight lineHeight letterSpacing Inter 1.125rem 600 1.25 -0.01em fontFamily fontSize fontWeight lineHeight Inter 1rem 400 1.5 fontFamily fontSize fontWeight lineHeight Inter 0.875rem 400 1.5 fontFamily fontSize fontWeight lineHeight Inter 0.75rem 500 1.4 fontFamily fontSize fontWeight lineHeight letterSpacing textTransform Inter 0.6875rem 500 1.2 0.08em uppercase fontFamily fontSize fontWeight lineHeight Roboto Mono 0.875rem 400 1.5
radius	none sm md lg xl full 0 4px 8px 10px 14px 9999px
spacing	1 2 3 4 5 6 8 10 12 0_5 1_5 4px 8px 12px 16px 20px 24px 32px 40px 48px 2px 6px
components	buttonPrimary buttonPrimaryHover buttonPrimaryFocus buttonSecondary buttonSecondaryHover buttonGhost buttonGhostHover buttonDestructive buttonDestructiveHover card input badgeStatus badgeBrand sidebar topbar popover dialog terminal backgroundColor textColor typography radius height padding {color.brand.primary} {color.brand.foreground} {typography.label} {radius.md} 36px 0 14px backgroundColor {color.brand.primaryHover} ringColor {color.brand.primaryRing} backgroundColor textColor borderColor typography radius height padding {color.surface.overlay} {color.foreground.onSecondary} {color.border.default} {typography.label} {radius.md} 36px 0 14px backgroundColor {color.surface.hover} backgroundColor textColor typography radius height padding transparent {color.foreground.default} {typography.label} {radius.md} 36px 0 8px backgroundColor {color.surface.hover} backgroundColor textColor typography radius height padding {color.status.red500} {color.foreground.onDestructive} {typography.label} {radius.md} 36px 0 14px backgroundColor {color.status.red600} backgroundColor borderColor radius padding {color.surface.raised} {color.border.default} {radius.xl} 24px backgroundColor textColor borderColor radius height padding {color.border.inputBg} {color.foreground.default} {color.border.strong} {radius.md} 36px 0 12px typography radius padding {typography.label} {radius.full} 2px 8px backgroundColor textColor typography radius padding {color.brand.primary} {color.brand.foreground} {typography.label} {radius.full} 2px 8px backgroundColor textColor width padding {color.surface.raised} {color.foreground.muted} 256px 12px 8px backgroundColor textColor borderColor height padding {color.surface.background} {color.foreground.default} {color.border.default} 56px 0 16px backgroundColor textColor radius padding {color.surface.overlay} {color.foreground.default} {radius.lg} 12px backgroundColor textColor radius padding {color.surface.raised} {color.foreground.default} {radius.xl} 24px backgroundColor textColor typography radius padding {color.surface.inset} {color.syntax.plain} {typography.code} {radius.lg} 16px

Overview

Trustworthy infrastructure tool, not a generic SaaS dashboard. Kilo Cloud is the developer-facing product around Kilo Code. It manages organizations, usage and billing, agent sessions, and developer operations. Product UI is dark-first, compact, and utilitarian: dense tables, calm chrome, low ornamentation, and concrete language.

The cloud-agent surface may use terminal typography, syntax color, a restrained brand focus glow, and inset surfaces. Elsewhere, utility takes precedence over decoration.

Three rules ground every screen.

1. Build depth with the surface ladder. Use surface.background for the app canvas, surface.raised for cards and shell chrome, surface.overlay for floating UI, and surface.inset for terminal or recessed regions. Use surface.hover and surface.selected only for interaction states.
2. Use low-alpha white borders. border.default is standard chrome; border.strong distinguishes inputs and emphasized boundaries. Do not introduce solid gray borders.
3. Yellow acts; neutrals carry everything else. brand.primary is both brand and primary action color. Use one primary action per surface. Blue is for inline links and the Cloud status domain, not button backgrounds.

Color

Surfaces

The six surface tokens have fixed roles:

Token	Value	Role
surface.inset	#101010	Terminal, code, and recessed regions
surface.background	#151515	App canvas
surface.raised	#202020	Cards, sidebar, dialogs, persistent chrome
surface.overlay	#333333	Popovers, dropdowns, tooltips
surface.hover	#3A3A3A	Pointer and ghost-control hover
surface.selected	#454545	Selected rows, active neutral controls

Stack surfaces by role. Do not substitute arbitrary grays, gradients, or per-component surface colors. Floating UI may use a restrained shadow, but normal hierarchy comes from surface changes and borders.

Foreground and borders

• foreground.default is default text.
• foreground.muted is secondary copy and metadata.
• foreground.subtle is tertiary or disabled copy. Confirm contrast before using it for essential information.
• foreground.onSecondary is text on neutral action surfaces.
• foreground.onDestructive is text on destructive fills.
• border.default is the standard 10%-white boundary.
• border.strong is the 18%-white emphasized boundary.
• border.inputBg is a recessed input fill, not a border color.

Never use color alone to communicate state. Pair status color with labels, icons, or other visible structure.

Brand and actions

brand.primary (#F7F586) is scarce and load-bearing. Reserve it for the logo, one primary CTA per surface, and deliberate brand moments. Use brand.foreground (#1F1F1F) on primary fills. Hover darkens to brand.primaryHover (#E6E475). Keyboard focus uses brand.primaryRing (#F7F58659) or the semantic focus-ring token supplied by the implementation.

Secondary actions use neutral surfaces and foreground.onSecondary. Ghost actions have no fill at rest and use surface.hover on hover. Destructive actions use red only when semantics are destructive; prefer reversible undo flows over confirmation dialogs when possible.

Status domains

Status colors are assigned by domain, never by mood:

Domain	Family
Cloud	Blue
VS Code	Purple
CLI	Gray
Slack	Teal
Agent Manager	Orange
Success	Green
Warning	Yellow
Destructive	Red

Use the 500 step as the base swatch, 400 for dark-surface foreground emphasis, 300 for lighter emphasis, and 600 for darker interaction or high-emphasis states. Status badges may compose a low-alpha 500 background and border with 400 text. Preserve a non-color cue and verify contrast in context.

Do not invent status hues or substitute emerald for teal or zinc for gray. Blue remains acceptable for inline links, but not primary action fills.

Syntax and diffs

Use syntax tokens only in code, terminal, and editor-like surfaces:

• syntax.plain for unclassified source text.
• syntax.comment for comments and de-emphasized code.
• syntax.keyword, syntax.string, syntax.number, syntax.function, syntax.type, syntax.property, syntax.constant, and syntax.operator for their matching grammar scopes.

Diffs use diff.addText on diff.addSurface and diff.deleteText on diff.deleteSurface. Always retain +/- markers or equivalent structure so additions and deletions do not depend on color alone.

Typography

Use Inter for UI and Roboto Mono for code, identifiers, terminal output, timestamps, and dense numerical data. Do not introduce another family. JetBrains Mono may remain on existing editor-specific surfaces, but it is not part of this token contract.

The product scale is intentionally compact:

• title: page titles, 24px / 600 / 1.2.
• heading: section and card headings, 18px / 600 / 1.25.
• bodyLg: lead or emphasized prose, 16px / 400 / 1.5.
• body: default product copy, 14px / 400 / 1.5.
• label: controls, compact metadata, and badges, 12px / 500 / 1.4.
• eyebrow: short uppercase category labels, 11px / 500 / 1.2, with 0.08em tracking.
• code: code and terminal text, 14px / 400 / 1.5.

Use sentence case for user-visible copy. Eyebrows are the exception because the token explicitly transforms them to uppercase. Use tabular-nums for values aligned in columns. Do not use monospace as prose emphasis.

Layout and spacing

Use the supplied 4px-based spacing ladder. spacing.2, spacing.3, spacing.4, and spacing.6 cover most product layout. spacing.8, spacing.10, and spacing.12 create section separation. spacing.0_5 and spacing.1_5 are for tight optical adjustments and compact component internals, not general page layout.

• Topbar height is 56px; use border.default along its lower edge.
• Expanded sidebar width is 256px; use the existing sidebar primitive for responsive collapse.
• Default page padding and card padding are 24px.
• Default controls are 36px tall; small and large variants may use 32px and 40px.
• Table rows target 48px in dense desktop UI.
• Prefer gap over ad hoc margins.
• Never nest cards. Use spacing, dividers, headings, or inset regions for internal grouping.

Product UI must reflow at narrow widths. Test around 375px, 768–1024px, and 1440px. Required actions cannot depend on hover. On touch surfaces, preserve at least a 44px target even when the visual control is compact.

Shape

Use radius by role:

• radius.none for edge-to-edge or intentionally square regions.
• radius.sm (4px) for tight chips and compact inline elements.
• radius.md (8px) for buttons and inputs.
• radius.lg (10px) for popovers and medium containers.
• radius.xl (14px) for cards and dialogs.
• radius.full for badges, avatars, and status pills.

Do not introduce one-off radii. Follow existing shadcn primitives when their semantic radius already matches these roles.

Components and interaction

Buttons. Primary uses brand.primary with brand.foreground, once per surface. Secondary uses surface.overlay, foreground.onSecondary, and border.default. Ghost uses no fill at rest and surface.hover on hover. Destructive uses status.red500, darkening to status.red600. Do not scale buttons on press.

Cards. Use surface.raised, border.default, radius.xl, and 24px padding. Cards represent distinct content or interaction boundaries, not every grouping.

Inputs. Use border.inputBg, border.strong, radius.md, and visible labels. Focus must remain visible. Errors pair a red boundary or icon with explanatory text connected through aria-describedby.

Status badges. Use the fixed domain mapping, a full radius, and typography.label. Include text or an icon so meaning survives color-vision differences.

Sidebar. Use surface.raised, sidebar semantic tokens where available, and foreground.muted for inactive items. Active rows use surface.selected; hover uses surface.hover. Use the existing responsive sidebar or Sheet behavior instead of creating another mobile navigation tree.

Topbar. Use surface.background, border.default, and a 56px height. Keep primary page actions in page content rather than persistent chrome.

Overlays. Popovers and menus use surface.overlay; dialogs use surface.raised. Build them with existing Radix and shadcn primitives for focus trapping, keyboard navigation, dismissal, portals, and stacking.

Terminal and code. Use surface.inset, typography.code, and the syntax palette. Disable ligatures where exact glyph representation matters. Diff views use the dedicated diff tokens.

Every interactive component must account for default, hover, focus-visible, active, disabled, loading, error, and success states where relevant. Hover is supplementary. Focus indicators need at least 3:1 contrast against adjacent colors and must not be removed without a replacement.

Motion

Product motion is short and functional. Use opacity and transform transitions around 100–200ms for direct feedback and 200–300ms for overlays or state changes. Reuse the established strong ease-out curve. Avoid bounce, elastic motion, and casual animation of layout properties.

Brand flourishes belong only in deliberate brand moments. Respect prefers-reduced-motion; preserve function while removing nonessential movement. Use existing Radix/shadcn transitions for dialogs, dropdowns, sheets, and tooltips.

Voice

Kilo voice is clear, technical, calm, and direct. Use concrete verbs and specific nouns. Buttons use verb + object (Save changes, Create workspace, Delete project) rather than Submit, OK, or Yes. Error copy states what happened and what the user can do next. Do not use hype, jokes in errors, emoji in product chrome, or inconsistent terminology.

Do and don't

Do

• Use semantic implementation tokens that map to this contract before raw hex values.
• Build hierarchy with the six-role surface ladder and low-alpha borders.
• Keep brand yellow-green scarce and reserve it for primary action and brand roles.
• Use fixed domain mappings for statuses.
• Use syntax and diff colors only on code-oriented surfaces.
• Use Inter for UI, Roboto Mono for code and aligned technical data.
• Preserve keyboard, screen-reader, reduced-motion, touch, and responsive behavior.

Don't

• Use pure black, gradients, or arbitrary surface grays.
• Put multiple yellow primary buttons on one surface.
• Use blue as a primary button background.
• Rename teal to emerald or gray to zinc in the token contract.
• Invent status colors, spacing values, radii, or typography roles.
• Nest cards or use shadows as the default source of depth.
• Depend on color, hover, placeholders, or icon shape alone to convey meaning.