AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

epic-design

Use for any landing page, hero section or scroll-driven web design that should feel cinematic (parallax, scrollytelling, overlapping sections, text reveals, Apple-style animation), before coding. Inspects assets with inspect-assets.py, then builds with 45+ 2.5D techniques, no WebGL.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--epic-design at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 10

references/accessibility.md

Accessibility Reference

Non-Negotiable Rules

Every 2.5D website MUST implement ALL of the following. These are not optional enhancements — they are legal requirements in many jurisdictions and ethical requirements always.


1. prefers-reduced-motion (Most Critical)

Parallax and complex animations can trigger vestibular disorders — dizziness, nausea, migraines — in a significant portion of users. WCAG 2.1 Success Criterion 2.3.3 requires handling this.

/* This block must be in EVERY project */
@media (prefers-reduced-motion: reduce) {
  /* Nuclear option: stop all animations globally */
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }

  /* Specifically disable 2.5D techniques */
  .float-loop { animation: none !important; }
  .parallax-layer { transform: none !important; }
  .depth-0, .depth-1, .depth-2, 
  .depth-3, .depth-4, .depth-5 {
    transform: none !important;
    filter: none !important;
  }
  .glow-blob { opacity: 0.3; animation: none !important; }
  .theatrical, .theatrical-with-exit {
    animation: none !important;
    opacity: 1 !important;
    transform: none !important;
  }
}
// Also check in JavaScript — some GSAP animations don't respect CSS media queries
if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
  gsap.globalTimeline.timeScale(0); // Stops all GSAP animations
  ScrollTrigger.getAll().forEach(t => t.kill()); // Kill all scroll triggers
  
  // Show all content immediately (don't hide-until-animated)
  document.querySelectorAll('[data-animate]').forEach(el => {
    el.style.opacity = '1';
    el.style.transform = 'none';
    el.removeAttribute('data-animate');
  });
}

Per-Effect Reduced Motion (Smarter Than Kill-All)

Rather than freezing every animation globally, classify each type:

| Animation Type | At reduced-motion | |---|---| | Scroll parallax depth layers | DISABLE — continuous motion triggers vestibular issues | | Float loops / ambient movement | DISABLE — looping motion is a trigger | | DJI scale-in / perspective zoom | DISABLE — fast scale can cause dizziness | | Particle systems | DISABLE | | Clip-path reveals (one-shot) | KEEP — not continuous, not fast | | Fade-in on scroll (opacity only) | KEEP — safe | | Word-by-word scroll lighting | KEEP — no movement, just colour | | Curtain / wipe reveals (one-shot) | KEEP | | Text entrance slides (one-shot) | KEEP but reduce duration |

const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

if (prefersReduced) {
  // Disable the motion-heavy ones
  document.querySelectorAll('.float-loop').forEach(el => {
    el.style.animation = 'none';
  });
  document.querySelectorAll('[data-depth]').forEach(el => {
    el.style.transform = 'none';
    el.style.willChange = 'auto';
  });

  // Slow GSAP to near-freeze (don't fully kill — keep structure intact)
  gsap.globalTimeline.timeScale(0.01);

  // Safe animations: show them immediately at final state
  gsap.utils.toArray('.clip-reveal, .fade-reveal, .word-light').forEach(el => {
    gsap.set(el, { clipPath: 'inset(0 0% 0 0)', opacity: 1 });
  });
}

2. Semantic HTML Structure

<!-- CORRECT semantic structure -->
<main>
  <!-- Each visual scene is a section with proper landmarks -->
  <section aria-label="Hero — Product Introduction">
    
    <!-- ALL purely decorative elements get aria-hidden -->
    <div class="layer depth-0" aria-hidden="true">
      <!-- background gradients, glow blobs, particles -->
    </div>
    <div class="layer depth-1" aria-hidden="true">
      <!-- atmospheric effects -->
    </div>
    <div class="layer depth-5" aria-hidden="true">
      <!-- particles, sparkles -->
    </div>

    <!-- Meaningful content is NOT hidden -->
    <div class="layer depth-3">
      <img 
        src="product.png" 
        alt="[Descriptive alt text — what is the product, what does it look like]"
        <!-- NOT: alt="" for meaningful images! -->
      >
    </div>
    
    <div class="layer depth-4">
      <!-- Proper heading hierarchy -->
      <h1>Your Brand Name</h1>
      <!-- h1 is the page title — only one per page -->
      <p>Supporting description that provides context for screen readers</p>
      <a href="#features" class="cta-btn">
        Explore Features
        <!-- CTAs need descriptive text, not just "Click here" -->
      </a>
    </div>

  </section>
  
  <section aria-label="Product Features">
    <h2>Why Choose [Product]</h2>
    <!-- h2 for section headings -->
  </section>
</main>

3. SplitText & Screen Readers

When using SplitText to fragment text into characters/words, the individual fragments get announced one at a time by screen readers — which sounds terrible. Fix this:

function splitTextAccessibly(el, options) {
  // Save the full text for screen readers
  const fullText = el.textContent.trim();
  el.setAttribute('aria-label', fullText);

  // Split visually only
  const split = new SplitText(el, options);

  // Hide the split fragments from screen readers
  // Screen readers will use aria-label instead
  split.chars?.forEach(char => char.setAttribute('aria-hidden', 'true'));
  split.words?.forEach(word => word.setAttribute('aria-hidden', 'true'));
  split.lines?.forEach(line => line.setAttribute('aria-hidden', 'true'));

  return split;
}

// Usage
splitTextAccessibly(document.querySelector('.hero-title'), { type: 'chars,words' });

4. Keyboard Navigation

