hypnagaga_old/docs/ANIMATIONS.md

Hand-Drawn Animation Effects

This project includes a sustainable animation system for adding hand-drawn, organic animation effects to text and UI elements throughout the site.

Using Animations in Markdown

Thanks to the markdown-it-attrs plugin (already installed), you can add CSS classes to any text inline in your markdown files using the {.classname} syntax.

Available Animation Classes

.shiver - Subtle Shake/Vibration

Creates a gentle trembling effect, like hand-drawn letters slightly moving.

This text will [shiver]{.shiver} on the page!

.wobble - Gentle Sway

A slow, organic swaying motion.

The word [wobbles]{.wobble} gently back and forth.

.draw - Hand-Drawing Effect

Simulates text being drawn onto the page (plays once on load).

This text [appears drawn]{.draw} onto the page.

.jitter - Erratic Movement

Fast, jittery movement for emphasis.

This is [urgent]{.jitter} and needs attention!

.bounce - Playful Bounce

Bounces up and down playfully.

[Click here]{.bounce} for something fun!

Examples

Single Word Animation

I'm feeling [jittery]{.jitter} about this!

Multiple Animations

The [shaky]{.shiver} text was [drawn]{.draw} by hand.

Combining with Other Attributes

You can combine animations with other markdown-it-attrs features:

[Important note]{.shiver #special-note style="color: red;"}

Applying to Entire Paragraphs

You can also apply animations to entire blocks:

The whole paragraph wobbles!
{.wobble}

Technical Details

CSS Architecture

• Location: /src/assets/css/global/utilities/text-animations.css
• Layer: utilities (automatically imported via @import-glob)
• Build: Processed through PostCSS, minified in production

Animation Properties

All animations:

• Use display: inline-block to enable transforms
• Include staggered delays for visual interest
• Respect prefers-reduced-motion for accessibility
• Use CSS custom properties where beneficial

Performance Considerations

• Animations use transform and opacity (GPU-accelerated)
• No layout thrashing or reflows
• Minimal impact on page performance
• Can be disabled per-element or globally via media query

Track Navigation Buttons

The track navigation buttons on mix pages automatically include animated SVG backgrounds:

• Previous button: Mirrored wavy line pointing left
• Next button: Wavy line pointing right
• Animation: Subtle color shift and opacity pulse
• Hover: Faster animation speed

Implementation

• Uses ::before pseudo-element for background
• SVG: /assets/svg/ui/mix_seek_01.svg
• Controlled via data-track-nav attribute
• CSS: /src/assets/css/global/blocks/track-navigation.css

Extending the System

Adding New Animation Effects

1. Add keyframes to /src/assets/css/global/utilities/text-animations.css:

@keyframes my-effect {
  0% { transform: /* start state */ }
  100% { transform: /* end state */ }
}

.my-effect {
  display: inline-block;
  animation: my-effect 1s ease-in-out infinite;
}

2. Use in markdown:

Text with [my custom effect]{.my-effect}!

Creating Component-Specific Animations

For UI components (like buttons, cards), add animations to the component's CSS file in /src/assets/css/global/blocks/.

Example:

.my-component[data-animated]::after {
  animation: wave-draw 2s ease infinite;
}

Alternative Approaches Considered

Custom Markdown Plugin

We could create a custom shortcode like {% shiver "text" %}, but:

• ❌ More verbose syntax
• ❌ Requires custom plugin development
• ❌ Less flexible than attributes
• ✅ Already have markdown-it-attrs installed

Inline Syntax

We could use delimiters like {shiver}text{/shiver}, but:

• ❌ Conflicts with existing syntax
• ❌ Harder to parse reliably
• ❌ Not standard markdown
• ✅ Attributes are a well-established pattern

JavaScript-Based Animation

We could use JavaScript libraries like:

• Anime.js, GSAP, Motion One
• ❌ Additional bundle size
• ❌ Requires JavaScript to run
• ❌ More complex implementation
• ✅ CSS is simpler, more performant, works without JS

Best Practices

1. Use sparingly: Animation should enhance, not distract
2. Consider accessibility: Some users find animations distracting
3. Test performance: Too many animated elements can impact page speed
4. Semantic HTML: Animations are presentational, keep markup semantic
5. Progressive enhancement: Content should work without animations

Resources

• markdown-it-attrs documentation
• Web Animations API
• prefers-reduced-motion