aethex-forge/DESIGN_SYSTEM.md

Developer Platform Design System

Status: Foundation Complete
Version: 1.0
Last Updated: January 7, 2026

---

🎨 Design Principles

Visual Identity

• Dark Mode First: Developer-optimized color scheme
• Clean & Technical: Inspired by Vercel, Stripe, and GitHub
• Consistent Branding: Aligned with AeThex blue/purple theme
• Professional: Business-ready, not gaming-flashy

UX Principles

• Developer Efficiency: Keyboard shortcuts, quick actions
• Progressive Disclosure: Simple by default, power features available
• Consistent Patterns: Same interaction model across modules
• Fast & Responsive: < 100ms interaction latency

---

🎭 Typography

Font Families

Primary UI Font:

font-family: "Inter", "-apple-system", "BlinkMacSystemFont", "Segoe UI", sans-serif;

Code Font:

font-family: "JetBrains Mono", "Fira Code", "Courier New", monospace;

Usage in Components:

• All UI text: Inter (default)
• Code blocks: JetBrains Mono (monospace)
• API endpoints: Monospace
• Documentation: Inter with generous line-height

Typography Scale

text-xs:   0.75rem  (12px)
text-sm:   0.875rem (14px)
text-base: 1rem     (16px)
text-lg:   1.125rem (18px)
text-xl:   1.25rem  (20px)
text-2xl:  1.5rem   (24px)
text-3xl:  1.875rem (30px)
text-4xl:  2.25rem  (36px)

---

🌈 Color System

Brand Colors (AeThex)

--aethex-500: hsl(250 100% 60%)  /* Primary brand color */
--aethex-600: hsl(250 100% 50%)  /* Darker variant */
--aethex-400: hsl(250 100% 70%)  /* Lighter variant */

Semantic Colors

Primary (Interactive Elements)

--primary: hsl(250 100% 60%)              /* Buttons, links, active states */
--primary-foreground: hsl(210 40% 98%)    /* Text on primary background */

Background

--background: hsl(222 84% 4.9%)           /* Page background */
--foreground: hsl(210 40% 98%)            /* Primary text */

Muted (Secondary Elements)

--muted: hsl(217.2 32.6% 17.5%)           /* Disabled, placeholders */
--muted-foreground: hsl(215 20.2% 65.1%)  /* Secondary text */

Accent (Hover States)

--accent: hsl(217.2 32.6% 17.5%)          /* Hover backgrounds */
--accent-foreground: hsl(210 40% 98%)     /* Text on accent */

Borders

--border: hsl(217.2 32.6% 17.5%)          /* Default borders */
--border/40: Border with 40% opacity      /* Subtle borders */

Status Colors

/* Success */
--success: hsl(120 100% 70%)
--success-bg: hsl(120 100% 70% / 0.1)

/* Warning */
--warning: hsl(50 100% 70%)
--warning-bg: hsl(50 100% 70% / 0.1)

/* Error */
--error: hsl(0 62.8% 30.6%)
--error-bg: hsl(0 62.8% 30.6% / 0.1)

/* Info */
--info: hsl(210 100% 70%)
--info-bg: hsl(210 100% 70% / 0.1)

HTTP Method Colors

GET:    hsl(210 100% 50%)  /* Blue */
POST:   hsl(120 100% 40%)  /* Green */
PUT:    hsl(50 100% 50%)   /* Yellow */
DELETE: hsl(0 100% 50%)    /* Red */
PATCH:  hsl(280 100% 50%)  /* Purple */

---

📐 Spacing System

Based on 4px base unit:

--space-1: 4px
--space-2: 8px
--space-3: 12px
--space-4: 16px
--space-5: 24px
--space-6: 32px
--space-8: 48px
--space-12: 64px
--space-16: 96px

Common Patterns

/* Card padding */
p-6         /* 24px - standard card */
p-4         /* 16px - compact card */

/* Section spacing */
py-12       /* 48px - mobile */
py-16       /* 64px - desktop */

/* Component gaps */
gap-4       /* 16px - between related items */
gap-6       /* 24px - between sections */

---

📦 Component Library

Core Navigation Components

DevPlatformNav

Location: /client/components/dev-platform/DevPlatformNav.tsx

Features:

