### Quick Start: Button Component (TSX)

Source: https://github.com/lucasols/vindur/blob/main/README.md

A basic example demonstrating how to create a styled button component using Vindur's `styled` API. It shows the TSX code and the resulting compiled CSS and JSX.

```tsx
import { styled } from 'vindur';

const Button = styled.button`
  background: blue;
  color: white;
  padding: 12px 24px;
  border-radius: 4px;
  border: none;
  cursor: pointer;
`;

export default function App() {
  return <Button>Click me</Button>;
}
```

```css
/* Generated CSS */
.vhash123-1 {
  background: blue;
  color: white;
  padding: 12px 24px;
  border-radius: 4px;
  border: none;
  cursor: pointer;
}
```

```tsx
// Generated JSX, no runtime overhead!!
export default function App() {
  return <button className="vhash123-1">Click me</button>;
}
```

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

### Install Vindur (Bash)

Source: https://github.com/lucasols/vindur/blob/main/README.md

Instructions for installing the Vindur library and its Vite plugin using npm, pnpm, or yarn. This is the initial step to integrate Vindur into your project.

```bash
npm install vindur @vindur-css/vite
# or
pnpm add vindur @vindur-css/vite
# or
yarn add vindur @vindur-css/vite
```

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

### Dynamic Color Usage Examples

Source: https://github.com/lucasols/vindur/blob/main/README.md

Illustrates practical usage of dynamic colors, showing how to set colors with additional styles and class names, and how to apply conditional styling to components based on color properties like dark or light.

```tsx
// Color setting with additional styles
const { className, style } = dynamicColor.setInComponent('#007bff', {
  style: { padding: '20px' },
  className: 'custom-card',
  setColorScheme: { fallback: 'dark' },
});

// Conditional styling based on color properties
const AdaptiveButton = styled.button`
  background: ${dynamicColor.var};
  color: ${dynamicColor.contrast.var};

  /* Different styles for dark vs light colors */
  &${dynamicColor.self.isDark} {
    border: 1px solid ${dynamicColor.lighter(0.2)};
  }

  &${dynamicColor.self.isLight} {
    border: 1px solid ${dynamicColor.darker(0.2)};
  }

  /* Conditional styles in parent containers */
  ${dynamicColor.container.isDefined} & {
    transition: all 0.2s ease;
  }
`;

```

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

### Vindur Index Assignment Example

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Demonstrates Vindur's file-scoped incremental counter for features. Shows how same names reuse indices and different names get sequential indices, with each file having its own counter space.

```tsx
const styles = css`
  color: red;
`; // Index 1
<div cx={{ active: true }} />; // Index 2
const Button = styled.button`
  color: blue;
`; // Index 3
<div cx={{ test: true, loading: true }} />; // test uses index 4, loading gets index 5
```

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

### Transformation Logic Example

Source: https://github.com/lucasols/vindur/blob/main/specs/style-flags.md

Illustrates how a styled component definition with modifier props is transformed into a function call that handles the application of hashed modifier classes. This process optimizes bundle size by hashing class names.

```tsx
const StyledWithModifiers = styled.div<{\n  active: boolean;\n  size: 'small' | 'medium' | 'large';\n  disabled: boolean;\n}>`\n  padding: 16px;\n\n  &.active {\n    background: blue;\n  }\n\n  &.size-small {\n    padding: 8px;\n  }\n\n  &.size-medium {\n    padding: 16px;\n  }\n\n  &.size-large {\n    padding: 24px;\n  }\n\n  &.disabled {\n    opacity: 0.5;\n  }\n`;\n\n// will be transformed to:\nconst StyledWithModifiers = vComponentWithModifiers(\n  [\n    ['active', 'v1234hash-active'], // boolean prop\n    ['size', 'v1234hash-size'], // string union prop\n    ['disabled', 'v1234hash-disabled'], // boolean prop\n  ],\n  'v1234hash-1',\n  'div',\n);\n\n// Component can be used as a normal JSX component\n// Internal implementation handles modifier class application\nconst usage = (\n  <StyledWithModifiers\n    active={true}\n    size=\"large\"\n    disabled={false}\n  >\n    Content\n  </StyledWithModifiers>\n);
```

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

### Vindur Testing with Vitest

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Demonstrates how to run tests for the Vindur library using Vitest. Commands allow running all tests, specific files, or tests matching a pattern, with options for passing additional Vitest arguments.

