### Build and View Examples

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/examples/index.html

Provides the command to build the @poupe/tailwindcss examples and instructions to view them in a web browser.

```Shell
pnpm run build
# Then open examples/index.html in browser
```

--------------------------------

### Install @poupe/theme-builder

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-theme-builder/README.md

Instructions for installing the `@poupe/theme-builder` package using npm, yarn, or pnpm as a development dependency.

```bash
# npm
npm install -D @poupe/theme-builder

# yarn
yarn add -D @poupe/theme-builder

# pnpm
pnpm add -D @poupe/theme-builder
```

--------------------------------

### Install @poupe/css Library

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Instructions for installing the @poupe/css utility library using popular Node.js package managers like npm, yarn, and pnpm. The `-D` flag indicates installation as a development dependency.

```bash
npm install -D @poupe/css
```

```bash
yarn add -D @poupe/css
```

```bash
pnpm add -D @poupe/css
```

--------------------------------

### Start Poupe Nuxt Module Development Playground

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-nuxt/AGENT.md

Provides instructions for navigating to the development playground directory and starting the Nuxt development server using pnpm, enabling local testing and development of the @poupe/nuxt module.

```bash
cd playground
pnpm dev  # Start playground dev server
```

--------------------------------

### Run CLI Validation Tests for TailwindCSS Plugins

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/examples/README.md

Command to execute the test suite, including CLI validation, for the `@poupe/tailwindcss` plugin examples. Tests use temporary files to avoid interfering with the example directory.

```bash
# From package root - runs all tests including CLI validation
pnpm test

# Tests use temporary files and don't interfere with examples/
```

--------------------------------

### Install Poupe Vue and TailwindCSS Integration

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-vue/README.md

Provides commands for installing the core `@poupe/vue` library along with `@poupe/theme-builder` using npm, yarn, or pnpm. It also includes the separate installation command for `@poupe/tailwindcss` for seamless integration with TailwindCSS.

```bash
npm install @poupe/vue @poupe/theme-builder
# or
yarn add @poupe/vue @poupe/theme-builder
# or
pnpm add @poupe/vue @poupe/theme-builder

npm install @poupe/tailwindcss
```

--------------------------------

### TailwindCSS Plugin Examples Directory Structure

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/examples/README.md

The flattened file structure of the `examples/` directory, detailing the purpose of each file, including documentation, unified HTML, various CSS input files for different plugin workflows, and configuration files.

```text
examples/
├── README.md                # This documentation
├── index.html               # Unified demo HTML with utility classes
├── input.css                # Default: imports src/assets/default.css
├── default-plugin.css       # @plugin workflow with dist/index.mjs
├── flat-plugin.css          # Flat plugin via config
├── theme-plugin.css         # Theme plugin via config
├── flat-plugin.config.js    # Config for flat plugin
├── theme-plugin.config.js   # Config for theme plugin
└── output.css               # Generated output (git-ignored)
```

--------------------------------

### Install Poupe Nuxt Module and Dependencies

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-nuxt/README.md

Instructions for installing the core Poupe packages required for the Nuxt module, including @poupe/nuxt, @poupe/vue, and @poupe/theme-builder, using common package managers.

```bash
npm install @poupe/nuxt @poupe/vue @poupe/theme-builder
# or
yarn add @poupe/nuxt @poupe/vue @poupe/theme-builder
# or
pnpm add @poupe/nuxt @poupe/vue @poupe/theme-builder
```

--------------------------------

### Basic Poupe Nuxt Module Setup in nuxt.config.ts

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-nuxt/README.md

Add the @poupe/nuxt module to your Nuxt configuration file. This snippet demonstrates the minimal setup and an example of configuring primary and secondary theme colors.

```typescript
export default defineNuxtConfig({
  modules: [
    '@poupe/nuxt'
  ],
  poupe: {
    // Configuration options
    theme: {
      colors: {
        primary: '#1976d2',
        secondary: '#9c27b0',
        // Add more colors as needed
      }
    }
  }
})
```

--------------------------------

### Development Commands for Poupe UI Monorepo

Source: https://github.com/poupe-ui/poupe/blob/main/README.md

Essential pnpm commands for managing the Poupe UI monorepo, including installing dependencies, building all packages, and running tests across the project.

```bash
pnpm install
```

```bash
pnpm -r build
```

```bash
pnpm -r test
```

--------------------------------

### Example: Setting Deep CSS Rules

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Provides examples of using `setDeepRule` for direct assignment, nested assignment, and merging with existing CSS rule objects, demonstrating how new values take precedence during merges.

```typescript
import { setDeepRule } from '@poupe/css';

const rules = {};

// Direct assignment
setDeepRule(rules, 'button', { color: 'blue' });
// Result: { button: { color: 'blue' } }

// Nested assignment
setDeepRule(rules, ['components', 'button'], { color: 'blue' });
// Result: { components: { button: { color: 'blue' } } }

// Merging with existing object (new values take precedence)
const existingRules = { button: { color: 'red', margin: '5px' } };
setDeepRule(existingRules, 'button', { color: 'blue', padding: '10px' });
// Result: { button: { color: 'blue', margin: '5px', padding: '10px' } }
```

--------------------------------

### Test TailwindCSS Plugin Workflows Manually

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/examples/README.md

Commands to manually test different `@poupe/tailwindcss` plugin integration workflows using `@tailwindcss/cli`. Each command targets a specific CSS input file to demonstrate asset import, direct plugin import, flat plugin via config, and theme plugin via config.

