npm - @mohammadhprp/system-prompt - Versions diffs - 0.12.0 → 0.12.2 - Mend

@mohammadhprp/system-prompt 0.12.0 → 0.12.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (124) hide show

package/framework/skills/great-interface/references/focus-and-keyboard.md ADDED Viewed

@@ -0,0 +1,131 @@
+# Focus and keyboard
+Focus rings, skip links, tabindex, focus trapping and the APG keyboard patterns.
+## Focus rings
+Style `:focus-visible`, not bare `:focus`. The browser shows it for keyboard and assistive-tech focus and suppresses it for mouse clicks, where focus is already obvious. Never write `outline: none` or `focus:outline-none` without a visible replacement, which removes keyboard navigation for sighted keyboard users.
+Prefer the browser's unmodified focus indicator, which adapts to platform and forced-color settings without the author predicting every background. Adding only `outline-offset` preserves it. A custom `outline: 2px solid` with no color renders `currentColor`, which is not automatically accessible, because the outline may cross colors unlike the text's own background. The preference order:
+```css
+/* Best: keep the browser ring, just give it breathing room */
+:focus-visible {
+  outline-offset: 2px;
+}
+/* Custom ring when the design requires one: use the project's verified token */
+:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+```
+```tsx
+// Tailwind: use the project's focus token or established focus-ring utility
+<button className="focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--focus-ring)]">
+  Save
+</button>
+```
+A custom focus indicator must meet the applicable project or WCAG target for visible area and change of contrast. Inspect the whole perimeter against every adjacent color it crosses: component fills, page surfaces, images, gradients, hover and selected states. A token, brand color, or `currentColor` passes only when that rendered check does.
+In `forced-colors: active` (Windows High Contrast), keep the default color adjustment or name a system color such as `Highlight`. `forced-color-adjust: none` freezes the authored color, so use it only where you have checked the control stays perceivable.
+Group focus styles with `:focus-within` when a wrapper should light up while an inner input has focus (e.g. a search box with an icon inside the border).
+## Skip link
+Target `<main id="main">` and visually hide the link until focused:
+```css
+.skip-link {
+  position: absolute;
+  inset-inline-start: -999px;
+}
+.skip-link:focus {
+  inset-inline-start: 16px;
+  top: 16px;
+}
+```
+```html
+<body>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <header>…</header>
+  <main id="main">…</main>
+</body>
+```
+Give in-page anchor targets `scroll-margin-top`, such as `80px` under a sticky header, so the target isn't hidden when jumped to.
+## tabindex rules
+- `tabindex="0"`: adds an element to the natural tab order. Only for custom interactive elements that aren't natively focusable.
+- `tabindex="-1"`: focusable via JavaScript only (`el.focus()`). Use for headings you move focus to, modal containers and roving-tabindex members.
+- Positive `tabindex`: never. It hijacks the tab order for the whole page. Fix the DOM order instead.
+### Roving tabindex
+Composite widgets, meaning tabs, menus, toolbars and radio groups, occupy one Tab stop. The active item has `tabindex="0"`, all others `tabindex="-1"`, and arrow keys move both focus and the `0`:
+```tsx
+<div role="tablist">
+  {tabs.map((tab, i) => (
+    <button
+      role="tab"
+      tabIndex={i === activeIndex ? 0 : -1}
+      aria-selected={i === activeIndex}
+      onKeyDown={handleArrowKeys} // ArrowLeft/ArrowRight move activeIndex, wrapping
+    >
+      {tab.label}
+    </button>
+  ))}
+</div>
+```
+## Focus trapping and restoration
+Modals must trap focus. Put `inert` on everything behind the dialog, which removes background content from the tab order and from assistive tech in one move:
+```tsx
+// On open
+document.getElementById("app-content").inert = true;
+const dialog = dialogRef.current;
+(dialog.querySelector("[autofocus]") ??
+  dialog.querySelector("button, [href], input, select, textarea"))?.focus();
+// On close
+document.getElementById("app-content").inert = false;
+triggerRef.current?.focus(); // always return focus to the element that opened it
+```
+Prefer native `<dialog>` with `showModal()`, which gives you the trap, the `inert` background and Escape handling for free. A custom overlay that can't use it needs `role="dialog"`, `aria-modal="true"` and an accessible name via `aria-labelledby`. Either way:
+- On open, focus the first focusable element. For destructive confirmations, focus the least destructive action instead.
+- On close, return focus to the trigger, or to the nearest logical container if the trigger is gone.
+- Add `overscroll-behavior: contain` on the dialog so scrolling inside never scrolls the page behind it.
+## Keyboard patterns (ARIA APG)
+Native elements come with these behaviors; custom widgets must implement them. A role is a promise. Give something `role="tab"` and users expect the full tab keyboard model.
+| Widget | Keys |
+| --- | --- |
+| Dialog | Tab/Shift+Tab cycle inside (wrap at ends); Escape closes |
+| Tabs | Arrow keys move between tabs (wrapping); Tab exits to the panel; Home/End jump to first/last |
+| Menu button | Enter/Space/ArrowDown opens and focuses first item; ArrowUp opens and focuses last; arrows navigate; Escape closes and refocuses the button |
+| Disclosure / accordion | Header is a `<button aria-expanded>`; Enter and Space toggle |
+| Combobox | ArrowDown opens/moves into the list; Enter accepts; Escape closes and returns to the input; typing filters |
+| Listbox / radio group | Arrow keys move selection; one Tab stop for the whole group |
+Universal rules:
+- Escape dismisses whatever opened last: tooltip, then menu, then dialog.
+- Arrow keys, not Tab, move within a composite widget; Tab moves between widgets.
+- Tabs choose activation mode: automatic (panel switches on arrow focus) when panels render instantly, manual (Enter/Space to activate) when switching is expensive.
+- Enter submits the focused input's form. In `<textarea>`, Enter inserts a newline and ⌘/Ctrl+Enter submits.
+## SPA route changes
+Client-side navigation doesn't reset focus or announce anything. On route change, update `document.title` to match the new context, then move focus to the new view's `<h1>` (given `tabindex="-1"`) or to `<main>`. Restore scroll position on back and forward navigation, and scroll to top on forward navigation.