```bash
# Must be in the lib directory
cd lib

# Run all tests
pnpm test

# Run tests for a specific file
pnpm test tests/filename.test.ts

# Run a specific test matching a pattern
pnpm test tests/filename.test.ts -t "test name pattern"

# Use additional arguments supported by Vitest
pnpm test [...args]
```

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

### Vindur Library Development Commands

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Commands for managing the core Vindur library package located in the `lib/` directory. Includes running tests, linting, building the library, and performing TypeScript checks using pnpm.

```bash
cd lib
pnpm test
pnpm lint
pnpm build
pnpm tsc
```

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

### Dynamic Color API Reference

Source: https://github.com/lucasols/vindur/blob/main/README.md

Provides details on the API for dynamic colors, including methods for setting colors and conditional selectors for styling. `setProps` allows setting a color and returning props for integration, while `self.*` and `container.*` enable conditional styling based on color properties.

```APIDOC
Dynamic Color API:

Color Setting:
- `setProps(hexColor, options?)`: Sets the color value and returns className and style props.
  - `hexColor`: The color to set (e.g., '#ff6b6b').
  - `options.style?`: Additional CSS properties to merge.
  - `options.className?`: Additional class names to merge.
  - `options.setColorScheme?`: Configure color scheme detection with fallback (e.g., `{ fallback: 'dark' }`).

Conditional Selectors:
- `self.*`: Selectors for the component that sets the color.
- `container.*`: Selectors for child components.

Available Conditional Selectors:
- `isDark`: When the set color is considered dark.
- `isLight`: When the set color is considered light.
- `isDefined`: When a color has been set.
- `isNotDefined`: When no color has been set.
- `isVeryDark`: When the color is very dark (high contrast needed).
- `isNotVeryDark`: When the color is not very dark.
- `isVeryLight`: When the color is very light (high contrast needed).
- `isNotVeryLight`: When the color is not very light.

```

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

### Dynamic Theme Colors with createDynamicCssColor

Source: https://github.com/lucasols/vindur/blob/main/README.md

Demonstrates how to create dynamic color systems that can be customized at runtime using `createDynamicCssColor`. It shows usage with styled-components for applying colors and conditional styling based on color properties like darkness or lightness.

```tsx
import { createDynamicCssColor } from 'vindur';

const dynamicColor = createDynamicCssColor();

const Container = styled.div`
  background: ${dynamicColor.var};
  color: ${dynamicColor.contrast.var};

  /* use self selectors to conditionally style the component that is setting the color */
  ${dynamicColor.self.isDark} {
    border: 2px solid white;
  }
`;

const Card = styled.div`
  background: ${dynamicColor.var};
  color: ${dynamicColor.contrast.var};

  &:hover {
    background: ${dynamicColor.darker(0.1)};
  }

  /* use container selectors to conditionally style child components */
  ${dynamicColor.container.isLight} {
    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  }
`;

const ChildElement = styled.div`
  background: ${dynamicColor.var};
  color: ${dynamicColor.contrast.var};
`;

// for dom elements, and styled components you can use the dynamicColors prop to set the color
const MyComponent = () => {
  return (
    <div dynamicColor={dynamicColor}>
      <Card>This card adapts to the dynamic color</Card>
    </div>
  );
};

// for custom components, you can use the color.setProps to set the color
const MyComponent = () => {
  return (
    <div {...dynamicColor.setProps('#ff6b6b')}>
      <Card>This card adapts to the dynamic color</Card>
    </div>
  );
};

// multiple colors can be passed to dynamicColor prop
const MyComponent = () => {
  return (
    <div dynamicColor={[dynamicColor1, dynamicColor2]}>
      <Card>This card adapts to the dynamic color</Card>
    </div>
  );
};

```

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

### Vindur E2E Testing with Playwright

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Shows how to execute end-to-end tests for Vindur using Playwright. Commands enable running all tests, specific files, or tests matching a pattern, with options for debug logs and Playwright arguments.

```bash
# Must be in the e2e-tests directory
cd e2e-tests

# Run all tests
pnpm test

# Run tests for a specific file
pnpm test tests/filename.spec.ts

# Run a specific test matching a pattern
pnpm test tests/filename.spec.ts --grep "test name pattern"

# Run with debug logs
DEBUG=1 pnpm test ...

# Use additional arguments supported by Playwright
pnpm test [...args]
```

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