```bash
# Test default workflow (imports assets)
cd examples/
pnpx @tailwindcss/cli -i input.css -o output.css --content index.html

# Test @plugin workflow
pnpx @tailwindcss/cli -i default-plugin.css -o output.css --content index.html

# Test flat plugin via config
pnpx @tailwindcss/cli -i flat-plugin.css -o output.css --content index.html

# Test theme plugin via config
pnpx @tailwindcss/cli -i theme-plugin.css -o output.css --content index.html
```

--------------------------------

### Install @poupe/tailwindcss with npm, yarn, or pnpm

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/README.md

Instructions for installing the @poupe/tailwindcss plugin using different package managers (npm, yarn, pnpm) for TailwindCSS v4 projects.

```bash
# npm
npm install -D @poupe/tailwindcss tailwindcss@4

# yarn
yarn add -D @poupe/tailwindcss tailwindcss@4

# pnpm
pnpm add -D @poupe/tailwindcss tailwindcss@4
```

--------------------------------

### Using Poupe Vue Components in a Template

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-vue/README.md

Demonstrates how to incorporate various Poupe UI components, such as `PButton`, `PCard`, and `PInput`, directly within a Vue 3 template. The example also shows basic data binding using `v-model` and reactive state management with `ref` in a `<script setup>` block.

```vue
<template>
  <div>
    <PButton variant="filled" color="primary">Click Me</PButton>

    <PCard>
      <template #header>Card Header</template>
      Card content goes here
      <template #footer>Card Footer</template>
    </PCard>

    <PInput v-model="inputValue" label="Username" />
  </div>
</template>

<script setup>
import { ref } from 'vue'

const inputValue = ref('')
</script>
```

--------------------------------

### Example: Using defaultValidCSSRule for Custom Validation

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Demonstrates how `defaultValidCSSRule` can be integrated into a custom validation function to extend its logic, for example, to exclude rules starting with an underscore.

```typescript
import { defaultValidCSSRule } from '@poupe/css';

// Use with custom rule validation
const customValid = (key, value) => {
  return defaultValidCSSRule(key, value) && !key.startsWith('_');
};
```

--------------------------------

### Install Poupe UI for Vue Applications

Source: https://github.com/poupe-ui/poupe/blob/main/README.md

Installs the necessary packages for integrating Poupe UI into a Vue 3 application, including the Vue component library, theme builder, and TailwindCSS.

```bash
npm install @poupe/vue @poupe/theme-builder tailwindcss
```

--------------------------------

### TypeScript Example: Converting Strings to Kebab-Case

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Illustrates the usage of the `kebabCase` function from `@poupe/css` to convert different string formats, such as camelCase, snake_case, and PascalCase, into kebab-case. It also shows how vendor prefixes are handled correctly, demonstrating its versatility.

```typescript
import { kebabCase } from '@poupe/css';

kebabCase('XMLHttpRequest'); // 'xml-http-request'
kebabCase('camelCase');      // 'camel-case'
kebabCase('snake_case');     // 'snake-case'
kebabCase('WebkitTransition'); // '-webkit-transition'
```

--------------------------------

### Execute Common Development Commands for Poupe Packages

Source: https://github.com/poupe-ui/poupe/blob/main/AGENT.md

Provides essential pnpm commands for development workflows across all packages, including starting development mode, building, testing, and cleaning project artifacts. These commands are crucial for local development and ensuring code functionality.

```bash
pnpm dev          # Start development mode (watch for changes)
pnpm build        # Build the package
pnpm test         # Run tests (watch mode in most packages)
pnpm clean        # Remove dist/ and node_modules/
```

--------------------------------

### Install and Configure Poupe UI for Nuxt Applications

Source: https://github.com/poupe-ui/poupe/blob/main/README.md

Installs the Poupe UI Nuxt module and configures it in `nuxt.config.ts` to enable seamless integration with Nuxt applications.

```bash
npm install @poupe/nuxt
```

```typescript
export default defineNuxtConfig({
  modules: ['@poupe/nuxt'],
})
```

--------------------------------

### Initialize Poupe UI with Vue Application

Source: https://github.com/poupe-ui/poupe/blob/main/README.md

Shows how to integrate and initialize Poupe UI within a Vue 3 application, applying a custom theme during the `createPoupe` setup.

```typescript
import { createApp } from 'vue'
import { createPoupe } from '@poupe/vue'
import App from './App.vue'

const app = createApp(App)

app.use(createPoupe({
  theme: {
    colors: {
      primary: '#1976d2',
      secondary: '#9c27b0',
    },
  },
}))

app.mount('#app')
```

--------------------------------

### Install and Configure Poupe UI for TailwindCSS Only

Source: https://github.com/poupe-ui/poupe/blob/main/README.md

Installs the Poupe UI TailwindCSS plugin and theme builder, then configures the plugin in `tailwind.config.js` for native TailwindCSS v4 support with theme customization.

```bash
npm install @poupe/tailwindcss @poupe/theme-builder
```

```javascript
import { poupePlugin } from '@poupe/tailwindcss'

export default {
  // ...
  plugins: [
    poupePlugin({
      // your theme configuration
    }),
  ],
}
```

--------------------------------