package/framework/skills/great-interface/references/forms.md ADDED Viewed

@@ -0,0 +1,84 @@
+# Forms
+Labels, autocomplete, error messaging, input types and submit behavior.
+## Labels
+Every control needs a programmatic label: `<label for>` pointing at the input's `id`, or a wrapping `<label>`. A placeholder is never a label. It disappears the moment the user types and usually fails contrast.
+```html
+<!-- Good: explicit association -->
+<label for="email">Email</label>
+<input id="email" type="email" autocomplete="email" />
+<!-- Good: wrapping label, so label and control share one hit target -->
+<label>
+  <input type="checkbox" /> Send me updates
+</label>
+```
+Label and control share one hit target, so clicking "Send me updates" toggles the checkbox with no dead zone between them. Mark required fields with native `required` plus a visible indicator explained once per form ("* required").
+A placeholder used *in addition to* a label shows an example of the expected format: `placeholder="name@company.com"`.
+## Error messaging
+The complete pattern:
+```html
+<label for="email">Email</label>
+<input
+  id="email"
+  type="email"
+  autocomplete="email"
+  aria-invalid="true"
+  aria-describedby="email-error"
+/>
+<p id="email-error">Enter a valid email address.</p>
+```
+- `aria-invalid="true"` on the failing field, removed once fixed.
+- `aria-describedby` links the field to its inline error so screen readers announce it with the field.
+- Errors render inline beside their fields, with an icon or text. Never a red border alone, which is a color-only cue.
+- On submit, focus the first invalid field.
+- Allow incomplete submission so validation can surface. Never disable submit until valid (see below).
+- Accept free text and validate after. Never block typing or filter characters as the user types. Trim values before validating, because autocomplete and text expansion add trailing spaces.
+## Autocomplete and input types
+`autocomplete` with a meaningful `name` fills forms in one tap and is a WCAG requirement (1.3.5) for fields about the user. The common tokens:
+| Field | `autocomplete` |
+| --- | --- |
+| Name | `name` (or `given-name` / `family-name`) |
+| Email | `email` |
+| Phone | `tel` |
+| Address | `street-address`, `address-line1`, `postal-code`, `country` |
+| Card | `cc-number`, `cc-exp`, `cc-csc`, `cc-name` |
+| Login | `username`, `current-password` |
+| Signup / reset | `new-password` |
+| 2FA code | `one-time-code` |
+Prefix with a section where relevant: `autocomplete="shipping street-address"`.
+Correct `type` and `inputmode` pick the right mobile keyboard:
+| Input | Use |
+| --- | --- |
+| Email, URL, phone | `type="email"`, `type="url"`, `type="tel"` |
+| OTP / PIN / card number | `type="text" inputmode="numeric"` (keeps text semantics, no spinner) |
+| Money, decimals | `type="text" inputmode="decimal"` |
+| True numeric quantity | `type="number"` |
+Disable spellcheck on emails, codes and usernames: `spellcheck="false"`.
+## Never fight the user's tools
+- Stay compatible with password managers and 2FA autofill: real `<form>`, correct `autocomplete`, no fake inputs.
+## Submit behavior
+- Keep submit enabled until the request starts, then disable it and show a spinner *beside the original label*. "Save" with a spinner, not a bare spinner. The label is what tells assistive tech which button is busy.
+- Announce results. Success goes through a polite live region. On failure, focus the first invalid field, which is itself the announcement. Reserve `role="alert"` for form-level errors not tied to a field ([screen-readers.md](screen-readers.md)).
+- Warn on unsaved changes before navigation, and never lose typed input to a re-render. Hydration must preserve focus and value.
+- Enter submits from any focused input; in `<textarea>`, ⌘/Ctrl+Enter submits.

