| name | frontend-patterns |
| description | CSS design system principles — token usage, semantic layering, mobile-first, component isolation. |
| when_to_use | Working on CSS, styling, design tokens, or frontend component structure. |
| user-invocable | false |
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.
:root { --color-primary: #5b5956; }
.button { background: var(--color-primary); }
.button { background: #5b5956; }
For JavaScript/SDK integrations, read tokens at runtime:
const primary = getComputedStyle(document.documentElement)
.getPropertyValue('--color-primary').trim();
SDK.configure({ buttonColor: primary });
SDK.configure({ buttonColor: '#5b5956' });
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); }
.card { padding: 32px; border-radius: 12px; }
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.
:root { --color-charcoal: #5b5956; }
:root { --color-primary: var(--color-charcoal); }
.button { background: var(--color-primary); }
.button { background: var(--color-charcoal); }
4. Separation of Concerns
CSS owns presentation. Never use inline styles. State changes toggle CSS classes, not inline styles.
.card.selected { border-color: var(--color-accent); }
Exception: JavaScript-calculated values unknown at build time.
5. Design Token Propagation
External integrations (third-party SDKs, embedded widgets) must read design tokens at runtime, not hardcode values. This keeps the design system as the single source of truth even across integration boundaries.
6. Component Isolation with Global Consistency
Components control their own structure (layout, flex, grid) but get their design values (colors, spacing, radii) from global tokens. Don't redefine token values inside components. Don't reach into child components with global selectors.
7. Mobile-First Progressive Enhancement
Base styles target mobile. Enhance upward with min-width media queries. Never use max-width.
.grid { grid-template-columns: 1fr; }
@media (min-width: 768px) {
.grid { grid-template-columns: repeat(2, 1fr); }
}
Desktop-first (max-width) leads to undoing styles at smaller sizes — harder to maintain and reason about.
8. Explicit Over Implicit
Be clear about sizing, positioning, and state.
.container { max-width: var(--max-width); margin: 0 auto; }
.container { width: 90%; }
.modal { position: fixed; top: 50%; left: 50%; }
.modal { position: absolute; }
9. Consistency Over Cleverness
Prefer boring, predictable patterns over novel solutions. When solving similar problems, use the same approach. Before creating a new pattern, check if an existing one can be adapted.
<div class="card"><h3 class="card-title">...</h3></div>
<div class="service-box"><h3 class="service-heading">...</h3></div>
<div class="product-container"><h3 class="product-name">...</h3></div>