### TypeScript Example: Processing and Expanding CSS Selectors

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Demonstrates the `processCSSSelectors` and `expandSelectorAlias` functions for handling CSS selectors. It illustrates theme-aware processing, custom alias definitions for responsive design, and individual alias expansion, providing powerful tools for dynamic CSS management.

```typescript
import { processCSSSelectors, expandSelectorAlias } from '@poupe/css';

// Theme-aware selector processing
const darkModeSelectors = processCSSSelectors(['.dark', 'media']);
// Result: ['.dark, .dark *', '@media (prefers-color-scheme: dark)']

// Custom aliases for responsive design
const customAliases = {
  'wide': '@media (min-width: 1440px)',
  'touch': '@media (hover: none) and (pointer: coarse)'
};

const responsiveSelectors = processCSSSelectors(
  ['mobile', 'wide'],
  { aliases: customAliases }
);
// Result: ['@media (max-width: 768px)', '@media (min-width: 1440px)']

// Expand individual aliases
expandSelectorAlias('tablet');
// '@media (min-width: 769px) and (max-width: 1024px)'
```

--------------------------------

### Apply elevation shadows with TailwindCSS classes

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/README.md

HTML examples demonstrating the application of different elevation shadow levels (z1-z5) and an inset shadow using provided TailwindCSS utility classes.

```html
<div class="shadow-z1">Level 1</div>
<div class="shadow-z2">Level 2 (default)</div>
<div class="shadow-z3">Level 3</div>
<div class="shadow-z4">Level 4</div>
<div class="shadow-z5">Level 5</div>
<div class="inset-shadow">Inset Shadow</div>
```

--------------------------------

### Package Structure Overview for @poupe/tailwindcss

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/AGENT.md

Illustrates the directory and file organization of the @poupe/tailwindcss package. It details the source code layout including tests, assets, flat and theme plugin APIs, utilities, and main exports. It also shows examples of different plugin workflows.

```text
src/
├── __tests__/        # Unit and CLI integration tests
├── assets/           # Pre-built CSS files
│   ├── style.css     # Minimal setup without theme
│   └── default.css   # Complete example with defaults
├── flat/             # Flat plugin API
├── theme/            # Theme generation and utilities
│   ├── match-utilities.ts  # v4-to-v3 bridge for dynamic utilities
│   └── ...
├── utils/            # Builder and helper utilities
└── index.ts          # Main exports

examples/
├── plugin-workflow/     # @plugin syntax example
│   ├── package.json     # Stand-alone project config
│   ├── default-plugin.css  # Uses @plugin directive
│   ├── index.html       # Demo with utility classes
│   └── output.css       # Generated (auto-created by build)
├── flat-plugin/         # Default export usage example
│   ├── package.json     # Stand-alone project config
│   ├── flat-plugin.config.js
│   ├── flat-plugin.css  # Uses @config directive
│   ├── index.html       # Demo with utility classes
│   └── output.css       # Generated (auto-created by build)
└── theme-plugin/        # Named export usage example
    ├── package.json     # Stand-alone project config
    ├── theme-plugin.config.js
    ├── theme-plugin.css # Uses @config directive
    ├── index.html       # Demo with utility classes
    └── output.css       # Generated (auto-created by build)
```

--------------------------------

### Manipulate Colors with HCT and Utilities

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-theme-builder/README.md

Provides examples of advanced color manipulation using the HCT color space (Hue, Chroma, Tone), `colord` utilities for HSL/Hex conversions and lightening, `hexString` for formatting, and `makeTonalPalette` for creating cohesive color palettes, including harmonization.

```typescript
import {
  hct, colord, hexString, makeTonalPalette
} from '@poupe/theme-builder/core'

// HCT color space (Hue, Chroma, Tone)
const color = hct('#1976d2')
const lighter = color.withTone(80)   // Lighter variant
const muted = color.withChroma(30)   // Lower saturation

// Advanced color utilities
const c = colord('#1976d2')
console.log(c.toHsl())               // HSL representation
console.log(c.lighten(0.2).toHex())  // Lightened color

// Format colors
console.log(hexString(lighter))      // Convert to hex string

// Create tonal palette with full tone range (0-100)
const palette = makeTonalPalette('#1976d2')
console.log(palette.tone(50))        // Medium tone
console.log(palette.tone(90))        // Light tone
console.log(palette.tone(10))        // Dark tone

// Harmonize colors to create cohesive palettes
const primary = hct('#1976d2')
const harmonized = makeTonalPalette('#9c27b0', primary)
```

--------------------------------

### TypeScript Example: Interconverting Kebab-Case and CamelCase

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Provides a practical example of using `kebabCase` and `camelCase` functions together to convert between CSS property names (kebab-case) and JavaScript object property names (camelCase). It shows how to transform a style object into an array of CSS property strings, useful for dynamic styling.

```typescript
import { kebabCase, camelCase } from '@poupe/css';

// Kebab-case to camelCase
const camelProperty = camelCase('background-color'); // 'backgroundColor'

// CamelCase to kebab-case
const kebabProperty = kebabCase('backgroundColor'); // 'background-color'

// Useful for converting between CSS and JavaScript property names
const styleObject = {
  backgroundColor: 'red',
  fontSize: '16px'
};

// Convert to CSS properties
const cssProperties = Object.entries(styleObject).map(
  ([key, value]) => `${kebabCase(key)}: ${value};`
);
// ['background-color: red;', 'font-size: 16px;']
```

--------------------------------

