@jini-ai/agent-plugins 0.6.17 → 0.6.19

package/ui-ux-design/skills/ui-ux-design/references/foundations.md

@@ -0,0 +1,145 @@
+# Foundations
+
+Use this reference when creating or extending the visual system for a product or feature.
+
+This file owns the token, layout, and visual-system contract. `ui-loop.md` owns the
+resulting page/screen quality review; do not treat this reference's decisions or
+anti-patterns as a substitute completion checklist.
+
+## Goals
+
+- Define a stable visual foundation before designing individual screens.
+- Give Programmer a constrained, reusable system instead of one-off styling decisions.
+- Preserve existing product patterns unless the user explicitly wants a new direction.
+
+## Required Decisions
+
+1. Visual direction
+2. Color and semantic token system
+3. Typography hierarchy
+4. Spacing scale
+5. Layout/container/grid rules
+6. Breakpoint behavior
+7. Elevation, border, radius, and motion primitives
+
+## Minimum Foundation Contract
+
+### Visual Direction
+
+Define:
+
+- product character in 3-5 adjectives
+- intended level of formality
+- density target: compact, balanced, spacious
+- contrast profile: restrained, moderate, bold
+- reuse vs reinvention decision
+
+If working within an existing system, document continuation rules instead of inventing a new style.
+
+### Token Categories
+
+Create or extend tokens for:
+
+- surface/background
+- text/foreground
+- border/separator
+- interactive/brand
+- success/warning/error/info
+- focus ring
+- shadow/elevation
+- radius
+- spacing
+- typography
+- motion duration/easing
+
+Prefer semantic names over raw color names.
+
+### Typography
+
+Define:
+
+- display or hero style if needed
+- heading scale
+- body sizes
+- caption/supporting text
+- monospace usage if relevant
+- line-height and weight rules
+
+### Spacing
+
+Use a consistent scale. Typical safe pattern:
+
+- `4, 8, 12, 16, 24, 32, 48, 64`
+
+Apply the same scale to:
+
+- margins
+- padding
+- grid gaps
+- section rhythm
+- component spacing
+
+### Layout
+
+Define:
+
+- max content widths
+- section padding rules
+- grid column behavior
+- stack behavior on narrow screens
+- sticky or persistent UI elements if any
+
+Default to mobile-first.
+
+### Breakpoints
+
+Document behavior at:
+
+- mobile
+- tablet
+- desktop
+- large desktop if relevant
+
+Describe behavior, not just widths:
+
+- navigation changes
+- card/list reflow
+- sidebar collapse/expand
+- media cropping
+- density and spacing adjustments
+
+## Theming
+
+Do not require multiple themes by default.
+
+If theming is in scope, define:
+
+- what tokens change
+- contrast rules
+- image/media treatment changes
+- persistence behavior
+
+Do not add a theme toggle only because it is possible.
+
+## Anti-Patterns
+
+- hardcoded one-off colors across components
+- spacing chosen ad hoc per screen
+- headings without a system
+- desktop-first layout that collapses poorly on mobile
+- decorative motion without purpose
+- dark mode or theme switching as mandatory default
+
+## Reference-Specific Output
+
+Record the applicable foundation decisions in the authorized design artifact or
+living visual `design.md`:
+
+- visual direction named
+- semantic token groups defined
+- typography hierarchy defined
+- spacing scale defined
+- breakpoints documented
+- layout rules documented
+- motion/elevation basics documented
+- assumptions and constraints explicitly noted

package/ui-ux-design/skills/ui-ux-design/references/inclusive-ai-imagery.md

@@ -0,0 +1,57 @@
+# Inclusive AI Imagery
+
+Use this reference only when image or video generation is part of the design task.
+
+## Core Rule
+
+Identity is not a decorative adjective. Generated imagery must avoid stereotype defaults, tokenism, and incoherent cultural details.
+
+## Prompt Structure
+
+Build prompts in layers:
+
+1. subject
+2. action or pose
+3. environment and geographic/cultural context
+4. lighting and camera treatment
+5. style or medium
+6. explicit negative constraints
+
+## Inclusive Representation Constraints
+
+Specify when relevant:
+
+- distinct faces, body types, ages, and attire
+- authentic geography and architecture
+- accurate cultural clothing or symbols
+- realistic lighting for different skin tones
+- mobility aids and assistive devices with physical realism
+
+## Negative Prompt Themes
+
+Block:
+
+- clone faces
+- gibberish text or fake signage
+- exoticized or sensationalized framing
+- oversized symbolic props replacing the human subject
+- malformed hands, limbs, or devices
+- futuristic or stock-photo tropes unless intentionally requested
+
+## Review Checklist
+
+Before approving generated imagery, check:
+
+- is the subject depicted with dignity and agency
+- does the environment fit the claimed context
+- are there stereotype shortcuts
+- do multiple people look meaningfully distinct
+- is any text, signage, or symbolism coherent
+- do clothing, hair, and movement obey physical reality
+
+## Anti-Patterns
+
+- "diverse team" prompts with no specificity
+- relying on ethnicity descriptors without contextual realism
+- using image prompts as a substitute for real brand/art direction
+- importing imagery guidance into tasks that only need UI design

