playbooks

home / skills / fusengine / agents / component-variants

component-variants skill

/plugins/design-expert/skills/component-variants

This skill helps you implement multi-style components using CVA variants (glass, outline, flat) with dark mode and hover states.

npx playbooks add skill fusengine/agents --skill component-variants

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.6 KB
---
name: component-variants
description: Use when creating multi-style components, variant props, or style switching. Covers Glass, Outline, and Flat styles with CVA.
versions:
  cva: "1.x"
user-invocable: true
allowed-tools: Read, Write, Edit, Glob, Grep
related-skills: glassmorphism-advanced, generating-components
---

# Component Variants

## Agent Workflow (MANDATORY)

Before implementation, use `TeamCreate` to spawn 3 agents:

1. **fuse-ai-pilot:explore-codebase** - Check existing variant patterns
2. **fuse-ai-pilot:research-expert** - cva/class-variance-authority docs

After: Run **fuse-ai-pilot:sniper** for validation.

---

## Overview

| Style | Characteristics | Use Case |
|-------|-----------------|----------|
| **Glass** | Blur + transparency + glow | Premium, modern, hero |
| **Outline** | Border only, no fill | Secondary actions |
| **Flat** | Solid color, no effects | Dense UI, fallback |

---

## Quick Reference

### CVA Card Variants

```tsx
import { cva, type VariantProps } from "class-variance-authority";

const cardVariants = cva(
  "rounded-2xl p-6 transition-all duration-200",
  {
    variants: {
      variant: {
        glass: [
          "bg-white/80 backdrop-blur-xl",
          "border border-white/20",
          "shadow-xl shadow-black/5",
        ],
        outline: [
          "bg-transparent",
          "border-2 border-primary/30",
          "hover:border-primary/50",
        ],
        flat: [
          "bg-surface",
          "border border-border",
        ],
      },
    },
    defaultVariants: {
      variant: "glass",
    },
  }
);
```

### Button Variants

```tsx
const buttonVariants = cva(
  "inline-flex items-center justify-center font-medium transition-all",
  {
    variants: {
      variant: {
        glass: "bg-white/20 backdrop-blur-md border border-white/30",
        outline: "bg-transparent border-2 border-primary text-primary",
        flat: "bg-primary text-primary-foreground",
      },
    },
  }
);
```

### Dark Mode Per Variant

```tsx
const glassVariant = {
  light: "bg-white/80 backdrop-blur-xl border-white/20",
  dark: "bg-black/40 backdrop-blur-xl border-white/10",
};

// Tailwind
className="bg-white/80 dark:bg-black/40 backdrop-blur-xl"
```

---

## Validation Checklist

```
[ ] All 3 variants defined (glass, outline, flat)
[ ] CVA or similar variant system used
[ ] Dark mode handled per variant
[ ] Default variant specified
[ ] Hover states per variant
```

---

## Best Practices

### DO
- Use CVA for type-safe variants
- Define all three styles consistently
- Handle dark mode per variant
- Add hover/focus states

### DON'T
- Mix variant systems
- Forget default variant
- Skip dark mode
- Ignore hover states

Overview

This skill helps teams implement multi-style UI components using class-variance-authority (CVA) patterns. It codifies three consistent visual variants—Glass, Outline, and Flat—plus dark mode and hover behaviors. Use it to standardize variant props, default values, and validation for component libraries.

How this skill works

The skill provides CVA configurations and example variant definitions for cards, buttons, and other primitives. It enforces a checklist: define glass/outline/flat variants, use CVA (or an equivalent typed variant system), specify a default variant, and include dark-mode and hover states. It also includes an agent workflow to research existing patterns and validate the final implementation.

When to use it

  • Building new reusable components that need multiple visual styles
  • Migrating or refactoring existing components to a consistent variant system
  • Creating design-system tokens that must support light and dark themes
  • Implementing variant props with type-safety in TypeScript
  • Adding hover, focus, and accessibility-aware states to variants

Best practices

  • Use CVA for type-safe, composable variant definitions
  • Define all three variants (glass, outline, flat) for consistency
  • Set a sensible default variant to avoid undefined styling
  • Provide dark-mode alternatives per variant rather than global overrides
  • Add hover and focus states to each variant for predictable interactions

Example use cases

  • Card component with cva-based variant prop and default set to glass
  • Button primitive exposing variant prop: glass, outline, flat with typed VariantProps
  • Theme-aware components switching border/fill for dark and light modes
  • Component migration where each existing style maps to one of the three canonical variants
  • Automated validation step that checks variant presence, CVA usage, defaults, and hover states

FAQ

What exactly are the three variants?

Glass uses blur, transparency, and glow for premium surfaces; Outline is border-only for secondary actions; Flat is solid color without effects for dense or fallback UI.

Do I have to use CVA?

You should use CVA or a similar typed variant utility for consistency and type-safety, but the pattern can be adapted if your stack provides equivalent tools.

How should dark mode be handled?

Provide per-variant dark values (e.g., glass.light vs glass.dark) instead of a single global swap. This ensures visual intent remains across themes.