ub-tailwind

---
name: ub-tailwind
description: Use this skill for Tailwind setup, migration, integration, and utility-first styling. Apply it when the task mentions Tailwind directives or utilities, @import "tailwindcss", @theme, plugin wiring, legacy-to-modern migration, token bridging with CSS variables, or framework-specific Tailwind build issues.
license: MIT
---

# UB Tailwind

## Overview

Use this skill to keep Tailwind usage current and correct across different environments and avoid outdated patterns. This skill targets the latest stable Tailwind CSS: enforce CSS-first setup, apply official framework recipes, and replace legacy defaults in generated guidance.

Implement against the detected project and tooling truth, but bias setup and
migration guidance toward modern CSS-first Tailwind rather than retaining
legacy configuration habits or compatibility layers by default.

## Load References On Demand

- Read `../ub-authoring/references/authoring-conventions.md` when adjusting routing
  guidance or cross-skill authoring conventions.
- Read `references/tailwind-guardrails.md` for strict do/don't rules, deprecated syntax traps, and review checklists.
- Read `references/framework-recipes.md` for environment-specific setup paths (standalone HTML/CDN, Vue + Vite, Nuxt).
- Read `references/tailwind-legacy-to-modern-migration.md` for migration matrix, upgrade replacements, and compatibility caveats.

## When Not To Use

- Do not use this skill when the task is plain CSS architecture, selector
  strategy, or token-driven styling without Tailwind as the primary surface;
  co-load or defer to `ub-css` when Tailwind and CSS architecture overlap.
- Do not use this skill when the main issue is framework runtime behavior
  rather than Tailwind integration or utility-class authoring.

## Core Workflow

1. Identify the target environment before writing any Tailwind setup.
2. Run required detection checks: `nuxt.config.*`, `vite.config.*`, `package.json` dependencies, CSS entrypoints, and Nuxt app stylesheet placement (for modern Nuxt, expect `app/assets/css/main.css`).
3. Choose the matching recipe from `references/framework-recipes.md`.
4. Compare official guidance, repo truth, and observed code reality for
   non-trivial or version-sensitive recommendations.
5. Surface `OFFICIAL_CONFLICT` when authoritative sources, repo truth, or live
   code reality materially disagree on a non-trivial recommendation.
6. Surface `UNVERIFIED` when a non-trivial claim could not be confirmed in
   official sources after targeted research.
7. Apply modern Tailwind CSS-first rules from `references/tailwind-guardrails.md`.
8. Apply upgrade-safe replacements from `references/tailwind-legacy-to-modern-migration.md`.
9. Run the environment-specific validation checklist.
10. Reject and replace deprecated or legacy syntax.

## Environment Selection

- Use the **Standalone HTML/CDN** recipe for plain HTML pages without a build tool.
- Use the **Vue + Vite** recipe for Vue projects with Vite bundling.
- Use the **Nuxt** recipe for Nuxt apps where integration details differ from plain Vite.
- For Nuxt, default to the official setup path (`@tailwindcss/vite` wired in `nuxt.config.*`), not legacy module defaults.

If the environment is unclear, inspect project markers first (`package.json`, framework config, build plugins) and do not guess.

## Non-Negotiable Guardrails

### Tailwind Version and Syntax

- Use modern Tailwind CSS-first patterns and current docs semantics.
- Prefer CSS entrypoint `@import "tailwindcss"`.
- Prefer CSS directives like `@theme`, `@utility`, `@variant`, `@custom-variant`, `@source`, and `@reference` as needed.
- Treat `@config` and `@plugin` as legacy paths unless explicitly required for compatibility.
- Prefer compatibility only as a bounded layer with a documented migration back to CSS-first defaults.

### Build Strategy

- Do not assume PostCSS is required for modern Tailwind.
- Use Vite plugin integration where applicable (`@tailwindcss/vite`) for Vue + Vite workflows.
- For Nuxt, use the official Nuxt framework-guide flow and configure the Vite plugin under Nuxt config instead of creating Vue-only `vite.config.*` instructions.
- Keep setup minimal and environment-native.

