@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/ui-ux-design/skills/ui-ux-design/references/premium-ui.md

@@ -0,0 +1,55 @@
+# Premium UI
+
+Premium web and product UI guidance: raising perceived quality without sacrificing
+clarity, conversion, performance, accessibility, or maintainability.
+
+This file routes premium-design methods. It does not define another universal
+workflow, completion checklist, or implementation contract; use `ui-loop.md` for
+completion review. Its final output section only names source-specific decisions to
+capture when these methods are used.
+
+Load for websites, landing pages, SaaS screens, hero sections, service pages,
+ecommerce pages, portfolios, dashboards, and UI copy where the ask is a premium,
+expensive, luxury, high-converting, agency-grade, high-trust, or visually elevated
+result.
+
+## Choose The Design-School Notes
+
+Never gate these notes on the user naming their sources. Select them from the actual
+surface and scope:
+
+An earlier version gated them on the user naming a source, a condition that rarely
+fired; premium work then used this summary alone and became templated. The current
+router gates on surface breadth instead. Keep the ambiguous-case default at “load
+all three” so the same failure does not return under a different trigger.
+
+- **Broad, open-ended, hybrid marketing/product, ecommerce, or high-stakes premium
+  work:** load all three.
+- **Clearly narrow marketing/first-impression work:** load Sam Crawford and
+  Self-Made Web Designer.
+- **Clearly narrow product UI, dashboard, or admin work:** load Self-Made Web
+  Designer and Kole Jain.
+
+When scope is ambiguous or crosses categories, load all three. Together they are
+about 19KB (~5k tokens); the specific methods live in the notes, not this router.
+
+| File | What it gives you |
+|---|---|
+| `sam-crawford-premium-websites.md` | Premium-website psychology and constraints — halo effect, cognitive fluency, peak-end moments, bespoke/real assets, commercial filtering, client ownership, and post-launch care. |
+| `self-made-web-designer-core-skills.md` | The repeatable fundamentals — typography, layout, spacing, color, code literacy, conversion thinking — plus fast upgrades to an existing site: font pairing, a focal visual idea, visual rhyming, depth, opacity hierarchy, and forcing divergent variants instead of shipping the first workable one |
+| `kole-jain-uiux-concepts.md` | Product-UI treatments — signifiers and affordances, contextual grids, typography ranges, color semantics, dark mode, shadows, icons/buttons, micro-interactions, and text-over-image overlays |
+
+They are design schools, not absolute rules. When they conflict, state the
+tradeoff, pick the advice that best fits the product, audience, and business goal,
+and avoid blending incompatible aesthetics without a clear reason.
+
+## Reference-Specific Output
+
+When this router is activated, record the applicable premium decisions:
+
+- first-impression target
+- visual hierarchy and layout direction
+- asset and imagery plan
+- copy and CTA approach
+- interaction and animation restraint
+- risks or tradeoffs around performance, accessibility, conversion, and maintainability

package/ui-ux-design/skills/ui-ux-design/references/research-and-validation.md

@@ -0,0 +1,88 @@
+# Research and Validation
+
+Use this reference when the design needs a validation plan, clearer user framing, or a way to separate assumptions from evidence.
+
+This file owns proposed evidence-gathering, not visual self-review. Use `ui-loop.md`
+for the design gate.
+
+## Important Constraint
+
+Do not present invented research as completed research. Use this reference to structure:
+
+- proposed research plans
+- user hypotheses
+- validation criteria
+- usability-test plans
+
+## Useful Artifacts
+
+### Proto-Persona
+
+Use when real research does not yet exist.
+
+Include:
+
+- user type
+- main goals
+- main frustrations
+- environment/context of use
+- skill level
+- critical accessibility considerations
+
+Label it explicitly as a working assumption.
+
+### Journey Snapshot
+
+Map:
+
+- trigger
+- entry point
+- main steps
+- friction points
+- moments of uncertainty
+- completion state
+- follow-up state
+
+### Usability-Test Plan
+
+Define:
+
+- research questions
+- participant criteria
+- tasks to complete
+- success criteria
+- metrics to watch
+- qualitative prompts
+
+### Validation Plan Contract
+
+Map each uncertain user or usability claim to a research question, participant or
+evidence source, task, success criterion, and decision the result would change.
+Keep untested claims labeled as hypotheses.
+
+### Reference-Specific Validation Questions
+
+Use these to decide what the research or usability plan must observe; do not treat
+untested answers as evidence:
+
+- does the layout support the primary user goal quickly
+- are key decisions reversible
+- do labels match user language
+- are errors recoverable
+- is the empty state actionable
+- is keyboard/mobile usage still workable
+
+## When This Reference Is Worth Loading
+
+- dashboard or workflow-heavy UI
+- ambiguous user roles
+- onboarding flows
+- high-risk UX with multiple steps
+- claims about "user needs" that need structure
+
+## Anti-Patterns
+
+- pretending empathy maps are evidence
+- writing personas with no behavioral relevance
+- validation plans with no measurable success criteria
+- feature flows optimized for internal assumptions only

