@hegemonart/get-design-done 1.14.8 → 1.15.0

package/reference/framer-motion-patterns.md

@@ -0,0 +1,411 @@
+<!-- Source: nextlevelbuilder/ui-ux-pro-max-skill (MIT) — data/stacks/react.csv (framer-motion rows) -->
+
+# Framer Motion Patterns
+
+Framer Motion is the standard animation library for React. It abstracts the browser's animation primitives into a declarative API that stays out of your way for common cases while exposing full physics-based control when you need it. This reference covers implementation patterns — not just the API, but _why_ each pattern exists and when to apply it.
+
+---
+
+## 1. Basics — motion components
+
+Any HTML (or SVG) element can become a motion component by prefixing it with `motion.`. The most common variants are `motion.div`, `motion.span`, `motion.button`, and `motion.li`, but `motion.section`, `motion.a`, `motion.img`, and any other HTML element follow the same pattern.
+
+The four primary animation props are:
+
+- **`initial`** — the state the element starts in before it mounts (or before a transition begins). Without `initial`, the element won't animate _from_ anything — it'll just be in the `animate` state on mount. Always provide `initial` when you want an entrance animation.
+- **`animate`** — the state the element should animate _to_. Framer drives the element toward this state whenever it changes.
+- **`exit`** — the state the element animates _to_ when it unmounts. Requires `<AnimatePresence>` as a parent — see Section 3.
+- **`transition`** — controls how the animation happens (spring, tween, duration, ease). If omitted, Framer applies a spring by default for layout/positional changes and a tween for opacity.
+
+A basic fade-in example:
+
+```tsx
+import { motion } from 'framer-motion'
+
+function FadeIn({ children }: { children: React.ReactNode }) {
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 8 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ type: 'tween', duration: 0.2, ease: 'easeOut' }}
+    >
+      {children}
+    </motion.div>
+  )
+}
+```
+
+The slight `y: 8` offset on entry gives the element a sense of emerging from below — a common, subtle entrance pattern. The `easeOut` ease starts fast and slows at the end, which feels responsive.
+
+---
+
+## 2. Spring vs. Tween Configuration
+
+Framer Motion supports two fundamentally different animation models. Choosing between them is not arbitrary — each has a domain where it clearly wins.
+
+### Spring physics (preferred for UI motion)
+
+Springs model the physics of a real spring: the element overshoots slightly and settles. This is why spring motion _feels natural_ — real objects in the world have inertia and settle under physical forces. For UI, spring motion communicates responsiveness and quality.
+
+`type: "spring"` is Framer's default for layout animations and positional changes. Key parameters:
+
+- **`stiffness`** (100–800): controls how forcefully the spring pulls toward the target. High stiffness = arrives fast and decisively. Low stiffness = slow, lazy arrival.
+- **`damping`** (10–30): controls oscillation resistance. High damping = settles without overshoot. Low damping = bouncy.
+- **`mass`** (0.5–2): adds inertia. Higher mass makes the element feel heavier and slower to respond.
+
+The relationship that matters in practice:
+- **High stiffness + high damping = snappy** — fast arrival, no bounce. This is the production UI default.
+- **Low stiffness + low damping = bouncy** — never use in production UI. Bounce feels playful and toy-like, which is wrong for most product contexts.
+
+**Hard constraint: `bounce: 0` always for icon cross-fades and micro-interactions.** The `bounce` shorthand parameter is a convenience alias — setting it to 0 ensures no oscillation. "Bounce must be zero" is a non-negotiable rule for any interaction that fires frequently or in information-dense UI.
+
+Recommended production preset:
+
+```tsx
+transition={{ type: 'spring', stiffness: 400, damping: 30 }}
+```
+
+This is snappy and clean. It arrives fast and settles without any visible oscillation. Use it as the default for hover lifts, modal entries, and element transitions.
+
+### Tween (for duration-controlled, eased animations)
+
+Tween animations run over a fixed duration with a specified easing curve. Use them when exact timing matters — opacity fades, color transitions, anything where you need predictable, duration-controlled behavior rather than physics.
+
+```tsx
+transition={{ type: 'tween', duration: 0.2, ease: 'easeOut' }}
+```
+
+Ease guidance:
+- **`"easeOut"`** for entrances — starts fast (feels responsive), decelerates to rest.
+- **`"easeIn"`** for exits — accelerates away, gets out of the way quickly.
+- **`"easeInOut"`** for emphasis transitions — smooth acceleration and deceleration, used when the same element transitions between states (not entering/exiting).
+
+The rule of thumb: use springs for movement and scale; use tweens for opacity, color, and blur.
+
+---
+
+## 3. AnimatePresence
+
+`AnimatePresence` is the component that enables exit animations. Without it, React unmounts components immediately, and `exit` props are never executed — the element simply vanishes.
+
+```tsx
+import { AnimatePresence, motion } from 'framer-motion'
+
+function ToastContainer({ toasts }) {
+  return (
+    <AnimatePresence>
+      {toasts.map(toast => (
+        <motion.div
+          key={toast.id}
+          initial={{ opacity: 0, y: -10 }}
+          animate={{ opacity: 1, y: 0 }}
+          exit={{ opacity: 0, y: -10 }}
+          transition={{ type: 'spring', stiffness: 400, damping: 30 }}
+        >
+          {toast.message}
+        </motion.div>
+      ))}
+    </AnimatePresence>
+  )
+}
+```
+
+Every child of `AnimatePresence` that will be conditionally rendered **must have a `key` prop**. Framer uses the key to track which element is entering and which is exiting. Without a key, exit animations will not fire.
+
+### AnimatePresence `mode` prop
+
+The `mode` prop controls how entering and exiting elements interact during a transition:
+
+- **`mode: "wait"`** — the exiting element completes its exit animation fully before the entering element begins its entrance. Use this for route transitions and tab panel swaps, where showing two elements simultaneously would be confusing.
+- **`mode: "sync"`** — enter and exit animations run simultaneously. Use this when you're swapping UI elements (like icon cross-fades) and want both transitions to happen at once.
+- **`mode: "popLayout"`** — the exiting element immediately pops out of the document flow so surrounding elements can animate into their new positions right away, while the exiting element still plays its exit animation. Ideal for list item removal.
+
+### Critical rule: `<AnimatePresence initial={false}>`
+
+When `AnimatePresence` wraps persistent UI that already exists on first render — like a tab panel that's visible on page load, or a sidebar that's open by default — you must pass `initial={false}`:
+
+```tsx
+<AnimatePresence initial={false}>
+  {isOpen && (
+    <motion.div key="panel" initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}>
+      {children}
+    </motion.div>
+  )}
+</AnimatePresence>
+```
+
+Without `initial={false}`, every component inside `AnimatePresence` will play its entrance animation on first mount, even when the user didn't trigger it. This is jarring and wrong — **never animate on initial load for existing UI**.
+
+---
+
+## 4. Layout Animations
+
+The `layout` prop is one of Framer Motion's most powerful features. Add `layout` to a `motion` component, and Framer automatically detects when the component's position or size changes in the DOM and animates it from the old layout to the new one — even if the change was caused by other elements shifting around it.
+
+```tsx
+<motion.div layout className="card">
+  {isExpanded ? <FullContent /> : <Summary />}
+</motion.div>
+```
+
+When `isExpanded` changes, Framer measures the old and new layouts and smoothly animates the transition. This works for position changes caused by sibling elements reordering, parent resizing, or content toggling.
+
+**`layoutId` — shared element transitions:** Assign the same `layoutId` to two different components, and Framer will morph between them when one unmounts and the other mounts. This is the canonical implementation for expanding card → detail transitions and hero → full-view animations.
+
+```tsx
+// Card in list view
+<motion.img layoutId={`product-image-${id}`} src={thumbnail} />
+
+// Same image in expanded modal
+<motion.img layoutId={`product-image-${id}`} src={fullImage} />
+```
+
+When the list-view card unmounts and the modal mounts, Framer animates the image from its list-view position to its modal position. The two components don't need to coexist — the transition bridges the gap.
+
+**Important:** ensure only one component with a given `layoutId` is mounted at a time. Two simultaneously mounted components with the same `layoutId` will fight each other and produce broken animations.
+
+**`layout="position"`:** Use this variant when you only want to animate the element's position, not its size. This prevents layout animation from attempting to smoothly resize the element when content-length changes cause size changes.
+
+---
+
+## 5. Variants and Orchestration
+
+Variants let you define named animation states as objects and apply them declaratively, rather than repeating animation values inline throughout your component tree.
+
+```tsx
+const containerVariants = {
+  hidden: { opacity: 0 },
+  visible: {
+    opacity: 1,
+    transition: {
+      staggerChildren: 0.05,
+      delayChildren: 0.1,
+    },
+  },
+}
+
+const itemVariants = {
+  hidden: { opacity: 0, y: 10 },
+  visible: { opacity: 1, y: 0 },
+}
+
+function AnimatedList({ items }) {
+  return (
+    <motion.ul
+      variants={containerVariants}
+      initial="hidden"
+      animate="visible"
+    >
+      {items.map(item => (
+        <motion.li key={item.id} variants={itemVariants}>
+          {item.label}
+        </motion.li>
+      ))}
+    </motion.ul>
+  )
+}
+```
+
+**Propagation:** When a parent has `variants` and `animate="visible"`, child `motion` components that also have `variants` will automatically receive the same `animate` value — they don't need their own `animate` prop. Framer propagates the state name down the tree.
+
+**`staggerChildren`** delays each child's animation start by the specified seconds after the previous child. A value of `0.05` means each item enters 50ms after the previous — the standard for list entrance animations. More than `0.08` seconds starts to feel slow; more than 6–8 items should stagger in parallel (`staggerChildren` + `staggerDirection` with a cap).
+
+**`delayChildren`** adds an initial delay before the first child begins, which gives the parent time to render visibly before its children start entering.
+
+---
+
+## 6. Gesture-Driven Motion
+
+Framer Motion provides props that animate elements in response to user gestures without requiring event handlers or state.
+
+**`whileHover`:** The animation state while the pointer is hovering. Prefer subtle transforms — `scale: 1.02` for a gentle grow or `y: -2` for a subtle lift. Avoid large scale values (> 1.05) on UI elements; they feel unstable.
+
+```tsx
+<motion.button whileHover={{ scale: 1.02 }} transition={{ type: 'spring', stiffness: 400, damping: 30 }}>
+  Save draft
+</motion.button>
+```
+
+**`whileTap`:** The animation state while the element is pressed. The canonical scale-on-press value is **0.96**. Never go below 0.95 (looks broken) and never above 0.98 (imperceptible) for primary interactive elements.
+
+```tsx
+<motion.button
+  whileHover={{ scale: 1.02 }}
+  whileTap={{ scale: 0.96 }}
+  transition={{ type: 'spring', stiffness: 400, damping: 30 }}
+>
+  Confirm
+</motion.button>
+```
+
+**`drag` + `dragConstraints`:** Enable drag with `drag` (either `true`, `"x"`, or `"y"`), and bound the drag region with `dragConstraints`. Use `dragElastic: 0.1` for a subtle resistance when dragging beyond the constraint boundaries — this gives physical feedback that the user has reached an edge.
+
+```tsx
+<motion.div
+  drag="x"
+  dragConstraints={{ left: -100, right: 100 }}
+  dragElastic={0.1}
+  whileDrag={{ scale: 1.05, cursor: 'grabbing' }}
+>
+  Drag me
+</motion.div>
+```
+
+**`whileDrag`:** Applies an animation state while the element is being dragged. Use it to provide visual feedback that the element is in motion (subtle scale-up, shadow, cursor change).
+
+---
+
+## 7. Scroll-Linked Animations
+
+**`useScroll()` + `useTransform()`:** For animations that respond continuously to scroll position, use `useScroll` to get `scrollYProgress` (a motion value from 0 to 1 representing document scroll) and `useTransform` to map that range to any animated value.
+
+```tsx
+import { useScroll, useTransform, motion } from 'framer-motion'
+
+function ParallaxHero() {
+  const { scrollYProgress } = useScroll()
+  const y = useTransform(scrollYProgress, [0, 1], [0, -200])
+
+  return (
+    <motion.div style={{ y }}>
+      <HeroImage />
+    </motion.div>
+  )
+}
+```
+
+Use `style={{ y }}` (not `animate`) for scroll-linked values because `animate` creates discrete state transitions, while `style` with a motion value creates continuous, real-time updates.
+
+**`whileInView` + `viewport`:** For elements that should animate when they enter the viewport (the most common scroll animation pattern), `whileInView` is more reliable than `useScroll`. It triggers a state change rather than a continuous value mapping, which is easier to reason about and less prone to performance issues.
+
+```tsx
+<motion.section
+  initial={{ opacity: 0, y: 20 }}
+  whileInView={{ opacity: 1, y: 0 }}
+  viewport={{ once: true, margin: '-100px' }}
+  transition={{ type: 'tween', duration: 0.4, ease: 'easeOut' }}
+>
+  <FeatureSection />
+</motion.section>
+```
+
+**`viewport={{ once: true }}`** is the preferred option for entrance animations — the element animates in once and stays visible. Without `once: true`, the element will animate every time it enters the viewport, which is usually wrong for entrance effects (and can feel janky during fast scrolling).
+
+---
+
+## 8. prefers-reduced-motion Compliance
+
+Respecting `prefers-reduced-motion` is **mandatory** for accessibility compliance. Some users have vestibular disorders or motion sensitivity — for them, unnecessary motion causes real physical discomfort. This is not optional polish; it is a WCAG 2.1 requirement.
+
+### Per-component approach with `useReducedMotion`
+
+```tsx
+import { useReducedMotion, motion } from 'framer-motion'
+
+function AnimatedCard() {
+  const prefersReducedMotion = useReducedMotion()
+
+  const transition = prefersReducedMotion
+    ? { duration: 0 }
+    : { type: 'spring', stiffness: 400, damping: 30 }
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: prefersReducedMotion ? 0 : 10 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={transition}
+    >
+      Content
+    </motion.div>
+  )
+}
+```
+
+When `prefersReducedMotion` is true, set `duration: 0` and remove any positional animation values — the element should appear instantly without motion.
+
+### App-wide approach with `MotionConfig` (preferred)
+
+The cleanest solution for most applications is to wrap the app root with `MotionConfig` using `reducedMotion: "user"`. This instructs Framer to automatically apply reduced-motion behavior for all motion components in the subtree when the OS preference is set — no per-component logic needed.
+
+```tsx
+import { MotionConfig } from 'framer-motion'
+
+function App() {
+  return (
+    <MotionConfig reducedMotion="user">
+      <Router />
+    </MotionConfig>
+  )
+}
+```
+
+`reducedMotion: "user"` reads the OS setting via `prefers-reduced-motion` media query and disables animations globally when it's set. This is the preferred approach because it's zero-maintenance — adding new animated components automatically inherits the behavior.
+
+---
+
+## 9. 60fps Performance Rules
+
+Animation performance on the web comes down to a single principle: **only animate properties that the browser can handle on the GPU compositor thread**. Everything else requires the browser to recalculate layout or repaint pixels — work that happens on the main thread and causes dropped frames.
+
+### Properties that are GPU-safe (always use these)
+
+- `x`, `y` — map to `translateX()` and `translateY()` in `transform`
+- `scale`, `scaleX`, `scaleY` — map to `scale()` in `transform`
+- `rotate`, `rotateX`, `rotateY`, `rotateZ`
+- `skewX`, `skewY`
+- `opacity`
+
+These properties run on the compositor thread and never block the main thread, regardless of how complex the rest of the page is.
+
+### Properties that cause jank (never animate these)
+
+- `width`, `height` — triggers layout recalculation on every frame
+- `margin`, `padding` — shifts surrounding elements, triggers full reflow
+- `border-width`
+- `left`, `top`, `right`, `bottom` (on positioned elements) — triggers layout
+- `font-size` — triggers layout and repaint
+
+If you need to animate a size change, use `scale` on a wrapper. If you need to animate position, use `x`/`y` rather than `left`/`top`. This distinction is why Framer's layout animation system (Section 4) works — it uses `transform` internally even when responding to layout-driven position changes.
+
+### `will-change: transform`
+
+Only add `will-change: transform` when you observe a first-frame stutter on a specific element. Do not add it preemptively — it forces the browser to allocate a separate GPU layer for the element immediately, consuming GPU memory whether or not the animation is actually playing. Reserve it for elements with known performance issues after profiling.
+
+---
+
+## 10. MotionConfig
+
+`MotionConfig` is a context provider that configures all `motion` components within its subtree. Use it for:
+
+- **Reduced motion compliance** — as shown in Section 8, `reducedMotion: "user"` is the cleanest global solution.
+- **Global transition defaults** — set a default transition for all motion components so individual components don't need to repeat the same `transition` prop.
+- **Custom ease functions** — define a custom cubic-bezier ease once and reference it by name throughout the tree.
+
+```tsx
+<MotionConfig
+  transition={{ type: 'spring', stiffness: 300, damping: 25 }}
+  reducedMotion="user"
+>
+  <App />
+</MotionConfig>
+```
+
+With this configuration, every `motion` component that doesn't specify its own `transition` will use the spring default, and the reduced-motion preference is respected automatically.
+
+---
+
+## 11. Common Pitfalls (from UUPM react.csv data)
+
+These are the mistakes that appear most frequently in codebases using Framer Motion:
+
+**Missing `initial` with `animate`:** If you add `animate={{ opacity: 1 }}` without `initial={{ opacity: 0 }}`, the element is already at opacity 1 on mount — there's nothing to animate from. Always pair `animate` with `initial` when you want an entrance effect.
+
+**Missing `key` props in `AnimatePresence`:** Exit animations will silently not fire if children of `AnimatePresence` don't have `key` props. Framer can't identify which element is leaving without a stable key.
+
+**Variant propagation only reaches `motion` children:** Parent variants propagate to child `motion` components, but not to plain HTML children or non-motion React components. If a list item is a plain `<li>` instead of `<motion.li>`, it won't receive the parent's variant orchestration.
+
+**`layoutId` conflicts:** If two components with the same `layoutId` are both mounted simultaneously — even briefly during a transition — Framer doesn't know which is the source and which is the target. The result is erratic, broken animation. Ensure mutual exclusivity: when one mounts, the other must have already unmounted.
+
+**Unnecessary `AnimatePresence` nesting:** Nesting `AnimatePresence` inside another `AnimatePresence` complicates exit orchestration — inner exits may not complete before outer exits begin. Keep the tree flat; use a single `AnimatePresence` at the appropriate level.
+
+**Wrapping everything in `motion.div`:** `motion.div` carries a slightly larger bundle footprint than a plain `div` because it registers the element with Framer's animation engine. Don't wrap static, unanimated elements. Only wrap elements that actually need animation. Reserve `motion.*` for elements where animation provides genuine value.

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.