love-ui 1.2.14 → 1.2.17

package/skills/loveui-skills/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: loveui-skills
+description: Build beautiful, professional software interfaces and websites with LoveUI. Use when users ask to create, redesign, or polish web apps, pages, dashboards, landing pages, SaaS UI, or multi-page product experiences with high visual quality, responsive behavior, and production-ready code.
+---
+
+# LoveUI Skills
+
+Follow this skill to design and implement polished, production-ready UI in LoveUI projects.
+
+## Reference System (Read in Every UI Task)
+
+- Read `references/visual-primitives.md` to set non-negotiable visual constraints.
+- Read `references/interaction-heuristics.md` to define interaction behavior and state handling.
+- Read `references/structural-cleanliness.md` to enforce semantic, reusable, responsive architecture.
+- Use `references/quality-gates.md` as the final ship checklist.
+
+## Extended References (Read Based on Scope)
+
+- Read `references/accessibility-baseline.md` for accessibility requirements (contrast, keyboard, ARIA, touch targets).
+- Read `references/content-ux-writing.md` for microcopy, error language, and destructive action wording.
+- Read `references/forms-and-validation.md` for form architecture, validation timing, and async validation behavior.
+- Read `references/motion-and-feedback.md` for motion timing, feedback primitives, skeleton/spinner decisions.
+- Read `references/navigation-and-information-architecture.md` for navigation hierarchy, wayfinding, and URL state.
+- Read `references/screenshot-translation-protocol.md` when implementing from screenshots, mockups, or visual references.
+- Read `references/component-api-and-naming.md` for prop/API quality, composition patterns, and naming.
+- Read `references/frontend-architecture.md` for state boundaries, data flow, side-effect placement, and feature structure.
+- Read `references/testing-and-quality-strategy.md` for test scope, visual regression, and release quality gates.
+
+## Skill Pack Discovery (Required)
+
+This repository is a multi-skill pack. In addition to this root skill, the agent must treat every `skills/*/SKILL.md` file as an available specialized skill when this pack is installed.
+
+Before implementation work, scan the `skills/` directory and select the best matching specialist skill(s) for the request.
+
+### Available Specialist Skills
+
+- `skills/adapt/SKILL.md`
+- `skills/animate/SKILL.md`
+- `skills/audit/SKILL.md`
+- `skills/bolder/SKILL.md`
+- `skills/clarify/SKILL.md`
+- `skills/colorize/SKILL.md`
+- `skills/critique/SKILL.md`
+- `skills/delight/SKILL.md`
+- `skills/distill/SKILL.md`
+- `skills/extract/SKILL.md`
+- `skills/frontend-design/SKILL.md`
+- `skills/harden/SKILL.md`
+- `skills/normalize/SKILL.md`
+- `skills/onboard/SKILL.md`
+- `skills/optimize/SKILL.md`
+- `skills/polish/SKILL.md`
+- `skills/quieter/SKILL.md`
+- `skills/teach-loveui/SKILL.md`
+
+### Routing Rule
+
+- Prefer the most specific specialist skill over generic guidance when one clearly matches the task.
+- If multiple specialist skills apply, use one primary skill and at most one supporting skill to avoid conflicting directives.
+- If no specialist skill applies, continue with this root skill and the `references/*` system.
+
+## Required Tooling
+
+- Use the `loveui` MCP server as the authoritative source for LoveUI registry knowledge.
+- Use MCP `resources/list` to discover all available registry items.
+- Use MCP tool `get-loveui-package` to fetch exact registry JSON for selected items.
+- Treat MCP results as the source of truth for UI components, building blocks, examples, templates, and related registry entries.
+
+## Core Rules
+
+- Start by extracting constraints: product type, audience, framework, existing design system, and timeline.
+- Choose one visual direction before coding. Avoid generic default layouts.
+- Build a coherent token system first: spacing, typography, colors, radius, shadows.
+- Enforce visual rules from `references/visual-primitives.md` before component assembly.
+- Enforce interaction/state rules from `references/interaction-heuristics.md` for every interactive surface.
+- Enforce semantic and reuse rules from `references/structural-cleanliness.md` when defining components/layouts.
+- Design desktop and mobile together.
+- Define loading, empty, error, and success states for core surfaces.
+- Preserve existing visual patterns when working in an established codebase.
+- For LoveUI installs, use `npx love-ui add <component>` only.
+- Never install internal packages directly (`@loveui/*`, `@love-ui/*`, `@repo/*`).
+- Do not guess component availability from memory when MCP is available.
+
+## Agent UX Contract (Non-Negotiables)
+
+When the UI includes an agent, automation, or “apply changes” workflow, the implementation MUST include:
+
+### Plan → Preview → Apply
+
+- **Plan:** 1–3 bullets: what will change, why, what won’t change.
+- **Preview:** diffs/screenshots/structured change summary BEFORE commit.
+- **Apply:** execution state + completion summary.
+
+### Undo & History are first‑class
+
+- **Undo** in the success toast for reversible actions.
+- **History** panel with restore points for high‑impact operations.
+- High‑risk actions require confirmation + preview.
+
+### Choice Architecture
+
+- Default surface shows **3–5** primary actions max.
+- Use progressive disclosure: “More…”, “Advanced”, context menus.
+- Prefer a command palette with context-valid actions (keyboard-first).
+
+### Trust & Explainability Primitives
+
+- “Why this?” drawer for suggestions (short, plain-language).
+- Source/provenance pill (e.g., “From LoveUI registry” / “From MCP item X”).
+- Risk labeling: Low (styling), Medium (layout), High (data/auth/routing).
+- No dead ends: every empty/error state offers a next action.
+
+## Workflow
+
+1. Define scope and screens.
+- List exact pages/views and core user actions for each.
+- For agent surfaces, define the Plan/Preview/Apply flow and the rollback strategy.
+
+2. Set constraints from references.
+- Read `references/visual-primitives.md` and commit to visual constraints (color, type, spacing, depth).
+- Read `references/interaction-heuristics.md` and list required states/interactions per core action.
+- Read `references/structural-cleanliness.md` and define component boundaries + semantic landmarks.
+- If scope includes forms, read `references/forms-and-validation.md`.
+- If scope includes content or system messaging, read `references/content-ux-writing.md`.
+- If scope includes navigation changes, read `references/navigation-and-information-architecture.md`.
+- If scope includes motion/feedback patterns, read `references/motion-and-feedback.md`.
+- If user provides screenshots or mockups, read `references/screenshot-translation-protocol.md` and report preserve/normalize/invent decisions.
+- For all production work, read `references/accessibility-baseline.md`, `references/component-api-and-naming.md`, `references/frontend-architecture.md`, and `references/testing-and-quality-strategy.md`.
+
+3. Build live LoveUI catalog context with MCP.
+- Read `references/mcp-catalog-workflow.md`.
+- Call `resources/list` and map candidate registry items for the requested UI.
+- Call `get-loveui-package` for each selected item before implementation.
+
+4. Choose visual direction.
+- Read `references/design-directions.md`.
+- Commit to one direction for the implementation.
+
+5. Choose layout blueprint.
+- Read `references/page-blueprints.md`.
+- Start from the closest blueprint and adapt.
+
+6. Implement foundations.
+- Set design tokens and section rhythm first.
+- Confirm consistent container widths and breakpoints.
+
+7. Build reusable UI and compose pages.
+- Build reusable components before page assembly.
+- Keep APIs variant-driven and minimal.
+- Ensure semantics and keyboard support.
+- For agent UIs, prefer an “Agent UI Kit” set of blocks:
+  - command palette, plan/preview/apply panel, diff viewer, run log/timeline, history/restore, inspector.
+
+8. Apply quality gates.
+- Read `references/quality-gates.md`.
+- Verify visual primitives, interaction heuristics, and structural cleanliness checks passed.
+- Verify accessibility, copy quality, navigation clarity, component API cleanliness, architecture boundaries, and testing gates passed when applicable.
+- Fix all failing checks before finalizing.
+
+## Output Contract
+
+Always provide:
+
+- The chosen visual direction and brief rationale.
+- Confirmation that `visual-primitives`, `interaction-heuristics`, and `structural-cleanliness` constraints were applied.
+- Any additional references used (accessibility/forms/content/motion/navigation/architecture/testing) and how they influenced decisions.
+- For screenshot-driven tasks, include what was preserved, normalized, and invented.
+- Files created/updated.
+- Commands run.
+- Any remaining gaps or tradeoffs.

