KDCDesignSystem/design.md

---
version: beta
name: Kode Design Consultants Ltd Design System
description: The official design system for Kode Design Consultants — tokens, components, and guidelines for building consistent KDC product and brand experiences.
colors:
  brand.primary: "#6B35A7"
  brand.primaryHover: "#582A8D"
  brand.primaryPressed: "#45216E"
  brand.ink: "#000000"
  brand.canvas: "#F5F4F0"
  neutral.0: "#FFFFFF"
  neutral.50: "#F5F4F0"
  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: "Opificio"
    fontSize: "72px"
    fontWeight: 700
    lineHeight: "80px"
    letterSpacing: "-0.01em"
  wordmarkSecondary:
    fontFamily: "Manrope"
    fontSize: "20px"
    fontWeight: 200
    lineHeight: "28px"
    letterSpacing: "0.04em"
  headingXL:
    fontFamily: "Manrope"
    fontSize: "32px"
    fontWeight: 700
    lineHeight: "40px"
  headingL:
    fontFamily: "Manrope"
    fontSize: "24px"
    fontWeight: 600
    lineHeight: "32px"
  headingM:
    fontFamily: "Manrope"
    fontSize: "20px"
    fontWeight: 600
    lineHeight: "28px"
  headingS:
    fontFamily: "Manrope"
    fontSize: "16px"
    fontWeight: 600
    lineHeight: "24px"
  bodyL:
    fontFamily: "Manrope"
    fontSize: "18px"
    fontWeight: 400
    lineHeight: "28px"
  bodyM:
    fontFamily: "Manrope"
    fontSize: "16px"
    fontWeight: 400
    lineHeight: "24px"
  bodyS:
    fontFamily: "Manrope"
    fontSize: "14px"
    fontWeight: 400
    lineHeight: "20px"
  caption:
    fontFamily: "Manrope"
    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** — the four-color brand palette: `brand.primary` (`#6B35A7` purple), `brand.ink` (`#000000`), `neutral.0` (`#FFFFFF`), and `brand.canvas` (`#F5F4F0` off-white).
2. **Neutral** — a 12-step gray ramp powering surfaces, text, and borders. `neutral.50` is set to `brand.canvas` so the off-white reads as the natural page surface.
3. **Semantic** — meaning-bearing colors for status: success, warning, danger, info. These sit alongside the brand palette but are not part of brand identity.

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

KDS uses two brand typefaces:

- **Opificio Bold** — reserved for the **kode** wordmark and headline display moments. Available in Bold, Rounded, and Regular cuts; Bold is the canonical brand weight.
- **Manrope** — the working typeface for all UI: headings, body, captions, and the secondary wordmark line ("design consultants"). Use the full weight ramp: ExtraLight (200), Light (300), Regular (400), Medium (500), SemiBold (600), Bold (700), ExtraBold (800).

The wordmark lockup pairs them: primary line in Opificio Bold (72pt, 52pt spacing), secondary line in Manrope ExtraLight (20pt, 76pt spacing).

The UI 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.

A monospace stack (Roboto Mono fallback to system mono) is available for code and tabular figures only — it is **not** part of the brand identity.

Web fonts are self-hosted from `assets/fonts/` and preloaded for Manrope Regular (400) and SemiBold (600), plus Opificio Bold for the wordmark.

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