feat: improve skill coverage and optimize description (v0.1.1)

.gitignore

@@ -0,0 +1,33 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+.astro/
+coverage/
+
+# Benchmark harness (not part of the skill)
+benchmark/
+
+# Local planning artifacts
+.plan/
+
+# Session artifacts
+preview.err
+preview.out
+preview.log
+chromewebdata_*.report.html
+
+# Environment
+.env
+.env.*
+
+# Logs and temp
+*.log
+*.tmp
+.DS_Store
+Thumbs.db
+
+# System
+server.pid

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tailwind-pro
-description: Enterprise patterns for Tailwind CSS v4+ including design tokens with @theme and OKLCH, CVA + tailwind-merge composition, dark mode class strategies, container queries, fluid typography with clamp, performance via @source and safelist, a11y best practices, and v3 to v4 migration guidance.
+description: Tailwind CSS v4+ design system patterns: @theme and OKLCH tokens, CVA + tailwind-merge, @utility and @custom-variant, @apply in @layer components, dark mode class strategies (incl. data-theme), @container queries, fluid clamp typography and spacing, arbitrary values and properties (color-mix, :has), @source and safelist performance, @keyframes and reduced-motion a11y, and v3-to-v4 migration. Use @reference for CSS Modules; not for Tailwind v1/v2, Bootstrap, Sass, or CSS-in-JS.
 license: MIT
 ---
 

rules/dark-mode-strategies.mdc

@@ -26,6 +26,14 @@ Support light, dark, and system preference.
   if (theme === 'dark' || (theme === 'system' && matchMedia('(prefers-color-scheme: dark)').matches)) {
     document.documentElement.classList.add('dark');
   }
+  const mq = window.matchMedia('(prefers-color-scheme: dark)');
+  mq.addEventListener('change', () => {
+    // Re-evalúa matchMedia directamente cuando el tema es system
+    if (localStorage.getItem('theme') === 'system') {
+      const isDark = mq.matches;
+      document.documentElement.classList.toggle('dark', isDark);
+    }
+  });
 </script>
 ```
 
@@ -57,3 +65,4 @@ function setTheme(mode: 'light' | 'dark' | 'system') {
 - Respect `prefers-color-scheme` for system
 - Use semantic tokens, not `dark:` utilities everywhere
 - Test with forced-colors and high contrast
+- Para modo `system`, la variante `@custom-variant dark` debe combinarse con `prefers-color-scheme` cuando no haya clase explícita de `.light`/`.dark`.

rules/migration-v3-v4.mdc

@@ -0,0 +1,48 @@
+---
+description: Tailwind v3 to v4 migration guide with breaking changes table and equivalences.
+---
+
+# Migration v3 → v4
+
+## Breaking Changes
+
+| v3 | v4 | Notes |
+|----|----|-------|
+| `tailwind.config.js` with `theme.extend.colors` | `@theme { --color-* }` | Map `theme.extend.colors` → `--color-*`, `theme.extend.spacing` → `--spacing-*`, etc. |
+| `@tailwind base` / `@tailwind components` / `@tailwind utilities` | `@import "tailwindcss"` | Single import replaces directives. |
+| `darkMode: 'class'` | `@custom-variant dark (&:where(.dark, .dark *));` | Class strategy with custom variant. |
+| `safelist: [...]` in config | `@source inline("...")` in CSS | Inline safelisting for dynamic classes. |
+| `shadow-sm` | `shadow-xs` | Scale changed: `shadow-2xs`, `shadow-xs`, `shadow-sm`, `shadow-md`... |
+| `flex-shrink-*` | `shrink-*` | Shorter utilities. |
+| `flex-grow-*` | `grow-*` | Shorter utilities. |
+| `outline-none` | `outline-hidden` | New semantic name. |
+| `ring` (default) | `ring-1` / `ring-3` | Ring defaults changed. |
+| `bg-opacity-*` | `bg-black/50` | Use opacity modifier. |
+| `text-opacity-*` | `text-black/50` | Use `/` modifier. |
+| `blur` | `blur-sm` | Scale adjusted. |
+| `rounded-sm` | `rounded-xs` | Radius scale shifted. |
+| `shadow` | `shadow-sm` | Default shadow renamed. |
+| `theme()` function | `var(--*)` | Use CSS variables. |
+
+## Behavior Notes
+
+- `@layer components` + `@apply` continues to work.
+- `@utility` does **not** use `@apply`; declare CSS directly.
+- `--breakpoint-*` for viewport media queries; `--container-*` for `@container` queries.
+- New capabilities: `@theme inline`, `@reference`, `@theme static`.
+
+## Examples
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-brand-500: oklch(0.65 0.18 250);
+  --spacing: 0.25rem;
+}
+
+@custom-variant dark (&:where(.dark, .dark *));
+@source inline("{hover:,}bg-red-{50,100..900..100,950}");
+```
+
+Prefer verified renames from https://tailwindcss.com/docs/upgrade-guide; mark uncertain items as "verify".

