soureeui 1.0.0

package/references/audit-and-refactor.md

@@ -0,0 +1,64 @@
+# Audit and Refactor
+
+For "make this modern", "improve this UI", "this looks bad", and every redesign of something that already exists.
+
+---
+
+## Superficial changes are not a redesign
+
+If the response to "make this modern" is: new accent color, bigger radius, a gradient, new shadows, a new font — the work has not been done. Those change the skin and leave every real problem intact.
+
+Diagnose first. Then fix what is actually wrong, in this order of impact:
+
+```
+1. Information architecture   what is here, how it is grouped, what does not belong
+2. Layout and composition     structure, rhythm, alignment, density
+3. Visual hierarchy           what wins attention, and does it deserve to
+4. Navigation                 can users find and return
+5. Typography                 scale, contrast, measure, weight
+6. Spacing                    consistency and grouping
+7. Components                 consistency, states, variant sprawl
+8. Color and surfaces         roles, contrast, meaning
+9. Imagery                    purpose, quality, placement
+10. Interaction and motion    feedback, transitions, error and empty states
+11. Responsive                mobile as a designed experience
+12. Accessibility             throughout
+```
+
+Most interfaces that "look bad" have a hierarchy and spacing problem, not a color problem.
+
+---
+
+## Audit first
+
+Run the audit and present it before changing code. Template: `../templates/ui-audit.md`.
+
+Keep it short and specific. Every problem names a location and a consequence:
+
+> *Dashboard header — four equally-weighted actions, none primary. Users cannot tell which one starts the main task.*
+
+not
+
+> *Header could be improved.*
+
+---
+
+## Scope discipline
+
+- do not rewrite an entire interface when focused changes reach the goal
+- preserve working functionality and existing behavior exactly
+- keep the project's conventions, even ones you would not choose
+- no unrelated refactoring bundled into a design change
+- when the redesign is large, stage it: tokens first, then shared components, then screens — so the product stays shippable throughout
+
+## Removal is part of the work
+
+Redesign deletes. Look for: duplicate components doing the same job, dead styles, one-off overrides, unused dependencies, decorative elements with no purpose, sections nobody uses, states that never occur.
+
+A redesign that only adds is usually just a reskin.
+
+## Result standard
+
+After the work, the improvement must be **structural and visible**, not cosmetic: a clearer primary action, a real hierarchy, consistent components, a mobile layout that was designed, states that exist, and an identity that belongs to this product.
+
+If a stakeholder cannot name three concrete things that got better, the redesign failed.

package/references/content-and-copy.md

@@ -0,0 +1,75 @@
+# Content and Copy
+
+Copy is not filled in after the design. Copy *is* the design — length, specificity, and voice determine layout, hierarchy, and whether the interface communicates anything.
+
+---
+
+## Banned by default
+
+```
+Lorem ipsum dolor sit amet
+Amazing solutions for your business
+Transform your workflow
+The future of innovation
+Empower your team
+Take your X to the next level
+Seamlessly integrate everything
+Built for the modern web
+Unlock the power of...
+```
+
+Allowed only when the user explicitly asked for placeholder text.
+
+---
+
+## What to write instead
+
+When real copy is unavailable, write realistic product-specific copy from the requirements. Specific and provisional beats vague and permanent — and it exposes layout problems early, because real strings are uneven.
+
+| Generic | Specific |
+|---|---|
+| "Transform your workflow" | "Close the month in two days, not two weeks" |
+| "Powerful analytics" | "See which shifts cost the most overtime" |
+| "Get Started" | "Create your first invoice" |
+| "Learn more" | "See how routing works" |
+| "Something went wrong" | "We couldn't reach the payment provider. Your card was not charged." |
+| "No data" | "No shipments yet. Import a manifest to get started." |
+
+Mark invented facts as invented. Never fabricate customer names, logos, testimonials, metrics, certifications, or awards. If a section needs social proof that does not exist, cut the section or leave a clearly labeled slot.
+
+---
+
+## Interface copy rules
+
+- **Buttons name the outcome.** "Send invoice", not "Submit". "Delete project", not "OK"
+- **Labels over placeholders.** Placeholder text disappears on focus and fails accessibility as a label
+- **Errors say what happened, why, and what to do next.** No error codes alone, no blame
+- **Empty states teach.** What this is, why it is empty, one action to fill it
+- **Loading states say what is loading** when it takes more than a moment
+- **Confirmations state consequence and scope.** "Delete 14 records permanently?" not "Are you sure?"
+- **Headings are scannable.** A reader skimming only the headings should understand the page
+- **Sentence case** for interface text unless the brand demands otherwise. It reads faster
+- **No exclamation marks** as a substitute for value. No congratulating the user for routine actions
+- **Numbers are formatted** for locale, and units are always shown
+
+---
+
+## Voice
+
+Match the sector and audience established in `product-brief.md`. Terse and technical for developer tools. Plain and reassuring for health and finance. Warm for consumer. Neutral and unambiguous for enterprise.
+
+One voice throughout. A playful empty state inside a formal product reads as an accident.
+
+---
+
+## Content shapes the layout
+
+Design against realistic extremes before declaring a layout done:
+
+- the longest plausible name, title, and label
+- a translated string 40% longer
+- empty, one item, and hundreds of items
+- a missing image, a missing avatar, a null value
+- the largest number the field can hold
+
+A layout that only works with the copy that was invented for the mockup is not finished.

