KDCDesignSystem/design.md

version, name, description, colors, typography, rounded, spacing, components

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