Assembling Components

Assembling Components

Purpose

This skill transforms the outputs of AI Design Components skills into production-ready applications. It provides library-specific context for our token system, component patterns, and skill chain workflow - knowledge that generic assembly patterns cannot provide. The skill validates token integration, generates proper scaffolding, and wires components together correctly.

When to Use

Activate this skill when:

• Completing a skill chain workflow (theming → layout → dashboards → data-viz → feedback)
• Generating new project scaffolding for React/Vite, Next.js, FastAPI, Flask, or Rust/Axum
• Validating that all generated CSS uses design tokens (not hardcoded values)
• Creating barrel exports and wiring component imports correctly
• Assembling components from multiple skills into a unified application
• Debugging integration issues (missing entry points, broken imports, theme not switching)
• Preparing generated code for production deployment

Skill Chain Context

This skill understands the output of every AI Design Components skill:

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│ theming-         │────▶│ designing-       │────▶│ creating-        │
│ components       │     │ layouts          │     │ dashboards       │
└──────────────────┘     └──────────────────┘     └──────────────────┘
        │                        │                        │
        ▼                        ▼                        ▼
    tokens.css               Layout.tsx             Dashboard.tsx
    theme-provider.tsx       Header.tsx             KPICard.tsx
        │                        │                        │
        └────────────────────────┴────────────────────────┘
                                 │
                                 ▼
                    ┌──────────────────────┐
                    │ visualizing-data     │
                    │ providing-feedback   │
                    └──────────────────────┘
                                 │
                                 ▼
                         DonutChart.tsx
                         Toast.tsx, Spinner.tsx
                                 │
                                 ▼
                    ┌──────────────────────┐
                    │ ASSEMBLING-          │
                    │ COMPONENTS           │
                    │ (THIS SKILL)         │
                    └──────────────────────┘
                                 │
                                 ▼
                       WORKING COMPONENT SYSTEM

Expected Outputs by Skill

Token Validation

Run Validation Script (Token-Free Execution)

# Basic validation
python scripts/validate_tokens.py src/styles

# Strict mode with fix suggestions
python scripts/validate_tokens.py src --strict --fix-suggestions

# JSON output for CI/CD
python scripts/validate_tokens.py src --json

Our Token Naming Conventions

/* Colors - semantic naming */
--color-primary: #FA582D;          /* Brand primary */
--color-success: #00CC66;          /* Positive states */
--color-warning: #FFCB06;          /* Caution states */
--color-error: #C84727;            /* Error states */
--color-info: #00C0E8;             /* Informational */

--color-bg-primary: #FFFFFF;       /* Main background */
--color-bg-secondary: #F8FAFC;     /* Elevated surfaces */
--color-text-primary: #1E293B;     /* Body text */
--color-text-secondary: #64748B;   /* Muted text */

/* Spacing - 4px base unit */
--spacing-xs: 0.25rem;   /* 4px */
--spacing-sm: 0.5rem;    /* 8px */
--spacing-md: 1rem;      /* 16px */
--spacing-lg: 1.5rem;    /* 24px */
--spacing-xl: 2rem;      /* 32px */

/* Typography */
--font-size-xs: 0.75rem;   /* 12px */
--font-size-sm: 0.875rem;  /* 14px */
--font-size-base: 1rem;    /* 16px */
--font-size-lg: 1.125rem;  /* 18px */

/* Component sizes */
--icon-size-sm: 1rem;      /* 16px */
--icon-size-md: 1.5rem;    /* 24px */
--radius-sm: 4px;
--radius-md: 8px;
--shadow-sm: 0 1px 2px rgba(0,0,0,0.05);

Validation Rules

Framework Selection

React/TypeScript

Choose Vite + React when:

• Building single-page applications
• Lightweight, fast development builds
• Maximum control over configuration
• No server-side rendering needed

Choose Next.js 14/15 when:

• Need server-side rendering or static generation
• Building full-stack with API routes
• SEO is important
• Using React Server Components

Python

Choose FastAPI when:

• Building modern async APIs
• Need automatic OpenAPI documentation
• High performance is required
• Using Pydantic for validation

Choose Flask when:

• Simpler, more flexible setup
• Familiar with Flask ecosystem
• Template rendering (Jinja2)
• Smaller applications

Rust

Choose Axum when:

• Modern tower-based architecture
• Type-safe extractors
• Async-first design
• Growing ecosystem

Choose Actix Web when:

• Maximum performance required
• Actor model benefits your use case
• More mature ecosystem

Implementation Approach

1. Validate Token Integration

Before assembly, check all CSS uses tokens:

python scripts/validate_tokens.py <component-directory>

Fix any violations before proceeding.

2. Generate Project Scaffolding

React/Vite:

// src/main.tsx - Entry point
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ThemeProvider } from '@/context/theme-provider'
import App from './App'
import './styles/tokens.css'   // FIRST - token definitions
import './styles/globals.css'  // SECOND - global resets

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ThemeProvider>
      <App />
    </ThemeProvider>
  </StrictMode>,
)

index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{PROJECT_TITLE}}</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

3. Wire Components Together

Theme Provider:

// src/context/theme-provider.tsx
import { createContext, useContext, useEffect, useState } from 'react'

type Theme = 'light' | 'dark' | 'system'

const ThemeContext = createContext<{
  theme: Theme
  setTheme: (theme: Theme) => void
} | undefined>(undefined)

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>('system')

  useEffect(() => {
    const root = document.documentElement
    const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches
      ? 'dark' : 'light'
    root.setAttribute('data-theme', theme === 'system' ? systemTheme : theme)
    localStorage.setItem('theme', theme)
  }, [theme])

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

export const useTheme = () => {
  const context = useContext(ThemeContext)
  if (!context) throw new Error('useTheme must be used within ThemeProvider')
  return context
}

Barrel Exports:

// src/components/ui/index.ts
export { Button } from './button'
export { Card } from './card'

// src/components/features/dashboard/index.ts
export { KPICard } from './kpi-card'
export { DonutChart } from './donut-chart'
export { Dashboard } from './dashboard'

4. Configure Build System

vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["src"]
}

Cross-Skill Integration

Using Theming Components

// Import tokens first, components inherit token values
import './styles/tokens.css'

// Use ThemeProvider at root
<ThemeProvider>
  <App />
</ThemeProvider>

Using Dashboard Components

// Components from creating-dashboards skill
import { Dashboard, KPICard } from '@/components/features/dashboard'

// Wire with data
<Dashboard>
  <KPICard
    label="Total Threats"
    value={1234}
    severity="critical"
    trend={{ value: 15.3, direction: 'up' }}
  />
</Dashboard>

Using Data Visualization

// Charts from visualizing-data skill
import { DonutChart } from '@/components/charts'

// Charts use --chart-color-* tokens automatically
<DonutChart
  data={threatData}
  title="Threats by Severity"
/>

Using Feedback Components

// From providing-feedback skill
import { Toast, Spinner, EmptyState } from '@/components/feedback'

// Wire toast notifications
<ToastProvider>
  <App />
</ToastProvider>

// Use spinner for loading states
{isLoading ? <Spinner /> : <Dashboard />}

Integration Checklist

Before delivery, verify:

• [ ] Token file exists (tokens.css) with all 7 categories
• [ ] Token import order correct (tokens.css → globals.css → components)
• [ ] No hardcoded values (run validate_tokens.py)
• [ ] Theme toggle works (data-theme attribute switches)
• [ ] Reduced motion supported (@media (prefers-reduced-motion))
• [ ] Build completes without errors
• [ ] Types pass (TypeScript compiles)
• [ ] Imports resolve (no missing modules)
• [ ] Barrel exports exist for each component directory

Bundled Resources

Scripts (Token-Free Execution)

• scripts/validate_tokens.py - Validate CSS uses design tokens
• scripts/generate_scaffold.py - Generate project boilerplate
• scripts/check_imports.py - Validate import chains
• scripts/generate_exports.py - Create barrel export files

Run scripts directly without loading into context:

python scripts/validate_tokens.py demo/examples --fix-suggestions

References (Detailed Patterns)

• references/library-context.md - AI Design Components library awareness
• references/react-vite-template.md - Full Vite + React setup
• references/nextjs-template.md - Next.js 14/15 patterns
• references/python-fastapi-template.md - FastAPI project structure
• references/rust-axum-template.md - Rust/Axum project structure
• references/token-validation-rules.md - Complete validation rules

Examples (Complete Implementations)

• examples/react-dashboard/ - Full Vite + React dashboard
• examples/nextjs-dashboard/ - Next.js App Router dashboard
• examples/fastapi-dashboard/ - Python FastAPI dashboard
• examples/rust-axum-dashboard/ - Rust Axum dashboard

Assets (Templates)

• assets/templates/react/ - React project templates
• assets/templates/python/ - Python project templates
• assets/templates/rust/ - Rust project templates

Application Assembly Workflow