package/references/design-directions.md

@@ -0,0 +1,81 @@
+# Design Directions
+
+Pick a direction from the product. Never from what is trending.
+
+**Formula: one primary visual language + at most one supporting technique.**
+Editorial + subtle bento. Swiss + expressive display type. Minimal + restrained glass surfaces. Flat + purposeful motion. Stacking four trends is how interfaces start looking generated.
+
+---
+
+## Catalog
+
+| Direction | Reads as | Fits | Fails when |
+|---|---|---|---|
+| **Minimalism** | Calm, confident, content-first | Content products, tools, premium goods | Content is genuinely complex and needs scaffolding |
+| **Swiss / International** | Rigorous, objective, gridded | Editorial, data, institutional, portfolio | Product needs warmth or play |
+| **Editorial** | Authored, opinionated, typographic | Publishing, research, brand-led marketing, long-form | Task-heavy app screens |
+| **Neo-Brutalism** | Loud, honest, unpolished on purpose | Creative tools, youth brands, dev tools with attitude | Trust-sensitive sectors: finance, health, legal |
+| **Bento** | Modular, scannable, systematic | Feature overviews, dashboards, product tours | Used as a default grid for unrelated content |
+| **Glassmorphism** | Layered, atmospheric, soft depth | Media-rich surfaces, overlays over real imagery | Applied to flat backgrounds — becomes noise; hurts contrast |
+| **Neumorphism** | Tactile, soft, physical | Controls, audio/hardware-adjacent interfaces | Accessibility matters — contrast is inherently weak |
+| **Luxury / Premium** | Restrained, spacious, slow | Fashion, hospitality, high-value goods, private services | Users came to complete a task quickly |
+| **Corporate / Enterprise** | Reliable, legible, unsurprising | B2B platforms, internal tools, gov | It becomes an excuse for zero identity |
+| **Industrial** | Utilitarian, engineered, sturdy | Logistics, manufacturing, field ops, hardware | Consumer delight is the goal |
+| **Futuristic / Cyberpunk** | Technical, high-energy, synthetic | Gaming, crypto, security, entertainment | Legibility and trust are load-bearing |
+| **Retro / Y2K** | Nostalgic, playful, referential | Culture brands, music, indie products | Audience has no relationship to the reference |
+| **Soft UI / Organic** | Friendly, approachable, rounded | Wellness, kids, health, consumer habit apps | Precision and density are required |
+| **Flat / Material-inspired** | Familiar, systematic, efficient | Cross-platform apps, admin, mobile-first | Differentiation is the point |
+| **Maximalist** | Dense, expressive, layered | Culture, entertainment, editorial features | Users need to find one thing fast |
+| **Monochromatic** | Focused, disciplined, graphic | Tools, portfolios, brand sites | Color carries meaning (status, categories, data) |
+| **Dark UI** | Focused, cinematic, low-fatigue | Media, dev tools, monitoring, night use | Content is long-form reading or print-adjacent |
+| **Data-centric** | Dense, precise, scannable | Analytics, trading, observability, admin | The page is a marketing page |
+| **Typography-focused** | Voice-led, confident | Editorial, agencies, manifestos, docs | Product is visual or transactional |
+| **Image-led** | Aspirational, tangible | Commerce, travel, real estate, food | No real imagery exists and none can be produced |
+| **Experimental** | Memorable, risky | Portfolios, launches, campaigns | Anything with a conversion or task target |
+
+---
+
+## Selecting
+
+Weigh, in order: existing visual identity → sector expectations → audience → content type → primary task → brand personality. Trend relevance is a tiebreaker, never a driver.
+
+Sanity checks before committing:
+
+- Does the direction serve the *content* that actually exists?
+- Does it survive the worst case — long strings, empty states, 40 rows, one product photo?
+- Does it survive mobile?
+- Would a designer in this sector recognize it as competent, not costume?
+
+---
+
+## Presenting options
+
+Only when more than one direction genuinely fits. Three lines each, named, with the trade-off visible. Then ask.
+
+```
+Three directions fit this product:
+
+A. Editorial Minimal
+   Strong typography, generous whitespace, asymmetric composition.
+   Best if the writing carries the product. Slower to scan.
+
+B. Neo-Brutalist
+   High contrast, hard edges, bold type, expressive interaction.
+   Memorable and cheap to build. Polarizing for enterprise buyers.
+
+C. Premium Modern
+   Restrained palette, refined type, image-led composition.
+   Signals quality. Requires real photography.
+
+Which direction?
+```
+
+Do not force a choice when the product answers it. Say the direction, give the reason, keep going.
+
+---
+
+## Making a direction specific
+
+A named style is a starting point, not a design. Add at least two product-specific decisions that no other product would share — a layout that mirrors the actual workflow, a color drawn from the physical product, a type pairing from the sector's own history, a component shaped by the real data.
+
+Without those, "Editorial Minimal" is just another template.

