Tailwind CSS Plugin • Wedges Documentation

Wedges provides a Tailwind CSS plugin enabling the use of Wedges design tokens and creation of custom themes in your projects. This plugin is inspired and based on the awesome tw-colors plugin.

Tailwind CSS supports dark mode, but with Wedges, you can create an unlimited number of custom themes. There's no cap on the themes and colors you can use, and it even supports nested themes for more complex use cases.

Installation

If you haven't installed Tailwind CSS already, follow the instructions in the official Tailwind CSS installation guide.

Once Tailwind CSS is installed, update your tailwind.config file to add the necessary configuration for Wedges:

tailwind.config.ts

import { wedgesTW } from "@lemonsqueezy/wedges";
import type { Config } from "tailwindcss";
 
const config: Config = {
  content: [
    // ...
    "node_modules/@lemonsqueezy/wedges/dist/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {},
  darkMode: "class",
  plugins: [wedgesTW()],
};
 
export default config;

Configuration

Plugin Options

The wedgesTW plugin accepts a configuration object allowing you to customize the plugin's behavior. This is the default structure of the configuration object:

tailwind.config.ts

import { wedgesTW } from "@lemonsqueezy/wedges";
import type { Config } from "tailwindcss";
 
const config: Config = {
  content: [
    // ...
    "node_modules/@lemonsqueezy/wedges/dist/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {},
  darkMode: "class",
  plugins: [
    wedgesTW({
      prefix: "wg", // prefix used for CSS variables
      defaultTheme: "light", // default theme
      defaultExtendTheme: "light", // default theme to extend when creating custom themes
      fontSmooth: "antialiased", // specify font smoothing for Wedges components
      themes: {
        light: {
          colors: {}, // light themable colors
        },
        dark: {
          colors: {}, // dark themable colors
        },
        // ... custom themes
      },
    }),
  ],
};

Type

The configuration object type is defined as follows:

type WedgesOptions = {
  /**
   * The prefix for CSS variables.
   * @default "wg"
   */
  prefix?: string;
 
  /**
   * The theme definitions.
   */
  themes?: ConfigThemes;
 
  /**
   * The default theme to use.
   * @default "light"
   */
  defaultTheme?: DefaultThemeType;
 
  /**
   * The default theme to extend. Available values are "light" and "dark".
   * @default "light"
   */
  defaultExtendTheme?: "light" | "dark";
 
  /**
   * Specifies whether or not to apply font anti-aliasing to Wedges components.
   *
   * If set to `antialiased` (default), Wedges components will have anti-aliasing applied to them.
   * If set to `inherit`, no specific styles will be set for text anti-aliasing.
   *
   * * @default "antialiased"
   */
  fontSmooth?: "antialiased" | "inherit";
};

type ConfigTheme = {
  /**
   * Whether to extend 'dark' or 'light' theme.
   * @default "light"
   */
  extend?: "light" | "dark";
 
  /**
   * Defines an extended colors object, providing a flexible foundation for theming or custom color configurations.
   *
   * Key Features:
   * 1. **Themable Colors**: Customize or extend existing themes by overriding values in the `wedgesPalette`.
   * 2. **Custom Colors**: Introduce new color schemes by adding unique key-value pairs.
   * 3. **Nested Colors**: Allows for the grouping of color variations under a single key, facilitating organized and hierarchical color definitions.
   * 4. **Prefix 'wg'**: The colors defined in `wedgesPalette` are prefixed with 'wg' to prevent conflicts with the standard Tailwind color palette, ensuring a seamless integration.
   *
   * @example
   * colors: {
   *   'wg-red': '#ff0000',
   *   customColor: {
   *     500: '#f0f0f0',
   *     600: '#0d0d0d',
   *   },
   * }
   */
  colors?: Partial<ThemableColors> | Record<string, string | Record<string, string>>;
};

API Reference

Option	Value	Default
`defaultExtendTheme`	`"light" \| "dark"`	`"light"`
`defaultTheme`	`DefaultThemeType`	`"light"`
`fontSmooth`	`"antialiased" \| "inherit"`	`"antialiased"`
`prefix`	`string`	`"wg"`
`themes`	`ConfigThemes`	`{}`

Nested Themes

Wedges supports nested themes, enabling the use of multiple themes within individual sections for flexible styling.

<html class="light">
  ...
  <div class="dark">...</div>
  <div class="orange-blue">...</div>
  <!-- custom theme -->
</html>