### Example: Streaming CSS Rules from an Array

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Shows how to use `generateCSSRulesArray` to stream CSS lines from a large array of rules, demonstrating its memory efficiency by processing lines one by one.

```typescript
import { generateCSSRulesArray } from '@poupe/css';

const rulesArray = [
  { 'color': 'red' },
  '',  // Empty string creates blank line
  { 'font-size': '16px' }
];

// Stream through large rule arrays
for (const line of generateCSSRulesArray(rulesArray)) {
  process.stdout.write(line + '\n');
}
```

--------------------------------

### Importing and Using Server-Side CSS Utilities

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-theme-builder/README.md

This section illustrates importing server-side utilities from `@poupe/theme-builder/server` for color parameter processing and CSS stringification. It provides examples of converting CSS rule arrays into plain strings, normalized strings, ReadableStreams, and direct Response objects, including streaming responses for large files.

```typescript
import {
  // Parameter processing
  getColorParam,
  getThemeSchemeParam,

  // CSS formatting utilities
  stringifyCSSRulesArray,
  stringifyCSSRulesArrayStream,
  stringifyCSSRulesArrayAsStream,
  stringifyCSSRulesArrayAsResponse,
  stringifyCSSRulesArrayAsStreamingResponse,

  // Color types (re-exported)
  type HexColor,
  hct,
  colord,
} from '@poupe/theme-builder/server'

// Convert to CSS string (no trailing newline)
const cssString = stringifyCSSRulesArray([
  { '.theme': { '--primary': '#6750A4' } }
])

// Convert with camelCase to kebab-case normalization
const normalizedCSS = stringifyCSSRulesArray([
  { fontSize: '16px', backgroundColor: 'blue' }
], { normalizeProperties: true })
// Result: 'font-size: 16px;\nbackground-color: blue;'

// Create ReadableStream (perfect for Cloudflare Workers)
const stream = stringifyCSSRulesArrayAsStream([
  { '.theme': { '--primary': '#6750A4' } }
])
const response = new Response(stream, {
  headers: { 'Content-Type': 'text/css' }
})

// Create Response object with headers
const response = stringifyCSSRulesArrayAsResponse([
  { '.theme': { '--primary': '#6750A4' } }
])

// Create streaming Response for large CSS files
const streamingResponse = stringifyCSSRulesArrayAsStreamingResponse([
  // Large array of CSS rules
])
```

--------------------------------

### Example: Using generateCSSRules for CSS Generation

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Demonstrates how to use `generateCSSRules` to generate CSS lines from a rule object. It shows both iterating through the generator and collecting all lines into an array.

```typescript
import { generateCSSRules } from '@poupe/css';

const rules = {
  'body': {
    'color': 'red',
    'font-size': '16px'
  }
};

// Use generator for streaming or large files
for (const line of generateCSSRules(rules)) {
  console.log(line);
}
// Output:
// body {
//   color: red;
//   font-size: 16px;
// }

// Or collect all lines (same as formatCSSRules)
const lines = [...generateCSSRules(rules)];
```

--------------------------------

### Basic Poupe Vue Application Setup with Custom Theme

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-vue/README.md

Illustrates the fundamental steps to integrate `@poupe/vue` into a Vue 3 application. This snippet demonstrates how to initialize the Poupe plugin with a custom theme configuration, including color palettes and component-specific default options, before mounting the Vue app.

```typescript
import { createApp } from 'vue'
import { createPoupe } from '@poupe/vue'
import App from './App.vue'

// Create Vue app
const app = createApp(App)

// Setup Poupe with theme
app.use(createPoupe({
  theme: {
    colors: {
      primary: '#1976d2',
      secondary: '#9c27b0',
      // Add more colors as needed
    }
  },
  // Optional: component-specific options
  components: {
    // Button specific options
    button: {
      defaultVariant: 'filled'
    }
  }
}))

app.mount('#app')
```

--------------------------------

### Poupe UI TailwindCSS Plugin Build and Test Commands

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/AGENT.md

Commands to build the Poupe UI TailwindCSS plugin, generate assets, and run tests. The `pnpm build` command creates the main plugin, CSS assets, and example CSS files. The `pnpm test` command runs all tests, including CLI integration tests.

```bash
# Full build - generates plugin, assets, and examples
pnpm build

# This creates:
# - dist/index.mjs (main plugin)
# - src/assets/*.css (theme files)
# - examples/*/output.css (example CSS)

# Run all tests
pnpm test

# Run only CLI tests
pnpm test cli.test.ts
```

--------------------------------

### TypeScript Example: Converting Strings to CamelCase

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Demonstrates the `camelCase` function from `@poupe/css` for converting strings from kebab-case, PascalCase, and snake_case to camelCase. It also highlights its ability to handle vendor prefixes and preserve acronym capitalization, making it robust for various naming conventions.

```typescript
import { camelCase } from '@poupe/css';

camelCase('kebab-case');      // 'kebabCase'
camelCase('PascalCase');      // 'pascalCase'
camelCase('snake_case');      // 'snakeCase'
camelCase('-webkit-transition'); // 'webkitTransition'
camelCase('HTMLElement');     // 'htmlElement'
camelCase('BGColor');         // 'bgColor'
```

--------------------------------

### Using Built-in Aliases for Responsive Theming

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-theme-builder/README.md

