frontend-patterns

Frontend Design Principles

Core principles for maintaining consistent, maintainable frontend code. Framework-agnostic -- adapt examples to your stack.

1. Single Source of Truth

Every design decision is defined exactly once. Design tokens live in the styles system. Components reference them, never redefine them.

/* Token file */
:root { --color-primary: #5b5956; }

/* Component */
.button { background: var(--color-primary); }  /* yes */
.button { background: #5b5956; }               /* no */

For JavaScript/SDK integrations, read tokens at runtime:

const primary = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-primary').trim();
SDK.configure({ buttonColor: primary });  /* yes */
SDK.configure({ buttonColor: '#5b5956' }); /* no */

2. Variable-First Development

If it's a design value, it's a variable. Colors, spacing, fonts, shadows, radii, and breakpoints are always variables -- even if used once.

.card { padding: var(--space-xl); border-radius: var(--radius-lg); }     /* yes */
.card { padding: 32px; border-radius: 12px; }                            /* no */

Every referenced variable must exist in the token files. Undefined variables fall back to browser defaults silently.

Exceptions: 0, single-pixel borders (1px), proportional values (100%), one-off transforms.

3. Semantic Layering

Base tokens -> Semantic tokens -> Component usage. Define primitives, map to purposes, use purposes in components.

/* Layer 1: Base primitives */
:root { --color-charcoal: #5b5956; }

/* Layer 2: Semantic purpose */
:root { --color-primary: var(--color-charcoal); }

/* Layer 3: Component usage */
.button { background: var(--color-primary); }     /* yes -- semantic */
.button { background: var(--color-charcoal); }    /* no -- base primitive */

4. Separation of Concerns

CSS owns presentation. Never use inline styles. State changes toggle CSS classes, not inline styles.

/* yes -- class-driven state */
.card.selected { border-color: var(--color-accent); }

/* no -- inline style state */
/* style={selected ? 'border: 2px solid blue;' : ''} */