Design Systems

1. 1
   Primitive tokens

   The raw palette and scales: every colour, every space step, every radius, every type size, each with a name and no opinion about use.

   fails by Consumed directly by components, which couples the component to a specific colour rather than to a role, and makes re-theming impossible (Design Tokens).

2. 2
   Semantic tokens

   Roles rather than values: surface, text-on-surface, border-subtle, danger, focus-ring. This is the layer a theme swaps.

   fails by Missing entirely, so there is nothing to re-point at a new palette and every theme is a fork.

3. 3
   Components

   Interactive primitives with real semantics, keyboard behaviour, focus handling and announcement, consuming only semantic tokens (Accessible Component Patterns).

   fails by Built as styled div elements, industrialising one accessibility defect across every product that adopts it.

4. 4
   Patterns

   Recurring compositions: form layout with error placement, destructive confirmation, empty state, data table with sorting and pagination.

   fails by Left out, so five teams each invent a different confirmation flow and the product is consistent at the button and incoherent at the task.

5. 5
   Applications

   Compose patterns, own page-level structure: headings, landmarks, routing, focus on navigation, and the words (Document Structure and Reading Order).

   fails by Forking a component to change one detail, which permanently disconnects that screen from every future fix.

6. 6
   Release

   Versioned publish with a changelog, migration notes and codemods for mechanical breaking changes.

   fails by Breaking changes shipped as patches, which teaches every consumer to pin and ends upgrades (Versioning: What a Version Even Promises in API Design).

Read the failure column as the design system's actual risk register. Each one is recoverable early and close to permanent once four products depend on it.

1// Leaks its internals: every consumer can depend on the DOM,
2// so every internal change is a breaking change.
3export function Button(props: { className?: string; onClick?: () => void; children: React.ReactNode }) {
4  return (
5    <div className={`ds-btn ${props.className ?? ''}`} onClick={props.onClick} role="button">
6      <span className="ds-btn__inner">{props.children}</span>
7    </div>
8  )
9}
10// consumer, now permanent:  .ds-btn__inner { padding: 0 }
11 
12// Names its contract, hides its structure.
13export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
14  /** what the button is for, not what it looks like */
15  variant?: 'primary' | 'secondary' | 'danger'
16  /** the only supported way to render an icon alongside the label */
17  icon?: React.ReactNode
18}
19 
20export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
21  function Button({ variant = 'secondary', icon, children, ...rest }, ref) {
22    // real element: type, keyboard activation, focus, disabled, form
23    // participation and the accessibility role all come from the platform
24    return (
25      <button ref={ref} type="button" data-variant={variant} {...rest}>
26        {icon}
27        {children}
28      </button>
29    )
30  },
31)

The second version exposes a variant role rather than a colour, forwards a ref because consumers legitimately need the node, spreads native attributes so aria-*, form and disabled work without the library enumerating them — and renders a real button, which is where the keyboard behaviour and the accessibility role come from at no cost.