Pattern Overlay

Visual Hierarchy

Patterns should be subtle enough to add texture without competing with content. Use low opacity values (0.05 to 0.15) for backgrounds behind text. Reserve higher opacity values for decorative hero sections or empty states where readability is not a concern.

Spacing & Layout

The parent container must have position: relative and overflow: hidden when using PatternOverlay directly. Content above the overlay needs relative z-10 to appear above the pattern. Use PatternBackground to avoid managing this manually.

Responsive Behavior

Pattern overlays scale based on the scale prop and CSS background-size, so they tile naturally at any container size. On smaller screens, consider reducing opacity slightly to avoid visual noise on compact layouts. Patterns remain performant across all viewport sizes since they use pure CSS gradients.

Color & Contrast

Patterns inherit currentColor by default, adapting to the parent text color. Use design token variables like var(--primary) or var(--muted-foreground) for theme-consistent colors. Always verify that text remains readable over patterned backgrounds by testing in both light and dark modes.

Keyboard Navigation

• Pattern overlays are purely decorative and do not receive focus
• pointer-events: none is applied by default, so overlays never intercept Tab navigation or clicks
• Interactive content placed above patterns (z-10) remains fully keyboard accessible

Screen Reader Support

• aria-hidden="true" is set by default on the overlay element, hiding it from assistive technology
• Patterns carry no semantic meaning and should never convey information that is not available through other means
• Screen readers will skip the overlay entirely and read only the content above it

Focus Management

Pattern overlays do not affect focus management. The overlay is positioned at z-0 and content at z-10, ensuring focus rings on interactive elements remain visible and unobscured. No focus trapping or redirection occurs.

Motion & Visual Sensitivity

Patterns are static CSS backgrounds with no animation. The opacity transition (0.3s ease) is the only motion applied and is minimal. Users with visual sensitivities benefit from the low default opacity (0.1) which ensures patterns are subtle. Consider providing a way for users to disable patterns entirely for maximum accessibility.

ARIA Attributes

{/* Pattern overlays are decorative — always use aria-hidden */}
<div className="relative overflow-hidden">
  <PatternOverlay
    pattern="dots"
    opacity={0.15}
    aria-hidden="true"  {/* Set by default */}
  />
  <div className="relative z-10">
    <p>Accessible content here</p>
  </div>
</div>

{/* PatternBackground handles this automatically */}
<PatternBackground pattern="grid" className="p-6">
  <p>Content is automatically wrapped with correct z-index</p>
</PatternBackground>