• Sticky header with backdrop blur
• Module switcher (Docs, API, SDK, Templates, Marketplace)
• Command palette trigger (Cmd+K)
• User menu
• Mobile responsive with hamburger menu

Usage:

import { DevPlatformNav } from "@/components/dev-platform/DevPlatformNav";

<DevPlatformNav />

DevPlatformFooter

Location: /client/components/dev-platform/DevPlatformFooter.tsx

Features:

• AeThex ecosystem links
• Resources, Community, Company sections
• Social media links
• Legal links

Usage:

import { DevPlatformFooter } from "@/components/dev-platform/DevPlatformFooter";

<DevPlatformFooter />

Breadcrumbs

Location: /client/components/dev-platform/Breadcrumbs.tsx

Features:

• Auto-generated from URL path
• Or manually specified items
• Home icon for root
• Clickable navigation

Usage:

import { Breadcrumbs } from "@/components/dev-platform/Breadcrumbs";

// Auto-generated
<Breadcrumbs />

// Manual
<Breadcrumbs
  items={[
    { label: "Docs", href: "/docs" },
    { label: "Getting Started", href: "/docs/getting-started" },
    { label: "Installation" }
  ]}
/>

Layout Components

DevPlatformLayout

Location: /client/components/dev-platform/layouts/DevPlatformLayout.tsx

Features:

• Wraps page content with nav and footer
• Optional hide nav/footer
• Flex layout with sticky nav

Usage:

import { DevPlatformLayout } from "@/components/dev-platform/layouts/DevPlatformLayout";

<DevPlatformLayout>
  <YourPageContent />
</DevPlatformLayout>

ThreeColumnLayout

Location: /client/components/dev-platform/layouts/ThreeColumnLayout.tsx

Features:

• Left: Navigation sidebar (sticky)
• Center: Main content
• Right: Table of contents or code examples (optional, sticky)
• Responsive (collapses on mobile)

Usage:

import { ThreeColumnLayout } from "@/components/dev-platform/layouts/ThreeColumnLayout";

<ThreeColumnLayout
  sidebar={<DocsSidebar />}
  aside={<TableOfContents />}
>
  <ArticleContent />
</ThreeColumnLayout>

UI Components

CodeBlock

Location: /client/components/dev-platform/ui/CodeBlock.tsx

Features:

• Syntax highlighting (basic)
• Copy to clipboard button
• Optional line numbers
• Optional line highlighting
• Language badge
• File name header

Usage:

import { CodeBlock } from "@/components/dev-platform/ui/CodeBlock";

<CodeBlock
  code={`const game = new AeThex.Game();\ngame.start();`}
  language="typescript"
  fileName="example.ts"
  showLineNumbers={true}
  highlightLines={[2]}
/>

Callout

Location: /client/components/dev-platform/ui/Callout.tsx

Features:

• Four types: info, warning, success, error
• Optional title
• Icon included
• Semantic colors

Usage:

import { Callout } from "@/components/dev-platform/ui/Callout";

<Callout type="warning" title="Important">
  Make sure to set your API key before deployment.
</Callout>

StatCard

Location: /client/components/dev-platform/ui/StatCard.tsx

Features:

• Dashboard metric display
• Optional icon
• Optional trend indicator (↑ +5%)
• Hover effect

Usage:

import { StatCard } from "@/components/dev-platform/ui/StatCard";
import { Zap } from "lucide-react";

<StatCard
  title="API Calls"
  value="1.2M"
  description="Last 30 days"
  icon={Zap}
  trend={{ value: 12, isPositive: true }}
/>

ApiEndpointCard

Location: /client/components/dev-platform/ui/ApiEndpointCard.tsx

Features:

• HTTP method badge (color-coded)
• Endpoint path in monospace
• Description
• Clickable for details
• Hover effect

Usage:

import { ApiEndpointCard } from "@/components/dev-platform/ui/ApiEndpointCard";

<ApiEndpointCard
  method="POST"
  endpoint="/api/creators"
  description="Create a new creator profile"
  onClick={() => navigate('/api-reference/creators')}
/>

---

🎯 Usage Patterns

Page Structure (Standard)

import { DevPlatformLayout } from "@/components/dev-platform/layouts/DevPlatformLayout";
import { Breadcrumbs } from "@/components/dev-platform/Breadcrumbs";

