love-ui 1.2.15 → 1.2.18

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/design-directions.md

@@ -0,0 +1,60 @@
+# Design Directions
+
+Choose exactly one direction per project unless the user asks for mixed styles.
+
+## 1) Editorial Premium
+
+- Typography-first hierarchy with restrained color.
+- Strong spacing discipline and subtle separators.
+- Best for: marketing pages, product narrative, docs.
+
+## 2) Data-Rich Enterprise
+
+- Dense but readable information zoning.
+- Strong table/chart readability and utility controls.
+- Best for: dashboards, admin tools, operations software.
+
+## 3) Modern SaaS Crisp
+
+- Clean medium-density layout with clear calls to action.
+- Soft radii, controlled shadows, limited accent color.
+- Best for: SaaS products, onboarding, account flows.
+- Also strong for: agent workflows where you want guided “Plan → Preview → Apply”.
+
+## 4) Minimal Product Studio
+
+- Low ornamentation and deliberate whitespace.
+- Strong alignment precision and calm interaction design.
+- Best for: focused tools, portfolio, productivity apps.
+
+## 5) Bold Campaign
+
+- High-impact hero and conversion-first section flow.
+- Strong anchors, large typography, selective motion.
+- Best for: launches, event pages, acquisition landers.
+
+## 6) Technical Console
+
+- Utility-first, fast-scanning interface style.
+- Compact controls and explicit status signaling.
+- Best for: developer tools, monitoring, internal platforms.
+- Also strong for: agent tooling where logs, diffs, and provenance must be always visible.
+
+## Selection Checklist
+
+- Match audience expectations.
+- Match information density.
+- Match brand voice.
+- Confirm readability and contrast.
+
+### Agent UX Fit Checks
+
+If the UI includes an agent:
+
+- Prefer **Technical Console** for power users (dense, explicit status + logs).
+- Prefer **Modern SaaS Crisp** for mixed audiences (guided steps + clearer affordances).
+- Ensure the direction supports:
+  - a clear primary action,
+  - visible system status,
+  - readable diff/log surfaces,
+  - consistent “apply” affordances.

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/mcp-catalog-workflow.md

@@ -0,0 +1,68 @@
+# MCP Catalog Workflow
+
+Use this workflow whenever the `loveui` MCP server is available.
+
+## Goal
+
+Access complete LoveUI registry knowledge from MCP for:
+
+- UI components
+- building blocks
+- examples/demos
+- templates and related registry entries
+
+## Mandatory Steps
+
+1. Call `resources/list` on the `loveui` MCP server.
+- Treat this output as the authoritative live catalog.
+- Do not assume availability from memory.
+
+2. Narrow candidates by user intent.
+- Match names to required surfaces and interactions.
+- Keep a shortlist of likely registry items.
+
+3. Fetch exact definitions with `get-loveui-package`.
+- Call once per shortlisted item.
+- Read `type`, `files`, `dependencies`, `registryDependencies`, and metadata.
+
+4. Build install plan.
+- Use `npx love-ui add <component>` for install commands.
+- Never use internal package installs (`@loveui/*`, `@love-ui/*`, `@repo/*`).
+
+5. Validate composition coverage.
+- Ensure selected items cover all required screens and states.
+- Add missing items by repeating steps 2-4.
+
+## Agent UI Kit (When an agent is present)
+
+If the experience includes “generate/apply changes”, always attempt to assemble a minimal “Agent UI Kit”
+from registry items (components, blocks, examples). Look for items that cover:
+
+- Command palette / quick actions
+- Plan → Preview → Apply panels
+- Diff viewer (code/text) and/or before/after preview
+- Run log / timeline (steps, progress, streaming output)
+- History / restore (snapshots, rollback)
+- Inspector / “why this?” drawer
+- Toasts with Undo, banners, inline status components
+
+If any of these are missing from the selected set, return to steps 2–4 and add them.
+
+## Selection Heuristics
+
+- Prefer base primitives first, then add higher-level blocks/examples.
+- Use examples/demos to accelerate layout and interaction scaffolding.
+- Keep installed set minimal for maintainability.
+- For agent UIs:
+  - prioritize diff/log/history primitives early,
+  - prioritize keyboard-first affordances (palette, shortcuts),
+  - prefer context-valid actions over huge menus.
+
+## Output Requirements
+
+When presenting work, include:
+
+- MCP items selected (names).
+- Install commands executed.
+- Why each selected item maps to the requested UX.
+- For agent UIs: where Plan/Preview/Apply, Undo, and History live in the UI.

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/page-blueprints.md

