---
version: alpha
name: KDC Design System
description: The official design system for KDC — tokens, components, and guidelines for building consistent KDC product and brand experiences.
colors:
  brand.primary: "rgb(11, 95, 255)"
  brand.primaryHover: "#0848C2"
  brand.primaryPressed: "#063494"
  brand.secondary: "#FF6B00"
  brand.accent: "#00C2A8"
  neutral.0: "#FFFFFF"
  neutral.50: "#F7F8FA"
  neutral.100: "#EDEFF3"
  neutral.200: "#D9DCE3"
  neutral.300: "#B8BDC9"
  neutral.500: "#6B7280"
  neutral.700: "#374151"
  neutral.900: "#111827"
  neutral.1000: "#000000"
  semantic.success: "#16A34A"
  semantic.warning: "#F59E0B"
  semantic.danger: "#DC2626"
  semantic.info: "#0EA5E9"
  surface.background: "{colors.neutral.0}"
  surface.subtle: "{colors.neutral.50}"
  surface.muted: "{colors.neutral.100}"
  text.default: "{colors.neutral.900}"
  text.muted: "{colors.neutral.500}"
  text.inverse: "{colors.neutral.0}"
  border.default: "{colors.neutral.200}"
  border.strong: "{colors.neutral.300}"
typography:
  display:
    fontFamily: "Inter"
    fontSize: "48px"
    fontWeight: 700
    lineHeight: "56px"
    letterSpacing: "-0.02em"
  headingXL:
    fontFamily: "Inter"
    fontSize: "32px"
    fontWeight: 700
    lineHeight: "40px"
  headingL:
    fontFamily: "Inter"
    fontSize: "24px"
    fontWeight: 600
    lineHeight: "32px"
  headingM:
    fontFamily: "Inter"
    fontSize: "20px"
    fontWeight: 600
    lineHeight: "28px"
  headingS:
    fontFamily: "Inter"
    fontSize: "16px"
    fontWeight: 600
    lineHeight: "24px"
  bodyL:
    fontFamily: "Inter"
    fontSize: "18px"
    fontWeight: 400
    lineHeight: "28px"
  bodyM:
    fontFamily: "Inter"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: "24px"
  bodyS:
    fontFamily: "Inter"
    fontSize: "14px"
    fontWeight: 400
    lineHeight: "20px"
  caption:
    fontFamily: "Inter"
    fontSize: "12px"
    fontWeight: 500
    lineHeight: "16px"
    letterSpacing: "0.02em"
  mono:
    fontFamily: "Roboto Mono"
    fontSize: "14px"
    fontWeight: 400
    lineHeight: "20px"
rounded:
  none: "0px"
  xs: "2px"
  sm: "4px"
  md: "8px"
  lg: "12px"
  xl: "16px"
  "2xl": "24px"
  full: "9999px"
spacing:
  "0": "0px"
  "1": "4px"
  "2": "8px"
  "3": "12px"
  "4": "16px"
  "5": "20px"
  "6": "24px"
  "8": "32px"
  "10": "40px"
  "12": "48px"
  "16": "64px"
  "20": "80px"
  "24": "96px"
components:
  button.primary:
    backgroundColor: "{colors.brand.primary}"
    textColor: "{colors.text.inverse}"
    typography: "{typography.bodyM}"
    rounded: "{rounded.md}"
    padding: "12px 20px"
    height: "40px"
  button.primaryHover:
    backgroundColor: "{colors.brand.primaryHover}"
    textColor: "{colors.text.inverse}"
  button.primaryPressed:
    backgroundColor: "{colors.brand.primaryPressed}"
    textColor: "{colors.text.inverse}"
  button.secondary:
    backgroundColor: "{colors.surface.subtle}"
    textColor: "{colors.text.default}"
    typography: "{typography.bodyM}"
    rounded: "{rounded.md}"
    padding: "12px 20px"
    height: "40px"
  button.ghost:
    backgroundColor: "transparent"
    textColor: "{colors.brand.primary}"
    typography: "{typography.bodyM}"
    rounded: "{rounded.md}"
    padding: "12px 20px"
    height: "40px"
  input.default:
    backgroundColor: "{colors.surface.background}"
    textColor: "{colors.text.default}"
    typography: "{typography.bodyM}"
    rounded: "{rounded.md}"
    padding: "10px 12px"
    height: "40px"
  card.default:
    backgroundColor: "{colors.surface.background}"
    textColor: "{colors.text.default}"
    rounded: "{rounded.lg}"
    padding: "24px"
  badge.default:
    backgroundColor: "{colors.surface.muted}"
    textColor: "{colors.text.default}"
    typography: "{typography.caption}"
    rounded: "{rounded.full}"
    padding: "2px 8px"
    height: "20px"
  modal.default:
    backgroundColor: "{colors.surface.background}"
    textColor: "{colors.text.default}"
    rounded: "{rounded.xl}"
    padding: "24px"
    width: "480px"
---

## Overview

