Atomic Design: Quarks

Master the creation and organization of quarks - the sub-atomic design tokens and primitive values that form the foundation of your design system. Quarks are the smallest building blocks that atoms consume.

What Are Quarks?

Quarks extend Brad Frost's Atomic Design methodology by adding a level below atoms. While atoms are the smallest UI components, quarks are the smallest design values - the raw materials from which atoms are built.

Quarks are:

• Primitive Values: Colors, spacing units, font sizes, shadows

• Non-Visual: They don't render anything on their own

• Design Tokens: Named constants that define your design language

• Consumed by Atoms: Atoms import and use quarks for styling

Quarks vs Atoms

Aspect Quarks Atoms

Nature Values/Tokens UI Components

Render Nothing (CSS variables, constants) Visual elements

Examples --color-primary-500 , spacing.md

Button, Input, Label

Imports None (base level) Quarks only

Purpose Define design language Implement design language

Common Quark Types

Color Tokens

// quarks/colors.ts export const colors = { // Brand colors primary: { 50: '#e3f2fd', 100: '#bbdefb', 200: '#90caf9', 300: '#64b5f6', 400: '#42a5f5', 500: '#2196f3', // Primary 600: '#1e88e5', 700: '#1976d2', 800: '#1565c0', 900: '#0d47a1', },

// Semantic colors success: { light: '#4caf50', main: '#2e7d32', dark: '#1b5e20', }, warning: { light: '#ff9800', main: '#ed6c02', dark: '#e65100', }, danger: { light: '#ef5350', main: '#d32f2f', dark: '#c62828', },

// Neutral colors neutral: { 0: '#ffffff', 50: '#fafafa', 100: '#f5f5f5', 200: '#eeeeee', 300: '#e0e0e0', 400: '#bdbdbd', 500: '#9e9e9e', 600: '#757575', 700: '#616161', 800: '#424242', 900: '#212121', }, } as const;

export type ColorScale = keyof typeof colors; export type PrimaryShade = keyof typeof colors.primary;

Spacing Tokens

// quarks/spacing.ts export const spacing = { px: '1px', 0: '0', 0.5: '0.125rem', // 2px 1: '0.25rem', // 4px 1.5: '0.375rem', // 6px 2: '0.5rem', // 8px 2.5: '0.625rem', // 10px 3: '0.75rem', // 12px 3.5: '0.875rem', // 14px 4: '1rem', // 16px 5: '1.25rem', // 20px 6: '1.5rem', // 24px 7: '1.75rem', // 28px 8: '2rem', // 32px 9: '2.25rem', // 36px 10: '2.5rem', // 40px 12: '3rem', // 48px 14: '3.5rem', // 56px 16: '4rem', // 64px 20: '5rem', // 80px 24: '6rem', // 96px } as const;

// Semantic spacing aliases export const spacingAliases = { none: spacing[0], xs: spacing[1], sm: spacing[2], md: spacing[4], lg: spacing[6], xl: spacing[8], '2xl': spacing[12], '3xl': spacing[16], } as const;

Typography Tokens

// quarks/typography.ts export const fontFamily = { sans: [ 'Inter', 'ui-sans-serif', 'system-ui', '-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'sans-serif', ].join(', '), serif: [ 'Georgia', 'Cambria', 'Times New Roman', 'Times', 'serif', ].join(', '), mono: [ 'Fira Code', 'ui-monospace', 'SFMono-Regular', 'Menlo', 'Monaco', 'Consolas', 'monospace', ].join(', '), } as const;

