WorkOS DESIGN.md

Enterprise auth design with confident blue identity, SSO-first surfaces, admin portal clarity, and B2B-ready integration UX.

1. Visual Theme & Atmosphere

WorkOS should feel enterprise-ready, developer-friendly, and trustworthy. The design language communicates Single Sign-On, SCIM provisioning, fine-grained authorization, Admin Portal, and the infrastructure that makes apps enterprise-grade.

• Mood: enterprise-ready, developer-friendly, reliable, professional
• Density: medium, with SSO connection tables, directory sync dashboards, organization management, and audit log surfaces
• Character: confident blue brand, clean white enterprise surfaces, dark sidebar navigation, compliance-ready clarity

2. Color Palette & Roles

Blue is the primary action and brand signal. The connection-status scale (green/amber/red) must be strictly consistent — it communicates whether enterprise customers can actually log in.

3. Typography Rules

css--font-sans: Inter, ui-sans-serif, system-ui, -apple-system, sans-serif;
--font-mono: "JetBrains Mono", "SF Mono", Menlo, monospace;

4. Component Stylings

css.button-primary {
  min-height: 38px;
  padding: 0 16px;
  border: none;
  border-radius: 8px;
  background: #6363F1;
  color: #FFFFFF;
  font: 600 14px/1 Inter, sans-serif;
}

.connection-card {
  border: 1px solid #E2E8F0;
  border-radius: 10px;
  background: #FFFFFF;
  padding: 16px 20px;
  display: flex;
  align-items: center;
  gap: 14px;
}

.org-row {
  display: flex;
  align-items: center;
  padding: 12px 16px;
  border-bottom: 1px solid #E2E8F0;
}

.connection-status {
  display: inline-flex;
  align-items: center;
  gap: 6px;
  padding: 3px 10px;
  border-radius: 999px;
  font: 600 12px/1.4 Inter, sans-serif;
}

.code-value {
  font: 400 13px/1 "JetBrains Mono", monospace;
  padding: 3px 8px;
  border-radius: 4px;
  background: #F1F5F9;
  color: #475569;
}

5. Layout Principles

Organizations list is the primary surface. Each org expands to show its SSO connections, directory sync, and audit logs. API keys and client IDs always display in mono with a copy button.

6. Depth & Elevation

css.shadow-card   { box-shadow: 0 1px 4px rgba(17, 24, 39, 0.06); }
.shadow-panel  { box-shadow: 0 8px 24px rgba(99, 99, 241, 0.10); }
.shadow-modal  { box-shadow: 0 20px 50px rgba(17, 24, 39, 0.16); }

Clean, flat surfaces with minimal shadow — enterprise tools convey reliability through precision, not decoration.

7. Do's and Don'ts

Do always show connection status with a color indicator and a text label. Do display client IDs and API keys in mono with one-click copy. Do surface organization count and active SSO connections on the dashboard. Do not use blue for failed connection states. Do not hide the audit log — enterprise customers require it for compliance.

8. Responsive Behavior

Enterprise auth management is a desktop workflow. Mobile for monitoring only.

9. Agent Prompt Guide

Design like WorkOS: confident blue CTAs, deep indigo sidebar, SSO-connection status scale, organization management tables, mono API key display, enterprise-ready clean surfaces, and B2B auth infrastructure hierarchy.