respira/DESIGN_TOKENS_REFERENCE.md

Design Tokens Quick Reference

Quick lookup for all design tokens and standard patterns in SKiTCH Controller.

---

Colors

Semantic Colors

/* Primary - Blue (Actions, Branding) */
--color-primary: #2563eb;        /* blue-600 */
--color-primary-light: #3b82f6;  /* blue-500 */
--color-primary-dark: #1d4ed8;   /* blue-700 */

/* Secondary - Slate (Secondary actions) */
--color-secondary: #64748b;      /* slate-600 */
--color-secondary-light: #94a3b8; /* slate-400 */

/* Success - Green (Complete, Good) */
--color-success: #16a34a;        /* green-600 */
--color-success-bg: #dcfce7;     /* green-100 */

/* Warning - Amber (Wait, Caution) */
--color-warning: #d97706;        /* amber-600 */
--color-warning-bg: #fef3c7;     /* amber-100 */

/* Danger - Red (Errors, Destructive) */
--color-danger: #dc2626;         /* red-600 */
--color-danger-bg: #fee2e2;      /* red-100 */

/* Info - Cyan (Active, Information) */
--color-info: #0891b2;           /* cyan-600 */
--color-info-bg: #cffafe;        /* cyan-100 */

/* Neutral - Gray (Text, Borders) */
--color-neutral-50: #f9fafb;     /* gray-50 - Subtle BG */
--color-neutral-100: #f3f4f6;    /* gray-100 - Card BG */
--color-neutral-200: #e5e7eb;    /* gray-200 - Borders */
--color-neutral-300: #d1d5db;    /* gray-300 - Disabled BG */
--color-neutral-600: #4b5563;    /* gray-600 - Secondary text */
--color-neutral-900: #111827;    /* gray-900 - Primary text */

Usage Guide

Token	Use For	Example
primary	Main actions, links, current state	Connect, Upload, Start buttons
secondary	Less important actions	Mask Trace, secondary buttons
success	Completed states, positive feedback	Sewing complete, upload success
warning	Waiting states, cautions	Color change wait, pause
danger	Errors, destructive actions	Delete, disconnect, errors
info	Active states, information	Sewing in progress, informational messages
neutral-900	Primary text	Headings, body text
neutral-600	Secondary text	Labels, helper text
neutral-300	Borders, disabled states	Card borders, disabled buttons
neutral-100	Backgrounds	Card backgrounds
neutral-50	Subtle backgrounds	Component backgrounds

---

Typography

Text Sizes

// Headings
h1: "text-2xl font-bold text-neutral-900"        // 24px - Main title
h2: "text-xl font-semibold text-neutral-900"     // 20px - Section titles
h3: "text-base font-semibold text-neutral-900"   // 16px - Subsections
h4: "text-sm font-semibold text-neutral-700"     // 14px - Small headings

// Body Text
text-base: 16px    // Large body text, important info
text-sm: 14px      // Standard body text (MINIMUM)
text-xs: 12px      // Small text, captions
text-[11px]: 11px  // Very small (use sparingly)

// Line Heights
leading-tight: 1.25    // Headings
leading-normal: 1.5    // Body text
leading-relaxed: 1.625 // Comfortable reading

Font Weights

font-normal: 400    // Regular text
font-medium: 500    // Emphasis
font-semibold: 600  // Headings, labels
font-bold: 700      // Main headings, important

Usage Examples

// Page title
<h1 className="text-2xl font-bold text-neutral-900">SKiTCH Controller</h1>

// Section header
<h2 className="text-xl font-semibold text-neutral-900">Pattern Preview</h2>

// Subsection
<h3 className="text-base font-semibold text-neutral-900">Pattern Information</h3>

// Small heading
<h4 className="text-sm font-semibold text-neutral-700">Color Blocks</h4>

// Body text
<p className="text-sm text-neutral-700 leading-normal">Description text...</p>

// Label
<span className="text-xs font-medium text-neutral-600 uppercase tracking-wide">File Name</span>

// Value
<span className="text-sm font-semibold text-neutral-900">pattern.pes</span>

---

Spacing

Padding Scale

