Pinceau Documentation

Pinceau is a typed styling API designed to make <script> blocks lighter and <style> blocks smarter. It is built for modern design systems and provides:

• Typed Styling API: Inspired by Stitches, allowing for component-based styling ($styled.a), scoped CSS (styled), and global CSS (css).
• Design Token Support: Multi-layer configuration compatible with Design Tokens community standards.
• Vite Integration: Plug & play support for Vue, React, Svelte, Nuxt, and Astro.
• Robust Design System Tools: Includes responsive variants, style composition, style colocation, and runtime theme swapping.
• SSR Optimized: Ready for Server-Side Rendering with optimized hydration and no JS/CSS duplication.
• Developer Experience: Includes a VSCode extension for enhanced DX.

The colorSchemeMode option determines how Pinceau handles dark/light mode. You can choose between 'media' (using CSS media queries) or 'class' (using a CSS class like .dark on a root element).

• 'media' mode: Uses @media (prefers-color-scheme: dark).
• 'class' mode: Uses a selector like :root.dark.

/* Example of 'class' mode output */
.my-button {
  background-color: var(--color-gray-100);
}

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

While you can define tokens as simple key/value pairs (e.g., myColor: 'red'), you can also use the explicit object syntax (e.g., myColor: { value: 'red' }). Using the value object is optional and has no impact on outputs if used alone, but it becomes useful when you need to:

• Use other Design Token attributes for later consumption.
• Use the $schema key for a specific token.
• Synchronize with tokens generated by external tools like Figma Tokens.
• Maintain a specific organizational preference.

// Explicit value syntax
myColor: { value: 'red' }

// Simple syntax (automatically normalized to the above)
myColor: 'red'

Pinceau integrates Utils properties directly into the css() function. When you define a utility in your theme, it is treated as a first-class property with full TypeScript autocomplete support.

If a utility returns nested CSS, the compiler unwraps it using the key position as the root.

Example Theme Definition:

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

Usage in css():

css({
  '.my-button': {
    // 'mx' will be suggested by autocomplete
    mx: 2
  }
})

The extension monitors your code for token usage using both the string syntax '{your.token}' and the function syntax $dt('your.token').

If a token's origin cannot be found within your loaded Pinceau configurations, the extension will flag it as a warning in the VSCode Problems panel.

You can customize this behavior in your VSCode settings to either change the severity level of the warning or disable the check entirely.

// Supported syntaxes for detection:
'{your.token}'
$dt('your.token')

To make component styles react to props, use Computed Styles. This involves two steps:

1. Define the prop using computedStyle: Import computedStyle from pinceau/runtime and use it within defineProps. You can provide a type (e.g., keyof PinceauTheme['color']) and a default value.
2. Use arrow functions in css(): Instead of static values, pass an arrow function to the CSS property. This function receives the props object and returns a token string.

Example:

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

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

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

The CSS prop automatically has the local tokens defined within a component injected into it. This allows parent components to easily override a component's internal design tokens by passing them through the css prop.

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