This example demonstrates how to leverage the built-in selector aliases like 'dark', 'light', 'mobile', 'tablet', and 'desktop' with `makeCSSTheme` for responsive theming. It shows combining 'dark' with 'tablet' and 'light' with 'desktop' to apply themes based on both color scheme preference and screen size.

```typescript
// Using aliases for responsive theming
const cssTheme = makeCSSTheme(colors, {
  darkMode: ['dark', 'tablet'],    // Dark mode + tablet screens
  lightMode: ['light', 'desktop'], // Light mode + desktop screens
})
```

--------------------------------

### Example: Formatting an Array of CSS Rules

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Illustrates how to use `formatCSSRulesArray` to convert an array of mixed CSS rule types (objects, strings, media queries) into properly indented CSS lines.

```typescript
import { formatCSSRulesArray } from '@poupe/css';

const rulesArray = [
  { 'color': 'red' },
  { 'font-size': '16px' },
  'font-weight: bold',
  {
    '@media (max-width: 768px)': {
      'font-size': '14px'
    }
  }
];

const lines = formatCSSRulesArray(rulesArray);
// Returns lines with proper indentation for each rule
```

--------------------------------

### Using Poupe UI Components in Nuxt Templates

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-nuxt/README.md

Example demonstrating how to integrate and use auto-imported Poupe components, such as PButton and PCard, directly within a Nuxt application's Vue template.

```vue
<template>
  <div>
    <PButton>Click me</PButton>
    <PCard>
      <h2>Card Title</h2>
      <p>Card content</p>
    </PCard>
  </div>
</template>
```

--------------------------------

### Generating CSS Custom Properties with makeCSSTheme

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-theme-builder/README.md

This example demonstrates using `makeCSSTheme` to automatically generate CSS custom properties from a color palette. It shows how to configure variable prefixes, dark/light mode selectors, and suffixes, and how to access the generated variable names and CSS rule objects.

```typescript
const cssTheme = makeCSSTheme({
  primary: '#6750A4',
}, {
  prefix: 'md-',         // Variable prefix
  darkMode: '.dark',     // Dark mode selector
  lightMode: '.light',   // Light mode selector (optional)
  darkSuffix: '-dark',   // Dark variable suffix
  lightSuffix: '-light', // Light variable suffix
})

// Generated variables
cssTheme.vars.primary            // '--md-primary'
cssTheme.vars.onPrimary          // '--md-on-primary'
cssTheme.styles                  // CSS rule objects
```

--------------------------------

### Example: Interleaving CSS Rule Objects for Spacing

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Shows how `interleavedRules` can be used to insert empty objects between CSS rule blocks, which translates to empty lines when the rules are formatted into a string.

```typescript
import { interleavedRules } from '@poupe/css';

const rules = [
  { '.button': { color: 'blue' } },
  { '.input': { border: '1px solid gray' } }
];

const spacedRules = interleavedRules(rules);
// Returns:
// [
//   { '.button': { color: 'blue' } },
//   {}, // Empty object for spacing
//   { '.input': { border: '1px solid gray' } }
// ]

// When stringified, this creates an empty line between rule blocks
```

--------------------------------

### Example: Renaming CSS Rule Selectors

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Illustrates various use cases for `renameRules`, including adding prefixes to selectors, transforming selectors into utility classes, and conditionally filtering rules by returning a falsy value from the renaming function.

```typescript
import { renameRules } from '@poupe/css';

const rules = {
  '.button': { color: 'blue' },
  '.input': { border: '1px solid gray' }
};

// Add a prefix to all selectors
const prefixedRules = renameRules(rules, key => `.prefix ${key}`);
// Returns:
// {
//   '.prefix .button': { color: 'blue' },
//   '.prefix .input': { border: '1px solid gray' }
// }

// Transform selectors to utility classes
const utilityRules = renameRules(rules, key => `@utility ${key.slice(1)}`);
// Returns:
// {
//   '@utility button': { color: 'blue' },
//   '@utility input': { border: '1px solid gray' }
// }

// Return falsy from the function to skip/remove a rule
const filteredRules = renameRules(rules, key =>
  key.includes('button') ? key : null);
// Returns:
// {
//   '.button': { color: 'blue' }
// }
```

--------------------------------

### Configuring Dark Mode with makeCSSTheme Selectors

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-theme-builder/README.md

This snippet illustrates the flexible dark mode support provided by `makeCSSTheme`, allowing various configurations for dark mode selectors. It covers class-based, media query, multiple selector, built-in responsive alias, custom selector, and disabled dark mode setups.

```typescript
// Class-based dark mode (default)
makeCSSTheme(colors, { darkMode: '.dark' })

// Media query dark mode using built-in alias
makeCSSTheme(colors, { darkMode: 'media' })

// Multiple selectors
makeCSSTheme(colors, { darkMode: ['.dark', '.theme-dark'] })

// Built-in responsive aliases
makeCSSTheme(colors, {
  darkMode: ['dark', 'mobile'],  // Uses media queries
  lightMode: 'light'
})

// Custom selectors
makeCSSTheme(colors, {
  darkMode: '[data-theme="dark"]',
  lightMode: '[data-theme="light"]'
})

// Disable dark mode
makeCSSTheme(colors, { darkMode: false })
```

--------------------------------

### APIDOC: defaultValidPair Function for Key-Value Validation

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Documents the `defaultValidPair` function, which defines the default criteria for validating a key-value pair. It checks for non-null/undefined values, absence of spaces in keys, and keys not starting with an underscore, ensuring data integrity.

