Tailwind Theme Tokens 🪙

Nuxt module for generating Tailwind theme variables using structured design tokens.

Features

• 🎨 Tailwind CSS v4
• 🚀 Powered by Style Dictionary
• 📦 Ready-to-use design tokens structure to share with your design team
• 🎛️ Manages primitive, theme and breakpoint tokens

Get Started

Installation

Add the module to your nuxt.config.ts and configure it with the tailwindTokens configuration key

export default defineNuxtConfig({
  modules: ['@digital-retex/twind-design-tokens'],
  tailwindTokens: {
    //Options
  },
})

That's it! You can now use the Tailwind Theme Tokens in your Nuxt app ✨

Configuration

To configure the tailwind tokens module, you can use the tailwindTokens key in your nuxt.config.ts.

export default defineNuxtConfig({
  tailwindTokens: {
    //Options
  },
})

cwd

The cwd option allows you to specify the current working directory for the module.

export default defineNuxtConfig({
  tailwindTokens: {
    cwd: fileURLToPath(new URL('./', import.meta.url)),
  },
})

jsonFiles

Default: ['tokens.json']

The jsonFiles option allows you to specify the JSON files that contain the design tokens.

export default defineNuxtConfig({
  tailwindTokens: {
    jsonFiles: ['input.json'],
  },
})

tokens

The tokens option allows you to specify the names of the token collections and their default values.

export default defineNuxtConfig({
  tailwindTokens: {
    tokens: {
      primitive: {
        // Options
      },
      theme: {
        // Options
      },
      breakpoint: {
        // Options
      },
    },
  },
})

tokens.primitive

export default defineNuxtConfig({
  tailwindTokens: {
    tokens: {
      primitive: {
        name: 'primitive',
      },
    },
  },
})

tokens.primitive.name

Default: primitive

Defines the name of the primitive token collection.

tokens.theme

The tokens.theme option allows you to specify the name of the theme token collection, the default theme name, and whether to handle multiple themes.

export default defineNuxtConfig({
  tailwindTokens: {
    tokens: {
      theme: {
        name: 'theme',
        isMultiTheme: true,
        default: 'neutral',
      },
    },
  },
})

tokens.theme.name

Default: theme

Defines the name of the theme token collection.

tokens.theme.isMultiTheme

Default: true

Specifies whether multiple themes should be supported.

tokens.theme.default

Default: neutral

Sets the default theme name. This optionshas no effect when tokens.theme.isMultiTheme is set to false.

tokens.breakpoint

export default defineNuxtConfig({
  tailwindTokens: {
    tokens: {
      breakpoint: {
        name: 'breakpoint',
        screens: {
          sm: 640,
          md: 768,
          lg: 1024,
          xl: 1280,
        },
      },
    },
  },
})

tokens.breakpoint.name

Default: breakpoint

Defines the name of the breakpoint token collection.

tokens.breakpoint.screens

Default: { sm: 640, md: 768, lg: 1024, xl: 1280 }

Specifies the valid breakpoints.

[!IMPORTANT] Only these breakpoints will be used to generate responsive classes. Please ensure they are correctly referenced in your JSON file.

output

The output option allows you to specify the output configuration for the generated CSS file.

export default defineNuxtConfig({
  tailwindTokens: {
    output: {
      //Options
    },
  },
})

output.destination

Default: style.css

Specifies the destination path for the generated CSS file.

output.tailwindImport

Default: true

Determines whether to include the Tailwind import statement in the generated CSS file.

output.transforms

Default: []

Specifies the transformation rules for token names. Those rules are used to convert token names to Tailwind-compatible syntax. You can find the default rules in the transform.yaml file.

export default defineNuxtConfig({
  tailwindTokens: {
    output: {
      transforms: [
        { from: 'spacing-gap', to: 'gap' },
        { from: 'spacing-margin', to: 'grid-system-spacing-x' },
        { from: 'spacing-gutter', to: 'grid-system-gutter-x' },
        { from: 'grids-columns', to: 'grid-system-columns' },
      ],
    },
  },
})

output.disableDefaultTransforms

Default: false

Specifies whether to disable the default transformation rules.

output.filters

Default: []

Specifies the tokens to be excluded from the final output. The syntax is based on gitignore.

output.formatter

Specifies a function to format the generated CSS file using your project's preferred styling tool, such as Prettier or Biome. This function can be customized to ensure consistent code formatting. It takes destinationPath as an argument and does not return anything.

Here is an example of what the formatter configuration could look like when using Prettier:

import { format } from 'prettier'
export default defineNuxtConfig({
  tailwindTokens: {
    output: {
      formatter: async destinationPath => {
        try {
          const output = await fs.readFile(destinationPath, { encoding: 'utf-8' })
          const outputFormatted = await format(output, {
            parser: 'css',
            filepath: destinationPath,
          })
          await fs.writeFile(destinationPath, outputFormatted)
        } catch (error) {
          console.error(`Failed to format the file at ${destinationPath}:`, error)
        }
      },
    },
  },
})

Documentation

While working locally and running the development server, you can access the documentation for the generated tokens. Simply navigate to the /token-doc route to view the classes that have been generated. This allows you to easily trace the design tokens back to their corresponding CSS variables and Tailwind utility classes.

How to use the module

To use the generated tokens in your Nuxt app, import the JSON file and utilize the tokens as you would with any other Tailwind utility class.

To export the tokens to a JSON file, we recommend using the Figma Tokens plugin.

Once you have the JSON file, visit the local route /token-doc to view the generated tokens and learn how to use them.

Design tokens

The main idea behind this module is to import Figma tokens directly into your project and start using them by referencing the tailwind class utilities. Given a json file, the module will generate a css file containing the necessary Tailwind configuration.

Before using this module, we recommend aligning with your design team on the required design token structure.

We expect Figma tokens to be structured in three collections:

• Primitive: contains all the primitive tokens;
• Theme: contains all the theme tokens, which change across different brand themes;
• Breakpoint: contains all the breakpoint tokens, which adapt to different screen sizes.