export const fontSize = { xs: '0.75rem', // 12px sm: '0.875rem', // 14px base: '1rem', // 16px lg: '1.125rem', // 18px xl: '1.25rem', // 20px '2xl': '1.5rem', // 24px '3xl': '1.875rem', // 30px '4xl': '2.25rem', // 36px '5xl': '3rem', // 48px '6xl': '3.75rem', // 60px } as const;

export const fontWeight = { thin: 100, extralight: 200, light: 300, normal: 400, medium: 500, semibold: 600, bold: 700, extrabold: 800, black: 900, } as const;

export const lineHeight = { none: 1, tight: 1.25, snug: 1.375, normal: 1.5, relaxed: 1.625, loose: 2, } as const;

export const letterSpacing = { tighter: '-0.05em', tight: '-0.025em', normal: '0em', wide: '0.025em', wider: '0.05em', widest: '0.1em', } as const;

Border Tokens

// quarks/borders.ts export const borderRadius = { none: '0', sm: '0.125rem', // 2px DEFAULT: '0.25rem', // 4px md: '0.375rem', // 6px lg: '0.5rem', // 8px xl: '0.75rem', // 12px '2xl': '1rem', // 16px '3xl': '1.5rem', // 24px full: '9999px', } as const;

export const borderWidth = { DEFAULT: '1px', 0: '0', 2: '2px', 4: '4px', 8: '8px', } as const;

Shadow Tokens

// quarks/shadows.ts export const shadows = { none: 'none', sm: '0 1px 2px 0 rgb(0 0 0 / 0.05)', DEFAULT: '0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)', md: '0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)', lg: '0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)', xl: '0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)', '2xl': '0 25px 50px -12px rgb(0 0 0 / 0.25)', inner: 'inset 0 2px 4px 0 rgb(0 0 0 / 0.05)', } as const;

// Focus ring shadows export const focusRings = { primary: '0 0 0 3px rgba(33, 150, 243, 0.4)', danger: '0 0 0 3px rgba(239, 83, 80, 0.4)', success: '0 0 0 3px rgba(76, 175, 80, 0.4)', } as const;

Animation Tokens

// quarks/animations.ts export const duration = { instant: '0ms', fast: '100ms', normal: '200ms', slow: '300ms', slower: '500ms', } as const;

export const easing = { linear: 'linear', in: 'cubic-bezier(0.4, 0, 1, 1)', out: 'cubic-bezier(0, 0, 0.2, 1)', inOut: 'cubic-bezier(0.4, 0, 0.2, 1)', bounce: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)', } as const;

export const transitions = { none: 'none', all: all ${duration.normal} ${easing.inOut}, colors: background-color, border-color, color, fill, stroke ${duration.normal} ${easing.inOut}, opacity: opacity ${duration.normal} ${easing.inOut}, shadow: box-shadow ${duration.normal} ${easing.inOut}, transform: transform ${duration.normal} ${easing.inOut}, } as const;

Breakpoint Tokens

// quarks/breakpoints.ts export const breakpoints = { xs: '320px', sm: '640px', md: '768px', lg: '1024px', xl: '1280px', '2xl': '1536px', } as const;

// Media query helpers export const mediaQueries = { xs: @media (min-width: ${breakpoints.xs}), sm: @media (min-width: ${breakpoints.sm}), md: @media (min-width: ${breakpoints.md}), lg: @media (min-width: ${breakpoints.lg}), xl: @media (min-width: ${breakpoints.xl}), '2xl': @media (min-width: ${breakpoints['2xl']}), } as const;

Z-Index Tokens

// quarks/z-index.ts export const zIndex = { hide: -1, base: 0, raised: 1, dropdown: 1000, sticky: 1100, fixed: 1200, overlay: 1300, modal: 1400, popover: 1500, tooltip: 1600, toast: 1700, } as const;

CSS Custom Properties

Export quarks as CSS custom properties for runtime theming.

// quarks/css-variables.ts import { colors, spacing, fontSize, fontFamily } from './index';

export function generateCSSVariables(): string { const lines: string[] = [':root {'];

// Colors Object.entries(colors).forEach(([category, shades]) => { if (typeof shades === 'object') { Object.entries(shades).forEach(([shade, value]) => { lines.push( --color-${category}-${shade}: ${value};); }); } });

// Spacing Object.entries(spacing).forEach(([key, value]) => { const sanitizedKey = key.replace('.', '_'); lines.push( --spacing-${sanitizedKey}: ${value};); });

// Typography Object.entries(fontSize).forEach(([key, value]) => { lines.push( --font-size-${key}: ${value};); });

Object.entries(fontFamily).forEach(([key, value]) => { lines.push( --font-family-${key}: ${value};); });

lines.push('}'); return lines.join('\n'); }

Generated CSS

/* quarks/variables.css - Generated output / :root { / Colors - Primary */ --color-primary-50: #e3f2fd; --color-primary-100: #bbdefb; --color-primary-500: #2196f3; --color-primary-900: #0d47a1;

/* Colors - Neutral */ --color-neutral-0: #ffffff; --color-neutral-100: #f5f5f5; --color-neutral-900: #212121;

/* Spacing */ --spacing-0: 0; --spacing-1: 0.25rem; --spacing-2: 0.5rem; --spacing-4: 1rem; --spacing-8: 2rem;

/* Typography */ --font-size-xs: 0.75rem; --font-size-sm: 0.875rem; --font-size-base: 1rem; --font-size-lg: 1.125rem;

--font-family-sans: Inter, ui-sans-serif, system-ui, sans-serif; --font-family-mono: Fira Code, ui-monospace, monospace;

/* Borders */ --border-radius-sm: 0.125rem; --border-radius-md: 0.375rem; --border-radius-lg: 0.5rem; --border-radius-full: 9999px;

/* Shadows */ --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05); --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1); --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);

