Pinceau

https://github.com/tahul/pinceau
Admin
A typed CSS-in-JS styling library with design tokens support for Vue, React, Svelte, Nuxt, and...
Tokens:79,825
Snippets:386
Trust Score:8.4
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install and Setup Pinceau for React

Source: https://github.com/tahul/pinceau/blob/main/README.md

Install and configure Pinceau for React. Run the install command, then add the plugin to your Vite config.

```bash
pnpm install @pinceau/react

```

```ts
// vite.config.ts
import Pinceau from '@pinceau/react/plugin'

export default defineConfig({
  plugins: [
    Pinceau(),
    ...yourPlugins
  ],
})

```

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

### Install and Setup Pinceau for Svelte

Source: https://github.com/tahul/pinceau/blob/main/README.md

Install and configure Pinceau for Svelte. Run the install command, then add the plugin to your Vite config.

```bash
pnpm install @pinceau/svelte

```

```ts
// vite.config.ts
import Pinceau from '@pinceau/svelte/plugin'

export default defineConfig({
  plugins: [
    Pinceau(),
    ...yourPlugins
  ],
})

```

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

### Install and Setup Pinceau for Vue

Source: https://github.com/tahul/pinceau/blob/main/README.md

Install and configure Pinceau for Vue. Run the install command, then add the plugin to your Vite config.

```bash
pnpm install @pinceau/vue

```

```ts
// vite.config.ts
import Pinceau from '@pinceau/vue/plugin'

export default defineConfig({
  plugins: [
    Pinceau(),
    ...yourPlugins
  ],
})

```

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

### Run development server with npm, pnpm, yarn, or bun

Source: https://github.com/tahul/pinceau/blob/main/docs/README.md

Start the development server on http://localhost:3000. Use the command for your package manager.

```bash
# npm
npm run dev

# pnpm
pnpm run dev

# yarn
yarn dev

# bun
bun run dev
```

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

### Configure Pinceau plugin options in Vite and Nuxt

Source: https://github.com/tahul/pinceau/blob/main/docs/content/3.advanced/0.vite-plugin-options.md

Shows how to pass Pinceau options in Vite and Nuxt setups. The Vite example uses the `pinceau/vite` plugin, while the Nuxt example uses the `pinceau/nuxt` module with a `pinceau` key.

```ts
import { defineConfig } from 'vite'
import Pinceau from 'pinceau/vite'

export default defineConfig({
  plugins: [
    Pinceau({
      ...options
    })
  ],
})
```

```ts
defineNuxtConfig({
  modules: ['pinceau/nuxt'],

  pinceau: {
    ...options
  }
})
```

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

### Install Pinceau with yarn

Source: https://github.com/tahul/pinceau/blob/main/docs/content/0.get-started/1.installation.md

Installs Pinceau as a development dependency using the yarn package manager.

```bash
yarn add pinceau --save-dev
```

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

### Install Pinceau with pnpm

Source: https://github.com/tahul/pinceau/blob/main/docs/content/0.get-started/1.installation.md

Installs Pinceau as a development dependency using the pnpm package manager.

```bash
pnpm install -D pinceau
```

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

### Install dependencies with npm, pnpm, yarn, or bun

Source: https://github.com/tahul/pinceau/blob/main/docs/README.md

Install project dependencies using npm, pnpm, yarn, or bun. Choose the command for your preferred package manager.

```bash
# npm
npm install

# pnpm
pnpm install

# yarn
yarn install

# bun
bun install
```

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

### Configure layers option with string and ConfigLayer entries

Source: https://github.com/tahul/pinceau/blob/main/docs/content/3.advanced/0.vite-plugin-options.md

Example of the `layers` option, showing a string path, a `ConfigLayer` with `tokens`, and a `ConfigLayer` with `path` and `configFileName`.

```ts
{
  layers: [
    // `string`
    './my-themes/basic/',
    // `ConfigLayer` with `tokens`
    {
      tokens: {
        color: {
          primary: 'red'
        }
      }
    },
    // `ConfigLayer` with `cwd`
    {
      path: './my-themes/figma',
      configFileName: 'figma.config'
    }
  ]
}
```

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

### Install Pinceau with npm

Source: https://github.com/tahul/pinceau/blob/main/docs/content/0.get-started/1.installation.md

Installs Pinceau as a development dependency using the npm package manager.

```bash
npm install pinceau --save-dev
```

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

### Pinceau Typed Styling API Examples

Source: https://github.com/tahul/pinceau/blob/main/README.md

Shows three core APIs of Pinceau's typed styling: $styled for styled components, styled for scoped class generation, and css for global styles. These are brief examples meant to highlight the TypeScript-based styling capabilities.

```typescript
const Component = $styled.a<Props>({ ...componentStyle })
```