1. Validate Components: Run validate_tokens.py on all generated CSS 2. Choose Framework: React/Vite, Next.js, FastAPI, or Rust based on requirements 3. Generate Scaffolding: Create project structure and configuration 4. Wire Imports: Set up entry point, import chain, barrel exports 5. Add Providers: ThemeProvider, ToastProvider at root 6. Connect Components: Import and compose feature components 7. Configure Build: vite.config, tsconfig, package.json 8. Final Validation: Build, type-check, lint 9. Document: README with setup and usage instructions

For library-specific patterns and complete context, see references/library-context.md.

Python FastAPI Template

Starter template for Python backend applications using FastAPI.

Stack

• FastAPI (async web framework)
• SQLAlchemy 2.0 (ORM)
• Pydantic 2.0 (validation)
• PostgreSQL (database)
• Alembic (migrations)

Project Structure

my-fastapi-app/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI app instance
│   ├── config.py            # Settings and environment
│   ├── database.py          # Database connection
│   ├── dependencies.py      # Shared dependencies
│   ├── models/              # SQLAlchemy models
│   │   ├── __init__.py
│   │   └── user.py
│   ├── schemas/             # Pydantic schemas
│   │   ├── __init__.py
│   │   └── user.py
│   ├── routers/             # API routes
│   │   ├── __init__.py
│   │   ├── auth.py
│   │   └── users.py
│   └── services/            # Business logic
│       ├── __init__.py
│       └── user_service.py
├── alembic/                 # Database migrations
├── tests/
├── requirements.txt
├── .env.example
└── README.md

Quick Start

# 1. Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure environment
cp .env.example .env
# Edit .env with your database URL

# 4. Run migrations
alembic upgrade head

# 5. Start server
uvicorn app.main:app --reload

Access API docs: http://localhost:8000/docs

Use with Skill

This template is referenced by the assembling-components skill for rapidly scaffolding Python backend applications.

React + Vite Template

Modern React template with TypeScript, Vite, TanStack Query, and Tailwind CSS.

Stack

• React 18
• TypeScript
• Vite (build tool)
• TanStack Query (data fetching)
• React Router (routing)
• Tailwind CSS (styling)
• Shadcn/ui (components)

Project Structure

my-react-app/
├── src/
│   ├── main.tsx             # Entry point
│   ├── App.tsx              # Root component
│   ├── components/          # Reusable components
│   │   ├── ui/              # Shadcn/ui components
│   │   ├── layout/
│   │   │   ├── Header.tsx
│   │   │   ├── Sidebar.tsx
│   │   │   └── Layout.tsx
│   │   └── common/
│   ├── pages/               # Page components
│   │   ├── Home.tsx
│   │   ├── Dashboard.tsx
│   │   └── NotFound.tsx
│   ├── hooks/               # Custom hooks
│   │   ├── useAuth.ts
│   │   └── useApi.ts
│   ├── services/            # API clients
│   │   └── api.ts
│   ├── lib/                 # Utilities
│   │   └── utils.ts
│   ├── types/               # TypeScript types
│   │   └── index.ts
│   └── styles/
│       └── index.css
├── public/
├── index.html
├── vite.config.ts
├── tailwind.config.js
├── tsconfig.json
└── package.json

Quick Start

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with API URL

# 3. Start development server
npm run dev

Access app: http://localhost:5173

Features

• Hot Module Replacement (HMR)
• TypeScript strict mode
• ESLint + Prettier configured
• Path aliases (@/components)
• TanStack Query for server state
• React Router for navigation

Use with Skill

This template is referenced by the assembling-components skill for rapidly scaffolding React frontend applications.

Rust Axum Template

High-performance Rust backend template using Axum, SQLx, and PostgreSQL.

Stack

• Axum (web framework)
• SQLx (compile-time checked queries)
• PostgreSQL (database)
• Tower (middleware)
• Tokio (async runtime)
• Serde (serialization)

Project Structure

my-axum-app/
├── src/
│   ├── main.rs              # Entry point
│   ├── config.rs            # Configuration
│   ├── db.rs                # Database connection pool
│   ├── error.rs             # Error types
│   ├── models/              # Data models
│   │   ├── mod.rs
│   │   └── user.rs
│   ├── routes/              # API routes
│   │   ├── mod.rs
│   │   ├── auth.rs
│   │   └── users.rs
│   ├── handlers/            # Route handlers
│   │   ├── mod.rs
│   │   └── user_handlers.rs
│   ├── services/            # Business logic
│   │   ├── mod.rs
│   │   └── user_service.rs
│   └── middleware/          # Custom middleware
│       ├── mod.rs
│       └── auth.rs
├── migrations/              # SQLx migrations
├── tests/
├── Cargo.toml
├── .env.example
└── README.md

Quick Start

# 1. Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 2. Install sqlx-cli
cargo install sqlx-cli --no-default-features --features postgres

# 3. Configure environment
cp .env.example .env
# Edit .env with DATABASE_URL

# 4. Run migrations
sqlx database create
sqlx migrate run

# 5. Build and run
cargo run --release

Access API: http://localhost:3000

Features

• Compile-time SQL query validation
• Automatic JSON serialization
• Tower middleware (CORS, logging, compression)
• Graceful shutdown
• Connection pooling
• Zero-cost abstractions

Performance

• ~140,000 requests/second (hello world)
• <1ms p99 latency
• ~5MB memory footprint
• Compiles to native binary

Use with Skill

This template is referenced by the assembling-components skill for rapidly scaffolding Rust backend applications.

FastAPI Dashboard Backend Example

Complete FastAPI backend for dashboard applications with PostgreSQL, authentication, and real-time metrics.

Features

• User authentication (JWT)
• Dashboard metrics endpoints
• Real-time data streaming (SSE)
• PostgreSQL with SQLAlchemy 2.0
• CORS configuration
• Rate limiting
• OpenAPI documentation

Project Structure

fastapi-dashboard/
├── app/
│   ├── main.py              # FastAPI app
│   ├── auth.py              # JWT authentication
│   ├── database.py          # SQLAlchemy setup
│   ├── models.py            # Database models
│   ├── schemas.py           # Pydantic schemas
│   └── routers/
│       ├── dashboard.py     # Dashboard endpoints
│       ├── metrics.py       # Metrics streaming
│       └── users.py         # User management
├── requirements.txt
├── .env.example
└── README.md

Endpoints

POST   /auth/login          - User login
POST   /auth/refresh        - Refresh token
GET    /dashboard/metrics   - Get dashboard KPIs
GET    /dashboard/charts    - Get chart data
GET    /metrics/stream      - SSE real-time metrics
GET    /users/me            - Get current user

Quick Start

# Install
pip install -r requirements.txt

# Configure
cp .env.example .env

# Run migrations
alembic upgrade head

# Start server
uvicorn app.main:app --reload

Integration

This backend pairs with:

• Frontend: React dashboard (see examples/react-dashboard/)
• Database skill: databases-relational
• Auth skill: auth-security
• Real-time skill: realtime-sync (SSE)

API Documentation

Access auto-generated docs at http://localhost:8000/docs

Next.js Dashboard Example

Full-stack Next.js 14 dashboard with App Router, Server Components, and real-time updates.

Features

• Next.js 14 App Router
• Server Components + Client Components
• Authentication (NextAuth.js)
• PostgreSQL with Prisma
• Real-time metrics (SSE)
• TanStack Table
• Recharts visualization
• Tailwind CSS + Shadcn/ui
• TypeScript strict mode

Project Structure

nextjs-dashboard/
├── app/
│   ├── layout.tsx           # Root layout
│   ├── page.tsx             # Home page
│   ├── dashboard/
│   │   ├── layout.tsx       # Dashboard layout
│   │   ├── page.tsx         # Dashboard home
│   │   ├── metrics/
│   │   └── analytics/
│   ├── api/
│   │   ├── auth/[...nextauth]/route.ts
│   │   ├── dashboard/
│   │   │   └── metrics/route.ts
│   │   └── stream/
│   │       └── route.ts     # SSE endpoint
│   └── (auth)/
│       ├── login/page.tsx
│       └── register/page.tsx
├── components/
│   ├── ui/                  # Shadcn/ui components
│   ├── dashboard/
│   │   ├── KPICard.tsx
│   │   ├── MetricsChart.tsx
│   │   └── DataTable.tsx
│   └── layout/
│       ├── Header.tsx
│       └── Sidebar.tsx
├── lib/
│   ├── db.ts                # Prisma client
│   ├── auth.ts              # NextAuth config
│   └── utils.ts
├── prisma/
│   └── schema.prisma
├── next.config.js
└── package.json

Quick Start

# Install
npm install

# Setup database
cp .env.example .env
npx prisma migrate dev

# Start dev server
npm run dev

Access: http://localhost:3000

Key Features

Server Components (Default)

// app/dashboard/page.tsx (Server Component)
import { getMetrics } from '@/lib/api';

export default async function DashboardPage() {
  const metrics = await getMetrics();  // Fetched on server
  return <MetricsDisplay metrics={metrics} />;
}