```APIDOC
`defaultValidPair<K extends string, T>(key: K, value: T): boolean`

Validates if a key-value pair meets default criteria:
- The value is neither null nor undefined
- The key doesn't contain spaces
- The key doesn't start with an underscore (_)
```

--------------------------------

### Configure Poupe UI TailwindCSS Plugins

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/README.md

This snippet provides examples of configuration options for `themePlugin()` and `flatPlugin()` in Poupe UI. It demonstrates how to set theme prefixes, surface prefixes, dark mode suffixes, color shades, and define primary, secondary, and neutral colors, including options for direct color definition and harmonization.

```typescript
{
  themePrefix: 'md-',
  surfacePrefix: 'surface-',
  omitTheme: false,
  darkSuffix: '',
  shades: [50,100,200,300,400,500,600,700,800,900],
  colors: { primary: { value: '#6750A4' } }
}
```

```typescript
{
  themePrefix: 'md-',
  surfacePrefix: 'surface-',
  primary: '#6750A4',              // Direct color definition
  secondary: ['#958DA5', false],   // [color, harmonize]
  neutral: [50, 100, 200, 500]     // Custom shades
}
```

--------------------------------

### CSS Material Design Color System Variables

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/README.md

Shows example CSS custom properties for Material Design colors, including primary color and its automatically generated shade variants (50, 500, 900).

```css
:root {
  --md-primary: 103, 80, 164;
  --md-primary-50: 244, 242, 250;
  --md-primary-500: 103, 80, 164;
  --md-primary-900: 30, 27, 38;
}
```

--------------------------------

### Poupe UI TailwindCSS Plugin Configuration

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/AGENT.md

Example configuration for integrating the Poupe UI TailwindCSS plugin into a TailwindCSS project. It demonstrates how to import and use the `poupePlugin` within `tailwind.config.js`, with optional parameters for utility prefixing, custom color overrides, and surface utility generation.

```js
// tailwind.config.js
import { poupePlugin } from '@poupe/tailwindcss'

export default {
  plugins: [
    poupePlugin({
      // Optional configuration
      prefix: 'p-',        // Prefix for utilities
      colors: {...},       // Custom color overrides
      generateSurfaces: true  // Generate surface utilities
    })
  ]
}
```

--------------------------------

### Apply Material Design 3 Surface Colors in HTML

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/README.md

This snippet demonstrates the application of Material Design 3 surface component utilities in HTML. It showcases various `surface-` classes for different background and text color combinations, ensuring proper contrast. Examples include primary, secondary, and container surfaces, as well as fixed color combinations.

```html
<div class="surface-primary">Primary Surface</div>
<div class="surface-secondary">Secondary Surface</div>
<div class="surface-secondary-container">Secondary Container</div>

<div class="surface-container-lowest">Lowest</div>
<div class="surface-container-low">Low</div>
<div class="surface-container">Standard</div>
<div class="surface-container-high">High</div>
<div class="surface-container-highest">Highest</div>

<!-- Fixed color combinations -->
<div class="surface-primary-fixed">Fixed background with on-fixed text</div>
<div class="surface-primary-fixed-variant">Fixed background with variant text</div>
<div class="surface-primary-fixed-dim">Dim fixed background with on-fixed text</div>
<div class="surface-primary-fixed-dim-variant">Dim fixed with variant text</div>
```

--------------------------------

### TypeScript Example: Iterating Object Pairs with `pairs` Function

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

Demonstrates how to use the `pairs` function from `@poupe/css` to iterate over object key-value pairs. It shows both default validation, which excludes private and empty values, and custom validation for specific string length criteria, providing flexibility in data filtering.

```typescript
import { pairs } from '@poupe/css';

const obj = { color: 'red', fontSize: '16px', _private: 'hidden', empty: '' };

// Use with default validation (excludes keys starting with underscore and
// null/empty values)
for (const [key, value] of pairs(obj)) {
  console.log(`${key}: ${value}`); // "color: red", "fontSize: 16px"
}

// Use with custom validation
const customValid = (key: string, value: unknown) =>
  typeof value === 'string' && value.length > 3;
for (const [key, value] of pairs(obj, customValid)) {
  console.log(`${key}: ${value}`); // "color: red", "_private: hidden"
}
```

--------------------------------

### Configure Dark Mode for Poupe UI

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/README.md

This snippet illustrates how to enable and customize dark mode in Poupe UI. It shows the default HTML class for activating dark mode and provides a TypeScript example for configuring the `themePlugin` to change the dark mode strategy, such as using media queries or a custom dark selector.

```html
<html class="dark"><!-- Dark mode active --></html>
```

```typescript
themePlugin({
  darkMode: 'class',        // Default: .dark class
  // darkMode: 'media',     // Use @media (prefers-color-scheme)
  // darkSuffix: '-dark',   // Custom dark selector
})
```

--------------------------------

### Poupe UI Package Release Commands

Source: https://github.com/poupe-ui/poupe/blob/main/AGENT.md

Command-line steps for preparing a package for release, including running prepack scripts, building, and publishing to npm, as part of the `poupe-ui` monorepo's release process.

```Shell
pnpm prepack
```

```Shell
pnpm build
```

```Shell
pnpm publish
```

--------------------------------

### Run @poupe/vue Preview Application

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-vue/AGENT.md