```typescript
const className = styled({ ...scopedCss })
```

```typescript
css({ ...globalCss })
```

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

### Define utils in theme.config.ts

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/4.utils-properties.md

Define utility properties under the `utils` key in your theme config. Each utility is a function that returns a CSS declaration object. The example defines `px` and `mx` utilities for horizontal padding and margin.

```ts
import type { PropertyValue } from '@pinceau/style'

export default defineTheme({
  space: {
    1: '0.25rem',
    2: '0.5rem',
    3: '0.75rem',
    4: '1rem'
  },

  utils: {
    px: (value: PropertyValue<'padding'>) => ({
      paddingLeft: value,
      paddingRight: value
    }),
    mx: (value: PropertyValue<'margin'>) => ({
      marginLeft: value,
      marginRight: value
    })
  }
})
```

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

### Define utils property in theme

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/1.css-function.md

Example of defining a utils property 'mx' in the theme. The property returns an object with marginRight and marginLeft, and is used to generate utility classes.

```ts
defineTheme({
  utils: {
    mx: value => ({ marginRight: v, marginLeft: v })
  }
})
```

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

### Use component context in computed style

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/3.computed-styles.md

Uses a ref from the script setup context inside a computed style to set the background color.

```vue
<script setup lang="ts">
type ThemeColors = keyof PinceauTheme['color']

const currentColor = ref<ThemeColors>('green')

const setCurrentColor = (value: ThemeColors) => (currentColor.value = value)
</script>

<style lang="ts">
css({
  '.my-button': {
    backgroundColor: () => currentColor.value
  }
})
</style>
```

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

### Access theme token with $theme() in TypeScript

Source: https://github.com/tahul/pinceau/blob/main/docs/content/0.get-started/0.what-is-pinceau.md

Accesses a design token value in TypeScript using the $theme() helper. This example retrieves the color.green.5 token.

```ts
const green500 = $theme('color.green.5')
```

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

### Overriding Local Tokens with CSS Prop

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/5.css-prop.md

The CSS prop has the local tokens defined inside the component injected into it, allowing you to overwrite any local tokens from a parent component. This example shows how to pass a CSS object with a custom property to override a local token.

```html
<template>
  <MyButton :css="{ '--button-primary': '{color.red.200}' }" />
</template>
```

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

### Build for production with npm, pnpm, yarn, or bun

Source: https://github.com/tahul/pinceau/blob/main/docs/README.md

Build the application for production. Use the command for your package manager.

```bash
# npm
npm run build

# pnpm
pnpm run build

# yarn
yarn build

# bun
bun run build
```

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

### Preview production build with npm, pnpm, yarn, or bun

Source: https://github.com/tahul/pinceau/blob/main/docs/README.md

Locally preview the production build. Use the command for your package manager.

```bash
# npm
npm run preview

# pnpm
pnpm run preview

# yarn
yarn preview

# bun
bun run preview
```

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

### Define a responsive token with initial and dark keys

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/3.responsive-tokens.md

Defines a responsive token for the primary color that uses a light color in dark mode and a dark color in light mode. The token value is an object with an `initial` key for the default value and a `dark` key for dark mode. Also defines a blue color palette with shades from 0 to 9.

```ts
export default defineTheme({
  primary: {
    initial: '$color.blue.9',
    dark: '$color.blue.0'
  },
  blue: {
    0: '#C5CDE8',
    1: '#B6C1E2',
    2: '#99A8D7',
    3: '#7B8FCB',
    4: '#5E77C0',
    5: '#4560B0',
    6: '#354A88',
    7: '#25345F',
    8: '#161E37',
    9: '#06080F',
  },
})
```

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

### Import utils for runtime features

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/4.utils-properties.md

To use utils with runtime features like Variants, Computed Styles, or the CSS Prop, import the utils from `@pinceau/outputs/utils` and pass them to the Pinceau plugin. This is required because Pinceau does not include utils by default to avoid shipping unnecessary JavaScript.

```ts
import { createApp } from 'vue'
import Pinceau from 'pinceau/runtime'
import utils from '@pinceau/outputs/utils'

const app = createApp()

app.use(Pinceau, { utils })
```

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

### Define theme configuration with defineTheme

Source: https://github.com/tahul/pinceau/blob/main/docs/content/0.get-started/0.what-is-pinceau.md

Defines the theme configuration file with media queries, design tokens (colors and spacing), and utility properties. This file is the central place to store all design tokens, media queries, and utils properties for Pinceau.

