Building a Design System - Grid Systems as the Foundation

Steps

Understanding the Grid-First Principle

Design systems aren't collections of pretty components—they're mathematical frameworks for creating consistent, scalable user experiences. Let's understand why grid-first approach works better than the traditional backwards approach.

Copy

1// Traditional approach (backwards) ❌
2// 1. Choose colors and fonts
3// 2. Design individual components
4// 3. Try to make layouts consistent
5// 4. Struggle with responsive behavior
6
7// Grid-first approach ✅
8// 1. Establish mathematical foundation (grid)
9// 2. Define spacing and sizing relationships
10// 3. Create components that align to the system
11// 4. Responsive behavior becomes predictable
12
13// Audit Exercise: Measure spacing inconsistencies
14const auditResults = {
15  page1: { headerMargin: '24px', cardPadding: '16px', buttonSpacing: '12px' },
16  page2: { headerMargin: '20px', cardPadding: '20px', buttonSpacing: '8px' },
17  page3: { headerMargin: '32px', cardPadding: '12px', buttonSpacing: '16px' }
18};
19
20// Question: Do you see mathematical relationships or arbitrary decisions?

Analyze Industry Leader Approaches

We'll examine three different grid-based design systems: IBM Carbon's 2x Grid System, Material Design's 8dp Baseline Grid, and Atlassian's Enterprise Grid. Each solves different challenges and provides proven patterns.

Copy

1/* IBM Carbon 2x System - Binary Progression */
2:root {
3  --base-unit: 8px;
4  --space-2x: 16px;   /* Base × 2 */
5  --space-4x: 32px;   /* Base × 4 */
6  --space-8x: 64px;   /* Base × 8 */
7  --space-16x: 128px; /* Base × 16 */
8}
9
10/* Material Design 8dp System - Linear Progression */
11:root {
12  --base-unit: 8px;
13  --space-1x: 8px;    /* Base × 1 */
14  --space-2x: 16px;   /* Base × 2 */
15  --space-3x: 24px;   /* Base × 3 */
16  --space-4x: 32px;   /* Base × 4 */
17  --space-5x: 40px;   /* Base × 5 */
18}
19
20/* Comparison Analysis */
21.comparison-table {
22  /* IBM Carbon: Best for complex enterprise tools */
23  /* Material Design: Best for multi-platform consistency */
24  /* Atlassian: Best for data-heavy interfaces */
25}

Choose Your Mathematical Foundation

Build your own grid system by choosing your base unit (4px or 8px) and scaling strategy (linear or mathematical progression). The 8px system works for most digital products and aligns with device pixel densities.

Copy

1:root {
2  /* Base unit selection - 8px recommended for digital products */
3  --base-unit: 8px;
4
5  /* Option A: Linear Progression (Material approach) */
6  --space-1: calc(var(--base-unit) * 1); /* 8px */
7  --space-2: calc(var(--base-unit) * 2); /* 16px */
8  --space-3: calc(var(--base-unit) * 3); /* 24px */
9  --space-4: calc(var(--base-unit) * 4); /* 32px */
10  --space-5: calc(var(--base-unit) * 5); /* 40px */
11
12  /* Option B: Mathematical Progression (IBM approach) */
13  --space-xs: var(--base-unit);                    /* 8px */
14  --space-sm: calc(var(--base-unit) * 2);          /* 16px */
15  --space-md: calc(var(--base-unit) * 4);          /* 32px */
16  --space-lg: calc(var(--base-unit) * 8);          /* 64px */
17  --space-xl: calc(var(--base-unit) * 16);         /* 128px */
18}
19
20/* Exercise: Build your spacing scale */
21.your-spacing-scale {
22  /* Token Name | Value | Use Case */
23  /* space-1    | 8px   | Micro spacing (icon to text) */
24  /* space-2    | 16px  | Small spacing (button padding) */
25  /* space-3    | 24px  | Medium spacing (between sections) */
26  /* space-4    | 32px  | Large spacing (page margins) */
27  /* space-5    | 40px  | Extra large spacing (hero sections) */
28}

