@jini-ai/agent-plugins 0.6.16 → 0.6.19

package/ui-ux-design/skills/ui-ux-design/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: ui-ux-design
+version: 1.7.0
+last_updated: 2026-10-30
+description: Use when creating frontend design systems, visual direction, component/state specs, responsive behavior, brand-aware UI guidance, premium/high-converting website polish, browser-backed UI iteration, or implementation-ready design handoff from a feature spec or existing product constraints.
+---
+
+# Skill: UI/UX Design
+
+
+## Tool use and context
+
+Load this skill and the references needed for the task through the current host's
+guidance reader. Discover available editing, media and screenshot tools before using
+them. Follow the host's tool permissions. CLI examples apply only to an authorized
+coding checkout. If a capability is missing, explain the limitation instead of
+inventing a tool. Use supplied specs and design notes as context; this skill does not
+require a particular repository or framework. Return the design in the conversation
+unless the user requests a saved artifact through an available tool.
+
+## Execution
+
+- Read any supplied feature spec, current product UI constraints and architecture decisions before making visual decisions; state assumptions where context is missing.
+- Preserve an existing design system unless the user explicitly requests a new direction.
+- For every page or screen creation, redesign, audit, or visual-polish task, read
+  `references/ui-loop.md` before making design decisions. It is the canonical home
+  for the design-intent gate, complete review checklist, browser Change → Observe
+  loop, evidence boundary, reconciliation, and handoff rules.
+- Run its **Design Intent** mode for every page or screen. Add **Rendered Iteration**
+  mode only when `browser-live-analysis` verifies `browser_automation = enabled`.
+- For web pages, Design Intent includes a concrete mobile composition plan before
+  implementation: first-view message and action, content order, stacking/reflow,
+  typography and spacing changes, imagery/crops, and interaction risks. Do not defer
+  mobile thinking until browser QA.
+- For an implemented website or web app that can be affected by responsive layout,
+  mobile navigation, forms, overlays, or sticky/fixed elements, first run the
+  browser preflight. Load and run `references/chrome-mobile-test-matrix.md` only
+  when `browser_automation = enabled`. Use Chrome/Chromium when the provider exposes
+  it; otherwise record `CHROME_NOT_VERIFIED` and provide the unresolved manual checks.
+- Define foundations before screens: tokens, typography, spacing, breakpoints, layout rules, interaction baselines.
+- Define component behavior before polish: default, hover, focus, active, loading, empty, error, success, disabled.
+- After the required `references/ui-loop.md`, load only the domain references needed
+  for the current task. **Any request for visual quality loads
+  `references/premium-ui.md` up front**, then follows its surface routing: load all
+  three design-school notes for broad, open-ended, hybrid marketing/product, or
+  high-stakes premium work; use its smaller marketing or product-UI subset only for
+  a clearly narrow task. `ui-loop.md` remains the only generic page/screen review
+  checklist.
+  - `references/ui-loop.md` for the required page/screen design gate, canonical
+    checklist, browser iteration loop, and verification boundary
+  - `references/chrome-mobile-test-matrix.md` for the conditional browser-observed
+    phone viewport matrix and mobile interaction bug sweep
+  - `references/premium-ui.md` for routing among premium psychology, concrete visual-system heuristics, and product-UI affordance methods
+  - `references/foundations.md` for the token, layout, responsive, and visual-system decision contract
+  - `references/components-and-states.md` for the reusable component inventory, state matrix, and interaction specification
+  - `references/brand-and-voice.md` for brand inputs, tone rules, messaging architecture, and visual-identity translation
+  - `references/research-and-validation.md` for assumption labeling, personas, journeys, and usability-test planning
+  - `references/visual-storytelling.md` for narrative frames, visual proof, and data-storytelling methods
+  - `references/openai-frontend-skill.md` for composition-first art direction and distinctive landing-page or branded-demo methods
+  - `references/delight-and-motion.md` for contextual microcopy, micro-interactions, personality, and delight intensity
+  - `references/ui-animation.md` when animating anything (scroll reveals, text reveals,
+    transitions, pinned sections, micro-interactions): kUInetic-first library choice,
+    implementation defaults, and micro-interaction recipes
+  - `references/kuinetic-reference.md` with `ui-animation.md` when the page has kUInetic
+    (`data-kui`, `vendor/kuinetic/`, the `kuinetic` package): attributes, effect names, tiers
+  - `references/inclusive-ai-imagery.md` for generated-imagery prompting and representation review
+- Treat accessibility, responsive behavior, and implementation clarity as default requirements.
+- Produce design output that Programmer, QA/E2E, and Code Inspection can execute without guessing.
+
+## UI Loop Contract
+
+- `references/ui-loop.md` owns all page/screen self-review questions and iteration
+  mechanics. Do not recreate a short checklist here or copy its rendered checks into
+  another skill or agent persona.
+- Before finalizing design direction, complete the reference's eight-category Design
+  Intent pass. When Rendered Iteration is available, complete its browser-observed
+  checks and reconciliation pass before claiming visual completion.
+- When a surface cannot be rendered, label it design-reviewed but not
+  rendered-verified and provide the unresolved manual viewport/state checks.
+- When the Chrome mobile matrix is triggered, complete it after the general rendered
+  checks and before claiming responsive or mobile verification.
+- The Design Intent mobile plan is always required for a web page even when the
+  Chrome matrix cannot run. The matrix validates the rendered result; it is not the
+  first point at which mobile composition is considered.
+- Keep checklist details internal unless the user requests an audit or a failed item,
+  assumption, or tradeoff materially affects the result.
+
+## Guardrails
+
+- Implementation authority belongs to the consuming persona and the user's request.
+  The Web Design Agent authorizes presentation-layer implementation by default;
+  spec-only, audit-only, and other consumers do not gain implementation authority
+  merely by loading this skill.
+- Do not invent a brand system when the product already has one; extend or document the existing one.
+- Do not prescribe motion, whimsy, or theme toggles by default when they conflict with product context.
+- Do not rely on color alone for meaning, placeholder-only labels, or non-semantic interaction patterns.
+- Do not use AI-image guidance unless image or video generation is actually in scope.
+- Do not present user research fiction as real evidence; label proposed research and validation plans as plans.
+- Do not claim a Chrome mobile pass without recording the actual browser engine,
+  tested routes and viewports, interactive paths, and remaining device-only checks.
+- If `references/openai-frontend-skill.md` is activated, explicitly tell the user before using its direction so they can redirect if they do not want that visual approach.
+
+## Output
+
+Match the output to the operating context:
+
+- **Existing surface, fix mode:** implement authorized presentation-layer changes
+  and report what changed, why, the UI Loop mode used, what was actually observed,
+  and unresolved tradeoffs. Do not force a standalone design artifact unless the
+  user or pipeline asks for one.
+- **Pre-implementation or pipeline direction:** write a concise design artifact at
+  the path defined by the consuming persona or active pipeline. The Web Design Agent
+  uses `<ADS_MEMORY_ROOT>/reports/pipeline/<NNN>-<feature-name>/web-design-spec.md`.
+- **Audit-only:** provide prioritized findings and evidence without editing files.
+
+When a design artifact is required, include:
+
+- visual direction summary
+- design foundations: tokens, typography, spacing, layout, breakpoints
+- component inventory and state matrix
+- interaction, motion, and microcopy rules
+- UI Loop mode used, unresolved checklist items, and rendered-evidence status
+- Chrome mobile matrix results when that conditional reference was activated
+- accessibility and inclusive-design requirements
+- brand/voice constraints when relevant
+- implementation notes for Programmer
+- verification notes for QA/E2E and Code Inspection
+
+## Reference
+
+### Preconditions
+
+- Inputs expected: active feature spec, existing UI/design constraints, ADR constraints if available, target platform context.
+- For an existing-UI audit, pair this skill with `frontend-accessibility`. Load
+  `vercel-web-design-guidelines` only when the user explicitly requests Vercel's
+  Web Interface Guidelines or a fresh external-rule compliance audit. Treat its
+  `file:line` findings as supplemental evidence mapped into UI Loop categories;
+  `ui-loop.md` remains the completion authority.
+
+### Decision Rule
+
+- Any page or screen creation, redesign, audit, or visual polish -> load
+  `references/ui-loop.md` and complete Design Intent mode; add Rendered Iteration
+  only with verified browser automation
+- Implemented website/web-app work that can affect responsive layout, mobile
+  navigation, forms, overlays, or sticky/fixed elements -> after browser preflight
+  verifies automation, load and run `chrome-mobile-test-matrix.md`; otherwise record
+  `CHROME_NOT_VERIFIED` and manual checks
+- Any signal that visual quality matters — premium, high-end, expensive, luxury,
+  agency-grade, high-converting, "make it look good", a redesign, or a
+  first-impression/marketing surface -> load `premium-ui.md` first, then its full or
+  narrow note set according to that router
+- Need layout, theming, or token structure -> load `foundations.md`
+- Need reusable components or interaction states -> load `components-and-states.md`
+- Need brand system or tone definition -> load `brand-and-voice.md`
+- Need validation plan or persona/journey structure -> load `research-and-validation.md`
+- Need narrative landing page, infographic, or campaign framing -> load `visual-storytelling.md`
+- Need visually strong landing-page composition, branded demo direction, or anti-generic UI guidance -> load `openai-frontend-skill.md`
+- Need delight, motion, or playful interaction guidance -> load `delight-and-motion.md`
+- Implementing any animation, scroll or text reveal, transition, or micro-interaction ->
+  load `ui-animation.md`; add `kuinetic-reference.md` when kUInetic is detected
+- Need AI-generated imagery or inclusive representation constraints -> load `inclusive-ai-imagery.md`
+- User explicitly requests Vercel Web Interface Guidelines or a fresh external-rule
+  compliance audit -> load `vercel-web-design-guidelines` as supplemental evidence,
+  never as a second completion checklist
+
+### Failure Path
+
+- If brand direction conflicts with accessibility or compliance, keep the baseline and escalate the conflict.
+- If the spec lacks enough product context for irreversible design decisions, produce a constrained design spec with explicit assumptions and open questions.
+- If requested style would materially harm usability, note the tradeoff and require human approval before locking it in.