```ts
import { defineTheme } from '@pinceau/theme'

defineTheme({
  // Media queries
  media: {
    mobile: '(min-width: 320px)',
    tablet: '(min-width: 768px)',
    desktop: '(min-width: 1280px)'
  },

  // Some Design tokens
  color: {
    red: {
      1: '#FCDFDA',
      2: '#F48E7C',
      3: '#ED4D31',
      4: '#A0240E',
      5: '#390D05',
    },
    green: {
      1: '#CDF4E5',
      2: '#9AE9CB',
      3: '#36D397',
      4: '#1B7D58',
      5: '#072117',
    }
  },
  space: {
    1: '0.25rem',
    2: '0.5rem',
    3: '0.75rem',
    4: '1rem'
  },

  // Utils properties
  utils: {
    px: (value: PropertyValue<'padding'>) => ({ paddingLeft: value, paddingRight: value }),
    py: (value: PropertyValue<'padding'>) => ({ paddingTop: value, paddingBottom: value })
  }
})
```

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

### Use media queries in .postcss files

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/2.media-queries.md

Use media queries in `.postcss` files with the `$dt()` helper. The `@dark` and `@md` blocks apply the nested styles when the corresponding media query matches.

```css
html {
  color: $dt('color.gray.900');
  padding: $dt('space.4');

  @dark {
    color: $dt('color.gray.100');
  }

  @md {
    padding: $dt('space.8');
  }
}
```

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

### Usage in MDC

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/0.your-first-component.md

Shows how to use the button component in MDC syntax with different color props.

```md
::my-button{color="red"}
Red button
::

::my-button{color="teal"}
Teal button
::

::my-button{color="blue"}
Blue button
::
```

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

### Use media queries in .css files

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/2.media-queries.md

Use media queries in `.css` files with the `$dt()` helper. The `@dark` and `@md` blocks apply the nested styles when the corresponding media query matches.

```css
html {
  color: $dt('color.gray.900');
  padding: $dt('space.4');
}

@dark {
  html {
    color: $dt('color.gray.100');
  }
}

@md {
  html {
    padding: $dt('space.8');
  }
}
```

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

### Use size prop in MDC usage

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/0.your-first-component.md

Shows how to use the `size` prop in Markdown components (MDC) with YAML front matter for responsive sizes.

```md
::my-button{size="sm"}
Small button
::

::my-button{size="md"}
Medium button
::

::my-button
---
size:
  initial: sm
  md: md
  lg: lg
  xl: xl
---
Responsive button
::
```

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

### Define a theme with defineTheme and view generated CSS and TS outputs

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/0.tokens-config.md

A minimal theme.config.ts using defineTheme with media, color, and space tokens. The CSS output shows generated custom properties, and the TypeScript output shows the typed theme object with value, variable, and original fields.

```ts
import { defineTheme } from '@pinceau/theme'

export default defineTheme({
  media: {
    tablet: '(min-width: 768px)',
    desktop: '(min-width: 1024px)',
  },

  color: {
    white: '#FFFFFF',
    black: '#191919',
    primary: '#ED4D31',
    secondary: '#4560B0',
    tertiary: '#FBEFDE'
  },

  space: {
    1: '0.25rem',
    2: '0.5rem',
    3: '0.75rem',
    4: '1rem'
  }
})
```

```css
@media {
  :root {
    --pinceau-mq: initial;
    --space-4: 1rem;
    --space-3: 0.75rem;
    --space-2: 0.5rem;
    --space-1: 0.25rem;
    --color-tertiary: #FBEFDE;
    --color-secondary: #4560B0;
    --color-primary: #ED4D31;
    --color-black: #191919;
    --color-white: #FFFFFF;
    --media-desktop: (min-width: 1024px);
    --media-tablet: (min-width: 768px);
  }
}
```

```ts
export const theme = {
  media: {
    tablet: {
      value: '(min-width: 768px)',
      variable: 'var(--media-tablet)',
      original: '(min-width: 768px)'
    },
    desktop: {
      value: '(min-width: 1024px)',
      variable: 'var(--media-desktop)',
      original: '(min-width: 1024px)'
    }
  },
  color: {
    white: {
      value: '#FFFFFF',
      variable: 'var(--color-white)',
      original: '#FFFFFF'
    },
    black: {
      value: '#191919',
      variable: 'var(--color-black)',
      original: '#191919'
    },
    primary: {
      value: '#ED4D31',
      variable: 'var(--color-primary)',
      original: '#ED4D31'
    },
    secondary: {
      value: '#4560B0',
      variable: 'var(--color-secondary)',
      original: '#4560B0'
    },
    tertiary: {
      value: '#FBEFDE',
      variable: 'var(--color-tertiary)',
      original: '#FBEFDE'
    }
  },
  space: {
    1: {
      value: '0.25rem',
      variable: 'var(--space-1)',
      original: '0.25rem'
    },
    2: {
      value: '0.5rem',
      variable: 'var(--space-2)',
      original: '0.5rem'
    },
    3: {
      value: '0.75rem',
      variable: 'var(--space-3)',
      original: '0.75rem'
    },
    4: {
      value: '1rem',
      variable: 'var(--space-4)',
      original: '1rem'
    }
  }
} as const

export type PinceauTheme = typeof theme

export type PinceauThemePaths = 'media.tablet' | 'media.desktop' | 'color.white' | 'color.black' | 'color.primary' | 'color.secondary' | 'color.tertiary' | 'space.1' | 'space.2' | 'space.3' | 'space.4'

export default theme
```

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