package/framework/skills/great-interface/references/from-an-image.md ADDED Viewed

@@ -0,0 +1,55 @@
+# Reading a screenshot
+The method for a screenshot, where the answer is a reconstruction rather than a reading. Which property lands in which bucket:
+| Exact from pixels | Ratios only | Unavailable |
+| --- | --- | --- |
+| Color values | Type sizes | Tokens and their names |
+| Contrast between any two sampled colors | Spacing values | The stack and styling system |
+| Relative proportion of anything measurable | Radii | Breakpoints |
+| Which colors repeat and where | Stroke and border weights | Motion, easing, duration |
+| | | Every state but the captured one |
+You do not know the capture's scale. A screenshot may be at 1×, 2×, or browser zoom, so a measured 30px could be 15pt of type or 30. Never report a `px` size or spacing from an image alone.
+One exception. Where the image contains text you can identify as body copy, assume `16px` and express everything as a multiple of it. Say you did, since the assumption may be wrong.
+## Colors, which are the reliable part
+Sample the actual pixels rather than describing what you see. Then hand the values to `better-colors`:
+- Convert each to OKLCH, so lightness is comparable across hues.
+- Sort by lightness to see whether the samples form a ramp and whether steps sit denser at the light end.
+- Check hue constancy across the ramp. A drifting hue means someone picked the ramp by eye.
+- Measure contrast on every foreground and background pair you can isolate. It is exact and the most valuable single number an image gives you.
+- Watch for a tinted neutral. A gray carrying a few percent of the accent hue is a deliberate choice worth naming.
+## Type, by category not by name
+You cannot identify a typeface from a screenshot with confidence, so never claim one. You can read its category and features, which is what transfers:
+- **Category:** geometric sans, grotesque, humanist, transitional serif, slab. Say which and why.
+- **Tells worth naming:** single or double-storey `a` and `g`, terminal angle, aperture, x-height against cap height. Also whether the digits are lining or old-style and whether the figures look tabular.
+- **Scale:** count the distinct sizes. Express them as multiples of the body size and derive the ratio.
+- **Weight contrast:** how many weights and how far apart. Two weights three steps apart reads deliberate, four weights one step apart accidental.
+- **Measure:** count characters on a full line of body copy and compare against `better-typography`'s 60 to 75 range.
+Where the actual face matters, name the category and suggest identifying it from the live page.
+## Spacing, as a rhythm
+Measure in the image, then divide everything by the smallest repeated gap. That quotient set is the rhythm, and it survives not knowing the scale.
+Then check the ratio `better-layout` owns, the gap between groups against the gap within one. At or above 2, space is carrying the grouping. Below that, something else is, usually a border or a background shape.
+## Say what the image hid
+Close by naming what a screenshot could not show, since that is where the reader would otherwise assume you looked:
+- Hover, focus, active, disabled, loading, empty and error states.
+- Whether anything animates and how.
+- Behavior at any other width.
+- Whether it is keyboard reachable and whether focus is visible.
+- The other appearance, light or dark.
+Where any of these matter to the reader's question, say that a live URL would answer it and this image cannot.

