# Appiqa Genesis — Design Tokens & System Specification

> The flagship AI-friendly design system for developer tools, high-speed SaaS, and Next.js applications.

---

## 1. Design System Archetype & Best Project Fit

- **System Archetype**: `saas`
- **Specification Format**: `DESIGN.md v1.0` (Tailwind 50-950 + Semantic Role Architecture)
- **Target Integrations**: Cursor, Claude Code, Windsurf, Antigravity, Tailwind CSS v3/v4

### 1.1 Recommended Use Cases & Project Fit
- **Best For**: B2B SaaS Applications, Developer Platforms & APIs, Cloud Management Portals, Next.js 16 Web Applications
- **Visual Personality**: Clean, authoritative, minimal cognitive load, engineered for AI pair programming.
- **Industry Fit**: Developer Tools, B2B Software, Cloud Services, Productivity
- **Design Pairing Tip**: Inter + JetBrains Mono, dense 4px grid system, subtle card borders.

---

## 2. Complete 50-950 Tailwind Color Scales

### 2.1 Primary Brand Scale (`primary`)
| Shade | Hex Code | Tailwind Class | Contrast Text |
| :--- | :--- | :--- | :--- |
| **50** | `#EEEDFC` | `bg-primary-50` | Dark text |
| **100** | `#D4D2F9` | `bg-primary-100` | Dark text |
| **200** | `#AAA6F2` | `bg-primary-200` | Dark text |
| **300** | `#7F79EC` | `bg-primary-300` | Dark text |
| **400** | `#544CE6` | `bg-primary-400` | Dark text |
| **500** | `#4F46E5` | `bg-primary-500` | Light text |
| **600** | `#241CC4` (Base CTA) | `bg-primary-600` | Light text (`text-white`) |
| **700** | `#1D169C` (Hover) | `bg-primary-700` | Light text (`text-white`) |
| **800** | `#161174` (Active) | `bg-primary-800` | Light text (`text-white`) |
| **900** | `#0F0B50` | `bg-primary-900` | Light text |
| **950** | `#090731` | `bg-primary-950` | Light text |

### 2.2 Secondary Accent Scale (`secondary`)
| Shade | Hex Code | Tailwind Class |
| :--- | :--- | :--- |
| **50** | `#EBFCFE` | `bg-secondary-50` |
| **100** | `#CEF6FD` | `bg-secondary-100` |
| **500** | `#06B6D4` | `bg-secondary-500` |
| **600** | `#07BADA` | `bg-secondary-600` |
| **700** | `#0594AD` | `bg-secondary-700` |
| **950** | `#022F36` | `bg-secondary-950` |

---

## 3. Semantic Color Tokens

### 2.1 Brand & Interactive Tokens

| Token Name | Light Mode | Dark Mode | Description |
| :--- | :--- | :--- | :--- |
| `brand.primary` | `#4F46E5` | `#4C44E4` | Main CTA, active states, key interactive indicators |
| `brand.onPrimary` | `#FFFFFF` (CR 6.29:1) | `#FFFFFF` (CR 6.45:1) | High-contrast foreground text/icon atop primary |
| `brand.container` | `#E5E4FB` | `#0F0B50` | Subtle brand backgrounds, badges, and soft highlights |
| `brand.onContainer` | `#120E62` | `#CCC9F7` | Text and icons rendered atop brand containers |

### 2.2 Surface Tokens

| Token Name | Light Mode | Dark Mode | Description |
| :--- | :--- | :--- | :--- |
| `surface.background` | `#FFFFFF` | `#090B0E` | Base screen canvas background |
| `surface.canvas` | `#F8FAFC` | `#090B0E` | Sectioning canvas / secondary background |
| `surface.card` | `#FFFFFF` | `#11151B` | Default card and component container background |
| `surface.subtle` | `#F1F5F9` | `#171C24` | Muted card header or soft grouped container |
| `surface.raised` | `#FFFFFF` | `#1C222C` | Modals, dropdowns, popovers, elevated surfaces |
| `surface.overlay` | `rgba(15, 23, 42, 0.75)` | `rgba(0, 0, 0, 0.85)` | Backdrop overlay for dialogs and sheets |