### Basic button styling with css() and theme tokens

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/0.your-first-component.md

Defines the basic styling of a button component using the `css()` function in a scoped `<style lang="ts">` block. It uses local tokens `--button-primary` and `--button-secondary` for the button palette, and references theme tokens like `{radii.lg}` and `{color.primary.600}`. The button uses `<ContentSlot>` instead of `<slot>` to support MDC syntax.

```vue
<template>
  <button class="my-button">
    <span>
      <ContentSlot :use="$slots.default" unwrap="p" />
    </span>
  </button>
</template>

<style scoped lang="ts">
css({
  '.my-button': {
    '--button-primary': '{color.primary.600}',
    '--button-secondary': '{color.primary.500}',
    'display': 'inline-block',
    'borderRadius': '{radii.xl}',
    'transition': '{transition.all}',
    'color': '{color.white}',
    'boxShadow': '0 5px 0 {button.primary}, 0 12px 16px {color.dimmed}',
    'span': {
      display: 'inline-block',
      fontFamily: '{typography.font.display}',
      borderRadius: '{radii.lg}',
      fontSize: '{fontSize.xl}',
      lineHeight: '{lead.none}',
      transition: '{transition.all}',
      backgroundColor: '{button.primary}',
      boxShadow: 'inset 0 -1px 1px {color.dark}',
      padding: '{space.3} {space.6}'
    },
    '&:hover': {
      span: {
        backgroundColor: '{button.secondary}',
      }
    },
    '&:active': {
      span: {
        transform: 'translateY({space.1})'
      }
    }
  }
})
</style>
```

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

### Define media queries in theme configuration

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/2.media-queries.md

Define media queries in your theme config using the `media` key. Values are used as if replacing `*` in `@media * { }` for regular queries, or in `<html class="*">` for root class queries.

```ts
defineTheme({
  media: {
    // @tablet
    tablet: '(min-width: 768px)',
    // @desktop
    desktop: '(min-width: 1024px)',
    // @sepia
    sepia: ':root.sepia'
  },
})
```

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

### Generated utils output from @pinceau/outputs/utils

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/4.utils-properties.md

This is the generated output file that Pinceau creates from the `utils` defined in `theme.config.ts`. It exports the utility functions and a `utils` object, along with a type `PinceauUtils`.

```ts
import { PropertyValue } from '@pinceau/style'

export function px(value: PropertyValue<'padding'>) {
  return {
    paddingLeft: value,
    paddingRight: value,
  }
}

export function mx(value: PropertyValue<'margin'>) {
  return {
    marginLeft: value,
    marginRight: value,
  }
}

export const utils = { px, mx } as const

export type PinceauUtils = typeof utils

export default utils
```

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

### Theme definition and normalized design tokens

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/1.design-tokens.md

Shows the plain key/value theme definition passed to defineTheme and the normalized form where each token is wrapped in a value object. The normalized version is what Pinceau produces internally.

```ts
defineTheme({
  media: {
    tablet: '(min-width: 768px)',
    desktop: '(min-width: 1024px)',
  },

  color: {
    white: '#FFFFFF',
    black: '#191919',
    primary: '#ED4D31',
    secondary: '#4560B0',
    tertiary: '#FBEFDE',
  },

  space: {
    1: '0.25rem',
    2: '0.5rem',
    3: '0.75rem',
    4: '1rem',
  }
})
```

```ts
const theme = {
  media: {
    tablet: {
      value: '(min-width: 768px)'
    },
    desktop: {
      value: '(min-width: 1024px)'
    }
  },
  color: {
    white: {
      value: '#FFFFFF'
    },
    black: {
      value: '#191919'
    },
    primary: {
      value: '#ED4D31'
    },
    secondary: {
      value: '#4560B0'
    },
    tertiary: {
      value: '#FBEFDE'
    }
  },
  space: {
    1: {
      value: '0.25rem'
    },
    2: {
      value: '0.5rem'
    },
    3: {
      value: '0.75rem'
    },
    4: {
      value: '1rem'
    }
  }
}
```

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

### css() with utils property autocomplete

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/1.css-function.md