package/framework/skills/great-interface/references/grouping-and-alignment.md ADDED Viewed

@@ -0,0 +1,123 @@
+# Grouping and alignment
+How spacing, shapes, shared edges and ordering communicate what belongs together and what matters most.
+## Group with space, not lines
+Three tools create grouping, in order of preference:
+1. **Negative space**, the default. Related items sit close, unrelated ones far apart.
+2. **Background shapes**, a card or filled container, where a group must read as one unit such as a selectable row or a draggable card.
+3. **Separator lines**, a last resort for dense data where space costs too much, such as tables and long settings lists.
+The structural rule is that the gap between groups is at least 2× the gap within one. At `8px` inside a group, groups need `16px`+ between them, or the eye can't tell where one ends.
+```css
+/* Good: spacing alone communicates the grouping */
+.field-group { display: flex; flex-direction: column; gap: 8px; }
+.form { display: flex; flex-direction: column; gap: 24px; }
+/* Bad: uniform spacing plus lines to compensate */
+.form > * { margin-bottom: 12px; border-bottom: 1px solid var(--separator); }
+```
+```html
+<!-- Good: Tailwind -->
+<div class="space-y-6">
+  <div class="space-y-2">…field group…</div>
+  <div class="space-y-2">…field group…</div>
+</div>
+```
+Where a separator is genuinely needed, keep it quiet: hairline width, low contrast, never combined with a large gap that already did the job.
+## Keep controls distinct from content
+Interactive elements need a visual signal: a background, a border, an underline, or placement in a consistent control zone such as a toolbar or footer row. A control styled identically to static text is invisible.
+```html
+<!-- Bad: action looks exactly like the description text next to it -->
+<p class="text-zinc-600">Your trial ends soon. Upgrade now</p>
+<!-- Good: the action reads as an action -->
+<p class="text-zinc-600">Your trial ends soon.</p>
+<button class="font-medium text-blue-600">Upgrade now</button>
+```
+The inverse holds too. A non-clickable badge shaped exactly like the buttons beside it collects dead clicks.
+## Align to shared edges
+Pick a small set of alignment edges and put everything on them, because the eye tracks straight edges to scan content.
+- Every stray edge reads as noise even when nobody can name it: an icon 2px off the text edge, a card padded unlike its neighbor.
+- Use one project spacing step to express hierarchy. `16px` is a useful default where no scale exists, and deeper nesting repeats the same step.
+- Numbers in tables align to the trailing edge, text to the leading edge. Tabular figures are `better-typography`'s.
+```css
+/* Good: one shared leading edge, one indent step */
+.section { padding-inline: 24px; }
+.section .child { margin-inline-start: 16px; }
+/* Bad: three unrelated leading edges in one column */
+.header { padding-inline-start: 20px; }
+.list-item { padding-inline-start: 14px; }
+.footer { padding-inline-start: 24px; }
+```
+## Logical properties, not physical
+Express direction-dependent horizontal position as leading/trailing so the layout mirrors automatically under `dir="rtl"`:
+| Physical (avoid) | Logical (use) |
+| --- | --- |
+| `margin-left` | `margin-inline-start` |
+| `padding-right` | `padding-inline-end` |
+| `left: 0` | `inset-inline-start: 0` |
+| `text-align: left` | `text-align: start` |
+| `border-right` | `border-inline-end` |
+```html
+<!-- Good: Tailwind logical utilities -->
+<div class="ms-4 pe-6 text-start">…</div>
+<!-- Bad: breaks in RTL -->
+<div class="ml-4 pr-6 text-left">…</div>
+```
+Reserve physical properties for things that refer to physical screen sides whatever the language, such as positioning against a device notch or matching a gesture direction.
+Where arrangement encodes progression, as in star ratings, step indicators and progress bars, the sequence mirrors in RTL and stars fill from the trailing side. Flexbox and grid with logical properties mirror automatically; hand-positioned elements do not. Digit order inside numbers never reverses, which with other bidi rules belongs to `better-typography`.
+## Order by importance
+Readers scan top-to-bottom and leading-to-trailing. Place content accordingly:
+- The most important information sits near the top and the leading edge. The further down and trailing something sits, the less attention it gets.
+- Give essential information room. Never bury the one number the user came for under rows of secondary detail. Push that into collapsed sections, tabs, or detail views.
+- Within a row, identifying content leads and metadata and actions trail.
+```html
+<!-- Good: primary fact first, detail demoted -->
+<div>
+  <p class="text-2xl font-semibold">$4,320.00</p>
+  <p class="text-sm text-zinc-500">Available balance</p>
+</div>
+<!-- Bad: the key fact is buried below the fold of the card -->
+<div>
+  <p class="text-sm">Account 4402 · Opened 2019 · Standard tier</p>
+  <p class="text-sm">Last statement: June 30</p>
+  <p class="text-sm">Balance: $4,320.00</p>
+</div>
+```
+With logical properties, the same hierarchy mirrors correctly in RTL locales.
+## Don't overload the entry point
+The first screenful is a table of contents, not the whole book. If everything is prominent, nothing is:
+- One primary action per view. `better-colors` owns how color enforces it.
+- Group secondary actions behind a menu once they exceed two or three.
+- Prefer a short view that links deeper over a long view that shows everything at level one.