p-2: 0.5rem (8px)   // Tight
p-3: 0.75rem (12px) // Compact
p-4: 1rem (16px)    // Standard
p-5: 1.25rem (20px) // Comfortable
p-6: 1.5rem (24px)  // Spacious
p-8: 2rem (32px)    // Very spacious

Gap Scale

gap-1: 0.25rem (4px)  // Very tight
gap-2: 0.5rem (8px)   // Tight grouping
gap-3: 0.75rem (12px) // Related items
gap-4: 1rem (16px)    // Section spacing
gap-6: 1.5rem (24px)  // Major sections
gap-8: 2rem (32px)    // Large gaps

Margin Scale

mb-2: 0.5rem (8px)   // Tight
mb-3: 0.75rem (12px) // Compact
mb-4: 1rem (16px)    // Standard
mb-5: 1.25rem (20px) // Comfortable
mb-6: 1.5rem (24px)  // Spacious
mb-8: 2rem (32px)    // Large gap

Standard Component Spacing

// Card padding
"p-6"           // Standard card (24px)
"p-5"           // Compact card (20px)
"p-4"           // Small card (16px)

// Content stacking
"space-y-2"     // Tight grouping (8px)
"space-y-3"     // Related items (12px)
"space-y-4"     // Section spacing (16px)
"space-y-6"     // Major sections (24px)

// Grid gaps
"gap-3"         // Tight grid (12px)
"gap-4"         // Standard grid (16px)
"gap-6"         // Spacious grid (24px)

---

Buttons

Primary Button (Main Actions)

className="
  px-6 py-3
  bg-primary text-white
  rounded-lg font-semibold text-sm
  shadow-sm
  hover:bg-primary-light hover:shadow-md hover:scale-[1.02]
  active:bg-primary-dark active:scale-[0.98]
  focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
  disabled:bg-neutral-300 disabled:text-neutral-500 disabled:cursor-not-allowed disabled:shadow-none
  transition-all duration-150 ease-in-out
  cursor-pointer
"

Use for: Connect, Upload, Start Sewing, Resume

---

Secondary Button (Less Important Actions)

className="
  px-6 py-3
  bg-white text-neutral-700 border border-neutral-300
  rounded-lg font-semibold text-sm
  shadow-sm
  hover:bg-neutral-50 hover:border-neutral-400
  active:bg-neutral-100 active:scale-[0.98]
  focus:outline-none focus:ring-2 focus:ring-neutral-400 focus:ring-offset-2
  disabled:bg-neutral-50 disabled:text-neutral-400 disabled:cursor-not-allowed
  transition-all duration-150
  cursor-pointer
"

Use for: Mask Trace, Refresh, Cancel

---

Danger Button (Destructive Actions)

className="
  px-6 py-3
  bg-danger text-white
  rounded-lg font-semibold text-sm
  shadow-sm
  hover:bg-red-700 hover:shadow-md
  active:bg-red-800 active:scale-[0.98]
  focus:outline-none focus:ring-2 focus:ring-danger focus:ring-offset-2
  disabled:bg-neutral-300 disabled:text-neutral-500 disabled:cursor-not-allowed disabled:shadow-none
  transition-all duration-150
  cursor-pointer
"

Use for: Delete, Disconnect

---

Icon Button (Zoom, Controls)

className="
  w-10 h-10
  flex items-center justify-center
  bg-white border border-neutral-300
  rounded-lg
  text-neutral-700
  hover:bg-primary hover:text-white hover:border-primary
  active:bg-primary-dark active:scale-95
  focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
  transition-all duration-150
  cursor-pointer
"
aria-label="Descriptive label"

Use for: Zoom in/out/reset, small controls

---

Cards & Containers

Standard Card

<div className="bg-white p-6 rounded-lg shadow-md border border-neutral-100">
  <div className="mb-5 pb-3 border-b border-neutral-200">
    <h2 className="text-xl font-bold text-neutral-900">Title</h2>
  </div>
  <div className="space-y-4">
    {/* Content */}
  </div>
</div>

---

Compact Card

<div className="bg-white p-5 rounded-lg shadow-md border border-neutral-100">
  {/* Content */}
</div>

---

Info Card (Small)

