Design System - Desktop Mockup

This design system provides comprehensive design tokens and atomic utilities extracted from the Desktop.png mockup, following W3C DTCG standards with modern CSS features.

Overview

Design Tokens

W3C DTCG-compliant tokens

File: src/styles/design-tokens.json

Complete CSS

Tokens + Tailwind-style utilities

File: src/styles/design-system.css

Documentation

Comprehensive usage guide

File: src/styles/DESIGN-SYSTEM.md

Features

✅ CSS Custom Properties - All design tokens as CSS variables

✅ Atomic Utilities - Comprehensive Tailwind-style utility classes

✅ Container Query Variants - Responsive utilities (sm:, md:, lg:, xl:)

✅ State Variants - Hover, focus, and active states

✅ Accessibility - Reduced motion, forced colors, WCAG-compliant focus

✅ Cascade Layers - Organized with @layer for predictable specificity

✅ Logical Properties - Better i18n support (RTL languages)

---

Quick Start

Installation

1. Import the design system in your global CSS or layout:

   @import '/styles/design-system.css';

2. Or link in HTML:

   <link rel="stylesheet" href="/styles/design-system.css">

3. Start using utilities:

   <div class="bg-primary-600 text-white p-lg rounded-md">
     Utility-first design!
   </div>

---

Design Tokens

Colors

Primary Blue Palette

—color-primary-400

#2D7AB8

Lighter primary for hover states

—color-primary-500

#195A8E

Primary brand blue (header)

—color-primary-600

#0F5A96

Accent blue (buttons, interactive)

—color-primary-700

#0D4A7A

Darker primary for active states

Token	Value	Usage
--color-primary-400	#2D7AB8	Lighter primary for hover states
--color-primary-500	#195A8E	Primary brand blue (header)
--color-primary-600	#0F5A96	Accent blue (buttons, interactive)
--color-primary-700	#0D4A7A	Darker primary for active states

Accent Blue Palette

—color-accent-300

#C0E5FF

Light backgrounds

—color-accent-400

#A8DBFF

Decorative elements

—color-accent-500

#87CEEB

Secondary accents

Token	Value	Usage
--color-accent-300	#C0E5FF	Light backgrounds
--color-accent-400	#A8DBFF	Decorative elements
--color-accent-500	#87CEEB	Secondary accents

Neutral Gray Scale

—color-neutral-50

#F9FAFB

Off-white background

—color-neutral-100

#F3F4F6

Light gray background

—color-neutral-200

#E5E7EB

Border gray

—color-neutral-300

#CDD5E3

Placeholder background

—color-neutral-400

#9CA3AF

Disabled text

—color-neutral-500

#6B7280

Secondary text

—color-neutral-600

#4B5563

Body text

—color-neutral-700

#374151

Primary text

—color-neutral-900

#111827

Heading text

Token	Value	Usage
--color-neutral-50	#F9FAFB	Off-white background
--color-neutral-100	#F3F4F6	Light gray background
--color-neutral-200	#E5E7EB	Border gray
--color-neutral-300	#CDD5E3	Placeholder background
--color-neutral-400	#9CA3AF	Disabled text
--color-neutral-500	#6B7280	Secondary text
--color-neutral-600	#4B5563	Body text
--color-neutral-700	#374151	Primary text
--color-neutral-900	#111827	Heading text

Typography

Font Sizes

Token	Value	Pixels	Usage
--font-size-xs	0.75rem	12px	Extra small text
--font-size-sm	0.875rem	14px	Small text, labels
--font-size-base	1rem	16px	Base font size
--font-size-lg	1.125rem	18px	Large body text
--font-size-xl	1.25rem	20px	Subheadings
--font-size-2xl	1.5rem	24px	Section headings
--font-size-3xl	2rem	32px	Page headings
--font-size-4xl	3rem	48px	Large headings
--font-size-5xl	4rem	64px	Display headings

Font Weights

Token	Value	Name
--font-weight-regular	400	Regular
--font-weight-medium	500	Medium
--font-weight-semibold	600	Semi-bold
--font-weight-bold	700	Bold

Line Heights

Token	Value	Usage
--line-height-tight	1.1	Headings
--line-height-snug	1.25	Tight paragraphs
--line-height-normal	1.5	Body text
--line-height-relaxed	1.625	Long-form content
--line-height-loose	1.75	Very spacious text

Spacing Scale

Mathematical progression using rem units (based on 4px grid):

Token	Value	Pixels	Multiplier
--spacing-scale-xs	0.25rem	4px	1×
--spacing-scale-sm	0.5rem	8px	2×
--spacing-scale-md	1rem	16px	4×
--spacing-scale-lg	1.5rem	24px	6×
--spacing-scale-xl	2rem	32px	8×
--spacing-scale-2xl	3rem	48px	12×
--spacing-scale-3xl	4rem	64px	16×

Layout Tokens

Border Radius