Client Components (Interactive)

'use client';

import { useEffect, useState } from 'react';

export function RealtimeMetrics() {
  const [metrics, setMetrics] = useState(null);

  useEffect(() => {
    const es = new EventSource('/api/stream');
    es.onmessage = (e) => setMetrics(JSON.parse(e.data));
    return () => es.close();
  }, []);

  return <MetricsChart data={metrics} />;
}

Integration

Combines skills:

• creating-dashboards (KPIs, charts)
• building-tables (data grids)
• visualizing-data (charts)
• auth-security (NextAuth)
• databases-relational (Prisma)
• realtime-sync (SSE streaming)

React SPA Dashboard Example

Single Page Application dashboard using React, Vite, and TanStack ecosystem.

Stack

• React 18
• TypeScript
• Vite
• TanStack Query (data fetching)
• TanStack Table (data grid)
• React Router (routing)
• Recharts (visualization)
• Tailwind CSS + Shadcn/ui
• Zustand (state management)

Project Structure

react-dashboard/
├── src/
│   ├── main.tsx
│   ├── App.tsx
│   ├── pages/
│   │   ├── Dashboard.tsx
│   │   ├── Analytics.tsx
│   │   ├── Reports.tsx
│   │   └── Settings.tsx
│   ├── components/
│   │   ├── ui/              # Shadcn/ui
│   │   ├── dashboard/
│   │   │   ├── KPICard.tsx
│   │   │   ├── MetricsChart.tsx
│   │   │   └── DataTable.tsx
│   │   └── layout/
│   │       ├── Header.tsx
│   │       ├── Sidebar.tsx
│   │       └── Layout.tsx
│   ├── hooks/
│   │   ├── useMetrics.ts
│   │   ├── useAuth.ts
│   │   └── useSSE.ts
│   ├── services/
│   │   └── api.ts           # API client
│   ├── stores/
│   │   └── authStore.ts     # Zustand store
│   └── lib/
│       └── utils.ts
├── vite.config.ts
└── package.json

Quick Start

# Install
npm install

# Configure
cp .env.example .env
# Set VITE_API_URL

# Start dev server
npm run dev

Data Fetching Pattern

import { useQuery } from '@tanstack/react-query';

function DashboardMetrics() {
  const { data, isLoading } = useQuery({
    queryKey: ['metrics'],
    queryFn: () => fetch('/api/metrics').then(r => r.json()),
    refetchInterval: 30000,  // Refresh every 30s
  });

  if (isLoading) return <Skeleton />;
  return <MetricsDisplay data={data} />;
}

Real-Time Updates

import { useSSE } from '@/hooks/useSSE';

function RealtimeChart() {
  const { data } = useSSE('/api/metrics/stream');
  return <LineChart data={data} />;
}

Integration

Backend options:

• FastAPI (see examples/fastapi-dashboard/)
• Rust Axum (see examples/rust-axum-dashboard/)
• Node.js Hono/Express

Assembly Examples

This directory contains example implementations demonstrating the assembling-components skill.

Available Examples

Existing Dashboard Example

The Palo Alto Security Dashboard in demo/examples/palo-alto-security-dashboard/ serves as a reference implementation showing:

• Complete token system integration
• Theme toggle with dark mode support
• Component composition (KPICard, DonutChart, Toast, Spinner)
• Proper CSS token usage

Generating New Examples

Use the scaffolding script to create new project examples:

# React + Vite
python scripts/generate_scaffold.py react-dashboard react-vite ./examples

# Next.js
python scripts/generate_scaffold.py nextjs-dashboard nextjs ./examples

# Python FastAPI
python scripts/generate_scaffold.py fastapi-dashboard python-fastapi ./examples

# Rust Axum
python scripts/generate_scaffold.py rust-dashboard rust-axum ./examples

Validation

After creating or modifying examples, validate them:

# Validate CSS tokens
python scripts/validate_tokens.py examples/react-dashboard/src

# Check import chains
python scripts/check_imports.py examples/react-dashboard/src

# Generate barrel exports
python scripts/generate_exports.py examples/react-dashboard/src/components

Example Structure

Each example should follow this structure:

example-name/
├── src/
│   ├── main.tsx              # Entry point
│   ├── App.tsx               # Root component
│   ├── styles/
│   │   ├── tokens.css        # Design tokens (imported FIRST)
│   │   └── globals.css       # Global styles
│   ├── context/
│   │   └── theme-provider.tsx
│   ├── components/
│   │   ├── ui/               # Shared UI components
│   │   │   └── index.ts      # Barrel export
│   │   ├── layout/           # Layout components
│   │   │   └── index.ts
│   │   └── features/         # Feature components
│   │       └── dashboard/
│   │           └── index.ts
│   └── lib/
│       └── utils.ts
├── package.json
├── vite.config.ts
└── tsconfig.json

Integration Checklist

Before considering an example complete:

• [ ] tokens.css exists and is imported first
• [ ] All CSS uses token variables (no hardcoded values)
• [ ] ThemeProvider wraps the app
• [ ] Theme toggle works (light/dark)
• [ ] Barrel exports exist for component directories
• [ ] Build completes without errors
• [ ] npm run validate:tokens passes

Rust Axum Dashboard Backend

High-performance Rust backend for dashboard applications using Axum and PostgreSQL.

Stack

• Axum (web framework)
• SQLx (compile-time checked SQL)
• PostgreSQL
• Tower (middleware)
• Tokio (async runtime)
• JWT authentication
• SSE streaming

Project Structure

rust-axum-dashboard/
├── src/
│   ├── main.rs
│   ├── config.rs
│   ├── db.rs                # Database pool
│   ├── error.rs             # Error handling
│   ├── models/
│   │   ├── mod.rs
│   │   └── user.rs
│   ├── routes/
│   │   ├── mod.rs
│   │   ├── auth.rs
│   │   ├── dashboard.rs
│   │   └── metrics.rs
│   ├── handlers/
│   │   └── dashboard_handlers.rs
│   ├── middleware/
│   │   └── auth.rs
│   └── services/
│       └── metrics_service.rs
├── migrations/
├── Cargo.toml
└── .env.example

Quick Start

# Install SQLx CLI
cargo install sqlx-cli

# Configure
cp .env.example .env

# Setup database
sqlx database create
sqlx migrate run

# Run (development)
cargo run

# Run (production)
cargo build --release
./target/release/axum-dashboard

Performance

• 140,000+ requests/second
• <1ms p99 latency
• 5-10MB memory usage
• Sub-second startup time

API Endpoints

POST /auth/login
GET  /dashboard/metrics
GET  /dashboard/kpis
GET  /stream/metrics       (SSE)

Integration

Frontend options:

• React (see examples/react-dashboard/)
• Next.js (see examples/nextjs-dashboard/)

Skills used:

• databases-relational (SQLx)
• auth-security (JWT)
• realtime-sync (SSE)

AI Design Components Library Context

Critical Reference: This document provides the assembling-components skill with deep awareness of the AI Design Components library structure, enabling intelligent assembly that generic LLM knowledge cannot provide.

Table of Contents

• Why This Context Matters
• Skill Chain Architecture
• Standard Skill Chain Flow
• Skill Outputs Reference
• Token System Reference
• Token Naming Conventions
• Component Integration Patterns
• Import Chain (Critical Order)
• Component Directory Structure
• State Integration Patterns
• Skill-Specific Assembly Rules
• After theming-components Skill
• After designing-layouts Skill
• After creating-dashboards Skill
• After visualizing-data Skill
• After providing-feedback Skill
• Validation Checklist (Library-Specific)
• Token Compliance
• Theme System
• Component Integration
• Accessibility
• Common Integration Patterns
• Theme Toggle Button
• KPI Card with Severity
• Toast Notifications
• Version Compatibility
• Summary

Why This Context Matters

LLMs are already proficient at general application assembly. This skill's unique value comes from:

1. Library-Specific Knowledge - Understanding our exact component outputs 2. Token System Mastery - Knowing our precise naming conventions 3. Skill Chain Awareness - Understanding what each skill produces 4. Integration Intelligence - Knowing how our components connect

---

Skill Chain Architecture

Standard Skill Chain Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  theming-   │────▶│  designing- │────▶│  creating-  │
│  components │     │  layouts    │     │  dashboards │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
   tokens.css         Layout.tsx         Dashboard.tsx
   globals.css        Header.tsx         KPICard.tsx
                      Sidebar.tsx
       │                   │                   │
       └───────────────────┴───────────────────┘
                           │
                           ▼
               ┌───────────────────────┐
               │  visualizing-data     │
               │  (data-viz skill)     │
               └───────────────────────┘
                           │
                           ▼
                   DonutChart.tsx
                   BarChart.tsx
                   LineChart.tsx
                           │
                           ▼
               ┌───────────────────────┐
               │  providing-feedback   │
               └───────────────────────┘
                           │
                           ▼
                    Toast.tsx
                    Spinner.tsx
                    EmptyState.tsx
                           │
                           ▼
               ┌───────────────────────┐
               │ ASSEMBLING-COMPONENTS │
               │    (THIS SKILL)       │
               └───────────────────────┘
                           │
                           ▼
                 WORKING COMPONENT SYSTEM