export default function MyPage() {
  return (
    <DevPlatformLayout>
      <div className="container py-10">
        <Breadcrumbs />
        <h1 className="text-4xl font-bold mt-4 mb-6">Page Title</h1>
        {/* Page content */}
      </div>
    </DevPlatformLayout>
  );
}

Documentation Page

import { DevPlatformLayout } from "@/components/dev-platform/layouts/DevPlatformLayout";
import { ThreeColumnLayout } from "@/components/dev-platform/layouts/ThreeColumnLayout";
import { CodeBlock } from "@/components/dev-platform/ui/CodeBlock";
import { Callout } from "@/components/dev-platform/ui/Callout";

export default function DocsPage() {
  return (
    <DevPlatformLayout>
      <ThreeColumnLayout
        sidebar={<DocsSidebar />}
        aside={<TableOfContents />}
      >
        <article className="prose prose-invert max-w-none">
          <h1>Getting Started</h1>
          <p>Install the AeThex SDK...</p>
          
          <CodeBlock
            code="npm install @aethex/sdk"
            language="bash"
          />
          
          <Callout type="info">
            Make sure Node.js 18+ is installed.
          </Callout>
        </article>
      </ThreeColumnLayout>
    </DevPlatformLayout>
  );
}

Dashboard Page

import { DevPlatformLayout } from "@/components/dev-platform/layouts/DevPlatformLayout";
import { StatCard } from "@/components/dev-platform/ui/StatCard";
import { Activity, Key, Zap } from "lucide-react";

export default function DashboardPage() {
  return (
    <DevPlatformLayout>
      <div className="container py-10">
        <h1 className="text-4xl font-bold mb-8">Developer Dashboard</h1>
        
        <div className="grid gap-6 md:grid-cols-3 mb-8">
          <StatCard
            title="API Calls"
            value="1.2M"
            icon={Activity}
            trend={{ value: 12, isPositive: true }}
          />
          <StatCard
            title="API Keys"
            value="3"
            icon={Key}
          />
          <StatCard
            title="Rate Limit"
            value="89%"
            description="Remaining"
            icon={Zap}
          />
        </div>
      </div>
    </DevPlatformLayout>
  );
}

---

♿ Accessibility

Standards

• WCAG 2.1 AA compliance
• Keyboard navigation for all interactive elements
• Focus indicators visible
• Semantic HTML
• ARIA labels where needed

Keyboard Shortcuts

• Cmd/Ctrl + K: Open command palette
• Tab: Navigate forward
• Shift + Tab: Navigate backward
• Enter/Space: Activate buttons
• Esc: Close modals/dialogs

Focus Management

/* All interactive elements have visible focus */
focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2 focus:ring-offset-background

Screen Reader Support

• Alt text on all images
• Descriptive link text (no "click here")
• Form labels properly associated
• Status messages announced

---

📱 Responsive Design

Breakpoints

sm:  640px   /* Mobile landscape */
md:  768px   /* Tablet */
lg:  1024px  /* Desktop */
xl:  1280px  /* Large desktop */
2xl: 1536px  /* Extra large */

Mobile-First Approach

// Default: Mobile
<div className="text-sm">

// Desktop: Larger text
<div className="text-sm md:text-base lg:text-lg">

// Grid: 1 column mobile, 3 columns desktop
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">

---

🚀 Performance

Loading States

• Skeleton loaders for content
• Suspense boundaries for code splitting
• Progressive image loading

Optimization

• Lazy load routes
• Code split heavy components
• Minimize bundle size
• Use production builds

---

📚 Additional Resources

• Shadcn/ui Documentation: https://ui.shadcn.com/
• Tailwind CSS: https://tailwindcss.com/docs
• Radix UI: https://www.radix-ui.com/
• Lucide Icons: https://lucide.dev/

---

✅ Next Steps

1. Add More Components:

   • LanguageTabs (for code examples)
   • ApiKeyManager (dashboard)
   • UsageChart (analytics)
   • TemplateCard (templates)
   • Command Palette (global search)

2. Enhance Existing:

   • Add syntax highlighting to CodeBlock (Prism.js)
   • Implement full command palette
   • Add more comprehensive examples

3. Documentation:

   • Create Storybook for component showcase
   • Add more usage examples
   • Create component playground

---

Document Version: 1.0
Component Count: 9 core components
Status: Foundation Complete
Last Updated: January 7, 2026