Design Guide
Core Philosophy
Apply modern, minimal design principles focused on clarity, consistency, and professionalism. Every UI element should serve a purpose, with intentional use of space, color, and typography.
Design Principles
1. Clean and Minimal Layout
Whitespace is essential
- Use generous padding and margins
- Avoid cluttered interfaces
- Group related elements with clear visual separation
- Remove unnecessary decorative elements
Visual hierarchy
- Establish clear content priority through size and spacing
- Use whitespace to guide attention
- Limit elements per section (3-7 items optimal)
2. Color System
Base palette
- Primary background: Off-white (#FAFAFA, #F5F5F5) or pure white (#FFFFFF)
- Text colors:
- Primary: Dark gray (#1A1A1A, #2D2D2D)
- Secondary: Medium gray (#6B6B6B, #737373)
- Tertiary: Light gray (#A0A0A0, #B3B3B3)
- Borders and dividers: Very light gray (#E5E5E5, #EBEBEB)
Accent color
- Choose ONE accent color for the entire interface
- Use sparingly for CTAs, links, and important interactive elements
- Recommended: Teal (#0D9488), Emerald (#059669), Indigo (#4F46E5), or custom brand color
- Apply to: Primary buttons, active states, key icons
Forbidden patterns
- No purple-blue gradients
- No rainbow or multi-color gradients
- No more than 3 colors total (base grays + one accent)
- No bright, saturated colors for large areas
3. Spacing System (8px Grid)
Consistent spacing units
- 8px: Compact spacing (icon padding, tight elements)
- 16px: Default spacing (between related elements, button padding)
- 24px: Medium spacing (section padding, card content)
- 32px: Large spacing (between sections)
- 48px: XL spacing (major section breaks)
- 64px: XXL spacing (page sections, hero spacing)
Application
- All margins, padding, gaps use these values exclusively
- Component dimensions follow 8px increments when possible
- Line heights: 1.5 for body, 1.2 for headings
4. Typography
Font selection
- Maximum 2 fonts: one for headings, one for body (or same for both)
- System fonts acceptable:
-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
- Web fonts: Inter, Poppins, Work Sans, DM Sans
Size hierarchy
- Body text: 16px minimum (never below 14px)
- Small text: 14px (metadata, captions)
- Headings:
- H1: 32-48px
- H2: 24-32px
- H3: 20-24px
- H4: 18-20px
Weight and style
- Avoid excessive bold text
- Use weight variations (400, 500, 600, 700) for hierarchy
- Letter-spacing: -0.02em for large headings, 0 for body
5. Shadows and Depth
Subtle elevation
- Light shadow:
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12), 0 1px 2px rgba(0, 0, 0, 0.06)
- Medium shadow:
box-shadow: 0 4px 6px rgba(0, 0, 0, 0.07), 0 2px 4px rgba(0, 0, 0, 0.05)
- Avoid heavy, dramatic shadows
When to use
- Cards and modals: light to medium shadow
- Buttons: very subtle shadow on rest, slightly elevated on hover
- Dropdowns and popovers: medium shadow
6. Borders and Corners
Border radius
- Subtle rounding: 4-8px for most elements
- Medium rounding: 12-16px for cards and large containers
- Not everything needs rounding (tables, data grids can remain sharp)
Border usage
- Use either borders OR shadows, not both on the same element
- Thin borders: 1px solid with light gray (#E5E5E5)
- Input focus: 2px solid with accent color
7. Interactive States
Required states for all interactive elements
Buttons
css
1/* Default */
2background: accent-color;
3color: white;
4padding: 12px 24px;
5border-radius: 6px;
6box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
7
8/* Hover */
9background: slightly-darker-accent;
10box-shadow: 0 2px 4px rgba(0, 0, 0, 0.08);
11transform: translateY(-1px);
12
13/* Active */
14transform: translateY(0);
15box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
16
17/* Disabled */
18background: light-gray;
19color: medium-gray;
20cursor: not-allowed;
21opacity: 0.6;
Links
- Default: Accent color, no underline
- Hover: Underline, slightly darker
- Visited: Same as default (or slightly muted)
Form inputs
- Default: 1px border, light gray
- Focus: 2px border, accent color, subtle glow
- Error: Red border (#DC2626), error message below
- Disabled: Gray background, reduced opacity
8. Mobile-First Approach
Responsive thinking
- Design for mobile viewport first (320px-768px)
- Scale up to tablet (768px-1024px) and desktop (1024px+)
- Touch targets: Minimum 44x44px for buttons and interactive elements
- Stack vertically on mobile, consider horizontal on desktop
Breakpoints
css
1/* Mobile: base styles */
2/* Tablet: 768px */
3/* Desktop: 1024px */
4/* Large desktop: 1440px */
Component Patterns
Good example
html
1<button class="btn-primary">
2 Save Changes
3</button>
4
5<style>
6.btn-primary {
7 background: #0D9488;
8 color: white;
9 padding: 12px 24px;
10 border-radius: 6px;
11 border: none;
12 font-size: 16px;
13 font-weight: 500;
14 cursor: pointer;
15 transition: all 0.15s ease;
16 box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
17}
18
19.btn-primary:hover {
20 background: #0F766E;
21 box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
22 transform: translateY(-1px);
23}
24
25.btn-primary:disabled {
26 background: #D1D5DB;
27 color: #9CA3AF;
28 cursor: not-allowed;
29 transform: none;
30}
31</style>
Bad example
css
1/* Avoid */
2.btn-bad {
3 background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
4 padding: 5px 10px; /* Too small */
5 border-radius: 25px; /* Too rounded */
6 box-shadow: 0 10px 25px rgba(102, 126, 234, 0.5); /* Too heavy */
7 text-transform: uppercase;
8 letter-spacing: 2px;
9}
Cards
Good example
html
1<div class="card">
2 <h3 class="card-title">Dashboard</h3>
3 <p class="card-description">View your analytics and metrics</p>
4</div>
5
6<style>
7.card {
8 background: white;
9 border: 1px solid #E5E5E5;
10 border-radius: 8px;
11 padding: 24px;
12 transition: border-color 0.2s ease;
13}
14
15.card:hover {
16 border-color: #D1D5DB;
17}
18
19.card-title {
20 font-size: 20px;
21 font-weight: 600;
22 margin-bottom: 8px;
23 color: #1A1A1A;
24}
25
26.card-description {
27 font-size: 16px;
28 color: #6B6B6B;
29}
30</style>
Bad example
css
1/* Avoid */
2.card-bad {
3 background: linear-gradient(to right, #fa709a, #fee140);
4 border: 3px solid purple;
5 box-shadow: 0 15px 40px rgba(0, 0, 0, 0.5);
6 border-radius: 30px;
7}
Good example
html
1<form class="form">
2 <div class="form-group">
3 <label for="email">Email Address</label>
4 <input type="email" id="email" placeholder="you@example.com">
5 <span class="form-hint">We'll never share your email</span>
6 </div>
7
8 <div class="form-group">
9 <label for="password">Password</label>
10 <input type="password" id="password" class="error">
11 <span class="form-error">Password must be at least 8 characters</span>
12 </div>
13</form>
14
15<style>
16.form-group {
17 margin-bottom: 24px;
18}
19
20label {
21 display: block;
22 font-size: 14px;
23 font-weight: 500;
24 color: #2D2D2D;
25 margin-bottom: 8px;
26}
27
28input {
29 width: 100%;
30 padding: 12px 16px;
31 border: 1px solid #D1D5DB;
32 border-radius: 6px;
33 font-size: 16px;
34 transition: border-color 0.2s ease;
35}
36
37input:focus {
38 outline: none;
39 border-color: #0D9488;
40 box-shadow: 0 0 0 3px rgba(13, 148, 136, 0.1);
41}
42
43input.error {
44 border-color: #DC2626;
45}
46
47.form-hint {
48 font-size: 14px;
49 color: #6B6B6B;
50 margin-top: 4px;
51 display: block;
52}
53
54.form-error {
55 font-size: 14px;
56 color: #DC2626;
57 margin-top: 4px;
58 display: block;
59}
60</style>
Anti-Patterns to Avoid
Visual crimes
- Rainbow gradients or multiple bright colors
- Text smaller than 14px (except in rare cases)
- Inconsistent spacing (mixing random pixel values)
- Every element in a different color
- Heavy drop shadows everywhere
- Over-animation and excessive transitions
- Centered text for long paragraphs
- Poor color contrast (text on similar-colored backgrounds)
Structural issues
- No clear visual hierarchy
- Cluttered layouts with no breathing room
- Missing interactive states
- Inconsistent component styling
- Mixing design patterns (e.g., outlined buttons with filled buttons randomly)
Implementation Checklist
Before finalizing any UI component or page, verify:
When to Break These Rules
Rules can be broken with explicit user request or specific brand requirements. Document the deviation and ensure consistency in the exception.