Skill Outputs Reference

---

Token System Reference

Token Naming Conventions

Our library uses a semantic token architecture with these categories:

Color Tokens

/* Brand colors (source of truth) */
--color-cyber-orange: #FA582D;
--color-prisma-blue: #00C0E8;
--color-cortex-green: #00CC66;
--color-strata-yellow: #FFCB06;
--color-unit42-red: #C84727;

/* Semantic mappings */
--color-primary: var(--color-cyber-orange);
--color-success: var(--color-cortex-green);
--color-warning: var(--color-strata-yellow);
--color-error: var(--color-unit42-red);
--color-info: var(--color-prisma-blue);

/* Surface colors */
--color-bg-primary: #FFFFFF;      /* Main background */
--color-bg-secondary: #F8FAFC;    /* Elevated surfaces */
--color-bg-tertiary: #F1F5F9;     /* Subtle backgrounds */
--color-bg-elevated: #FFFFFF;     /* Cards, modals */

/* Text colors */
--color-text-primary: #1E293B;    /* Headings, body */
--color-text-secondary: #64748B;  /* Descriptions */
--color-text-tertiary: #94A3B8;   /* Muted text */
--color-text-inverse: #FFFFFF;    /* On dark backgrounds */

Spacing Tokens

/* Base scale (4px unit) */
--space-1: 0.25rem;   /* 4px - xs */
--space-2: 0.5rem;    /* 8px - sm */
--space-3: 0.75rem;   /* 12px */
--space-4: 1rem;      /* 16px - md */
--space-6: 1.5rem;    /* 24px - lg */
--space-8: 2rem;      /* 32px - xl */
--space-12: 3rem;     /* 48px - 2xl */

/* Semantic aliases */
--spacing-xs: var(--space-1);
--spacing-sm: var(--space-2);
--spacing-md: var(--space-4);
--spacing-lg: var(--space-6);
--spacing-xl: var(--space-8);
--spacing-2xl: var(--space-12);

Component Size Tokens

/* Icons */
--icon-size-sm: 1rem;      /* 16px */
--icon-size-md: 1.5rem;    /* 24px */
--icon-size-lg: 2rem;      /* 32px */
--icon-size-xl: 3rem;      /* 48px */

/* Buttons */
--button-height-sm: 2rem;
--button-height-md: 2.5rem;
--button-height-lg: 3rem;

/* Cards/Charts */
--min-height-card: 140px;
--min-height-chart: 200px;

---

Component Integration Patterns

Import Chain (Critical Order)

// src/main.tsx - CORRECT ORDER
import './styles/tokens.css'      // 1. Tokens first!
import './styles/globals.css'     // 2. Global resets
import './styles/components.css'  // 3. Component styles

import { ThemeProvider } from '@/context/theme-provider'
import App from './App'

Component Directory Structure

src/components/
├── ui/                     # From theming-components, forms skills
│   ├── button.tsx
│   ├── input.tsx
│   ├── card.tsx
│   └── index.ts           # Barrel export
├── layout/                 # From designing-layouts skill
│   ├── header.tsx
│   ├── sidebar.tsx
│   ├── footer.tsx
│   └── index.ts
├── charts/                 # From visualizing-data skill
│   ├── donut-chart.tsx
│   ├── bar-chart.tsx
│   ├── line-chart.tsx
│   └── index.ts
├── feedback/               # From providing-feedback skill
│   ├── toast.tsx
│   ├── spinner.tsx
│   ├── empty-state.tsx
│   └── index.ts
└── features/               # Domain-specific compositions
    └── dashboard/
        ├── kpi-card.tsx
        ├── dashboard.tsx
        └── index.ts

State Integration Patterns

// Theme context - always at root
<ThemeProvider>
  <App />
</ThemeProvider>

// Toast context - for notifications
<ToastProvider>
  <ThemeProvider>
    <App />
  </ThemeProvider>
</ToastProvider>

---

Skill-Specific Assembly Rules

After theming-components Skill

Expected outputs:

• tokens.css with complete token definitions
• Dark theme via [data-theme="dark"] selector
• Reduced motion support via @media (prefers-reduced-motion)

Assembly actions: 1. Verify tokens.css has all 7 categories (colors, spacing, typography, borders, shadows, motion, z-index) 2. Create theme-provider.tsx if not present 3. Ensure index.html has no data-theme attribute (let JS handle it)

After designing-layouts Skill

Expected outputs:

• Layout components (Header, Sidebar, Footer)
• CSS Grid/Flexbox patterns
• Responsive breakpoints

Assembly actions: 1. Wire layout components into App.tsx 2. Verify layout CSS uses spacing tokens (not px values) 3. Check responsive classes use correct breakpoints

After creating-dashboards Skill

Expected outputs:

• Dashboard.tsx with grid layout
• KPI cards with trend indicators
• Section organization

Assembly actions: 1. Import chart components from visualizing-data 2. Wire data fetching/state management 3. Ensure loading states use Spinner from feedback

After visualizing-data Skill

Expected outputs:

• Chart components (Donut, Bar, Line, etc.)
• Legend components
• Accessible chart markup

Assembly actions: 1. Verify chart colors use --chart-color-* tokens 2. Check legends use correct typography tokens 3. Ensure empty states are handled

After providing-feedback Skill

Expected outputs:

• Toast/notification system
• Loading spinners
• Empty states
• Error boundaries

Assembly actions: 1. Create ToastProvider context 2. Wire toast system to API error handlers 3. Add loading spinners to async operations

---

Validation Checklist (Library-Specific)

Token Compliance

• [ ] All colors use --color-* tokens (not hex/rgb)
• [ ] All spacing uses --spacing-* or --space-* tokens
• [ ] All typography uses --font-size-*, --font-weight-* tokens
• [ ] All radii use --radius-* tokens
• [ ] All shadows use --shadow-* tokens
• [ ] All transitions use --transition-* or --duration-* tokens
• [ ] All z-indices use --z-* tokens

Theme System

• [ ] Theme toggle updates data-theme attribute on <html>
• [ ] Dark theme has all required color overrides
• [ ] System preference detection works
• [ ] Theme persists in localStorage

Component Integration

• [ ] All component CSS imports tokens.css (or inherits)
• [ ] Barrel exports exist for each component directory
• [ ] No circular imports
• [ ] TypeScript types are exported

Accessibility

• [ ] prefers-reduced-motion disables animations
• [ ] Focus states use --color-border-focus or --shadow-focus
• [ ] Color contrast meets WCAG 2.1 AA
• [ ] Interactive elements have focus-visible styles

---

Common Integration Patterns

Theme Toggle Button

// Uses our token system
function ThemeToggle() {
  const { theme, setTheme } = useTheme()

  return (
    <button
      className="theme-toggle"
      onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
      aria-label={`Switch to ${theme === 'dark' ? 'light' : 'dark'} mode`}
    >
      {theme === 'dark' ? '☀️' : '🌙'}
    </button>
  )
}

.theme-toggle {
  width: var(--button-height-md);
  height: var(--button-height-md);
  background: var(--color-bg-tertiary);
  border: var(--border-width-thin) solid var(--color-border-primary);
  border-radius: var(--radius-md);
  cursor: pointer;
  transition: var(--transition-fast);
}

.theme-toggle:hover {
  background: var(--color-bg-secondary);
}

KPI Card with Severity

interface KPICardProps {
  severity: 'critical' | 'high' | 'medium' | 'low' | 'info'
  // ...
}

function KPICard({ severity, ...props }: KPICardProps) {
  return (
    <div className={`kpi-card kpi-card--${severity}`}>
      {/* Uses severity-specific tokens */}
    </div>
  )
}

Toast Notifications

// Toast types map to our semantic colors
type ToastType = 'success' | 'error' | 'warning' | 'info'

function Toast({ type, message }: { type: ToastType; message: string }) {
  return (
    <div className={`toast toast--${type}`}>
      <div className="toast__icon">{icons[type]}</div>
      <div className="toast__content">{message}</div>
    </div>
  )
}

---

Version Compatibility

---

Summary

This skill is not about generic app assembly - it's about understanding our specific design library's:

1. 14 component skills and what each produces 2. Token system with precise naming conventions 3. Skill chain workflow and expected outputs at each step 4. Integration patterns unique to our library

The validation scripts and assembly rules encode this library-specific knowledge, ensuring consistent, token-compliant applications regardless of the target ecosystem.

Next.js 14/15 Template

Complete scaffolding template for full-stack applications using Next.js App Router with TypeScript.

Table of Contents