package/references/design-system.md

@@ -0,0 +1,124 @@
+# Design System
+
+Define a small, coherent system before building many components. Small means enough to build the product and nothing more.
+
+Token groups: **color · typography · spacing · radius · elevation · borders · motion · breakpoints · icon sizing · component states**
+
+If the project already has tokens, extend them. Two competing systems is worse than an imperfect one.
+
+---
+
+## Color
+
+Define by role, never by literal name. `--color-danger`, not `--color-red-500` at the point of use.
+
+```
+background          page ground
+surface             card / panel ground
+surface-elevated    popover, modal, dropdown
+text                primary content
+text-muted          secondary content, metadata
+border              dividers, input outlines
+primary             brand / primary action
+primary-contrast    text on primary
+secondary           supporting action or accent
+success warning error info   state colors, each with a text-safe and a fill variant
+```
+
+Rules:
+
+- one primary. An interface with three "primary" colors has none
+- state colors are reserved for state. Never use `success` because green looked nice
+- verify contrast at definition time, not review time (see `accessibility.md`)
+- if the product is dark-mode-capable, define roles for both modes at once; do not invert at the end
+- never scatter literal hex values through components
+
+## Typography
+
+```
+family      display (optional) + body (+ mono if the product shows code or figures)
+scale       display / h1 / h2 / h3 / body-lg / body / body-sm / caption
+weight      2–3 weights maximum in use
+line-height tight for display, comfortable for body (roughly 1.1–1.3 vs 1.5–1.7)
+tracking    negative on large display sizes, neutral on body
+measure     ~60–75 characters for body text
+```
+
+Rules:
+
+- do not reuse the same font pairing in every project; pick for this brand
+- pick a scale ratio and stay on it; arbitrary sizes between steps break rhythm
+- tabular figures for anything numeric that aligns in columns
+- a heading level is a semantic rank, not a size. Style and semantics are set independently
+
+## Spacing
+
+One scale, used everywhere. A 4px base with steps at 4, 8, 12, 16, 24, 32, 48, 64, 96 covers most products.
+
+Rules:
+
+- `margin: 13px` in a project with a scale is a bug
+- space belongs to the container's rhythm, not to one-off overrides
+- define section rhythm too: the vertical gap between major page sections is a token, not a guess
+- related items sit closer than unrelated ones. Proximity is hierarchy
+
+## Radius
+
+Pick a character and hold it: sharp (0) · subtle (2–4px) · medium (6–10px) · rounded (12–16px) · pill (full, for chips and avatars only).
+
+Rules:
+
+- do not default everything to a large radius
+- nested radii: inner radius = outer radius − padding, or the corners look wrong
+- one exception can be deliberate (pill avatars in a sharp system). Five exceptions is noise
+
+## Elevation
+
+Shadows model distance from the page. Most flat content needs none.
+
+```
+0   flat content
+1   raised surface that can be interacted with
+2   dropdown, popover
+3   modal, dialog
+```
+
+Rules:
+
+- borders or surface contrast usually separate content better than shadows
+- never stack multiple shadows for "depth" without a light-source rationale
+- shadows in dark UI generally fail; use surface lightness instead
+
+## Borders
+
+Choose one strategy and apply it: border-led · shadow-led · surface-contrast-led · borderless. Mixing all four is what makes an interface look assembled.
+
+## Motion
+
+```
+duration   fast 120–160ms (hover, toggle)
+           base 200–260ms (dropdown, tab, expand)
+           slow 300–400ms (modal, page transition, large layout shift)
+easing     standard  ease-out for enter, ease-in for exit
+           emphasized for large movement
+```
+
+See `motion.md` for when motion is justified at all, and for choreography, performance, and reduced-motion rules.
+
+## Breakpoints
+
+Follow the project's existing breakpoints. Otherwise pick three to four and name them by intent, not device. Design the *content's* breakpoints: break where the layout stops working, not where a phone model happens to end.
+
+## Icon sizing
+
+Two or three sizes, tied to the type scale (16 / 20 / 24 typical). Icons align optically with the text they accompany, and inherit color from context. See `imagery-and-icons.md`.
+
+## Component states
+
+Every interactive component defines: default · hover · focus-visible · active · disabled · loading · and where relevant selected, error, empty, success. A component without a focus state is unfinished.
+
+---
+
+## Implementation
+
+Express tokens in whatever the project already uses: CSS custom properties, a theme file, a utility framework's config, platform resources. The mechanism matters less than the discipline — no literal values at the point of use, and no new value invented mid-build.

