KDCDesignSystem/design.md

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

version	name	description	colors	typography	rounded	spacing	components
beta	Kode Design Consultants Ltd Design System	The official design system for Kode Design Consultants — tokens, components, and guidelines for building consistent KDC product and brand experiences.	brand.primary brand.primaryHover brand.primaryPressed brand.ink brand.canvas 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 #6B35A7 #582A8D #45216E #000000 #F5F4F0 #FFFFFF #F5F4F0 #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 wordmarkSecondary headingXL headingL headingM headingS bodyL bodyM bodyS caption mono fontFamily fontSize fontWeight lineHeight letterSpacing Opificio 72px 700 80px -0.01em fontFamily fontSize fontWeight lineHeight letterSpacing Manrope 20px 200 28px 0.04em fontFamily fontSize fontWeight lineHeight Manrope 32px 700 40px fontFamily fontSize fontWeight lineHeight Manrope 24px 600 32px fontFamily fontSize fontWeight lineHeight Manrope 20px 600 28px fontFamily fontSize fontWeight lineHeight Manrope 16px 600 24px fontFamily fontSize fontWeight lineHeight Manrope 18px 400 28px fontFamily fontSize fontWeight lineHeight Manrope 16px 400 24px fontFamily fontSize fontWeight lineHeight Manrope 14px 400 20px fontFamily fontSize fontWeight lineHeight letterSpacing Manrope 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 — 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.