• Project Structure
• Core Files
• package.json
• next.config.mjs
• tsconfig.json
• src/app/layout.tsx
• src/app/globals.css
• src/app/page.tsx
• src/context/theme-provider.tsx
• src/app/api/health/route.ts
• Server Components vs Client Components
• When to use Server Components (default)
• When to use Client Components
• Commands
• Integration Checklist

Project Structure

project-name/
├── package.json
├── next.config.mjs
├── tsconfig.json
├── tailwind.config.ts         # Optional: if using Tailwind
├── postcss.config.mjs
├── .env.local
├── public/
│   ├── favicon.ico
│   └── images/
└── src/
    ├── app/
    │   ├── layout.tsx         # Root layout with providers
    │   ├── page.tsx           # Home page
    │   ├── globals.css        # Global styles + token imports
    │   ├── dashboard/
    │   │   └── page.tsx
    │   └── api/
    │       └── health/
    │           └── route.ts
    ├── components/
    │   ├── ui/
    │   │   ├── button.tsx
    │   │   ├── card.tsx
    │   │   └── index.ts
    │   ├── layout/
    │   │   ├── header.tsx
    │   │   ├── sidebar.tsx
    │   │   └── index.ts
    │   ├── charts/
    │   │   ├── donut-chart.tsx
    │   │   └── index.ts
    │   ├── feedback/
    │   │   ├── toast.tsx
    │   │   ├── spinner.tsx
    │   │   └── index.ts
    │   └── features/
    │       └── dashboard/
    │           ├── kpi-card.tsx
    │           ├── dashboard.tsx
    │           └── index.ts
    ├── lib/
    │   └── utils.ts
    ├── hooks/
    │   └── use-theme.ts
    ├── context/
    │   └── theme-provider.tsx
    ├── styles/
    │   └── tokens.css         # Design tokens
    └── types/
        └── index.ts

Core Files

package.json

{
  "name": "{{PROJECT_NAME}}",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "validate:tokens": "python scripts/validate_tokens.py src"
  },
  "dependencies": {
    "next": "^14.2.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "@types/react": "^18.3.0",
    "@types/react-dom": "^18.3.0",
    "typescript": "^5.4.0"
  }
}

next.config.mjs

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
  // Enable experimental features if needed
  // experimental: {
  //   serverActions: true,
  // },
}

export default nextConfig

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

src/app/layout.tsx

import type { Metadata } from 'next'
import { ThemeProvider } from '@/context/theme-provider'

// CRITICAL: Import tokens first
import '@/styles/tokens.css'
import './globals.css'

export const metadata: Metadata = {
  title: '{{PROJECT_TITLE}}',
  description: '{{PROJECT_DESCRIPTION}}',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="data-theme"
          defaultTheme="system"
          enableSystem
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

src/app/globals.css

/*
 * Global styles - tokens.css is imported in layout.tsx before this
 * All styles here should use CSS variables from tokens.css
 */

*,
*::before,
*::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

html {
  font-family: var(--font-sans);
  font-size: var(--font-size-base);
  line-height: var(--line-height-normal);
  color: var(--color-text-primary);
  background: var(--color-bg-primary);
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

body {
  min-height: 100vh;
}

/* Focus states for accessibility */
:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

/* Reduced motion support */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

src/app/page.tsx

import { Header, Sidebar } from '@/components/layout'
import { Dashboard } from '@/components/features/dashboard'

export default function Home() {
  return (
    <div className="app">
      <Header />
      <div className="app__body">
        <Sidebar />
        <main className="app__main">
          <Dashboard />
        </main>
      </div>
    </div>
  )
}

src/context/theme-provider.tsx

'use client'

import { createContext, useContext, useEffect, useState, ReactNode } from 'react'

type Theme = 'light' | 'dark' | 'system'

interface ThemeContextType {
  theme: Theme
  setTheme: (theme: Theme) => void
}

const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

interface ThemeProviderProps {
  children: ReactNode
  attribute?: string
  defaultTheme?: Theme
  enableSystem?: boolean
}

export function ThemeProvider({
  children,
  attribute = 'data-theme',
  defaultTheme = 'system',
  enableSystem = true,
}: ThemeProviderProps) {
  const [theme, setTheme] = useState<Theme>(defaultTheme)
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setMounted(true)
    const stored = localStorage.getItem('theme') as Theme | null
    if (stored) {
      setTheme(stored)
    }
  }, [])

  useEffect(() => {
    if (!mounted) return

    const root = window.document.documentElement

    if (theme === 'system' && enableSystem) {
      const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches
        ? 'dark'
        : 'light'
      root.setAttribute(attribute, systemTheme)
    } else {
      root.setAttribute(attribute, theme)
    }

    localStorage.setItem('theme', theme)
  }, [theme, mounted, attribute, enableSystem])

  // Prevent flash of incorrect theme
  if (!mounted) {
    return null
  }

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

export function useTheme() {
  const context = useContext(ThemeContext)
  if (!context) {
    throw new Error('useTheme must be used within ThemeProvider')
  }
  return context
}

src/app/api/health/route.ts

import { NextResponse } from 'next/server'

export async function GET() {
  return NextResponse.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
  })
}

Server Components vs Client Components

When to use Server Components (default)

• Fetching data from APIs
• Accessing backend resources directly
• Keeping sensitive information on server
• Large dependencies that should stay on server

// app/dashboard/page.tsx (Server Component)
async function getData() {
  const res = await fetch('https://api.example.com/data')
  return res.json()
}

export default async function DashboardPage() {
  const data = await getData()
  return <Dashboard data={data} />
}

When to use Client Components

• Interactivity (onClick, onChange, etc.)
• Browser APIs (localStorage, window, etc.)
• React hooks (useState, useEffect, useContext)
• Custom hooks that use state

'use client'

// components/ui/button.tsx
import { useState } from 'react'

export function Button({ children, onClick }) {
  const [isLoading, setIsLoading] = useState(false)
  // ...
}

Commands

# Install dependencies
npm install

# Start development server
npm run dev

# Validate CSS tokens
npm run validate:tokens

# Production build
npm run build

# Start production server
npm run start

Integration Checklist

• [ ] tokens.css imported in layout.tsx before globals.css
• [ ] ThemeProvider wraps entire app with 'use client'
• [ ] suppressHydrationWarning on html tag
• [ ] All CSS uses token variables
• [ ] Barrel exports exist for component directories
• [ ] Path aliases configured (@/)
• [ ] Server vs Client components properly separated
• [ ] Build completes without errors

Python FastAPI Template

Complete scaffolding template for modern async APIs using FastAPI with Pydantic validation.

Table of Contents

• Project Structure
• Core Files
• pyproject.toml
• requirements.txt
• src/project_name/main.py
• src/project_name/config.py
• src/project_name/api/routes/health.py
• src/project_name/api/routes/dashboard.py
• src/project_name/templates/base.html
• src/project_name/templates/dashboard.html
• Dockerfile
• docker-compose.yml
• Commands
• Integration Checklist

Project Structure

project-name/
├── pyproject.toml             # Modern Python packaging
├── requirements.txt           # Production dependencies
├── requirements-dev.txt       # Development dependencies
├── .env                       # Environment variables
├── .env.example              # Example environment file
├── Dockerfile
├── docker-compose.yml
├── src/
│   └── project_name/          # Main package
│       ├── __init__.py
│       ├── main.py            # Application entry point
│       ├── config.py          # Configuration management
│       ├── api/               # API routes
│       │   ├── __init__.py
│       │   ├── dependencies.py
│       │   └── routes/
│       │       ├── __init__.py
│       │       ├── dashboard.py
│       │       └── health.py
│       ├── core/              # Core business logic
│       │   ├── __init__.py
│       │   └── security.py
│       ├── models/            # Data models
│       │   ├── __init__.py
│       │   ├── schemas.py     # Pydantic schemas
│       │   └── database.py    # SQLAlchemy models
│       ├── services/          # Business logic services
│       │   ├── __init__.py
│       │   └── dashboard_service.py
│       ├── static/            # Static files (CSS, JS)
│       │   ├── css/
│       │   │   └── tokens.css
│       │   └── js/
│       └── templates/         # Jinja2 templates
│           ├── base.html
│           └── dashboard.html
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   └── test_dashboard.py
└── scripts/
    └── validate_tokens.py

Core Files

pyproject.toml

[project]
name = "{{PROJECT_NAME}}"
version = "1.0.0"
description = "{{PROJECT_DESCRIPTION}}"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.109.0",
    "uvicorn[standard]>=0.27.0",
    "pydantic>=2.5.0",
    "pydantic-settings>=2.1.0",
    "python-dotenv>=1.0.0",
    "jinja2>=3.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-asyncio>=0.23.0",
    "httpx>=0.26.0",
    "ruff>=0.1.0",
    "mypy>=1.8.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/project_name"]

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.mypy]
python_version = "3.11"
strict = true

requirements.txt

fastapi>=0.109.0
uvicorn[standard]>=0.27.0
pydantic>=2.5.0
pydantic-settings>=2.1.0
python-dotenv>=1.0.0
jinja2>=3.1.0