@@ -0,0 +1,76 @@
+# Page Blueprints
+
+Use these as defaults and adapt to product constraints.
+
+## SaaS Dashboard
+
+1. Global header: context, search, notifications, profile.
+2. KPI row: 3-6 key metrics with trend indicators.
+3. Primary insights zone: chart/table split.
+4. Secondary panels: activity, alerts, tasks, or funnel.
+5. Footer utilities: status/help links.
+
+## Marketing / Landing
+
+1. Hero: value proposition + primary CTA.
+2. Proof: logos, social proof, key stats.
+3. Feature grid with concise benefit copy.
+4. FAQ or comparison section.
+5. Final CTA + footer.
+
+## Workspace / Tool Screen
+
+1. Top bar: context title + critical actions.
+2. Left navigation rail or sidebar.
+3. Main canvas or primary panel.
+4. Secondary inspector/context panel.
+5. Feedback layer: toast, inline status, banners.
+
+## Settings / Account
+
+1. Section tabs or sidebar nav.
+2. Profile and organization settings.
+3. Billing and subscription controls.
+4. Security/access controls.
+5. Danger zone and audit/history.
+
+## Content / Docs
+
+1. Title block with metadata.
+2. Reading progress + table of contents.
+3. Main semantic content body.
+4. Related resources and next action.
+5. Feedback/edit links.
+
+## Agent Workspace (Plan → Preview → Apply)
+
+Use this when the UI includes an agent that proposes changes or executes steps.
+
+1. Top bar: workspace context + primary action (Apply) + secondary (Preview/Run) + palette trigger.
+2. Left rail: activity feed or “runs” list (recent executions).
+3. Center: tabbed **Plan / Preview / Apply** surface.
+   - Plan: concise bullets + risk label.
+   - Preview: diff + before/after preview + impacted files list.
+   - Apply: progress, step timeline, streaming log, final summary.
+4. Right inspector: “Why this?”, provenance, settings, and per-change details.
+5. Bottom feedback: toasts (with Undo), warnings, and inline error recovery actions.
+
+## Diff Review (Focused)
+
+Use for heavy change review or refactors.
+
+1. Header: scope summary (files, risk, estimated impact) + primary actions.
+2. Diff list (left): files/sections, filters (only changed, risky, failing gates).
+3. Diff viewer (center): side-by-side by default with inline comments.
+4. Run/test panel (right or bottom): checks, failures, rerun buttons.
+5. Footer: Apply/merge controls + Undo/restore point creation.
+
+## History & Restore
+
+Use when users need confidence and rollback.
+
+1. Timeline of restore points with metadata (who/when/what).
+2. Compare view between any two snapshots.
+3. Restore flow (preview + confirm).
+4. Guardrails for destructive restores.
+5. Export/share audit trail if relevant.

package/skills/loveui-skills/references/quality-gates.md

@@ -0,0 +1,51 @@
+# Quality Gates
+
+Ship only after all gates pass.
+
+## Visual System
+
+- Typography scale is consistent.
+- Spacing increments are consistent.
+- Color and elevation are tokenized and purposeful.
+- Radius and border treatment are coherent.
+
+## UX and Interaction
+
+- Primary action is obvious on every view.
+- Hover/focus/active/disabled states are present.
+- Loading/empty/error/success states are implemented.
+- Core workflows are obvious and low-friction.
+
+### Agent UX Gates (Ship-blockers)
+
+If the UI includes an agent or “apply changes” workflow:
+
+- **Plan → Preview → Apply** exists and is the default path.
+- **Preview required** for high-risk operations (routing/auth/data model/destructive ops).
+- **Undo** exists for reversible actions and appears in the success toast.
+- **History/restore** exists for high-impact changes (restore points/snapshots).
+- **Visible system status**: current step, progress, and outcome are always visible.
+- **No dead ends**: every empty/error state has a next action.
+- **Choice architecture**: 3–5 primary actions max on the default surface; progressive disclosure for the rest.
+- **Keyboard-first happy path**: palette + navigable controls for key actions.
+- **Provenance**: users can see where suggestions/actions came from (“Why this?”, sources).
+
+## Responsive Behavior
+
+- Layout works on mobile, tablet, desktop.
+- Critical actions remain accessible on small screens.
+- Data surfaces degrade gracefully on narrow viewports.
+
+## Accessibility
+
+- Text/control contrast is sufficient.
+- Keyboard navigation works for all key actions.
+- Semantic headings/landmarks are present.
+- Form labels and validation feedback are clear.
+
+## Maintainability
+
+- Components are reusable and not tightly coupled.
+- Motion is meaningful and restrained.
+- Naming and file organization are consistent.
+- Avoid unnecessary client-side complexity.

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.