All interactive elements must be reachable and operable via keyboard (Tab, Enter, Space, Arrow keys).

/* Ensure focus indicators are visible — WCAG 2.4.7 */
:focus-visible {
  outline: 3px solid #005fcc; /* High contrast focus ring */
  outline-offset: 3px;
  border-radius: 3px;
}

/* Remove default outline only if replacing with custom */
:focus:not(:focus-visible) {
  outline: none;
}

/* Skip link for keyboard users to bypass navigation */
.skip-link {
  position: absolute;
  top: -100px;
  left: 0;
  background: #005fcc;
  color: white;
  padding: 12px 20px;
  z-index: 10000;
  font-weight: 600;
  text-decoration: none;
}
.skip-link:focus {
  top: 0; /* Appears at top when focused */
}
<!-- Always first element in body -->
<a href="#main-content" class="skip-link">Skip to main content</a>
<main id="main-content">
  ...
</main>

5. Color Contrast (WCAG 2.1 AA)

Text must have sufficient contrast against its background:

  • Normal text (under 18pt): minimum 4.5:1 contrast ratio
  • Large text (18pt+ or 14pt+ bold): minimum 3:1 contrast ratio
  • UI components and focus indicators: minimum 3:1
/* Common mistake: light text on gradient with glow effects */
/* Always test contrast with the darkest AND lightest background in the gradient */

/* Safe text over complex backgrounds — add text shadow for contrast boost */
.hero-text-on-image {
  color: #ffffff;
  /* Multiple small text shadows create a halo that boosts contrast */
  text-shadow: 
    0 0 20px rgba(0,0,0,0.8),
    0 2px 4px rgba(0,0,0,0.6),
    0 0 40px rgba(0,0,0,0.4);
}

/* Or use a semi-transparent backdrop */
.text-backdrop {
  background: rgba(0, 0, 0, 0.55);
  backdrop-filter: blur(8px);
  padding: 1rem 1.5rem;
  border-radius: 8px;
}

Testing tool: Use browser DevTools accessibility panel or webaim.org/resources/contrastchecker/


6. Motion-Sensitive Users — User Control

Beyond prefers-reduced-motion, provide an in-page control:

<!-- Floating toggle button -->
<button 
  class="motion-toggle" 
  aria-pressed="false"
  aria-label="Toggle animations on/off"
>
  <span class="motion-toggle-icon">✦</span>
  <span class="motion-toggle-text">Animations On</span>
</button>
const motionToggle = document.querySelector('.motion-toggle');
let animationsEnabled = !window.matchMedia('(prefers-reduced-motion: reduce)').matches;

motionToggle.addEventListener('click', () => {
  animationsEnabled = !animationsEnabled;
  motionToggle.setAttribute('aria-pressed', !animationsEnabled);
  motionToggle.querySelector('.motion-toggle-text').textContent = 
    animationsEnabled ? 'Animations On' : 'Animations Off';
  
  if (animationsEnabled) {
    document.documentElement.classList.remove('no-motion');
    gsap.globalTimeline.timeScale(1);
  } else {
    document.documentElement.classList.add('no-motion');
    gsap.globalTimeline.timeScale(0);
  }
  
  // Persist preference
  localStorage.setItem('motionPreference', animationsEnabled ? 'on' : 'off');
});

// Restore on load
const saved = localStorage.getItem('motionPreference');
if (saved === 'off') motionToggle.click();

7. Images — Alt Text Guidelines

<!-- Meaningful product image -->
<img src="juice-glass.png" alt="Tall glass of fresh orange juice with ice, floating on a gradient background">

<!-- Decorative geometric shape -->
<img src="shape-circle.png" alt="" aria-hidden="true">
<!-- Empty alt="" tells screen readers to skip it -->

<!-- Icon with text label next to it -->
<img src="icon-arrow.svg" alt="" aria-hidden="true">
<span>Learn More</span>
<!-- Icon is decorative when text is present -->

<!-- Standalone icon button — needs alt text -->
<button>
  <img src="icon-menu.svg" alt="Open navigation menu">
</button>

8. Loading Screen Accessibility

// Announce loading state to screen readers
function announceLoading() {
  const announcement = document.createElement('div');
  announcement.setAttribute('role', 'status');
  announcement.setAttribute('aria-live', 'polite');
  announcement.setAttribute('aria-label', 'Page loading');
  announcement.className = 'sr-only'; // visually hidden
  document.body.appendChild(announcement);

  // Update announcement when done
  window.addEventListener('load', () => {
    announcement.textContent = 'Page loaded';
    setTimeout(() => announcement.remove(), 1000);
  });
}
/* Screen-reader only utility class */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0,0,0,0);
  white-space: nowrap;
  border: 0;
}

WCAG 2.1 AA Compliance Checklist

Before shipping any 2.5D website:

  • [ ] prefers-reduced-motion CSS block present and tested
  • [ ] GSAP animations stopped when reduced motion detected
  • [ ] All decorative elements have aria-hidden="true"
  • [ ] All meaningful images have descriptive alt text
  • [ ] SplitText elements have aria-label on parent
  • [ ] Heading hierarchy is logical (h1 → h2 → h3, no skipping)
  • [ ] All interactive elements reachable via keyboard Tab
  • [ ] Focus indicators visible and have 3:1 contrast
  • [ ] Skip-to-main-content link present
  • [ ] Text contrast meets 4.5:1 minimum
  • [ ] CTA buttons have descriptive text
  • [ ] Motion toggle button provided (optional but recommended)
  • [ ] Page has <html lang="en"> (or correct language)
  • [ ] <main> landmark wraps page content
  • [ ] Section landmarks use aria-label to differentiate them