package/skills/loveui-skills/references/accessibility-baseline.md

@@ -0,0 +1,32 @@
+# Accessibility Baseline (WCAG-Focused)
+
+Accessibility is not an enhancement; it is a foundational requirement for all LoveUI components. Every interface must be universally usable by default.
+
+## 1. Contrast and Visual Legibility
+- **Text Contrast:** All normal-sized text must strictly meet WCAG AA standards (minimum 4.5:1 contrast ratio against its background). Large text (18pt and above) must meet a 3:1 ratio.
+- **Non-Text Contrast:** Essential UI components, such as input borders, icons, and focus rings, must maintain a 3:1 contrast ratio against adjacent colors to ensure they are perceivable.
+
+## 2. Keyboard Navigation & Focus Order
+- **Focus Indicators:** Every interactive element must have a highly visible focus ring. Never remove the default outline unless replacing it with a more prominent, brand-aligned focus state.
+- **Logical Flow:** Focus must travel predictably from top-to-bottom, left-to-right. The DOM order must match the visual order.
+- **No Traps:** A user must be able to navigate into and out of any component (like a modal or complex widget) using only the `Tab` and `Shift+Tab` keys.
+
+## 3. ARIA Rules of Engagement
+- **First Rule of ARIA:** No ARIA is better than bad ARIA. Always use native semantic HTML elements (`nav`, `button`, `dialog`) before reaching for ARIA roles.
+- **State Management:** Use `aria-expanded`, `aria-pressed`, and `aria-invalid` to programmatically communicate the live state of interactive components to screen readers.
+- **Hidden Elements:** Ensure decorative icons or redundant visual elements are hidden from screen readers to reduce auditory clutter. 
+
+## 4. Screen Reader Context
+- **Actionable Labels:** Icon-only buttons (like a trash can or a magnifying glass) must have explicit, visually hidden text labels explaining their exact function.
+- **Contextual Announcements:** Dynamic page changes, such as a successful form submission or a new error appearing, must be announced to assistive technologies via live regions.
+
+## 5. Reduced Motion & Touch Targets
+- **Motion Preferences:** All decorative animations and continuous motion must be disabled if the user's operating system requests reduced motion.
+- **Touch Targets:** Any interactive element on a touch device must have a minimum interactive area of 44x44 pixels, even if the visual element (like a small icon) is smaller.
+
+## 6. Accessibility Verification Checklist
+- **Keyboard Pass:** Navigate core flows with keyboard only (`Tab`, `Shift+Tab`, `Enter`, `Space`, `Esc`) and verify no blocked step.
+- **Screen Reader Labels:** Validate that icon-only controls, form inputs, and landmark regions have meaningful announced names.
+- **Focus Visibility:** Confirm focus ring remains visible on all interactive controls in both light and dark themes.
+- **Contrast Spot Checks:** Validate primary text, muted text, and controls against their backgrounds.
+- **Dynamic Announcements:** Verify success/error/status updates are announced when content changes asynchronously.

