ub-tailwind

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.