package/framework/skills/great-interface/references/hit-areas.md ADDED Viewed

@@ -0,0 +1,94 @@
+# Hit areas
+Target sizes, expanding hit areas without changing visual size and collision rules.
+## Target sizes
+Separate the conformance baseline from larger usability targets:
+| Standard | Minimum |
+| --- | --- |
+| WCAG 2.5.8 (AA) | 24×24px, the hard floor |
+| WCAG 2.5.5 (AAA) | 44×44px |
+| Apple HIG | 44×44pt |
+| Material Design | 48×48dp |
+WCAG 2.5.8 Level AA requires a 24×24 CSS-pixel target or one of its exceptions. Treat 44px as the recommended touch target for primary controls and 40px as a useful desktop target where density permits. Smaller controls are not automatic failures. Check the spacing, equivalent-control, inline, user-agent and essential exceptions before reporting one.
+Under the spacing exception, an undersized target passes when a 24px circle centered on its bounding box intersects no other target and no other undersized target's circle. In the simple case, 20px targets need a 4px gap.
+The visible element can stay small; the hit area is what must be big. Anything that looks clickable must be clickable across its whole visual extent, with no dead zones. A checkbox and its label share one hit target.
+## Expanding the hit area
+Where the visible element is smaller, say a 20×20 checkbox, extend the hit area with a pseudo-element. Put it on the wrapping `<label>` or `<button>`, never on the `<input>`, because replaced elements don't render `::before`/`::after` reliably.
+### CSS example
+```css
+/* Small checkbox with expanded 44px hit area, on the wrapping label */
+.checkbox-label {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+.checkbox-label::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%; /* physical centering: direction-independent */
+  transform: translate(-50%, -50%);
+  width: 44px;
+  height: 44px;
+}
+```
+### Tailwind example
+```tsx
+<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-11 after:-translate-1/2">
+  <CheckIcon />
+</button>
+```
+### Layout alternative
+Where the element can afford real box size, skip the pseudo-element and let the box be the target. That hands the browser real geometry for scrolling and gestures:
+```css
+.icon-button {
+  min-width: 44px;
+  min-height: 44px;
+  display: inline-grid;
+  place-items: center;
+}
+```
+## Collision rule
+Where the extended hit area overlaps another interactive element, shrink the pseudo-element to the largest size that does not collide. Two interactive elements never have overlapping hit areas.
+## Decorative layers
+A decorative layer painted over interactive content absorbs every pointer event its box covers: a gradient scrim, a glow, a blurred sheen, a full-bleed `::after`. The control underneath looks live and does nothing, and no hit-area sizing fixes it.
+Give each one `pointer-events: none` (Tailwind `pointer-events-none`) so events reach the control below, plus `aria-hidden="true"` to keep it out of the accessibility tree:
+```css
+.card-glow {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+```
+Keep pointer events on any layer the user is meant to hit: a modal scrim that dismisses on click is a control, not decoration.
+## Touch behavior
+- Add `touch-action: manipulation` to interactive elements to remove the double-tap-to-zoom delay on mobile.
+- Set `touch-action: none` on a surface implementing its own pan, zoom, or drag gestures, so the browser stops claiming them for scrolling and pinch-zoom. Scope it to that surface; at page level it removes scrolling.
+- Set `-webkit-tap-highlight-color` to match the design instead of the default gray flash.
+- Put hover-only styling behind `@media (hover: hover)`. On touch, `:hover` latches after a tap and holds until the user taps elsewhere, so it reads as a stuck selected state. Tailwind 4's `hover:` variant already compiles under this query.
+- Prefer generous targets and clear affordances over finicky interactions such as tiny drag handles and precise hover zones.