<div className="bg-white p-3 rounded-lg border border-neutral-200 shadow-sm">
  <div className="text-xs font-medium text-neutral-500 mb-1.5 uppercase tracking-wide">
    Label
  </div>
  <div className="font-semibold text-sm text-neutral-900">
    Value
  </div>
</div>

---

Alert Boxes

Info Alert

<div className="bg-info-bg border-l-4 border-info p-4 rounded-lg">
  <div className="flex items-start gap-3">
    <InformationCircleIcon className="w-6 h-6 text-info flex-shrink-0" />
    <div>
      <h4 className="font-semibold text-cyan-900 mb-1">Title</h4>
      <p className="text-sm text-cyan-800">Message</p>
    </div>
  </div>
</div>

---

Success Alert

<div className="bg-success-bg border-l-4 border-success p-4 rounded-lg">
  <div className="flex items-start gap-3">
    <CheckCircleIcon className="w-6 h-6 text-success flex-shrink-0" />
    <div>
      <h4 className="font-semibold text-green-900 mb-1">Title</h4>
      <p className="text-sm text-green-800">Message</p>
    </div>
  </div>
</div>

---

Warning Alert

<div className="bg-warning-bg border-l-4 border-warning p-4 rounded-lg">
  <div className="flex items-start gap-3">
    <ExclamationTriangleIcon className="w-6 h-6 text-warning flex-shrink-0" />
    <div>
      <h4 className="font-semibold text-amber-900 mb-1">Title</h4>
      <p className="text-sm text-amber-800">Message</p>
    </div>
  </div>
</div>

---

Error Alert

<div className="bg-danger-bg border-l-4 border-danger p-4 rounded-lg">
  <div className="flex items-start gap-3">
    <XCircleIcon className="w-6 h-6 text-danger flex-shrink-0" />
    <div>
      <h4 className="font-semibold text-red-900 mb-1">Title</h4>
      <p className="text-sm text-red-800">Message</p>
    </div>
  </div>
</div>

---

Progress Bars

Standard Progress Bar

<div className="h-2.5 bg-neutral-200 rounded-full overflow-hidden shadow-inner">
  <div
    className="h-full bg-gradient-to-r from-primary to-primary-light transition-all duration-300 ease-out relative overflow-hidden"
    style={{ width: `${progress}%` }}
    role="progressbar"
    aria-valuenow={progress}
    aria-valuemin={0}
    aria-valuemax={100}
    aria-label="Progress description"
  >
    <div className="absolute inset-0 bg-gradient-to-r from-transparent via-white/30 to-transparent animate-[shimmer_2s_infinite]" />
  </div>
</div>

---

Block Progress Bar (Smaller)

<div className="h-1.5 bg-neutral-200 rounded-full overflow-hidden">
  <div
    className="h-full bg-primary transition-all duration-300"
    style={{ width: `${progress}%` }}
  />
</div>

---

Status Badges

Status Badge Template

<span className={`
  inline-flex items-center gap-2
  px-3.5 py-2
  rounded-lg
  font-semibold text-sm
  border border-current/20
  ${statusColor}
`}>
  <span className="text-base leading-none">{icon}</span>
  <span>{text}</span>
</span>

Status Color Classes

const statusColors = {
  idle: 'bg-cyan-100 text-cyan-800 border-cyan-200',
  active: 'bg-yellow-100 text-yellow-800 border-yellow-200',
  complete: 'bg-green-100 text-green-800 border-green-200',
  error: 'bg-red-100 text-red-800 border-red-200',
  info: 'bg-blue-100 text-blue-800 border-blue-200',
};

---

Overlays (Canvas)

Standard Overlay

<div className="absolute top-3 left-3 bg-white/98 backdrop-blur-sm p-4 rounded-xl shadow-lg border border-neutral-200 z-10">
  {/* Content */}
</div>

---

Data Grids

Info Grid (2×2)

<div className="grid grid-cols-2 gap-3">
  <div className="bg-white p-3 rounded-lg border border-neutral-200 shadow-sm">
    <div className="text-xs font-medium text-neutral-500 mb-1.5 uppercase tracking-wide">
      Label
    </div>
    <div className="font-semibold text-sm text-neutral-900">
      Value
    </div>
  </div>
  {/* Repeat for other cells */}