package/skills/loveui-skills/references/component-api-and-naming.md

@@ -0,0 +1,30 @@
+# Component API and Naming Conventions
+
+UI components are the internal building blocks of the product. Their APIs must be predictable, tightly scoped, and self-documenting to prevent architectural rot.
+
+## 1. Prop Naming Conventions
+- **Event Handlers:** All callback properties must start with `on` followed by an explicit verb-noun pairing describing the event trigger (e.g., `onConfirm`, `onDrawerClose`).
+- **State Declarations:** Boolean properties that describe the component's state must be phrased as questions or assertions (e.g., `isLoading`, `hasError`, `isExpanded`).
+
+## 2. The Anti-Pattern of Boolean Explosion
+- **Variants Over Booleans:** Never use multiple overlapping boolean properties to dictate a component's appearance. Instead of having separate flags for `isPrimary`, `isDestructive`, and `isGhost`, use a single, explicit `variant` property that accepts specific string values. 
+
+## 3. Composition Over Configuration
+- **The "Mega Prop" Ban:** A component should never accept a massive data object that dictates its entire internal layout. 
+- **Slot Architecture:** Build complex components using modular slots or child compositions. A complex layout should be built by nesting modular sub-components (like Header, Body, and Footer structural elements) rather than passing all data through one monolithic property.
+
+## 4. File and Concept Naming
+- **Domain-Driven:** File and component names must describe *what* the component represents within the business logic, not *how* it looks. 
+- **Case Consistency:** Enforce strict naming conventions. Use PascalCase for structural component files and kebab-case for utility or conceptual files.
+
+## 5. API Surface Discipline
+- **Minimal Public API:** Expose only props needed by real callers; remove speculative options.
+- **Stable Defaults:** Prefer sensible defaults so call sites stay short and consistent.
+- **Controlled vs Uncontrolled:** If a component can be controlled, define `value` + `onChange` clearly and document fallback behavior.
+- **No Leaky Abstractions:** Avoid exposing internal implementation details (DOM shape, internal state flags) through public props.
+
+## 6. Component Definition of Done
+- Prop names are explicit and consistent with project conventions.
+- Variant model replaces overlapping visual booleans.
+- Composition patterns are preferred over mega-config props.
+- Component API remains small, predictable, and documented by usage.

package/skills/loveui-skills/references/content-ux-writing.md

@@ -0,0 +1,33 @@
+# Content and UX Writing
+
+Words are the most critical interface layer. LoveUI relies on crisp, predictable, and plain-language microcopy to guide users without cognitive friction.
+
+## 1. Action-Oriented Button Labels
+- **Verb-Led:** Buttons must always start with a strong, unambiguous verb that describes the exact outcome of the click (e.g., "Create Project", "Delete Account", "Save Changes").
+- **Avoid Vagueness:** Never use generic labels like "Submit", "Click Here", or "Go" for primary workflows.
+
+## 2. Empty, Error, and Loading States
+- **Empty States:** An empty screen is a missed opportunity. Empty state copy must explain what the space is for, why it is currently empty, and provide a clear primary action to populate it.
+- **Error Copy:** Never blame the user. Error messages must explicitly state what went wrong in plain language and provide a direct path to resolution. Avoid technical jargon or error codes in the user-facing text.
+- **Loading Copy:** For operations taking longer than two seconds, provide context on what the system is doing (e.g., "Analyzing your dataset..." rather than just "Loading...").
+
+## 3. Confirmation and Destructive Language
+- **High-Friction Language:** Destructive actions must use explicitly cautious language. The confirmation button must match the severity of the action (e.g., "Yes, Delete Organization").
+- **Double Confirmation:** For irreversible, high-impact actions, require the user to manually type the name of the object being deleted to confirm intent.
+
+## 4. Tone Consistency and Plain Language
+- **Professional but Human:** The tone should be helpful, direct, and encouraging. Avoid overly robotic phrasing, but do not use forced humor, slang, or emojis in system-level messaging.
+- **Reading Level:** Write interface copy at an eighth-grade reading level. Prioritize clarity over cleverness.
+
+## 5. Copy Templates (Default Patterns)
+- **Empty state:** `"[Resource] appears here. [One-line benefit]. [Primary action]."`
+- **Error state:** `"We couldn't [action]. [Likely reason if known]. [Next step]."`
+- **Success toast:** `"[Action] complete."` plus `Undo` for reversible operations.
+- **Destructive confirm title:** `"Delete [object]?"`
+- **Destructive confirm body:** `"This will [consequence]. This action [is/is not] reversible."`
+
+## 6. UX Writing Definition of Done
+- Labels, helper text, and validation messages use consistent terminology.
+- Every empty/error/loading/success state includes clear next-step guidance.
+- Destructive actions communicate consequence and reversibility explicitly.
+- Primary actions use specific verb-led labels, not generic wording.