package/ui-ux-design/skills/ui-ux-design/references/sam-crawford-premium-websites.md

@@ -0,0 +1,103 @@
+# Sam Crawford Premium Website Notes
+
+Source context: extracted from user-provided transcript files attributed to Sam Crawford / bycrawford, including:
+
+- `Brutally Honest Advice About Web Design in 9 mins.txt`
+- `How To Build a Website SO Premium They Beg You To Buy.txt`
+- `The Psychology of Premium Websites.txt`
+
+The duplicate file `Brutally Honest Advice About Web Design in 9 mins (1).txt` was ignored because it matched the non-suffixed file byte-for-byte.
+
+The later pasted checklist `How to Build a Website So Premium People Trust You Instantly` was reviewed and treated as redundant with this reference. It restates the same system around intentional first impression, bespoke assets, brand foundations, subtle animation, strategic structure, client autonomy, and handover/post-launch care.
+
+## Core Thesis
+
+Premium websites create a fast feeling of quality, trust, and authority through intentional first impressions, clarity, bespoke visual systems, and restrained details. The goal is not just to look impressive; the site must help the right visitor understand the offer, trust the business, and take the next action.
+
+## Psychological Principles
+
+- **Halo effect:** visitors form an initial judgment extremely quickly, and that judgment colors how they interpret the rest of the site. Treat the hero and first viewport as the highest-value real estate.
+- **Cognitive fluency:** people trust experiences that are easy to process. Reduce confusion with simple navigation, strong hierarchy, predictable layouts, clear copy, and generous spacing.
+- **Peak-end rule:** users remember standout moments and the ending more than the average of the whole experience. Use micro-interactions, confirmation states, polished transitions, and good completion moments to create small positive peaks.
+- **First-impression feeling:** name the intended immediate feeling—calm,
+  confidence, authority, excitement, exclusivity, technical competence, or another
+  product-specific target—before selecting premium signals.
+- **Blink test:** expose the composition only briefly, then check what remains in
+  memory. The offer or current task, intended audience, and next action should
+  survive the glance.
+
+## Premium Signals
+
+- Use bespoke assets instead of generic icons, default templates, and disconnected stock imagery.
+- Make graphics serve a purpose: break up content, guide the eye, clarify the message, or reinforce the brand.
+- Use a professional logo, cohesive color palette, and thoughtfully chosen fonts as the foundation.
+- Prefer real imagery, even imperfect real imagery, when it proves that the business is genuine.
+- Use metrics, case studies, real faces, and specific proof where they build trust faster than paragraphs.
+- Give the design a point of view so the business does not look interchangeable with competitors.
+
+## Copy And Content
+
+- Write for scanners. Use short sections, obvious headings, bolded essentials, and copy that can be understood at a glance.
+- Cut weak copy aggressively. If removing a sentence does not make the page worse, remove it.
+- Sell the result or transformation, not the internal feature list.
+- Make the about page reassure the visitor: credibility, understanding of their problem, proof of having solved it before, and the transformation created.
+- Be explicit about who the offer is for and who it is not for.
+- Where commercially appropriate, show pricing or at least a starting point to filter the wrong leads and attract qualified buyers.
+
+## Structure And Conversion
+
+- Give each page a purpose and a next step.
+- Make the CTA obvious, easy to find, and easy to take.
+- Use fewer, stronger pages instead of many mediocre pages.
+- Ensure the site map, page hierarchy, internal linking, and content organization make sense for both people and search engines.
+- Do not bury the main action in the footer or force visitors to guess the next logical step.
+- Treat confusion as a conversion leak.
+
+## Animation And Interaction
+
+- Use subtle motion for feedback, orientation, and attention guidance.
+- Good examples: button hover response, natural content fade-in, smooth transitions, useful form validation feedback.
+- Avoid animation that becomes the thing people notice instead of the offer.
+- Avoid heavy 3D, parallax, or scroll effects when they slow the site, overwhelm the visitor, or distract from the message.
+- Respect reduced-motion preferences and performance budgets.
+
+## Performance And Practicality
+
+- A premium site must feel fast, especially on mobile and weak connections.
+- Compress images, avoid bloated plugins, and question every unnecessary animation or asset.
+- Test outside the designer's ideal setup: mobile viewport, slower network, and realistic user paths.
+
+## Commercial And Ownership Constraints
+
+- Avoid black-box builds when client ownership matters. A premium site should be practical to update, not a trap that requires a developer for every content change.
+- Treat launch as the start: collect data, test, optimize, add fresh proof, and keep the site current.
+
+## Applying These Principles
+
+Use `ui-loop.md` for generic design and rendered review. This reference contributes
+premium psychology, signal selection, copy/conversion techniques,
+motion/performance examples, and commercial/ownership constraints.
+
+Client ownership, maintainability after launch, and future optimization remain
+additional product constraints when the brief includes them. Record those in the
+design output rather than turning them into universal visual checks.
+
+## Reference-Specific Output
+
+- first-impression psychology and selected premium signals
+- scanner-oriented copy, proof, and qualification decisions
+- CTA/page-purpose and information-architecture implications
+- motion and weak-connection performance constraints
+- client ownership and post-launch maintenance requirements
+
+## Conflict Handling For Future References
+
+If another reference recommends a different direction, resolve the conflict by asking:
+
+1. What audience is this for?
+2. What feeling should the first impression create?
+3. What business action should the page drive?
+4. Which advice improves clarity, trust, and conversion for this context?
+5. Which advice introduces avoidable risk in performance, accessibility, or maintainability?
+
+Document the chosen direction briefly instead of silently merging incompatible advice.