### Vue/Nuxt Style Context

- For Vue/Nuxt component-scoped styles using `@apply` or `@variant`, include `@reference` to the main stylesheet or app stylesheet context.
- Avoid duplicating imported CSS just to expose theme values in component-local styles.

### Design Tokens

- Keep Tailwind tokens centralized in `@theme`.
- Reuse existing token primitives and avoid ad-hoc hardcoded drift.

### Do Not Generate

- Do not generate `@tailwind base;`, `@tailwind components;`, `@tailwind utilities;` as the default modern entrypoint.
- Do not assume PostCSS setup is mandatory for modern Tailwind.
- Do not default to `@nuxtjs/tailwindcss` as the first-line setup for fresh Nuxt guidance.

## Output Requirements

When generating or modifying code, always provide:

1. A short environment detection note.
2. A source truth note: detected project version, environment markers, and any
   material gap versus latest stable guidance.
3. The selected setup path (CDN, Vue + Vite, or Nuxt).
4. Exact deprecated-to-modern replacements applied (syntax/tooling/utility changes).
5. A quick validation checklist confirming modern Tailwind setup.
6. Compatibility notes when legacy directives (`@config`/`@plugin`) are retained.
7. Conflict note when relevant: `OFFICIAL_CONFLICT` or `UNVERIFIED` with a
   concise explanation and the implementation consequence.

## Version & Research Policy

- Target the latest stable release of Tailwind CSS.
- Detect the project's actual Tailwind version from `package.json` and lockfiles.
- Use web search to verify current best practices, directive availability, and migration guidance against official Tailwind CSS documentation.
- Treat repo truth as the gold implementation standard when deciding what can
  actually ship safely in the current project.
- Treat official Tailwind docs as the preferred guidance baseline for
  forward-looking design and migration-ready patterns.
- If official guidance and repo truth diverge materially on a non-trivial
  recommendation, surface `OFFICIAL_CONFLICT`, implement the repo-safe path,
  and explain the migration path.
- If official sources disagree with each other on a non-trivial
  recommendation, also surface `OFFICIAL_CONFLICT` instead of silently
  collapsing the disagreement.
- If a non-trivial claim cannot be confirmed in official sources after
  targeted research, mark it `UNVERIFIED` or avoid presenting it as settled
  guidance.
- Keep conflict and uncertainty disclosure scoped to non-trivial,
  version-sensitive, or contested guidance rather than trivial edits.
- When the project's installed version is behind latest stable, note the version gap and recommend an upgrade path.
- Inspect the host repository's `AGENTS.md` or equivalent instructions when
  present for project-specific version policy and tooling; do not assume it
  contains this catalog's defaults.
- Do not hardcode version numbers in generated guidance — keep recommendations evergreen.

## Freshness Review

- Volatility: high
- Review recommendation: review on touch and during periodic maintenance, targeting a quarterly rhythm when practical.
- Trigger signals: official migration changes, deprecated directives, major Tailwind releases, or repo toolchain changes that affect setup recipes.
- Enforcement: advisory only; stale Tailwind guidance is a review signal, not a blocking gate by itself.
- Stable core: environment detection, official recipe selection, and deprecated-syntax avoidance should remain useful even when exact setup details evolve.

## Completion Checklist

- Environment explicitly identified before setup.
- Tailwind entrypoint and directives align with modern guidance.
- No deprecated/legacy syntax remains without explicit compatibility reason.
- Framework-specific differences are handled (CDN vs Vite vs Nuxt).
- Nuxt guidance uses the official framework path and does not drift into Vue-only `vite.config.*` steps.
- Token usage is centralized and consistent.
- Generated instructions are concise, deterministic, and current-version oriented.
- Any material official-source conflict or unverified non-trivial guidance is
  disclosed explicitly when relevant.