One Animation Asset in a Design System: Naming, States and Versioning

What makes animation an asset

A one-off animation belongs to the feature that uses it. An asset is reused, has a stable interface and can be changed without rewriting every consumer. That means it needs more than a file: a name, a purpose, a state list, an input contract and a path to production. Without those, every team copies the file and the copies drift.

Name by intent

Name the asset by the job it does, not the shape it draws. motion.enter.sheet is easier to reuse than blueSlideUp. The same applies to tokens inside it: motion.spring.snappy is more useful than spring420. Intent-based names survive redesigns and make it clear when a new asset is actually needed.

• Asset name: what it is for, such as success-confirmation
• State names: idle, pressed, loading, success, error
• Input names: what the app can set, such as isSaving
• Event names: what the app can react to, such as confirmed
• Token names: intent, not raw numbers

Document every state

The documentation should list each state, what triggers it, what changes visually and what the user can do next. Include the reduced-motion version and the fallback when the asset fails to load. A single video of the happy path is not enough. The states that cause bugs are usually loading, error, disabled and interrupted.

Connect to motion tokens

Use the same timing and spring values as the rest of the product. If the asset hard-codes its own numbers, it will drift from the system. If the runtime cannot consume tokens directly, document the mapping and review changes against the token set. A design-system asset that ignores the design system is just a shared file.

Version it like a component

A change to an animation can break layout, timing or state logic. Treat it as a component change: review the diff, note the visual difference, and release a version. Keep a changelog that says what changed and why. If consumers can pin a version, a risky change does not have to ship everywhere at once.

Distribution and ownership

Put the asset where the work happens. If designers work in a design file and developers consume a package, keep both in sync from one source. Name an owner who reviews changes and retires duplicates. A runtime file can give design and code the same reference, but the governance model matters more than the file format.