src/project_name/main.py

"""FastAPI application entry point."""

from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates

from .api.routes import dashboard, health
from .config import settings


@asynccontextmanager
async def lifespan(app: FastAPI):
    """Application lifespan events."""
    # Startup
    print(f"Starting {settings.app_name}...")
    yield
    # Shutdown
    print("Shutting down...")


def create_app() -> FastAPI:
    """Create and configure the FastAPI application."""
    app = FastAPI(
        title=settings.app_name,
        version=settings.version,
        lifespan=lifespan,
    )

    # Mount static files
    app.mount("/static", StaticFiles(directory="src/project_name/static"), name="static")

    # Include routers
    app.include_router(health.router, prefix="/api", tags=["health"])
    app.include_router(dashboard.router, prefix="/api", tags=["dashboard"])

    return app


app = create_app()


if __name__ == "__main__":
    import uvicorn
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

src/project_name/config.py

"""Application configuration using Pydantic Settings."""

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    """Application settings."""

    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
    )

    # Application
    app_name: str = "{{PROJECT_NAME}}"
    version: str = "1.0.0"
    debug: bool = False

    # Server
    host: str = "0.0.0.0"
    port: int = 8000

    # Database (if needed)
    # database_url: str = "sqlite:///./app.db"


settings = Settings()

src/project_name/api/routes/health.py

"""Health check routes."""

from datetime import datetime
from fastapi import APIRouter
from pydantic import BaseModel


router = APIRouter()


class HealthResponse(BaseModel):
    """Health check response model."""

    status: str
    timestamp: datetime
    version: str


@router.get("/health", response_model=HealthResponse)
async def health_check() -> HealthResponse:
    """Check API health status."""
    from ...config import settings

    return HealthResponse(
        status="ok",
        timestamp=datetime.now(),
        version=settings.version,
    )

src/project_name/api/routes/dashboard.py

"""Dashboard routes."""

from fastapi import APIRouter, Request
from fastapi.templating import Jinja2Templates
from pydantic import BaseModel


router = APIRouter()
templates = Jinja2Templates(directory="src/project_name/templates")


class KPIData(BaseModel):
    """KPI data model."""

    label: str
    value: int
    trend: float
    trend_direction: str


class DashboardData(BaseModel):
    """Dashboard data model."""

    kpis: list[KPIData]


@router.get("/dashboard")
async def get_dashboard(request: Request):
    """Render dashboard page."""
    return templates.TemplateResponse(
        "dashboard.html",
        {
            "request": request,
            "theme": "light",
            "title": "Dashboard",
        }
    )


@router.get("/dashboard/data", response_model=DashboardData)
async def get_dashboard_data() -> DashboardData:
    """Get dashboard data as JSON."""
    return DashboardData(
        kpis=[
            KPIData(label="Total Threats", value=1234, trend=15.3, trend_direction="up"),
            KPIData(label="Blocked Attacks", value=892, trend=8.2, trend_direction="up"),
            KPIData(label="Active Alerts", value=23, trend=-5.1, trend_direction="down"),
        ]
    )

src/project_name/templates/base.html

<!DOCTYPE html>
<html lang="en" data-theme="{{ theme | default('light') }}">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ title }} - {{PROJECT_NAME}}</title>

  <!-- Design tokens FIRST -->
  <link rel="stylesheet" href="{{ url_for('static', path='css/tokens.css') }}">
  <!-- Component styles -->
  <link rel="stylesheet" href="{{ url_for('static', path='css/dashboard.css') }}">

  <script>
    // Theme toggle
    (function() {
      const theme = localStorage.getItem('theme') || 'light';
      document.documentElement.setAttribute('data-theme', theme);
    })();
  </script>
</head>
<body>
  {% block content %}{% endblock %}

  <script>
    // Theme toggle button
    function toggleTheme() {
      const html = document.documentElement;
      const current = html.getAttribute('data-theme');
      const next = current === 'dark' ? 'light' : 'dark';
      html.setAttribute('data-theme', next);
      localStorage.setItem('theme', next);
    }
  </script>
</body>
</html>

src/project_name/templates/dashboard.html

{% extends "base.html" %}

{% block content %}
<div class="dashboard">
  <header class="dashboard__header">
    <h1>Dashboard</h1>
    <button onclick="toggleTheme()" class="theme-toggle">
      Toggle Theme
    </button>
  </header>

  <main class="dashboard__content">
    <section class="kpi-grid" id="kpi-container">
      <!-- KPI cards loaded via JavaScript -->
    </section>
  </main>
</div>

<script>
  // Fetch and render KPI data
  async function loadDashboard() {
    const response = await fetch('/api/dashboard/data');
    const data = await response.json();

    const container = document.getElementById('kpi-container');
    container.innerHTML = data.kpis.map(kpi => `
      <div class="kpi-card">
        <h3 class="kpi-card__label">${kpi.label}</h3>
        <div class="kpi-card__value">${kpi.value.toLocaleString()}</div>
        <div class="kpi-card__trend trend--${kpi.trend_direction === 'up' ? 'positive' : 'negative'}">
          ${kpi.trend_direction === 'up' ? '↑' : '↓'} ${Math.abs(kpi.trend)}%
        </div>
      </div>
    `).join('');
  }

  loadDashboard();
</script>
{% endblock %}

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY src/ ./src/

# Run application
CMD ["uvicorn", "src.project_name.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml

version: '3.8'

services:
  app:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./src:/app/src
    environment:
      - DEBUG=true
    command: uvicorn src.project_name.main:app --host 0.0.0.0 --port 8000 --reload

Commands

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -e ".[dev]"

# Start development server
uvicorn src.project_name.main:app --reload

# Validate CSS tokens
python scripts/validate_tokens.py src/project_name/static

# Run tests
pytest

# Type checking
mypy src/

# Linting
ruff check src/

Integration Checklist

• [ ] tokens.css exists in static/css/
• [ ] Templates load tokens.css before other styles
• [ ] Theme toggle updates data-theme attribute
• [ ] Pydantic models validate all API data
• [ ] Configuration uses pydantic-settings
• [ ] Tests cover critical endpoints
• [ ] Dockerfile builds successfully

React + Vite Template

Complete scaffolding template for single-page applications using Vite and React with TypeScript.

Table of Contents

• Project Structure
• Core Files
• index.html
• package.json
• vite.config.ts
• tsconfig.json
• tsconfig.node.json
• src/main.tsx
• src/App.tsx
• src/context/theme-provider.tsx
• src/lib/utils.ts
• Barrel Export Pattern
• Commands
• Integration Checklist

Project Structure

project-name/
├── index.html                 # Entry point
├── package.json               # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
├── tsconfig.node.json         # Node-specific TypeScript config
├── vite.config.ts             # Vite configuration
├── public/
│   └── favicon.svg
└── src/
    ├── main.tsx               # React bootstrap
    ├── App.tsx                # Root component
    ├── styles/
    │   ├── tokens.css         # Design tokens (FIRST import)
    │   └── globals.css        # Global resets
    ├── context/
    │   └── theme-provider.tsx # Theme context
    ├── components/
    │   ├── ui/                # Shared UI components
    │   │   ├── button.tsx
    │   │   ├── card.tsx
    │   │   └── index.ts       # Barrel export
    │   ├── layout/            # Layout components
    │   │   ├── header.tsx
    │   │   ├── sidebar.tsx
    │   │   └── index.ts
    │   ├── charts/            # Data visualization
    │   │   ├── donut-chart.tsx
    │   │   └── index.ts
    │   ├── feedback/          # Feedback components
    │   │   ├── toast.tsx
    │   │   ├── spinner.tsx
    │   │   └── index.ts
    │   └── features/          # Feature components
    │       └── dashboard/
    │           ├── kpi-card.tsx
    │           ├── dashboard.tsx
    │           └── index.ts
    ├── hooks/
    │   └── use-theme.ts
    ├── lib/
    │   └── utils.ts
    └── types/
        └── index.ts

Core Files

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="description" content="{{PROJECT_DESCRIPTION}}" />
    <title>{{PROJECT_TITLE}}</title>
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

package.json

{
  "name": "{{PROJECT_NAME}}",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "validate:tokens": "python scripts/validate_tokens.py src"
  },
  "dependencies": {
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
    "@types/react": "^18.3.0",
    "@types/react-dom": "^18.3.0",
    "@vitejs/plugin-react": "^4.3.0",
    "typescript": "^5.4.0",
    "vite": "^5.4.0"
  }
}

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  css: {
    devSourcemap: true,
  },
  build: {
    sourcemap: true,
  },
})

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}

tsconfig.node.json

{
  "compilerOptions": {
    "composite": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "strict": true
  },
  "include": ["vite.config.ts"]
}

src/main.tsx

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ThemeProvider } from '@/context/theme-provider'
import App from './App'