Create Responsive Breakpoints

Define breakpoints based on content, not devices. Effective breakpoints focus on when your content needs to reflow, creating natural breaking points for different screen sizes.

Copy

1:root {
2  /* Content-based breakpoint system */
3  --breakpoint-sm: 576px;  /* Large phones */
4  --breakpoint-md: 768px;  /* Tablets */
5  --breakpoint-lg: 992px;  /* Small laptops */
6  --breakpoint-xl: 1200px; /* Large screens */
7  --breakpoint-xxl: 1400px; /* Extra large screens */
8
9  /* Grid column behavior at each breakpoint */
10  --columns-mobile: 4;
11  --columns-tablet: 8;
12  --columns-desktop: 12;
13  --columns-wide: 16;
14}
15
16/* Media query structure for consistent usage */
17@media (min-width: 576px) { /* sm breakpoint */ }
18@media (min-width: 768px) { /* md breakpoint */ }
19@media (min-width: 992px) { /* lg breakpoint */ }
20@media (min-width: 1200px) { /* xl breakpoint */ }
21
22/* Exercise: Define your custom breakpoints */
23.your-breakpoints {
24  /* Analyze your content's natural breaking points */
25  /* Mobile: ___ columns, Tablet: ___ columns */
26  /* Desktop: ___ columns, Wide: ___ columns */
27}

Build Your Complete Token System

Transform your grid decisions into implementable CSS custom properties. This creates a complete design token system that enforces consistency across your entire application.

Copy

1:root {
2  /* === SPACING TOKENS === */
3  --space-1: 8px;    /* Micro spacing (icon to text) */
4  --space-2: 16px;   /* Small spacing (button padding) */
5  --space-3: 24px;   /* Medium spacing (form groups) */
6  --space-4: 32px;   /* Large spacing (section margins) */
7  --space-5: 40px;   /* Extra large spacing (page margins) */
8  --space-6: 48px;   /* Hero sections */
9
10  /* === LAYOUT TOKENS === */
11  --container-sm: 540px;
12  --container-md: 720px;
13  --container-lg: 960px;
14  --container-xl: 1140px;
15  --container-xxl: 1320px;
16
17  /* === GRID TOKENS === */
18  --grid-columns: 12;
19  --grid-gutter: var(--space-3);
20  --grid-margin: var(--space-4);
21}
22
23/* Test your system with a simple component */
24.test-component {
25  padding: var(--space-3);
26  margin-bottom: var(--space-4);
27  border: 1px solid #ccc;
28}

Create Grid-Aware Components

Build components that reinforce your grid system. All component dimensions should use spacing tokens, align to grid increments, and maintain mathematical relationships for visual consistency.

Copy

1/* Button Component - Grid Aligned */
2.btn {
3  padding: var(--space-2) var(--space-3);
4  margin: var(--space-1) 0;
5  border-radius: var(--space-1);
6  font-size: var(--space-2);
7  line-height: 1.5;
8  border: none;
9  cursor: pointer;
10  display: inline-block;
11}
12
13.btn--large {
14  padding: var(--space-3) var(--space-4);
15  font-size: var(--space-3);
16}
17
18.btn--small {
19  padding: var(--space-1) var(--space-2);
20  font-size: calc(var(--space-2) * 0.875);
21}
22
23/* Card Component - Grid Aligned */
24.card {
25  padding: var(--space-4);
26  margin-bottom: var(--space-4);
27  border-radius: var(--space-1);
28  background: white;
29  box-shadow: 0 var(--space-1) var(--space-3) rgba(0, 0, 0, 0.1);
30  border: 1px solid #e5e5e5;
31}
32
33.card__header {
34  margin-bottom: var(--space-3);
35  padding-bottom: var(--space-2);
36  border-bottom: 1px solid #e5e5e5;
37}
38
39.card__title {
40  margin: 0 0 var(--space-1) 0;
41  font-size: var(--space-3);
42  line-height: 1.3;
43}
44
45.card__content {
46  margin-bottom: var(--space-3);
47}