package/ui-ux-design/skills/ui-ux-design/references/brand-and-voice.md

@@ -0,0 +1,78 @@
+# Brand and Voice
+
+Use this reference when the design work includes identity direction, messaging behavior, or visual tone.
+
+This file owns brand inputs and translation rules. `ui-loop.md` owns the resulting
+page/screen quality review.
+
+## When to Use
+
+- greenfield product with no established brand system
+- redesign where the user wants a visual reset
+- public-facing marketing or landing surfaces
+- copy or tone decisions that materially affect UX
+
+## Brand Foundation Inputs
+
+If enough context exists, define:
+
+- purpose
+- vision
+- mission
+- values
+- personality traits
+- audience
+- competitive differentiation
+
+Keep this lightweight unless the user explicitly requests full brand strategy work.
+
+## Voice Rules
+
+Define:
+
+- tone adjectives
+- preferred reading level
+- helpfulness vs confidence balance
+- what copy should avoid
+- how errors, empty states, and success messages should sound
+
+Prefer clear, human, concise language over generic corporate filler.
+
+## Visual Identity Translation
+
+Translate brand direction into:
+
+- palette behavior
+- typography mood
+- imagery treatment
+- icon/illustration style
+- density and whitespace
+- motion character
+
+## Messaging Architecture
+
+For public-facing surfaces, define:
+
+- headline style
+- subhead style
+- value proposition structure
+- CTA tone
+- proof/trust elements
+
+## Anti-Patterns
+
+- inventing deep brand strategy when only feature-level UI is needed
+- robotic generic copy
+- brand tone that conflicts with task clarity
+- visual identity choices that reduce readability or accessibility
+
+## Reference-Specific Output
+
+Record the applicable brand decisions in the authorized design artifact or living
+visual `design.md`:
+
+- brand assumptions stated
+- tone/voice rules stated
+- copy style examples provided when relevant
+- visual identity translation documented
+- conflicts with existing brand noted explicitly