Shows how utils properties are suggested in the css() function. The comment indicates that 'mx' will be suggested at the position of the asterisk.

```ts
css({
  '.my-button': {
    // Will suggest `mx`
    '*': ''
  }
})
```

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

### Define component styles with css() in a <style lang="ts"> block

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/0.your-first-component.md

Use a `<style lang="ts">` block with the `css()` function to define static and runtime CSS for a component. The `css()` call is parsed by Pinceau and splits between static and runtime styles, so no styling-related JavaScript is shipped unless needed.

```vue
<style lang="ts">
css({
  '.my-button': {
    backgroundColor: '{color.blue.1}',
    padding: '{space.4}'
  }
})
</style>
```

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

### Use Pigments Theme with Pinceau

Source: https://github.com/tahul/pinceau/blob/main/README.md

Vite config using Pinceau's default Pigments theme by setting the theme.layers option to include '@pinceau/pigments'.

```ts
// vite.config.ts
export default defineConfig({
  plugins: [
    Pinceau({
      theme: {
        layers: ['@pinceau/pigments']
      }
    })
  ]
})

```

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

### Use media queries with css() function

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/2.media-queries.md

Use media queries in the `css()` function. The `@dark` and `@md` selectors apply the nested styles when the corresponding media query matches.

```vue
<style lang="ts">
css({
  html: {
    color: '{color.gray.900}'
    padding: '{space.4}'

    '@dark': {
      color: '{color.gray.100}'
    }

    '@md': {
      padding: '{space.8}'
    }
  }
})
</style>
```

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

### Reference a token with $color.blue.5 in defineTheme

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/0.tokens-config.md

Shows how to reference an already defined token using the $ syntax. The primary token points to $color.blue.5, and the reference resolves to var(--color-blue-500).

```ts
defineTheme({
  primary: '$color.blue.5',
  blue: {
    0: '#C5CDE8',
    1: '#B6C1E2',
    2: '#99A8D7',
    3: '#7B8FCB',
    4: '#5E77C0',
    5: '#4560B0',
    6: '#354A88',
    7: '#25345F',
    8: '#161E37',
    9: '#06080F',
  },
})
```

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

### Use ThemeTokens and PropertyValue types

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/3.computed-styles.md

Shows how ThemeTokens and PropertyValue types filter theme tokens and map them to CSS properties.

```ts
defineTheme({
  color: {
    red: 'red',
    green: 'green',
    blue: 'blue',
    primary: {
      1: 'purple',
      2: 'violet'
    }
  }
})

const colors: ThemeTokens<'color'> = *
// All the tokens paths that starts with 'color'

const backgroundColors: PropertyValue<'backgroundColor'> = *
// All the tokens paths are mapped to backgroundColor CSS property

// '*' can be:
// 'color.red' | 'color.green' | 'color.blue'
// | 'color.primary.1' | 'color.primary.2'
```

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

### Usage in Vue template

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/0.your-first-component.md

Shows how to use the MyButton component in a Vue template with different color props.

```vue
<MyButton color="red">
Red button
</MyButton>

<MyButton color="teal">
Teal button
</MyButton>

<MyButton color="blue">
Blue button
</MyButton>
```

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

### Local tokens in css()

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/1.css-function.md

Demonstrates using local CSS custom properties within css(). Local tokens support theme token syntax and computed styles, and are used like theme tokens.

```ts
css({
  '.my-button': {
    // This is a local token
    '--button-primary': '{color.primary.100}',
    // Local tokens also supports Computed Styles
    '--button-secondary': props => `{color.${props.color}.100}`,
    // Local tokens are used like theme tokens
    'backgroundColor': '{button.primary}',
    'color': '{button.secondary}'
  }
})
```

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

### Theme usage in css() with output

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/1.css-function.md

Shows how to use theme tokens inside css() and the compiled CSS output. The token '{color.primary.100}' is resolved to the CSS variable 'var(--color-primary-100)'.

```ts
css({
  '.my-button': {
    backgroundColor: '{color.primary.100}'
  }
})
```

```css
.my-button {
  background-color: var(--color-primary-100);
}
```

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

### Usage of $dt() with defineTheme

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/2.tokens-helper.md

Shows how to define a theme with defineTheme and then use $dt() to reference a token. The first call returns the CSS variable, the second with 'value' returns the raw value.

```ts
defineTheme({
  color: {
    primary: {
      100: 'red'
    }
  }
})

$dt('color.primary.100') // var(--color-primary-100)

$dt('color.primary.100', 'value') // 'red'
```

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

### css() Function

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/1.css-function.md

The css() function is a build-time styling API that accepts a style object, resolves theme tokens to CSS variables, supports utils properties, and compiles static styles to CSS.