### Run All Vindur Project Commands

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Execute common development tasks across all packages in the Vindur monorepo using pnpm. These commands cover testing, building, linting, and TypeScript compilation for the entire project.

```bash
pnpm test-all
pnpm build-all
pnpm lint-all
pnpm tsc-all
```

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

### Vindur E2E Tests Development Commands

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Commands for running end-to-end tests for Vindur, located in the `e2e-tests/` directory. Supports running all tests, specific files, or tests matching a pattern using pnpm and Playwright.

```bash
cd e2e-tests
pnpm test
pnpm eslint
pnpm lint
pnpm tsc
```

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

### Vindur Vite Plugin Development Commands

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Commands for developing the Vite plugin for Vindur, located in the `vite-plugin/` directory. Tasks include building the plugin, linting, and TypeScript compilation via pnpm.

```bash
cd vite-plugin
pnpm build
pnpm lint
pnpm tsc
```

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

### Global Styles with Variable Interpolation

Source: https://github.com/lucasols/vindur/blob/main/README.md

Demonstrates using JavaScript variables and CSS custom properties within `createGlobalStyle` for dynamic theming and style injection.

```tsx
const primaryColor = '#007bff';
const fontFamily = 'Inter, system-ui, sans-serif';

createGlobalStyle`
  :root {
    --primary-color: ${primaryColor};
    --font-family: ${fontFamily};
  }

  body {
    font-family: var(--font-family);
    color: #333;
  }

  .highlight {
    color: ${primaryColor};
  }
`;
```

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

### CSS Layers with Vindir

Source: https://github.com/lucasols/vindur/blob/main/README.md

Explains how to use CSS layers to manage style specificity and avoid conflicts. It demonstrates using `createGlobalStyle` to define layer order and the `layer` function to apply styles within specific CSS layers.

```tsx
import { styled, layer, createGlobalStyle } from 'vindur';

// optionally create global style to set the layers order
const GlobalStyle = createGlobalStyle`
  @layer lower-priority, higher-priority;
`;

// then use the `layer` function extend the layers in the components;
const Card = styled.div`
  ${layer('higher-priority')} {
    background: white;
    padding: 20px;
    border-radius: 8px;
  }

  ${layer('lower-priority')} {
    background: red;
  }
`;

```

```css
@layer lower-priority, higher-priority;

@layer higher-priority {
  .vhash123-1-Card {
    background: white;
    padding: 20px;
    border-radius: 8px;
  }
}

@layer lower-priority {
  .vhash123-1-Card {
    background: red;
  }
}

```

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

### Create Styled Components (TSX)

Source: https://github.com/lucasols/vindur/blob/main/README.md

Illustrates creating various styled components for common HTML elements like `h1`, `div`, and `main`. This showcases Vindur's ability to style any HTML tag.

```tsx
import { styled } from 'vindur';

const Title = styled.h1`
  font-size: 24px;
  color: #333;
  margin-bottom: 16px;
`;

const Card = styled.div`
  background: white;
  border-radius: 8px;
  padding: 20px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
`;

const Container = styled.main`
  max-width: 1200px;
  margin: 0 auto;
  padding: 20px;
`;
```

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

### Global Styles Referencing Styled Components

Source: https://github.com/lucasols/vindur/blob/main/README.md

Shows how to reference and apply styles to existing styled components directly within `createGlobalStyle`.

```tsx
import { styled } from 'vindur';

const Button = styled.button`
  padding: 12px 24px;
`;

createGlobalStyle`
  ${Button} {
    background: #007bff;
    color: white;
  }
`;
```

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

### Generate Stable IDs for Components

Source: https://github.com/lucasols/vindur/blob/main/README.md

Shows how to create deterministic, stable IDs using `stableId` and `createClassName` for use in styled components and CSS. These IDs are compiled at build time.

```tsx
import { css, styled, generateClassName, stableId } from 'vindur';

// stableId marker creates stable class names based on variable name
export const elementClassName = generateClassName();
export const genericPurposeId = stableId();

// is compiled to:
// export const elementClassName = createClassName('vhash-1');
// export const genericPurposeId = 'vhash-2';
```

```tsx
import { elementClassName, genericPurposeId } from './styles';

const Element = styled.div`
  ${elementClassName.selector} {
    background: red;
    --value: ${genericPurposeId};
  }
`;

const style = css`
  ${elementClassName.selector} {
    background: red;
    --value: ${genericPurposeId};
  }
