CODITECT Design Tokens Standard

CAPaaS - Coditect Agentic Platform as a Service Copyright 2026 AZ1.AI Inc. All Rights Reserved

Version: 1.0.0 Status: ACTIVE Last Updated: 2026-01-19 Related ADR: ADR-085-atomic-design-component-library.md

---

Overview

Design tokens are the single source of truth for visual design values. All UI components MUST use design tokens rather than hardcoded values to ensure consistency, maintainability, and theming support.

Core Principles

1. No Magic Numbers - Every visual value must reference a token
2. Semantic Naming - Tokens describe purpose, not appearance
3. Theme Support - Tokens enable light/dark mode switching
4. 8px Grid - Spacing follows the 8px grid system

---

Color Tokens

Semantic Colors

:root {
  /* Primary Brand */
  --coditect-color-primary-50: #f0f9ff;
  --coditect-color-primary-100: #e0f2fe;
  --coditect-color-primary-200: #bae6fd;
  --coditect-color-primary-300: #7dd3fc;
  --coditect-color-primary-400: #38bdf8;
  --coditect-color-primary-500: #0ea5e9;  /* Default */
  --coditect-color-primary-600: #0284c7;
  --coditect-color-primary-700: #0369a1;
  --coditect-color-primary-800: #075985;
  --coditect-color-primary-900: #0c4a6e;

  /* Neutral (Gray Scale) */
  --coditect-color-neutral-50: #f9fafb;
  --coditect-color-neutral-100: #f3f4f6;
  --coditect-color-neutral-200: #e5e7eb;
  --coditect-color-neutral-300: #d1d5db;
  --coditect-color-neutral-400: #9ca3af;
  --coditect-color-neutral-500: #6b7280;
  --coditect-color-neutral-600: #4b5563;
  --coditect-color-neutral-700: #374151;
  --coditect-color-neutral-800: #1f2937;
  --coditect-color-neutral-900: #111827;

  /* Status Colors */
  --coditect-color-success-500: #22c55e;
  --coditect-color-success-600: #16a34a;
  --coditect-color-warning-500: #f59e0b;
  --coditect-color-warning-600: #d97706;
  --coditect-color-error-500: #ef4444;
  --coditect-color-error-600: #dc2626;
  --coditect-color-info-500: #3b82f6;
  --coditect-color-info-600: #2563eb;
}

Contextual Colors

:root {
  /* Backgrounds */
  --coditect-bg-primary: var(--coditect-color-neutral-50);
  --coditect-bg-secondary: var(--coditect-color-neutral-100);
  --coditect-bg-tertiary: var(--coditect-color-neutral-200);
  --coditect-bg-inverse: var(--coditect-color-neutral-900);

  /* Foregrounds (Text) */
  --coditect-fg-primary: var(--coditect-color-neutral-900);
  --coditect-fg-secondary: var(--coditect-color-neutral-600);
  --coditect-fg-tertiary: var(--coditect-color-neutral-400);
  --coditect-fg-inverse: var(--coditect-color-neutral-50);

  /* Borders */
  --coditect-border-default: var(--coditect-color-neutral-200);
  --coditect-border-strong: var(--coditect-color-neutral-300);
  --coditect-border-focus: var(--coditect-color-primary-500);
}

Dark Theme Override

[data-theme="dark"] {
  --coditect-bg-primary: var(--coditect-color-neutral-900);
  --coditect-bg-secondary: var(--coditect-color-neutral-800);
  --coditect-bg-tertiary: var(--coditect-color-neutral-700);
  --coditect-bg-inverse: var(--coditect-color-neutral-50);

  --coditect-fg-primary: var(--coditect-color-neutral-50);
  --coditect-fg-secondary: var(--coditect-color-neutral-300);
  --coditect-fg-tertiary: var(--coditect-color-neutral-500);
  --coditect-fg-inverse: var(--coditect-color-neutral-900);

  --coditect-border-default: var(--coditect-color-neutral-700);
  --coditect-border-strong: var(--coditect-color-neutral-600);
}

---

Typography Tokens

Font Families

:root {
  --coditect-font-family-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  --coditect-font-family-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
}

Font Sizes (Modular Scale)

:root {
  /* Base: 16px, Scale: 1.25 (Major Third) */
  --coditect-font-size-xs: 0.75rem;    /* 12px */
  --coditect-font-size-sm: 0.875rem;   /* 14px */
  --coditect-font-size-base: 1rem;     /* 16px */
  --coditect-font-size-lg: 1.125rem;   /* 18px */
  --coditect-font-size-xl: 1.25rem;    /* 20px */
  --coditect-font-size-2xl: 1.5rem;    /* 24px */
  --coditect-font-size-3xl: 1.875rem;  /* 30px */
  --coditect-font-size-4xl: 2.25rem;   /* 36px */
}

Font Weights

:root {
  --coditect-font-weight-normal: 400;
  --coditect-font-weight-medium: 500;
  --coditect-font-weight-semibold: 600;
  --coditect-font-weight-bold: 700;
}

Line Heights

:root {
  --coditect-line-height-tight: 1.25;
  --coditect-line-height-normal: 1.5;
  --coditect-line-height-relaxed: 1.75;
}