```APIDOC
## css() Function

### Description
The `css()` function allows you to write styling in the same language as your `<script>` block. It acts as a build-time feature that resolves theme tokens to their CSS variable values, places utils properties at the same level as other CSS properties, compiles static styling to CSS, and optimizes runtime features.

### Usage
```ts
css({
  '.my-button': {
    backgroundColor: '{color.primary.100}'
  }
})
```

### Parameters
- **styleObject** (object) - Required - A CSS-like object where properties can be theme tokens, utils properties, or local custom properties.

### Theme Usage
Theme tokens can be used anywhere in the `css()` function. They are resolved to their CSS variable value in the theme stylesheet.

```ts
css({
  '.my-button': {
    backgroundColor: '{color.primary.100}'
  }
})
```

Output:
```css
.my-button {
  background-color: var(--color-primary-100);
}
```

### Utils Properties Usage
Utils properties defined in the theme are available at the same level as CSS properties. They are autocompleted and preserve typings.

```ts
defineTheme({
  utils: {
    mx: value => ({ marginRight: v, marginLeft: v })
  }
})

css({
  '.my-button': {
    // Will suggest `mx`
    '*': ''
  }
})
```

Utils properties can also return nested CSS, which will be unwrapped with the key position as root.

### Local Tokens
The `css()` function provides shortcuts to use CSS custom properties. Local tokens are detected by the compiler and support:
- Usage with regular token syntax: `{button.primary}`
- Added to the CSS Prop type for type-safe parent customization
- Autocompletion in the VSCode extension

```ts
css({
  '.my-button': {
    '--button-primary': '{color.primary.100}',
    '--button-secondary': props => `{color.${props.color}.100}`,
    'backgroundColor': '{button.primary}',
    'color': '{button.secondary}'
  }
})
```

### Response
No response is returned; the function is used for styling and compiles to CSS at build time.
```

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

### Use size prop in Vue template

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/0.your-first-component.md

Shows how to use the `size` prop as a string or object in Vue templates. The object form uses media query keys like `initial`, `md`, `lg`, `xl` for responsive sizes.

```vue
<MyButton size="sm">
Small button
</MyButton>

<MyButton size="md">
Medium button
</MyButton>

<MyButton :size="{ initial: 'sm', md: 'md', lg: 'lg', xl: 'xl' }">
Responsive button
</MyButton>
```

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

### Vite config with Pinceau plugin

Source: https://github.com/tahul/pinceau/blob/main/docs/content/0.get-started/1.installation.md

Adds the Pinceau Vite plugin to the Vite config. The plugin is imported from 'pinceau/vite' and accepts an options object.

```ts
import { defineConfig } from 'vite'
import Pinceau from 'pinceau/vite'
import Vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    // https://pinceau.dev
    Pinceau({ ...options }),
    // https://vuejs.org
    Vue(),
  ],
})
```

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

### Configure Pinceau layers in vite.config.ts

Source: https://github.com/tahul/pinceau/blob/main/docs/content/3.advanced/1.multi-layer.md

Configure Pinceau to load additional theme.config files from a custom path. The layers option accepts an array of layer objects, each with a path and an optional configFileName to override the default.

```ts
import { defineConfig } from 'vite'
import Pinceau from 'pinceau/vite'

export default defineConfig({
  plugins: [
    Pinceau({
      theme: {
        layers: [
          {
            // Layer cwd
            path: resolve(__dirname, './theme'),
            // Custom configFileName at layer level
            configFileName: 'theme.config',
          },
        ]
      }
    })
  ]
})
```

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

### Class variants with utility classes

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/4.variants.md

Defines a class variant `size` with utility class strings and `mediaPrefix` option enabled. Classes are added to the component root element.

```ts
<style lang="ts">
css({
  variants: {
    size: {
      sm: 'px-3 py-6',
      md: 'px-6 py-8',
      lg: 'px-8 py-12',
      xl: 'px-12 py-24',
      options: {
        default: 'sm',
        mediaPrefix: true
      },
    },
  },
})
</style>
```

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

### Color scheme modes: Style, Media, and Class

Source: https://github.com/tahul/pinceau/blob/main/docs/content/3.advanced/0.vite-plugin-options.md

Shows the three color scheme modes for the `colorSchemeMode` option: `'media'` (default) uses a `@media` query, `'class'` uses a `.dark` class on `:root`, and the Style input uses `@dark`.

```ts
css({
  '.my-button': {
    'backgroundColor': '{color.gray.100}',
    '@dark': {
      backgroundColor: '{color.gray.900}'
    }
  }
})
```

```css
.my-button {
  background-color: var(--color-gray-100);
}

@media (prefers-color-scheme: dark) {
  .my-button {
    background-color: var(--color-gray-900);
  }
}
```