package/ui-ux-design/skills/ui-ux-design/references/kole-jain-uiux-concepts.md

@@ -0,0 +1,104 @@
+# Kole Jain UI/UX Concepts Notes
+
+Source context: extracted from the user-provided transcript `Every UIUX Concept Explained in Under 10 Minutes.txt`, attributed to Kole Jain.
+
+## Core Thesis
+
+Good UI/UX makes behavior legible without explanation. Interfaces should communicate relationship, importance, state, affordance, and feedback through visual structure: signifiers, hierarchy, whitespace, typography, color, depth, icons, component states, and micro-interactions.
+
+## Signifiers And Affordances
+
+- Use visible cues to show what an element is, what it can do, and what state it is in.
+- Examples: active nav highlights, selected containers, disabled opacity, button press states, hover states, focus states, and tooltips.
+- A user should often understand interaction rules before reading instructions.
+- Treat missing state feedback as a UX bug, not just a polish gap.
+
+## Hierarchy
+
+- Use size, position, color, imagery, and contrast to tell users what matters first.
+- Put the most important information near the top or in the strongest visual position.
+- Use images when they materially improve scanning or recognition.
+- Make high-value facts visually distinct: for example, price, status, active item, or primary action.
+- Use icons and visual relationships to reduce unnecessary labels when the meaning is clear.
+
+## Layout, Whitespace, And Grids
+
+- Treat column grids and spacing systems as guidelines, not hard laws.
+- Use grids most strictly for structured repeated content such as galleries, blogs, lists, and responsive card layouts.
+- For custom landing pages, prioritize breathing room and visual composition over forcing every element into a rigid grid.
+- Use whitespace to group related elements and separate unrelated elements.
+- A 4-point grid can work well because values split cleanly and keep spacing consistent.
+- Keep spacing intentional even when it is not mathematically rigid.
+
+## Typography
+
+- Most UI is text, so typography carries a large part of the design.
+- One strong sans-serif family is often enough for product UI.
+- Tighten large heading letter spacing slightly and use compact heading line height, roughly 110-120%, when it improves polish and readability.
+- Landing pages can use a broader type range, but keep the number of font sizes limited.
+- Dense dashboards and app screens usually need a tighter type range; large display sizes often become impractical.
+- Spend less time hunting fonts for product UI and more time making hierarchy, spacing, and states work.
+
+## Color
+
+- Start with one primary brand color and derive lighter backgrounds or darker text treatments from it.
+- Build toward a color ramp when the interface needs chips, states, charts, and repeated semantic uses.
+- Use semantic colors for meaning: danger, warning, success, trust, focus, urgency, or newness.
+- In dark mode, reduce harsh borders and create depth by making foreground surfaces slightly lighter than the background.
+- Dim overly bright chips or accents in dark mode and preserve hierarchy with adjusted saturation, brightness, and text contrast.
+
+## Depth And Shadows
+
+- In light mode, use shadows to separate layers, but keep them subtle.
+- Reduce shadow opacity and increase blur when shadows feel too harsh.
+- Cards generally need lighter shadows than popovers or surfaces that sit above other content.
+- Use inner and outer shadows when a tactile raised control is appropriate.
+- If the shadow is the first thing the user notices, it is too strong.
+
+## Icons And Buttons
+
+- Size icons to match the related text line height where practical.
+- Tighten icon-and-label spacing so pairs feel intentional.
+- Treat sidebar links and subtle nav actions as ghost buttons: no background by default, visible response on hover or active state.
+- For button padding, a useful default is more horizontal than vertical padding, often about double.
+- Use icons in buttons when they clarify action, status, or scanability.
+
+## States And Feedback
+
+- Every user action should produce a response.
+- Buttons need at least default, hover, active/pressed, and disabled states; loading states are needed when work is pending.
+- Inputs need focus, error, and message states; warning states can help with optional or recoverable issues.
+- Data fetching needs loading feedback. Completed actions need success feedback.
+- Swipe, scroll, copy, submit, selection, and navigation actions should make the result visible.
+
+## Micro-Interactions
+
+- Use micro-interactions as feedback that confirms an action or helps the user understand what changed.
+- Practical examples include a copied confirmation, a small chip animation, a state transition, or a completion cue.
+- Keep playful motion subordinate to clarity and task completion.
+
+## Text Over Images
+
+- Do not put text directly over images without protecting readability.
+- Use overlays, gradients, or progressive blur to preserve the image while creating a readable text zone.
+- Prefer a directional gradient when the text occupies one side or edge of the image.
+- Ensure the final composition preserves both image quality and text contrast.
+
+## Applying These Principles
+
+Use `ui-loop.md` for generic design and rendered review, and
+`components-and-states.md` for the implementation-level state matrix. This reference adds
+concrete product-UI treatments for affordances, contextual grids, dark-mode depth,
+shadows, icon/button pairing, micro-interaction feedback, and text over imagery.
+
+When these treatments are used, specify their intended affordance, dark-mode depth,
+layer/shadow relationship, icon alignment, outcome-linked feedback, or protected
+text zone so implementation does not require guesswork.
+
+## Reference-Specific Output
+
+- affordance and action-feedback rules
+- hierarchy, grouping, grid, and whitespace decisions
+- semantic color and dark-mode depth treatment
+- icon/button alignment and component-state notes
+- text-over-image protection when used