</div>

---

Key-Value Rows

<div className="bg-neutral-50 p-4 rounded-lg border border-neutral-200 space-y-3">
  <div className="flex justify-between items-center">
    <span className="text-sm font-medium text-neutral-600">Label:</span>
    <span className="text-base font-bold text-neutral-900">Value</span>
  </div>
  {/* Repeat for other rows */}
</div>

---

Icons

Size Scale

w-4 h-4: 16px   // Small icons (in buttons)
w-5 h-5: 20px   // Standard icons
w-6 h-6: 24px   // Medium icons (alerts)
w-8 h-8: 32px   // Large icons (status)
w-10 h-10: 40px // Very large (main features)

Usage

// In buttons
<PlayIcon className="w-4 h-4" />

// In alerts
<InformationCircleIcon className="w-6 h-6 text-info" />

// In headers
<CheckCircleIcon className="w-8 h-8 text-success" />

---

Border Radius

rounded: 4px      // Subtle (rarely used)
rounded-md: 6px   // Small elements
rounded-lg: 8px   // Standard (buttons, cards)
rounded-xl: 12px  // Large elements (overlays)
rounded-full: 9999px // Pills, circles

---

Shadows

shadow-sm: Small shadow        // Buttons, cards
shadow-md: Medium shadow       // Hover states
shadow-lg: Large shadow        // Overlays, modals
shadow-inner: Inset shadow     // Progress bar tracks

// With color
shadow-primary/10: Colored shadow (10% opacity)
shadow-primary/20: Stronger colored shadow
shadow-primary/30: Prominent colored shadow

---

Transitions

// Standard transition
transition-all duration-150 ease-in-out

// Specific properties
transition-colors duration-150
transition-transform duration-150
transition-opacity duration-300

// Easing
ease-in-out  // Standard
ease-out     // Decelerate
ease-in      // Accelerate

---

Accessibility Attributes

Buttons

aria-label="Descriptive action"    // For icon buttons
title="Tooltip text"                // For hover tooltips
disabled={condition}                // Properly disabled

Progress Bars

role="progressbar"
aria-valuenow={currentValue}
aria-valuemin={0}
aria-valuemax={100}
aria-label="What's progressing"

Interactive Elements

focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2
tabIndex={0}                        // If not naturally focusable

---

Touch Targets

Minimum Sizes

// Buttons: 44×44px minimum
min-w-[44px] min-h-[44px]

// Icon buttons: Use w-10 h-10 (40px) as minimum
w-10 h-10  // Close to 44px with padding

---

Responsive Breakpoints

sm: 640px   // Small devices
md: 768px   // Tablets
lg: 1024px  // Laptops
xl: 1280px  // Desktops
2xl: 1536px // Large screens

Usage

// Mobile-first approach
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">

// Show/hide by breakpoint
<div className="hidden md:block">Desktop only</div>
<div className="md:hidden">Mobile only</div>

---

Copy-Paste Snippets

Section Header

<div className="mb-5 pb-3 border-b border-neutral-200">
  <h2 className="text-xl font-bold text-neutral-900">Section Title</h2>
</div>

Stat Card

<div className="bg-white p-3 rounded-lg border border-neutral-200 shadow-sm">
  <div className="text-xs font-medium text-neutral-500 mb-1.5 uppercase tracking-wide">
    Label
  </div>
  <div className="font-semibold text-sm text-neutral-900">
    Value
  </div>
</div>

Loading Spinner

<div className="w-6 h-6 border-2 border-primary border-t-transparent rounded-full animate-spin" />

---

Quick Reference Table

Element	Padding	Radius	Shadow	Border
Button	px-6 py-3	rounded-lg	shadow-sm	-
Card	p-6	rounded-lg	shadow-md	border-neutral-100
Overlay	p-4	rounded-xl	shadow-lg	border-neutral-200
Alert	p-4	rounded-lg	-	border-l-4
Badge	px-3.5 py-2	rounded-lg	-	border-current/20
Stat Card	p-3	rounded-lg	shadow-sm	border-neutral-200

---

Quick reference for SKiTCH Controller design system Use with: All component files Created: 2025-12-06