package/ui-ux-design/skills/ui-ux-design/references/chrome-mobile-test-matrix.md

@@ -0,0 +1,137 @@
+# Chrome Mobile Test Matrix
+
+Use this reference only for an existing or implemented web surface when responsive
+behavior can be observed in a verified browser session. It expands the general
+mobile checks in `ui-loop.md` into a repeatable Chrome/Chromium bug sweep; it is not
+standing context for design specs, native apps, or non-rendered work.
+
+This is a whole-page mobile check, not only a navigation/forms checklist. Run **Page
+And Layout** for every applicable route to verify the first-view message, hierarchy,
+content flow, typography, imagery, density, and overflow. Run the navigation, forms,
+overlays, and sticky/fixed sections when those patterns exist.
+
+## Preconditions And Browser Identity
+
+1. Run the `browser-live-analysis` preflight and continue only when
+   `browser_automation = enabled`.
+2. Start the project with its normal local command and open the target route through
+   the configured browser provider.
+3. Select Chrome or Chromium when the provider exposes a browser-engine choice.
+   Record the engine actually used. If Chrome/Chromium cannot be selected, run the
+   available browser pass when useful but label the result `CHROME_NOT_VERIFIED`.
+4. Keep console and failed-network-request evidence available throughout the pass.
+
+Chrome responsive emulation does not prove physical-device behavior, mobile Safari,
+safe-area handling on notched hardware, soft-keyboard effects, or real touch and
+performance characteristics. Call out any of those that still require a device pass.
+
+## Required Viewport Matrix
+
+Use project-defined supported devices when they exist. Otherwise test this default
+portrait matrix:
+
+| Profile | Viewport | Purpose |
+|---|---:|---|
+| Narrow phone | `320 × 568` | Exposes minimum-width overflow, wrapping, and cramped controls |
+| Common Android | `360 × 800` | Exercises a common narrow Android layout |
+| Common modern phone | `390 × 844` | Primary contemporary phone composition |
+| Large phone | `430 × 932` | Exposes over-wide content, spacing, and stretched mobile layouts |
+
+Also test:
+
+- one landscape viewport, default `844 × 390`, when the surface contains navigation,
+  forms, media, drawers, modals, or sticky/fixed controls
+- `breakpoint - 1`, `breakpoint`, and `breakpoint + 1` around every breakpoint changed
+  by the task
+- one normal desktop viewport after the mobile fixes as a regression control
+
+For each applicable route and viewport, hard-reload, wait for the stable rendered
+state, capture the first viewport and full-page state when useful, then interact with
+the controls rather than judging from a screenshot alone.
+
+## Checklist
+
+Record each item as `PASS`, `N/A`, or a defect with route, viewport, state, evidence,
+and intended correction.
+
+### Page And Layout
+
+- [ ] No unexpected horizontal scrolling, clipped content, off-canvas text, or
+      element wider than the viewport.
+- [ ] The first viewport still explains the page or current task and keeps the
+      primary action discoverable without crowding.
+- [ ] Headings, body copy, labels, badges, prices, and buttons wrap without collision,
+      truncation, or isolated words that materially weaken the composition.
+- [ ] Grids, cards, tables, code blocks, carousels, and media choose an intentional
+      stack, scroll, crop, or alternate mobile treatment.
+- [ ] Images remain sharp, correctly cropped, and proportionate; no important subject
+      or product detail disappears at the mobile crop.
+- [ ] Section spacing and content density remain coherent at all four widths rather
+      than merely fitting inside them.
+
+### Navigation
+
+- [ ] The mobile navigation trigger is visible, labeled, reachable, and large enough
+      to operate without hitting adjacent controls.
+- [ ] The menu opens and closes through every supported path: trigger, close control,
+      backdrop, Escape, route selection, and browser navigation where applicable.
+- [ ] Opening the menu applies the intended background scroll lock; closing it
+      restores scroll position and focus without leaving stale overlays.
+- [ ] Long navigation labels, account controls, locale selectors, and nested items fit
+      or scroll without hiding the exit path.
+
+### Forms
+
+- [ ] Labels, help text, required indicators, values, and validation messages remain
+      visible and associated with the correct controls.
+- [ ] Inputs use appropriate types and do not create unintended zoom, clipping, or
+      horizontal movement when focused.
+- [ ] Focused controls and the primary submit action remain reachable when the viewport
+      height is reduced. Treat soft-keyboard behavior as requiring a real-device pass
+      when browser emulation cannot reproduce it.
+- [ ] Error, disabled, loading, success, and resubmission states do not change the
+      layout in a way that hides the error or action.
+
+### Modals, Drawers, Menus, And Overlays
+
+- [ ] Dialogs, drawers, sheets, popovers, and menus fit within the current viewport
+      and keep their title, content, and close or confirm actions reachable.
+- [ ] Long overlay content scrolls in the intended container without trapping the page
+      at an unreachable position.
+- [ ] Background scroll lock, focus containment, focus return, backdrop behavior, and
+      layering remain correct at each relevant width.
+- [ ] Tooltips or hover-only disclosures have a touch-accessible alternative.
+
+### Sticky And Fixed Elements
+
+- [ ] Sticky headers, bottom navigation, cookie banners, chat widgets, and floating
+      actions do not cover content, validation messages, or each other.
+- [ ] `100vh`/`100svh`/`100dvh` sections account for persistent headers and controls
+      and do not strand content below an unreachable fold.
+- [ ] Sticky behavior starts and ends at the intended boundaries without jitter,
+      overlap, or unexpected stacking-context failures.
+- [ ] Safe-area-dependent placement is either verified on suitable hardware or
+      explicitly left for a device pass.
+
+### Interaction, States, And Stability
+
+- [ ] Critical actions work through touch-style clicks and do not depend on hover.
+- [ ] Loading, empty, error, success, long-content, and realistic-data states preserve
+      the mobile layout and keep recovery actions visible.
+- [ ] Resizing across breakpoints and rotating to the landscape check does not leave
+      stale menu, modal, scroll-lock, or layout state behind.
+- [ ] Reduced-motion mode preserves meaning and removes motion that becomes distracting
+      or expensive on the mobile viewport.
+- [ ] No new console errors, failed requests, obvious layout shifts, janky scrolling,
+      or slow blocking media appear during the tested path.
+
+## Completion Evidence
+
+Before claiming mobile verification:
+
+1. Re-run every viewport and state affected by a fix.
+2. Re-run the desktop control viewport.
+3. Record the routes, viewport profiles, browser engine, interactive paths, defects
+   fixed, remaining `N/A` or device-only items, and representative screenshots.
+4. Treat any unresolved issue that blocks navigation, reading, form completion, or a
+   primary action as a failed mobile pass rather than a cosmetic advisory.

