1071 lines
21 KiB
Markdown
1071 lines
21 KiB
Markdown
# Design Tokens
|
|
|
|
## Document Overview
|
|
|
|
This document defines all design tokens for ColaFlow's multi-tenant, SSO, and MCP Token management features. Design tokens are the atomic values that make up a design system - colors, typography, spacing, shadows, etc.
|
|
|
|
**Version:** 1.0
|
|
**Last Updated:** 2025-11-03
|
|
**Format:** JSON, CSS Variables, Tailwind Config
|
|
**Owner:** UX/UI Team
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Color Tokens](#color-tokens)
|
|
2. [Typography Tokens](#typography-tokens)
|
|
3. [Spacing Tokens](#spacing-tokens)
|
|
4. [Border Radius Tokens](#border-radius-tokens)
|
|
5. [Shadow Tokens](#shadow-tokens)
|
|
6. [Animation Tokens](#animation-tokens)
|
|
7. [Z-Index Tokens](#z-index-tokens)
|
|
8. [Icon Sizes](#icon-sizes)
|
|
9. [Implementation](#implementation)
|
|
|
|
---
|
|
|
|
## Color Tokens
|
|
|
|
### Brand Colors
|
|
|
|
Primary brand color for ColaFlow (Blue):
|
|
|
|
```json
|
|
{
|
|
"color": {
|
|
"brand": {
|
|
"primary": {
|
|
"50": "#e3f2fd",
|
|
"100": "#bbdefb",
|
|
"200": "#90caf9",
|
|
"300": "#64b5f6",
|
|
"400": "#42a5f5",
|
|
"500": "#2196F3", // Main brand color
|
|
"600": "#1e88e5",
|
|
"700": "#1976D2", // Darker shade for hover
|
|
"800": "#1565c0",
|
|
"900": "#0d47a1"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
- Primary-500: Main buttons, links, active states
|
|
- Primary-700: Hover states, darker accents
|
|
- Primary-50: Light backgrounds, selected states
|
|
- Primary-100: Subtle highlights
|
|
|
|
---
|
|
|
|
### Semantic Colors
|
|
|
|
Status and feedback colors:
|
|
|
|
```json
|
|
{
|
|
"color": {
|
|
"semantic": {
|
|
"success": {
|
|
"DEFAULT": "#4CAF50",
|
|
"light": "#81C784",
|
|
"dark": "#388E3C",
|
|
"bg": "#E8F5E9",
|
|
"border": "#A5D6A7"
|
|
},
|
|
"warning": {
|
|
"DEFAULT": "#FF9800",
|
|
"light": "#FFB74D",
|
|
"dark": "#F57C00",
|
|
"bg": "#FFF3E0",
|
|
"border": "#FFE0B2"
|
|
},
|
|
"error": {
|
|
"DEFAULT": "#F44336",
|
|
"light": "#E57373",
|
|
"dark": "#D32F2F",
|
|
"bg": "#FFEBEE",
|
|
"border": "#FFCDD2"
|
|
},
|
|
"info": {
|
|
"DEFAULT": "#2196F3",
|
|
"light": "#64B5F6",
|
|
"dark": "#1976D2",
|
|
"bg": "#E3F2FD",
|
|
"border": "#BBDEFB"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
- success: Success messages, completed actions
|
|
- warning: Warnings, cautions, pending states
|
|
- error: Errors, validation failures, destructive actions
|
|
- info: Informational messages, tooltips
|
|
|
|
---
|
|
|
|
### Priority Colors
|
|
|
|
For task/issue priority indicators:
|
|
|
|
```json
|
|
{
|
|
"color": {
|
|
"priority": {
|
|
"urgent": {
|
|
"DEFAULT": "#F44336",
|
|
"bg": "#FFEBEE",
|
|
"text": "#C62828"
|
|
},
|
|
"high": {
|
|
"DEFAULT": "#FF9800",
|
|
"bg": "#FFF3E0",
|
|
"text": "#E65100"
|
|
},
|
|
"medium": {
|
|
"DEFAULT": "#2196F3",
|
|
"bg": "#E3F2FD",
|
|
"text": "#1565C0"
|
|
},
|
|
"low": {
|
|
"DEFAULT": "#9E9E9E",
|
|
"bg": "#F5F5F5",
|
|
"text": "#616161"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Status Colors
|
|
|
|
For tenant/token/user status badges:
|
|
|
|
```json
|
|
{
|
|
"color": {
|
|
"status": {
|
|
"active": {
|
|
"DEFAULT": "#4CAF50",
|
|
"bg": "#E8F5E9",
|
|
"text": "#2E7D32"
|
|
},
|
|
"suspended": {
|
|
"DEFAULT": "#FF9800",
|
|
"bg": "#FFF3E0",
|
|
"text": "#E65100"
|
|
},
|
|
"cancelled": {
|
|
"DEFAULT": "#F44336",
|
|
"bg": "#FFEBEE",
|
|
"text": "#C62828"
|
|
},
|
|
"pending": {
|
|
"DEFAULT": "#FFC107",
|
|
"bg": "#FFF8E1",
|
|
"text": "#F57F17"
|
|
},
|
|
"expired": {
|
|
"DEFAULT": "#9E9E9E",
|
|
"bg": "#F5F5F5",
|
|
"text": "#616161"
|
|
},
|
|
"revoked": {
|
|
"DEFAULT": "#F44336",
|
|
"bg": "#FFEBEE",
|
|
"text": "#C62828"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### SSO Provider Colors
|
|
|
|
Brand colors for SSO buttons:
|
|
|
|
```json
|
|
{
|
|
"color": {
|
|
"sso": {
|
|
"microsoft": {
|
|
"bg": "#00A4EF",
|
|
"text": "#FFFFFF",
|
|
"hover": "#0078D4",
|
|
"active": "#005A9E"
|
|
},
|
|
"google": {
|
|
"bg": "#FFFFFF",
|
|
"text": "#3C4043",
|
|
"hover": "#F8F9FA",
|
|
"active": "#E8EAED",
|
|
"border": "#DADCE0"
|
|
},
|
|
"okta": {
|
|
"bg": "#007DC1",
|
|
"text": "#FFFFFF",
|
|
"hover": "#005F96",
|
|
"active": "#004D7A"
|
|
},
|
|
"saml": {
|
|
"bg": "#6B7280",
|
|
"text": "#FFFFFF",
|
|
"hover": "#4B5563",
|
|
"active": "#374151"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Gray Scale
|
|
|
|
Neutral colors for UI elements:
|
|
|
|
```json
|
|
{
|
|
"color": {
|
|
"gray": {
|
|
"50": "#fafafa",
|
|
"100": "#f5f5f5",
|
|
"200": "#eeeeee",
|
|
"300": "#e0e0e0",
|
|
"400": "#bdbdbd",
|
|
"500": "#9e9e9e",
|
|
"600": "#757575",
|
|
"700": "#616161",
|
|
"800": "#424242",
|
|
"900": "#212121"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
- 50-200: Backgrounds, subtle borders
|
|
- 300-400: Borders, dividers, disabled states
|
|
- 500-600: Secondary text, icons
|
|
- 700-900: Primary text, headings
|
|
|
|
---
|
|
|
|
### Text Colors
|
|
|
|
```json
|
|
{
|
|
"color": {
|
|
"text": {
|
|
"primary": "#212121", // Main body text
|
|
"secondary": "#616161", // Secondary text, captions
|
|
"disabled": "#9E9E9E", // Disabled state
|
|
"inverse": "#FFFFFF", // White text on dark bg
|
|
"link": "#2196F3", // Links
|
|
"link-hover": "#1976D2" // Link hover
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Background Colors
|
|
|
|
```json
|
|
{
|
|
"color": {
|
|
"background": {
|
|
"primary": "#FFFFFF", // Main page background
|
|
"secondary": "#F5F5F5", // Card backgrounds
|
|
"tertiary": "#FAFAFA", // Subtle backgrounds
|
|
"overlay": "rgba(0, 0, 0, 0.5)", // Modal backdrop
|
|
"hover": "#F8F9FA", // Hover state
|
|
"selected": "#E3F2FD" // Selected state
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Typography Tokens
|
|
|
|
### Font Families
|
|
|
|
```json
|
|
{
|
|
"font": {
|
|
"family": {
|
|
"sans": [
|
|
"Inter",
|
|
"Roboto",
|
|
"PingFang SC",
|
|
"Microsoft YaHei",
|
|
"sans-serif"
|
|
],
|
|
"mono": [
|
|
"JetBrains Mono",
|
|
"Consolas",
|
|
"Monaco",
|
|
"monospace"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Loading:**
|
|
```html
|
|
<!-- Google Fonts -->
|
|
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
```
|
|
|
|
---
|
|
|
|
### Font Sizes
|
|
|
|
```json
|
|
{
|
|
"font": {
|
|
"size": {
|
|
"xs": {
|
|
"size": "12px",
|
|
"lineHeight": "16px",
|
|
"letterSpacing": "0.01em"
|
|
},
|
|
"sm": {
|
|
"size": "14px",
|
|
"lineHeight": "20px",
|
|
"letterSpacing": "0.01em"
|
|
},
|
|
"base": {
|
|
"size": "16px",
|
|
"lineHeight": "24px",
|
|
"letterSpacing": "0"
|
|
},
|
|
"lg": {
|
|
"size": "18px",
|
|
"lineHeight": "28px",
|
|
"letterSpacing": "0"
|
|
},
|
|
"xl": {
|
|
"size": "20px",
|
|
"lineHeight": "28px",
|
|
"letterSpacing": "-0.01em"
|
|
},
|
|
"2xl": {
|
|
"size": "24px",
|
|
"lineHeight": "32px",
|
|
"letterSpacing": "-0.01em"
|
|
},
|
|
"3xl": {
|
|
"size": "30px",
|
|
"lineHeight": "36px",
|
|
"letterSpacing": "-0.02em"
|
|
},
|
|
"4xl": {
|
|
"size": "36px",
|
|
"lineHeight": "40px",
|
|
"letterSpacing": "-0.02em"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
- xs: Labels, captions, metadata
|
|
- sm: Body text (small), secondary info
|
|
- base: Default body text
|
|
- lg: Emphasized text, subheadings
|
|
- xl-4xl: Headings (H4 → H1)
|
|
|
|
---
|
|
|
|
### Font Weights
|
|
|
|
```json
|
|
{
|
|
"font": {
|
|
"weight": {
|
|
"normal": "400",
|
|
"medium": "500",
|
|
"semibold": "600",
|
|
"bold": "700"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
- normal: Body text, descriptions
|
|
- medium: Emphasized text, button labels
|
|
- semibold: Subheadings, card titles
|
|
- bold: Main headings, important labels
|
|
|
|
---
|
|
|
|
### Line Heights
|
|
|
|
```json
|
|
{
|
|
"font": {
|
|
"lineHeight": {
|
|
"none": "1",
|
|
"tight": "1.25",
|
|
"snug": "1.375",
|
|
"normal": "1.5",
|
|
"relaxed": "1.625",
|
|
"loose": "2"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Spacing Tokens
|
|
|
|
8px base grid system:
|
|
|
|
```json
|
|
{
|
|
"spacing": {
|
|
"0": "0px",
|
|
"0.5": "2px",
|
|
"1": "4px", // 0.5 * 8
|
|
"1.5": "6px",
|
|
"2": "8px", // 1 * 8
|
|
"2.5": "10px",
|
|
"3": "12px", // 1.5 * 8
|
|
"3.5": "14px",
|
|
"4": "16px", // 2 * 8
|
|
"5": "20px", // 2.5 * 8
|
|
"6": "24px", // 3 * 8
|
|
"7": "28px",
|
|
"8": "32px", // 4 * 8
|
|
"9": "36px",
|
|
"10": "40px", // 5 * 8
|
|
"11": "44px",
|
|
"12": "48px", // 6 * 8
|
|
"14": "56px",
|
|
"16": "64px", // 8 * 8
|
|
"20": "80px", // 10 * 8
|
|
"24": "96px", // 12 * 8
|
|
"28": "112px",
|
|
"32": "128px",
|
|
"36": "144px",
|
|
"40": "160px",
|
|
"44": "176px",
|
|
"48": "192px",
|
|
"52": "208px",
|
|
"56": "224px",
|
|
"60": "240px",
|
|
"64": "256px",
|
|
"72": "288px",
|
|
"80": "320px",
|
|
"96": "384px"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Common Patterns:**
|
|
- Component padding: 4, 6, 8
|
|
- Element gaps: 2, 3, 4, 6
|
|
- Section spacing: 8, 12, 16
|
|
- Page margins: 4 (mobile), 6 (tablet), 8 (desktop)
|
|
|
|
---
|
|
|
|
## Border Radius Tokens
|
|
|
|
```json
|
|
{
|
|
"borderRadius": {
|
|
"none": "0",
|
|
"sm": "4px",
|
|
"DEFAULT": "6px",
|
|
"md": "8px",
|
|
"lg": "12px",
|
|
"xl": "16px",
|
|
"2xl": "24px",
|
|
"3xl": "32px",
|
|
"full": "9999px"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
- sm: Small buttons, badges
|
|
- DEFAULT: Input fields, standard buttons
|
|
- md: Cards, panels
|
|
- lg: Modals, large cards
|
|
- xl: Feature sections
|
|
- full: Pills, avatar images, toggle switches
|
|
|
|
---
|
|
|
|
## Shadow Tokens
|
|
|
|
```json
|
|
{
|
|
"boxShadow": {
|
|
"none": "none",
|
|
"sm": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
|
|
"DEFAULT": "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06)",
|
|
"md": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
|
|
"lg": "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)",
|
|
"xl": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)",
|
|
"2xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)",
|
|
"inner": "inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)",
|
|
"focus": "0 0 0 3px rgba(33, 150, 243, 0.3)"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
- sm: Subtle cards, hover states
|
|
- DEFAULT: Standard cards, dropdowns
|
|
- md: Elevated panels, popovers
|
|
- lg: Modals, important panels
|
|
- xl: Large modals, feature blocks
|
|
- focus: Focus rings on interactive elements
|
|
|
|
---
|
|
|
|
## Animation Tokens
|
|
|
|
### Duration
|
|
|
|
```json
|
|
{
|
|
"transitionDuration": {
|
|
"75": "75ms",
|
|
"100": "100ms",
|
|
"150": "150ms",
|
|
"200": "200ms",
|
|
"300": "300ms",
|
|
"500": "500ms",
|
|
"700": "700ms",
|
|
"1000": "1000ms"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
- 75-150ms: Micro-interactions (hover, focus)
|
|
- 200-300ms: Standard transitions (expand, fade)
|
|
- 500-700ms: Complex animations (page transitions)
|
|
- 1000ms: Special effects (success celebrations)
|
|
|
|
---
|
|
|
|
### Easing
|
|
|
|
```json
|
|
{
|
|
"transitionTimingFunction": {
|
|
"linear": "linear",
|
|
"in": "cubic-bezier(0.4, 0, 1, 1)",
|
|
"out": "cubic-bezier(0, 0, 0.2, 1)",
|
|
"in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
|
|
"spring": "cubic-bezier(0.175, 0.885, 0.32, 1.275)"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
- out: Elements entering (modals, dropdowns)
|
|
- in: Elements exiting (close, hide)
|
|
- in-out: Smooth transitions (toggle, expand)
|
|
- spring: Playful animations (success states)
|
|
|
|
---
|
|
|
|
## Z-Index Tokens
|
|
|
|
Layer hierarchy:
|
|
|
|
```json
|
|
{
|
|
"zIndex": {
|
|
"base": "0",
|
|
"dropdown": "1000",
|
|
"sticky": "1020",
|
|
"fixed": "1030",
|
|
"modal-backdrop": "1040",
|
|
"modal": "1050",
|
|
"popover": "1060",
|
|
"tooltip": "1070",
|
|
"notification": "1080"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Layer Stack (bottom to top):**
|
|
1. base (0): Normal document flow
|
|
2. dropdown (1000): Dropdown menus
|
|
3. sticky (1020): Sticky headers
|
|
4. fixed (1030): Fixed navigation
|
|
5. modal-backdrop (1040): Modal backdrop
|
|
6. modal (1050): Modal dialogs
|
|
7. popover (1060): Popovers
|
|
8. tooltip (1070): Tooltips
|
|
9. notification (1080): Toast notifications
|
|
|
|
---
|
|
|
|
## Icon Sizes
|
|
|
|
```json
|
|
{
|
|
"icon": {
|
|
"size": {
|
|
"xs": "12px",
|
|
"sm": "16px",
|
|
"base": "20px",
|
|
"md": "24px",
|
|
"lg": "32px",
|
|
"xl": "40px",
|
|
"2xl": "48px"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Usage:**
|
|
- xs: Inline icons, metadata
|
|
- sm: Button icons (small)
|
|
- base: Standard button icons
|
|
- md: Card icons, list icons
|
|
- lg: Section icons, empty states
|
|
- xl-2xl: Hero icons, feature illustrations
|
|
|
|
---
|
|
|
|
## Implementation
|
|
|
|
### CSS Variables
|
|
|
|
Generate CSS custom properties from tokens:
|
|
|
|
```css
|
|
/* colors.css */
|
|
:root {
|
|
/* Brand Colors */
|
|
--color-primary-50: #e3f2fd;
|
|
--color-primary-100: #bbdefb;
|
|
--color-primary-500: #2196F3;
|
|
--color-primary-700: #1976D2;
|
|
|
|
/* Semantic Colors */
|
|
--color-success: #4CAF50;
|
|
--color-warning: #FF9800;
|
|
--color-error: #F44336;
|
|
--color-info: #2196F3;
|
|
|
|
/* SSO Provider Colors */
|
|
--color-sso-microsoft: #00A4EF;
|
|
--color-sso-google: #FFFFFF;
|
|
--color-sso-okta: #007DC1;
|
|
|
|
/* Spacing */
|
|
--spacing-2: 8px;
|
|
--spacing-4: 16px;
|
|
--spacing-6: 24px;
|
|
--spacing-8: 32px;
|
|
|
|
/* Typography */
|
|
--font-size-sm: 14px;
|
|
--font-size-base: 16px;
|
|
--font-size-lg: 18px;
|
|
--font-size-xl: 20px;
|
|
|
|
--font-weight-normal: 400;
|
|
--font-weight-medium: 500;
|
|
--font-weight-semibold: 600;
|
|
--font-weight-bold: 700;
|
|
|
|
/* Border Radius */
|
|
--radius-sm: 4px;
|
|
--radius-md: 8px;
|
|
--radius-lg: 12px;
|
|
--radius-full: 9999px;
|
|
|
|
/* Shadows */
|
|
--shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
|
|
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
|
|
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
|
|
|
|
/* Z-Index */
|
|
--z-dropdown: 1000;
|
|
--z-modal: 1050;
|
|
--z-tooltip: 1070;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Tailwind Configuration
|
|
|
|
```typescript
|
|
// tailwind.config.ts
|
|
import type { Config } from 'tailwindcss';
|
|
|
|
const config: Config = {
|
|
content: [
|
|
'./src/pages/**/*.{js,ts,jsx,tsx,mdx}',
|
|
'./src/components/**/*.{js,ts,jsx,tsx,mdx}',
|
|
'./src/app/**/*.{js,ts,jsx,tsx,mdx}',
|
|
],
|
|
theme: {
|
|
extend: {
|
|
colors: {
|
|
primary: {
|
|
50: '#e3f2fd',
|
|
100: '#bbdefb',
|
|
200: '#90caf9',
|
|
300: '#64b5f6',
|
|
400: '#42a5f5',
|
|
500: '#2196F3',
|
|
600: '#1e88e5',
|
|
700: '#1976D2',
|
|
800: '#1565c0',
|
|
900: '#0d47a1',
|
|
},
|
|
success: '#4CAF50',
|
|
warning: '#FF9800',
|
|
error: '#F44336',
|
|
info: '#2196F3',
|
|
sso: {
|
|
microsoft: '#00A4EF',
|
|
google: '#FFFFFF',
|
|
okta: '#007DC1',
|
|
saml: '#6B7280',
|
|
},
|
|
},
|
|
fontFamily: {
|
|
sans: ['Inter', 'Roboto', 'PingFang SC', 'Microsoft YaHei', 'sans-serif'],
|
|
mono: ['JetBrains Mono', 'Consolas', 'monospace'],
|
|
},
|
|
fontSize: {
|
|
'xs': ['12px', { lineHeight: '16px' }],
|
|
'sm': ['14px', { lineHeight: '20px' }],
|
|
'base': ['16px', { lineHeight: '24px' }],
|
|
'lg': ['18px', { lineHeight: '28px' }],
|
|
'xl': ['20px', { lineHeight: '28px' }],
|
|
'2xl': ['24px', { lineHeight: '32px' }],
|
|
'3xl': ['30px', { lineHeight: '36px' }],
|
|
'4xl': ['36px', { lineHeight: '40px' }],
|
|
},
|
|
spacing: {
|
|
'0.5': '2px',
|
|
'1': '4px',
|
|
'1.5': '6px',
|
|
'2': '8px',
|
|
'3': '12px',
|
|
'4': '16px',
|
|
'5': '20px',
|
|
'6': '24px',
|
|
'8': '32px',
|
|
'10': '40px',
|
|
'12': '48px',
|
|
'16': '64px',
|
|
'20': '80px',
|
|
'24': '96px',
|
|
},
|
|
borderRadius: {
|
|
'sm': '4px',
|
|
'DEFAULT': '6px',
|
|
'md': '8px',
|
|
'lg': '12px',
|
|
'xl': '16px',
|
|
'2xl': '24px',
|
|
'full': '9999px',
|
|
},
|
|
boxShadow: {
|
|
'sm': '0 1px 2px 0 rgba(0, 0, 0, 0.05)',
|
|
'DEFAULT': '0 1px 3px 0 rgba(0, 0, 0, 0.1)',
|
|
'md': '0 4px 6px -1px rgba(0, 0, 0, 0.1)',
|
|
'lg': '0 10px 15px -3px rgba(0, 0, 0, 0.1)',
|
|
'xl': '0 20px 25px -5px rgba(0, 0, 0, 0.1)',
|
|
'focus': '0 0 0 3px rgba(33, 150, 243, 0.3)',
|
|
},
|
|
zIndex: {
|
|
'dropdown': '1000',
|
|
'sticky': '1020',
|
|
'fixed': '1030',
|
|
'modal-backdrop': '1040',
|
|
'modal': '1050',
|
|
'popover': '1060',
|
|
'tooltip': '1070',
|
|
'notification': '1080',
|
|
},
|
|
transitionDuration: {
|
|
'75': '75ms',
|
|
'150': '150ms',
|
|
'200': '200ms',
|
|
'300': '300ms',
|
|
'500': '500ms',
|
|
},
|
|
},
|
|
},
|
|
plugins: [],
|
|
};
|
|
|
|
export default config;
|
|
```
|
|
|
|
---
|
|
|
|
### TypeScript Token Types
|
|
|
|
```typescript
|
|
// types/tokens.ts
|
|
export type ColorToken = {
|
|
50?: string;
|
|
100?: string;
|
|
200?: string;
|
|
300?: string;
|
|
400?: string;
|
|
500?: string;
|
|
600?: string;
|
|
700?: string;
|
|
800?: string;
|
|
900?: string;
|
|
DEFAULT?: string;
|
|
};
|
|
|
|
export type SpacingToken = string | number;
|
|
|
|
export type FontSizeToken = {
|
|
size: string;
|
|
lineHeight: string;
|
|
letterSpacing?: string;
|
|
};
|
|
|
|
export const tokens = {
|
|
colors: {
|
|
primary: { /* ... */ },
|
|
success: '#4CAF50',
|
|
// ...
|
|
},
|
|
spacing: {
|
|
2: '8px',
|
|
4: '16px',
|
|
// ...
|
|
},
|
|
fontSize: {
|
|
base: { size: '16px', lineHeight: '24px' },
|
|
// ...
|
|
},
|
|
} as const;
|
|
|
|
export type Tokens = typeof tokens;
|
|
```
|
|
|
|
---
|
|
|
|
### Usage Examples
|
|
|
|
#### Using in Components
|
|
|
|
```tsx
|
|
// SsoButton.tsx
|
|
import { tokens } from '@/design/tokens';
|
|
|
|
export const SsoButton = ({ provider }: { provider: string }) => {
|
|
return (
|
|
<button
|
|
style={{
|
|
backgroundColor: tokens.colors.sso[provider],
|
|
padding: `${tokens.spacing[3]} ${tokens.spacing[6]}`,
|
|
borderRadius: tokens.borderRadius.md,
|
|
fontSize: tokens.fontSize.base.size,
|
|
fontWeight: tokens.fontWeight.medium,
|
|
boxShadow: tokens.boxShadow.sm,
|
|
transition: `all ${tokens.transitionDuration[200]} ${tokens.transitionTimingFunction.out}`,
|
|
}}
|
|
>
|
|
{/* Button content */}
|
|
</button>
|
|
);
|
|
};
|
|
```
|
|
|
|
#### Using with Tailwind
|
|
|
|
```tsx
|
|
// LoginForm.tsx
|
|
export const LoginForm = () => {
|
|
return (
|
|
<form className="
|
|
space-y-6
|
|
p-8
|
|
bg-white
|
|
rounded-lg
|
|
shadow-lg
|
|
">
|
|
<Input
|
|
className="
|
|
text-base
|
|
px-4 py-3
|
|
rounded-md
|
|
border border-gray-300
|
|
focus:border-primary-500
|
|
focus:shadow-focus
|
|
"
|
|
/>
|
|
|
|
<Button
|
|
className="
|
|
w-full
|
|
px-6 py-3
|
|
bg-primary-500
|
|
hover:bg-primary-700
|
|
text-white
|
|
font-medium
|
|
rounded-md
|
|
shadow-sm
|
|
transition-all duration-200
|
|
"
|
|
>
|
|
Sign In
|
|
</Button>
|
|
</form>
|
|
);
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Token Maintenance
|
|
|
|
### Version Control
|
|
|
|
```json
|
|
{
|
|
"version": "1.0.0",
|
|
"lastUpdated": "2025-11-03",
|
|
"changelog": [
|
|
{
|
|
"version": "1.0.0",
|
|
"date": "2025-11-03",
|
|
"changes": [
|
|
"Initial design token system",
|
|
"Added SSO provider colors",
|
|
"Defined spacing scale",
|
|
"Established typography system"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Update Process
|
|
|
|
1. **Propose Change:** Create design proposal document
|
|
2. **Review:** UX/UI team reviews with stakeholders
|
|
3. **Approve:** Get sign-off from design lead
|
|
4. **Update Tokens:** Modify token definitions
|
|
5. **Update Components:** Update affected components
|
|
6. **Test:** Visual regression testing
|
|
7. **Document:** Update changelog
|
|
8. **Release:** Deploy with version bump
|
|
|
|
### Testing Tokens
|
|
|
|
```typescript
|
|
// tokens.test.ts
|
|
import { tokens } from '@/design/tokens';
|
|
|
|
describe('Design Tokens', () => {
|
|
test('Primary color contrast meets WCAG AA', () => {
|
|
const contrast = getContrast(tokens.colors.primary[500], '#FFFFFF');
|
|
expect(contrast).toBeGreaterThanOrEqual(4.5);
|
|
});
|
|
|
|
test('Spacing follows 8px grid', () => {
|
|
Object.values(tokens.spacing).forEach(value => {
|
|
const px = parseInt(value);
|
|
expect(px % 4).toBe(0); // All spacing is multiple of 4
|
|
});
|
|
});
|
|
|
|
test('Font sizes are readable', () => {
|
|
const baseFontSize = parseInt(tokens.fontSize.base.size);
|
|
expect(baseFontSize).toBeGreaterThanOrEqual(16); // Min 16px for body
|
|
});
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Accessibility Considerations
|
|
|
|
### Color Contrast
|
|
|
|
All color combinations meet WCAG 2.1 Level AA standards:
|
|
|
|
- **Normal text (< 18px):** Contrast ratio ≥ 4.5:1
|
|
- **Large text (≥ 18px or 14px bold):** Contrast ratio ≥ 3:1
|
|
|
|
**Tested Combinations:**
|
|
- Primary-500 on white: 4.53:1 ✓
|
|
- Success on white: 3.94:1 ✓ (large text only)
|
|
- Error on white: 4.61:1 ✓
|
|
- Gray-700 on white: 6.41:1 ✓
|
|
|
|
### Touch Targets
|
|
|
|
Minimum touch target size: **44x44px** (iOS guidelines)
|
|
|
|
All interactive elements (buttons, links, inputs) meet this requirement on mobile.
|
|
|
|
### Focus Indicators
|
|
|
|
All interactive elements have visible focus indicators:
|
|
|
|
```css
|
|
:focus-visible {
|
|
outline: 2px solid var(--color-primary-500);
|
|
outline-offset: 2px;
|
|
}
|
|
|
|
/* Alternative: focus ring */
|
|
:focus-visible {
|
|
box-shadow: var(--shadow-focus);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Conclusion
|
|
|
|
This design token system provides a consistent, maintainable foundation for ColaFlow's UI. By using tokens, we ensure:
|
|
|
|
1. **Consistency:** Same values across all components
|
|
2. **Maintainability:** Update once, apply everywhere
|
|
3. **Scalability:** Easy to extend with new tokens
|
|
4. **Accessibility:** Built-in contrast and sizing standards
|
|
5. **Developer Experience:** Type-safe, autocomplete-friendly
|
|
|
|
**Next Steps:**
|
|
1. Integrate tokens into component library
|
|
2. Set up visual regression testing
|
|
3. Create Figma design system linked to tokens
|
|
4. Document token usage guidelines
|
|
5. Train team on token system
|
|
|
|
**Questions:** Contact UX/UI team at ux@colaflow.com
|