@nerdev/skillset 0.2.1

package/skills/ui/ui-engineering/references/navigation.md

@@ -0,0 +1,81 @@
+# Navigation patterns
+
+Rules for choosing and implementing navigation patterns. For
+accessibility and responsive behavior, see accessibility.md and
+responsive.md.
+
+## Sidebar vs topbar
+
+- Sidebar: use when the app has 5 or more top-level destinations,
+  persistent state per section, or dense tooling (dashboards, IDEs,
+  mail clients). Left rail on desktop, drawer on mobile.
+- Topbar: use when there are 3 to 5 destinations, the page is
+  content-led, or the product is marketing/landing. Horizontal links
+  or tabs.
+- Mixed: sidebar for app chrome, topbar for page-level tabs within a
+  section. Don't nest both at the same level. One owns the primary
+  hierarchy.
+- Collapse rule: sidebar collapses to icon rail at `md`, to drawer at
+  `sm`. Icon rail labels appear on hover or on `lg+`.
+
+## Breadcrumbs
+
+- Show when the user is more than one level deep in a hierarchy.
+  Suppress on the home/landing level.
+- Truncate middle segments with an ellipsis when the path exceeds 4
+  segments. Keep the first and last two segments visible.
+- Clickable segments: every crumb except the current page is a link.
+  Current page is plain text, aria-current="page".
+- Separator: `/` or `›`. Pick one, stay consistent. Don't use chevrons
+  for every level in deep hierarchies. It becomes visual noise.
+
+## Tab bar vs segmented control
+
+- Tab bar: use for top-level destinations within a page or section.
+  Horizontal, always visible, under a section header.
+- Segmented control: use for toggling between 2 to 4 views of the same
+  data. Compact, inline, looks like a toggle group.
+- Don't mix: if the user needs to navigate to a different page, use
+  tabs or links. If the user needs to filter the same data, use a
+  segmented control.
+
+## Active-state indication
+
+- Current page: filled tab, bottom border, or background tint. Pick one
+  per product. Never underline + background + color change together.
+- Visited state: optional. If used, keep it subtle (slightly darker
+  text, not a color change). Don't treat visited like selected.
+- Hover state: background tint or underline. Never color shift alone.
+  Color is for active, not hover.
+
+## Mobile nav collapse patterns
+
+- Hamburger: use when there are more than 4 top-level destinations, or
+  when destinations are secondary. Icon-only button, aria-label
+  "Menu".
+- Bottom tab bar: use for 3 to 5 primary destinations in a mobile app.
+  Fixed to viewport bottom, safe-area-inset padding.
+- Tab bar in-page: use for 2 to 4 secondary destinations within a
+  single mobile screen. Horizontal scroll if needed, not dropdown.
+- Don't hide primary navigation behind a hamburger on mobile. If a
+  destination is primary, it belongs in a tab bar or topbar.
+
+## Nested nav: drawer vs flyout
+
+- Drawer: use for navigation trees deeper than 2 levels, or when the
+  secondary nav has its own structure. Swipe to dismiss on mobile.
+- Flyout: use for 2-level nav where the second level is short (3 to 5
+  items). Appears on hover/focus on desktop, tap on mobile.
+- Avoid: flyouts deeper than 2 levels. If the tree is deep, use a
+  drawer or a dedicated page.
+
+## Don'ts
+
+- Don't use breadcrumbs on a single-level page.
+- Don't mix tab-bar and topbar for the same hierarchy level.
+- Don't hide the active state. The user should never have to guess
+  where they are.
+- Don't use dropdowns for primary navigation. Dropdowns hide options.
+  Navigation should reveal them.
+- Don't animate nav reflows with stagger. One motion: the new state
+  appears, the old one leaves.

package/skills/ui/ui-engineering/references/overlays.md