package/ui-ux-design/skills/ui-ux-design/references/components-and-states.md

@@ -0,0 +1,112 @@
+# Components and States
+
+Use this reference when defining the reusable UI pieces and behavior needed for implementation.
+
+This file owns component and state specification. The UI Loop judges the assembled
+surface, while the Chrome mobile matrix verifies rendered mobile interaction.
+
+## Component-First Rule
+
+Do not spec isolated screens only. Identify the reusable components first, then define where they are used.
+
+## Minimum Component Inventory
+
+Consider whether the feature needs:
+
+- buttons and links
+- text inputs, selects, checkboxes, radios, switches
+- search/filter controls
+- cards, lists, tables
+- tabs, accordions, drawers, modals
+- toasts, alerts, banners
+- skeletons, spinners, progress indicators
+- empty-state blocks
+- navigation elements
+
+## State Matrix
+
+Every key interactive component should define:
+
+- default
+- hover
+- focus-visible
+- active/pressed
+- disabled
+- loading
+- error
+- success
+
+Feature-level surfaces should also define:
+
+- empty
+- partial data
+- failure/retry
+- permission denied
+- offline or degraded mode when relevant
+
+## Interaction Rules
+
+Document:
+
+- trigger action
+- feedback timing
+- validation timing
+- keyboard behavior
+- focus movement
+- escape and dismissal rules
+- optimistic vs confirmed feedback
+
+## Forms
+
+Specify:
+
+- visible labels
+- helper text
+- required/optional treatment
+- inline validation behavior
+- error copy style
+- submit loading state
+- success confirmation behavior
+
+Do not rely on placeholder text as the label.
+
+## Tables and Dense Data
+
+Define:
+
+- row density
+- sorting/filter controls
+- responsive fallback
+- sticky columns/headers if needed
+- loading and empty-state behavior
+- selected-row or bulk-action behavior
+
+## Navigation
+
+Specify:
+
+- information hierarchy
+- current-page indicator
+- hover/focus treatment
+- mobile adaptation
+- overflow behavior
+
+## Anti-Patterns
+
+- components with only happy-path states
+- focus styles omitted because they "look ugly"
+- error feedback shown only through color
+- modal/dialog flows without focus return
+- hover-only affordances on mobile-relevant UI
+- components invented without checking existing system primitives
+
+## Reference-Specific Output
+
+Record the applicable component decisions in the authorized design artifact:
+
+- component inventory listed
+- state matrix covered
+- interaction rules documented
+- form behavior defined where needed
+- navigation behavior defined where needed
+- implementation notes point to reusable primitives, not one-off styling