package/skills/loveui-skills/references/forms-and-validation.md

@@ -0,0 +1,30 @@
+# Forms and Validation Architecture
+
+Forms are the primary engine of data collection. Their design must minimize anxiety and maximize completion rates through logical flow and intelligent feedback.
+
+## 1. Cognitive Grouping
+- **Chunking:** Break long forms into logical, thematic sections using clear headings or multi-step wizards. A user should never face a wall of inputs.
+- **Single Column Layouts:** Default to single-column forms. Users read forms top-to-bottom; multi-column layouts disrupt the visual scanning path and increase cognitive load.
+
+## 2. Required vs. Optional Conventions
+- **Assume Required:** In modern SaaS, most form fields should be required. Instead of marking every field with a red asterisk, explicitly mark the rare optional fields with an "(optional)" text label next to the field name.
+
+## 3. Inline Validation Timing
+- **Reward Early, Punish Late:** Never show an error while the user is actively typing in a field for the first time. 
+- **On Blur:** Validate a field and display errors only after the user has finished typing and moved away from the input (on blur).
+- **Error Recovery:** Once an error is displayed, switch to aggressive validation. Clear the error immediately as the user types the correct input (on change) to provide instant positive reinforcement.
+
+## 4. Asynchronous Validation
+- **Immediate Feedback:** For fields that require server-side checks (like username availability or complex data formatting), display a subtle, inline loading indicator within the input field to communicate that the system is checking.
+
+## 5. Submission and Error Summary
+- **Preserve Input:** Never clear user-entered values after validation failures.
+- **First Error Focus:** On submit failure, move focus to the first invalid field and keep inline errors visible.
+- **Error Summary:** For long forms, show a top-level summary linking to invalid fields.
+- **Pending State:** Disable duplicate submit attempts while request is in flight and show explicit progress text.
+
+## 6. Form Definition of Done
+- Required vs optional fields are unambiguous.
+- Inline validation timing follows on-blur first, then on-change recovery.
+- Async validation has visible pending, success, and failure states.
+- Failed submits preserve values and provide clear correction path.

package/skills/loveui-skills/references/frontend-architecture.md

@@ -0,0 +1,30 @@
+# Frontend Architecture Philosophy
+
+The boundary between interface rendering and data logic must be impenetrable. A clean architecture ensures the UI remains fast, scalable, and easy to debug.
+
+## 1. State and Data Boundaries
+- **Local vs. Global:** Default to keeping state strictly local to the component that needs it. Only elevate state to a global context if it is required by multiple, disconnected regions of the application (like user authentication status or global theme settings).
+- **Derived State:** Never store data in the state if it can be mathematically derived or filtered from existing data on the fly.
+
+## 2. Server vs. Client Logic Separation
+- **Dumb Components:** Visual interface components must be entirely unaware of how data is fetched or mutated. They should simply receive data, render it beautifully, and emit events when the user interacts.
+- **Smart Wrappers:** All data fetching, caching, and server mutation logic must be abstracted into dedicated container modules or custom hooks that wrap the visual components.
+
+## 3. API Conventions and Side Effects
+- **Predictable Mutations:** Side effects (like submitting data to a server) must be highly localized and traceable. 
+- **Optimistic UI:** When a user takes a highly predictable action (like starring an item), update the visual interface instantly to assume success, while handling the actual server request silently in the background. If the request fails, cleanly revert the interface and show an error.
+
+## 4. Folder Structure Logic
+- **Feature-Centric:** Organize the architecture by feature domain (e.g., "Authentication", "Billing", "Projects") rather than by file type (e.g., putting all global components in one massive folder). This ensures that deleting a feature completely removes its associated logic and interface elements.
+
+## 5. Data and Side-Effect Boundaries
+- **One Mutation Path:** Each write action should have one clear pathway (action/hook/service), not duplicated request logic across components.
+- **Fetch Ownership:** Data fetching responsibility should be explicit per route/feature to prevent duplicate requests and race conditions.
+- **Error Normalization:** Normalize server errors into predictable shapes before they reach presentation components.
+- **Caching Rules:** Define stale/refresh behavior intentionally for each high-traffic surface.
+
+## 6. Architecture Definition of Done
+- Local, shared, and global state boundaries are justified and documented by usage.
+- Presentational components remain data-source agnostic.
+- Side effects are traceable and concentrated in predictable modules.
+- Feature folders encapsulate UI, state, and behavior coherently.

package/skills/loveui-skills/references/interaction-heuristics.md