// CRITICAL: Import order matters!
import './styles/tokens.css'   // 1. Design tokens FIRST
import './styles/globals.css'  // 2. Global resets

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ThemeProvider>
      <App />
    </ThemeProvider>
  </StrictMode>,
)

src/App.tsx

import { Header, Sidebar } from '@/components/layout'
import { Dashboard } from '@/components/features/dashboard'
import './App.css'

function App() {
  return (
    <div className="app">
      <Header />
      <div className="app__body">
        <Sidebar />
        <main className="app__main">
          <Dashboard />
        </main>
      </div>
    </div>
  )
}

export default App

src/context/theme-provider.tsx

import { createContext, useContext, useEffect, useState, ReactNode } from 'react'

type Theme = 'light' | 'dark' | 'system'

interface ThemeContextType {
  theme: Theme
  setTheme: (theme: Theme) => void
}

const ThemeContext = createContext<ThemeContextType | undefined>(undefined)

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState<Theme>(() => {
    if (typeof window !== 'undefined') {
      return (localStorage.getItem('theme') as Theme) || 'system'
    }
    return 'system'
  })

  useEffect(() => {
    const root = window.document.documentElement
    root.removeAttribute('data-theme')

    if (theme === 'system') {
      const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches
        ? 'dark'
        : 'light'
      root.setAttribute('data-theme', systemTheme)
    } else {
      root.setAttribute('data-theme', theme)
    }

    localStorage.setItem('theme', theme)
  }, [theme])

  // Listen for system theme changes
  useEffect(() => {
    if (theme !== 'system') return

    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
    const handleChange = () => {
      const root = window.document.documentElement
      root.setAttribute('data-theme', mediaQuery.matches ? 'dark' : 'light')
    }

    mediaQuery.addEventListener('change', handleChange)
    return () => mediaQuery.removeEventListener('change', handleChange)
  }, [theme])

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  )
}

export function useTheme() {
  const context = useContext(ThemeContext)
  if (!context) {
    throw new Error('useTheme must be used within ThemeProvider')
  }
  return context
}

src/lib/utils.ts

import { type ClassValue, clsx } from 'clsx'

/**
 * Utility for conditionally joining classNames together
 */
export function cn(...inputs: ClassValue[]) {
  return clsx(inputs)
}

Barrel Export Pattern

Each component directory should have an index.ts file:

// src/components/ui/index.ts
export { Button } from './button'
export { Card } from './card'
export { Input } from './input'

// src/components/layout/index.ts
export { Header } from './header'
export { Sidebar } from './sidebar'
export { Footer } from './footer'

// src/components/features/dashboard/index.ts
export { Dashboard } from './dashboard'
export { KPICard } from './kpi-card'
export { DonutChart } from './donut-chart'

Commands

# Install dependencies
npm install

# Start development server
npm run dev

# Validate CSS tokens
npm run validate:tokens

# Production build
npm run build

# Preview production build
npm run preview

Integration Checklist

• [ ] tokens.css imported before all other styles
• [ ] ThemeProvider wraps entire app
• [ ] All CSS uses token variables (no hardcoded values)
• [ ] Barrel exports exist for each component directory
• [ ] Path aliases configured (@/)
• [ ] TypeScript strict mode enabled
• [ ] Build completes without errors

Rust Axum Template

Complete scaffolding template for high-performance web applications using Axum with tower middleware.

Table of Contents

• Project Structure
• Core Files
• Cargo.toml
• src/main.rs
• src/config.rs
• src/error.rs
• src/routes/mod.rs
• src/routes/health.rs
• src/routes/dashboard.rs
• src/models/mod.rs
• src/models/dashboard.rs
• templates/base.html (Tera)
• Dockerfile
• docker-compose.yml
• Commands
• Integration Checklist

Project Structure

project-name/
├── Cargo.toml                 # Dependencies and metadata
├── Cargo.lock
├── .env                       # Environment variables
├── Dockerfile
├── docker-compose.yml
├── src/
│   ├── main.rs                # Application entry point
│   ├── lib.rs                 # Library crate (optional)
│   ├── config.rs              # Configuration
│   ├── error.rs               # Error handling
│   ├── routes/                # HTTP routes
│   │   ├── mod.rs
│   │   ├── dashboard.rs
│   │   └── health.rs
│   ├── handlers/              # Request handlers
│   │   ├── mod.rs
│   │   └── dashboard_handler.rs
│   ├── models/                # Data structures
│   │   ├── mod.rs
│   │   └── dashboard.rs
│   ├── services/              # Business logic
│   │   ├── mod.rs
│   │   └── dashboard_service.rs
│   └── middleware/            # Custom middleware
│       └── mod.rs
├── static/                    # Static assets
│   ├── css/
│   │   └── tokens.css
│   └── js/
├── templates/                 # Tera templates
│   ├── base.html
│   └── dashboard.html
└── tests/
    └── integration_tests.rs

Core Files

Cargo.toml

[package]
name = "{{PROJECT_NAME}}"
version = "1.0.0"
edition = "2021"
authors = ["{{AUTHOR}}"]
description = "{{PROJECT_DESCRIPTION}}"

[dependencies]
# Web framework
axum = "0.7"
tokio = { version = "1.35", features = ["full"] }
tower = "0.4"
tower-http = { version = "0.5", features = ["fs", "trace", "cors"] }

# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

# Configuration
dotenvy = "0.15"
config = "0.14"

# Templating
tera = "1.19"

# Tracing
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

# Error handling
thiserror = "1.0"
anyhow = "1.0"

[dev-dependencies]
axum-test = "14.0"

src/main.rs

//! Application entry point.

mod config;
mod error;
mod handlers;
mod models;
mod routes;
mod services;

use axum::Router;
use std::net::SocketAddr;
use tower_http::services::ServeDir;
use tower_http::trace::TraceLayer;
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

use crate::config::Config;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Initialize tracing
    tracing_subscriber::registry()
        .with(tracing_subscriber::EnvFilter::try_from_default_env()
            .unwrap_or_else(|_| "info".into()))
        .with(tracing_subscriber::fmt::layer())
        .init();

    // Load configuration
    let config = Config::from_env()?;
    tracing::info!("Starting {} v{}", config.app_name, config.version);

    // Build application
    let app = Router::new()
        .merge(routes::create_router())
        .nest_service("/static", ServeDir::new("static"))
        .layer(TraceLayer::new_for_http());

    // Run server
    let addr = SocketAddr::from(([0, 0, 0, 0], config.port));
    tracing::info!("Listening on {}", addr);

    let listener = tokio::net::TcpListener::bind(addr).await?;
    axum::serve(listener, app).await?;

    Ok(())
}

src/config.rs

//! Application configuration.

use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct Config {
    #[serde(default = "default_app_name")]
    pub app_name: String,

    #[serde(default = "default_version")]
    pub version: String,

    #[serde(default = "default_port")]
    pub port: u16,

    #[serde(default)]
    pub debug: bool,
}

fn default_app_name() -> String {
    "{{PROJECT_NAME}}".into()
}

fn default_version() -> String {
    "1.0.0".into()
}

fn default_port() -> u16 {
    3000
}

impl Config {
    pub fn from_env() -> anyhow::Result<Self> {
        dotenvy::dotenv().ok();

        let config = config::Config::builder()
            .add_source(config::Environment::default())
            .build()?;

        Ok(config.try_deserialize()?)
    }
}

src/error.rs

//! Application error types.

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    Json,
};
use serde_json::json;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum AppError {
    #[error("Not found: {0}")]
    NotFound(String),

    #[error("Bad request: {0}")]
    BadRequest(String),

    #[error("Internal server error")]
    InternalError(#[from] anyhow::Error),
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match &self {
            AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg.clone()),
            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
            AppError::InternalError(_) => {
                tracing::error!("Internal error: {:?}", self);
                (StatusCode::INTERNAL_SERVER_ERROR, "Internal server error".into())
            }
        };

        let body = Json(json!({
            "error": message,
            "status": status.as_u16(),
        }));

        (status, body).into_response()
    }
}

src/routes/mod.rs

//! Route definitions.

pub mod dashboard;
pub mod health;

use axum::{routing::get, Router};

pub fn create_router() -> Router {
    Router::new()
        .route("/api/health", get(health::health_check))
        .route("/api/dashboard", get(dashboard::get_dashboard))
        .route("/api/dashboard/data", get(dashboard::get_dashboard_data))
}

src/routes/health.rs

//! Health check routes.

use axum::Json;
use serde::Serialize;

#[derive(Serialize)]
pub struct HealthResponse {
    status: String,
    version: String,
}

pub async fn health_check() -> Json<HealthResponse> {
    Json(HealthResponse {
        status: "ok".into(),
        version: env!("CARGO_PKG_VERSION").into(),
    })
}

src/routes/dashboard.rs

//! Dashboard routes.

use axum::Json;

use crate::models::dashboard::{DashboardData, KpiData};

pub async fn get_dashboard() -> &'static str {
    // In production, render a template here
    "Dashboard"
}