package/ui-ux-design/skills/ui-ux-design/references/kuinetic-reference.md

@@ -0,0 +1,184 @@
+# kUInetic Reference
+
+> Maintained in AI-Dev-Shop. Downstream copies are synced from here; edit it in
+> AI-Dev-Shop, not in a downstream copy.
+
+Attribute and effect lookup for kUInetic, the declarative `data-kui` animation library.
+`ui-animation.md` owns when to use it and the motion rules; this file only lists what
+exists. Not a tutorial.
+
+**Authority:** the kUInetic source, package `kuinetic` v0.2.4 (MIT, kuinetic.com),
+checked at commit `9fc5e54` on 2026-10-30. Every name below is registered in the
+source; each group's `Source:` line is a path inside the kUInetic repo. Where the docs
+and the source disagree, this file follows the source.
+
+**Version lag:** a vendored bundle (e.g. `<theme>/vendor/kuinetic/kuinetic.js`) can be
+older than the source. Before relying on a recent option (`direction:rise-mask`, the
+`from:` event source, `wide:`/`narrow:`), grep the shipped bundle for it. Use
+`kuinetic.describe('<effect>')` in the page only for effect parameters; it does not list
+reserved keys, gates or event-source syntax, which live in the parser. An unknown effect is skipped; an unsupported
+parameter or value may fall back to its default, and an invalid breakpoint gate is dropped
+so the effect runs at every width. Nothing throws, and diagnostics appear only with a
+reporter (see Dev warnings).
+
+## Detect
+
+kUInetic is present when any of these hold:
+
+- markup carries `data-kui` (authored) or `data-kui-fx` / `data-kui-state` (stamped at runtime)
+- the page loads `kuinetic.js`, `kuinetic.all.js`, `kuinetic.min.js` or `kuinetic.all.min.js`,
+  or the theme ships a `vendor/kuinetic/` folder
+- `package.json` depends on `kuinetic`, or code imports `kuinetic`, `kuinetic/css`, `kuinetic/advanced`
+- `window.__kuinetic` (the auto-started animator) exists in the running page
+
+Source: `src/browser/boot.ts`, `src/core/attrs.ts`, `package.json`.
+
+## Install And Initialise
+
+| Setup | How |
+|---|---|
+| Split bundle (preferred: CSS still works if JS fails) | `<link rel="stylesheet" href="kuinetic.css">` + `<script src="kuinetic.js"></script>`. Auto-starts at `DOMContentLoaded` with `observe: true`; the animator is `window.__kuinetic`. |
+| One tag | `kuinetic.all.js` / `kuinetic.all.min.js` (CSS embedded, same auto-start). |
+| Manual start | `data-kui-manual` on the script tag, then `kuinetic.kuinetic({ observe: true }).start()`. |
+| npm / bundler | `import { kuinetic } from 'kuinetic'`, `import 'kuinetic/css'`, `kuinetic({ observe: true }).start()`. An import never auto-starts. |
+| Dev warnings | Pass `reporter: consoleReporter()` in the options; the default reporter is silent. |
+| Pre-JS hide | `<html data-kui-cloak>` hides cloaked entrances until start; fails open (start, watchdog, CSS release). |
+
+Never start a second animator beside an auto-started bundle. Pass custom options before
+auto-start, or use `data-kui-manual` and create exactly one animator; a factory call with
+options after the page has been scanned creates a second animator. Source: `README.md`, `src/browser/boot.ts`,
+`src/css/base.css`, `src/core/reporter.ts`.
+
+## Attribute Grammar
+
+```html
+<h2 data-kui="fade-up 700ms 120ms ease-out distance:16px, blur-in 400ms at:-200ms">
+```
+
+- First token is the effect; then positional **duration → delay → easing**, or
+  `duration:` / `delay:` / `ease:`. Effect parameters are `key:value`.
+- Comma-separate effects whose channels don't collide. A collision keeps the first and warns.
+- Quote any value containing spaces or commas: `target:'.stops > li'`.
+- Named bundle: `<template data-kui-define="card-in" data-kui="fade-up 700ms, blur-in 400ms at:-200ms">`,
+  then `data-kui="card-in 300ms"`. Local values override the bundle.
+- Longhand attributes (an inline key wins): `data-kui-on`, `data-kui-timeline`,
+  `data-kui-threshold`, `data-kui-stagger`. Timing has no longhand. Set reduced motion
+  with the `rm:` key.
+- Stamped by the runtime; read, never author: `data-kui-fx`, `data-kui-state`,
+  `data-kui-unmatched`, `data-kui-part`, `data-kui-rm` (the compiled reduced-motion policy).
+
+Source: `src/core/parse.ts`, `src/core/attrs.ts`, `src/core/bundles.ts`.
+
+## Reserved Keys
+
+| Key | Values |
+|---|---|
+| `on:` | `enter` (once, default for reveals), `leave`, `load`, `manual`, `hover`/`unhover`, `focus`/`blur`, `click`, any DOM event (`invalid`, `submit`, `cart:updated`), or a forward/back pair `hover/unhover`, `enter/leave`. |
+| `data-kui-on="click from:#copy-btn"` | Listen on another element. Longhand only. |
+| `actions:` | Four scroll crossings, slash-separated: `play` `pause` `resume` `reverse` `reset` `restart` `complete` `none`. |
+| `threshold:` | Fraction visible before `enter` fires: `threshold:30%`. Default `0%`. |
+| `timeline:` | `time` (default), `view`, `scroll`, `pin`. Range: `data-kui-timeline="view entry 0% cover 60%"`. |
+| `at:` | Relative to the previous effect: `-200ms`, `+100ms`, `after`, `with`, `with+150ms`. |
+| `repeat:` / `yoyo:` | Total plays or `infinite`; `yoyo:true` alternates. |
+| `above:` / `below:` | Viewport gate on `sm` `md` `lg` `xl` `2xl`. `wide:` / `narrow:` gate the same scale against the nearest `data-kui-container` ancestor. |
+| `cascade:` / `spread:` | Group stagger step, or total budget, on the **parent** (or `data-kui-stagger="90ms"`). |
+| `order:` / `cols:` / `along:` | `start` `end` `center` `edges` `random`, a child index, or an `x/y` point; `cols:6` or `cols:auto`; `along:x`/`along:y`. |
+| `target:` / `scope:page` | Animate matching descendants (or page matches) instead of the host. |
+| `rm:` | Reduced-motion policy, mildest to strictest `shorten`, `crossfade`, `disable`; may only be stricter than the effect's own. |
+| `func:` | Global function run on `kui:finish`. Never build it from CMS or user input. |
+
+`stagger:` on the split-text effects is the gap between generated pieces, not the group
+`cascade:`. Source: `src/core/parse.ts`, `src/core/activation.ts`,
+`src/core/event-sources.ts`, `src/core/types.ts`, `src/core/repeat.ts`, `src/core/breakpoints.ts`,
+`src/core/stagger-config.ts`, `src/core/target.ts`.
+
+**Easing keywords:** `linear` `ease` `ease-in` `ease-out` `ease-in-out` `step-start`
+`step-end` `expo-in` `expo-out` `expo-in-out` `back-in` `back-out` `back-in-out`
+`quart-out` `circ-out` `spring` `bounce`; functions `cubic-bezier()` `steps()` `linear()`
+`spring(bounce:0.3)` / `spring(stiffness:400 damping:20 mass:1)` (`bounce` 0–0.85; the
+spring shapes the curve, your duration still holds). Source: `src/core/parse.ts`, `src/core/easing.ts`.
+
+**Events and API:** `kui:start`, `kui:finish`, `kui:reverse-finish`, `kui:cancel` bubble
+with `detail { effects, activation, timeline, reason }`. `kui` is `window.__kuinetic` under a
+script tag, or what `kuinetic(...).start()` returns: `kui.play(target, effect, options)`,
+`kui.activate(el)`, `kui.deactivate(el)`, `kui.control(target)` (`pause` `play` `reverse`
+`seek(0..1)` `timeScale`, `progress`, `state`), `kui.process(el)`, `kui.reset(el)`.
+JS-rendered and scroll-driven effects expose no playhead. Source: `src/core/control.ts`,
+`src/core/animator.ts`.
+
+## Effects By Family
+
+Defaults are the source defaults; override per element.
+
+| Family | Names | Source |
+|---|---|---|
+| Entrance | `fade-in` `fade-up` `fade-down` `fade-left` `fade-right` `slide-up` `slide-down` `slide-left` `slide-right` `slide-inline-start` `slide-inline-end` `slide-block-start` `slide-block-end` `zoom-in` `zoom-in-up` `zoom-in-down` `pop-in` `flip-in-x` `flip-in-y` `rotate-in` `roll-in` `swing-in` `blur-in` `fade-blur-up` `fade-blur-in` `back-in-up` `back-in-down` `bounce-in` `reveal-once` (same as `fade-up`). Base default `600ms ease-out`, `distance:24px`. Preset exceptions: `slide-*` use `distance:100px` (no fade); `back-in-up`/`back-in-down` use `120px` with `expo-out`; `pop-in` uses scale 0.6 with `back-out`; `bounce-in` starts at scale 0.3 and uses the multi-peak `bounce` curve. | `src/effects/catalog/core.ts` |
+| Exit | `fade-out` `fade-out-up` `fade-out-down` `fade-out-left` `fade-out-right` `slide-out-up` `slide-out-down` `slide-out-left` `slide-out-right` `zoom-out` `pop-out` `blur-out` | `src/effects/catalog/core.ts` |
+| Scroll-linked | `parallax-y` `parallax-x` `parallax-scale` `parallax-rotate` `depth-layer` `scroll-fade` `scroll-desaturate` `scroll-skew` `scroll-progress-bar` `scroll-progress-bar-y` `scroll-progress-ring`. Use `timeline:view`/`scroll`; duration is meaningless there. | `src/effects/catalog/core.ts` |
+| Pin and scroll mechanics | `pin-section` (`distance:100vh`, `offset-top:`, `spacer:true`) `pin-until` `pin-spacer` `stacking-cards` `horizontal-scroll` `scrollytelling-step` (`steps:`, `target:` stamps `data-kui-step-state` before/active/after and `--kui-step`) `scroll-progress` `sequence-scrub` `video-scrub` `scroll-snap-x` `scroll-snap-y` `scroll-spy` `smooth-scroll-to`. Set `--kui-pin-offset` on `:root` to clear a fixed header. | `src/effects/scroll-mechanics/presets.ts` |
+| Text split | `split-chars` (30ms) `split-words` (90ms) `split-lines` (160ms), `direction:fade\|up\|down\|mask\|rise-mask`, `unit:`, `stagger:`; presets `text-reveal-up` `text-reveal-down` (words) `text-reveal-mask` (lines, mask). `rise-mask` slides each unit up 120% inside a stationary clip. `--kui-mask-bleed: 0.1em` protects ascenders under tight leading. | `src/effects/catalog/text.ts`, `text-shared.ts` |
+| Text other | `typewriter` `typewriter-loop` `scramble` `decode` `glitch` `word-cycler` `highlight-sweep` `underline-draw` `gradient-shimmer` `gradient-sweep` `text-outline-fill` `text-wave` `text-jitter` `marquee` `marquee-scroll-linked` `redaction-reveal` `text-3d-extrude` `var-weight` `var-width` `var-slant` `var-axis` | `src/effects/catalog/text.ts` |
+| Media reveal | `wipe-up` `wipe-down` `wipe-left` `wipe-right` `wipe-circle` `wipe-diagonal` `mask-reveal` `curtain-reveal` `before-after-wipe` `ken-burns` `ken-burns-out` `blur-up` `image-parallax-frame` `slat-assemble` `duotone-hover` `grayscale-hover` `saturate-hover` `bg` `background` `video-backdrop` `video-hero` | `src/effects/catalog/media.ts` |
+| Hover and press | `lift` (220ms, `distance:6px`) `lift-shadow` `pop` (`scale:1.06`) `shine-sweep` `split-flap` `border-draw` `border-glow` `beam-border` `underline-slide` `underline-center` `icon-wiggle` `icon-spin` `icon-bounce` `tilt-3d` `tilt-parallax` `cursor-follow` `cursor-lag` `cursor-label` `cursor-spotlight` `cursor-invert` | `src/effects/catalog/interaction.ts` |
+| Press, group, reveal-on-hover | `press-depth` (120ms, `scale:0.96`) `group-dim`; `masked-label-swap` `masked-label-swap-x` `masked-label-swap-diagonal` `hover-intent` `anchored-preview` `anchored-preview-bottom` `anchored-preview-left` `anchored-preview-right` `search-expand`; `proximity-glow` `proximity-field` | `interaction-states.ts`, `interaction-reveal.ts`, `interaction-proximity.ts` (all `src/effects/catalog/`) |
+| Feedback | `skeleton-shimmer` `skeleton-to-content` `spinner` `spinner-dots` `spinner-ring` `progress-indeterminate` `toast-slide-in` `toast-slide-out` `shake-error` `wobble` `ripple` `badge-pop` `count-bump` `heart-burst` `confetti-burst` `copy-confirm` `pull-to-refresh` | `src/effects/catalog/feedback.ts` |
+| Numbers | `count-up` (1600ms, `from:` `to:` `decimals:` `format:` `currency:`) `count-down` `count-currency` `count-percent` `count-compact` `odometer-roll` `progress-ring` `progress-bar` `progress-segments` `gauge-sweep` `star-rating-fill` `sparkline-draw` `donut-sweep` | `src/effects/catalog/numbers.ts` |
+| Forms | `label-float` `input-underline-grow` `focus-ring-grow` `validate-shake` `validate-check` `strength-meter` `toggle-morph` `checkbox-draw` `radio-fill` `range-fill` `submit-to-spinner-to-check` `step-progress` `carousel` | `src/effects/forms/index.ts` |
+| SVG and icons | `draw-stroke` `draw-signature` `draw-underline` `checkmark-draw` `cross-draw` `chart-line-draw` (`length:` sets path length); toggles `hamburger-to-x` (`aria-expanded`) `play-to-pause` (`aria-pressed`) `plus-to-minus` (`aria-expanded`) | `src/effects/svg/index.ts` |
+| Layout (FLIP) | `flip-reorder` `flip-filter` `flip-sort` `flip-shuffle` `accordion-height` `expand-to-modal` `grid-to-list` `tab-indicator-slide` `masonry-reflow`. Motion only; you own `aria-expanded`, focus, keys. | `src/effects/layout/presets.ts` |
+| Open/close from `display: none` | `fade-open` `pop-open` `scale-open` `drop-open` `slide-open-up` `slide-open-down` (`@starting-style`). Each stays hidden until opened: native `<dialog>` and popovers open through their own APIs (`[open]`, `:popover-open`); for an ordinary element, toggle the presence of `data-open` | `src/effects/catalog/discrete.ts` |
+| Page and view | `page-morph` `view-swap` (View Transitions); `page-fade` `page-slide` `curtain-wipe` `loading-bar` | `src/effects/catalog/view-transitions.ts`; `src/effects/three-d/index.ts` |
+| Navigation | `header-shrink` `header-hide-on-scroll` `menu-stagger-open` `menu-fullscreen` `dropdown-open` `drawer-slide` `mega-menu-drop` `back-to-top-fade` | `src/effects/navigation/index.ts` |
+| CSS 3D (core entry) | `card-flip-x` `card-flip-y` `cube-rotate` `fold-panel` `flip-card` `book-page-turn`; ring/stack carousels `carousel-3d` `carousel-stack` | `src/effects/three-d/index.ts`, `src/effects/carousel/` |
+| Ambient loops | `glow-pulse` `aurora` `gradient-mesh` `gradient-border` `gradient-rotate-border` `float` `bob` `orbit` `floating-shapes` `starfield` `dot-grid-drift` `line-grid-drift` `scanline` `spotlight-follow` `wave-blob`; `beam-border-auto` (runs unconditionally and loops forever) | `src/effects/catalog/ambient.ts`; `beam-border-auto` in `src/effects/catalog/interaction.ts` |
+| Gestures | `drag` `drag-x` `drag-y` `drag-inertia` `throwable` `elastic-pull` `rubber-band` `snap-back` `swipe` `swipe-x` `swipe-y` `long-press` `magnetic` `magnetic-snap` | `src/effects/gestures/index.ts` |
+| Generic tween | `tween` (to values) `tween-from` (from values): `tween x:100 opacity:0 rotate:45deg 800ms` | `src/effects/tween/index.ts` |
+| Showcase widgets | `lightbox` `video-lightbox` `compare` `carousel-fade` `carousel-slide` `video-hero-slideshow` `scroll-story` `hotspots` `device-frame` `slow-mo` | `src/showcase/` |
+| Paths, material | `motion-path` `path-arc` `path-loop` `path-swoop` `path-wave`; `glass`; `rotate-static` | `src/effects/motion-path/index.ts`, `src/effects/catalog/materials.ts`, `src/effects/catalog/transforms.ts` |
+
+Catalog note (`docs/catalog.md` §I): every hover effect ships a `:focus-visible`
+equivalent and a coarse-pointer fallback.
+
+## Reduced Motion
+
+Each effect declares a policy; the runtime stamps it as `data-kui-rm`, and
+`src/css/base.css` applies it under `prefers-reduced-motion: reduce`:
+
+- `shorten`: CSS animations run at 1ms with no delay. Entrances, hover, feedback, counters.
+  JS counters instead finish in one timer tick (~16ms) after any authored delay.
+- `crossfade`: replaced by a 200ms fade. No effect defaults to it; opt in with `rm:crossfade`.
+- `disable`: no animation; the element is forced to its end state (`opacity: 1`, no
+  translate/scale/rotate/filter/offset-path). Split text, typewriter, scramble, pins,
+  parallax, scroll progress, ambient loops, spinners, cursor and tilt effects, gestures, FLIP layout,
+  `toggle-morph`.
+- CSS transitions on every marked element shorten to 1ms under every policy.
+- A skipped effect still emits `kui:finish` with `reason: 'reduced-motion'` (no `kui:start`),
+  so chained work still runs.
+- The animator option `reducedMotion: 'ignore'` exists for demos and tests only.
+
+Source: `src/core/types.ts` (`ReducedMotionPolicy`), `src/core/animator.ts`,
+`src/core/host-facts.ts`, `src/css/base.css`; per-effect policy is each primitive's
+`reducedMotion` field.
+
+## Opt-In Tiers
+
+| Tier | Load | Names |
+|---|---|---|
+| Advanced (experimental, WebGL2 / Canvas / Web Audio, API may change without a major) | `<script src="kuinetic.advanced.js">` beside core, either order; or `registerAdvanced(k)` from `kuinetic/advanced` (or `registerShaders`, `registerScenes`, `registerCamera`, `registerParticles`, `registerFluidCursor`, `registerAudio`). No CSS file. | `shaders` `shader-displace` `shader-fluid` `fluid-pointer` `shader-liquid` `liquid-distort` `shader-particles` `particle-field` `shader-morph` `image-morph` `shader-gradient` `gradient-liquid` `gradient-bands` `gradient-holo` `shader-logo` `logo-gradient`; `scene` `scene-step`; `camera-scene` `camera-layer`; `particle-dissolve`; `fluid-trail` `cursor-fluid` `fluid-cursor`; `audio-source` `audio-reactive` `audio-mic` |
+| 3D model | Not published: `src/3d/` is absent from the package `exports` and its renderer is not built. Do not use. | `model-3d` |
+| Notes | Optional `kuinetic.notes.js`, only to add plain-words notes to `describe()` output. | none |
+
+Every advanced primitive declares `reducedMotion: 'disable'`. Generative shaders bake one
+still frame, `scene` holds its final frame, and `camera-scene` renders a stationary
+composition. Source: `src/advanced/index.ts` and its modules,
+`docs/advanced-modules.md`, `src/3d/index.ts`.
+
+## Gotchas
+
+- A hidden element (`display: none`, a closed `<dialog>` or popover) cannot trigger a visible entrance while closed, and `on:enter` may fire only once it opens. For opening transitions, especially repeated ones, prefer the open/close family.
+- Split, typewriter and scramble skip a host that contains a link or control; put them on a leaf.
+- Author counters with the final value as text (`<b data-kui="count-up to:237">237</b>`).
+- `repeat:infinite` is dropped on `view`/`scroll`/`pin` timelines. A `view` timeline stalls while pinned; use `timeline:pin`.
+- `submit-to-spinner-to-check` runs on fixed timers (`load:1200ms`, `hold:1500ms`) with no error stage; it is a demo, not request state.
+- `copy-confirm` fades 0 → 1 → 0 over 1400ms and ends hidden; put it on the status label, not the button. Under reduced motion it inherits `shorten`, runs in about 1ms and ends at opacity 0, so the app must keep its own visible "Copied" status for the hold period.
+- `above:`/`below:` accept only the five named breakpoints. `above:900px` is invalid, and the gate is dropped, so the effect runs at every width.