@@ -0,0 +1,45 @@
+# Interaction & UX Heuristics
+
+A beautiful interface is useless if it feels static or overwhelming. This document dictates the behavioral expectations and user experience rules for all LoveUI elements.
+
+## 1. Mandatory Micro-Interactions
+Every interactive element on the screen must provide immediate visual feedback to the user.
+- **Hover States:** Any clickable element must visibly react when a cursor passes over it, typically through a subtle background color shift or a slight change in opacity.
+- **Focus Rings:** Accessibility is non-negotiable. All inputs and buttons must display a crisp, highly visible focus ring when navigated via keyboard. 
+- **Disabled States:** Elements that are currently inactive must be visually muted (lowered opacity) and visually communicate that they cannot be interacted with.
+
+## 2. Progressive Disclosure
+Interfaces must respect the user's cognitive load. Do not present every possible action or piece of data at once.
+- **Primary vs. Secondary:** A screen or panel should have exactly one clear primary action. 
+- **Hiding Complexity:** If a surface requires more than four or five actions, the secondary and tertiary actions must be nested behind a context menu, an "Advanced" toggle, or a "More options" dropdown. Keep the default view pristine.
+
+## 3. Predictable Alignment
+The human eye scans for patterns. Breakages in alignment create subconscious friction.
+- **Text and Data:** Default to left-alignment for almost all text, forms, and data tables. Numbers in tables should be right-aligned for easy comparison.
+- **Centering:** Reserve center-alignment strictly for standalone elements like marketing hero headers or empty-state messaging. Do not center-align paragraphs of text or form fields.
+- **Structural Integrity:** Ensure that the edges of containers, typography bounding boxes, and image assets align perfectly on a vertical axis down the page.
+
+## 4. State Management Visibility
+The user must never guess what the system is doing.
+- **Transitional States:** Define clear visual states for when data is loading (e.g., subtle pulsing skeletons instead of disruptive spinners).
+- **Empty States:** When a data table or list is empty, never leave a blank screen. Always provide a beautifully formatted empty state that explains what belongs there and offers a primary action to populate it.
+
+## 5. Feedback Timing & Motion Restraint
+Motion should communicate cause-and-effect, never decorate.
+- **Timing:** Keep most transitions between 120-220ms; avoid slow, dramatic easing for core actions.
+- **Consistency:** Reuse the same interaction timing/easing tokens across buttons, menus, drawers, and toasts.
+- **Reduced Motion:** Respect reduced-motion preferences by minimizing or disabling non-essential movement.
+
+## 6. Action Safety & Recovery
+Users need confidence when actions can change real state.
+- **Risk Signaling:** Label risky actions with clear severity and consequence language before execution.
+- **Confirmation:** Require confirm + preview for destructive or high-impact changes.
+- **Recovery:** Success feedback should include Undo when the action is reversible.
+- **Error Recovery:** Error states must present at least one clear next action (retry, edit input, or open details).
+
+## 7. Definition of Done (Interaction)
+- Every interactive element has visible hover, focus, and disabled states.
+- Primary action is obvious in each major screen/panel.
+- Loading, empty, error, and success states are implemented for key workflows.
+- Keyboard navigation and focus order are coherent for primary flows.
+- Complex action sets are progressively disclosed rather than front-loaded.

package/skills/loveui-skills/references/motion-and-feedback.md

@@ -0,0 +1,31 @@
+# Motion and System Feedback
+
+Animation in LoveUI is strictly functional. It exists to explain state changes, establish spatial relationships, and focus attention—never for mere decoration.
+
+## 1. The Timing and Easing System
+- **Speed Constraints:** Interface animations should be virtually imperceptible, serving only to smooth transitions. Default to ultra-fast durations for micro-interactions and slightly longer durations for structural page shifts.
+- **Easing Curves:** Never use linear animations. Use snappy, decelerating easing curves for elements entering the screen (starting fast, ending slow) and accelerating curves for elements exiting.
+
+## 2. Purpose-Driven Animation
+- **When to Animate:** Animate to show an object's origin (like a modal expanding from a button), to highlight a change in status, or to smooth the transition between layout changes.
+- **When to Remain Static:** Do not animate standard data rendering, typography loads, or static structural borders. 
+
+## 3. Skeletons vs. Spinners
+- **Skeletons for Known Layouts:** If the structural layout of the incoming data is known (like a list of cards or a table), use pulsing skeleton loaders to establish the spatial expectation before the data arrives.
+- **Spinners for Unknowns:** Reserve circular loading spinners strictly for localized, unpredictable actions (like a button processing a payment) or full-page blank-slate loads.
+
+## 4. Toasts and Banners
+- **Transient Toasts:** Use small, auto-dismissing toast notifications strictly for low-priority, successful system confirmations (e.g., "Link copied to clipboard"). 
+- **Persistent Banners:** Use full-width, non-dismissible (or manually dismissible) banners for high-priority, contextual warnings that affect the user's current workflow (e.g., "Your trial expires in 2 days").
+
+## 5. Timing Defaults
+- **Micro interactions:** 120-180ms.
+- **Panel open/close:** 180-240ms.
+- **Page/route transitions:** 200-300ms, only when they improve orientation.
+- **Staggering:** Avoid multi-element staggers unless the sequence communicates order or priority.
+
+## 6. Motion Definition of Done
+- Motion explains state or spatial change; no decorative animation loops.
+- Reduced-motion preference is respected for non-essential transitions.
+- Feedback primitive selection is intentional (skeleton vs spinner, toast vs banner).
+- Success, warning, and error feedback are visually and semantically distinct.