```css
.my-button {
  background-color: var(--color-gray-100);
}

:root.dark .my-button {
  background-color: var(--color-gray-900);
}
```

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

### Use MyButton component in Vue and MDC syntax

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/0.your-first-component.md

Two ways to use the button component: as a Vue component with props, or with MDC syntax from @nuxt/content. Both pass `color` and `size` props to the button.

```vue
<MyButton color="primary" size="md">
Hello world 🧑‍🎨
</MyButton>
```

```md
::my-button{color="primary" size="md"}
Hello world 🧑‍🎨
::
```

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

### Using enum variants in a Vue component

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/4.variants.md

Shows two ways to use the enum variant: a simple string prop and a responsive object with `initial` and `lg` keys.

```vue
<MyButton size="sm" />

<MyButton :size="{ initial: 'sm', lg: 'xl' }" />
```

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

### Define a CSS prop with cssProp helper

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/5.css-prop.md

Define a component that accepts a `css` prop using the `cssProp` helper. The prop supports selectors and media queries, and should not have a default value.

```vue
<script setup lang="ts">
import { cssProp } from 'vue'

defineProps({
  css: cssProp
})
</script>

<template>
  <div>
    <slot />
  </div>
</template>
```

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

### Define size variants in a Vue component with Pinceau

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/0.your-first-component.md

Adds a `variants` key to the `css()` function and spreads a `variants` object in `defineProps()` to create a type-safe `size` prop. The `size` prop accepts keys like 'sm', 'md', 'lg', 'xl' as string values or an object with media query keys for responsive sizes.

```vue
<script setup lang="ts">
import { computedStyle } from 'pinceau/runtime'

defineProps({
  color: computedStyle<keyof PinceauTheme['color']>('red'),
  ...variants,
})
</script>

<template>
  <button class="my-button">
    <span>
      <ContentSlot :use="$slots.default" unwrap="p" />
    </span>
  </button>
</template>

<style scoped lang="ts">
css({
  '.my-button': {
    ...previousStyling
  },
  'variants': {
    size: {
      sm: {
        span: {
          padding: '{space.3} {space.6}',
        },
      },
      md: {
        span: {
          padding: '{space.6} {space.8}'
        },
      },
      lg: {
        span: {
          padding: '{space.8} {space.12}'
        },
      },
      xl: {
        span: {
          padding: '{space.12} {space.24}'
        },
      },
      options: {
        default: 'sm',
      },
    },
  },
})
</style>
```

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

### Define variants in a Vue component with css()

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/4.variants.md

Shows a complete Vue component with a `<style lang="ts">` block that defines a `size` variant with `sm`, `md`, `lg`, `xl` keys and a default option. The `variants` object is spread into `defineProps()` to generate props.

```vue
<script setup lang="ts">
defineProps({
  ...variants
})
</script>

<template>
  <div>
    <slot />
  </div>
</template>

<style lang="ts">
css({
  variants: {
    size: {
      sm: {
        padding: '{space.3} {space.6}',
      },
      md: {
        padding: '{space.6} {space.8}'
      },
      lg: {
        padding: '{space.8} {space.12}'
      },
      xl: {
        padding: '{space.12} {space.24}'
      },
      options: {
        default: 'sm',
      },
    },
  },
})
</style>
```

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

### Use css() function in Vue component with variants

Source: https://github.com/tahul/pinceau/blob/main/docs/content/0.get-started/0.what-is-pinceau.md

Shows a Vue component using the css() function in a <style lang="ts"> block. It defines a computed style prop and variants for responsive sizing, with token references like '{space.4}'.

```vue
<script setup>
defineProps({
  color: computedStyle<keyof PinceauTheme['color']>('green'),
  ...variants
})
</script>

<template>
  <button class="my-button">
    <slot />
  </button>
</template>

<style lang="ts">
css({
  '.my-button': {
    px: '{space.4}',
    color: 'white',
    backgroundColor: props => `$color.${props.color}.4`,
  },
  'variants': {
    size: {
      sm: {
        padding: '{space.2}'
      },
      md: {
        padding: '{space.3}'
      },
      lg: {
        padding: '{space.4}'
      },
      options: {
        default: 'sm'
      }
    }
  }
})
</style>
```

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

### Use utils in Vue component style block

Source: https://github.com/tahul/pinceau/blob/main/docs/content/1.configuration/4.utils-properties.md

Use the defined utilities inside a Vue component's `<style lang="ts">` block. The utilities are available as CSS properties and will autocomplete with the correct value type.

```vue
<style lang="ts">
css({
  '.my-element': {
    // Will autocomplete with the type of `value` argument of `utils.px`
    px: '{space.4}',
    // Will autocomplete with the type of `value` argument of `utils.mx`
    mx: '{space.2}',
  }
})
</style>
```

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

