@frontiers/tailwind-plugin

A Tailwind CSS 4 plugin that extends tailwindcss-primeui with custom utilities and seamlessly integrates PrimeVue design tokens with Tailwind's utility class system.

Overview

This plugin extends tailwindcss-primeui and is designed to work with PrimeVue components and the @frontiers/prime-preset theme. It bridges PrimeVue's color system with Tailwind CSS 4, allowing you to use PrimeVue's theme colors directly in Tailwind utility classes. It maps all PrimeVue color palettes (green, red, gray, purple, cyan, orange, blue) to Tailwind's color system, provides custom typography and elevation utilities, and sets Museo Sans as the default sans-serif font.

Purpose

• Extends tailwindcss-primeui - Builds upon the PrimeUI Tailwind plugin with additional utilities
• PrimeVue Integration - Designed specifically for use with PrimeVue components
• Frontiers Theme - Works seamlessly with @frontiers/prime-preset theme for PrimeVue
• Brink Design System Utilities - Adds 72 typography and 50 elevation utilities from Brink Design System, adapted as Tailwind 4 utilities

🤖 Using an AI agent / LLM? A complete, auto-generated inventory of every utility in this package (all typography, elevation, color, and breakpoint tokens) lives in AGENTS.md. It ships inside the published package, so consumers can always read it at node_modules/@frontiers/tailwind-plugin/AGENTS.md. It also includes a From Figma section that maps Figma style names 1:1 to utilities for design-to-code via the Figma MCP.

Installation

Install the plugin along with its peer dependencies:

# Install all required dependencies
pnpm add @frontiers/tailwind-plugin tailwindcss-primeui @primeuix/themes

# Install PrimeVue and the Frontiers theme preset
pnpm add primevue @frontiers/prime-preset

Note: This plugin extends tailwindcss-primeui and is designed to work with PrimeVue components using the @frontiers/prime-preset theme.

Usage

Full Import (Theme + Typography)

Import everything in your main CSS file:

@import "tailwindcss";
@import "@frontiers/tailwind-plugin";

This imports theme (colors & fonts), typography utilities, and elevation shadows.

Modular Imports

Import only what you need:

@import "tailwindcss";

/* Theme only (PrimeVue colors + Museo Sans font) */
@import "@frontiers/tailwind-plugin/theme";

/* Typography only (72 utility classes) */
@import "@frontiers/tailwind-plugin/typography";

/* Elevation only (50 shadow utilities) */
@import "@frontiers/tailwind-plugin/elevation";

/* Or import selectively */
@import "@frontiers/tailwind-plugin/theme";
@import "@frontiers/tailwind-plugin/typography";
@import "@frontiers/tailwind-plugin/elevation";

Features

✍️ Typography Utilities

Custom typography utilities based on the Brink Design System, adapted as Tailwind 4 utilities for consistent text styling:

• Headings (f-heading-*) - 6 sizes (xs-2xl) with 3 weights each (light, semibold, bold)
• Display (f-display-*) - 6 sizes (xs-2xl) with 2 weights (light, semibold)
• Body (f-body-*) - 4 sizes (sm-xl) with regular and tall line heights
• Labels (f-label-*) - 4 sizes (xs-lg) with 2 weights
• Buttons (f-button-*) - 3 sizes (sm-lg), bold (700)
• Links (f-link-*) - 2 sizes (sm, md), bold (700); also available as plural aliases f-links-* for Figma token-name parity
• Quotes (f-quote-*) - 2 sizes (sm, lg)
• Fluid Headings (f-fluid-heading-*) - Responsive typography that scales with viewport

Total: 72 typography utility classes (from Brink Design System; includes 2 plural f-links-* aliases)

🎨 PrimeVue Color Integration

All PrimeVue color palettes are mapped to Tailwind:

• Green (green-50 through green-950)
• Red (red-50 through red-950)
• Gray (gray-50 through gray-950)
• Purple (purple-50 through purple-950)
• Cyan (cyan-50 through cyan-950)
• Orange (orange-50 through orange-950)
• Blue (blue-50 through blue-950)

🔤 Custom Font

Sets Museo Sans as the default sans-serif font family.

📐 Responsive Breakpoints

Custom breakpoints aligned with the Brink Design System:

| Breakpoint | Size | Pixels | Use Case | | ---------- | -------- | -------- | --------------------------- | | sm | 40rem | 640px | Mobile landscape | | md | 48rem | 768px | Tablets | | lg | 64rem | 1024px | Small laptops | | xl | 80rem | 1280px | Desktops | | 2xl | 90rem | 1440px | Large desktops | | 3xl | 120rem | 1920px | Extra large screens / 1080p |

🎭 Elevation Utilities

Custom shadow utilities based on the Brink Design System, adapted as Tailwind 4 utilities for depth and elevation effects:

• Light Shadows (elevation-light-*) - Subtle shadows for light themes
• Dark Shadows (elevation-dark-*) - Pronounced shadows for emphasis

Positions: top, center, bottom, right, left
Intensities: 10, 20, 30, 40, 50 (increasing depth)

Total: 50 elevation utility classes (from Brink Design System)

Example class names:

• elevation-light-bottom-20 - Light shadow below element
• elevation-dark-center-30 - Dark shadow around element
• elevation-light-top-10 - Subtle light shadow above element

Examples

Using Typography Utilities

<!-- Headings -->
<h1 class="f-heading-2xl-bold">Main Heading</h1>
<h2 class="f-heading-xl-semibold">Section Heading</h2>
<h3 class="f-heading-lg">Subsection</h3>

<!-- Display Text (Hero sections) -->
<h1 class="f-display-xl-semibold">Large Hero Title</h1>
<p class="f-display-xs">Impressive subtitle</p>

<!-- Body Text -->
<p class="f-body-lg">Large body text for readability</p>
<p class="f-body-md-tall">Regular body with comfortable line height</p>
<p class="f-body-sm">Small descriptive text</p>

<!-- Labels -->
<label class="f-label-md-semibold">Form Label</label>
<span class="f-label-sm">Helper text</span>

<!-- Buttons -->
<button class="f-button-lg bg-blue-500 text-white px-6 py-3">
  Large Button
</button>

<!-- Links -->
<a href="#" class="f-link-md text-blue-600">Medium Link</a>

<!-- Fluid Typography (Responsive) -->
<h1 class="f-fluid-heading-2xl">
  Scales from 1.5rem on mobile to 2.5rem on large screens
</h1>

Using Elevation Utilities

<!-- Light Shadows (for light backgrounds) -->
<div class="bg-white elevation-light-bottom-20 rounded-lg p-6">
  Card with subtle bottom shadow
</div>

<!-- Dark Shadows (for emphasis) -->
<div class="bg-white elevation-dark-center-30 rounded-lg p-6">
  Card with pronounced shadow
</div>

<!-- Directional Shadows -->
<div class="bg-white elevation-light-right-20 rounded-lg p-6">
  Shadow on the right side
</div>

<div class="bg-white elevation-light-top-10 rounded-lg p-6">
  Subtle shadow above (inverted)
</div>

<!-- Different Intensities -->
<div class="bg-white elevation-light-bottom-10 rounded-lg p-4">Light</div>
<div class="bg-white elevation-light-bottom-30 rounded-lg p-4">Medium</div>
<div class="bg-white elevation-light-bottom-50 rounded-lg p-4">Heavy</div>

Using PrimeVue Colors

<!-- Background colors -->
<div class="bg-green-500 text-white">Success message</div>
<div class="bg-red-500 text-white">Error message</div>
<div class="bg-blue-500 text-white">Info message</div>

<!-- Text colors -->
<p class="text-purple-600">Purple text</p>
<p class="text-cyan-500">Cyan text</p>
<p class="text-orange-700">Orange text</p>

<!-- Border colors -->
<div class="border border-gray-300">Bordered content</div>
<div class="border-2 border-green-500">Green border</div>

<!-- Hover states -->
<button class="bg-blue-500 hover:bg-blue-600 text-white px-4 py-2">
  Hover me
</button>

Using with PrimeVue Components

This plugin is designed to work seamlessly with PrimeVue components and the @frontiers/prime-preset theme:

<template>
  <div class="p-6">
    <!-- PrimeVue components styled with custom typography -->
    <h1 class="f-heading-2xl-bold mb-6">Dashboard</h1>

    <!-- PrimeVue Button with Tailwind utilities -->
    <Button label="Primary" class="mr-2" />

    <!-- PrimeVue Card with elevation utilities -->
    <Card class="elevation-light-bottom-20">
      <template #title>
        <h2 class="f-heading-lg-semibold text-gray-900">Card Title</h2>
      </template>
      <template #content>
        <p class="f-body-md text-gray-600">
          Using PrimeVue components with @frontiers/prime-preset theme and
          custom Tailwind utilities from this plugin!
        </p>
      </template>
    </Card>
  </div>
