Playbook Design

Application Styling Playbook

CSS architecture and styling patterns for maintainable, scalable UI. Give this to your AI agent for consistent visual implementation.

# agent_prompt

Copy this prompt and give it to your AI agent:

"Follow these styling practices:

1. Mobile-first responsive design (min-width breakpoints)

2. Use CSS custom properties for colors, spacing, typography

3. Utility-first approach with Tailwind (or utility classes)

4. Component-scoped styles when needed

5. Consistent spacing scale (4px base: 4, 8, 12, 16, 24, 32, 48)

6. Dark theme support with CSS variables

7. Accessible color contrast (WCAG AA minimum)"

# design_tokens

Define your design system with CSS custom properties. Single source of truth for all values. 

:root {
  /* Colors */
  --color-primary: #06b6d4;
  --color-secondary: #8b5cf6;
  --color-background: #0f172a;
  --color-surface: #1e293b;
  --color-text: #f8fafc;
  --color-text-muted: #94a3b8;

  /* Spacing (4px base) */
  --space-1: 0.25rem;  /* 4px */
  --space-2: 0.5rem;   /* 8px */
  --space-3: 0.75rem;  /* 12px */
  --space-4: 1rem;     /* 16px */
  --space-6: 1.5rem;   /* 24px */
  --space-8: 2rem;     /* 32px */

  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;

  /* Borders & Shadows */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 1rem;
  --shadow-sm: 0 1px 2px rgba(0,0,0,0.1);
}

# responsive_design

Mobile-first approach. Start with mobile styles, add complexity for larger screens.

❌ Desktop-first

.container {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
}
@media (max-width: 768px) {
  .container {
    grid-template-columns: 1fr;
  }
}

✅ Mobile-first

.container {
  display: grid;
  grid-template-columns: 1fr;
}
@media (min-width: 768px) {
  .container {
    grid-template-columns: repeat(3, 1fr);
  }
}

Standard Breakpoints

sm: 640px   /* Large phones */
md: 768px   /* Tablets */
lg: 1024px  /* Laptops */
xl: 1280px  /* Desktops */
2xl: 1536px /* Large screens */

# component_styling

Create reusable component classes with consistent patterns. 

/* Button component */
.btn {
  display: inline-flex;
  align-items: center;
  gap: var(--space-2);
  padding: var(--space-2) var(--space-4);
  font-weight: 500;
  border-radius: var(--radius-md);
  transition: all 150ms ease;
}

.btn-primary {
  background: var(--color-primary);
  color: var(--color-background);
}

.btn-primary:hover {
  filter: brightness(1.1);
}

/* Card component */
.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-lg);
  padding: var(--space-6);
}
  • • Base class: Shared styles (.btn, .card, .input)
  • • Modifier classes: Variants (.btn-primary, .btn-secondary)
  • • State classes: Interactive states (.is-active, .is-loading)
  • • Size classes: Scaling (.btn-sm, .btn-lg)

# dark_theme

Use CSS custom properties to support theme switching without duplicating styles. 

/* Light theme (default) */
:root {
  --bg-primary: #ffffff;
  --bg-secondary: #f8fafc;
  --text-primary: #0f172a;
  --text-secondary: #64748b;
  --border-color: #e2e8f0;
}

/* Dark theme */
[data-theme="dark"],
.dark {
  --bg-primary: #0f172a;
  --bg-secondary: #1e293b;
  --text-primary: #f8fafc;
  --text-secondary: #94a3b8;
  --border-color: #334155;
}

/* System preference */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    /* Dark theme variables */
  }
}

# utility_classes

Utility-first CSS (like Tailwind) for rapid, consistent styling.

Spacing

.p-4 { padding: 1rem; }
.px-4 { padding-left: 1rem; padding-right: 1rem; }
.mt-2 { margin-top: 0.5rem; }
.gap-4 { gap: 1rem; }

Flexbox

.flex { display: flex; }
.items-center { align-items: center; }
.justify-between { justify-content: space-between; }
.flex-col { flex-direction: column; }

Pro tip: Use Tailwind CSS for a complete utility system, or create your own minimal set for smaller projects.

# typography

Establish a clear typographic hierarchy with consistent sizing and spacing. 

/* Type scale */
.text-xs  { font-size: 0.75rem; line-height: 1rem; }
.text-sm  { font-size: 0.875rem; line-height: 1.25rem; }
.text-base { font-size: 1rem; line-height: 1.5rem; }
.text-lg  { font-size: 1.125rem; line-height: 1.75rem; }
.text-xl  { font-size: 1.25rem; line-height: 1.75rem; }
.text-2xl { font-size: 1.5rem; line-height: 2rem; }
.text-3xl { font-size: 1.875rem; line-height: 2.25rem; }

/* Font weights */
.font-normal { font-weight: 400; }
.font-medium { font-weight: 500; }
.font-semibold { font-weight: 600; }
.font-bold { font-weight: 700; }
  • • Body text: 16px (1rem) minimum for readability
  • • Line height: 1.5 for body, 1.2 for headings
  • • Max width: 65-75 characters for comfortable reading
  • • Contrast: 4.5:1 minimum (WCAG AA)

# accessibility

Styling should enhance accessibility, not hinder it.

Focus States

/* Never remove focus outlines without replacement */
:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

/* Optional: custom focus for buttons */
.btn:focus-visible {
  box-shadow: 0 0 0 3px rgba(6, 182, 212, 0.3);
}
  • • Color contrast: 4.5:1 for normal text, 3:1 for large text
  • • Touch targets: 44x44px minimum for interactive elements
  • • Reduced motion: Respect prefers-reduced-motion
  • • Focus indicators: Visible, high-contrast focus states
  • • Screen readers: Don't hide content with display:none if it should be read
/* Respect reduced motion */
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}