---

Spacing Tokens (8px Grid)

:root {
  --coditect-space-0: 0;
  --coditect-space-1: 0.25rem;   /* 4px */
  --coditect-space-2: 0.5rem;    /* 8px */
  --coditect-space-3: 0.75rem;   /* 12px */
  --coditect-space-4: 1rem;      /* 16px */
  --coditect-space-5: 1.25rem;   /* 20px */
  --coditect-space-6: 1.5rem;    /* 24px */
  --coditect-space-8: 2rem;      /* 32px */
  --coditect-space-10: 2.5rem;   /* 40px */
  --coditect-space-12: 3rem;     /* 48px */
  --coditect-space-16: 4rem;     /* 64px */
  --coditect-space-20: 5rem;     /* 80px */
  --coditect-space-24: 6rem;     /* 96px */
}

Semantic Spacing

:root {
  /* Component Internal */
  --coditect-padding-button: var(--coditect-space-2) var(--coditect-space-4);
  --coditect-padding-input: var(--coditect-space-2) var(--coditect-space-3);
  --coditect-padding-card: var(--coditect-space-4);
  --coditect-padding-modal: var(--coditect-space-6);

  /* Layout */
  --coditect-gap-card-grid: var(--coditect-space-6);
  --coditect-gap-form-field: var(--coditect-space-4);
  --coditect-gap-button-group: var(--coditect-space-2);
}

---

Border & Radius Tokens

Border Widths

:root {
  --coditect-border-width-thin: 1px;
  --coditect-border-width-medium: 2px;
  --coditect-border-width-thick: 4px;
}

Border Radii

:root {
  --coditect-radius-none: 0;
  --coditect-radius-sm: 0.25rem;   /* 4px */
  --coditect-radius-md: 0.5rem;    /* 8px - Default */
  --coditect-radius-lg: 0.75rem;   /* 12px */
  --coditect-radius-xl: 1rem;      /* 16px */
  --coditect-radius-full: 9999px;  /* Pill/Circle */
}

---

Shadow Tokens

:root {
  /* Only 2 shadow levels (Flat Design 2.0) */
  --coditect-shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --coditect-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);

  /* Semantic */
  --coditect-shadow-card: var(--coditect-shadow-sm);
  --coditect-shadow-dropdown: var(--coditect-shadow-md);
  --coditect-shadow-modal: var(--coditect-shadow-md);
}

---

Animation Tokens

:root {
  /* Durations */
  --coditect-duration-fast: 150ms;
  --coditect-duration-normal: 250ms;
  --coditect-duration-slow: 400ms;

  /* Easings */
  --coditect-ease-default: cubic-bezier(0.4, 0, 0.2, 1);
  --coditect-ease-in: cubic-bezier(0.4, 0, 1, 1);
  --coditect-ease-out: cubic-bezier(0, 0, 0.2, 1);
  --coditect-ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);

  /* Common Transitions */
  --coditect-transition-default: all var(--coditect-duration-fast) var(--coditect-ease-default);
  --coditect-transition-colors: color var(--coditect-duration-fast), background-color var(--coditect-duration-fast), border-color var(--coditect-duration-fast);
}

---

Z-Index Tokens

:root {
  --coditect-z-base: 0;
  --coditect-z-dropdown: 100;
  --coditect-z-sticky: 200;
  --coditect-z-fixed: 300;
  --coditect-z-modal-backdrop: 400;
  --coditect-z-modal: 500;
  --coditect-z-popover: 600;
  --coditect-z-tooltip: 700;
  --coditect-z-toast: 800;
}

---

TypeScript Token Export

// tokens.ts
export const colors = {
  primary: {
    50: 'var(--coditect-color-primary-50)',
    100: 'var(--coditect-color-primary-100)',
    // ... full scale
    500: 'var(--coditect-color-primary-500)',
    900: 'var(--coditect-color-primary-900)',
  },
  // ... other colors
} as const;

export const spacing = {
  0: 'var(--coditect-space-0)',
  1: 'var(--coditect-space-1)',
  2: 'var(--coditect-space-2)',
  // ... full scale
} as const;

export type ColorToken = keyof typeof colors;
export type SpacingToken = keyof typeof spacing;

---

Compliance Requirements

MUST Use Tokens

Element	Token Category
All colors	--coditect-color-* or semantic
All font sizes	--coditect-font-size-*
All spacing	--coditect-space-*
All radii	--coditect-radius-*
All shadows	--coditect-shadow-*

MUST NOT Use

Prohibited	Use Instead
#3b82f6 (raw hex)	var(--coditect-color-primary-500)
16px (raw size)	var(--coditect-space-4)
font-size: 14px	font-size: var(--coditect-font-size-sm)

---

Validation

Design token compliance is enforced by:

• moe-ui-design-system-enforcer agent
• /ui-quality --gate tokens command
• Pre-commit hooks (optional)

---

Related Documents:

• CODITECT-STANDARD-ACCESSIBILITY.md
• CODITECT-STANDARD-COMPONENT-LIBRARY.md
• ADR-085-atomic-design-component-library.md

---

Version: 1.0.0 Last Updated: 2026-01-19 Maintained by: AZ1.AI Inc.