180 lines
4.9 KiB
Markdown
180 lines
4.9 KiB
Markdown
# 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.
|
|
|
|
```markdown
|
|
This text will [shiver]{.shiver} on the page!
|
|
```
|
|
|
|
#### `.wobble` - Gentle Sway
|
|
A slow, organic swaying motion.
|
|
|
|
```markdown
|
|
The word [wobbles]{.wobble} gently back and forth.
|
|
```
|
|
|
|
#### `.draw` - Hand-Drawing Effect
|
|
Simulates text being drawn onto the page (plays once on load).
|
|
|
|
```markdown
|
|
This text [appears drawn]{.draw} onto the page.
|
|
```
|
|
|
|
#### `.jitter` - Erratic Movement
|
|
Fast, jittery movement for emphasis.
|
|
|
|
```markdown
|
|
This is [urgent]{.jitter} and needs attention!
|
|
```
|
|
|
|
#### `.bounce` - Playful Bounce
|
|
Bounces up and down playfully.
|
|
|
|
```markdown
|
|
[Click here]{.bounce} for something fun!
|
|
```
|
|
|
|
### Examples
|
|
|
|
#### Single Word Animation
|
|
```markdown
|
|
I'm feeling [jittery]{.jitter} about this!
|
|
```
|
|
|
|
#### Multiple Animations
|
|
```markdown
|
|
The [shaky]{.shiver} text was [drawn]{.draw} by hand.
|
|
```
|
|
|
|
#### Combining with Other Attributes
|
|
You can combine animations with other markdown-it-attrs features:
|
|
|
|
```markdown
|
|
[Important note]{.shiver #special-note style="color: red;"}
|
|
```
|
|
|
|
### Applying to Entire Paragraphs
|
|
|
|
You can also apply animations to entire blocks:
|
|
|
|
```markdown
|
|
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`:
|
|
|
|
```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**:
|
|
|
|
```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:
|
|
```css
|
|
.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](https://github.com/arve0/markdown-it-attrs)
|
|
- [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API)
|
|
- [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion)
|