### 2.3 Typography & Foreground Tokens

| Token Name | Light Mode | Dark Mode | Description |
| :--- | :--- | :--- | :--- |
| `text.primary` | `#0F172A` | `#F8FAFC` | Headings, high-emphasis text, prominent titles |
| `text.secondary` | `#475569` | `#CBD5E1` | Body copy, subtitles, secondary descriptive text |
| `text.muted` | `#94A3B8` | `#64748B` | Placeholders, captions, timestamps, subtle meta |
| `text.inverse` | `#FFFFFF` | `#090B0E` | Contrast text when placed on inverse surfaces |

### 2.4 Border & Stroke Tokens

| Token Name | Light Mode | Dark Mode | Description |
| :--- | :--- | :--- | :--- |
| `border.subtle` | `#F1F5F9` | `rgba(255, 255, 255, 0.07)` | Subtle grid lines, light separators, table dividers |
| `border.default` | `#E2E8F0` | `rgba(255, 255, 255, 0.12)` | Default element boundary, inputs, inactive cards |
| `border.strong` | `#CBD5E1` | `rgba(255, 255, 255, 0.22)` | Emphasized borders, hover states, active outlines |
| `border.focus` | `#4F46E5` | `#4C44E4` | Keyboard navigation and focus ring token |

### 2.5 Feedback & Status Tokens

| Token Name | Light Mode | Dark Mode | Description |
| :--- | :--- | :--- | :--- |
| `status.success` | `#10B981` | `#34D399` | Success states, verified badges, positive balance |
| `status.warning` | `#F59E0B` | `#FBBF24` | Cautionary notices, pending states, alerts |
| `status.danger` | `#EF4444` | `#F87171` | Errors, destructive actions, negative alerts |
| `status.info` | `#0EA5E9` | `#38BDF8` | Informational messages, contextual tips |

---

## 3. Typography & Spacing Foundations

- **Display Font**: `Inter`
- **Body Font**: `Inter`
- **Monospace Font**: `JetBrains Mono, Menlo, monospace`
- **Base Font Size**: `16px`
- **Base Grid Unit**: `4px`
- **Border Radii**:
  - Small (Inputs, Badges): `6px`
  - Medium (Cards, Buttons): `12px`
  - Large (Modals, Hero banners): `20px`

---

## 4. AI Coding Agent Component Recipes

When building components with Tailwind CSS in this project, use these exact class combinations:

### 4.1 Primary Buttons
- **Solid Primary**: `px-4 py-2 rounded-xl bg-primary-600 hover:bg-primary-700 active:bg-primary-800 text-white font-semibold shadow-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 disabled:opacity-50 disabled:cursor-not-allowed transition-all`
- **Outline Primary**: `px-4 py-2 rounded-xl border border-primary-500 text-primary-600 dark:text-primary-400 hover:bg-primary-50 dark:hover:bg-primary-950/60 font-semibold transition-all`
- **Soft Brand Container**: `px-4 py-2 rounded-xl bg-primary-50 dark:bg-primary-950/80 text-primary-700 dark:text-primary-300 hover:bg-primary-100 font-semibold transition-all`
- **Ghost Button**: `px-3 py-2 rounded-xl text-slate-700 dark:text-slate-300 hover:bg-slate-100 dark:hover:bg-slate-800 font-medium transition-colors`

### 4.2 Status & Tag Badges
- **Brand Pill**: `inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-full text-xs font-semibold bg-primary-50 dark:bg-primary-950/80 text-primary-700 dark:text-primary-300 border border-primary-200 dark:border-primary-800`
- **Success Pill**: `inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-full text-xs font-semibold bg-emerald-50 dark:bg-emerald-950/80 text-emerald-700 dark:text-emerald-300 border border-emerald-200 dark:border-emerald-800`
- **Warning Pill**: `inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-full text-xs font-semibold bg-amber-50 dark:bg-amber-950/80 text-amber-700 dark:text-amber-300 border border-amber-200 dark:border-amber-800`
- **Danger Pill**: `inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-full text-xs font-semibold bg-rose-50 dark:bg-rose-950/80 text-rose-700 dark:text-rose-300 border border-rose-200 dark:border-rose-800`