Build Responsive Grid Layout System

Create a flexible grid system that adapts to your breakpoints. This CSS Grid-based approach provides modern layout capabilities while maintaining your mathematical foundations.

Copy

1/* Grid Container System */
2.grid {
3  display: grid;
4  gap: var(--grid-gutter);
5  margin: 0 var(--grid-margin);
6  grid-template-columns: repeat(var(--grid-columns), 1fr);
7  width: 100%;
8}
9
10/* Column span utilities */
11.col-1 { grid-column: span 1; }
12.col-2 { grid-column: span 2; }
13.col-3 { grid-column: span 3; }
14.col-4 { grid-column: span 4; }
15.col-6 { grid-column: span 6; }
16.col-8 { grid-column: span 8; }
17.col-12 { grid-column: span 12; }
18
19/* Responsive behavior */
20@media (max-width: 767px) {
21  .grid {
22    --grid-columns: 4;
23    --grid-margin: var(--space-2);
24    --grid-gutter: var(--space-2);
25  }
26
27  .col-sm-1 { grid-column: span 1; }
28  .col-sm-2 { grid-column: span 2; }
29  .col-sm-4 { grid-column: span 4; }
30}
31
32@media (min-width: 768px) and (max-width: 991px) {
33  .grid {
34    --grid-columns: 8;
35    --grid-gutter: var(--space-3);
36  }
37
38  .col-md-2 { grid-column: span 2; }
39  .col-md-4 { grid-column: span 4; }
40  .col-md-8 { grid-column: span 8; }
41}
42
43@media (min-width: 992px) {
44  .grid {
45    --grid-columns: 12;
46  }
47}

Form Component System with Grid Alignment

Create a complete form system that uses your grid tokens. Forms are often the most complex components, so getting them right demonstrates the power of your grid system.

Copy

1/* Form Components - Grid Aligned */
2.form {
3  max-width: var(--container-md);
4  margin: 0 auto;
5}
6
7.form-group {
8  margin-bottom: var(--space-4);
9}
10
11.form-label {
12  display: block;
13  margin-bottom: var(--space-1);
14  font-weight: 600;
15  font-size: var(--space-2);
16  color: #374151;
17}
18
19.form-input {
20  width: 100%;
21  padding: var(--space-2) var(--space-3);
22  border: 2px solid #e5e7eb;
23  border-radius: var(--space-1);
24  font-size: var(--space-2);
25  line-height: 1.5;
26  transition: border-color 0.15s ease-in-out;
27  box-sizing: border-box;
28}
29
30.form-input:focus {
31  outline: none;
32  border-color: #3b82f6;
33  box-shadow: 0 0 0 var(--space-1) rgba(59, 130, 246, 0.1);
34}
35
36.form-row {
37  display: grid;
38  gap: var(--space-3);
39  grid-template-columns: 1fr;
40}
41
42@media (min-width: 768px) {
43  .form-row {
44    grid-template-columns: 1fr 1fr;
45  }
46
47  .form-row--three {
48    grid-template-columns: 1fr 1fr 1fr;
49  }
50}
51
52.form-error {
53  color: #dc2626;
54  font-size: calc(var(--space-2) * 0.875);
55  margin-top: var(--space-1);
56}

Testing and Quality Assurance

Create a comprehensive test page to validate your grid system. This ensures visual consistency, mathematical relationships, and responsive behavior across all components.