package/framework/skills/great-interface/references/icon-transitions.md ADDED Viewed

@@ -0,0 +1,102 @@
+# Icon transitions
+Cross-fading an icon when it changes contextually or by state, with and without a motion library. Icon weight, color and direction live in [icons.md](icons.md).
+## Contextual icon animations
+When icons appear or disappear contextually, on hover or a state change, animate them with `opacity`, `scale` and `blur` rather than toggling visibility.
+### Motion example
+This uses the `motion` package. Where the project has `framer-motion`, import the same APIs from `"framer-motion"`. Never mix an installed package with the other's import path.
+```tsx
+import { AnimatePresence, motion } from "motion/react";
+function IconButton({ isActive, icon: Icon }) {
+  return (
+    <button>
+      <AnimatePresence mode="popLayout">
+        <motion.span
+          key={isActive ? "active" : "inactive"}
+          initial={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          animate={{ opacity: 1, scale: 1, filter: "blur(0px)" }}
+          exit={{ opacity: 0, scale: 0.25, filter: "blur(4px)" }}
+          transition={{ type: "spring", duration: 0.3, bounce: 0 }}
+        >
+          <Icon />
+        </motion.span>
+      </AnimatePresence>
+    </button>
+  );
+}
+```
+### CSS transition approach (no Motion)
+Without Motion or Framer Motion, keep both icons in the DOM and cross-fade with CSS transitions. Neither unmounts, so enter and exit both animate smoothly.
+One icon is absolutely positioned on top of the other. Toggling state cross-fades them, the entering icon scaling up from `0.25` while the exiting one scales down to `0.25`, both with opacity and blur.
+```tsx
+function IconButton({ isActive, ActiveIcon, InactiveIcon }) {
+  return (
+    <button>
+      <div className="relative">
+        <div
+          className={cn(
+            "absolute inset-0 flex items-center justify-center",
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-100 opacity-100 blur-0"
+              : "scale-[0.25] opacity-0 blur-[4px]"
+          )}
+        >
+          <ActiveIcon />
+        </div>
+        <div
+          className={cn(
+            "transition-[opacity,filter,scale] duration-300",
+            "ease-[cubic-bezier(0.2,0,0,1)]",
+            isActive
+              ? "scale-[0.25] opacity-0 blur-[4px]"
+              : "scale-100 opacity-100 blur-0"
+          )}
+        >
+          <InactiveIcon />
+        </div>
+      </div>
+    </button>
+  );
+}
+```
+The non-absolute icon, `InactiveIcon`, defines the layout size. The absolute one, `ActiveIcon`, overlays it without affecting flow.
+### Choosing between Motion and CSS
+| | Motion (Framer Motion) | CSS transitions (both icons in DOM) |
+| --- | --- | --- |
+| **Enter animation** | Yes | Yes |
+| **Exit animation** | Yes (via `AnimatePresence`) | Yes (cross-fade, icon never unmounts) |
+| **Spring physics** | Yes | No, use `cubic-bezier(0.2, 0, 0, 1)` as approximation |
+| **When to use** | Project already uses `motion` or `framer-motion` | No motion dependency, or keeping bundle small |
+Check the project's `package.json`. Import from `"motion/react"` when `motion` is installed, or `"framer-motion"` when that is. Where both exist, follow the imports the component or its nearest peers already use. Where neither is present, use the CSS cross-fade and never add a dependency just for icon transitions.
+### When to animate icons
+| Animate | Don't animate |
+| --- | --- |
+| Icons that appear on hover (action buttons) | Static navigation icons |
+| State change icons (play → pause, like → liked) | Decorative icons |
+| Icons in contextual toolbars | Icons that are always visible |
+| Loading/success state indicators | Icon labels (text next to icon) |
+Use exactly these values for contextual icon animations. Do not deviate:
+- `scale`: `0.25` → `1` (never use `0.5` or `0.6`)
+- `opacity`: `0` → `1`
+- `filter`: `"blur(4px)"` → `"blur(0px)"`
+- `transition`: `{ type: "spring", duration: 0.3, bounce: 0 }`; **bounce must always be `0`**, never `0.1` or any other value