kanopi/responsive-styling

Responsive Styling Skill

Purpose

Generate mobile-first, responsive CSS/SCSS that works across all devices and follows accessibility best practices.

Philosophy

Responsive design is accessibility. Mobile-first is user-first.

Core Beliefs

1. Mobile First is Performance First: Start with constraints, enhance progressively
2. Accessibility is Non-Negotiable: WCAG AA compliance is the baseline, not a bonus
3. Exact Specifications Build Confidence: Calculate exact contrast ratios, don't estimate
4. Touch-Friendly by Default: 44px minimum targets prevent user frustration

Why Mobile-First Responsive Styling Matters

• User Experience: Most users access sites on mobile devices
• Performance: Smaller initial payload, enhance for larger screens
• Accessibility: Ensures usability for all users and devices
• Professional Quality: Shows attention to detail and best practices

When This Skill Activates

This skill automatically activates when:

• User asks to "make it responsive"
• User mentions breakpoints, mobile, tablet, or desktop
• Creating styles for a component
• User asks about media queries
• Responsive design is needed for implementation
• WordPress block patterns need editor styling

Decision Framework

Before generating responsive styles, determine:

What's the Component Type?

1. Layout container → Focus on width, padding, grid/flex
2. Content block → Focus on typography, spacing, images
3. Interactive element (button, form) → Focus on touch targets, states, transitions
4. Navigation → Focus on mobile menu, breakpoint behavior
5. Media (images, video) → Focus on aspect ratios, object-fit

What Are the Breakpoints?

Standard mobile-first breakpoints:

• Base styles (320px+) - Mobile default
• Tablet (768px+) - @media (min-width: 768px)
• Desktop (1024px+) - @media (min-width: 1024px)
• Large desktop (1440px+) - Optional for max-width constraints

When to add breakpoints:

• ✅ Layout changes significantly (columns stack/unstack)
• ✅ Typography scales (mobile 16px → desktop 18px)
• ✅ Touch targets adjust (mobile 44px → desktop 40px)
• ❌ Minor pixel adjustments (avoid breakpoint bloat)

What Accessibility Requirements?

WCAG 2.1 Level AA compliance:

• ✅ Color contrast: 4.5:1 for normal text, 3:1 for large text (calculate exactly)
• ✅ Touch targets: ≥ 44x44px on mobile, ≥ 40x40px on desktop
• ✅ Focus indicators: 2px outline minimum, distinct from hover
• ✅ Motion sensitivity: @media (prefers-reduced-motion: reduce)

What States Are Needed?

Interactive states (buttons, links):

• :hover - Mouse pointer over element
• :focus - Keyboard navigation focus
• :focus-visible - Keyboard focus (not mouse click)
• :active - During click/tap
• :disabled - Inactive state

Priority: Focus states more important than hover (accessibility)

What Typography Scale?

Mobile-first sizing:

• Body text: Start 16px (never below, readability)
• Headings: Use clamp() for fluid scaling
  • Example: font-size: clamp(1.5rem, 5vw, 2.5rem);
• Line height: 1.5 for body, 1.2-1.3 for headings
• Font weights: Use actual weights, not relative (400, 600, 700)

What Spacing System?

Consistent spacing scale (choose one):

• 8px grid: 8px, 16px, 24px, 32px, 40px, 48px, 64px
• rem-based: 0.5rem, 1rem, 1.5rem, 2rem, 3rem, 4rem

Apply consistently:

• Margins, padding, gaps use same scale
• Avoid arbitrary values (17px, 23px)

Decision Tree

User requests responsive styles
    ↓
Determine component type
    ↓
Define mobile-first base styles (320px+)
    ↓
Calculate contrast ratios (WCAG AA)
    ↓
Add tablet breakpoint (768px+) if layout changes
    ↓
Add desktop breakpoint (1024px+) if needed
    ↓
Add all interactive states (focus > hover)
    ↓
Add reduced motion support
    ↓
Output mobile-first SCSS with exact values

Core Principles

1. Mobile-First Approach

Always write base styles for mobile, then enhance for larger screens:

// ✅ CORRECT: Mobile-first
.component {
  font-size: 1rem;        // Base mobile style
  padding: 1rem;

  @media (min-width: 768px) {
    font-size: 1.125rem;  // Enhance for tablet
    padding: 2rem;
  }

  @media (min-width: 1024px) {
    font-size: 1.25rem;   // Enhance for desktop
    padding: 3rem;
  }
}

// ❌ WRONG: Desktop-first
.component {
  font-size: 1.25rem;

  @media (max-width: 1024px) {
    font-size: 1.125rem;
  }

  @media (max-width: 768px) {
    font-size: 1rem;
  }
}

2. Standard Breakpoints

Use consistent breakpoints:

// Mobile: 320px - 767px (base styles, no media query)
// Tablet: 768px - 1023px
$breakpoint-tablet: 768px;

// Desktop: 1024px+
$breakpoint-desktop: 1024px;

// Optional additional breakpoints
$breakpoint-mobile-large: 480px;
$breakpoint-tablet-large: 960px;
$breakpoint-desktop-large: 1280px;

3. Responsive Typography

Scale typography appropriately:

.heading-1 {
  // Mobile base
  font-size: 2rem;        // 32px
  line-height: 1.2;
  font-weight: 700;
  margin-bottom: 1rem;

  // Tablet
  @media (min-width: 768px) {
    font-size: 2.5rem;    // 40px
    margin-bottom: 1.5rem;
  }

  // Desktop
  @media (min-width: 1024px) {
    font-size: 3rem;      // 48px
    margin-bottom: 2rem;
  }
}

.body-text {
  // Mobile base
  font-size: 1rem;        // 16px
  line-height: 1.6;

  // Tablet
  @media (min-width: 768px) {
    font-size: 1.125rem;  // 18px
    line-height: 1.7;
  }

  // Desktop
  @media (min-width: 1024px) {
    font-size: 1.25rem;   // 20px
    line-height: 1.8;
  }
}

4. Responsive Spacing

Use fluid spacing that scales:

// Method 1: Stepped spacing
.section {
  // Mobile
  padding: 2rem 1rem;
  margin-bottom: 2rem;

  // Tablet
  @media (min-width: 768px) {
    padding: 3rem 2rem;
    margin-bottom: 3rem;
  }

  // Desktop
  @media (min-width: 1024px) {
    padding: 4rem 3rem;
    margin-bottom: 4rem;
  }
}

// Method 2: Fluid spacing with clamp
.section-fluid {
  // Scales smoothly between mobile and desktop
  padding: clamp(2rem, 5vw, 4rem) clamp(1rem, 3vw, 3rem);
  margin-bottom: clamp(2rem, 4vw, 4rem);
}

5. Responsive Layouts

Stacked to Columns

.card-grid {
  display: grid;
  gap: 1.5rem;

  // Mobile: single column
  grid-template-columns: 1fr;

  // Tablet: 2 columns
  @media (min-width: 768px) {
    grid-template-columns: repeat(2, 1fr);
    gap: 2rem;
  }

  // Desktop: 3 columns
  @media (min-width: 1024px) {
    grid-template-columns: repeat(3, 1fr);
    gap: 3rem;
  }
}

Flexbox Responsive

.flex-container {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;

  // Mobile: stack vertically
  flex-direction: column;

  // Tablet and up: horizontal
  @media (min-width: 768px) {
    flex-direction: row;
    gap: 2rem;
  }

  .flex-item {
    // Mobile: full width
    flex: 1 1 100%;

    // Tablet: 2 items per row
    @media (min-width: 768px) {
      flex: 1 1 calc(50% - 1rem);
    }

    // Desktop: 3 items per row
    @media (min-width: 1024px) {
      flex: 1 1 calc(33.333% - 1.333rem);
    }
  }
}

WordPress-Specific Patterns

Full-Width Sections

// Handle WordPress core padding
.wp-block-cover {
  // Full viewport width accounting for theme padding
  width: calc(100vw - var(--wp--style--root--padding-left) - var(--wp--style--root--padding-right));
  max-width: none;

  // Center it
  margin-left: calc(-1 * var(--wp--style--root--padding-left));
  margin-right: calc(-1 * var(--wp--style--root--padding-right));
}

