@hegemonart/get-design-done 1.14.8 → 1.16.0

package/reference/gestalt.md

@@ -0,0 +1,219 @@
+# Gestalt Principles
+
+<!-- UUPM ux-guidelines.csv rows deduped into this file and heuristics.md/anti-patterns.md/priority-matrix.md — see .planning/research/uupm-import/ux-guidelines-reconciliation.md -->
+<!-- Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/ux-guidelines.csv (deduped) -->
+
+Gestalt psychology explains how the human visual system automatically organizes individual elements into coherent wholes. Designers who understand Gestalt principles can use them intentionally — grouping what belongs together, separating what is distinct, directing attention flow, and reducing cognitive effort. Designers who ignore these principles will inadvertently create layouts that confuse perception, because the visual system will apply Gestalt organization regardless of the designer's intent.
+
+The eight principles below are not rules to follow in isolation — they interact. A single design decision often activates multiple principles simultaneously. The audit checklist at the end of this file helps identify where principles are being violated or underutilized.
+
+---
+
+## 1. Proximity
+
+**Definition:** Elements that are physically close to each other are perceived as belonging to the same group, regardless of their visual appearance. Distance communicates separation; closeness communicates relationship.
+
+**Design application:** Related controls — a label and its input, an action button and its target, a heading and its body text — should be separated by no more than 8px. Unrelated elements should be separated by at least 32px. When this discipline is applied consistently, users read the layout's meaning before reading its content: the structure itself communicates relationships. Proximity is the most fundamental grouping tool available, and it costs nothing but intentionality.
+
+Proximity violations are among the most common layout defects. The symptom is a layout where users do not immediately know which label belongs to which input, or which button acts on which content area. The fix is almost always to increase the distance between unrelated groups and decrease the distance within groups.
+
+**Scoring rubric — audit by looking for:**
+- Label-to-input gap: should be ≤8px; flag anything ≥16px
+- Button-to-target gap: a button that acts on a specific element should be adjacent to it, not floating at a distance
+- Section separation: distinct content sections should be separated by ≥32px; flag sections that bleed into each other
+- Orphaned elements: any element that has equal distance to two different groups is ambiguous and should be assigned
+
+**CSS/HTML grep signatures:**
+```
+gap-2   # ≤8px — appropriate for related elements
+gap-8   # 32px — appropriate for section separation; flag if used between related elements
+mb-8    # check if this is separating related or unrelated content
+p-0     # elements with no internal padding may create proximity confusion at borders
+```
+
+---
+
+## 2. Similarity
+
+**Definition:** Elements that share visual properties — color, shape, size, texture, or orientation — are perceived as belonging to the same category. The visual system uses similarity as a shortcut for classification: if it looks the same, it is the same kind of thing.
+
+**Design application:** Consistency in visual treatment is not merely an aesthetic preference — it communicates semantic meaning. All primary buttons should look identical: same size, same color, same weight. All destructive actions should look identical: same red, same border treatment, same position relative to the confirm/cancel pair. All secondary navigation items should be visually indistinguishable from each other. When similar-role elements look different, users assume they are different kinds of things, which creates confusion and erodes trust in the interface's logic.
+
+Icon weight is one of the most commonly violated similarity contexts. Mixing outline icons with filled icons signals two different visual registers that users will try to interpret as meaningful — even when the mixing is accidental.
+
+**Scoring rubric — audit by looking for:**
+- Button variants: are all primary buttons identical? Are all secondary buttons identical? Flag mixed variants on the same screen.
+- Icon weight: are all icons from the same weight family (all outline or all filled)? Flag mixing.
+- List items: do all items in a list have identical visual treatment? Flag items that are visually distinct without a semantic reason.
+- Form fields: are all text inputs styled identically? Flag inconsistencies.
+
+**CSS/HTML grep signatures:**
+```
+btn-primary.*btn-secondary   # flag if both appear in same component with identical visual weight
+icon-outline.*icon-filled    # flag mixed icon weight patterns
+variant="primary"            # audit all variant prop usages for consistency
+```
+
+---
+
+## 3. Continuity
+
+**Definition:** The eye naturally follows lines, curves, and paths in the direction they are already moving. When elements are aligned along an invisible axis, the eye connects them into a continuous flow and expects the line to continue.
+
+**Design application:** Use alignment to create invisible flow lines that direct the eye through the layout in the intended sequence. Left-aligned content columns create a strong left-edge flow line that the eye tracks downward. A row of icons creates a horizontal flow line. A step indicator with connected segments creates a continuous path that the eye follows from start to finish. Carousels and horizontal scrollers leverage continuity by partially revealing the next item — the visible edge implies that more content continues in the same direction.
+
+Continuity is disrupted when elements break expected alignment without a purposeful reason. An element that juts out of an otherwise aligned column creates a visual interrupt — which can be used intentionally to draw attention, or accidentally to create confusion.
+
+**Scoring rubric — audit by looking for:**
+- Alignment consistency: are all left-aligned elements aligned to the same grid column? Flag arbitrary left-offset elements.
+- Step indicators: does the visual path between steps flow clearly? Flag broken or visually interrupted step flows.
+- Carousel edge reveals: does the last visible item partially reveal the next? Flag carousels that do not imply continuation.
+- Broken columns: are there elements that break column alignment without a documented reason?
+
+**CSS/HTML grep signatures:**
+```
+ml-auto    # right-alignment break — check if intentional
+text-center # mixed with text-left in same flow — flag if alignment signal is inconsistent
+translate-x # horizontal animation — verify it implies continuity, not arbitrary motion
+```
+
+---
+
+## 4. Closure
+
+**Definition:** The human visual system actively completes incomplete shapes, filling in missing information to perceive a whole. Users will "see" a rectangle even if its corners are open, or a circle even if its arc is broken, because the mind prefers complete, recognizable forms over fragments.
+
+**Design application:** Closure is widely used in logos and icons to create forms that feel complete while being visually light. In UI, closure explains why partial borders can suggest containment without a full rectangle: a top border on a card, or a left border on a quoted text block, implies a region even without three additional sides. Progress indicators with open ends imply continuation; closed rings imply completion. Skeleton loading states use closure — partial shapes that the user's mind completes as content — to make loading feel purposeful rather than empty.
+
+Closure can also be violated: a progress bar that ends before reaching the container's right edge correctly communicates incompletion, but if it ends at an arbitrary position with no visual context, users may perceive a broken UI rather than a progress state.
+
+**Scoring rubric — audit by looking for:**
+- Progress indicators: does the fill/track relationship clearly communicate completion percentage? Flag indicators where progress direction is ambiguous.
+- Partial borders: do partial borders clearly imply the group they define? Flag partial borders that could be mistaken for decorative rules.
+- Skeleton states: do skeleton shapes meaningfully correspond to the content they represent? Flag skeletons that are too abstract to prime recognition.
+- Logo/icon edges: do open edges in icons close convincingly at standard display sizes?
+
+**CSS/HTML grep signatures:**
+```
+border-l     # left-only border — check if closure context is clear
+border-t     # top-only border — check if closure context is clear
+rounded-full # complete closure (circle/pill) — appropriate for completion states
+w-1/2        # partial fill — verify progress context is established by container
+```
+
+---
+
+## 5. Figure-Ground
+
+**Definition:** The visual system constantly distinguishes between a subject (figure) and its context (ground). Figures are perceived as having form, existing in front, and being the focus of attention. Ground is perceived as formless, behind, and non-focal. This distinction happens automatically and is fundamental to perceiving anything at all.
+
+**Design application:** Every interactive element, content region, and overlay depends on successful figure-ground separation. Modal dialogs work because the scrim pushes the page content to ground and the dialog to figure. Buttons work because their filled background distinguishes them from the text-on-ground surrounding them. Navigation bars work because their elevated background separates them from the page content they sit above.
+
+The practical rule: foreground elements must have at least 3:1 contrast ratio against their background, and for text, 4.5:1 for body text (WCAG AA). But figure-ground extends beyond contrast — blur, shadow, and opacity all contribute. A high-contrast element on a cluttered background may still fail to read as figure if the background is too visually active.
+
+**Scoring rubric — audit by looking for:**
+- Modal scrim: is the background content pushed to ground with sufficient opacity or blur? Flag modals where the page behind is at full visibility and full saturation.
+- Button states: do buttons clearly read as figure against all surface colors they appear on? Flag buttons with insufficient background contrast.
+- Active navigation items: are selected/active states clearly distinguished from non-selected? Flag flat navigation with only a color difference.
+- Card separation: do cards separate from the page surface? Flag cards with no shadow, border, or background differentiation.
+
+**CSS/HTML grep signatures:**
+```
+bg-white.*text-white    # invisibility risk — figure and ground collapsed
+bg-black/50             # modal scrim — verify opacity is sufficient
+z-index|z-[0-9]         # stacking context — verify figure-ground intent is preserved
+opacity-0.*opacity-100  # transition — verify figure emerges cleanly from ground
+```
+
+---
+
+## 6. Common Fate
+
+**Definition:** Elements that move together — in the same direction, at the same speed, and with the same timing — are perceived as belonging to the same group, even if they are spatially separated. Movement is a powerful grouping signal precisely because it overrides static proximity and similarity cues.
+
+**Design application:** When a group of elements should be perceived as a unit, animate them with shared timing. A card that expands while its child elements simultaneously rearrange communicates that the card and its contents are one object. A list that reorders with synchronized item movement communicates that the list is a coherent set. Conversely, animating elements at different speeds signals that they are independent objects — which can be used to establish hierarchy (parent first, then children) by staggering their entrance timing.
+
+Staggered animation (where sub-elements enter sequentially with a small delay) is a specific application of common fate that establishes a visual hierarchy within a group: the first element that moves is perceived as most important, and the trailing elements are perceived as its dependents.
+
+**Scoring rubric — audit by looking for:**
+- Group animations: when a container appears or changes, do its children animate with it or independently? Flag children that animate on unrelated timings.
+- List reorder: when items reorder, do they move with shared timing that communicates the reorder as one operation? Flag lists where individual items move asynchronously.
+- Exit animations: when a group exits, do all elements leave together? Flag cases where parts of a group exit before the container.
+
+**CSS/HTML grep signatures:**
+```
+transition-all          # check if used on group container vs. children separately
+stagger                 # check stagger timing for hierarchy signal
+animate-*.*animate-*    # multiple simultaneous animations — verify they share timing
+delay-[0-9]             # stagger implementation — verify delay communicates hierarchy
+```
+
+---
+
+## 7. Common Region
+
+**Definition:** Elements enclosed within a clearly defined boundary — a border, a background color, a shadow, or any other perceptual container — are perceived as belonging to the same group, even if they are not close to each other. Common region overrides proximity: two elements far apart within the same bounded region are perceived as more related than two elements close together on either side of a region boundary.
+
+**Design application:** Cards, panels, table rows, form field groups, and toolbars all leverage common region by using visual boundaries to say "these things go together." The boundary does not need to be a literal border — a distinct background color works equally well. This is why alternating row colors in a data table immediately communicate that each row is a distinct unit, and why a card with a white background on a grey page surface reads as a contained group without needing a border.
+
+Common region is also useful for communicating hierarchy: nested regions (a card within a page, a sub-section within a card) communicate nested relationships. The visual boundary at each level tells the eye exactly how far a group extends.
+
+**Scoring rubric — audit by looking for:**
+- Card boundaries: do cards have a visible boundary (shadow, border, or background) that clearly separates them from their surroundings? Flag cards that blend into the page surface.
+- Form groups: are related form fields visually grouped within a shared container? Flag forms where field groups are separated only by vertical spacing without a region signal.
+- Table rows: are table rows distinguishable as individual regions? Flag tables with no row separation signal.
+- Nested regions: are nested groupings visually distinguishable from their parent container?
+
+**CSS/HTML grep signatures:**
+```
+rounded.*shadow         # card pattern — verify region boundary is sufficient
+bg-gray-50.*bg-white    # alternating region backgrounds — appropriate for table rows, list items
+border.*rounded         # explicit region boundary — verify visual weight is appropriate for nesting level
+divide-y                # table row divider — check if combined with sufficient vertical padding
+```
+
+---
+
+## 8. Prägnanz (Law of Simplicity)
+
+**Definition:** The visual system always interprets ambiguous inputs in the simplest possible way. When multiple interpretations of a visual input are possible, the mind chooses the interpretation that requires the least cognitive work. Complexity is resolved toward simplicity automatically.
+
+**Design application:** Prefer simple, recognizable shapes over complex, irregular ones. Remove any visual element that does not communicate something. Every decoration that does not carry meaning adds to the cognitive load the user must process before reaching the content that actually matters. This is the principle behind minimalism in UI design — not because minimalism is aesthetically superior, but because unnecessary visual complexity consumes perceptual resources that should be directed at the interface's actual purpose.
+
+Prägnanz also implies that when two layouts can communicate the same information, the simpler one is better. A three-color palette is simpler to parse than a seven-color palette, even if the seven-color palette is "more interesting." A consistent component structure is simpler to navigate than a varied one, even if the variation is intentional.
+
+**Scoring rubric — audit by looking for:**
+- Decorative elements: identify any visual element that serves no communicative purpose. Flag gradients, textures, and ornamental icons that do not carry semantic meaning.
+- Color count: how many distinct colors appear on a single screen? Flag screens with more than 4–5 distinct colors where the additional colors are not semantically required.
+- Shadow and border redundancy: are both shadow and border used simultaneously on the same element without a reason? Flag redundant depth cues.
+- Animation without purpose: identify any animation that does not communicate state change, progress, or relationship. Flag animations that exist for decoration alone.
+
+**CSS/HTML grep signatures:**
+```
+bg-gradient             # decorative gradient — verify it communicates something
+border.*shadow          # redundant boundary signals — flag unless both serve distinct purposes
+animate-bounce          # decorative animation — flag if it does not communicate a meaningful state
+after:.*before:         # pseudo-element decorations — verify each is communicative
+```
+
+---
+
+## Gestalt Audit Checklist
+
+Use this checklist when auditing a screen for Gestalt compliance. Each item maps to one or more principles.
+
+1. **Proximity check:** Can you identify every visual group by spacing alone, without relying on borders or background colors? Related elements should cluster tightly (≤8px); unrelated groups should breathe apart (≥32px). Flag any element where group membership is ambiguous from spacing alone.
+
+2. **Similarity check:** Do all elements of the same semantic role share identical visual treatment? Primary buttons match primary buttons. Destructive actions match destructive actions. Icons use consistent weight. Flag any visual inconsistency that users might interpret as a semantic difference.
+
+3. **Continuity check:** Does the layout create a clear reading path through its most important content? Can you trace an invisible line — horizontal, vertical, or diagonal — that connects the primary focal points in intended viewing order? Flag layouts where the reading path requires backtracking.
+
+4. **Closure check:** Are any incomplete shapes used? If so, do they close convincingly at the display size and resolution? Do progress indicators clearly communicate fill direction and completion scale? Flag ambiguous incomplete shapes.
+
+5. **Figure-ground check:** Does every interactive element have sufficient contrast against its background? Do modals and overlays effectively push page content to ground? Are active navigation states clearly elevated above inactive ones? Flag anything where figure and ground are insufficiently distinct.
+
+6. **Common fate check:** When elements animate, do grouped elements share timing? Is stagger used intentionally to signal hierarchy rather than arbitrarily? Flag groups where member elements animate independently with no shared timing.
+
+7. **Common region check:** Are all logically related groups of elements contained within a visible boundary (card, panel, background, or border)? Can a user identify group membership from the region boundary alone? Flag groups that rely only on proximity without a region signal in contexts where the proximity alone is insufficient.
+
+8. **Prägnanz check:** Remove one element at a time and ask: does the screen communicate less information without it? If the answer is no for any element, that element is decorative noise. Flag decorative elements, redundant visual signals, and any source of visual complexity that does not carry proportionate communicative value.