The KDC Design System (KDS) is the source of truth for the visual and interaction language across all KDC products, marketing, and brand surfaces. It exists to make consistency cheap, accessibility default, and good design fast.

**Brand pillars**

- **Clear** — communication is direct and free of jargon.
- **Confident** — strong typography, decisive color, generous whitespace.
- **Human** — warm accents and approachable voice balance the precision.

KDS targets WCAG 2.2 AA at minimum across all components and themes.

## Colors

Color is organized in three layers:

1. **Brand** — primary identity colors (`brand.primary`, `brand.secondary`, `brand.accent`).
2. **Neutral** — a 12-step gray ramp powering surfaces, text, and borders.
3. **Semantic** — meaning-bearing colors for status: success, warning, danger, info.

Always reference *role* tokens (`text.default`, `surface.subtle`, `border.default`) in product code rather than raw palette values, so themes can swap without churn.

Contrast minimums:

- Body text on background: ≥ 4.5:1
- Large text and UI icons: ≥ 3:1
- Disabled/decorative content is exempt but should still be perceivable.

## Typography

The primary typeface is **Inter** (variable, 100–900). The monospace companion is **Roboto Mono**, used only for code, tabular figures, and technical content.

The scale is a modular 8-step ramp (`caption` → `display`). Use semantic tokens (`headingL`, `bodyM`) — never hardcode `font-size`. Body copy defaults to `bodyM`/16px with a 1.5 line-height for readability. Display sizes use tighter tracking (`-0.02em`) to prevent airy letterspacing at large sizes.

Web fonts are self-hosted from `assets/fonts/` and preloaded for the two most common weights (400, 600).

## Layout

KDS is built on a **4px base unit**. All spacing, sizing, and layout dimensions are multiples of 4. The `spacing` scale exposes the curated set most commonly needed (`1`–`24`).

**Grid**

- 12-column responsive grid.
- Gutters: 16px (mobile) / 24px (tablet) / 32px (desktop).
- Max content width: 1200px, centered.

**Breakpoints**

| Token | Min width |
|-------|-----------|
| sm    | 640px     |
| md    | 768px     |
| lg    | 1024px    |
| xl    | 1280px    |
| 2xl   | 1536px    |

Layouts should be mobile-first and use logical properties (`inline-start`, `block-end`) for RTL readiness.

## Elevation & Depth

Elevation is conveyed through a small set of layered shadows plus subtle background shifts. Avoid using elevation for decoration — reserve it for affordance and hierarchy.

| Level | Use | Shadow |
|-------|-----|--------|
| 0 | flush surfaces, page background | none |
| 1 | cards, list rows | `0 1px 2px rgba(17,24,39,0.06)` |
| 2 | dropdowns, popovers | `0 4px 12px rgba(17,24,39,0.10)` |
| 3 | modals, dialogs | `0 16px 32px rgba(17,24,39,0.16)` |
| 4 | toasts, command bars | `0 24px 48px rgba(17,24,39,0.20)` |

In dark theme, shadows are de-emphasized and elevation is communicated primarily through lighter surface tints.

## Shapes

Corner radius is calibrated to component density:

- `xs` (2px) — chips, inline tags
- `sm` (4px) — inputs, small controls
- `md` (8px) — buttons, default surfaces
- `lg` (12px) — cards, sections
- `xl` (16px) — modals, sheets
- `2xl` (24px) — marketing surfaces, feature panels
- `full` — pills, avatars, circular buttons

Avoid mixing more than two radii in a single composition.

## Components

The component library lives under `components/` with one folder per primitive. Each folder ships:

- A spec (`README.md`) documenting variants, states, props, and a11y notes.
- Anatomy SVG/PNG.
- Implementation references (web/mobile, where applicable).

Core primitives shipped today:

- **Buttons** — primary, secondary, ghost, destructive; sizes sm/md/lg; loading & disabled states.
- **Inputs** — text, textarea, select, checkbox, radio, switch.
- **Cards** — default, elevated, outlined.
- **Modals** — dialog, sheet, drawer.
- **Navigation** — top bar, side nav, tabs, breadcrumbs, pagination.
- **Forms** — field, label, helper text, error message, fieldset.
- **Tables** — sortable, selectable, paginated.
- **Badges** — neutral, success, warning, danger, info.
- **Tooltips, Alerts, Tabs, Dropdowns**.

Every interactive component must define: default, hover, focus-visible, active/pressed, disabled, and (where relevant) loading.

## Do's and Don'ts

**Do**

- Use role tokens (`text.default`) over palette tokens (`neutral.900`).
- Pair every color with a contrast check before shipping.
- Lean on whitespace before adding rules, borders, or shadows.
- Keep motion under 250ms for UI feedback; ease-out for entrances, ease-in for exits.
- Provide focus-visible styles on every interactive element.

**Don't**

- Don't introduce off-system colors, fonts, or radii in product UI.
- Don't use color alone to convey meaning — always pair with icon or text.
- Don't stack more than two elevation levels in a single composition.
- Don't override component internals; extend via documented props/slots.
- Don't ship animations longer than 400ms on transactional UI.