This command allows developers to preview the built application for the @poupe/vue package. It is a unique command specific to this package, facilitating quick local testing and visualization of components.

```bash
pnpm preview      # Preview built application (unique to @poupe/vue)
```

--------------------------------

### Running Development and Build Commands for Poupe UI

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-vue/AGENT.md

This snippet provides common `pnpm` commands for developing, testing, and building the Poupe UI project. It includes commands for hot-reloading development, running tests, and verifying production builds.

```Shell
pnpm dev
pnpm test
pnpm build
```

--------------------------------

### Directory Structure of @poupe/css Package

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/AGENT.md

Illustrates the file and directory organization within the @poupe/css package, showing the location of source files, unit tests, and main exports. This structure ensures modularity and maintainability.

```text
src/
├── __tests__/        # Unit tests
│   ├── properties.test.ts
│   ├── rules.test.ts
│   ├── selectors.test.ts
│   └── utils.test.ts
├── index.ts          # Main exports
├── properties.ts     # CSS property utilities
├── rules.ts          # CSS rules formatting
├── selectors.ts      # CSS selector processing
└── utils.ts          # Utility functions
```

--------------------------------

### Package Structure of @poupe/theme-builder

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-theme-builder/AGENT.md

This snippet illustrates the directory structure of the @poupe/theme-builder package, detailing the organization of core logic, CSS utilities, server-side components, and theme-specific files.

```text
src/
├── core/             # Core theme generation logic
│   ├── __tests__/   # Core tests
│   ├── colors.ts    # Color utilities
│   ├── palettes.ts  # Palette generation
│   └── utils.ts     # Core utilities
├── css/              # CSS generation utilities
│   └── css.ts       # CSS output formatting
├── server/           # Server-side utilities
│   ├── index.ts     # Server exports
│   └── utils.ts     # Server utilities
├── theme/            # Theme system
│   ├── colors.ts    # Theme colors
│   ├── data.ts      # Theme data structures
│   ├── palettes.ts  # Theme palettes
│   └── theme.ts     # Main theme logic
├── from-image.ts    # Image color extraction
└── index.ts         # Main exports
```

--------------------------------

### Capturing Manual Screenshots with Poupe Playwright Helpers

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-vue/README.md

Provides command-line instructions for taking manual screenshots of Poupe components or the theme page using Playwright-based utilities. This method requires the development server to be running and supports options like specific components, dark mode, and capturing all viewport sizes.

```bash
# Start dev server first
pnpm dev

# In another terminal, take screenshots
pnpm screenshot                           # Theme page
pnpm screenshot button                    # Specific component
pnpm screenshot theme theme-dark.png --dark     # Dark mode
pnpm screenshot --all-viewports           # Multiple screen sizes
```

--------------------------------

### Understand @poupe/vue Package Directory Structure

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-vue/AGENT.md

This snippet outlines the directory structure of the @poupe/vue package. It details the organization of source files, including test directories, assets, components, composables, utilities, and main entry points, providing a clear overview of the project layout.

```text
src/
├── __tests__/        # Package-level tests (resolver, etc.)
├── assets/           # CSS assets
│   └── css/         # Main CSS imports
├── components/       # Vue components
│   ├── __tests__/   # Component tests (colocated)
│   ├── input/       # Complex component modules
│   ├── theme/       # Theme-related components
│   │   └── scheme/  # Color scheme components
│   └── variants/    # Variant utility system
├── composables/      # Vue composables (use-*.ts)
├── utils/            # Utility functions
├── app.vue          # Demo application component
├── config.ts        # TailwindCSS config exports
├── index.ts         # Main library exports
├── main.ts          # Demo app entry point
└── resolver.ts      # Component auto-import resolver
```

--------------------------------

### Debugging Commands for Poupe UI Monorepo

Source: https://github.com/poupe-ui/poupe/blob/main/AGENT.md

Essential command-line instructions for diagnosing and resolving common development issues such as build failures, test errors, dependency conflicts, and ESLint problems in the `poupe-ui` monorepo.

```Shell
pnpm clean
pnpm build
```

```Shell
pnpm test --reporter=verbose
```

```Shell
pnpm list
```

```Shell
DEBUG=eslint:eslint pnpm lint
```

--------------------------------

### API Overview: Server Module (@poupe/theme-builder/server)

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-theme-builder/AGENT.md

This section details the server-side utilities offered by @poupe/theme-builder/server, including server-side theme generation, image color extraction, theme caching, and various CSS formatting functions for different output needs, supporting options like property normalization and streaming.

```APIDOC
Server Module (`@poupe/theme-builder/server`)
- Server-side theme generation
- Image color extraction
- Theme caching utilities
- CSS formatting utilities
  - `stringifyCSSRulesArray`: String format (no trailing newline, optional property normalization)
  - `stringifyCSSRulesArrayStream`: Async generator for streaming
  - `stringifyCSSRulesArrayAsStream`: ReadableStream for edge environments
  - `stringifyCSSRulesArrayAsResponse`: Response object creation
  - `stringifyCSSRulesArrayAsStreamingResponse`: Streaming Response with ReadableStream
  - All functions support `normalizeProperties` option for camelCase to kebab-case conversion
```

--------------------------------

### Core API Utilities and Performance Patterns in @poupe/css

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/AGENT.md

Comprehensive overview of the primary utility categories exported by the @poupe/css package, alongside a detailed explanation of performance considerations for array-based versus generator-based implementations, highlighting their respective use cases and benefits for CSS generation.