### 4.3 Form Inputs
- **Text Input**: `w-full px-3.5 py-2 text-sm rounded-xl border border-slate-200 dark:border-slate-800 bg-white dark:bg-slate-900 text-slate-900 dark:text-white placeholder:text-slate-400 focus:outline-none focus:ring-2 focus:ring-primary-500 focus:border-transparent transition-all`
- **Input Error State**: `border-rose-300 dark:border-rose-800 focus:ring-rose-500 text-rose-900 dark:text-rose-100`

### 4.4 Surface Cards
- **Interactive Card**: `p-6 rounded-2xl bg-white dark:bg-slate-900 border border-slate-200/80 dark:border-slate-800/80 shadow-xs hover:shadow-md transition-shadow`

---

## 5. Implementation Snippets

### 5.1 CSS Custom Properties (Variables)

```css
/* Light Mode Tokens */
:root {
  --color-surface-bg: #FFFFFF;
  --color-surface-card: #FFFFFF;
  --color-surface-subtle: #F1F5F9;
  --color-surface-raised: #FFFFFF;
  
  --color-text-primary: #0F172A;
  --color-text-secondary: #475569;
  --color-text-muted: #94A3B8;
  
  --color-border-subtle: #F1F5F9;
  --color-border-default: #E2E8F0;
  --color-border-strong: #CBD5E1;
  --color-border-focus: #4F46E5;

  --color-brand-primary: #4F46E5;
  --color-brand-on-primary: #FFFFFF;
  --color-brand-container: #E5E4FB;
  --color-brand-on-container: #120E62;

  --color-status-success: #10B981;
  --color-status-warning: #F59E0B;
  --color-status-danger: #EF4444;
  --color-status-info: #0EA5E9;
}

/* Dark Mode Tokens */
.dark, [data-theme="dark"] {
  --color-surface-bg: #090B0E;
  --color-surface-card: #11151B;
  --color-surface-subtle: #171C24;
  --color-surface-raised: #1C222C;
  
  --color-text-primary: #F8FAFC;
  --color-text-secondary: #CBD5E1;
  --color-text-muted: #64748B;
  
  --color-border-subtle: rgba(255, 255, 255, 0.07);
  --color-border-default: rgba(255, 255, 255, 0.12);
  --color-border-strong: rgba(255, 255, 255, 0.22);
  --color-border-focus: #4C44E4;

  --color-brand-primary: #4C44E4;
  --color-brand-on-primary: #FFFFFF;
  --color-brand-container: #0F0B50;
  --color-brand-on-container: #CCC9F7;

  --color-status-success: #34D399;
  --color-status-warning: #FBBF24;
  --color-status-danger: #F87171;
  --color-status-info: #38BDF8;
}
```

### 4.2 Tailwind CSS Configuration (`tailwind.config.ts`)

```typescript
export default {
  theme: {
    extend: {
      colors: {
        surface: {
          DEFAULT: 'var(--color-surface-bg)',
          card: 'var(--color-surface-card)',
          subtle: 'var(--color-surface-subtle)',
          raised: 'var(--color-surface-raised)',
        },
        token: {
          primary: 'var(--color-text-primary)',
          secondary: 'var(--color-text-secondary)',
          muted: 'var(--color-text-muted)',
        },
        brand: {
          DEFAULT: 'var(--color-brand-primary)',
          fg: 'var(--color-brand-on-primary)',
          container: 'var(--color-brand-container)',
          'container-fg': 'var(--color-brand-on-container)',
        },
        border: {
          subtle: 'var(--color-border-subtle)',
          DEFAULT: 'var(--color-border-default)',
          strong: 'var(--color-border-strong)',
          focus: 'var(--color-border-focus)',
        },
        status: {
          success: 'var(--color-status-success)',
          warning: 'var(--color-status-warning)',
          danger: 'var(--color-status-danger)',
          info: 'var(--color-status-info)',
        }
      }
    }
  }
}
```

---
*Generated by Appiqa Design MD Engine — [https://appiqa.com/design-md](https://appiqa.com/design-md)*