`;

const Component = () => {
  return (
    <div
      css={`
        ${elementClassName.selector} {
          background: red;
          --value: ${genericPurposeId};
        }
      `}
    >
      <div id={genericPurposeId}>Hello</div>
    </div>
  );
};
```

```tsx
const Component = () => {
  return (
    <div className={elementClassName.value}>
      <div id={genericPurposeId}>Hello</div>
    </div>
  );
};
```

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

### Vindur: Dynamic CSS with vindurFn

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Shows how to handle dynamic CSS requirements by wrapping functions with `vindurFn`. This allows CSS properties to depend on runtime values like component props or state.

```tsx
const dynamicStyles = vindurFn(
  (color: string, isActive: boolean) => `
  color: ${color};              // ✅ OK inside vindurFn
  padding: ${isActive ? 16 : 8}px;  // ✅ OK inside vindurFn
`,
);

```

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

### Color API Reference

Source: https://github.com/lucasols/vindur/blob/main/README.md

Details the methods available for each color object generated by `createStaticThemeColors`, including CSS variable generation, alpha/darker/lighter variants, and contrast color access.

```APIDOC
Color Object API:

- `var`: CSS variable reference for the color (e.g., `var(--stc-primary-var)`).
- `defaultHex`: The original hex value provided during theme creation.
- `alpha(amount)`: Creates a variant with specified alpha transparency (0-1 scale). Returns a CSS variable reference.
- `darker(amount)`: Creates a darker variant of the color (0-1 scale). Returns a CSS variable reference.
- `lighter(amount)`: Creates a lighter variant of the color (0-1 scale). Returns a CSS variable reference.

Contrast API (accessed via `color.contrast`):

- `contrast.var`: CSS variable reference for the optimal contrast color.
- `contrast.optimal(options?)`: Generates optimal contrast. For light colors, it might use a saturated dark color instead of black. Returns a CSS variable reference.
- `contrast.alpha(amount)`: Creates an alpha variant of the contrast color. Returns a CSS variable reference.
```

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

### CSS Selector Patterns for Style Flags

Source: https://github.com/lucasols/vindur/blob/main/README.md

Illustrates the CSS selector patterns used for applying styles based on boolean and string union props in styled components.

```css
/* Boolean props */
&.propName {
  /* styles when prop is true */
}

/* String union props */
&.propName-value {
  /* styles when prop equals 'value' */
}
```

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

### Vindur TypeScript and ESLint Guidelines

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Outlines key TypeScript and ESLint best practices for the Vindur project. Emphasizes type safety, avoiding `any`, specific casting rules, and code organization principles.

```typescript
// Use types instead of interfaces
type MyType = { prop: string };

// Do not use 'any'
// let value: any; // Incorrect
let value: string | number;

// Do not use 'as Type' casts, except for 'as const'
// const str = value as string; // Incorrect
const obj = { key: 'value' } as const;

// Do not use non-null assertions (!)
// const element = document.getElementById('my-id')!;
const element = document.getElementById('my-id');

// Avoid using optional parameters, use default values or '| undefined'
// function greet(name?: string) {}
function greet(name: string | undefined = undefined) {}

// Abstract redundant types into a single type
type User = {
  id: number;
  name: string;
};

// Abstract redundant code into a single function
function processData(data: User) {
  // ... common processing logic ...
}
```

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

### Static Theme Colors

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Provides compile-time color utilities for consistent theming. Static color definitions are processed at build time, ensuring optimal performance and predictable color usage across the application.

```javascript
/*
  // Example of static theme color definitions (conceptual):
  // In a separate theme file (e.g., theme.js):
  export const colors = {
    primary: '#007bff',
    secondary: '#6c757d',
    danger: '#dc3545',
  };

  // In your component file:
  import { css} from 'vindur';
  import { colors } from './theme';

  const styles = css`
    background-color: ${colors.primary};
    color: ${colors.secondary};
  `;
*/

// This feature primarily influences how Vindur processes color variables at build time.
// The actual implementation would involve importing theme constants.
console.log('Static theme colors are processed at build time.');
```

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

### E2E Test Structure and Guidelines

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Demonstrates the recommended structure for End-to-End tests, emphasizing serial execution, shared setup/teardown hooks, and Playwright best practices for maintainability and performance.