package/ui-ux-design/skills/ui-ux-design/references/self-made-web-designer-core-skills.md

@@ -0,0 +1,119 @@
+# Self-Made Web Designer Core Skills Notes
+
+Source context: extracted from user-provided transcript files attributed to Self-Made Web Designer:
+
+- `The Only 5 Web Design Skills That Actually Matter (2025).txt`
+- `6 Tips to 10x ANY Site's Design.txt`
+
+## Core Thesis
+
+Strong web design comes from a small set of repeatable fundamentals: typography, layout, color, code literacy, and conversion thinking. Premium polish is not just taste; it comes from systems, deliberate focal ideas, and enough iteration to avoid settling for the first workable version.
+
+## The Five Skills
+
+### Typography
+
+- Treat typography as the largest visual surface on most websites.
+- Pick fonts that match the project's personality instead of defaulting to the same overused free fonts.
+- Consider less common free or affordable sources such as Fontshare and Uncut when a project needs more personality.
+- Build a type scale instead of eyeballing sizes. Start with a base body size, often around 16px, then scale headings consistently.
+- Use `rem` values where practical so type scales remain systematic.
+- Keep body text letter spacing at the default for legibility.
+- Tighten heading letter spacing and line height only where the larger type benefits from more impact.
+- Use about 150% line height for paragraph text as a starting point.
+
+### Layout
+
+- Use systems rather than dragging elements until they feel right.
+- Start from a responsive column grid: 12 columns on desktop, 8 on tablet, and 4 on mobile is a useful default.
+- Use an 8-point spacing system for rhythm: 8, 16, 24, 32, and so on.
+
+### Color
+
+- Use the 60/30/10 rule as a starting point: neutral/background/text colors, supporting colors, and accent colors for CTAs or emphasis.
+- Prefer opacity and tints from a core color before adding more unrelated colors.
+- Borrow and refine proven palettes rather than inventing every palette from scratch.
+- Use browser tooling such as Chrome DevTools CSS Overview to inspect real sites' color and type systems.
+
+### Code Literacy
+
+- Learn enough HTML, CSS, JavaScript, and platform-specific basics to understand what the design requires and how to adapt it.
+- A designer does not need to become a full-stack developer, but code literacy separates practical designers from purely visual ones.
+- Start from examples, snippets, CodePen, or generated code that gets most of the way there, then adjust the final behavior and polish.
+- Design with implementation constraints in mind.
+
+### Conversion
+
+- Design for action, not just looks.
+- Give every page one primary goal: buy, book, sign up, download, or another clear action.
+- Put a clear CTA in the hero, navigation, and at logical intervals down the page.
+- Build trust with clarity, emotion, testimonials, reviews, and social proof.
+- Make users know, like, trust, and feel something from the brand.
+- Do not improve visual style at the cost of the user journey.
+
+## Six Fast Upgrade Techniques
+
+### 1. Upgrade Typography With Font Pairing
+
+- One-font sites can work, but stronger visual character often comes from a better pairing system.
+- Use superfamilies when you want cohesion with low risk.
+- Use separate font families when you need more personality, but ensure they feel from the same world.
+- Choose an anchor font first. For many web pages, the headline font is the best anchor because it sets the personality.
+- Pick supporting fonts that contrast enough to add interest without feeling accidental.
+- Avoid pairings that are almost the same but slightly different; they often look unintentional.
+- Use references such as Fonts In Use to see proven pairings for a chosen anchor font.
+
+### 2. Create A Star Of The Show
+
+- A website is often the first meeting with a brand, so it should make the visitor feel something.
+- Pick one visual idea that anchors attention long enough for the visitor to understand and act.
+- The star can be a font, image, object, illustration, product visual, gradient, chart motif, or interactive element.
+- Connect the star to the story of the site rather than choosing it only because it looks cool.
+- Let surrounding design decisions grow from that focal idea.
+
+### 3. Use Visual Rhyming
+
+- Repeat details from the core visual idea across the page so everything feels from the same universe.
+- Rhyming can happen through shapes, colors, textures, gradients, masks, icons, card treatments, buttons, or link details.
+- Pull pieces from the strongest visual element and reuse them in secondary elements.
+- Use repetition to create cohesion, not clutter.
+
+### 4. Add Subtle Depth
+
+- Use depth to make digital interfaces feel more tangible.
+- Examples include light texture, noise, glass effects, layered cards, shadows, dimensional product elements, or 3D details.
+- Keep depth subordinate to the star of the show.
+- Avoid depth that competes with copy, harms readability, or looks like decoration pasted on top.
+
+### 5. Use Opacity For Hierarchy
+
+- Do not make every text element equally loud.
+- Keep the most important headline or action at full emphasis.
+- Lower opacity for supporting text, metadata, captions, muted navigation, or less important labels.
+- Use opacity deliberately to help the eye know what to read first, skim second, and ignore unless needed.
+- Maintain sufficient contrast for accessibility.
+
+### 6. Explore Strong Variants
+
+- Do not keep polishing only the first idea.
+- Create intentionally different versions: light and dark modes, different layout structures, different focal visuals, different font anchors, or different image concepts.
+- Push far enough away from the first version to reveal better possibilities.
+- Compare variants against the page goal, first-impression target, readability, and conversion path.
+
+## Applying These Principles
+
+The canonical UI Loop handles generic design and rendered review. This reference
+contributes candidate construction heuristics—type scales, grids, spacing, palette
+ratios, font pairing, focal ideas, visual rhyming, depth, and opacity hierarchy—not
+a second definition of quality.
+
+The Web Design persona's Principal Direction Pass owns when and how many variants to
+generate. This section supplies possible axes of divergence only.
+
+## Reference-Specific Output
+
+- selected type-scale, grid, spacing, and palette heuristics
+- font-pairing or single-family decision
+- focal “star of the show” and its connection to the page story
+- visual-rhyming, depth, and opacity-hierarchy rules
+- variant axes explored and the selected direction