/* Transitions */ --duration-fast: 100ms; --duration-normal: 200ms; --duration-slow: 300ms; --easing-in-out: cubic-bezier(0.4, 0, 0.2, 1); }

Directory Structure

Recommended Structure

src/ quarks/ # Design tokens index.ts # Barrel export colors.ts spacing.ts typography.ts borders.ts shadows.ts animations.ts breakpoints.ts z-index.ts css-variables.ts # CSS custom property generator variables.css # Generated CSS file components/ atoms/ # Atoms that consume quarks Button/ Input/ molecules/ organisms/ templates/ pages/

Index Barrel Export

// quarks/index.ts export * from './colors'; export * from './spacing'; export * from './typography'; export * from './borders'; export * from './shadows'; export * from './animations'; export * from './breakpoints'; export * from './z-index';

Using Quarks in Atoms

CSS-in-JS (styled-components/emotion)

// atoms/Button/Button.tsx import styled from 'styled-components'; import { colors, spacing, fontSize, borderRadius, transitions } from '@/quarks';

export const Button = styled.button<{ variant?: 'primary' | 'secondary' }>` padding: ${spacing[2]} ${spacing[4]}; font-size: ${fontSize.base}; border-radius: ${borderRadius.md}; transition: ${transitions.colors};

${({ variant = 'primary' }) => variant === 'primary' ? ` background-color: ${colors.primary[500]}; color: ${colors.neutral[0]};

    &:hover {
      background-color: ${colors.primary[600]};
    }
  `
  : `
    background-color: transparent;
    color: ${colors.primary[500]};
    border: 1px solid ${colors.primary[500]};

    &:hover {
      background-color: ${colors.primary[50]};
    }
  `}

`;

CSS Modules with Variables

// atoms/Button/Button.tsx import styles from './Button.module.css';

export const Button = ({ variant = 'primary', children }) => ( <button className={${styles.button} ${styles[variant]}}> {children} </button> );

/* atoms/Button/Button.module.css */ .button { padding: var(--spacing-2) var(--spacing-4); font-size: var(--font-size-base); border-radius: var(--border-radius-md); transition: var(--duration-normal) var(--easing-in-out); }

.primary { background-color: var(--color-primary-500); color: var(--color-neutral-0); }

.primary:hover { background-color: var(--color-primary-600); }

.secondary { background-color: transparent; color: var(--color-primary-500); border: 1px solid var(--color-primary-500); }

Tailwind CSS Integration

// tailwind.config.js const { colors, spacing, fontSize, borderRadius } = require('./src/quarks');

module.exports = { theme: { colors, spacing, fontSize, borderRadius, }, };

Theming with Quarks

Dark Mode Support

// quarks/themes.ts import { colors } from './colors';