### Use design tokens in CSS with $dt()

Source: https://github.com/tahul/pinceau/blob/main/docs/content/0.get-started/0.what-is-pinceau.md

Uses the $dt() function inside a <style> block to access design tokens. Supports responsive and dark mode variants with @dark and @desktop at-rules.

```postcss
<style>
button {
  padding: $dt('space.1') $dt('space.2');
  background-color: $dt('red.1');

  @dark {
    background-color: $dt('red.5')
  }

  @desktop {
    padding: $dt('space.2') $dt('space.4');
  }
}
</style>
```

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

### Bind $pinceau class to a nested element

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/4.variants.md

Shows how to manually bind the generated class to a nested element using `:class="$pinceau"` to disable automatic binding on the root element.

```vue
<template>
  <Transition>
    <div :class="$pinceau" />
  </Transition>
</template>
```

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

### Boolean variants with true/false keys

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/4.variants.md

Defines boolean variants `transparent` and `rounded` with `true` and `false` keys. The `rounded` variant has a default of `true`. This generates Boolean props.

```ts
css({
  variants: {
    transparent: {
      true: {
        backgroundColor: 'transparent'
      }
    },
    rounded: {
      true: {
        borderRadius: '{space.4}',
      },
      false: {
        borderRadius: '{space.0}'
      },
      options: {
        default: true
      }
    }
  }
})
```

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

### Using boolean variants in a Vue component

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/4.variants.md

Shows how to use the boolean variants in a Vue template: `transparent` as a boolean prop and `rounded` with a responsive object.

```vue
<MyButton transparent :rounded="{ initial: false, xl: true }" />
```

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

### Enum variants with string keys

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/4.variants.md

Defines an enum variant `size` with string keys `sm`, `md`, `lg`, `xl` and a default option. This generates a string prop with a union type.

```ts
<style lang="ts">
css({
  variants: {
    size: {
      sm: {
        padding: '{space.3} {space.6}',
      },
      md: {
        padding: '{space.6} {space.8}'
      },
      lg: {
        padding: '{space.8} {space.12}'
      },
      xl: {
        padding: '{space.12} {space.24}'
      },
      options: {
        default: 'sm',
      },
    },
  },
})
</style>
```

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

### Disable Nuxt extends support in nuxt.config.ts

Source: https://github.com/tahul/pinceau/blob/main/docs/content/3.advanced/1.multi-layer.md

Disable the automatic pushing of Nuxt extends layers into Pinceau's layers. Set the pinceau.extends option to false in nuxt.config.ts to prevent this behavior.

```ts
export default defineNuxtConfig({
  modules: ['pinceau/nuxt'],
  pinceau: {
    extends: false
  }
})
```

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

### Define a typed computedStyle prop with generic

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/3.computed-styles.md

Defines a typed computedStyle prop with a generic type for autocompletion and a default value of 'primary'.

```vue
<script setup>
import { computedStyle } from 'pinceau/runtime'

defineProps({
  color: computedStyle<keyof PinceauTheme['color']>('primary')
})
</script>
```

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

### Define a computed style prop with default value

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/3.computed-styles.md

Defines a component prop with a default value using computedStyle and uses it in a computed style to set the background color.

```vue
<script setup>
import { computedStyle } from 'pinceau/runtime'

defineProps({
  color: computedStyle('red')
})
</script>

<style scoped lang="ts">
css({
  '.my-button': {
    backgroundColor: props => props.color
  }
})
</style>
```

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

### Button component with computed color prop

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/0.your-first-component.md

Defines a button component with a color prop using computedStyle, and uses computed styles in the css() function to set CSS custom properties based on the color prop.

```vue
<script setup lang="ts">
import { computedStyle } from 'pinceau/runtime'

defineProps({
  color: computedStyle<keyof PinceauTheme['color']>('red'),
})
</script>

<template>
  <button class="my-button">
    <span>
      <ContentSlot :use="$slots.default" unwrap="p" />
    </span>
  </button>
</template>

<style scoped lang="ts">
css({
  '.my-button': {
    '--button-primary': props => `{color.${props.color}.600}`,
    '--button-secondary': props => `{color.${props.color}.500}`,
    ...previousStyling
  }
})
</style>
```

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

### Use computed style with CSS custom property

Source: https://github.com/tahul/pinceau/blob/main/docs/content/2.styling/3.computed-styles.md

Uses a computed style to set a CSS custom property and a background color from a prop.

```vue
<style lang="ts">
css({
  '.my-button': {
    '--my-button-color': props => props.color,
    'backgroundColor': '{my.button.color}',
  }
})
</style>
```
Tokens:
Raw