@poupe/vue

Vue component library for Poupe UI framework with theme customization and accessibility support.

Features

• 🧩 Feature-rich Vue 3 component library
• 🎨 Built-in theme customization with Material Design 3
• ♿ Strong focus on accessibility
• 🌓 Dark/light mode theming
• 🔧 Fully typed with TypeScript
• 📱 Responsive design out of the box
• ✨ Interactive state layers (hover, focus, pressed, disabled)

Installation

1npm install @poupe/vue @poupe/theme-builder
2# or
3yarn add @poupe/vue @poupe/theme-builder
4# or
5pnpm add @poupe/vue @poupe/theme-builder

For TailwindCSS integration:

1npm install @poupe/tailwindcss

Basic Setup

1import { createApp } from 'vue'
2import { createPoupe } from '@poupe/vue'
3import App from './App.vue'
4
5// Create Vue app
6const app = createApp(App)
7
8// Setup Poupe with theme
9app.use(createPoupe({
10  theme: {
11    colors: {
12      primary: '#1976d2',
13      secondary: '#9c27b0',
14      // Add more colors as needed
15    }
16  },
17  // Optional: component-specific options
18  components: {
19    // Button specific options
20    button: {
21      defaultVariant: 'filled'
22    }
23  }
24}))
25
26app.mount('#app')

Using Components

1<template>
2  <div>
3    <PButton variant="filled" color="primary">Click Me</PButton>
4
5    <PCard>
6      <template #header>Card Header</template>
7      Card content goes here
8      <template #footer>Card Footer</template>
9    </PCard>
10
11    <PInput v-model="inputValue" label="Username" />
12
13    <PSurface color="primary" shape="lg" shadow="z2" padding="md">
14      Elevated surface content
15    </PSurface>
16  </div>
17</template>
18
19<script setup>
20import { ref } from 'vue'
21
22const inputValue = ref('')
23</script>

PCard Component

The PCard component is built on PSurface and provides a convenient way to create Material Design 3 cards:

1<template>
2  <!-- Simple card with title -->
3  <PCard title="Card Title">
4    This is the card content. It can contain any text or components.
5  </PCard>
6
7  <!-- Card with custom header and footer -->
8  <PCard>
9    <template #header>
10      <h3 class="text-xl font-medium">Custom Header</h3>
11    </template>
12    Main content area
13    <template #footer>
14      <div class="flex justify-end gap-2">
15        <PButton surface="base">Cancel</PButton>
16        <PButton surface="primary">Save</PButton>
17      </div>
18    </template>
19  </PCard>
20
21  <!-- Interactive card with primary container -->
22  <PCard container="primary" interactive>
23    Click me! I'm an interactive card.
24  </PCard>
25
26  <!-- Card with surface variants -->
27  <PCard surface="high" shadow="z3" shape="lg">
28    Elevated card with high emphasis
29  </PCard>
30</template>

Card props:

• title: Card title displayed in header
• surface: Convenience prop for surface colors (base, dim, bright, lowest, low, container, high, highest)
• container: Convenience prop for container colors (primary, secondary, tertiary, error)
  • Note: If both surface and container are specified, container takes precedence
• shape: Corner radius variant (xs, sm, md, lg, xl) - defaults to 'md'
• shadow: Elevation shadow (none, z1-z5) - defaults to 'z1'
• interactive: Enable hover/focus/pressed states
• All other PSurface props are supported

PSurface Component

The PSurface component provides Material Design 3 surface containers:

1<template>
2  <!-- Basic surface -->
3  <PSurface>Default surface</PSurface>
4
5  <!-- Interactive surface with elevation -->
6  <PSurface
7    color="secondary"
8    shadow="z3"
9    shape="xl"
10    padding="lg"
11    interactive
12  >
13    Interactive elevated content
14  </PSurface>
15
16  <!-- Container variant -->
17  <PSurface variant="container" color="high">
18    High emphasis container
19  </PSurface>
20</template>

Surface props:

• variant: 'surface' | 'container' - Surface type
• color: Surface color based on MD3 color system
• shape: Shape variant (none, xs, sm, md, lg, xl, rounded, full, squircle-xs, etc.) - uses Material Design 3 shape system where size-only variants are squircles
• shadow: Elevation shadow (none, z1-z5)
• border: Border style (none, primary, secondary, outline, etc.)
• interactive: Enable hover/focus/pressed states
• padding: Content padding (none, sm, md, lg, xl)

Composables

useRipple

Add Material Design ripple effects to any element:

1<template>
2  <button ref="buttonRef" class="ripple-effect">
3    Click me
4  </button>
5</template>
6
7<script setup>
8import { ref } from 'vue'
9import { useRipple } from '@poupe/vue'
10
11const buttonRef = ref()
12useRipple(buttonRef, {
13  color: 'currentColor',
14  opacity: 0.12,
15  duration: 600
16})
17</script>

The ripple effect requires the .ripple-effect utility class from @poupe/tailwindcss for the animation keyframes.

usePoupe

Access global configuration and component defaults:

1<script setup>
2import { usePoupe, usePoupeMergedProps } from '@poupe/vue'
3
4// Access global configuration
5const poupe = usePoupe()
6console.log(poupe?.theme?.dark) // true/false
7
8// Merge props with component and global defaults
9const mergedProps = usePoupeMergedProps(props, 'button', {
10  variant: 'text',
11  color: 'primary',
12  size: 'medium'
13})
14</script>

Configure global defaults via the Poupe plugin:

1app.use(createPoupe({
2  theme: { dark: true },
3  defaults: {
4    button: {
5      variant: 'filled',
6      color: 'primary'
7    }
8  }
9}))

Story Viewer

The package includes a built-in story viewer for component documentation:

1<template>
2  <StoryViewer :stories="stories" />
3</template>
4
5<script setup>
6import { StoryViewer } from '@poupe/vue/story-viewer'
7import buttonStories from './components/button.stories.vue'
8import cardStories from './components/card.stories.vue'
9
10const stories = [
11  { name: 'Button', component: buttonStories },
12  { name: 'Card', component: cardStories }
13]
14</script>

Development Tools

Screenshot Helpers

The package includes Playwright-based screenshot utilities for capturing component states:

Manual Screenshots

1# Start dev server first
2pnpm dev
3
4# In another terminal, take screenshots
5pnpm screenshot                           # Theme page
6pnpm screenshot button                    # Specific component
7pnpm screenshot theme theme-dark.png --dark     # Dark mode
8pnpm screenshot --all-viewports           # Multiple screen sizes

Automated Screenshots

For CI/CD or quick captures without managing the dev server:

1# Automatically starts dev server, takes screenshot, and cleans up
2pnpm screenshot:auto                      # Theme page
3pnpm screenshot:auto button --dark        # Button in dark mode
4pnpm screenshot:auto --all-viewports      # All viewport sizes

Options:

• --dark - Enable dark mode
• --mobile - Use mobile viewport
• --full-page - Capture full page
• --all-viewports - Capture mobile, tablet, and desktop sizes

All screenshots are saved in the gitignored screenshots/ directory.

Available Exports

• Main export: Core components and configuration
• config: Theme configuration utilities
• resolver: Component resolving for build tools
• story-viewer: Components viewer
• theme-scheme: Theme visualization component

Theme Scheme Component

The ThemeScheme component is exported separately as it's a specialized utility component for visualizing and debugging theme colors:

1// Import from the separate export
2import { ThemeScheme } from '@poupe/vue/theme-scheme'

This component displays all theme color schemes and is useful for:

• Visualizing your theme's color palette
• Debugging theme configurations
• Showcasing theme variations to stakeholders

TailwindCSS Integration

For optimal experience, integrate with TailwindCSS:

1// tailwind.config.js
2import { poupePlugin } from '@poupe/tailwindcss'
3
4export default {
5  // ...
6  plugins: [
7    poupePlugin()
8  ]
9}

Related Packages

• @poupe/css - CSS-in-JS utilities
• @poupe/theme-builder - Theme token generation
• @poupe/tailwindcss - TailwindCSS integration
• @poupe/nuxt - Nuxt integration

Requirements

• Vue ^3.5.13
• Node.js >=20.19.1
• @poupe/theme-builder ^0.7.0
• @poupe/tailwindcss ^0.2.6

License

MIT licensed.