Copy

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8">
5  <meta name="viewport" content="width=device-width, initial-scale=1.0">
6  <title>Grid System Test</title>
7  <link rel="stylesheet" href="grid-system.css">
8</head>
9<body>
10  <div class="grid">
11    <!-- Header Section -->
12    <header class="col-12">
13      <h1>Grid System Test Page</h1>
14      <nav style="display: flex; gap: var(--space-2);">
15        <button class="btn">Navigation</button>
16        <button class="btn">Items</button>
17        <button class="btn btn--large">Call to Action</button>
18      </nav>
19    </header>
20
21    <!-- Main Content -->
22    <main class="col-md-8 col-12">
23      <div class="card">
24        <div class="card__header">
25          <h2 class="card__title">Test Card Component</h2>
26        </div>
27        <div class="card__content">
28          <p>This card uses grid-aligned spacing tokens for consistent visual rhythm.</p>
29        </div>
30
31        <form class="form">
32          <div class="form-row">
33            <div class="form-group">
34              <label class="form-label">First Name</label>
35              <input type="text" class="form-input" placeholder="Enter first name">
36            </div>
37            <div class="form-group">
38              <label class="form-label">Last Name</label>
39              <input type="text" class="form-input" placeholder="Enter last name">
40            </div>
41          </div>
42          <div class="form-group">
43            <button class="btn btn--large">Submit Form</button>
44          </div>
45        </form>
46      </div>
47    </main>
48
49    <!-- Sidebar -->
50    <aside class="col-md-4 col-12">
51      <div class="card">
52        <h3 class="card__title">Sidebar Content</h3>
53        <div class="card__content">
54          <p>Secondary content with consistent spacing relationships.</p>
55          <button class="btn">Secondary Action</button>
56        </div>
57      </div>
58    </aside>
59  </div>
60</body>
61</html>

Documentation and Team Adoption

Create comprehensive documentation for your grid system. Include principles, token reference, usage guidelines, and a quality assurance checklist to ensure team adoption.

Copy

1// Design System Documentation Interface
2interface GridSystemDoc {
3  principles: {
4    baseUnit: string;
5    scalingMethod: 'linear' | 'mathematical';
6    breakpointStrategy: string;
7  };
8
9  tokens: {
10    spacing: Record<string, string>;
11    breakpoints: Record<string, string>;
12    layout: Record<string, string>;
13  };
14
15  usage: {
16    guidelines: string[];
17    bestPractices: string[];
18  };
19
20  qa: {
21    checklist: string[];
22  };
23}
24
25// Grid System Configuration
26export const gridSystem: GridSystemDoc = {
27  principles: {
28    baseUnit: '8px',
29    scalingMethod: 'linear',
30    breakpointStrategy: 'content-based'
31  },
32
33  tokens: {
34    spacing: {
35      'space-1': '8px',   // Micro spacing (icon to text)
36      'space-2': '16px',  // Small spacing (button padding)
37      'space-3': '24px',  // Medium spacing (form groups)
38      'space-4': '32px',  // Large spacing (section margins)
39      'space-5': '40px',  // Extra large spacing (page margins)
40    },
41    breakpoints: {
42      'sm': '576px',   // Large phones
43      'md': '768px',   // Tablets
44      'lg': '992px',   // Small laptops
45      'xl': '1200px'   // Large screens
46    },
47    layout: {
48      'container-sm': '540px',
49      'container-md': '720px',
50      'container-lg': '960px',
51      'container-xl': '1140px'
52    }
53  },
54
55  usage: {
56    guidelines: [
57      'Always use spacing tokens for margins and padding',
58      'Components must align to grid increments',
59      'Test responsive behavior at all breakpoints'
60    ],
61    bestPractices: [
62      'Start with mathematical foundation',
63      'Create components that reinforce the system',
64      'Document decisions and usage patterns'
65    ]
66  },
67
68  qa: {
69    checklist: [
70      'All spacing uses defined tokens (no arbitrary values)',
71      'Component aligns to grid increments',
72      'Responsive behavior maintains grid relationships',
73      'Documentation explains spacing choices',
74      'Tested across all breakpoints'
75    ]
76  }
77};

Advanced Grid Utilities and Helpers