```typescript
test.describe.configure({ mode: 'serial' });

let env: TestEnv;
let page: Page;

test.beforeAll(async ({ browser }) => {
  page = await browser.newPage();
  env = await startEnv('test-name', {
    'App.tsx': dedent`
        // Single comprehensive App component
        // covering all test scenarios
      `,
  });
  await page.goto(env.baseUrl);
});

test.afterAll(async () => {
  await page.close();
  await env.cleanup();
});

test('should test feature A', async () => {
  const element = page.getByTestId('test-element');
  await expect(element).toHaveCSS('property', 'value');
});
```

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

### Vindur: Valid Static CSS with Module Constants

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Demonstrates using Vindur's `css` template literal with statically defined module-level constants and literal values. These are permitted during compile-time analysis.

```tsx
const BRAND_COLOR = '#667eea'; // Static constant - OK

const styles = css`
  color: ${BRAND_COLOR}; // Static variable - OK
  padding: 16px; // Literal value - OK
`;
```

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

### CreateGlobalStyle for Global CSS

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Injects global CSS styles into the document. `createGlobalStyle` handles build-time extraction and deduplication, ensuring global styles are injected only once per unique definition.

```javascript
import { createGlobalStyle } from 'vindur';

const GlobalStyles = createGlobalStyle`
  body {
    margin: 0;
    font-family: sans-serif;
    background-color: #f4f4f4;
  }

  a {
    color: blue;
    text-decoration: none;
  }
`;

// Example usage (typically in your App component's root):
// <>
//   <GlobalStyles />
//   {/* Rest of your app */}
// </>
```

```typescript
import { createGlobalStyle } from 'vindur';

const AppGlobalStyles = createGlobalStyle`
  @font-face {
    font-family: 'CustomFont';
    src: url('/fonts/custom.woff2') format('woff2');
  }

  html, body {
    box-sizing: border-box;
  }

  *, *:before, *:after {
    box-sizing: inherit;
  }
`;

// Example usage:
// <AppGlobalStyles />
```

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

### Runtime Helper Function 'cx' (Production)

Source: https://github.com/lucasols/vindur/blob/main/specs/cx-prop.md

Illustrates the production usage of the `cx` helper function, which evaluates dynamic conditions to produce optimized class names.

```tsx
import { cx } from 'vindur';

// Example usage in compiled output
const dynamicClassName = cx({
  'v1234hash-1': isActive,
  'v1234hash-2': isDisabled,
  noHash: true, // $ prefix was removed
});
```

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

### Runtime Helper Function 'cx' (Development)

Source: https://github.com/lucasols/vindur/blob/main/specs/cx-prop.md

Shows the usage of the `cx` helper function imported from 'vindur' in a development context, evaluating dynamic conditions to generate class names.

```tsx
import { cx } from 'vindur';

// Example usage in compiled output
const dynamicClassName = cx({
  'v1234hash-1-active': isActive,
  'v1234hash-2-disabled': isDisabled,
  noHash: true, // $ prefix was removed
});
```

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

### Create Global Styles

Source: https://github.com/lucasols/vindur/blob/main/README.md

Applies CSS styles globally to the entire document using the `createGlobalStyle` function. Styles are applied directly without needing class wrappers.

```tsx
import { createGlobalStyle } from 'vindur';

// Global styles are applied directly without class wrappers
createGlobalStyle`
  body {
    margin: 0;
    padding: 0;
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
    color: #333;
    background: #fff;
  }

  * {
    box-sizing: border-box;
  }

  h1, h2, h3, h4, h5, h6 {
    margin: 0 0 1rem 0;
    font-weight: 600;
  }

  button {
    font-family: inherit;
  }

  @media (prefers-reduced-motion: reduce) {
    * {
      animation-duration: 0.01ms !important;
      animation-iteration-count: 1 !important;
      transition-duration: 0.01ms !important;
    }
  }
`;
```

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

### Create type-safe theme color systems

Source: https://github.com/lucasols/vindur/blob/main/README.md

Utilize `createStaticThemeColors` to define a type-safe color theme. Each color provides methods for generating CSS variables, alpha variants, and contrast colors.

```tsx
import { createStaticThemeColors } from 'vindur';

const colors = createStaticThemeColors({
  primary: '#007bff',
  secondary: '#6c757d',
  success: '#28a745',
  danger: '#dc3545',
  warning: '#ffc107',
  info: '#17a2b8',
});

// Each color provides a complete theming API
const Button = styled.button`
  background: ${colors.primary.var};
  color: ${colors.primary.contrast.var};

  &:hover {
    background: ${colors.primary.darker(0.1)};
  }

  &:active {
    background: ${colors.primary.alpha(0.8)};
  }
