Jartan-LLC 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;' : ''} */
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; } /* mobile */
@media (min-width: 768px) {
.grid { grid-template-columns: repeat(2, 1fr); } /* desktop */
}
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; } /* yes -- explicit */
.container { width: 90%; } /* no -- 90% of what? */
.modal { position: fixed; top: 50%; left: 50%; } /* yes -- explicit */
.modal { position: absolute; } /* no -- relative to what? */
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.
<!-- yes -- consistent pattern for all cards -->
<div class="card"><h3 class="card-title">...</h3></div>
<!-- no -- different naming for each similar component -->
<div class="service-box"><h3 class="service-heading">...</h3></div>
<div class="product-container"><h3 class="product-name">...</h3></div>