snippets/safelist-examples.css

@@ -1,13 +1,21 @@
-/* Safelist examples for dynamic classes */
-@source inline("bg-red-500") "bg-*";
-@source inline("text-sm") "text-*";
-@source inline("grid-cols-1") "grid-cols-*";
+/* Safelist examples for dynamic classes — Tailwind CSS v4 @source inline */
+/* Broad patterns are acceptable only for closed, audited sets; avoid '*' in general scans. */
 
-/* Brace expansion examples */
-@source inline("opacity-0") "opacity-[0-100]";
+/* Simple safelist */
+@source inline("underline");
 
-/* Dynamic variant safelist */
-@source inline("dark:bg-gray-900") "dark:bg-*";
+/* Safelist with variants */
+@source inline("{hover:,focus:,}underline");
 
-/* Component-specific safelist */
-@source "./src/components/StatusBadge.tsx" "bg-success-*" "bg-warning-*";
+/* Brace expansion of color ... */
+@source inline("{hover:,}bg-red-{50,100..900..100,950}");
+
+/* Exclusion */
+/* @source not se usa con rutas, no con inline() — para excluir clases específicas simplemente no se safelistean */
+@source not "../src/components/legacy";
+
+/* Component-specific source with explicit classes */
+@source "./src/components/StatusBadge.tsx";
+/* For StatusBadge, safelist the exact variants used: */
+@source inline("bg-success-{500,600}");
+@source inline("bg-warning-{500,600}");

test-cases/non-trigger/11-chakra-ui-components.md

@@ -0,0 +1,7 @@
+# Non-trigger: Chakra UI components
+
+User wants to customize Chakra UI components using its theme and style props.
+
+Context: React app using Chakra UI component library.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/12-emotion-css-in-js.md

@@ -0,0 +1,7 @@
+# Non-trigger: Emotion CSS-in-JS
+
+User wants to use Emotion for styled components and inline styles with the css prop.
+
+Context: CSS-in-JS styling library.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/13-tailwind-v1.md

@@ -0,0 +1,7 @@
+# Non-trigger: Tailwind v1 legacy
+
+User is working with Tailwind CSS v1 and its pre-JIT configuration using PostCSS plugins directly.
+
+Context: Legacy Tailwind v1 setup without JIT engine.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/14-typescript-generics.md

@@ -0,0 +1,7 @@
+# Non-trigger: TypeScript generic types
+
+User wants to define generic TypeScript types and interfaces for a data model.
+
+Context: Pure TypeScript typing with no CSS involved.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/15-react-server-components.md

@@ -0,0 +1,7 @@
+# Non-trigger: React Server Components
+
+User wants to build React Server Components with async data fetching and streaming, without any styling concerns.
+
+Context: Server-side rendering architecture.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/16-storybook-stories.md