@@ -0,0 +1,74 @@
+# Overlays
+
+Rules for dropdowns, tooltips, popovers, and positioning. For
+accessibility requirements, see accessibility.md.
+
+## Dropdown / select / menu
+
+- Positioning: below trigger, left-aligned by default. Above if
+  overflow. Collision handling is required, not optional.
+- Width: match the trigger width, or min 200px. Don't let the dropdown
+  shrink below the widest item.
+- Scroll: show scrollbar when items exceed viewport height minus 2x
+  item height. Max height 320px.
+- Selection: single-select uses a checkmark or highlight. Multi-select
+  uses checkboxes. Don't use checkmarks for multi-select.
+- Empty state: "No options" or "No results". Don't show an empty list
+  with no message.
+- Keyboard: arrow keys navigate, Enter selects, Esc closes. See
+  accessibility.md.
+
+## Tooltip
+
+- Placement: top by default, bottom if not enough space above.
+  Left/right for long text. Don't use tooltips for critical
+  information. Tooltips are discoverable, not guaranteed.
+- Trigger: hover for desktop, focus for keyboard. Don't show on click
+  alone.
+- Delay: 300 to 500ms show delay on hover. No delay on focus. Don't
+  make the user wait for a tooltip they triggered with keyboard.
+- Duration: stay visible while hovered. Don't auto-hide after a
+  timeout. The user controls dismissal.
+- Rich vs plain: plain tooltip is text only, max 1 to 2 lines. Rich
+  tooltip includes an icon or link, max 200px wide. Don't use rich
+  tooltips for simple descriptions.
+- Accessibility: tooltips are supplementary. The trigger must work
+  without the tooltip. Don't put critical instructions only in a
+  tooltip.
+
+## Popover vs tooltip vs dropdown
+
+- Popover: use when the overlay contains interactive content (forms,
+  buttons, links). Stays open on interaction. Focus moves inside.
+- Tooltip: use when the overlay is non-interactive text. Dismisses on
+  hover/focus loss. Focus doesn't move inside.
+- Dropdown: use when the overlay is a list of options. Selection is
+  explicit. Dismisses on selection or Esc.
+- Don't use a tooltip for a form field hint. Use help text or a
+  placeholder. Tooltips are for supplementary info, not required
+  reading.
+
+## Positioning and collision handling
+
+- Default position: below trigger, left-aligned. Above if overflow.
+- Flip: flip to the opposite side before clipping. Flip before
+  shifting.
+- Shift: shift along the axis if still clipping after flip. Don't
+  shift more than 50% of the overlay width.
+- Arrow: show arrow pointing to trigger when there's room. Hide when
+  close to edge. Arrow is decorative, not interactive.
+- Safe areas: don't position overlays under notches, home indicators,
+  or system UI. Use env(safe-area-inset-*) on mobile.
+
+## Don'ts
+
+- Don't show tooltips on touch devices by default. Touch doesn't have
+  hover. Use long-press or a dedicated info button instead.
+- Don't nest overlays. A dropdown inside a dropdown inside a popover is
+  a navigation dead end.
+- Don't use dropdowns for single actions. If there's only one option,
+  show the action directly.
+- Don't let overlays cover the trigger. The trigger must remain visible
+  or be clearly replaceable by the overlay.
+- Don't use tooltips for error messages. Errors belong inline, near the
+  field.

package/skills/ui/ui-engineering/references/pagination.md