package/ui-ux-design/skills/ui-ux-design/references/delight-and-motion.md

@@ -0,0 +1,54 @@
+# Delight and Motion
+
+Use this reference when the product should feel lively, memorable, or distinctive without sacrificing usability.
+
+This file selects where delight and personality belong. `ui-loop.md` owns the final
+motion/restraint review and accessibility baseline.
+How to animate (timing, easing, kUInetic, micro-interaction recipes) lives in
+`ui-animation.md`.
+
+## Default Rule
+
+Delight is optional. Clarity, speed, and accessibility are not.
+
+## Appropriate Uses
+
+- celebratory success states
+- onboarding encouragement
+- empty states that benefit from warmth
+- lightweight hover/focus feedback
+- brand personality in low-risk surfaces
+
+## Microcopy Rules
+
+Use personality carefully in:
+
+- loading text
+- empty states
+- success confirmations
+- low-severity errors
+
+Keep copy:
+
+- short
+- helpful
+- brand-consistent
+- non-patronizing
+
+Avoid jokey or cute copy in high-stress flows such as payments, security, legal consent, or destructive actions.
+
+## Delight Spectrum
+
+- subtle: hover, focus, small success feedback
+- moderate: celebratory completion feedback, richer empty states, guided encouragement
+- strong: campaign-specific personality, easter eggs, playful brand moments
+
+Default to subtle unless the product context supports more.
+
+## Anti-Patterns
+
+- confetti for routine actions
+- whimsical error text during serious failure states
+- animations that slow repeated workflows
+- easter eggs on business-critical surfaces
+- personality that breaks brand trust