package/skills/loveui-skills/references/navigation-and-information-architecture.md

@@ -0,0 +1,30 @@
+# Navigation and Information Architecture
+
+Users should never feel lost. Navigation must act as a reliable map, heavily favoring explicit wayfinding over hidden menus.
+
+## 1. Navigation Depth and Hierarchy
+- **The Three-Click Rule:** A user should be able to reach any core functional area of the application within three interactions. 
+- **Flat Over Deep:** Avoid deep nesting. If an architecture requires four levels of folders or menus, the top-level categorization must be re-evaluated and flattened.
+
+## 2. Wayfinding and Context
+- **Active States:** The current location must always be explicitly highlighted in the primary and secondary navigation menus using bold typography, distinct background colors, or structural indicators.
+- **Breadcrumbs:** Utilize breadcrumbs for any view that is two or more levels deep. Breadcrumbs provide immediate context and an easy escape hatch to higher-level directories.
+
+## 3. URL as the Source of Truth
+- **State in the URL:** Any significant UI state change—such as opening a specific tab, applying a data filter, or opening a detail drawer—must be reflected in the URL parameters. 
+- **Shareability:** A user should be able to copy the URL at any exact moment, send it to a colleague, and have the interface load in the exact same state, including active filters and open views.
+
+## 4. Mobile Navigation Grace
+- **Bottom vs. Top:** On mobile, place primary navigation items in a highly accessible bottom bar. Reserve "hamburger" menus strictly for secondary settings, billing, and account management, never for core daily workflows.
+
+## 5. IA and Navigation Guardrails
+- **Single Primary Nav Model:** Use one primary navigation pattern per app area; avoid mixing unrelated paradigms in the same workspace.
+- **Stable Labels:** Keep navigation labels consistent across screens and releases unless a migration is intentional and documented.
+- **Back Behavior:** Browser back/forward should restore prior view state (filters, selected tab, pagination) when feasible.
+- **Escalation Path:** Deep detail views should always offer an obvious route back to the parent context.
+
+## 6. Navigation Definition of Done
+- Users can reach any core area quickly without hidden detours.
+- Active context is visible in nav and page-level heading hierarchy.
+- URL reflects meaningful state for sharing and restoring context.
+- Mobile navigation keeps core actions in thumb-reachable zones.

package/skills/loveui-skills/references/screenshot-translation-protocol.md

@@ -0,0 +1,52 @@
+# Screenshot Translation Protocol
+
+When provided with a static screenshot, mockup, or reference image, the goal is not to blindly duplicate pixels. The goal is to deconstruct the image's intent and reconstruct it using LoveUI's strict architectural and visual constraints. A static image is an incomplete blueprint; you must infer the missing systemic rules.
+
+## 1. Visual Deconstruction and The Grid
+Before analyzing any specific element, deconstruct the macro-layout of the provided image into a strict mathematical grid.
+- **Identify the Skeleton:** Map the image into core structural landmarks (e.g., Sidebars, Navigation Rails, Primary Canvas, Context Panels). Do not proceed until the overarching grid or flexbox architecture is conceptually defined.
+- **Normalize to the 8pt System:** Reference images often contain arbitrary or messy spacing. You must aggressively normalize all observed margins, paddings, and gaps into strict multiples of 4px or 8px. If a screenshot shows a 17px gap, correct it to 16px. 
+- **Alignment Enforcement:** Identify the primary alignment axes in the image. If elements in the screenshot are slightly misaligned, assume it is a human error in the mockup and enforce mathematically perfect horizontal and vertical alignment in the reconstruction.
+
+## 2. Token Extraction and System Mapping
+Do not sample exact hex codes or font sizes from the image if they violate LoveUI core principles. Translate the image's aesthetic into your predefined system tokens.
+- **Color Translation:** Strip away any gradients or excessive color usage found in the screenshot. Map the dominant background and surface colors to the closest LoveUI monochromatic tokens (Slate, Zinc, etc.). Identify the single primary action color in the screenshot and map it to the LoveUI accent token. 
+- **Typography Standardization:** Ignore the specific font family in the screenshot. Map the visual hierarchy (massive headers, readable body text, muted metadata) strictly to the established LoveUI typographic scale. Enforce readability over stylistic quirks.
+- **Containment Rules:** If the screenshot utilizes heavy drop shadows or thick borders for containment, downgrade them. Translate these boundaries into LoveUI's ultra-subtle 1px borders or the softest available elevation tokens.
+
+## 3. Component Identification and Modularization
+Never build a single, monolithic interface just because the screenshot looks like one flat image.
+- **Pattern Recognition:** Scan the screenshot for repeating visual patterns (e.g., a list of similar items, a row of metric cards). Extract these into conceptual, reusable sub-components rather than repeating the structural logic.
+- **Semantic Mapping:** Identify visual elements and assign them their correct semantic intent. If a visual block looks like a button but acts as a navigation link, structure it semantically as an anchor, regardless of its visual presentation.
+
+## 4. Inferring the Invisible (State and Interaction)
+A screenshot only represents a single moment in time (usually the "happy path"). You are strictly required to invent and implement the missing interactive dimensions.
+- **Mandatory Micro-Interactions:** Even if not pictured, you must define and apply logical `hover`, `focus`, and `disabled` states for every interactive element identified in the image.
+- **Edge Case Extrapolation:** The screenshot likely shows perfect data. You must design how the UI behaves when the data is imperfect. Define the text-truncation rules for long strings, the wrapping behavior for flex layouts, and the empty states if the visible data were to be removed.
+
+## 5. Viewport Adaptation
+A screenshot represents exactly one screen width. You must immediately define how this layout expands and contracts.
+- **Degradation Strategy:** Determine the mobile behavior for the desktop screenshot. Decide which columns will stack, which sidebars will become off-canvas drawers, and which secondary elements will be hidden behind progressive disclosure menus on smaller screens.
+
+## 6. Translation Workflow (Execution Order)
+1. **Classify source:** identify whether input is dashboard, marketing, workspace, settings, docs, or agent workspace.
+2. **Select blueprint:** map to `references/page-blueprints.md` and note any deviations.
+3. **Token-map visuals:** translate typography, spacing, color, radius, border, and elevation into LoveUI tokens.
+4. **Extract components:** list reusable blocks before coding repeated patterns.
+5. **Define states:** add hover/focus/disabled + loading/empty/error/success behavior.
+6. **Adapt responsively:** define desktop/tablet/mobile layout transitions.
+7. **Validate gates:** run `references/quality-gates.md` and accessibility checks before final output.
+
+## 7. Output Requirements for Screenshot Tasks
+When implementing from screenshots, always report:
+- **What was preserved:** hierarchy, information zoning, and key interaction model.
+- **What was normalized:** spacing alignment, token choices, contrast, and semantics.
+- **What was invented:** missing states, edge-case behavior, and mobile adaptations.
+- **Risk notes:** areas where screenshot ambiguity required assumptions.
+
+## 8. Definition of Done (Screenshot Translation)
+- Layout is mathematically aligned and normalized to 4/8 spacing increments.
+- Visual style conforms to LoveUI primitives rather than raw pixel copying.
+- Repeated patterns are componentized with reusable APIs.
+- Interaction states and non-happy-path states are explicitly implemented.
+- Result is responsive and passes quality + accessibility gates.