package/reference/iconography.md

@@ -0,0 +1,231 @@
+# Iconography — Reference Guide
+
+Icons are a precise visual language. Every sizing, weight, metaphor, and accessibility decision either reinforces or undermines the system's communicative intent. This reference establishes canonical rules for icon usage across the get-design-done framework.
+
+---
+
+## 1. Optical Sizing & Stroke Weight
+
+Icons are not scalable art objects that merely get bigger — they are optical instruments tuned to specific viewing contexts. A 16px icon rendered with the same stroke weight as a 32px icon will look fragile and thin at small sizes, because the eye perceives stroke weight relative to the overall icon bounding box.
+
+**Canonical stroke weights by icon size:**
+
+| Icon size | Recommended stroke | Why |
+|-----------|-------------------|-----|
+| 16px | 1.5px | At 16px, a 1px stroke disappears on most non-retina displays; 1.5px gives enough mass without filling the internal counter spaces |
+| 20px | 1.5–2px | Transition size — match the body text weight; if using medium-weight body copy, lean toward 2px |
+| 24px | 2px | The most common "default" icon grid. 2px is the industry convention (Lucide, Heroicons, Feather all default here) |
+| 32px | 2–2.5px | Larger icons need more weight to avoid looking drawn with a fine pen against the heavier surrounding UI |
+| 48px+ | 2.5–3px | Display-size icons (app icons, hero illustrations) should be optically balanced to read boldly at distance |
+
+**Pixel alignment rules:** Icons on an even grid (16px, 24px, 32px) align their strokes to whole pixels. Icons on an odd grid (20px, 28px) should have strokes centered on 0.5px boundaries to avoid sub-pixel blur on non-retina displays. For SVG exports, always set `shape-rendering: crispEdges` on icon wrappers, and center the viewBox exactly on the pixel grid (e.g., `viewBox="0 0 24 24"`, not `"0.5 0.5 23 23"`). A stroke centered on the path boundary will anti-alias; a stroke offset by 0.5px will render sharply.
+
+---
+
+## 2. Weight & Stroke Consistency
+
+Never mix stroke weights within the same UI surface. Mixing a 1.5px outline icon next to a 2px icon in the same toolbar creates a visual discord that users register as "something feels off" even if they cannot articulate why. The eye calibrates to a baseline weight, and deviations feel like errors.
+
+**The typography matching principle:** Icon weight should correspond to the surrounding text weight. A regular-weight body paragraph (400) pairs with a regular or medium icon (1.5–2px stroke). A bold heading (700) pairs with a bold or filled icon variant. This alignment creates a perception of visual kinship — the icon "belongs" to the text alongside it rather than floating in from a different design register.
+
+**Practical rule:** Choose one icon library per product surface and use it exclusively. If a specific icon is unavailable in your chosen library, draw it using the same stroke grammar rather than importing a single icon from a different library. The visual inconsistency of mixing libraries is nearly always worse than an imperfect icon from the right library.
+
+---
+
+## 3. Metaphor Taxonomy
+
+Icons communicate meaning through shared cultural metaphors. Understanding the four functional categories prevents category errors — using a navigation metaphor for an action, or a status metaphor for wayfinding.
+
+### Functional (Action) Icons
+
+Functional icons represent user-initiated operations: save, delete, copy, filter, sort, upload, download. They answer the question "what can I do here?" Their metaphors must be action-verifiable — a user looking at the icon should be able to predict the outcome of clicking it. The floppy disk for "save" is a dead metaphor that persists by convention, not visual logic; prefer more literal representations (cloud-upload for cloud save, checkmark-circle for "mark complete") where the action is unambiguous without cultural baggage.
+
+**Recognition test:** Cover the label. Can a first-time user accurately predict what clicking this icon will do? If fewer than 80% of testers answer correctly in usability studies, pair the icon with a text label.
+
+### Status Icons
+
+Status icons communicate system state: success, warning, error, loading, offline, syncing. They answer "what is the system telling me?" Their metaphors are highly convention-bound: green circle-check for success, yellow triangle-exclamation for warning, red circle-X for error. Deviating from these conventions introduces cognitive load — users must re-learn your system's visual language rather than drawing on years of software experience.
+
+**When to use:** Status icons appear adjacent to data fields, system messages, toast notifications, and form validation. They must never be used as the sole indicator of status for users with color vision deficiency — always pair with a distinct shape and a text description.
+
+### Navigation (Wayfinding) Icons
+
+Navigation icons orient users within an information space: home, back, forward, menu, close, external-link, settings. They answer "where am I and how do I move?" Their metaphors are cartographic and gestural — arrows indicate direction of travel, the house represents the origin point, the hamburger menu represents a collapsed list.
+
+**When to use:** Navigation icons appear in navbars, breadcrumbs, sidebars, and dialog controls. Because wayfinding is critical to task completion, navigation icons should almost always be paired with visible labels until the product has established enough user familiarity to support icon-only navigation (typically after repeated-use screens with power users).
+
+### Brand Icons
+
+Brand icons represent identity: logos, product wordmarks, social platform logos, and payment method marks. They follow the brand owner's guidelines, not the product's icon system. Never apply your system's stroke weight or color palette to third-party brand marks — use the official SVG assets. Brand icons communicate "who or what" rather than action, status, or direction.
+
+**Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/icons.csv**
+
+---
+
+## 4. Dark-Mode Icon Variants
+
+A common mistake is inverting an icon library's default black strokes to `#FFFFFF` in dark mode. Pure white icons on dark backgrounds produce harsh contrast that reads as aggressive, particularly for secondary and tertiary actions. More importantly, pure white does not participate in the opacity token system that controls visual hierarchy.
+
+**Use opacity tokens, not white fills.** The correct approach is to define icon colors using a semantic token (`--icon-default`, `--icon-secondary`, `--icon-disabled`) and resolve those tokens differently per color scheme:
+
+```css
+:root {
+  --icon-default: oklch(0.15 0 0);       /* near-black */
+  --icon-secondary: oklch(0.45 0 0);     /* mid-gray */
+  --icon-disabled: oklch(0.70 0 0 / 0.4);
+}
+
+[data-theme="dark"] {
+  --icon-default: oklch(0.92 0 0);       /* near-white, not pure */
+  --icon-secondary: oklch(0.65 0 0);
+  --icon-disabled: oklch(0.40 0 0 / 0.4);
+}
+```
+
+**Icon-on-color contrast rules:** When placing a white icon on a brand primary background (e.g., a white checkmark inside a colored button), the contrast ratio between the icon color and the background must meet WCAG 2.1 AA minimum of 4.5:1 for icons associated with text-size equivalents, and 3:1 for large-scale graphical elements (per WCAG 1.4.11 Non-text Contrast). Use the APCA method for more perceptually accurate contrast estimation in complex color environments.
+
+---
+
+## 5. Icon Animation Guidelines
+
+Animated icons communicate state transitions — they are not decorative flourishes. Every animation should signal a specific semantic event: a state change the user caused, a process completing, or feedback confirming an action.
+
+**Morphing between states (cross-fade pattern):**
+
+When transitioning between two icons (e.g., play → pause, bookmark-outline → bookmark-filled), use the following three-property animation. The outgoing icon exits while the incoming icon enters simultaneously:
+
+```css
+/* Outgoing icon */
+.icon-exit {
+  animation: icon-exit 150ms ease-in forwards;
+}
+@keyframes icon-exit {
+  from { opacity: 1; transform: scale(1); filter: blur(0px); }
+  to   { opacity: 0; transform: scale(0.75); filter: blur(4px); }
+}
+
+/* Incoming icon */
+.icon-enter {
+  animation: icon-enter 200ms ease-out forwards;
+  animation-delay: 100ms;
+}
+@keyframes icon-enter {
+  from { opacity: 0; transform: scale(0.25); filter: blur(4px); }
+  to   { opacity: 1; transform: scale(1); filter: blur(0px); }
+}
+```
+
+This pattern (scale 0.25→1, opacity 0→1, blur 4→0) creates a "materialization" feel that communicates emergence — the new state is coming into existence rather than simply swapping. Duration should be 150–200ms; shorter feels mechanical, longer feels sluggish.
+
+**Rotation for loading states:** A continuous 360° rotation at 700–900ms per revolution communicates "waiting for external process." Use `animation-timing-function: linear` — easing causes visual pulsing that reads as multiple distinct events rather than a continuous state. The rotation axis must be the center of the icon's bounding box.
+
+**Entrance for success states:** A success icon (checkmark, circle-check) should entrance with a brief overshoot — scale from 0 to 1.1 then settle to 1.0 — over 250–300ms using a spring-like timing function (`cubic-bezier(0.175, 0.885, 0.32, 1.275)`). This micro-bounce communicates "confirmed" rather than merely "appeared."
+
+**Respect prefers-reduced-motion:** All icon animations must be disabled or reduced to an instant opacity transition when `@media (prefers-reduced-motion: reduce)` is active.
+
+---
+
+## 6. Semantic vs. Decorative Labeling
+
+The single most common accessibility error in icon implementation is failing to distinguish between semantic icons (conveying meaning) and decorative icons (providing visual accompaniment to text that already conveys the meaning).
+
+**Semantic (interactive standalone) icons require `aria-label`:**
+
+```html
+<!-- Icon-only button — meaning conveyed solely by icon -->
+<button aria-label="Delete item">
+  <svg aria-hidden="true" focusable="false"><!-- trash icon --></svg>
+</button>
+```
+
+The `aria-label` on the button describes the action. The SVG itself receives `aria-hidden="true"` to prevent screen readers from announcing "svg" or the icon's internal text elements. Never rely on `title` elements within SVG for accessible names in interactive contexts — browser support is inconsistent.
+
+**Decorative icons require `aria-hidden="true"`:**
+
+```html
+<!-- Icon accompanies visible label — purely decorative -->
+<button>
+  <svg aria-hidden="true" focusable="false"><!-- search icon --></svg>
+  Search
+</button>
+```
+
+When visible text already conveys the full meaning, the icon is decorative. Hiding it from the accessibility tree prevents redundant announcements ("search graphic, search button").
+
+**Never use a standalone icon as the sole affordance for critical or destructive actions.** Even if the icon is well-recognized (trash = delete), critical actions like permanent deletion, payment confirmation, or account changes must always pair the icon with a visible text label. The cost of an unclear icon on a destructive action is irreversible user harm.
+
+---
+
+## 7. Touch Target Pairing
+
+Visual icon size and interactive touch target size are different concerns. A 16px icon is visually appropriate for compact UI contexts, but an interactive area of 16×16px fails accessibility and usability standards — fingers are much larger than icons.
+
+**Minimum interactive touch targets:**
+
+| Context | Minimum target | Rationale |
+|---------|---------------|-----------|
+| Standard interactive icon | 40×40px | WCAG 2.5.5 Target Size AAA; Apple HIG minimum |
+| Primary action icon | 48×48px | Material Design 3 recommendation for primary actions |
+| Dense data tables | 32×32px | Acceptable for expert-user interfaces with high density requirements |
+
+**Implementation with `::after` pseudo-element:**
+
+This technique extends the clickable area without changing the visual icon size:
+
+```css
+.icon-button {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.icon-button::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: 40px;
+  height: 40px;
+  /* Optionally: background: transparent; border-radius: 50%; */
+}
+```
+
+The visual icon remains 20px; the interactive zone expands to 40px. On touch devices, this satisfies pointer accuracy requirements without creating visual padding that disrupts layout density.
+
+---
+
+## 8. Public Icon Library Catalog
+
+Choosing an icon library is an architectural decision — all icons in a product surface should come from a single library to ensure stroke weight and visual grammar consistency. These are the major open-source libraries with their key characteristics.
+
+### Lucide Icons
+Over 1,000 icons under the MIT license. Stroke-based with a consistent 2px stroke weight on a 24px grid. This is the default icon library for shadcn/ui components and has become the de facto standard for React-based design systems. Strong community maintenance with frequent additions. Import individual icons by name to enable tree-shaking: `import { ChevronRight } from 'lucide-react'`. Never import the entire library — the barrel export will bloat bundles.
+
+### Phosphor Icons
+Available in six weights — thin, light, regular, bold, fill, and duotone — making it one of the most expressive icon systems available. MIT licensed. Ideal for products where visual hierarchy needs to be communicated through icon weight variation (e.g., active nav item uses bold, inactive uses regular). The duotone variant provides a two-tone fill that works well in marketing and onboarding contexts.
+
+### Heroicons
+Produced by the Tailwind CSS team. Available in outline and solid variants on a 24px grid. MIT licensed. The outline variant is a 1.5px stroke, which is slightly lighter than Lucide's 2px — choose based on whether your typography leans toward light or regular weight. First-class Tailwind integration and React/Vue packages available.
+
+### Radix Icons
+Designed specifically for the 15px grid rather than the standard 24px grid, making Radix Icons uniquely suited for dense, compact UI contexts — form fields, inline badges, data table actions. They pair directly with Radix UI primitives and share the same design philosophy: functional, unobtrusive, and predictable. MIT licensed.
+
+### Tabler Icons
+Over 3,000 icons with a consistent 2px stroke on a 24px grid. The largest coherent stroke-based icon set available. MIT licensed. Excellent for applications requiring coverage of unusual domains (medical, scientific, geographic) that other libraries do not address. Actively maintained with SVG optimization.
+
+### Iconoir
+Clean, minimal line icons on a 24px grid. MIT licensed. Characterized by a slightly rounded stroke termination that gives it a friendlier character than more angular systems. Well-suited for consumer-facing applications where the brand tonality is approachable and modern rather than corporate or technical.
+
+### Remix Icon
+Open-source with filled and line variants in each icon, organized into semantic categories (system, business, media, communication, etc.). The parallel line/filled pairing makes it straightforward to communicate active vs. inactive states without switching libraries.
+
+### SF Symbols
+Apple's system-native icon library, available exclusively on Apple platforms (iOS, macOS, watchOS, visionOS). Variable weights that match the San Francisco typeface — when the user adjusts text size or boldness in system settings, SF Symbols adjust proportionally. Not available for web or Android; use only in native Swift/SwiftUI or UIKit contexts. Access via `Image(systemName:)` in SwiftUI.
+
+### Feather
+A minimal, classic icon set with 287 icons on a 24px grid at a 2px stroke. MIT licensed. Feather is older than many alternatives on this list and receives fewer updates, but its visual grammar is exceptionally clean and it remains a reliable choice for products that prioritize restraint. The limited catalog means it works best for simple, focused applications rather than complex dashboards.
+
+---
+
+*This reference governs all icon decisions within the get-design-done framework. Deviations require explicit justification in `.design/DESIGN-CONTEXT.md` as a C-XX constraint.*