Responsive Block Patterns

// Pattern wrapper
.wp-block-group.pattern-name {
  // Mobile
  padding: 2rem 1rem;

  // Inner content container
  .wp-block-group__inner-container {
    max-width: 100%;
    margin: 0 auto;

    // Tablet
    @media (min-width: 768px) {
      max-width: 750px;
    }

    // Desktop
    @media (min-width: 1024px) {
      max-width: 1200px;
    }
  }
}

Drupal-Specific Patterns

Paragraph Responsive Styles

.paragraph--type--name {
  // Mobile base
  padding: 2rem 1rem;

  // Inner container
  .paragraph__content {
    max-width: 100%;
    margin: 0 auto;

    @media (min-width: 768px) {
      padding: 3rem 2rem;
      max-width: 750px;
    }

    @media (min-width: 1024px) {
      padding: 4rem 3rem;
      max-width: 1200px;
    }
  }
}

Field Responsive Display

.field--name-field-items {
  display: grid;
  gap: 1rem;

  // Mobile: stack
  grid-template-columns: 1fr;

  // Tablet: 2 up
  @media (min-width: 768px) {
    grid-template-columns: repeat(2, 1fr);
    gap: 1.5rem;
  }

  // Desktop: 3 up
  @media (min-width: 1024px) {
    grid-template-columns: repeat(3, 1fr);
    gap: 2rem;
  }
}

WordPress Block Editor Styles

IMPORTANT: WordPress block patterns require TWO separate stylesheets:

1. Front-End Stylesheet

Standard styles that apply to published pages. No special wrapper needed.

2. Editor Stylesheet

Styles for the WordPress block editor (admin). Must wrap all selectors with .editor-styles-wrapper.

Example:

Front-end (_hero-cta.scss):

.hero-cta-pattern {
  padding: 2rem 1rem;
  background: #0073aa;
  color: #ffffff;

  @media (min-width: 768px) {
    padding: 3rem 2rem;
  }
}

Editor (_hero-cta-editor.scss):

// Wrap everything with .editor-styles-wrapper
.editor-styles-wrapper {
  .hero-cta-pattern {
    padding: 2rem 1rem;
    background: #0073aa;
    color: #ffffff;

    @media (min-width: 768px) {
      padding: 3rem 2rem;
    }
  }
}

Why this is necessary:

• WordPress block editor uses .editor-styles-wrapper as a scoping mechanism
• Without this wrapper, styles won't apply in the admin editor
• Pattern appears unstyled when inserted, confusing users

Responsive Images

Basic Responsive Image

img {
  max-width: 100%;
  height: auto;
  display: block;
}

Responsive Background Images

.hero-background {
  background-size: cover;
  background-position: center;
  min-height: 300px;

  @media (min-width: 768px) {
    min-height: 400px;
  }

  @media (min-width: 1024px) {
    min-height: 600px;
  }
}

Art Direction

.responsive-image {
  // Mobile: portrait crop
  aspect-ratio: 4/5;
  object-fit: cover;

  // Tablet: square
  @media (min-width: 768px) {
    aspect-ratio: 1/1;
  }

  // Desktop: landscape
  @media (min-width: 1024px) {
    aspect-ratio: 16/9;
  }
}

Touch-Friendly Design

Minimum Touch Targets

button,
a,
input,
select {
  // Minimum 44x44px for touch
  min-height: 44px;
  min-width: 44px;

  // Larger on very small screens
  @media (max-width: 375px) {
    min-height: 48px;
    min-width: 48px;
  }
}

Spacing for Touch

.touch-menu {
  li {
    // More spacing on mobile
    margin-bottom: 0.5rem;

    a {
      // Larger tap area
      padding: 0.75rem 1rem;
      display: block;
    }
  }

  // Less spacing needed on desktop with mouse
  @media (min-width: 1024px) {
    li {
      margin-bottom: 0.25rem;

      a {
        padding: 0.5rem 1rem;
      }
    }
  }
}