@@ -0,0 +1,7 @@
+# Non-trigger: Storybook stories without Tailwind
+
+User wants to write Storybook stories and interaction tests for plain React components that use no Tailwind classes.
+
+Context: Component documentation tooling.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/17-css-cascade-layers.md

@@ -0,0 +1,7 @@
+# Non-trigger: CSS @import cascade layers
+
+User wants to structure native CSS cascade layers using `@import ... layer(...)` and `@layer` without any Tailwind.
+
+Context: Plain CSS cascade layering architecture.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/18-django-templates.md

@@ -0,0 +1,7 @@
+# Non-trigger: Django templates styling
+
+User wants to style Django templates using the template engine and inline HTML attributes.
+
+Context: Python/Django server-rendered templates.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/19-svg-smil-animation.md

@@ -0,0 +1,7 @@
+# Non-trigger: SVG animation with SMIL
+
+User wants to animate SVG graphics using SMIL elements like `<animate>` and `<animateTransform>`.
+
+Context: SVG presentation animation.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/20-wcag-audit.md

@@ -0,0 +1,7 @@
+# Non-trigger: Generic WCAG accessibility audit
+
+User wants a generic WCAG accessibility audit report for a website, unrelated to any Tailwind styling.
+
+Context: Accessibility compliance review.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/21-threejs-webgl.md

@@ -0,0 +1,7 @@
+# Non-trigger: Three.js WebGL rendering
+
+User wants to render 3D scenes with Three.js and WebGL shaders.
+
+Context: 3D graphics rendering on canvas.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/22-nginx-deploy.md

@@ -0,0 +1,7 @@
+# Non-trigger: Nginx server config
+
+User wants to write Nginx configuration for reverse proxying and static file serving.
+
+Context: Server deployment and infrastructure.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/23-jetpack-compose.md

@@ -0,0 +1,7 @@
+# Non-trigger: Jetpack Compose styling
+
+User wants to style Android UI using Jetpack Compose modifiers and Material3 theming.
+
+Context: Android native UI development.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/24-figma-tokens.md

@@ -0,0 +1,7 @@
+# Non-trigger: Figma token export
+
+User wants to export design tokens from Figma to a JSON file for handoff.
+
+Context: Design tool token management.
+
+Should NOT activate tailwind-pro.

test-cases/non-trigger/25-remix-vite-build.md

@@ -0,0 +1,7 @@
+# Non-trigger: Remix Vite server build
+
+User wants to configure a Remix app's Vite server build and deployment pipeline.
+
+Context: Build tooling and deployment configuration.
+
+Should NOT activate tailwind-pro.

test-cases/trigger/11-arbitrary-properties.md

@@ -0,0 +1,7 @@
+# Trigger: Arbitrary properties
+
+User wants to apply arbitrary CSS properties using bracket syntax like `[mask-type:luminance]` and `[color-scheme:dark]`.
+
+Context: Setting non-standard utility properties inline.
+
+Should activate tailwind-pro for arbitrary properties.

test-cases/trigger/12-reference-shared-theme.md

@@ -0,0 +1,7 @@
+# Trigger: @reference for shared theme
+
+User wants to use `@reference` to share a common theme file (tokens) across multiple CSS entry points without duplicating @theme.
+
+Context: Reusing theme tokens between separate CSS bundles.
+
+Should activate tailwind-pro for @reference theme sharing.

test-cases/trigger/13-css-modules-reference.md

@@ -0,0 +1,7 @@
+# Trigger: CSS Modules with @reference
+
+User wants to combine CSS Modules with Tailwind by using `@reference` to import Tailwind utilities into a module.css file and migrate utilities into scoped modules.
+
+Context: Migrating utility classes into CSS Module files while keeping Tailwind theme.
+
+Should activate tailwind-pro for CSS Modules @reference.