`;
```

```css
// Optimized CSS output
.v1560qbr-1-Button {
  background: #007bff;
  color: #fff;

  &:hover {
    background: #0056b3;
  }

  &:active {
    background: #0056b380;
  }
}

// Dev mode output with CSS variables
.v1560qbr-1-Button {
  background: var(--stc-primary-var, #007bff);
  color: var(--stc-primary-contrast-var, #fff);

  &:hover {
    background: var(--stc-primary-darker-0\.1, #0056b3);
  }

  &:active {
    background: var(--stc-primary-alpha-0\.8, #0056b380);
  }
}
```

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

### Create Reusable Styles with css() (TSX)

Source: https://github.com/lucasols/vindur/blob/main/README.md

Demonstrates using the `css` function from Vindur to define reusable style blocks. These styles can then be applied directly to elements via the `className` prop.

```tsx
import { css } from 'vindur'

const buttonBase = css`
  padding: 12px 24px;
  border-radius: 4px;
  border: none;
  cursor: pointer;
`

// Use in className
<button className={buttonBase}>Click me</button>
```

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

### CSS Nesting Support (TSX)

Source: https://github.com/lucasols/vindur/blob/main/README.md

Demonstrates Vindur's support for native CSS nesting syntax within template literals. This allows for more organized and readable stylesheets, mirroring modern CSS practices.

```tsx
import { styled } from 'vindur';

const Card = styled.div`
  background: white;
  padding: 20px;

  h3 {
    color: #333;
    margin-bottom: 16px;
  }

  &:hover {
    transform: translateY(-2px);
  }

  @media (max-width: 768px) {
    padding: 16px;
  }
`;

const Navigation = styled.nav`
  ul {
    list-style: none;
    display: flex;

    li a {
      color: #333;
      text-decoration: none;

      &:hover {
        background: #f5f5f5;
      }
    }
  }
`;
```

```css
**Output**: Native CSS nesting preserved as-is:
```css
.v1234567-1 {
  background: white;
  padding: 20px;

  h3 {
    color: #333;
    margin-bottom: 16px;
  }

  &:hover {
    transform: translateY(-2px);
  }

  @media (max-width: 768px) {
    padding: 16px;
  }
}
```
```

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

### Transform Test Structure

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Provides a template for testing transform functions, detailing the use of vitest, dedent utility, and a custom transformWithFormat function, with guidance on source inlining and default prop usage.

```tsx
import { describe, expect, test } from 'vitest';
import { dedent } from '@ls-stack/utils/dedent';
import { transformWithFormat } from './testUtils';
// ...

test('should handle ...', async () => {
  const result = await transformWithFormat({
    // source should be inlined if it is not used multiple times
    source: dedent`
      // ...
    `,
    // prefer using default props for `fs` and `importAliases` unless the test requires it
  });

  // code assertion should come first, then css assertion
  expect(result.code).toMatchInlineSnapshot(`
    // ...
  `);

  expect(result.css).toMatchInlineSnapshot(`
    // ...
  `);
});
```

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

### Styled Component References with '&'

Source: https://github.com/lucasols/vindur/blob/main/README.md

Demonstrates how to reference other styled components within CSS selectors using the `&` operator. This leverages native CSS nesting for cleaner styling. It covers referencing components within parent selectors and handling components defined later using forward references.

```tsx
const Card = styled.div`
  background: white;
  padding: 20px;
  border-radius: 8px;
`

const Button = styled.button`
  background: #007bff;
  color: white;
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
`

const Container = styled.div`
  ${Card}:hover & {
    transform: translateY(-2px);
    box-shadow: 0 4px 8px rgba(0,0,0,0.15);
  }

  & ${Button}:hover {
    background: #0056b3;
  }
`

// Usage
<Container>
  <Card>
    <h3>Card Title</h3>
    <Button>Action</Button>
  </Card>
</Container>
```

```css
.v1560qbr-1 {
  background: white;
  padding: 20px;
  border-radius: 8px;
}

.v1560qbr-2 {
  background: #007bff;
  color: white;
  padding: 8px 16px;
  border: none;
  border-radius: 4px;
}

.v1560qbr-3 {
  .v1560qbr-1:hover & {
    transform: translateY(-2px);
    box-shadow: 0 4px 8px rgba(0, 0, 0, 0.15);
  }

  & .v1560qbr-2:hover {
    background: #0056b3;
  }
}
```