Accessibility in Responsive Design

Focus Indicators

a, button, input, select {
  &:focus {
    outline: 2px solid currentColor;
    outline-offset: 2px;
  }

  // More prominent on mobile
  @media (max-width: 767px) {
    &:focus {
      outline-width: 3px;
    }
  }
}

Text Readability

.content {
  // Mobile: shorter line length
  max-width: 100%;

  // Desktop: optimal reading width
  @media (min-width: 768px) {
    max-width: 65ch; // ~65 characters per line
  }
}

Reduced Motion

// Respect user's motion preferences
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

Common Responsive Patterns

Hide/Show Elements

// Show only on mobile
.mobile-only {
  display: block;

  @media (min-width: 768px) {
    display: none;
  }
}

// Hide on mobile
.desktop-only {
  display: none;

  @media (min-width: 768px) {
    display: block;
  }
}

// Tablet and up
.tablet-up {
  display: none;

  @media (min-width: 768px) {
    display: block;
  }
}

Responsive Navigation

.main-nav {
  // Mobile: hamburger menu
  @media (max-width: 767px) {
    .menu-toggle {
      display: block;
    }

    .menu-items {
      display: none;

      &.is-open {
        display: block;
        position: fixed;
        top: 60px;
        left: 0;
        right: 0;
        background: white;
        padding: 1rem;
      }
    }
  }

  // Desktop: horizontal menu
  @media (min-width: 768px) {
    .menu-toggle {
      display: none;
    }

    .menu-items {
      display: flex;
      gap: 2rem;
    }
  }
}

Responsive Typography System

// Define fluid typography
:root {
  // Scales from 16px to 20px
  --font-size-base: clamp(1rem, 0.9rem + 0.5vw, 1.25rem);

  // Scales from 32px to 48px
  --font-size-h1: clamp(2rem, 1.5rem + 2vw, 3rem);

  // Scales from 24px to 32px
  --font-size-h2: clamp(1.5rem, 1.25rem + 1vw, 2rem);

  // Scales from 20px to 24px
  --font-size-h3: clamp(1.25rem, 1.125rem + 0.5vw, 1.5rem);
}

body {
  font-size: var(--font-size-base);
}

h1 {
  font-size: var(--font-size-h1);
}

h2 {
  font-size: var(--font-size-h2);
}

h3 {
  font-size: var(--font-size-h3);
}

Testing Checklist

When generating responsive styles, ensure:

• [ ] Mobile base styles defined first
• [ ] Breakpoints use min-width (mobile-first)
• [ ] Touch targets are 44px minimum
• [ ] Text is readable at all sizes
• [ ] Images scale properly
• [ ] Layouts don't break at any width
• [ ] Horizontal scrolling is prevented
• [ ] Focus indicators are visible
• [ ] Reduced motion is respected
• [ ] Content is accessible at 320px width
• [ ] Layout works up to 2560px width

Output Format

When generating responsive styles, provide:

/* Component Name */

/* Mobile base styles (320px - 767px) */
.component {
  /* All base styles here */
}

/* Tablet (768px - 1023px) */
@media (min-width: 768px) {
  .component {
    /* Tablet enhancements */
  }
}

/* Desktop (1024px+) */
@media (min-width: 1024px) {
  .component {
    /* Desktop enhancements */
  }
}

/* Accessibility */
@media (prefers-reduced-motion: reduce) {
  /* Reduced motion styles */
}

Common Mistakes to Avoid

❌ Desktop-first (using max-width) ❌ Magic numbers (random breakpoints) ❌ Forgetting touch targets ❌ Fixed pixel widths that don't scale ❌ Tiny text on mobile (<16px) ❌ Horizontal scrolling ❌ Ignoring landscape mobile ❌ Breaking at intermediate sizes

✅ Mobile-first (using min-width) ✅ Consistent breakpoints ✅ 44px minimum touch targets ✅ Flexible widths with max-width ✅ 16px minimum text ✅ Contained content ✅ Test at 320px, 768px, 1024px ✅ Test at all widths