package/ui-ux-design/skills/ui-ux-design/references/ui-animation.md

@@ -0,0 +1,173 @@
+# UI Animation
+
+> Maintained in AI-Dev-Shop. Downstream copies are synced from here; edit it in
+> AI-Dev-Shop, not in a downstream copy.
+
+Use this reference when implementing any animation: scroll reveals, text reveals,
+transitions, pinned or scroll-linked sections, or micro-interactions.
+
+This file owns **how** to animate: library choice, implementation defaults, and
+micro-interaction recipes. It does not restate what siblings own:
+
+- `delight-and-motion.md`: where delight belongs, intensity, microcopy.
+- `ui-loop.md`: the final restraint and motion review (category 6) and the
+  accessibility baseline (category 8), including "understandable with reduced motion".
+- `components-and-states.md`: which states each component needs and its interaction
+  rules (feedback timing, optimistic vs confirmed feedback).
+- `foundations.md`: motion duration and easing as design tokens.
+- `kuinetic-reference.md`: kUInetic syntax and every effect name used below.
+- The `impeccable` skill's `reference/animate.md`, when installed: the motion thesis,
+  choosing material by meaning, the duration-by-consequence table, and the default
+  arrival curve. Use its numbers; this file does not repeat them.
+
+## Library Choice: kUInetic First
+
+1. **Detect kUInetic before writing any motion.** Use the signals in
+   `kuinetic-reference.md` → Detect: `data-kui` in markup, a `vendor/kuinetic/` folder,
+   a `kuinetic*.js` script tag, the `kuinetic` package, or `window.__kuinetic`.
+2. **Present: use its attributes.** Express every effect the catalog names as `data-kui`.
+   Do not hand-write CSS or JS for an effect it provides. Do not load GSAP, Motion,
+   AOS, Animate.css or any second animation library for something it covers.
+3. **Extend before escaping.** Compose effects with commas, sequence them with `at:`,
+   name repeated compositions with `data-kui-define`, retarget with `target:`, and use
+   `tween`/`tween-from` for supported properties outside a named preset (it has a fixed
+   property list that excludes `width`, `height`, `top`, `left` and skew) before writing
+   custom code.
+4. **No matching effect: native CSS.** Transitions, `@keyframes`, `@starting-style`,
+   View Transitions, or scroll-driven `animation-timeline` behind `@supports`. Reuse the
+   same duration and easing tokens. Never animate a property a `data-kui` effect already
+   owns on the same element.
+5. **Absent: native CSS first.** Propose adding kUInetic only when the surface needs
+   several of its effects and adding a dependency is in scope; never for one effect.
+6. **Vendored copies lag.** Confirm a recent option exists in the shipped bundle before
+   using it (`kuinetic-reference.md` → Version lag).
+
+## Implementation Defaults
+
+### Timing And Easing
+
+- With kUInetic, keep its per-effect defaults (entrance 600ms `ease-out`, hover 220ms,
+  press 120ms, counters 1600ms). Override per element only to match a project token.
+- Without it, take durations from impeccable's table and store them as tokens.
+- Match the curve to direction: entering decelerates (`ease-out`, `expo-out`,
+  `quart-out`); leaving accelerates (`ease-in`); moving between two on-screen states
+  uses `ease-in-out`; `linear` only for continuous rotation, progress, and scrubbing.
+- Overshoot (`back-out`, `spring(bounce:…)`) only on small, rare confirmations such as a
+  badge or count bump, never on layout or page-level motion.
+- Entrance travel 8–24px. Longer travel reads as slow, not premium.
+
+### Staggering
+
+- Stagger only siblings that read as a list or grid. To start the group together, put
+  the effect on the parent with `target:`: `data-kui="fade-up target:'.card' cascade:60ms"`.
+  The matched children share one activation. `data-kui-stagger` alone only sets delays;
+  children with their own `data-kui` keep their own triggers.
+- Step 30–90ms per item. For a list of unknown length, budget the total with
+  `spread:` (≤ 600ms) instead of a per-item step.
+- Split text: keep kUInetic's unit defaults (chars 30ms, words 90ms, lines 160ms).
+  Prefer lines or words for headlines; chars only for short display text.
+- Use `cols:` with `order:center` only when the grid reads two-dimensionally.
+
+### Scroll Reveals
+
+- Reveal once (`on:enter`). Use `enter/leave` only for decoration, never for content.
+- Fire when a meaningful part is visible: `threshold:10%`–`30%` (kUInetic default `0%`).
+- Never delay or hide the hero heading, LCP image, or anything visible at load.
+- Content must render without JS. With kUInetic, opt into `<html data-kui-cloak>`,
+  which fails open. Hand-written: for a JS-driven reveal, set the hidden from-state only
+  under a class that JS adds, never in base CSS. `@supports` alone does not fail open,
+  because it stays true when scripts fail; use it alone only when a complete CSS
+  animation also restores visibility.
+- Pick one reveal (effect, distance, duration) per page and repeat it; do not invent a
+  new entrance per section.
+- A hidden element (`display: none`, a closed `<dialog>` or popover) cannot trigger a
+  visible entrance while closed. For opening transitions, especially repeated ones, use
+  the open/close family (`fade-open`, `pop-open`) or `@starting-style`.
+
+### Pinned And Scroll-Linked Sections
+
+- Trigger (time-based, plays on enter) by default. Scrub (`timeline:view`, `scroll`, `pin`)
+  only when scroll position is the meaning: progress, scrollytelling steps, before/after.
+- Each pinned viewport of `distance:` must deliver a new step. Budget 1–2 viewports per
+  idea; long pins read as broken scroll.
+- Clear fixed headers once with `--kui-pin-offset` on `:root`, not per pin.
+- Animate inside a pin with `timeline:pin`; a `view` timeline stalls while pinned.
+- Size pinned and stacked content to the visible viewport, fixed bars included. Verify
+  phones and short viewports with the touch-scroll check in `ui-loop.md` (section 7) and
+  `chrome-mobile-test-matrix.md`.
+
+### Reduced Motion
+
+The baseline is `ui-loop.md`. Animation-specific rules:
+
+- Set a policy per effect, not one global `0.01ms` kill. In kUInetic, `rm:` and the
+  resolved policy apply to the whole attribute, including its `target:` groups, and the
+  strictest policy wins; put effects that need different policies on separate elements. Short state feedback is
+  shortened or crossfaded so the change is still visible; spatial, continuous,
+  parallax, pinned, autoplaying, and scroll-linked motion is disabled to its end state.
+- Never strand an element at its from-state (`opacity: 0`, offset).
+- kUInetic applies this automatically (`kuinetic-reference.md` → Reduced Motion).
+  Tighten one element with `rm:`; do not add your own overrides on `data-kui` elements.
+- A disabled spinner or skeleton shimmer still needs a non-motion loading signal: text,
+  `aria-busy`, or a static placeholder.
+- Do not hang logic on `animationend` or `kui:start`. kUInetic still emits `kui:finish`
+  (`reason: 'reduced-motion'`) for skipped effects; hand-written code must too.
+- JS-driven motion reads `matchMedia('(prefers-reduced-motion: reduce)')` and listens
+  for its `change` event. kUInetic's CSS responds live, but its JS policy is a startup
+  snapshot: to honour a mid-session change, the app tears the animator down and recreates
+  it with fresh capabilities (`capabilities: detect(true)`).
+
+## Micro-Interactions
+
+States come from `components-and-states.md`; the recipes below only say how each one
+moves. Durations are ranges; pick one per project and tokenise it.
+
+| Interaction | What moves | Duration / easing | Reduced motion | kUInetic | Without kUInetic |
+|---|---|---|---|---|---|
+| Hover | 2–6px lift, tint, underline, or sheen | 150–220ms `ease-out` | Shortened; color change stays | `lift` `lift-shadow` `pop` `underline-slide` `shine-sweep` `border-glow` | `transition` on `translate`/`background-color` inside `@media (hover: hover)` |
+| Press / active | Scale to 0.96–0.98 or 1–2px down | 80–120ms in, ~150ms release, `ease-out` | Instant | `press-depth`; `ripple` for centered click feedback (it scales from the center, not from the pointer) | `:active { scale: 0.97 }` with a short transition |
+| Focus-visible | Ring appears; optional grow | ≤150ms `ease-out` | Ring shown at once | `focus-ring-grow`; hover effects ship focus-visible twins | `:focus-visible` outline plus `outline-offset` transition |
+| Loading | Spinner rotation, shimmer, indeterminate bar | Show after ~300ms; rotate 700–1000ms `linear` | Static placeholder plus text | `spinner` `spinner-dots` `spinner-ring` `skeleton-shimmer` `progress-indeterminate` | `@keyframes` rotate; delayed reveal via class |
+| Loading → content | Content fades in where the skeleton was | 200–300ms `ease-out` | Instant swap | Replace the skeleton through application state; put `skeleton-to-content` on the content node and start it with `kui.activate(el)` when data lands (it fades the content in; it does not crossfade from the skeleton) | Opacity transition on a `data-loaded` attribute |
+| Success | Check draws or label fades in, holds | 200–400ms `ease-out` | Instant | `validate-check` `checkmark-draw` `badge-pop` | `stroke-dashoffset` keyframes |
+| Error | One small horizontal shake | 300–500ms, once | No shake; icon, message, color | `shake-error` (`data-kui-on="invalid"`) `validate-shake` | `translate` x keyframes, ≤ 6px |
+| Toggle / switch | Thumb slides; track color crossfades | 150–250ms `ease-in-out` | Instant; position still shows state | `toggle-morph` (checkbox + `.kui-track > .kui-thumb`) `checkbox-draw` `radio-fill`; `hamburger-to-x` `plus-to-minus` keyed to `aria-expanded` | `:checked ~ .track` transition on `translate` |
+| Counter / ticker | Number counts to its value; bump on change | Count 800–1600ms `ease-out`; bump 200–300ms `back-out` | Final value shown | `count-up` `count-currency` `count-percent` `count-compact` `odometer-roll`; `count-bump` on updates | rAF tween of the text with `font-variant-numeric: tabular-nums` |
+| Copy to clipboard | Label or icon swaps to "Copied", holds 1–2s, reverts | 150ms fade in, ~200ms out | Instant swap; the app keeps "Copied" visible for the hold | The app owns a visible "Copied" status for the hold period; `copy-confirm` (`data-kui-on="manual"`, `kui.activate(label)` after `writeText()` resolves) is extra animation only, since under reduced motion it runs in ~1ms and ends hidden | Toggle a `data-copied` attribute and transition opacity |
+| Optimistic UI | Result applies at once; list items move into place | FLIP 200–300ms `ease-out` | Instant reorder | `flip-reorder` `flip-filter` `flip-sort`; `count-bump` for counts | FLIP with `translate`, or the View Transitions API |
+
+Recipe rules:
+
+- Count and copy confirmations announce through an `aria-live="polite"` region; the
+  motion is not the announcement. kUInetic counters already expose the final value.
+- Author counters with their final value as text, never `0`.
+- Show a copy or optimistic failure as visibly as the success: revert the change, then
+  give the error state its own motion and message.
+- `submit-to-spinner-to-check` runs on fixed timers with no error stage. Drive real
+  request state yourself.
+- Celebration effects such as `heart-burst` or `confetti-burst` follow
+  `delight-and-motion.md`; never add them as routine feedback.
+
+## Implementation Anti-Patterns
+
+- Hand-writing an effect kUInetic already provides, or loading a second motion library
+  beside it.
+- Incidental layout animation: `width`, `height`, `top`, `left`, or margins changing as a
+  side effect. Use `transform`/`opacity` or FLIP (the `flip-*` family). Expanding content
+  is the deliberate exception: `accordion-height` animates measured pixel heights, and
+  `grid-template-rows: 0fr → 1fr` also changes layout. For the grid trick, use one inner
+  child with `min-height: 0; overflow: hidden`, and keep collapsed content out of the
+  focus order separately (for example `inert`).
+- `transition: all`. It animates layout, theme switches, and properties nobody chose.
+- Blocking input until motion ends: disabled buttons during an entrance, ignored clicks,
+  or keyframe animations that cannot be interrupted. Prefer transitions for state, which
+  reverse from their current value.
+- Per-item stagger with no total cap, or staggering results the user re-scans (search
+  results, table rows, filtered lists).
+- Scroll-driven motion on `scroll` listeners or per-frame `getBoundingClientRect()`.
+  Use `animation-timeline`, IntersectionObserver, or kUInetic timelines.
+- Content hidden in base CSS until a script runs, with no fail-open path.
+- A spinner that flashes for operations under ~300ms, or a spinner as the only loading
+  signal under reduced motion.
+- Counters without tabular numerals, so the width jitters while counting.
+- Scroll-jacking: replacing native scroll speed.