```tsx
const Card = styled.div`
  ${baseStyles};
  background: white;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
`;

const styleWithCss = css`
  ${baseStyles}:hover & {
    background: #007bff;
    color: white;
  }
`;
```

```tsx
const Card = styled.div`
  background: white;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);

  ${() => Container}:hover & {
    background: #007bff;
    color: white;
  }
`;

const Container = styled.div`
  background: #007bff;
  color: white;
  border-color: #0056b3;
`;
```

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

### Extend Styled Components (TSX)

Source: https://github.com/lucasols/vindur/blob/main/README.md

Demonstrates how to inherit and extend styles from an existing styled component. This allows for creating variations of base components, promoting code reuse and maintainability.

```tsx
import { styled } from 'vindur';

const BaseButton = styled.button`
  padding: 12px 24px;
  border-radius: 4px;
  border: none;
  cursor: pointer;
`;

const PrimaryButton = styled(BaseButton)`
  background: #007bff;
  color: white;
`;

const SecondaryButton = styled(BaseButton)`
  background: #6c757d;
  color: white;
`;
```

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

### Define and Use CSS Keyframes Animation

Source: https://github.com/lucasols/vindur/blob/main/README.md

Demonstrates how to define CSS animations using the `keyframes` function and apply them to styled components. Supports variable interpolation within keyframe definitions.