export const lightTheme = { background: colors.neutral[0], foreground: colors.neutral[900], muted: colors.neutral[100], mutedForeground: colors.neutral[500], primary: colors.primary[500], primaryForeground: colors.neutral[0], };

export const darkTheme = { background: colors.neutral[900], foreground: colors.neutral[0], muted: colors.neutral[800], mutedForeground: colors.neutral[400], primary: colors.primary[400], primaryForeground: colors.neutral[900], };

export type Theme = typeof lightTheme;

CSS Variables for Theming

/* quarks/theme-light.css */ :root { --background: var(--color-neutral-0); --foreground: var(--color-neutral-900); --muted: var(--color-neutral-100); --primary: var(--color-primary-500); }

/* quarks/theme-dark.css */ [data-theme="dark"] { --background: var(--color-neutral-900); --foreground: var(--color-neutral-0); --muted: var(--color-neutral-800); --primary: var(--color-primary-400); }

Best Practices

1. Use Semantic Names

// GOOD: Semantic naming export const colors = { primary: { ... }, danger: { ... }, success: { ... }, };

// BAD: Raw color names export const colors = { blue: { ... }, red: { ... }, green: { ... }, };

2. Consistent Scales

// GOOD: Consistent scale pattern export const colors = { primary: { 50, 100, 200, 300, 400, 500, 600, 700, 800, 900 }, secondary: { 50, 100, 200, 300, 400, 500, 600, 700, 800, 900 }, };

// BAD: Inconsistent scales export const colors = { primary: { light, medium, dark }, secondary: { 100, 500, 900 }, };

3. Type Safety

// GOOD: Type-safe tokens export const spacing = { ... } as const; export type SpacingKey = keyof typeof spacing;

function getSpacing(key: SpacingKey): string { return spacing[key]; }

// BAD: Untyped strings function getSpacing(key: string): string { return spacing[key]; // No type checking }

4. Single Source of Truth

// GOOD: Quarks as the only source // All components import from quarks import { colors } from '@/quarks';

// BAD: Duplicate values const Button = styled.button color: #2196f3; // Hardcoded, not from quarks!;

5. Documentation

// GOOD: Document your tokens /**

• Primary color scale
• Use 500 for default primary actions
• Use 600+ for hover/active states
• Use 100-400 for backgrounds/accents */ export const primary = { ... };

Anti-Patterns to Avoid

1. Quarks with Logic

// BAD: Quarks should be pure values export const getColor = (isDark: boolean) => isDark ? '#ffffff' : '#000000';

// GOOD: Pure values, logic in components/themes export const colors = { light: { text: '#000000' }, dark: { text: '#ffffff' }, };

2. Component-Specific Tokens

// BAD: Token for specific component export const buttonPrimaryBackground = '#2196f3';

// GOOD: Generic semantic tokens export const colors = { primary: { 500: '#2196f3' }, };

3. Too Many Tokens

// BAD: Token for every possible value export const spacing = { 1: '1px', 2: '2px', 3: '3px', 4: '4px', 5: '5px', // ... 100 more values };

// GOOD: Deliberate, usable scale export const spacing = { 1: '0.25rem', 2: '0.5rem', 4: '1rem', 6: '1.5rem', 8: '2rem', };

When to Use This Skill

• Setting up design tokens for a new design system

• Organizing existing CSS variables into a structured system

• Creating theme-able component libraries

• Ensuring consistency across a large codebase

• Building white-label or multi-brand applications

• Migrating from hardcoded values to design tokens

Related Skills

• atomic-design-fundamentals

• Core methodology overview

• atomic-design-atoms

• Creating atomic components that consume quarks

• atomic-design-integration

• Framework-specific implementation patterns

Resources

Documentation

• Design Tokens W3C Community Group: https://www.w3.org/community/design-tokens/

• Style Dictionary: https://amzn.github.io/style-dictionary/

• Tokens Studio: https://tokens.studio/

Tools

• Figma Tokens: https://www.figma.com/community/plugin/843461159747178978

• Style Dictionary: https://amzn.github.io/style-dictionary/

• Theme UI: https://theme-ui.com/