Liveblocks DESIGN.md

Real-time collaboration infrastructure with a clean developer aesthetic — dark surfaces, electric blue presence indicators, and multiplayer-first UI patterns.

1. Visual Theme & Atmosphere

Liveblocks is the invisible layer that makes apps collaborative. Its design system reflects this: clean, precise, and unobtrusive — documentation and dashboards that help developers understand and integrate real-time features without friction. The palette is dark with electric blue presence indicators that evoke live cursors, active connections, and simultaneous users. The UI is minimal but energetic.

2. Color Palette & Roles

3. Typography Rules

css--font-sans: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', monospace;
--font-size-xs: 11px;
--font-size-sm: 13px;
--font-size-base: 14px;
--font-size-md: 16px;
--font-size-lg: 20px;
--font-size-xl: 28px;
--font-size-2xl: 36px;
--font-weight-regular: 400;
--font-weight-medium: 500;
--font-weight-semibold: 600;
--font-weight-bold: 700;
--line-height-tight: 1.25;
--line-height-base: 1.5;

4. Component Stylings

css/* Primary Button */
.button-primary {
  background: #6366F1;
  color: #FFFFFF;
  border: none;
  border-radius: 8px;
  padding: 9px 18px;
  font-size: 14px;
  font-weight: 600;
  cursor: pointer;
  transition: background 0.15s ease;
}
.button-primary:hover { background: #4F46E5; }

/* Presence Avatar */
.presence-avatar {
  width: 28px;
  height: 28px;
  border-radius: 50%;
  border: 2px solid var(--color-presence-1);
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 11px;
  font-weight: 700;
  color: #FFFFFF;
  background: var(--color-presence-1);
}
.presence-avatar--overlap {
  margin-left: -8px;
}

/* Live Cursor Indicator */
.live-cursor {
  position: absolute;
  pointer-events: none;
  display: flex;
  align-items: flex-start;
  gap: 6px;
}
.live-cursor__label {
  padding: 3px 8px;
  border-radius: 100px;
  font-size: 11px;
  font-weight: 600;
  color: #FFFFFF;
  background: var(--color-presence-1);
  white-space: nowrap;
  margin-top: 16px;
}

/* Connection Status Badge */
.status-badge {
  display: inline-flex;
  align-items: center;
  gap: 6px;
  padding: 4px 10px;
  border-radius: 100px;
  font-size: 12px;
  font-weight: 600;
  background: #141415;
  border: 1px solid #2A2A2E;
  color: #A1A1AA;
}
.status-badge::before {
  content: '';
  width: 6px;
  height: 6px;
  border-radius: 50%;
  background: currentColor;
}
.status-badge--connected { color: #22C55E; border-color: rgba(34,197,94,0.2); }
.status-badge--disconnected { color: #EF4444; border-color: rgba(239,68,68,0.2); }

/* Code Snippet Card */
.code-card {
  background: #0A0A0B;
  border: 1px solid #2A2A2E;
  border-radius: 10px;
  overflow: hidden;
}
.code-card__header {
  padding: 10px 16px;
  background: #141415;
  border-bottom: 1px solid #2A2A2E;
  font-size: 12px;
  font-weight: 600;
  color: #A1A1AA;
}
.code-card__body {
  padding: 16px;
  font-family: var(--font-mono);
  font-size: 13px;
  color: #FAFAFA;
  line-height: 1.6;
}

5. Layout Principles

6. Depth & Elevation

css.shadow-card { box-shadow: 0 2px 8px rgba(0,0,0,0.5); }
.shadow-dropdown { box-shadow: 0 8px 24px rgba(0,0,0,0.6); }
.shadow-cursor { filter: drop-shadow(0 2px 4px rgba(0,0,0,0.4)); }

7. Do's and Don'ts

Do:

• Use distinct colors for each concurrent user's presence indicator
• Show live connection status prominently in multiplayer UI contexts
• Overlap presence avatars with a negative left margin (−8px) for a stack effect
• Use monospace for all integration code and API keys

Don't:

• Don't use more than 5–6 simultaneous presence colors
• Don't animate presence indicators excessively — subtle pulse is enough
• Don't use the same color for multiple active users in the same room
• Don't show presence outside of collaborative contexts

8. Responsive Behavior

9. Agent Prompt Guide

You are designing for Liveblocks — real-time collaboration infrastructure.
Use a near-black background (#0A0A0B) with card surfaces at #141415.
Primary brand is indigo (#6366F1) for CTAs; presence indicators use a rotating palette of blue, purple, pink, and green.
User avatars are circular with a colored border matching their presence color.
Live cursors show a color-matched pointer with a pill label showing the user's name.
Connection status badges use dot + label pattern with semantic color.
Typography is Inter at 14px; monospace for all code integration snippets.
Tone is technical, collaborative, and multiplayer-forward.