Build utility classes and helper functions that make your grid system easy to use in development. These utilities provide shortcuts for common patterns while maintaining grid compliance.

Copy

1/* Spacing Utility Classes */
2.p-1 { padding: var(--space-1); }
3.p-2 { padding: var(--space-2); }
4.p-3 { padding: var(--space-3); }
5.p-4 { padding: var(--space-4); }
6.p-5 { padding: var(--space-5); }
7
8.m-1 { margin: var(--space-1); }
9.m-2 { margin: var(--space-2); }
10.m-3 { margin: var(--space-3); }
11.m-4 { margin: var(--space-4); }
12.m-5 { margin: var(--space-5); }
13
14/* Directional spacing utilities */
15.pt-2 { padding-top: var(--space-2); }
16.pr-2 { padding-right: var(--space-2); }
17.pb-2 { padding-bottom: var(--space-2); }
18.pl-2 { padding-left: var(--space-2); }
19
20.mt-4 { margin-top: var(--space-4); }
21.mr-4 { margin-right: var(--space-4); }
22.mb-4 { margin-bottom: var(--space-4); }
23.ml-4 { margin-left: var(--space-4); }
24
25/* Layout composition utilities */
26.container {
27  max-width: var(--container-xl);
28  margin: 0 auto;
29  padding: 0 var(--space-3);
30}
31
32/* Stack layout - vertical rhythm */
33.stack > * + * {
34  margin-top: var(--space-3);
35}
36
37.stack--small > * + * {
38  margin-top: var(--space-2);
39}
40
41.stack--large > * + * {
42  margin-top: var(--space-4);
43}
44
45/* Cluster layout - horizontal grouping */
46.cluster {
47  display: flex;
48  flex-wrap: wrap;
49  gap: var(--space-2);
50  align-items: center;
51}
52
53/* Center layout */
54.center {
55  display: flex;
56  flex-direction: column;
57  align-items: center;
58  justify-content: center;
59  text-align: center;
60}

Integration with Modern CSS Features

Enhance your grid system with modern CSS features like Container Queries and CSS Subgrid. These features provide powerful layout capabilities while maintaining your mathematical foundation.

Copy

1/* Container Queries for Component-Based Responsive Design */
2.card {
3  container-type: inline-size;
4  padding: var(--space-3);
5}
6
7@container (min-width: 300px) {
8  .card {
9    padding: var(--space-4);
10  }
11
12  .card__title {
13    font-size: var(--space-4);
14  }
15}
16
17@container (min-width: 500px) {
18  .card {
19    display: grid;
20    grid-template-columns: 1fr 2fr;
21    gap: var(--space-4);
22    padding: var(--space-5);
23  }
24}
25
26/* CSS Subgrid for Nested Grid Alignment */
27.nested-grid {
28  display: grid;
29  grid-template-columns: subgrid;
30  grid-column: span 6;
31  gap: var(--space-2);
32}
33
34.nested-grid-item {
35  padding: var(--space-2);
36}
37
38/* Logical Properties for Internationalization */
39.content {
40  padding-inline: var(--space-4);
41  padding-block: var(--space-3);
42  margin-block-end: var(--space-4);
43  border-inline-start: var(--space-1) solid #e5e7eb;
44}
45
46/* CSS Grid Template Areas for Semantic Layouts */
47.page-layout {
48  display: grid;
49  grid-template-areas:
50    "header header"
51    "sidebar main"
52    "footer footer";
53  grid-template-columns: 1fr 3fr;
54  gap: var(--space-4);
55  min-height: 100vh;
56}
57
58.header { grid-area: header; }
59.sidebar { grid-area: sidebar; }
60.main { grid-area: main; }
61.footer { grid-area: footer; }
62
63@media (max-width: 768px) {
64  .page-layout {
65    grid-template-areas:
66      "header"
67      "main"
68      "sidebar"
69      "footer";
70    grid-template-columns: 1fr;
71  }
72}