@xenterprises/nuxt-x-cards

nuxt-x-cards

A premium card component library for Nuxt 4 with cinematic image filters, warm surfaces, and accessible design.

Built on Nuxt UI v4 and Tailwind CSS v4. Inspired by Oura Ring and Rivian visual identities.

Quick Start

Install the layer in your Nuxt 4 project:

# From git (recommended during development)
pnpm add nuxt-x-cards@github:your-org/nuxt-x-cards

Add to your nuxt.config.ts:

export default defineNuxtConfig({
  extends: ['nuxt-x-cards']
})

All components and CSS utilities are now available. Brands bring their own fonts. The layer does not inject a Google Fonts stylesheet.

Configuration

Customize the design system via app.config.ts under the x.cards namespace. Every key has a sensible default — override only what you need.

// app.config.ts
export default defineAppConfig({
  x: {
    cards: {
      colors: {
        primary: 'blue',             // your Tailwind palette name
        accents: { gold: '#FF6B00' } // override just the gold accent
      },
      fonts: {
        sans: "'Geist', system-ui, sans-serif",
        googleFontsUrl: 'https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&display=swap'
      },
      brand: {
        appName: 'My App',
        logoIcon: 'i-lucide-zap'
      }
    }
  }
})

Full Config Reference

Accessing Config in Components

Use the auto-imported useXCards() composable:

<script setup>
const xCards = useXCards()
// xCards.colors.primary → 'cream'
// xCards.defaults.filter → 'cinematic'
</script>

Color Customization

The layer ships with two custom palettes defined in CSS (@theme static):

• Cream (primary) — warm Oura-inspired surfaces
• Olive (neutral) — warm Rivian charcoal tones

Using Built-in Palettes

Set colors.primary and colors.neutral in your config. These must match palette names defined in your CSS @theme static block.

Creating Custom Palettes

To use your own colors, create a CSS file with your palette and import it:

/* assets/css/my-theme.css */
@theme static {
  --color-ocean-50: #F0F9FF;
  --color-ocean-100: #E0F2FE;
  /* ... shades 200-950 ... */
  --color-ocean-950: #0C1D29;
}

Then set:

// app.config.ts
x: {
  cards: {
    colors: { primary: 'ocean' }
  }
}

Note: The @theme static block is resolved at build time. The config values tell components which palette name to reference in utility classes (e.g., text-primary-200), but the actual hex values come from CSS.

Accent Colors

Accent colors (gold, blue, green) are defined as standalone CSS custom properties (--color-accent-gold, etc.) in the layer's CSS. Override them in your own CSS:

@theme static {
  --color-accent-gold: #FF6B00;
  --color-accent-gold-hover: #E05A00;
}

Font Customization

Brands bring their own fonts. The layer does not inject Inter, Playfair Display, or any Google Fonts URL by default.

Optional pieces if you want the plugin to load a stylesheet:

1. fonts.sans / fonts.serif — CSS font-family stacks
2. fonts.googleFontsUrl — set only if you want this layer to inject a stylesheet
3. CSS @theme static — --font-sans, --font-serif, --font-display

To opt in:

// app.config.ts
x: {
  cards: {
    fonts: {
      sans: "'Geist', system-ui, sans-serif",
      serif: "'Lora', 'Georgia', serif",
      googleFontsUrl: 'https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700&family=Lora:ital,wght@0,400;0,700;1,400&display=swap'
    }
  }
}

And override the CSS custom properties:

@theme static {
  --font-sans: 'Geist', system-ui, sans-serif;
  --font-serif: 'Lora', 'Georgia', serif;
}

Leave googleFontsUrl empty (the default) to skip injection. Set a URL only when you want this layer to load the stylesheet.

Components

XCardHeroFullscreen

Full-viewport hero with cinematic overlay and optional CTAs.

XCardHeroSplit

Split-layout hero with image on one side, text on the other.

XCardMedia

Immersive media card with full-bleed image and text overlay.

XCardProduct

Product showcase with color swatches and image switching.

Events:

XCardFeature

Versatile feature card with icon, stat, or image variants.

XCardTestimonial

Story-driven testimonial with lifestyle imagery and serif quotes.

XCardTeam

Team member card with portrait and social links.

XCardPricing

Pricing tier card with feature list and optional highlighting.

XCardComparison

Feature comparison table with highlighted "ours" column.

XCardReview

Multi-source review card with star ratings.

XCardImageFilter

Filter showcase card with before/after hover effect.

XCardGrid

Responsive grid layout wrapper.

CSS Utilities

Image Filters

Gradient Overlays

Blur Panels

Typography

Button Variants

Card Animations

Surfaces & Gradients

Aspect Ratios

Image Prompt Templates

The prompts/ directory contains base photography descriptions for generating consistent imagery with AI image models (Nano Banana 2 or similar).

Each file includes camera simulation, lighting setup, color grading notes, a copy-paste base prompt, and variation modifiers.

Design System

Color Palettes

Cream (Primary)

Olive (Neutral)

Typography Scale

All line-heights are multiples of the 4px base grid:

WCAG Contrast Ratios

All text-on-surface combinations meet WCAG AA:

Demo Pages

Run the layer standalone to browse all demo pages:

pnpm dev

Routes: /, /hero-cards, /product-cards, /feature-cards, /media-cards, /testimonial-cards, /review-cards, /pricing-cards, /comparison-cards, /team-cards, /image-filters

Shared Types

All components import shared TypeScript types from app/types/x-cards.ts:

How It Works

The layer is structured as a standard Nuxt layer:

• nuxt.config.ts — Registers the global CSS file (xCards.css) which defines the custom color palettes (cream, olive), image filters, gradient overlays, typography scale, button variants, and animation utilities using Tailwind CSS v4's @theme static block.
• app/app.config.ts — Provides default design tokens under the x.cards namespace with type augmentation so consumers get autocomplete in their app.config.ts.
• app/composables/useXCards.ts — Auto-imported composable that deep-merges consumer overrides (from app.config.ts) with the layer defaults using defu. Components read their fallback filter, overlay, and aspect ratio values from this config.
• app/components/ — 12 auto-imported Vue components prefixed with XCard. Each component uses shared types from app/types/x-cards.ts and reads config defaults via useXCards().
• app/types/ — Centralized TypeScript types (FilterValue, OverlayValue, CtaProp, etc.) shared across all components to avoid duplication.

The CSS layer does not set body styles to avoid bleeding into consumer apps. Consumers should apply .bg-surface and .text-body classes (or their own styles) to their root layout.

Dependencies

• Nuxt 4 (^4.4.2)
• Nuxt UI v4 (^4.5.1)
• Tailwind CSS v4 (^4.2.1)
• Lucide Icons (@iconify-json/lucide)
• Simple Icons (@iconify-json/simple-icons)

License

MIT