test-cases/trigger/14-multiple-custom-variants.md

@@ -0,0 +1,7 @@
+# Trigger: Multiple custom variants
+
+User needs to define several custom variants with `@custom-variant` (e.g. `print`, `hocus`, `theme-dark`) to compose new selector variants.
+
+Context: Extending the variant system with multiple project-specific variants.
+
+Should activate tailwind-pro for custom variants.

test-cases/trigger/15-apply-layer-vs-utility.md

@@ -0,0 +1,7 @@
+# Trigger: @apply in component layer vs @utility
+
+User is deciding whether to use `@apply` inside `@layer components` or define a custom `@utility` for a reusable style, and needs to know which to use when.
+
+Context: Choosing the right abstraction for shared component styles.
+
+Should activate tailwind-pro for @apply vs @utility guidance.

test-cases/trigger/16-oklch-fallbacks.md

@@ -0,0 +1,7 @@
+# Trigger: OKLCH browser support and fallbacks
+
+User wants OKLCH color tokens plus fallback values for older browsers that lack OKLCH support.
+
+Context: Ensuring colors degrade gracefully in legacy browsers.
+
+Should activate tailwind-pro for OKLCH fallback patterns.

test-cases/trigger/17-dark-mode-data-theme.md

@@ -0,0 +1,7 @@
+# Trigger: Dark mode with data-theme
+
+User wants a dark mode strategy driven by a `data-theme` attribute instead of the `.dark` class selector.
+
+Context: Theming via data attributes across the app.
+
+Should activate tailwind-pro for data-theme dark mode strategies.

test-cases/trigger/18-source-not-exclusions.md

@@ -0,0 +1,7 @@
+# Trigger: @source not exclusions
+
+User wants to exclude specific files or directories from content scanning using `@source not`.
+
+Context: Preventing auto-detection from pulling in unwanted class sources.
+
+Should activate tailwind-pro for @source exclusion patterns.

test-cases/trigger/19-theme-static-variables.md

@@ -0,0 +1,7 @@
+# Trigger: @theme static variables
+
+User wants to force generation of static CSS variables using `@theme static` so tokens are emitted as real CSS custom properties with namespaced names.
+
+Context: Exposing theme tokens as stable CSS variables for external consumers.
+
+Should activate tailwind-pro for @theme static patterns.

test-cases/trigger/20-reduced-motion-keyframes.md

@@ -0,0 +1,7 @@
+# Trigger: Reduced motion with custom keyframes
+
+User wants custom `@keyframes` defined in `@theme` plus a `motion-reduce` variant to disable animation for prefers-reduced-motion users.
+
+Context: Accessible custom animations that respect user motion preferences.
+
+Should activate tailwind-pro for reduced motion and keyframes.

test-cases/trigger/21-alpha-color-mix-tints.md

@@ -0,0 +1,7 @@
+# Trigger: alpha and color-mix dynamic tints
+
+User wants dynamic tint/shade generation using the `--alpha()` modifier and `color-mix()` function on theme colors.
+
+Context: Creating lighter/darker shades without hardcoding each step.
+
+Should activate tailwind-pro for alpha and color-mix tinting.

test-cases/trigger/22-named-container-queries.md

@@ -0,0 +1,7 @@
+# Trigger: Named container queries
+
+User wants named container queries using `@container/main` and responsive variants like `@sm/main:` for scoped breakpoint styling.
+
+Context: Multiple container contexts with named breakpoints.
+
+Should activate tailwind-pro for named container queries.

test-cases/trigger/23-theme-inline-tokens.md

@@ -0,0 +1,7 @@
+# Trigger: @theme inline semantic tokens
+
+User wants `@theme inline` for semantic tokens that reference other tokens (e.g. `--color-surface: var(--color-background)`) resolved at build time.
+
+Context: Layering semantic tokens over primitive color scales.
+
+Should activate tailwind-pro for @theme inline token patterns.