Animations Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Animation Guidelines provide a structured framework for implementing, testing, and refining UI animations within the web-projects monorepo. The project centralizes animation logic within specialized packages and playgrounds to ensure high-quality interactive experiences across different applications like dotori-note and noumenon-front.
Sources: CLAUDE.md:27-38, README.md:12-25
Animation Architecture
The project utilizes a modular architecture where animation components are developed in a dedicated library and verified in specialized environments.
Core Animation Stack
The animation system is built upon modern React-based tools:
- Frameworks: React 19 and Next.js 15.
- Engine:
framer-motionserves as the primary animation engine for complex transitions and gestures. - Utilities:
flubberis included for fluid SVG shape morphing. - Hooks:
react-useprovides lifecycle utilities to support animation states.
Sources: packages/ui-craft/package.json:25-29, AGENTS.md:43-52
Component Organization
Animations are categorized into two main areas:
- @siluat/ui-craft: A personal UI animation library containing reusable React components.
- Animation Practice: A dedicated workspace for learning and experimenting with advanced techniques, such as those from the "Animation on the Web" curriculum.
Sources: CLAUDE.md:31-31, playgrounds/animation-practice/README.md:1-10
Development and Testing Workflow
The repository follows a strict workflow for creating and fine-tuning animations through designated playgrounds and automated test suites.
Workflow Diagram
The following diagram illustrates the lifecycle of an animation component from development in the library to visual testing in the playground.
The diagram shows the transition from raw component code in ui-craft to visual refinement in the playground using Leva, ending with verification via Vitest and Playwright.
Sources: packages/ui-craft/README.md:1-15, playgrounds/animation-practice/package.json:11-20
Animation Controls
The animation-practice and ui-craft-playground environments utilize Leva to provide a GUI for real-time manipulation of animation parameters (e.g., spring stiffness, damping, duration) without requiring code recompilation.
Sources: playgrounds/animation-practice/package.json:11-11, packages/ui-craft/README.md:13-15
Quality Standards and Timing
To ensure a consistent user experience, specific timing constants and interaction patterns are enforced across the project.
Timing Constants
Standardized timeouts are used in end-to-end tests to account for animation durations and ensure test stability.
| Category | Value | Description |
|---|---|---|
TIMEOUT.ANIMATION | 500ms - 1000ms | General wait time for UI transitions to complete. |
TIMEOUT.SCROLL | 1000ms | Buffer for smooth scroll animations in long-form content. |
TIMEOUT.CLICK_DELAY | 300ms | Buffer before/after interactions to prevent race conditions. |
Sources: apps/dotori-note/tests/heading-autolink.spec.ts:4-8, apps/dotori-note/tests/header-switch-theme.spec.ts:13-18
Interaction Verification
Animations are verified for accessibility and functional correctness:
- Keyboard Accessibility: Ensuring links and animated elements are focusable via
tabindexand triggerable via "Enter" keys. - State Transitions: Verifying that theme switches (Dark/Light/Auto) trigger correct CSS class applications (
.dark) following menu animations. - Visual Feedback: Checking for hover states, such as the appearance of "#" icons via
::beforepseudo-elements on autolink headings.
Sources: apps/dotori-note/tests/heading-autolink.spec.ts:130-155, apps/dotori-note/tests/header-switch-theme.spec.ts:114-140
Implementation Patterns
Adding New Animation Practices
New animation exercises are added following a standardized process:
- Create a new page within
playgrounds/animation-practice/app/(workspaces)/**. - Register the practice in the sidebar configuration located at
app/_config/sidebar.config.ts.
Sources: playgrounds/animation-practice/README.md:12-16
Project Structure for UI Craft
The UI animation library exports its components using a specific pattern to maintain clean workspace dependencies.
{
"name": "@siluat/ui-craft",
"type": "module",
"exports": {
"./react/*": "./react/*.tsx"
}
}
Sources: packages/ui-craft/package.json:2-15
Conclusion
Animations in this project are treated as first-class citizens, backed by a robust technical stack including framer-motion and react-use. By leveraging Turborepo for task orchestration and dedicated playgrounds for visual tuning, the project maintains a high standard of interactive performance and visual polish.