package/references/imagery-and-icons.md

@@ -0,0 +1,87 @@
+# Imagery and Icons
+
+---
+
+## Icons
+
+**Use the project's existing icon library.** Check the dependency manifest before anything else.
+
+If none exists, pick one and use only it: Lucide · Heroicons · Phosphor · Tabler · Radix Icons.
+
+### Rules
+
+- **Never hand-write an SVG for an icon the library already has.** Import it
+- **Never use emoji as UI icons.** They render differently per platform, ignore theme, carry unwanted tone, and announce badly to screen readers
+- one library per project. Mixed icon sets are visible instantly — different stroke weights, different grids
+- consistent semantics: one concept, one icon, everywhere. Trash means delete everywhere or nowhere
+- consistent size tokens, aligned optically to adjacent text (`design-system.md`)
+- icons inherit color from context; do not hardcode a color per icon
+- an icon-only control needs an accessible name and, on desktop, a tooltip
+- purely decorative icons are marked hidden from assistive technology
+- no icon soup: an icon beside every list item, heading, and label is noise. Icons mark *actions* and *status*
+
+Custom SVG is justified only for: the product's own logo or mark, a domain-specific glyph no library carries, or an illustration that is genuinely part of the design.
+
+---
+
+## Images
+
+Never invent an image, hotlink one, or embed an arbitrary asset. Mark the slot, state its purpose, and supply a generation prompt.
+
+### Placeholder
+
+Component form, when the project has or warrants one:
+
+```tsx
+<ImagePlaceholder
+  aspectRatio="16/9"
+  purpose="Hero — technician operating line equipment"
+/>
+```
+
+Markup-free form, for any stack:
+
+```
+[IMAGE PLACEHOLDER]
+Purpose:       Hero background, modern industrial workforce
+Aspect ratio:  16:9
+Negative space: left third, for headline and CTA
+```
+
+The placeholder must reserve the real aspect ratio so layout does not shift when the asset lands.
+
+### Every placeholder ships with a prompt
+
+Template: `../templates/image-prompt.md`. A usable prompt specifies:
+
+subject · composition · environment · lighting · camera or visual style · mood · color direction · aspect ratio · required negative space · elements that must not appear
+
+```
+Image Generation Prompt
+
+Wide cinematic photograph of a modern industrial workforce on a clean
+assembly floor: two technicians in safety gear reviewing a tablet beside
+automated equipment. Natural side light from high windows, soft falloff.
+Shot at 35mm, shallow depth of field, subject sharp, background softly
+blurred. Realistic commercial photography, not stock-posed. Muted steel
+and concrete palette with a single warm safety-orange accent. Composed
+with the subjects on the right third and clear negative space across the
+left third for headline and CTA text. 16:9.
+
+Must not appear: logos, readable text, faces looking at camera, lens
+flare, HDR over-processing, generic smiling stock poses.
+```
+
+### Rules
+
+- images serve UX or storytelling. Never fill space with an image
+- one hero image with a job beats four decorative ones
+- specify the aspect ratio and hold it responsively; art-direct the crop per breakpoint when the subject demands it
+- every content image gets real alt text; decorative images are marked as decorative (`accessibility.md`)
+- define loading behavior: dimensions reserved, lazy below the fold, priority for the hero
+- state the format expectation (modern format with fallback) so the slot is production-ready
+- when real assets already exist in the project, use them instead of a placeholder
+
+### Illustration and graphics
+
+Prefer real artifacts — product screenshots, charts from real data, maps, documents — over abstract illustration. Abstract illustration is the default when there is nothing to show, and it usually means the section has nothing to say.

