Design System Cheat Sheet

How to use this Design System cheat sheet

Design tokens store color, spacing, typography, and elevation as platform-agnostic variables consumed by CSS, iOS, and Android. Components compose tokens into buttons, inputs, and modals with documented props, states, and usage guidelines.

Semantic versioning communicates breaking API changes. Storybook or similar docs sites show live examples. An a11y checklist—focus order, contrast, labels, keyboard support—is part of definition of done for every component.

Quick Design System example

:root {
  --color-text-primary: #1a1a1a;
  --color-bg-surface: #ffffff;
  --space-md: 16px;
  --font-body: system-ui, sans-serif;
  --radius-md: 8px;
}

.ds-button {
  padding: var(--space-md);
  font-family: var(--font-body);
  border-radius: var(--radius-md);
  background: var(--color-brand-500);
  color: var(--color-text-on-brand);
}

Design Tokens

Components & API

Theming & Versioning

Documentation & A11y Checklist

Token JSON for Style Dictionary

{
  "color": {
    "brand": { "500": { "value": "#2563eb" } },
    "text": { "primary": { "value": "{color.neutral.900}" } }
  },
  "space": { "md": { "value": "16px" } }
}

Style Dictionary compiles tokens to CSS, SCSS, iOS, and Android outputs.

Component with variant API (React)

type ButtonProps = {
  variant?: 'primary' | 'ghost';
  size?: 'sm' | 'md';
  disabled?: boolean;
  children: React.ReactNode;
};

export function Button({ variant = 'primary', size = 'md', ...props }: ButtonProps) {
  return <button className={cn(styles.base, styles[variant], styles[size])} {...props} />;
}

Limit variant combinations—document supported matrix in Storybook.

A11y smoke test in Storybook

import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

it('Button has no a11y violations', async () => {
  const { container } = render(<Button>Save</Button>);
  expect(await axe(container)).toHaveNoViolations();
});

Run axe in CI for each component story baseline.

Common mistakes

• Publishing components without documented props, states, and accessibility behavior.
• Hard-coding hex values in products instead of consuming semantic tokens.
• Breaking changes in patch releases, eroding consumer trust.
• Shipping icon-only controls without accessible names.

Key takeaways

• Tokens separate raw values from semantic meaning for theming.
• Components expose small, documented variant APIs with forward refs.
• Semver and changelogs govern adoption across multiple product teams.
• Docs and a11y checks are part of the component, not an afterthought.