</template>

<script setup>
// Using @frontiers/prime-preset theme
import { usePrimeVue } from "primevue/config"
import FrontiersPreset from "@frontiers/prime-preset"

const PrimeVue = usePrimeVue()
PrimeVue.config.theme = {
  preset: FrontiersPreset,
}
</script>

Responsive Design with Custom Breakpoints

Use the custom breakpoints for responsive layouts:

<!-- Color changes at each breakpoint -->
<div
  class="bg-blue-500 md:bg-green-500 lg:bg-purple-500 xl:bg-cyan-500 2xl:bg-orange-500 3xl:bg-red-500 text-white p-4">
  Colors change at different breakpoints
</div>

<!-- Responsive typography -->
<h1 class="f-heading-md sm:f-heading-lg md:f-heading-xl lg:f-heading-2xl-bold">
  Responsive heading
</h1>

<!-- Responsive grid layout -->
<div
  class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4 3xl:grid-cols-5 gap-4">
  <!-- Grid items -->
</div>

<!-- Container widths -->
<div
  class="w-full lg:max-w-4xl xl:max-w-5xl 2xl:max-w-6xl 3xl:max-w-7xl mx-auto">
  Content container
</div>

Dark Mode Support

<div class="bg-gray-100 dark:bg-gray-900 text-gray-900 dark:text-gray-100">
  Adapts to dark mode
</div>

How It Works

The plugin uses Tailwind CSS 4's @theme inline directive to map PrimeVue CSS custom properties to Tailwind's color system:

@theme inline {
  --color-green-500: var(--p-green-500);
  --color-red-500: var(--p-red-500);
  /* ... and so on for all colors */
}

This means:

• ✅ Colors stay in sync with your PrimeVue theme
• ✅ Single source of truth for colors
• ✅ Use Tailwind utilities with PrimeVue's design system
• ✅ No duplicate color definitions

Because the colors resolve from the live --p-* variables, switching the PrimeVue theme at runtime updates every Tailwind utility automatically — no rebuild, no duplicated palette:

import { usePrimeVue } from "primevue/config"

const PrimeVue = usePrimeVue()
// Every `bg-*` / `text-* `/ `border-*` utility using these palettes follows the new theme.
PrimeVue.changeTheme("current-theme", "new-theme", "theme-link")

Usage Tips & Best Practices

Typography

• Reach for a single f-* class instead of stacking text-* font-* leading-*.
• Use f-body-md / f-body-lg for most running text; use the -tall variants for long-form paragraphs.
• Use f-fluid-heading-* when a heading should scale across breakpoints.
• semibold for emphasis, bold for strong emphasis.

Colors