```APIDOC
@poupe/css API Utilities:
- CSS property manipulation and formatting
- CSS rules and nested object formatting
- CSS selector processing and expansion
- CSS unit conversions and calculations
- Case conversion (camelCase ↔ kebab-case)
- Type-safe CSS value handling
- Property name normalization (camelCase to kebab-case) with intelligent preservation of selectors and at-rules

Performance Implementations:
- Array functions (e.g., formatCSSRules, formatCSSRulesArray):
    - Purpose: Convenient for small to medium CSS.
    - Output: Returns complete arrays.
    - Use Case: Good for immediate consumption.
- Generator functions (e.g., generateCSSRules, generateCSSRulesArray):
    - Purpose: Memory-efficient for large CSS generation.
    - Output: Lazy evaluation, yields lines as generated.
    - Use Case: Ideal for streaming or writing large CSS files.
Note: Both implementations produce identical output; array functions use generators internally.
```

--------------------------------

### Poupe UI Framework Monorepo Directory Structure

Source: https://github.com/poupe-ui/poupe/blob/main/AGENT.md

Illustrates the hierarchical organization of the Poupe UI Framework monorepo, detailing the location of packages, scripts, and configuration files. This structure helps AI assistants understand the project layout and navigate between different modules.

```text
poupe/
├── packages/
│   ├── @poupe-css/           # CSS utilities library
│   ├── @poupe-nuxt/          # Nuxt module
│   │   └── playground/       # Nuxt development playground
│   ├── @poupe-tailwindcss/   # TailwindCSS v4 plugin
│   ├── @poupe-theme-builder/ # Theme token generation
│   └── @poupe-vue/           # Vue 3 components
├── scripts/                  # Build and utility scripts
├── test/                     # Root-level test utilities
├── pnpm-workspace.yaml       # Workspace configuration
└── vitest.workspace.ts       # Test configuration
```

--------------------------------

### Automating Screenshots for CI/CD with Poupe Playwright Helpers

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-vue/README.md

Details commands for automating screenshot capture, ideal for CI/CD environments. This utility automatically manages the development server lifecycle, takes the desired screenshot, and cleans up, offering options for dark mode and capturing across all viewport sizes.

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

--------------------------------

### HTML Scrim Backdrop Overlays

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/README.md

Demonstrates various HTML `div` elements using `scrim` utility classes for modal backdrops, drawers, and high-priority overlays, including opacity modifiers and arbitrary z-index values.

```html
<!-- Semantic z-index levels -->
<div class="scrim-modal">Modal backdrop</div>
<div class="scrim-drawer">Drawer backdrop</div>
<div class="scrim-elevated">High priority overlay</div>

<!-- With opacity modifiers -->
<div class="scrim-modal/50">Modal with 50% opacity</div>
<div class="scrim-drawer/75">Drawer with 75% opacity</div>
<div class="scrim-content/25">Content overlay with 25% opacity</div>

<!-- Arbitrary z-index values with opacity -->
<div class="scrim-[1250]">Custom z-index</div>
<div class="scrim-[1250]/40">Custom z-index with 40% opacity</div>
<div class="scrim-[var(--custom-z)]/60">CSS variable with 60% opacity</div>
```

--------------------------------

### Running Poupe UI Screenshot Helper Commands

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-vue/AGENT.md

This snippet lists the primary `pnpm` commands for generating screenshots of Poupe UI components. It includes commands for both manual and automated screenshot capture.

```Shell
pnpm screenshot
pnpm screenshot:auto
```

--------------------------------

### Create a Custom Poupe UI Theme

Source: https://github.com/poupe-ui/poupe/blob/main/README.md

Demonstrates how to create a custom theme using `@poupe/theme-builder`, allowing definition of custom colors and other design tokens.

```typescript
import { createTheme } from '@poupe/theme-builder'

const theme = createTheme({
  // Define your theme
  colors: {
    primary: '#1976d2',
    secondary: '#9c27b0',
    // Add more colors as needed
  },
})
```

--------------------------------

### Get Object Keys (Unsafe): unsafeKeys (TypeScript)

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-css/README.md

The `unsafeKeys` function provides a type-safe wrapper around JavaScript's `Object.keys` method. It is designed to preserve the object's key types, returning an array of all keys present in the given object.

```APIDOC
unsafeKeys<T>(object: T): Array<keyof T>

A type-safe wrapper around Object.keys for preserving the object's key types.
```

--------------------------------

### Execute Monorepo Root-Level Commands

Source: https://github.com/poupe-ui/poupe/blob/main/AGENT.md

Defines pnpm commands that operate across all packages from the monorepo root, enabling bulk build, clean, and lint operations. These commands streamline monorepo-wide maintenance tasks.

```bash
pnpm build        # Build all packages
pnpm clean        # Clean all packages
pnpm lint         # Lint all packages
```

--------------------------------

### Import minimal theme-agnostic utilities from @poupe/tailwindcss/style.css

Source: https://github.com/poupe-ui/poupe/blob/main/packages/@poupe-tailwindcss/README.md

Import `style.css` for minimal theme-agnostic utilities including surface components, shadow system, scrim overlays, and Material Design z-index system, without predefined color values.

```css
/* Import together with TailwindCSS base */
@import 'tailwindcss';
@import '@poupe/tailwindcss';  /* or '@poupe/tailwindcss/style.css' */
```