package/references/motion.md

@@ -0,0 +1,186 @@
+# Motion
+
+Motion is an interface material, not decoration. It costs attention, battery, and comprehension when misused.
+
+**A motion is justified only if removing it would make something harder to understand.** If nothing is lost, remove it.
+
+---
+
+## The six legitimate jobs
+
+| Job | What it does | Example |
+|---|---|---|
+| **Feedback** | Confirms input was received | Press state, toggle flip, button spinner |
+| **Continuity** | Preserves object identity across a change | A list item expanding into a detail view |
+| **Hierarchy / spatial** | Shows where something came from and where it lives | Menu scaling from its trigger, drawer from its edge |
+| **Progress** | Communicates that time is passing and how much | Skeletons, determinate bars, step transitions |
+| **Attention** | Directs the eye to a genuine change | A row that just updated, a validation error appearing |
+| **Brand** | Carries personality in a moment that already needed motion | The character of an easing curve, one signature transition |
+
+Brand is last and rides along with the others. It never justifies motion on its own.
+
+---
+
+## Tokens
+
+Define once, in the design system, and use everywhere.
+
+```
+duration-instant   80–120ms    press feedback, color change
+duration-fast      140–180ms   hover, small toggles, tooltips
+duration-base      200–260ms   dropdowns, tabs, accordions, small dialogs
+duration-slow      280–400ms   modals, drawers, large layout change, page transitions
+```
+
+```
+ease-out           entering elements, most UI motion
+ease-in            exiting elements, and faster than the enter
+ease-in-out        elements that move within the view and stay
+spring / emphasized  direct-manipulation gestures and large expressive movement
+linear             only for continuous indeterminate motion: spinners, marquees
+```
+
+Rules of thumb:
+
+- exit is faster than enter. Nobody wants to wait to dismiss something
+- larger distance and larger surface get longer durations. A tooltip at 300ms feels broken; a full-screen sheet at 120ms feels like a glitch
+- anything over ~400ms on a routine interaction reads as lag, not polish
+- ease-out for almost everything. Linear on UI movement looks mechanical
+
+---
+
+## Choreography
+
+- one thing leads. If three elements animate at once, either they are one group moving together, or the design has no focal point
+- stagger sparingly: 20 to 40ms between items, capped at roughly five items. Longer chains turn into a wait
+- animate **from the origin**: a menu grows from its trigger, a sheet slides from the edge it lives on, a detail view expands from the row that opened it
+- keep the transform origin and the movement direction consistent across the product. Inconsistent direction destroys the spatial model
+- continuity beats fade. When the same object exists before and after, move it; do not cross-fade one into the other
+- when a shared-element transition is not feasible, a short cross-fade with a small positional shift is the honest fallback
+
+---
+
+## Per-component catalog
+
+| Interaction | Treatment |
+|---|---|
+| Hover | Color, elevation, or 1 to 2px movement at fast duration. Not scale on large surfaces |
+| Press | Instant, slightly inset or dimmed. Never delayed |
+| Focus | Instant. A focus ring must never animate in — it must be there the moment focus lands |
+| Toggle / switch | Knob travel plus track color, fast, with a distinct disabled treatment |
+| Accordion / expand | Height and opacity together at base duration; content does not fade in after the box opens |
+| Dropdown / popover | Scale from 0.96 plus fade, base duration, origin at the trigger |
+| Tooltip | Fade only, fast, after a short open delay and with no delay on close |
+| Modal | Backdrop fade plus content scale or rise at slow duration; exit at base |
+| Drawer / sheet | Slide from its own edge, slow; drag-to-dismiss follows the finger 1:1 |
+| Tabs | Indicator slides between tabs; panel content cross-fades quickly |
+| Route change | Short directional transition matching navigation direction; back reverses it |
+| List insert / remove | Neighbors move to their new positions so the user can track the change |
+| Reorder / drag | Item follows the pointer exactly; others shift with a base-duration transition |
+| Toast | Enter from a consistent edge, auto-dismiss with a visible timer or a pause on hover |
+| Validation error | Appear without shifting the layout. No shake unless the product's voice earns it |
+| Number / value change | Brief highlight of the changed value, not a counting animation, unless the count is the point |
+
+---
+
+## Loading and waiting
+
+Match the treatment to the wait:
+
+| Wait | Treatment |
+|---|---|
+| Under ~100ms | Nothing. A spinner that flashes is worse than no spinner |
+| 100ms to 1s | Inline indicator on the control that was activated |
+| 1s to 10s | Skeleton matching the final layout, or a determinate progress bar |
+| Over 10s | Determinate progress, a step description, and a way to cancel or leave |
+
+- skeletons mirror the real layout so nothing shifts when content lands. A skeleton that does not match is a second layout shift
+- keep skeleton shimmer subtle, or use a static tint. Aggressive shimmer across a full page is visual noise
+- optimistic updates respond immediately and reconcile on completion, with a clear, non-destructive rollback if the request fails
+- never let a spinner replace content that is already on screen. Update in place
+
+---
+
+## Scroll
+
+- scroll-driven progress indicators and sticky transitions are fine. Content that animates in on every scroll is not
+- if content animates on entry, it must be visible without JavaScript and without the animation. Never gate content on an intersection observer firing
+- parallax at most as a subtle depth cue on one element. Multi-layer parallax is a motion-sickness trigger and a performance cost
+- no scroll hijacking. The user owns the scroll
+- honor native smooth-scroll preferences instead of forcing a custom implementation
+
+---
+
+## Performance
+
+- animate **transform and opacity**. Both run on the compositor. Animating width, height, top, left, or margin forces layout on every frame
+- when a size change is required, prefer a transform-based technique or accept the cost knowingly on a small element
+- budget: 60fps, roughly 16ms per frame. Verify on a mid-range device, not a development laptop
+- `will-change` only immediately around the animation, on a small number of elements. Left on permanently, it wastes memory and can make things worse
+- avoid animating many elements at once on long lists; virtualize or cap the animated set
+- no infinite animations off-screen. Pause when not visible
+- prefer the platform's own transition primitives before adding an animation library (`packages.md`)
+
+---
+
+## Accessibility
+
+Reduced motion is a **replacement**, not a deletion. The information the motion carried must still arrive.
+
+| Full motion | Reduced motion |
+|---|---|
+| Slide-in drawer | Instant appearance, or opacity only |
+| Expanding detail view | Instant expand; keep the focus move |
+| Parallax and scroll effects | Off entirely |
+| Auto-advancing carousel | Stops; manual controls remain |
+| Attention pulse | Static highlight or a border change |
+| Page transition | Instant, with focus moved to the new heading |
+| Spinner | Keep it, but reduce or stop rotation; keep the text label |
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+That blanket rule is a floor, not a strategy. Where motion carried meaning, provide the reduced alternative explicitly. Express the equivalent in whatever the project's platform offers.
+
+Also:
+
+- motion is never the only channel carrying meaning. Pair it with text, state, or position
+- nothing flashes more than three times per second
+- anything moving or auto-updating for more than five seconds needs pause, stop, or hide controls
+- motion must not steal focus or move focus unexpectedly
+
+---
+
+## Anti-patterns
+
+- entrance animation on every element as the page scrolls
+- perpetual floating, bobbing, pulsing, or breathing elements
+- bouncy overshoot in a professional or high-trust product
+- animating a change the user did not cause
+- decorative background loops, animated gradients, particle fields
+- staggered chains longer than about five items
+- transitions on elements that update frequently — the interface never settles
+- carousels that auto-advance with no pause
+- loading animations longer than the load
+- motion that delays the user reaching content
+
+---
+
+## Checklist
+
+1. Every animation maps to one of the six jobs.
+2. Durations and easings come from tokens, not per-component guesses.
+3. Exits are faster than enters.
+4. Movement originates where the user acted.
+5. Only transform and opacity animate in hot paths.
+6. Reduced motion has an explicit alternative, not just removal.
+7. Nothing animates that the user did not trigger, except state they need to notice.
+8. Verified on a mid-range device, not only on a fast one.