package/skills/loveui-skills/references/structural-cleanliness.md

@@ -0,0 +1,37 @@
+# Structural Cleanliness & Architecture
+
+This document outlines the philosophy for constructing the underlying framework of the UI. Even though the end user does not see the structure, a messy foundation leads to a disjointed visual output. 
+
+## 1. Absolute Semantic Accuracy
+The structural tags used to build the interface must describe their exact purpose. 
+- **Landmarks:** The interface must be divided logically into headers, main content areas, navigation rails, sidebars, and footers using the correct descriptive syntax. 
+- **Interactive Semantics:** Only use button structures for actions that trigger events, and anchor structures for actions that navigate to new views. Do not mix their visual representations with their functional realities.
+
+## 2. Abstraction and Reusability
+Do not build monolithic, endlessly scrolling structures. 
+- **Granularity:** Break complex interfaces down into the smallest possible logical pieces. A data dashboard should be composed of distinct, reusable card structures, list structures, and chart structures.
+- **Utility Discipline:** When utilizing styling systems, avoid repeating long strings of visual definitions. If a specific combination of visual rules (like a standard card container with specific padding and borders) appears more than twice, it must be abstracted into a single, reusable concept.
+
+## 3. Responsive Grace
+The interface must degrade beautifully, not just functionally, as screen sizes change.
+- **Fluid Layouts:** Rely on flexible grid and column systems that naturally reflow content. 
+- **Mobile Realities:** On narrow viewports, complex multi-column layouts must stack logically. Ensure that touch targets become slightly larger to accommodate fingers, and that critical navigation actions remain permanently accessible without excessive scrolling.
+
+## 4. Information Hierarchy Integrity
+Structure should make meaning obvious without visual decoration.
+- **Heading Order:** Use a strict, logical heading sequence; do not skip levels in long-form or dashboard sections.
+- **Chunking:** Group related controls/content into explicit sections with concise section labels.
+- **Reading Flow:** Keep primary content before secondary utilities in the DOM when possible.
+
+## 5. Component and File Boundaries
+Maintain a clean implementation surface as UI complexity grows.
+- **Single Responsibility:** Each component should own one clear job (layout shell, card, table, filter bar, etc.).
+- **Composition First:** Favor composition of smaller primitives over deeply configurable mega-components.
+- **Locality:** Keep styles, tests, and stories/examples near components when project conventions allow.
+
+## 6. Definition of Done (Structure)
+- Landmarks and semantic elements match the page intent.
+- Buttons trigger actions; links navigate; semantics are never mixed for convenience.
+- Repeated UI patterns are abstracted into reusable components/tokens.
+- Mobile stacking preserves task flow and keeps critical actions reachable.
+- File and component naming remain consistent and predictable.

package/skills/loveui-skills/references/testing-and-quality-strategy.md

