Design Principles

These principles guide how we build interfaces at Frequency. They apply to dashboards, tools, and product UI — not marketing pages.

Core Principles

Surface & Depth

Professional interfaces separate themselves from amateur ones in how they handle surfaces. Study Vercel, Linear, Supabase — their elevation changes are so subtle you almost can’t see them, but you feel the hierarchy.

Surface Elevation

Surfaces stack. A dropdown sits above a card which sits above the page. Build a numbered system:

In dark mode: higher elevation = slightly lighter. In light mode: higher elevation = slightly lighter or uses shadow.

The difference between levels should be whisper-quiet — a few percentage points of lightness, not dramatic jumps.

Depth Strategy

Choose one approach and commit across the product:

Don’t mix strategies. A product with shadow cards and bordered tables feels inconsistent.

/* Borders-only */
border: 0.5px solid rgba(0, 0, 0, 0.08);
 
/* Subtle shadow */
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
 
/* Layered shadow */
box-shadow:
  0 0 0 0.5px rgba(0, 0, 0, 0.05),
  0 1px 2px rgba(0, 0, 0, 0.04),
  0 2px 4px rgba(0, 0, 0, 0.03),
  0 4px 8px rgba(0, 0, 0, 0.02);

Borders

Borders should define regions without demanding attention. They should disappear when you’re not looking for them, but be findable when you need to understand structure.

• If borders are the first thing you notice, they’re too strong
• If you can’t tell where regions begin and end, they’re too subtle
• Use low opacity (0.05–0.12 alpha in dark mode, slightly higher in light)

Spacing System

Use an 8px base unit. Every spacing value is a multiple. Random values signal no system.

Padding Rules

Keep padding symmetrical. If top is 16px, sides and bottom are 16px too — unless there’s a clear structural reason.

/* Good */
padding: 16px;
padding: 12px 16px; /* Only when horizontal needs more room */
 
/* Bad — random values signal no system */
padding: 24px 16px 12px 16px;

Typography Hierarchy

Type is not a container — it IS the design. The weight of a headline, the personality of a label, the texture of a paragraph shape how the product feels before anyone reads a word.

Four Levels of Text

Don’t just have “text” and “gray text.” Use all four consistently:

Type Pairing

Headlines need weight and tight tracking to feel authoritative. Body needs comfortable weight for sustained reading. Data needs monospace with font-variant-numeric: tabular-nums for column alignment.

Color Usage

Gray builds structure. Color communicates. Unmotivated color is noise.

Color Primitives

Every color in the interface should trace back to these primitives:

Don’t invent new colors. Map everything to these primitives. No random hex values — everything traces to the system.

One Accent, Used with Intention

One accent color used purposefully beats five colors used without thought. Frequency Blue (#169BDE) is the primary accent. Violet (#7E57C2) is secondary. Use semantic colors only for their intended meaning.

Interaction States

Every interactive element needs states. Missing states feel broken.

Controls

Data States

Form Controls

Native <select> and <input type="date"> cannot be styled consistently. Build custom components using Mantine’s primitives instead. Every input needs: label above (not placeholder-as-label), visible error state, and helpful error messages.

Animation

Keep it fast and functional. Animation should guide attention, not perform.

• No spring or bounce effects in product UI — they feel playful, not professional
• Always respect prefers-reduced-motion
• If you can’t explain what the animation communicates, remove it

Dark Mode

Dark interfaces have different needs. Same hierarchy, different execution.

Z-Index Scale

Responsive Design

Design mobile-first, then enhance for larger screens:

The Craft Checklist

Before shipping any interface, run these checks:

• The squint test: Blur your eyes at the interface. Can you still perceive hierarchy? Is anything jumping out harshly? Craft whispers.
• The swap test: If you swapped the typeface or layout for a generic alternative, would anyone notice? Where it wouldn’t matter is where you defaulted.
• The state test: Does every interactive element have hover, focus, active, and disabled states? Does data have loading, empty, and error states?
• The token test: Read your CSS variables out loud. Do they trace back to the system? No random hex values?
• The consistency test: Is spacing, padding, border radius, and depth strategy uniform across the entire interface?