@nqlib/nqui 0.5.6 → 0.6.1

package/docs/nqui-skills/MOTION.md

@@ -0,0 +1,189 @@
+---
+name: nqui-motion
+description: Motion design as a system, not decoration. Easing vocabulary, timing scale, choreography, reduced-motion. Use when adding ANY animation or transition. Without this, motion is either absent (cold) or busy (chaotic).
+---
+
+# nqui Motion — Choreography, Not Decoration
+
+Motion is design. It either serves comprehension (showing where something came from, conveying hierarchy, providing feedback) or it's noise. This file is the vocabulary.
+
+## Three motion principles
+
+1. **Motion has a job.** Every animation answers one of: *Where did this come from? Where did it go? What changed? What's happening right now?* If you can't answer, cut the animation.
+2. **Motion respects continuity.** Things appear from their source (Sheet slides from edge, Popover scales from its trigger, Toast slides from the toast region — never from random space).
+3. **Motion gets out of the way.** A confirmation animation that takes 600ms means the user waits 600ms before moving on. Make motion fast unless it's communicating something significant.
+
+## The timing scale
+
+Use named tokens, not arbitrary milliseconds. These cover 95% of UI motion.
+
+| Token | Duration | When to use |
+|-------|----------|-------------|
+| **instant** | 0ms (no animation) | State toggles where motion would be a delay (`checked`, `disabled`) |
+| **micro** | 100ms | Hover states, focus rings, color shifts on press |
+| **quick** | 150ms | Most state changes: opening dropdowns, button presses, small reveals |
+| **standard** | 200-250ms | Modal/Sheet/Drawer entries, page transitions, accordion expansions |
+| **dramatic** | 300-400ms | One-off attention moments — initial empty state appearing, success confirmation, onboarding cues |
+| **never** | ≥500ms | Almost nothing. If you reach for 500ms+, you're decorating, not communicating |
+
+**Default if unsure:** 150ms (`quick`). Most UI motion should be this fast.
+
+## The easing vocabulary
+
+Easing curves communicate **physicality** — they tell the eye whether something is decelerating naturally (good) or moving mechanically (bad).
+
+| Curve | Tailwind / CSS | When |
+|-------|---------------|------|
+| **ease-out** (`cubic-bezier(0.16, 1, 0.3, 1)`) | `ease-out` | **Default for entrances.** Things decelerate as they arrive — feels natural |
+| **ease-in** (`cubic-bezier(0.4, 0, 1, 1)`) | `ease-in` | **Default for exits.** Things accelerate as they leave — out of the way |
+| **ease-in-out** | `ease-in-out` | Reserved for symmetric back-and-forth (toggle that animates same way both directions) |
+| **linear** | `linear` | Only for continuous motion (loading bar, spinner, marquee) — never for state changes |
+| **spring** (react-spring / framer) | — | Only when modeling physical objects (drag, drawer pull). Subtle, not bouncy |
+
+**Banned curves:** elastic, bounce, anything with overshoot > 10%. They look dated and tacky. Real objects decelerate smoothly; they don't sproing.
+
+## Animate this, never animate that
+
+| ✅ Animate | ❌ Never animate |
+|------------|------------------|
+| `opacity` | `width` / `height` (use grid-row tricks if you need height transition) |
+| `transform` (translate, scale, rotate) | `top` / `left` / `right` / `bottom` |
+| `filter: blur()` (sparingly) | `padding` / `margin` |
+| `background-color` (subtle, fast) | `box-shadow` (very expensive — use opacity on a shadow layer instead) |
+| `color` | `font-size` |
+| CSS variables (modern, GPU-friendly) | Layout properties that cause reflow |
+
+**Why:** transform and opacity are GPU-composited and free. Layout properties cause reflow and jank, especially during scroll.
+
+## What to animate, when
+
+### Entrance / exit (mount, unmount)
+- **Modal/Dialog:** scale from 95% + fade in, 200ms ease-out
+- **Sheet:** translate from off-screen edge, 250ms ease-out (in), 200ms ease-in (out)
+- **Popover/Tooltip:** scale from 95% + fade, 150ms ease-out, origin at trigger
+- **Toast:** slide in from toast region (usually bottom or top-right), 200ms ease-out
+- **Empty state on first appearance:** fade in + translate up 4px, 300ms ease-out
+- **List items appearing:** stagger 30ms per item, fade + translate up 8px each, ease-out
+
+### State changes
+- **Selection (item in a list):** background color shift, 150ms
+- **Button press:** scale 0.97 for 100ms, then back — micro-affordance
+- **Hover:** background or color shift, 100ms — never transform
+- **Focus ring:** instant appear, fade out at 150ms
+
+### Attention direction (use sparingly)
+- **Skeleton → real content:** crossfade 150ms (avoid the "snap")
+- **Optimistic item appearing:** fade in at 70% opacity, then to 100% when confirmed
+- **Error shake:** translate x ±4px, 4 cycles of 50ms each — only for form submission errors with severity
+
+### Continuous (loading)
+- **Spinner:** 1 full rotation per 900ms, linear
+- **Skeleton shimmer:** 1.5s loop, ease-in-out, very subtle (8-12% opacity range)
+- **Loading bar (indeterminate):** 1.5s loop, ease-in-out
+- **Progress bar (determinate):** transition `width` change with 200ms ease-out (this is one of the few times width animation is OK because it represents real progress)
+
+## Choreography — when multiple things move
+
+Bad: everything animates at once → chaos.
+Good: a clear sequence the eye can follow.
+
+### Stagger
+When N similar things appear (list items, cards, nav items), animate them sequentially with a small delay (20-40ms between each). Stagger creates a sense of rhythm and avoids the "everything pops at once" feel.
+
+```tsx
+{items.map((item, i) => (
+  <div
+    key={item.id}
+    style={{ animationDelay: `${i * 30}ms` }}
+    className="animate-fade-in-up"
+  >
+    ...
+  </div>
+))}
+```
+
+**Cap stagger at ~8 items.** Beyond that, the last items appear so late it feels broken. For larger lists, skip the stagger or use a much smaller delay (10ms).
+
+### Sequence (different things, in order)
+When a complex element appears, parts can arrive in sequence — but only when sequence conveys meaning:
+
+```
+modal appears:
+  backdrop fades in (150ms)
+  → modal scales in (200ms, starts at 50ms — backdrop catches up)
+  → modal content fades in (150ms, starts at 200ms)
+```
+
+**Default to simultaneous unless sequence is meaningful.** Don't sequence parts of a single UI element — that fragments perception.
+
+## Reduced motion (mandatory)
+
+Respect `prefers-reduced-motion: reduce`. This is not optional — vestibular disorders are real.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+**What survives reduced motion:**
+- Opacity transitions (fade in/out) — these don't cause vestibular issues
+- Color transitions — fine
+- Subtle scale (≤ 5% change) — fine
+
+**What gets disabled:**
+- All translate-based animations (slide-in, slide-up)
+- Spinners (replace with text "Loading…")
+- Parallax, scroll-driven motion
+- Auto-playing carousels
+
+**The pattern:** wrap motion in a media query and provide a static alternative:
+
+```tsx
+const prefersReducedMotion = useReducedMotion()
+
+<div className={prefersReducedMotion ? "" : "animate-slide-in"}>
+  {content}
+</div>
+```
+
+## Anti-patterns (the AI-motion ones)
+
+These are the motion patterns that immediately signal AI-generated:
+
+| ❌ Anti-pattern | ✅ Use instead |
+|----------------|---------------|
+| Bouncing/elastic everything | Smooth ease-out, no overshoot |
+| 500ms+ for routine state changes | 150ms |
+| Animating layout (width/height/padding) | Transform + opacity |
+| Sequential typewriter text reveal | Just render the text |
+| Hover scales > 1.05 | Hover background shift only |
+| Wobbly button presses | scale(0.97) for 100ms, done |
+| Marquee scrolling text in non-marketing UI | Truncate with ellipsis |
+| Pulsing CTAs to "draw attention" | Better hierarchy, not motion |
+| Spinning logos | Why? Just why? |
+| Hero "shimmer" effects on every gradient | One shimmer, on one element, occasionally |
+| Per-letter text animation in product UI | Reserve for marketing landing pages |
+
+## The motion audit
+
+Before shipping:
+
+- [ ] Every animation answers one of the four "why" questions (where from / where to / what changed / what's happening)
+- [ ] No animation is longer than 250ms unless it's the rare "dramatic" moment
+- [ ] Animating only `transform` and `opacity` (no layout props)
+- [ ] Easing is ease-out for entrances, ease-in for exits (never linear except for continuous)
+- [ ] `prefers-reduced-motion: reduce` is respected — verified with the OS toggle
+- [ ] No bounce, elastic, or overshoot curves anywhere
+- [ ] Stagger capped at ~8 items
+- [ ] No infinite/looping animation outside of loading states
+- [ ] Hover states are color/background shifts, not transforms
+
+If anything moves "to look cool" rather than to serve comprehension, cut it.

package/docs/nqui-skills/README.md

@@ -6,10 +6,12 @@ These files mirror the **nqui** Cursor skills. They live in the `@nqlib/nqui` pa
 | Skill                                                                         | Path                                                                                   |
 | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | Hub (start here)                                                              | [SKILL.md](./SKILL.md)                                                                 |
+| **Composition (product UI, recipes vs catalog)**                              | [COMPOSITION.md](./COMPOSITION.md)                                                     |
 | **Task → components (designers)**                                             | [HUMAN_GUIDE.md](./HUMAN_GUIDE.md)                                                     |
 | **Component doc routing (agents; read first; saves tokens)**                  | [COMPONENTS_INDEX.md](./COMPONENTS_INDEX.md)                                           |
 | Per-component markdown (copied by `init-skills` to `.cursor/.../components/`) | `docs/components/` in repo; `components/` under this folder after init                 |
 | Components & layouts                                                          | [nqui-components/SKILL.md](./nqui-components/SKILL.md)                                 |
+| Data tables + ScrollArea (dashboard grids)                                    | [nqui-data-tables/SKILL.md](./nqui-data-tables/SKILL.md)                               |
 | Design system (sizing, Card + ScrollArea)                                     | [nqui-design-system/SKILL.md](./nqui-design-system/SKILL.md)                           |
 | shadcn-style usage rules                                                      | [nqui-shadcn/SKILL.md](./nqui-shadcn/SKILL.md)                                         |
 | Bundle size & peers                                                           | [nqui-bundle-size-best-practices/SKILL.md](./nqui-bundle-size-best-practices/SKILL.md) |

package/docs/nqui-skills/READ_BUDGET.md

@@ -0,0 +1,60 @@
+---
+name: read-budget
+description: Minimal-read routing for nqui agent tasks. Tells you which files to load (and which NOT to) for common tasks. Read this FIRST when the task is unclear — it will route you to ~1-3 files instead of bulk-reading the whole skills folder.
+---
+
+# Read Budget — load only what you need
+
+The skills folder has ~50 files totaling ~5000 lines. Bulk reading wastes context. Use this table to load 1–3 files per task.
+
+## Routing
+
+| Task | Read THIS | Then maybe | Do NOT read |
+|------|-----------|------------|-------------|
+| **Build a new view from scratch** | `SKILL.md` (Agent Build Protocol — 10 steps) → `nqui-composition/SKILL.md` (craft) → `COMPOSITION.md` (pattern) → `RECIPES.md` (combos) | `STATES.md` (state matrix), `WRITING.md` (copy), one `components/nqui-<name>.md` per component | MOTION.md unless you're adding animation, full component README |
+| **"How do I compose X?"** (status, bulk action, toolbar, loading state) | `RECIPES.md` (one numbered recipe) | The component(s) the recipe names | nqui-composition (philosophy, not needed for combo lookup) |
+| **Make UI feel more Apple / refined** | `nqui-composition/SKILL.md` (three principles + hierarchy rules) | `RECIPES.md` to replace busy combos | Refinement skills — fix the composition first |
+| **Make sure I've covered all states** | `STATES.md` (audit checklist) | — | nqui-composition (covered separately) |
+| **Write copy / labels / error messages / empty states** | `WRITING.md` | — | nqui-composition, components |
+| **Add transitions or animations** | `MOTION.md` (timing scale + easing) | The specific component's doc if it has motion-related props | All refinement skills |
+| **Layered UI / nested cards / "this needs more depth"** | `ELEVATION.md` (the 2+1 rule + decision tree) | `nqui-design-system/SKILL.md` for the token names | Refinement skills until depth is right |
+| **Run pre-ship review** | `SKILL.md` 30-second Linear designer test → `STATES.md` audit → `WRITING.md` audit → `MOTION.md` audit | `/audit` for technical/accessibility check | Refinement skills until the audits pass |
+| **Set up an AI agent to use nqui** | `AGENT_PROMPT.md` (paste into agent system prompt) | `SKILL.md` Agent Build Protocol | Skills folder — agent will discover via routing |
+| **Customize brand color / radius / palette** | `THEMING.md` | `colors.css` for the actual token names | Refinement skills, recipes |
+| **Verify a release before publishing** | `EVAL.md` (run the 12-prompt eval) | `MIGRATION.md` to note breaking changes | All other skills — eval drives the priority |
+| **Update consumer app after upgrade** | `MIGRATION.md` (latest section) | `THEMING.md` if customizations need re-verification | — |
+| **Build auth / login / signup / OAuth / OTP / SSO** | `RECIPES.md` recipes 16-22 | One component doc per Field used | `Dialog`-related docs (auth is page-level, not modal) |
+| **Choose between similar components** (Select vs Combobox, Dialog vs Sheet) | `COMPONENTS_INDEX.md` (inline decision tables) | One winner doc | Other component docs, COMPOSITION.md |
+| **Fix a specific component's behavior** | `components/nqui-<name>.md` (single file) | `nqui-design-system/SKILL.md` only if sizing/spacing | `impeccable/`, refinement skills |
+| **Card + ScrollArea / flex height bug** | `components/nqui-scroll-area.md` §0 (symptom routing) | §1 if §0 doesn't match | Other §, COMPOSITION.md |
+| **Data table with sticky header / paging** | `nqui-data-tables/SKILL.md` | `components/nqui-scroll-area.md` §0–§6 | `nqui-table.md` (different component) |
+| **Form (login, settings, checkout)** | `nqui-shadcn/rules/forms.md` | `components/nqui-field.md`, `nqui-input.md` | COMPOSITION.md form recipe is enough alone |
+| **Toolbar selection (mode, format)** | `nqui-components/SKILL.md` (ToggleGroup rules section only) | `components/nqui-toggle-group.md` | `nqui-radio-group.md` (wrong default) |
+| **Audit / review existing UI** | `audit/SKILL.md` | One specific reference IF a finding needs depth (see `impeccable/reference/INDEX.md`) | Full `impeccable/SKILL.md` if `.impeccable.md` exists |
+| **Apply a refinement** (`/layout`, `/colorize`, etc.) | The specific skill `SKILL.md` | `.impeccable.md` (project context, NOT the full impeccable skill) | Other refinement skills, full `impeccable/SKILL.md` |
+| **Design philosophy / anti-patterns** | `impeccable/SKILL.md` (one time, then trust it's loaded) | `impeccable/reference/<topic>.md` for one specific topic | All reference files at once |
+| **Install / setup / version migration** | `nqui-install/SKILL.md` OR `nqui-local-published-toggle/SKILL.md` | — | impeccable, components |
+
+## Rules of thumb
+
+1. **One-and-done lookups** (component prop, when-to-use): `COMPONENTS_INDEX.md` first, then ONE file. Stop.
+2. **Build tasks**: `SKILL.md` Agent Build Protocol → never deviate from its step order.
+3. **Don't reload `impeccable/SKILL.md`** if the conversation has already touched a design skill — its context persists.
+4. **`reference/` subdirectories** require an index — see `impeccable/reference/INDEX.md`. Do NOT bulk-read references.
+5. **`.impeccable.md` in project root** is the project's design context. Refinement skills should check it, not reload the full impeccable skill.
+
+## File-size hints (for picking the cheapest read)
+
+- Per-component docs: typically 15–70 lines. Largest: `nqui-scroll-area.md` (175), `nqui-combobox.md` (158).
+- `impeccable/SKILL.md`: ~360 lines — expensive. Load once per conversation.
+- `impeccable/reference/*`: 70–195 lines each. Use the index, never all.
+- `COMPOSITION.md`: ~220 lines. Contains all named layout patterns + checklist.
+- Refinement skill `SKILL.md` files: typically 100–150 lines.
+
+## Token-saving anti-patterns
+
+- ❌ Loading `components/README.md` (large index file) when `COMPONENTS_INDEX.md` answers the question
+- ❌ Bulk-reading `impeccable/reference/*` to "be thorough"
+- ❌ Re-invoking `/impeccable` mid-conversation when context is already loaded
+- ❌ Reading multiple refinement skills before choosing one — pick based on description
+- ❌ Reading all 65 component docs to "discover" what's available — use `COMPONENTS_INDEX.md` area tables