API

Discover how to create and use your tokens with @nuxtjs/design-tokens API.

tokens are a Design Tokens format compatible object definition that gets processed by Style Dictionary.

This allows the options defined by the theme author in his designTokens.tokens key to be type-safe for the theme user that will configure his theme via the same key or a tokens.config file.

Defining theme tokens

There is two ways to define theme tokens:

  • Via the designTokens.tokens key in the nuxt.config file.
  • Via the tokens.config.{js|ts} file at the root of your project.

Both of these options will be merged in the end.

These two ways will both work for theme authors and theme users as they will get processed in order of priority (user configuration > theme defaults).

tokens.config.ts
import { defineTokens } from '@nuxtjs/design-tokens'export default defineTokens({  colors: {    primary: {      value: 'green'    },    secondary: {      value: 'yellow'    },  }})
nuxt.config.ts
import { defineNuxtConfig } from 'nuxt'export default defineNuxtConfig({  designTokens: {    tokens: {      colors: {        primary: {          value: 'green'        },        secondary: {          value: 'yellow'        },      },    }  }})

Consuming theme tokens

Theme tokens gets processed by Style Dictionary and generates build targets that are globally accessible in your Nuxt project.

  • .nuxt/theme/
    • tokens.css global CSS variables injected to your Nuxt <head>.
    • tokens.scss for scss contexts.
    • tokens.json if you want to import it from a JSON context.
    • index.ts to import it from runtime or from any TypeScript context.
    • index.js to import it from runtime or from any JavaScript context.
    • types.d.ts for global type inference ($dt(), $tokens(), useTokens(), defineTokens, nuxt.config.designTokens.tokens).
  • Composable usage
    const { $dt } = useTokens()const primaryColor = $dt('colors.primary')
  • <template> usage
    <template><div :style="{ backgroundColor: $dt('colors.primary') }">  Hello World</div></template>
  • <style usage
    <style lang="postcss" scoped>.header {  background-color: v-bind($dt('colors.primary'));}</style>
  • import usage
    tailwind.config.ts
    import { $dt } from '@nuxtjs/design-tokens'export default {  theme: {    extend: {      colors: {        primary: $dt('colors.primary')      }    }  }}
  • server usage
    server/api/token.ts
    import { $dt } from '#design-tokens'export default defineHandler(() => {  return $dt('colors.base')})

Guide

Get Started