package/reference/motion.md

@@ -283,3 +283,105 @@ document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
 3. For many elements, share a single observer instance and call `observe()` once per element.
 4. Prefer CSS transitions triggered by a class toggle over requestAnimationFrame loops.
 5. Use `will-change: transform, opacity` sparingly (only on elements that animate repeatedly).
+
+---
+
+## MIFB Micro-Motion Extensions
+Source: jakubkrehel/make-interfaces-feel-better (MIT) — motion.md
+
+### Interruptible Animations
+
+Use CSS transitions for interactive elements because transitions retarget mid-animation — when a user moves their cursor away before a hover animation completes, the transition reverses smoothly from wherever it currently is. Keyframe animations restart from the beginning, creating a jarring jump.
+
+**Decision rule:**
+- Interactive states (hover, focus, active, pressed): always CSS transitions
+- Orchestrated sequences, entrance effects, data-driven animations: keyframe or JS animation
+
+```css
+/* Good — transition retargets smoothly */
+.button { transition: background-color 150ms ease-out; }
+
+/* Avoid for interactive — restarts on interruption */
+.button:hover { animation: hover-bg 150ms ease-out forwards; }
+```
+
+### Split-and-Stagger Enter/Exit
+
+For multi-element entrances (card grids, lists, feature sections):
+
+- Default stagger: 100ms between elements
+- Heading words: 80ms per word
+- Entrance transform: `opacity: 0 → 1` + `translateY(12px → 0)` + `blur(4px → 0)`
+- Entrance duration: 300ms, `ease-out`
+- Exit transform: `opacity: 1 → 0` + `translateY(0 → -12px)` (opposite direction, smaller offset)
+- Exit duration: 150ms (half the entrance duration — exits should be faster)
+
+The blur component adds a depth cue that makes entrances feel less flat. Keep blur modest (4px) — the goal is a subtle focus effect, not a visible blur.
+
+### Contextual Icon Animations — Cross-Fade Pattern
+
+When swapping two icons (e.g., play ↔ pause, chevron-up ↔ chevron-down, bookmark ↔ bookmarked), use this exact cross-fade spec:
+
+**Framer Motion spring (preferred):**
+- `scale: 0.25 → 1` (entering), `scale: 1 → 0.25` (exiting)
+- `opacity: 0 → 1` (entering), `opacity: 1 → 0` (exiting)
+- `filter: blur(4px) → blur(0)` (entering), `blur(0) → blur(4px)` (exiting)
+- `transition: { type: "spring", duration: 0.3, bounce: 0 }` — **bounce MUST be 0**
+
+**CSS fallback (no Framer):**
+- Keep both icons in the DOM, one `position: absolute`
+- Use `cubic-bezier(0.2, 0, 0, 1)` easing
+- Duration: 200ms
+
+The scale + blur combination creates a focus-snap effect that feels intentional rather than mechanical. The `bounce: 0` hard constraint exists because any bounce on a 0.25-scale origin point makes icons appear to "pop" invasively.
+
+### Scale on Press — Canonical Value
+
+The canonical scale value for press feedback is **`0.96`**.
+
+Rules:
+- Never use `scale(0.95)` — too large, feels unresponsive
+- Never use `scale(0.97)` — too subtle at high DPI, not perceived as feedback
+- Never use `scale(0.98)` or higher — imperceptible
+- `0.96` is the ONLY correct value for standard interactive elements
+
+Tailwind: `active:scale-[0.96]`
+Framer: `whileTap={{ scale: 0.96 }}`
+
+For primary CTAs where maximum tactility is needed (purchase, send, confirm):
+use `0.96` with a shadow reduction: `box-shadow: none` during press.
+
+Deprecation note: earlier versions of `reference/checklists.md` referenced `scale(0.97)`. That entry has been reconciled. **0.96 is the canonical value.**
+
+### AnimatePresence initial={false}
+
+When `AnimatePresence` wraps UI that exists in the DOM before it enters the animation scope (e.g., a tab panel that renders its first tab immediately, a dropdown that's already open on first load), use `initial={false}`:
+
+```tsx
+<AnimatePresence initial={false}>
+  {isOpen && <motion.div key="panel" initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }} />}
+</AnimatePresence>
+```
+
+Without `initial={false}`, Framer will animate the FIRST render of children — meaning UI that's immediately visible on page load will "fade in" unnecessarily. This creates a flash/flicker that signals poor craftsmanship.
+
+**Rule:** Any `AnimatePresence` wrapping persistent UI should have `initial={false}`.
+
+### will-change — GPU Property Table
+
+Only add `will-change` when you observe first-frame stutter on lower-end hardware. Do NOT add it preemptively — it consumes GPU memory continuously for every element that has it.
+
+GPU-compositable properties (safe with will-change):
+| Property | will-change value |
+|----------|------------------|
+| transform (translate, scale, rotate) | `transform` |
+| opacity | `opacity` |
+| filter (blur, brightness, contrast) | `filter` |
+| clip-path | `clip-path` |
+
+Never use `will-change: all` or `will-change: contents` — this forces the entire element and its subtree onto a new compositor layer, thrashing memory.
+
+Remove `will-change` after the animation completes if applied dynamically:
+```js
+element.addEventListener('transitionend', () => element.style.willChange = 'auto')
+```