@@ -0,0 +1,71 @@
+# Pagination and load-more patterns
+
+Rules for choosing between numbered pagination, "load more", and
+infinite scroll. For infinite-scroll implementation details, see
+ui-core/references/build.md.
+
+## Decision criteria
+
+- Numbered pagination: use when the user needs to jump to a specific
+  page, compare pages, or the data is truly paginated (search results,
+  table data). Shows page numbers, prev/next, and total count.
+- "Load more" button: use when the user is browsing a feed or list and
+  needs explicit control over pacing. Shows a button at the bottom of
+  the list.
+- Infinite scroll: use when the content is a continuous feed (social,
+  notifications) and the user is consuming, not searching. See
+  ui-core/references/build.md for implementation rules.
+- Don't mix: choose one pattern per list. A list with both "load more"
+  and infinite scroll is confusing.
+
+## Cursor-based vs offset-based pagination
+
+- Cursor-based: use for real-time or frequently changing data. The
+  cursor points to the last item, not a page number. UI shows "Load
+  more" or infinite scroll, not page numbers.
+- Offset-based: use for static or rarely changing data (archived posts,
+  reports). UI shows numbered pages.
+- UI difference: cursor-based never shows page numbers. Offset-based
+  can show page numbers, but doesn't have to.
+
+## Page-size selection
+
+- Show when the user is working with dense data (tables, lists) and
+  the page size affects usability. Hide for content feeds.
+- Placement: above the list, not below. Users look for controls before
+  they start consuming.
+- Options: 10, 25, 50, 100. Don't offer more than 4 options. Default
+  to 25 unless the data is dense (then 50) or sparse (then 10).
+- Persist: remember the user's choice per view. Don't reset on every
+  navigation.
+
+## Total counts
+
+- Show total count when the user needs to know the scope ("Showing 1-25
+  of 342 results"). Hide for infinite scroll feeds where the total is
+  unknown or not meaningful.
+- Format: "Showing 1-25 of 342" not "342 results". The first form
+  tells the user where they are, not just how much there is.
+- Don't show "Page 1 of 15" without also showing the range. Page
+  numbers alone don't tell the user how much data they're missing.
+
+## Scroll-position restoration
+
+- Restore scroll position when navigating back to a paginated list.
+  The user expects to return to where they were, not the top.
+- Implementation: store scroll position in a ref or state keyed by the
+  list identity. Restore on mount.
+- Don't restore for infinite scroll feeds. In infinite scroll, the
+  content is new every time. Restoring position would show stale data.
+
+## Don'ts
+
+- Don't show page numbers for cursor-based pagination. The cursor is
+  opaque. Page numbers are meaningless.
+- Don't use "load more" for search results. Search implies completion.
+  "Load more" implies there's more to find.
+- Don't hide the total count for paginated data. The user needs to know
+  the scope to make decisions.
+- Don't reset page size on every navigation. Persist per view.
+- Don't use infinite scroll for task-oriented lists. Infinite scroll is
+  for consumption, not completion.

package/skills/ui/ui-engineering/references/progress-indicators.md

@@ -0,0 +1,77 @@
+# Progress indicators
+
+Rules for choosing and implementing progress indicators. For skeleton
+and spinner patterns, see ui-core/references/build.md.
+
+## Determinate vs indeterminate
+
+- Determinate: use when the progress can be measured (upload, install,
+  form completion). Shows percentage or step.
+- Indeterminate: use when the duration is unknown but progress is
+  happening (loading data, processing). Shows animation, no percentage.
+- Do not guess: if you do not know the duration, use indeterminate. A
+  determinate bar that stalls at 90% is worse than an indeterminate
+  spinner.
+
+## Progress bar rules
+
+- Height: 4 to 8px for inline bars, 8 to 12px for standalone bars.
+  Thinner bars are subtler. Thicker bars are more prominent.
+- Fill direction: left to right for LTR, right to left for RTL. Use
+  logical properties or CSS transforms.
+- Percentage label: show when the percentage is meaningful (more than
+  10% steps). Hide for rapid progress where the number changes faster
+  than the user can read it.
+- Color: accent color for fill, muted border for track. Do not use
+  multiple colors to indicate "health". That is a status indicator, not
+  a progress bar.
+- Animation: smooth transition between values. Do not jump. 300ms ease
+  is fine here because the bar is the feedback, not a micro-interaction.
+
+## Step / wizard indicators
+
+- Linear steps: use when every step must be completed in order
+  (onboarding, checkout). Show step number, label, and completion
+  state.
+- Non-linear steps: use when steps can be skipped or reordered
+  (settings, configuration). Show steps as a list, not a progress bar.
+- Completed state: checkmark or filled step. Never remove completed
+  steps. The user needs to see progress.
+- Current step: accent color, larger or bolder. Do not use animation to
+  indicate the current step. Animation is for progress, not state.
+- Future steps: muted text or outline. Do not gray them out completely.
+  The user needs to see what is coming.
+
+## Multi-stage progress
+
+- Multi-stage: use when an operation has distinct phases (upload +
+  processing + complete). Show stage name and progress within the
+  current stage.
+- Stage transition: animate the stage name change, not the bar. The bar
+  resets for the new stage.
+- Error in multi-stage: show which stage failed, why, and how to retry
+  that stage. Do not restart from stage one.
+
+## Skeleton vs spinner vs progress bar
+
+- Skeleton: use when the content shape is known and the load is fast
+  (under 2s). See ui-core/references/build.md.
+- Spinner: use when the duration is unknown or the load is full-page.
+  See ui-core/references/build.md.
+- Progress bar: use when the progress is measurable. Do not use a
+  spinner when you can show a bar.
+- Do not show all three together. Pick one per loading state.
+
+## Avoid
+
+- Do not use indeterminate progress bars for operations that have a
+  known duration. If you know it takes 5 seconds, show a determinate
+  bar.
+- Do not animate progress bars with spring curves. Linear or ease-out
+  only.
+- Do not show percentage for very fast operations (under 1s). The
+  number changes too fast to read.
+- Do not use progress bars for multi-step wizards without showing the
+  step names. A bar alone does not tell the user where they are.
+- Do not hide progress indicators behind hover. Progress is critical
+  feedback. It must be visible.

package/skills/ui/ui-engineering/references/quality-bar.md

@@ -0,0 +1,293 @@
+# Quality Bar References
+
+**The standard.** Every UI decision should trace back to these references.
+
+
+## SaaS Gold Standard (Best "Feel": Snappy, Physics-Based)
+
+| Site | What to Steal | Why It Works |
+|------|---------------|--------------|
+| **Linear** | Command palette (⌘K), page transitions, cursor states, issue hover cards, keyboard shortcuts everywhere | Gold standard. Everything feels instant and intentional. |
+| **Raycast** | Website mirrors app speed; hover states, scroll reveals, copy-to-clipboard toast, keyboard-first nav | Razor-tight. No wasted motion. |
+| **Stripe** | Subtle gradient animations, docs pages with live code that morphs on scroll, careful color use | Restrained but delightful. Code blocks that animate on scroll. |
+| **Vercel** | Geometric motion, great restraint (not everything animates), clean type hierarchy | Confident minimalism. |
+| **Arc (The Browser Company)** | Playful micro-copy + micro-animation combo, onboarding flow, personality | Personality without chaos. |
+| **Attio / Cron (Notion Calendar)** | SaaS onboarding-style micro-interactions, drag-drop, inline editing | Product-led growth patterns. |
+
+
+## Agency/Showcase Tier (Heavier Animation, GSAP/WebGL)
+
+| Site | What to Steal | When to Use |
+|------|---------------|-------------|
+| **Awwwards Site of the Day** | Current trends, not fixed set | Dial = 3 only |
+| **Locomotive** | Smooth-scroll + parallax done right | Showcase landing pages |
+| **Basement.studio** | Experimental interactions, WebGL | Dial = 3, creative brands |
+| **Cuberto** | Character animation, fluid motion | Dial = 3 |
+| **Resn** | Immersive WebGL experiences | Dial = 3 |
+| **Active Theory** | Three.js + GSAP mastery | Dial = 3 |
+
+
+## Libraries/Tools (Beyond Aceternity)
+
+### Animation Engines
+| Library | Use For | Notes |
+|---------|---------|-------|
+| **motion.dev (Framer Motion)** | Page transitions, layout animations, enter/exit, gestures, basic scroll | Primary motion lib. `npm i motion` |
+| **GSAP + ScrollTrigger** | Scroll scrub, pin, snap, timelines, text/SVG morph, complex sequences | Showcase tier (dial=3). `npm i gsap` |
+| **Lenis** | Smooth scroll, pairs with GSAP | `npm i @studio-freight/lenis` |
+| **Rive** | Interactive vector animations that respond to state | Advanced, `npm i @rive-app/canvas` |
+
+### UI Primitives
+| Library | Use For | Notes |
+|---------|---------|-------|
+| **base-ui** | Dialogs, popovers, menus, selects, tooltips, combobox, tabs, accordion | Unstyled, accessible. `@base-ui-components/react` |
+| **Vaul** | Drawers, bottom sheets, side sheets | Gesture-driven. `npm i vaul` |
+| **cmdk** | Command palette (⌘K) | `npm i cmdk` |
+| **Radix UI** | Alternative to base-ui | More packages, similar philosophy |
+
+### Data & Forms
+| Library | Use For | Notes |
+|---------|---------|-------|
+| **TanStack Table** | Data tables, sorting, filtering, pagination, virtualization | `@tanstack/react-table` + `@tanstack/react-virtual` |
+| **Virtuoso** | Virtualized lists, feeds, chat, variable heights | `npm i react-virtuoso` |
+| **React Hook Form + Zod** | Forms, validation, server actions | `npm i react-hook-form @hookform/resolvers zod` |
+| **Sonner** | Toasts, notifications | `npm i sonner` |
+
+### Interaction Layer
+| Library | Use For |
+|---------|---------|
+| **dnd-kit** | Drag and drop |
+| **Vaul** | Drawers (already listed) |
+| **Radix/base-ui** | Popovers, tooltips, menus, selects |
+
+
+## Inspiration Galleries (Browse, Don't Copy)
+
+| Site | Best For |
+|------|----------|
+| **Awwwards** | Cutting-edge motion, WebGL |
+| **Mobbin** | Real UI patterns (not just heroes): mobile + desktop |
+| **Godly** | Curated landing pages |
+| **SiteInspire** | Design inspiration |
+| **Dribbble** | Micro-interaction concepts (search "micro-interaction") |
+| **Evil Charts** | Chart inspiration for data visualization UI |
+| **Kobbe.io** | Generous whitespace, clean typography, rounded aesthetic |
+| **Make.design** | Testimonial pages and polished design systems |
+| **Timmo.co.in** | Clean layout and modern SaaS feel |
+
+## What to Steal (Transferable Principles)
+
+| Reference | Principle to Extract |
+|-----------|----------------------|
+| **Linear** | Command palette as primary navigation. Hover cards that surface context without leaving the page. Page transitions that feel like state changes, not scenes. |
+| **Raycast** | Hover states that are near-instant. Copy-to-clipboard feedback that is visible but not intrusive. Keyboard-first means every click target has a keyboard target. |
+| **Stripe** | Gradient animations tied to scroll, not decoration. Code blocks that respond to user action. Color that leads the eye, not decorates it. |
+| **Vercel** | Geometric motion where the shape change is the feedback. Type hierarchy so strong it needs no color. Restraint as a feature, not a limit. |
+| **Arc** | Micro-copy that matches micro-animation. Onboarding that teaches through doing, not explaining. Personality in the pauses, not the noise. |
+| **Attio/Cron** | Inline editing that feels like paper, not a form. Drag-drop that snaps with intention. Micro-interactions that confirm the action, not announce it. |
+| **Kobbe.io** | Whitespace as rhythm. Generous section padding that lets content breathe. Typography with clean roundness that feels modern without being bubbly. |
+| **Make.design** | Testimonial pages where the quote is the hero, not the logo. Attribution that adds weight through simplicity. Visual rhythm that makes scrolling feel intentional. |
+| **Evil Charts** | Minimal ink: gridlines removed until the chart breaks, then added back sparingly. Annotations over legends. One accent per series, hue not lightness for distinction. |
+| **Timmo.co.in** | Clean SaaS feel through consistent spacing and restrained color. Layout that trusts the content without over-decorating. |
+
+
+## GitHub Repos to Study
+
+| Repo | Why |
+|------|-----|
+| `gastownhall/beads` | Motion primitives, gesture handling |
+| `addyosmani/agent-skills` | AI agent patterns |
+| `mattpocock/skills` | TypeScript patterns |
+
+
+## Token Templates (Starting Points)
+
+### Clinical (Linear-style)
+```css
+:root {
+  --accent: 220 100% 50%;        /* Blue */
+  --gray: 220 15% 20%;           /* Cool gray */
+  --radius: 0.5rem;              /* 8px */
+  --font-sans: 'Inter', system-ui;
+  --font-mono: 'JetBrains Mono', monospace;
+  --transition: 150ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+### Sharp/Editorial (Stripe-style)
+```css
+:root {
+  --accent: 340 100% 50%;        /* Pink/red */
+  --gray: 240 10% 15%;           /* Warm dark */
+  --radius: 0.375rem;            /* 6px */
+  --font-sans: 'Space Grotesk', system-ui;
+  --font-display: 'Space Grotesk', system-ui;
+  --transition: 200ms cubic-bezier(0.16, 1, 0.3, 1);
+}
+```
+
+### Playful (Arc-style)
+```css
+:root {
+  --accent: 280 100% 60%;        /* Purple */
+  --gray: 260 10% 15%;           /* Purple-tinted dark */
+  --radius: 0.75rem;             /* 12px */
+  --font-sans: 'DM Sans', system-ui;
+  --font-display: 'DM Sans', system-ui;
+  --transition: 250ms cubic-bezier(0.34, 1.56, 0.64, 1); /* Bouncier */
+}
+```
+
+### Dense/Terminal (Bloomberg-style)
+```css
+:root {
+  --accent: 120 100% 40%;        /* Green */
+  --gray: 0 0% 10%;              /* True black/white */
+  --radius: 0;                   /* No radius */
+  --font-sans: 'IBM Plex Mono', monospace;
+  --font-mono: 'IBM Plex Mono', monospace;
+  --transition: 100ms ease-out;
+}
+```
+
+
+## Motion Recipes (Copy-Paste Starting Points)
+
+### Page Transition (Linear)
+```tsx
+// app/layout.tsx
+<AnimatePresence mode="wait" initial={false}>
+  <motion.div
+    key={pathname}
+    initial={{ opacity: 0, y: 16 }}
+    animate={{ opacity: 1, y: 0 }}
+    exit={{ opacity: 0, y: -16 }}
+    transition={{ type: 'spring', stiffness: 500, damping: 30 }}
+  >
+    {children}
+  </motion.div>
+</AnimatePresence>
+```
+
+### Modal/Sheet Enter/Exit
+```tsx
+const modalTransition = {
+  initial: { opacity: 0, scale: 0.97 },
+  animate: { opacity: 1, scale: 1 },
+  exit: { opacity: 0, scale: 0.97 },
+  transition: { type: 'spring', stiffness: 500, damping: 30 },
+}
+```
+
+### Button Press (Raycast)
+```tsx
+<motion.button
+  whileHover={{ scale: 1.02 }}
+  whileTap={{ scale: 0.97 }}
+  transition={{ type: 'spring', stiffness: 600, damping: 20 }}
+>
+```
+
+### Stagger (Onboarding Only)
+```tsx
+<motion.ul
+  initial="hidden"
+  animate="show"
+  variants={{
+    hidden: { opacity: 0 },
+    show: { transition: { staggerChildren: 0.05 } },
+  }}
+>
+  {items.map(item => (
+    <motion.li key={item.id} variants={{ hidden: { opacity: 0, x: -20 }, show: { opacity: 1, x: 0 } }}>
+      {item.label}
+    </motion.li>
+  ))}
+</motion.ul>
+```
+
+### Scroll Reveal (Stripe)
+```tsx
+// Use GSAP for this
+gsap.from('.reveal', {
+  y: 60,
+  opacity: 0,
+  duration: 1,
+  ease: 'power3.out',
+  scrollTrigger: { trigger: '.reveal', start: 'top 85%' },
+})
+```
+
+
+## Component Checklist (Finish Gate)
+
+Every component must pass:
+
+- [ ] **One clear action**: Primary CTA obvious
+- [ ] **Color in small doses**: 1 accent, used only for actions
+- [ ] **Whitespace separates**: No borders/shadows for separation
+- [ ] **Real type hierarchy**: Display / Body / Hint (not 5 bold sizes)
+- [ ] **Feedback matches action**: Press = visual, Done = quiet, Destructive = confirm
+- [ ] **Dark mode works**: `theme="system"` wired
+- [ ] **Reduced motion works**: Instant state changes
+- [ ] **No em dashes**: In visible text
+- [ ] **Accessibility**: Keyboard, ARIA, focus visible, contrast AA
+- [ ] **TypeScript strict**: No `any`, discriminated unions
+- [ ] **Tailwind component-based**: Tokens first, raw CSS only with reason
+
+
+## Anti-Patterns (Auto-Reject)
+
+| Pattern | Rejection Reason |
+|---------|------------------|
+| Purple gradient background | AI slop marker |
+| Glowing buttons | AI slop marker |
+| Oversized rounded cards (2xl+) | AI slop marker |
+| Floating orbs in hero | Unless product IS orbs |
+| Stagger on every page load | Daily interactions = subtle/fast |
+| Scroll-jacking | User owns scroll |
+| Infinite marquee | Loops forever = no purpose |
+| `transition: all 0.3s ease` | Lazy, animates layout |
+| `ease-in-out` | Elevator curve, not UI |
+| No reduced-motion support | Accessibility fail |
+| Missing exit animation | One-frame vanish = flicker |
+| Focus not trapped in modal | Keyboard trap |
+| No ESC to close modal | UX fail |
+
+
+## Decision Tree (When User Says Vague Things)
+
+| User Says | You Ask | You Pick |
+|-----------|---------|----------|
+| "Make it pop" | "Linear-sharp? Arc-playful? Stripe-gradient?" | One |
+| "Add animations" | Load `motion` → Run Decide phase | Only what passes |
+| "Nice toast" | Load `ask-toast` → `ask-sonner` | `richColors`, action buttons |
+| "Command palette" | Load `ask-command-menu` → `ask-cmdk` | Full keyboard nav |
+| "Smooth scroll" | Dial check: if 3 → GSAP+Lenis, else motion.dev | Appropriate lib |
+| "Data table" | Load `ask-table` → `ask-tanstack-table` | Virtualized, sortable |
+| "Form" | Load `ask-form` → `ask-rhf` | Zod schema, server actions |
+
+
+## Quick Reference: Skill Loading Map
+
+```
+User: "Build the FE/UI"
+    │
+    ├─► ui-engineering (orchestrates all)
+    │     ├─► house-style (LAW)
+    │     ├─► ui (process)
+    │     ├─► pick-ui-library (per interaction)
+    │     │     ├─► ask-modal → ask-base-ui
+    │     │     ├─► ask-toast → ask-sonner
+    │     │     ├─► ask-animation → ask-motion (or ask-gsap if dial=3)
+    │     │     ├─► ask-command-menu → ask-cmdk
+    │     │     ├─► ask-form → ask-rhf
+    │     │     ├─► ask-table → ask-tanstack-table
+    │     │     ├─► ask-virtual-list → ask-virtuoso
+    │     │     └─► ask-drawer → ask-vaul
+    │     ├─► motion (name→decide→build→review)
+    │     ├─► impeccable (audit→polish→animate→verify)
+    │     └─► prototype (optional divergence)
+    │
+    └─► References: quality-bar + tokens + motion-recipes + component-checklist + navigation + search + pagination + progress-indicators + avatars + overlays + floating-actions + card-patterns + tailwind-architecture + ui-core (build, verify, system, accessibility, responsive, dark-mode, copy, direction, styles, redesign)
+```

package/skills/ui/ui-engineering/references/search.md

@@ -0,0 +1,68 @@
+# Search patterns
+
+Rules for search input placement, behavior, and results. For keyboard
+nav within results, see accessibility.md. For command-palette search,
+see the cmdk skill.
+
+## Input placement
+
+- Inline search: use when search is the primary action on a page
+  (inbox, docs, file browser). Full width on mobile, constrained on
+  desktop.
+- Command palette: use when search is a power-user shortcut across the
+  whole product. Triggered by ⌘K, not always visible. See
+  ask-command-menu.
+- Inline + command palette: both can coexist. Inline is the visible
+  entry point. Command palette is the keyboard-accessible expansion.
+- Don't bury inline search inside a dropdown. If search is primary, it
+  should be visible.
+
+## Autocomplete and suggestions
+
+- Show suggestions after 2 or more characters, not on focus alone.
+  Focus alone is a convenience, not a search trigger.
+- Debounce: 200-300ms for local data, 300-500ms for remote. Faster
+  feels instant. Slower feels laggy.
+- Keyboard nav: arrow keys move through results, Enter selects, Esc
+  closes. See accessibility.md for focus management.
+- Highlight: bold the matching substring in results. Don't highlight
+  the whole result. That defeats the purpose.
+- Recent searches: show below the input when empty, above live results
+  when typing. Max 5 recent items. Allow delete per item and clear all.
+
+## Empty search state
+
+- No query yet: show placeholder text with a format hint ("Search
+  projects..."), not a label ("Search").
+- No results: "No results for [query]" with a clear-filter action.
+  Don't show "Try different keywords". That's condescending.
+- Error state: "Something went wrong" is never enough. Say what
+  happened and offer retry.
+
+## Result highlighting
+
+- Highlight matching text in the result, not the surrounding context.
+  Context is helpful, but the match is what the user is looking for.
+- Don't highlight more than 2 or 3 segments per result. Too much
+  highlighting looks like noise.
+- Case-insensitive matching. Preserve original casing in results.
+
+## Keyboard nav within results
+
+- Arrow keys navigate results, Enter selects, Esc closes. See
+  accessibility.md for focus-trap rules.
+- Type-ahead: typing while results are open jumps to the next result
+  starting with that character. Don't require reopening the list.
+- Don't trap focus in the search input. Tab should move to the next
+  interactive element, not cycle within results.
+
+## Don'ts
+
+- Don't search on focus. Search is an action, not a reveal.
+- Don't show more than 8 to 10 results without a "Show all" link.
+  Infinite scroll in search results is disorienting.
+- Don't highlight every occurrence. One or two matches per result is
+  enough.
+- Don't use dropdowns for search results. Dropdowns imply a single
+  selection. Search results imply a list of options.
+- Don't forget the empty state. An empty result is still a result.