Token	Value	Pixels	Usage
--border-radius-sm	0.25rem	4px	Small elements
--border-radius-md	0.5rem	8px	Medium elements
--border-radius-lg	0.75rem	12px	Large elements
--border-radius-xl	1rem	16px	Extra large
--border-radius-full	9999px	∞	Pills/circles

Shadows

Token	Value	Usage
--shadow-sm	0 1px 2px 0 rgba(0, 0, 0, 0.05)	Subtle
--shadow-md	0 4px 6px -1px rgba(0, 0, 0, 0.1)	Medium
--shadow-lg	0 10px 15px -3px rgba(0, 0, 0, 0.1)	High elevation
--shadow-xl	0 20px 25px -5px rgba(0, 0, 0, 0.1)	Maximum

---

Utility Classes

Color Utilities

Text Colors

<p class="text-primary-600">Primary text</p>
<p class="text-neutral-500">Secondary text</p>
<p class="text-neutral-900">Heading text</p>
<p class="text-white">White text</p>

Background Colors

<div class="bg-primary-600">Primary background</div>
<div class="bg-neutral-50">Light gray background</div>
<div class="bg-surface-elevated">Elevated surface</div>
<div class="bg-white">White background</div>

Border Colors

<div class="border border-neutral-200">Light border</div>
<div class="border-2 border-primary-600">Primary border</div>

Spacing Utilities

Tip

All spacing utilities use logical properties for better internationalization and RTL language support.

Padding

<!-- All sides -->
<div class="p-md">Padding all sides (16px)</div>

<!-- Horizontal (inline) -->
<div class="px-lg">Horizontal padding (24px)</div>

<!-- Vertical (block) -->
<div class="py-md">Vertical padding (16px)</div>

<!-- Individual sides -->
<div class="pt-lg">Top padding (24px)</div>
<div class="pr-md">Right padding (16px)</div>
<div class="pb-xl">Bottom padding (32px)</div>
<div class="pl-sm">Left padding (8px)</div>

Margin

<!-- All sides -->
<div class="m-lg">Margin all sides (24px)</div>

<!-- Horizontal centering -->
<div class="mx-auto">Center horizontally</div>

<!-- Vertical -->
<div class="my-xl">Vertical margin (32px)</div>

<!-- Individual sides -->
<div class="mt-md mb-lg">Top 16px, bottom 24px</div>

Gap

<!-- Grid/Flexbox gap -->
<div class="flex gap-md">Gap 16px</div>
<div class="grid gap-lg">Gap 24px</div>

<!-- Directional gap -->
<div class="grid gap-x-lg gap-y-md">
  Horizontal 24px, vertical 16px
</div>

Typography Utilities

<!-- Font families -->
<h1 class="font-display">Display heading</h1>
<p class="font-sans">Body text</p>

<!-- Font sizes -->
<h1 class="text-5xl">64px heading</h1>
<h2 class="text-3xl">32px heading</h2>
<p class="text-lg">18px body text</p>

<!-- Font weights -->
<p class="font-bold">Bold text</p>
<p class="font-semibold">Semi-bold text</p>
<p class="font-medium">Medium text</p>

<!-- Line heights -->
<h1 class="leading-tight">Tight heading</h1>
<p class="leading-normal">Normal body text</p>
<p class="leading-relaxed">Relaxed paragraphs</p>

Layout Utilities

<!-- Border radius -->
<div class="rounded-md">Medium rounded corners</div>
<button class="rounded-full">Pill-shaped button</button>

<!-- Shadows -->
<div class="shadow-md">Medium shadow</div>
<div class="shadow-lg">Large shadow</div>

<!-- Container -->
<div class="container">
  Centered container with max-width 1200px
</div>

---

Responsive Variants

Use container query variants for responsive design based on container size:

Breakpoints

• sm: 640px (40rem)
• md: 768px (48rem)
• lg: 1024px (64rem)
• xl: 1280px (80rem)

Examples

Typography

<h1 class="text-2xl md:text-3xl lg:text-4xl xl:text-5xl">
  Responsive heading that grows with container
</h1>

Spacing

<div class="p-sm md:p-md lg:p-lg xl:p-xl">
  Padding increases at larger breakpoints
</div>

Grid

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</div>

---

State Variants

Hover States

<button class="bg-primary-600 hover:bg-primary-700 text-white">
  Button with hover state
</button>

<a href="#" class="text-neutral-700 hover:text-primary-600">
  Link with hover color
</a>

Focus States

<input class="focus:outline-primary-600" type="text" />

<button class="focus:ring-primary-500">
  Button with focus ring
</button>

Active States

<button class="bg-primary-600 active:bg-primary-700 active:scale-95">
  Button with active/pressed state
</button>

---

Complete Examples

Hero Section