• Prefer the semantic tokens from the preset (primary, surface) for theme-aware UI; use the named palettes (green, red, …) for fixed intents.
• Shade guidance: 50–200 for backgrounds, 300–500 for borders, 600–900 for text.
• Hover/active: go one shade darker on hover, two on active.
• Never hardcode hex values (bg-[#22c55e]) when a token exists.

Elevation

• Intensity guide: 10 hover states · 20 cards/panels · 30 dropdowns & popovers · 40 modals & dialogs · 50 maximum depth (overlays).
• Position guide: bottom for most cards/floating elements · center for modals/centered overlays · top for inverted shadows on sticky headers · right/left for sidebars and slide-out panels.
• Use light shadows for subtle depth, dark shadows for emphasis; pair with rounded-lg/rounded-xl.

From Figma (design-to-code)

The UX team maintains these primitives as Figma styles. When implementing a design pulled through the Figma MCP, map Figma styles to utilities instead of copying raw CSS.

• Typography maps 1:1 — the class is the Figma style name prefixed with f-:

<!-- Figma style "heading-2xl-bold"  -->
<h1 class="f-heading-2xl-bold">…</h1>
<!-- Figma style "body-md-tall"      -->
<p class="f-body-md-tall">…</p>
<!-- Figma style "label-sm-semibold" -->
<span class="f-label-sm-semibold">…</span>
<!-- Figma style "link-md" (plural f-links-md also works) -->
<a class="f-link-md underline">…</a>
<!-- "…-underline" Figma styles = compose with Tailwind `underline` -->

• Elevation maps 1:1 — use the matching elevation-{mode}-{position}-{intensity} class, not a raw box-shadow.
• Colors do NOT map 1:1 — Figma uses UX palette steps (0–90) with different values, so a Figma shade number is not the same Tailwind number (Figma …/50 → …-600). Never copy a Figma hex or shade number; convert, then map by intent: brand fill → bg-primary, near-white background → bg-surface-0, body text → text-surface-900, borders → border-surface-200.

Scheme palette conversion (blue, red, orange, purple, green, cyan):

| Figma | 0 | 5 | 10 | 20 | 30 | 40 | 50 | 55 | 60 | 70 | 80 | 90 | | ----- | ---- | ----- | ----- | ----- | ----- | ----- | ----- | ---- | ----- | ----- | ----- | ----- | | Token | 50 | 100 | 200 | 300 | 400 | 500 | 600 | — | 700 | 800 | 900 | 950 |

See the AGENTS.md From Figma section for the full conversion tables (scheme palettes, grey/surface, and semantic tokens) and the color caveats.

💡 For the complete, always-accurate list of every f-*, elevation-*, color, and breakpoint token, see AGENTS.md.

Maintaining the agent catalog

AGENTS.md is generated from the source CSS (src/theme.css, src/typography.css, src/elevation.css) by scripts/generate-catalog.mjs, so it can never drift from the utilities the package ships. It's committed to the repo (alongside README.md / CHANGELOG.md) and ships at node_modules/@frontiers/tailwind-plugin/AGENTS.md.

Whenever you change the utilities in src/*.css, regenerate it:

# Regenerates AGENTS.md from src/*.css
pnpm build

Note: this is a CSS-only package — it publishes src/ directly (no build artifact). pnpm build only regenerates the committed AGENTS.md; commit the result alongside your CSS change.

Requirements

• Tailwind CSS >= 4.0.0
• @primeuix/themes >= 1.0.0 (provides the --p-* CSS variables)
• tailwindcss-primeui >= 0.3.0 (PrimeUI Tailwind CSS plugin)

Color Reference

All colors follow the standard Tailwind scale (50-950):

| Palette | Classes | PrimeVue Variables | | ------- | --------------------------- | ------------------ | | Green | green-50 to green-950 | --p-green-* | | Red | red-50 to red-950 | --p-red-* | | Gray | gray-50 to gray-950 | --p-gray-* | | Purple | purple-50 to purple-950 | --p-purple-* | | Cyan | cyan-50 to cyan-950 | --p-cyan-* | | Orange | orange-50 to orange-950 | --p-orange-* | | Blue | blue-50 to blue-950 | --p-blue-* |

Each palette has 11 shades: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950

Font Family

The plugin sets Museo Sans as the default sans-serif font:

<p class="font-sans">This text uses Museo Sans</p>

Font stack:

"Museo Sans", "MuseoSans", ui-sans-serif, system-ui, sans-serif, ...

Framework Integration

Vue 3 / Nuxt

<!-- app.vue or nuxt.config.ts -->
<style>
@import "tailwindcss";
@import "@frontiers/tailwind-plugin";
</style>

React / Next.js

/* app/globals.css */
@import "tailwindcss";
@import "@frontiers/tailwind-plugin";

Vite

/* src/main.css */
@import "tailwindcss";
@import "@frontiers/tailwind-plugin";

Benefits

1. Extends tailwindcss-primeui - Builds on the base PrimeUI plugin with additional utilities
2. Frontiers Design System - Designed for @frontiers/prime-preset theme and PrimeVue components
3. Brink Design System Utilities - 72 typography and 50 elevation utilities from Brink Design System, converted to Tailwind 4 utilities
4. Consistent Design - Use the same colors across PrimeVue components and Tailwind utilities
5. Theme Integration - Colors automatically update when you change PrimeVue themes
6. Developer Experience - Familiar Tailwind syntax with PrimeVue colors
7. No Duplication - Single source of truth for color values (from @frontiers/prime-preset)
8. Zero Runtime - Pure CSS, no JavaScript overhead

Troubleshooting

Colors not showing up?

Make sure:

1. You're using Tailwind CSS v4.0+
2. @primeuix/themes is installed and configured
3. tailwindcss-primeui is installed
4. PrimeVue CSS variables (--p-*) are available in your app
5. The plugin is imported after Tailwind in your CSS

Different colors than expected?

The colors come from your PrimeVue theme configuration. To change colors, update your PrimeVue theme preset.

License

ISC

Author

Alexis Reina