package/ui-ux-design/skills/ui-ux-design/references/openai-frontend-skill.md

@@ -0,0 +1,139 @@
+# OpenAI Frontend Skill Reference
+
+Use this reference for visually led landing pages, branded demos, polished prototypes, and other frontend work where composition and art direction matter more than component count.
+
+This reference supplies an optional composition language. `ui-loop.md` owns generic
+review, `visual-storytelling.md` owns narrative sequencing, and
+`delight-and-motion.md` owns contextual motion decisions.
+
+Source note: adapted into local reference form from OpenAI's curated frontend skill on 2026-03-21 so this repo does not need to fetch it from the web during use.
+
+## Activation Guardrail
+
+- Hard guard: if you activate this reference, explicitly tell the user in your next reply that you are using `openai-frontend-skill.md`.
+- Say why it was activated in plain language, such as landing-page composition, branded demo direction, or anti-generic UI guidance.
+- Do this before presenting design direction, layout proposals, or stylistic recommendations derived from this reference.
+- If the user does not want this direction, stop using this reference and fall back to the base UX skill plus the other applicable local references.
+
+## Working Model
+
+Before designing, define:
+
+1. visual thesis: the mood, material, and energy
+2. dominant visual plane: what carries the composition before component details
+3. interaction character: how static, tactile, cinematic, or editorial it should feel
+
+## Composition Defaults
+
+- Start with composition before components.
+- Prefer one strong visual anchor in the first viewport.
+- Treat the first screen like a poster, not a document.
+- Make the brand or product name the loudest text on branded pages.
+- Use spacing, scale, alignment, contrast, and cropping before adding extra UI chrome.
+- Default to cardless layouts unless the card itself is the interaction.
+
+## Landing Page Sequence
+
+Default structure:
+
+1. hero: product or brand, promise, CTA, dominant visual
+2. support: one concrete feature, offer, or proof point
+3. detail: workflow, atmosphere, depth, or story
+4. final CTA: start, contact, convert, or visit
+
+## Hero Rules
+
+- One composition only.
+- Use a full-bleed image or another dominant visual plane when the brief supports it.
+- Keep the text column narrow and placed over a calm visual area.
+- Keep headlines readable in one glance and protect contrast and tap targets when
+  text sits over imagery.
+- Count sticky or fixed headers against the first-viewport budget. Do not stack
+  persistent chrome above a `100vh` or `100svh` hero without accounting for it.
+
+## Product UI Rules
+
+For app surfaces, use restraint:
+
+- calm hierarchy
+- strong typography
+- dense but readable information
+- minimal chrome
+- cards only when the card is the interaction
+
+Organize product UI around:
+
+- primary workspace
+- navigation
+- secondary context or inspector
+- one clear accent for action or state
+
+## Imagery Rules
+
+- Imagery must do narrative work, not just fill space.
+- Prefer strong, real-looking photography for brands, editorial, venue, or lifestyle surfaces.
+- Choose crops with a stable tonal area for text.
+- Avoid embedded signage, logos, or typography fighting the UI.
+- If several moments are needed, use several images instead of a collage.
+
+## Copy Rules
+
+- Write in product language, not design commentary.
+- Let the headline carry meaning, keep supporting copy short, and cut repetition
+  between sections.
+- Give each section one responsibility: explain, prove, deepen, or convert.
+
+For dashboards or operational UI:
+
+- prefer utility copy over marketing copy
+- lead with status, action, scope, or decision value
+- avoid homepage-style hero language unless explicitly requested
+
+## Motion Recipe
+
+For visually led work, explore a small set of intentional motions:
+
+- one entrance sequence in the hero
+- one scroll, sticky, or depth effect
+- one hover, reveal, or layout transition
+
+Keep the selected motions noticeable enough to support the intended atmosphere,
+fast and smooth on mobile, and consistent across the page. Remove any that are
+merely ornamental. This is an art-direction recipe, not a required motion count;
+`ui-loop.md` owns the final restraint and reduced-motion review.
+
+## Composition Anti-Patterns
+
+- no cards by default
+- no hero cards by default
+- no boxed center-column hero when the brief wants full bleed
+- no more than one dominant idea per section
+- no filler copy
+- no busy imagery behind text
+- no split-screen hero unless one side stays visually calm
+- no more than two typefaces without a reason
+- no more than one accent color unless the product already has a system
+
+## Failure Examples
+
+Reject or revise when you see:
+
+- generic SaaS card grid as the first impression
+- strong image but weak brand presence
+- strong headline but no clear action
+- repeated mood-setting sections with no informational progression
+- carousel with no narrative purpose
+- app UI built from stacked cards instead of layout
+
+## Source Litmus Questions
+
+- Is the brand or product unmistakable in the first screen?
+- Is there one strong visual anchor?
+- Can the page be understood by scanning headlines?
+- Does each section have one job?
+- Are cards actually necessary?
+- Does motion improve hierarchy or atmosphere?
+- Would the design still feel strong if shadows and decorative polish were removed?
+
+Do not turn these defaults into fixed numeric caps or a second acceptance checklist.
+Use the UI Loop to judge whether the selected composition succeeds in context.