<section class="bg-white py-3xl">
  <div class="container">
    <h1 class="font-display text-4xl md:text-5xl font-bold text-neutral-900 mb-lg">
      We Serve
    </h1>
    <p class="text-lg md:text-xl leading-relaxed text-neutral-600 mb-xl">
      We serve almost 60 people every seconds Saturday all while providing
      necessary recourses like showers, Clothes, and hair care.
    </p>
    <button class="px-lg py-md bg-primary-600 hover:bg-primary-700
                   text-white rounded-sm font-semibold">
      Learn More
    </button>
  </div>
</section>

Card Component

<article class="bg-white p-lg rounded-lg shadow-md border border-neutral-200
                hover:shadow-lg">
  <h2 class="font-display text-2xl font-bold text-neutral-900 mb-md">
    Card Title
  </h2>
  <p class="text-base leading-normal text-neutral-600 mb-lg">
    Card content with proper spacing and typography that maintains
    consistency across your application.
  </p>
  <button class="px-lg py-md bg-primary-600 hover:bg-primary-700
                 active:scale-95 text-white rounded-sm font-semibold
                 focus:ring-primary-500">
    Action Button
  </button>
</article>

Statistics Grid

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-lg">
  <div class="bg-neutral-50 p-lg rounded-md">
    <h3 class="text-sm text-neutral-500 mb-xs">Showers</h3>
    <p class="text-4xl font-bold text-primary-600">64</p>
    <p class="text-sm text-neutral-400 mt-xs">Requested</p>
  </div>

  <div class="bg-neutral-50 p-lg rounded-md">
    <h3 class="text-sm text-neutral-500 mb-xs">Clothes</h3>
    <p class="text-4xl font-bold text-primary-600">64</p>
    <p class="text-sm text-neutral-400 mt-xs">Requested</p>
  </div>

  <div class="bg-neutral-50 p-lg rounded-md">
    <h3 class="text-sm text-neutral-500 mb-xs">Haircuts</h3>
    <p class="text-4xl font-bold text-primary-600">64</p>
    <p class="text-sm text-neutral-400 mt-xs">Requested</p>
  </div>
</div>

---

Accessibility

The design system includes automatic accessibility support:

Reduced Motion

Respects prefers-reduced-motion preference to minimize or disable animations for users who prefer reduced motion.

High Contrast Mode

Adapts to forced colors mode (high contrast mode) for better visibility.

Focus Indicators

All interactive elements have WCAG-compliant focus indicators with 2px outline and proper contrast ratios.

Logical Properties

Uses logical properties (padding-inline, margin-block, etc.) for better internationalization and RTL language support.

---

Using with Custom CSS

You can mix utilities with custom CSS using the design tokens:

.custom-component {
  /* Use tokens for consistency */
  background: var(--color-surface-base);
  padding: var(--spacing-scale-lg);
  border-radius: var(--border-radius-md);
  box-shadow: var(--shadow-md);
  color: var(--color-text-primary);

  /* Custom properties */
  display: flex;
  align-items: center;
  gap: var(--spacing-scale-md);
}

---

Browser Support

Full Support (Modern Browsers)

• Chrome/Edge 88+
• Firefox 110+
• Safari 16+

Features Used

• CSS Custom Properties
• Cascade Layers (@layer)
• Container Queries
• Logical Properties

Progressive Enhancement

The design system gracefully degrades on older browsers:

• Base utilities work with custom property support
• Container query variants fall back to standard behavior
• Logical properties have reasonable fallbacks

---

Best Practices

Consistency First

Always use design tokens and utilities instead of hardcoded values for consistency across your application.

Good Practices

<!-- ✅ Use utility classes -->
<div class="bg-white p-lg rounded-md shadow-md">
  <h2 class="text-2xl font-bold mb-md">Title</h2>
</div>

<!-- ✅ Use tokens in custom CSS -->
<style>
  .component {
    color: var(--color-primary-600);
    padding: var(--spacing-scale-lg);
  }
</style>

Avoid

<!-- ❌ Don't use hardcoded values -->
<div style="background: white; padding: 24px;">
  <h2 style="font-size: 24px;">Title</h2>
</div>

<!-- ❌ Don't mix utilities with inline styles -->
<div class="bg-white" style="padding: 24px;">
  <h2 class="text-2xl">Title</h2>
</div>

---

Integration with SCSS

If using SCSS in your project, you can import the design system and use tokens:

// Import design system
@import '/styles/design-system.css';

// Use tokens in SCSS
.my-component {
  background: var(--color-primary-600);
  padding: var(--spacing-scale-lg);
  border-radius: var(--border-radius-md);

  &:hover {
    background: var(--color-primary-700);
  }
}

---

Resources

• W3C Design Tokens Specification
• CSS Cascade Layers
• CSS Container Queries
• CSS Logical Properties
• Full Documentation

---

Generated from: Desktop.png mockup

Last Updated: 2025-01-23

Format: W3C Design Tokens Community Group (DTCG)

Total Tokens: 65+

Categories: Colors, Typography, Spacing, Layout