```tsx
import { keyframes, styled } from 'vindur';

const fadeIn = keyframes`
  from {
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
`;

const slideIn = keyframes`
  0% {
    transform: translateX(-100%);
  }
  50% {
    transform: translateX(-10px);
  }
  100% {
    transform: translateX(0);
  }
`;

const AnimatedCard = styled.div`
  background: white;
  padding: 20px;
  animation: ${fadeIn} 0.3s ease-out;

  &:hover {
    animation: ${slideIn} 0.5s ease-in-out;
  }
`;
```

```tsx
const startPosition = '-100%';
const endPosition = '0';

const slideAnimation = keyframes`
  from {
    transform: translateX(${startPosition});
  }
  to {
    transform: translateX(${endPosition});
  }
`;
```

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

### Create Reusable Style Functions with vindurFn

Source: https://github.com/lucasols/vindur/blob/main/README.md

Defines reusable style logic using `vindurFn`, allowing for parameterized style generation similar to CSS mixins or functions.

```tsx
// utils/styles.ts
import { vindurFn } from 'vindur';

export const flexCenter = vindurFn(
  () => `
  display: flex;
  align-items: center;
  justify-content: center;
`,
);

export const buttonSize = vindurFn((size: 'sm' | 'md' | 'lg') =>
  size === 'sm' ? 'padding: 6px 12px; font-size: 14px;'
  : size === 'md' ? 'padding: 8px 16px; font-size: 16px;'
  : 'padding: 12px 24px; font-size: 18px;',
);

// components/Button.tsx
import { styled } from 'vindur';
import { flexCenter, buttonSize } from '../utils/styles';

const Button = styled.button`
  ${flexCenter()};
  ${buttonSize('md')};
  background: #007bff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
`;
```

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

### Dynamic Color Prop (Development)

Source: https://github.com/lucasols/vindur/blob/main/specs/cx-prop.md

Demonstrates how the `dynamicColor` prop, when used with `cx`, merges dynamic color properties into the final className for development environments.

```tsx
const before = (
  <div
    cx={{ active: isActive }}
    dynamicColor={color.set('#ff6b6b')}
  />
);

const compiled = (
  <div
    {...color._sp('#ff6b6b', {
      className: cx({ 'v1234hash-1-active': isActive }),
    })}
  />
);
```

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

### Apply Styles with JSX css Prop

Source: https://github.com/lucasols/vindur/blob/main/README.md

Enables direct styling of JSX elements using a `css` prop, similar to styled-components or emotion. It works with native elements and styled components.

```tsx
import { css } from 'vindur';

const App = () => (
  <div
    css={`
      background: blue;
      padding: 20px;
      color: white;
    `}
  >
    Hello World
  </div>
);

const Card = styled.div`
  background: white;
  padding: 20px;
`;

const AppWithCard = () => (
  <Card
    css={`
      border: 1px solid red;
    `}
  >
    Card with additional styling
  </Card>
);

const CustomComponent = ({ children, css }: { children: React.ReactNode; css: string }) => {
  return <div className={css}>{children}</div>;
};

// css now will correctly work with the component!
<CustomComponent css={`color: red;`}>Content</CustomComponent>;

// the component will compile to:
// <CustomComponent css="v1234hash-css-prop-1">Content</CustomComponent>;
```

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

### css prop on Styled Components

Source: https://github.com/lucasols/vindur/blob/main/specs/css-prop.md

Explains the compatibility of the 'css' prop with styled components. It demonstrates applying styles to a 'StyledCard' component and shows the resulting compiled output.

```tsx
const before = (
  <StyledCard
    css={`
      border: 1px solid red;
    `}
  >
    Content
  </StyledCard>
);

const compiled = (
  <div className="v1234hash-Card v1234hash-css-prop-1">Content</div>
);
```

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

### Create styled components with style flags props

Source: https://github.com/lucasols/vindur/blob/main/README.md

Define styled components that accept boolean and string union props for automatic conditional styling. Modifier classes are applied based on prop values.

```tsx
import { styled } from 'vindur';

const Button = styled.button<{
  primary: boolean;
  size: 'small' | 'medium' | 'large';
  disabled: boolean;
}>`
  padding: 12px 24px;
  background: #007bff;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;

  &.primary {
    background: #0056b3;
    transform: scale(1.05);
  }

  &.size-small {
    padding: 6px 12px;
    font-size: 14px;
  }

  &.size-medium {
    padding: 12px 24px;
    font-size: 16px;
  }

  &.size-large {
    padding: 18px 36px;
    font-size: 18px;
  }

  &.disabled {
    background: #6c757d;
    cursor: not-allowed;
    opacity: 0.6;
  }
`;

// Usage with boolean and string union props
const App = ({ isPrimary, buttonSize, isDisabled }) => (
  <Button
    primary={isPrimary}
    size={buttonSize}
    disabled={isDisabled}
  >
    Click me
  </Button>
);
```

```tsx
// Generated component
const Button = vComponentWithModifiers(
  [
    ['primary', 'classHash-1'],
    ['size', 'classHash-2'],
    ['disabled', 'classHash-3'],
  ],
  'vhash123-1',
  'button',
);

// Component can be used as a normal JSX component
const App = ({ isPrimary, buttonSize, isDisabled }) => (
  <Button
    primary={isPrimary}
    size={buttonSize}
    disabled={isDisabled}
  >
    Click me
  </Button>
);
```

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

### Styled Components

Source: https://github.com/lucasols/vindur/blob/main/CLAUDE.md

Enables creating styled React components. Supports non-exported components (injected directly), exported components (via helper), and style extension using `styled(Component)` syntax. Includes `withComponent` for changing the underlying element type.

```javascript
import styled from 'vindur';

const Button = styled.button`
  background-color: blue;
  color: white;
  padding: 10px;
`;

// Example usage:
// <Button>Click Me</Button>

// Style extension:
const PrimaryButton = styled(Button)`
  background-color: green;
`;

// Changing element type:
const LinkButton = Button.withComponent('a');
```

```typescript
import styled, { StyledComponent } from 'vindur';

interface ButtonProps {
  primary?: boolean;
}

const Button: StyledComponent<'button', ButtonProps> = styled.button<ButtonProps>`
  background-color: ${props => props.primary ? 'green' : 'blue'};
  color: white;
  padding: 10px;

  // Using '&' selector for nested styles
  &:hover {
    opacity: 0.9;
  }
`;

// Example usage:
// <Button>Default</Button>
// <Button primary>Primary</Button>

// Style extension:
const DangerButton = styled(Button)`
  background-color: red;
`;

// Changing element type:
const AnchorButton = Button.withComponent('a');
```

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

### Complex Integration (Development)

Source: https://github.com/lucasols/vindur/blob/main/specs/cx-prop.md

Demonstrates a complex scenario combining `className`, `cx`, `css` directives, `dynamicColor`, and spread props in a development environment.

```tsx
const before = (
  <div
    className="base-class"
    cx={{ active: isActive, disabled: isDisabled }}
    css={`
      background: red;
    `}
    dynamicColor={color.set('#ff6b6b')}
    {...props}
  />
);

const compiled = (
  <div
    {...props}
    {...color._sp('#ff6b6b', {
      className: mergeClassNames(
        [props],
        'base-class v1234hash-css-1-background',
        cx({
          'v1234hash-1-active': isActive,
          'v1234hash-2-disabled': isDisabled,
        }),
      ),
    })}
  />
);
```