pub async fn get_dashboard_data() -> Json<DashboardData> {
    Json(DashboardData {
        kpis: vec![
            KpiData {
                label: "Total Threats".into(),
                value: 1234,
                trend: 15.3,
                trend_direction: "up".into(),
            },
            KpiData {
                label: "Blocked Attacks".into(),
                value: 892,
                trend: 8.2,
                trend_direction: "up".into(),
            },
            KpiData {
                label: "Active Alerts".into(),
                value: 23,
                trend: -5.1,
                trend_direction: "down".into(),
            },
        ],
    })
}

src/models/mod.rs

//! Data models.

pub mod dashboard;

src/models/dashboard.rs

//! Dashboard data models.

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct KpiData {
    pub label: String,
    pub value: i64,
    pub trend: f64,
    pub trend_direction: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DashboardData {
    pub kpis: Vec<KpiData>,
}

templates/base.html (Tera)

<!DOCTYPE html>
<html lang="en" data-theme="{{ theme | default(value='light') }}">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ title }} - {{PROJECT_NAME}}</title>

  <!-- Design tokens FIRST -->
  <link rel="stylesheet" href="/static/css/tokens.css">
  <link rel="stylesheet" href="/static/css/dashboard.css">

  <script>
    (function() {
      const theme = localStorage.getItem('theme') || 'light';
      document.documentElement.setAttribute('data-theme', theme);
    })();
  </script>
</head>
<body>
  {% block content %}{% endblock %}

  <script>
    function toggleTheme() {
      const html = document.documentElement;
      const current = html.getAttribute('data-theme');
      const next = current === 'dark' ? 'light' : 'dark';
      html.setAttribute('data-theme', next);
      localStorage.setItem('theme', next);
    }
  </script>
</body>
</html>

Dockerfile

# Build stage
FROM rust:1.75-slim as builder

WORKDIR /app
COPY . .
RUN cargo build --release

# Runtime stage
FROM debian:bookworm-slim

WORKDIR /app

# Copy binary
COPY --from=builder /app/target/release/{{PROJECT_NAME}} .

# Copy static files and templates
COPY static/ ./static/
COPY templates/ ./templates/

# Run
EXPOSE 3000
CMD ["./{{PROJECT_NAME}}"]

docker-compose.yml

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./static:/app/static
      - ./templates:/app/templates
    environment:
      - RUST_LOG=info
      - PORT=3000

Commands

# Build
cargo build

# Run development server (with auto-reload using cargo-watch)
cargo watch -x run

# Validate CSS tokens
python scripts/validate_tokens.py static

# Run tests
cargo test

# Production build
cargo build --release

# Format code
cargo fmt

# Lint
cargo clippy

Integration Checklist

• [ ] tokens.css exists in static/css/
• [ ] Templates load tokens.css before other styles
• [ ] Tower-http serves static files correctly
• [ ] Error types implement IntoResponse
• [ ] Tracing configured for observability
• [ ] Configuration loads from environment
• [ ] Dockerfile builds successfully
• [ ] Tests cover critical routes

Token Validation Rules

Complete reference for CSS design token validation rules used by validate_tokens.py.

Table of Contents

• Overview
• Severity Levels
• Validation Rules
• 1. Colors (Error)
• 2. Spacing (Error)
• 3. Font Sizes (Error)
• 4. Border Radius (Warning)
• 5. Box Shadows (Warning)
• 6. Transitions (Info - Strict Mode Only)
• 7. Z-Index (Warning)
• Exceptions (Always Allowed)
• CSS Keywords
• Small Values
• Layout Values
• Context-Specific
• Exception Properties
• Script Usage
• CI/CD Integration
• GitHub Actions
• Pre-commit Hook
• Output Example

Overview

The token validation script scans CSS files for hardcoded values that should use design tokens. This ensures consistent theming and makes dark mode, brand customization, and accessibility features work correctly.

Severity Levels

Validation Rules

1. Colors (Error)

Pattern: Hardcoded hex, rgb, rgba, hsl values

Bad:

.button {
  background: #FA582D;
  color: rgb(30, 41, 59);
  border-color: rgba(0, 0, 0, 0.1);
}

Good:

.button {
  background: var(--color-primary);
  color: var(--color-text-primary);
  border-color: var(--color-border-primary);
}

Common Token Mappings:

Exceptions:

• currentColor - CSS keyword
• transparent - CSS keyword
• inherit - CSS keyword

2. Spacing (Error)

Pattern: Hardcoded pixel values ≥ 4px on spacing properties

Properties: padding, margin, gap, top, right, bottom, left

Bad:

.card {
  padding: 16px;
  margin-bottom: 24px;
  gap: 8px;
}

Good:

.card {
  padding: var(--spacing-md);
  margin-bottom: var(--spacing-lg);
  gap: var(--spacing-sm);
}

Token Scale:

Exceptions:

• 0, 0px - Zero values
• 1px - Hairline borders
• 2px - Focus outlines

3. Font Sizes (Error)

Pattern: Hardcoded font-size values

Bad:

.title {
  font-size: 24px;
}
.body {
  font-size: 14px;
}

Good:

.title {
  font-size: var(--font-size-2xl);
}
.body {
  font-size: var(--font-size-sm);
}

Token Scale:

4. Border Radius (Warning)

Pattern: Hardcoded border-radius values

Bad:

.button {
  border-radius: 8px;
}
.avatar {
  border-radius: 9999px;
}

Good:

.button {
  border-radius: var(--radius-md);
}
.avatar {
  border-radius: var(--radius-full);
}

Token Scale:

5. Box Shadows (Warning)

Pattern: Hardcoded box-shadow values

Bad:

.card {
  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
}
.modal {
  box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
}

Good:

.card {
  box-shadow: var(--shadow-sm);
}
.modal {
  box-shadow: var(--shadow-2xl);
}

Token Scale:

6. Transitions (Info - Strict Mode Only)

Pattern: Hardcoded transition timing

Bad:

.button {
  transition: all 150ms ease;
}

Good:

.button {
  transition: var(--transition-fast);
}

Token Scale:

7. Z-Index (Warning)

Pattern: Hardcoded z-index values ≥ 100

Bad:

.dropdown {
  z-index: 1000;
}
.modal {
  z-index: 1050;
}

Good:

.dropdown {
  z-index: var(--z-dropdown);
}
.modal {
  z-index: var(--z-modal);
}

Token Scale:

Exceptions (Always Allowed)

CSS Keywords

• currentColor
• transparent
• inherit
• initial
• unset
• none
• auto

Small Values

• 0, 0px - Zero
• 1px - Hairline borders
• 2px - Focus outlines
• 100%, 50% - Percentages

Layout Values

These are skipped because they're structural, not themeable:

• Container max-widths (1400px, 1200px, 1024px)
• Media query breakpoints (768px, 640px, 480px)
• Grid functions (minmax(), repeat())
• Grid templates

Context-Specific

• Lines starting with -- (token definitions)
• Comments (/*, *, */)
• @media query lines
• @keyframes definitions
• Animation percentages (0%, 100%)

Exception Properties

Some properties accept hardcoded values:

• outline - Accessibility focus indicators
• outline-offset - Accessibility
• transform - Animation transforms
• animation - Animation definitions
• content - Pseudo-element content
• clip-path - Complex clipping
• mask - Complex masking

Script Usage

# Basic validation
python scripts/validate_tokens.py src/styles

# Strict mode (includes info-level)
python scripts/validate_tokens.py src --strict

# JSON output for CI/CD
python scripts/validate_tokens.py src --json

# Show fix suggestions
python scripts/validate_tokens.py src --fix-suggestions

CI/CD Integration

GitHub Actions

- name: Validate CSS Tokens
  run: python scripts/validate_tokens.py src --json > token-report.json

- name: Check for Errors
  run: |
    errors=$(jq '.errors' token-report.json)
    if [ "$errors" -gt 0 ]; then
      echo "Found $errors token violations"
      exit 1
    fi

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

python scripts/validate_tokens.py src --strict
if [ $? -ne 0 ]; then
  echo "CSS token validation failed. Fix violations before committing."
  exit 1
fi

Output Example

======================================================================
  CSS DESIGN TOKEN VALIDATION REPORT
======================================================================

  src/components/Card.css
  ------------------------------------------------------------
    ❌ Line 5:12 [ERROR]
       Found: #FA582D
       Rule: colors
       Fix: Use semantic color token (e.g., --color-primary)
       Suggested: var(--color-cyber-orange)

    ⚠️ Line 12:3 [WARNING]
       Found: border-radius: 8px
       Rule: radii
       Fix: Use radius token (e.g., --radius-md)
       Suggested: var(--radius-md)

----------------------------------------------------------------------
  SUMMARY
----------------------------------------------------------------------
  Files scanned:     15
  Files with issues: 3
  Total violations:  7
    - Errors:   4
    - Warnings: 3
    - Info:     0

  By Category:
    - colors: 4
    - radii: 2
    - shadows: 1