@@ -0,0 +1,33 @@
+# Testing and Quality Strategy
+
+A beautiful interface is fragile without a rigorous quality safety net. Quality must be enforced systematically before any design reaches production.
+
+## 1. The Testing Pyramid
+- **Unit Testing:** Focus unit tests strictly on complex, isolated mathematical logic, data formatting utilities, and pure state transformations. Do not write brittle unit tests that verify simple CSS class names.
+- **Integration Testing:** Prioritize integration tests that verify the exact connections between smart data wrappers and the dumb visual components.
+- **End-to-End (E2E):** Reserve heavy E2E tests for the absolute critical business paths (e.g., user signup, payment flows, core object creation).
+
+## 2. Visual Regression Policy
+- **Automated Eyes:** Any change to a core UI component must automatically trigger a visual regression check against established baselines. This prevents a spacing tweak in a button from cascading and breaking navigation headers across the platform.
+
+## 3. Accessibility Quality Gates
+- **Automated Audits:** The continuous integration pipeline must automatically block any code that introduces standard WCAG violations (like missing form labels, severe contrast failures, or missing ARIA roles).
+
+## 4. The Definition of Done
+A feature or UI update is strictly not considered complete until:
+- It functions flawlessly on desktop, tablet, and mobile breakpoints.
+- It can be fully operated using only a keyboard.
+- All loading, empty, and error states have been explicitly designed and implemented.
+- It adheres completely to the LoveUI visual primitives and spatial grid constraints.
+
+## 5. Minimum Test Matrix (Per Feature)
+- **Happy path integration test:** verifies primary user objective end-to-end within the feature boundary.
+- **Failure path integration test:** verifies user-visible recovery for at least one realistic backend/client failure.
+- **Accessibility smoke test:** keyboard traversal + basic a11y assertions for primary controls.
+- **Visual snapshot(s):** stable snapshots for default, loading, and error/empty states where layout risk exists.
+
+## 6. Release Gate Checklist
+- Critical flows pass on target browsers/devices.
+- No unresolved high-severity accessibility or UX regressions.
+- New or changed components include regression coverage at the right layer.
+- Quality-gate references (`visual-primitives`, `interaction-heuristics`, `structural-cleanliness`) are satisfied.

package/skills/loveui-skills/references/visual-primitives.md

@@ -0,0 +1,42 @@
+# Visual Primitives & Aesthetic Constraints
+
+This document defines the strict visual boundaries for all LoveUI generations. The goal is an ultra-clean, minimalist, and highly professional aesthetic. You must adhere to these foundational design rules before assembling any layout.
+
+## 1. The Zero-Gradient Mandate
+Under no circumstances should gradients be applied to backgrounds, typography, borders, or buttons unless explicitly requested by the user. Gradients introduce unnecessary visual noise. Rely entirely on flat, solid colors to establish depth and hierarchy.
+
+## 2. Monochromatic Dominance & Singular Accent
+The color system must be strictly disciplined. 
+- **Base Palette:** Ninety percent of the interface must utilize a neutral, monochromatic scale (e.g., pure grays, slates, or zincs). 
+- **Accent Application:** Select exactly one primary brand color. This color must be reserved exclusively for primary actions, active states, and critical data highlights. Never use the accent color for decorative backgrounds or structural borders.
+- **Backgrounds:** Default to a pure white or an ultra-light gray for light mode, and a pure black or ultra-dark gray for dark mode. Avoid mid-tones for main structural backgrounds.
+
+## 3. Topographic Typography
+Typography must do the heavy lifting for the interface's structural hierarchy.
+- **Font Selection:** Always default to a clean, modern, sans-serif system typeface.
+- **Scale and Weight:** Enforce a strict typographic scale. Page titles must be large and bold; section headings should be medium and semibold; body text must be legible and regular weight.
+- **Subordinate Text:** Metadata, timestamps, and secondary descriptions must utilize a smaller font size and a muted text color to recede visually. 
+
+## 4. The Spatial Grid 
+Whitespace is the primary tool for organizing information.
+- **Strict Multiples:** All margins, padding, and positional values must adhere to a strict base-8 (or base-4 for micro-spacing) mathematical scale. 
+- **Breathing Room:** Never crowd elements. Elements that belong to the same logical group should be closer together, while distinct sections must be separated by generous, mathematically consistent whitespace.
+
+## 5. Depth and Containment
+Avoid heavy drop shadows and thick borders. 
+- **Separation:** Use ultra-subtle, one-pixel borders in a very light gray to separate panels and sections.
+- **Elevation:** If shadows are necessary to indicate a floating element (like a dropdown menu or modal), use the softest, most diffused, and smallest shadow available. The interface should feel flat and crisp, not raised and heavy.
+
+## 6. Implementation Defaults (Use Unless User Overrides)
+- **Spacing Scale:** `4, 8, 12, 16, 24, 32, 40, 48, 64`.
+- **Radius Scale:** `6` (inputs/buttons), `10` (cards), `14` (modals/drawers), avoid mixing many radii.
+- **Border Color:** one neutral border token for most surfaces, one stronger border token for focus/active grouping.
+- **Shadow Policy:** no persistent heavy shadows; one subtle shadow token for floating layers only.
+- **Accent Budget:** one accent hue, with at most two intensity steps for hover/active states.
+
+## 7. Definition of Done (Visual)
+- No gradients unless explicitly requested.
+- Accent color appears only on primary actions, active states, and critical highlights.
+- Typography hierarchy is clear at a glance (title, section, body, metadata).
+- Spacing values snap to the defined scale and are consistent between similar sections.
+- Borders/shadows are subtle, sparse, and purposeful.