@biggora/claude-plugins 1.2.0 → 1.2.2

package/src/skills/tailwindcss-best-practices/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: tailwindcss-best-practices
+description: Tailwind CSS v4.x utility-first CSS framework best practices. Use when styling web applications with utility classes, building responsive layouts, customizing design systems with @theme variables, migrating from v3 to v4, configuring dark mode, creating custom utilities with @utility, or working with any Tailwind CSS v4 features. This skill covers the full v4.x line through v4.2 including text shadows, masks, logical properties, and source detection. Use this skill even for simple Tailwind questions — v4 changed many class names and configuration patterns that trip people up.
+---
+
+# Tailwind CSS v4.x Best Practices
+
+> Covers Tailwind CSS v4.0 through v4.2.2 (latest stable as of March 2026). Always check the official docs at https://tailwindcss.com/docs for the latest.
+
+Tailwind CSS is a utility-first CSS framework. Instead of writing custom CSS, you compose designs using utility classes directly in your markup. Tailwind v4 introduced CSS-first configuration with `@theme` variables, `@utility` for custom utilities, and `@custom-variant` for custom variants — replacing the old `tailwind.config.js` approach entirely.
+
+## Critical v4 Migration Gotchas
+
+These are the most common mistakes when working with Tailwind v4. If you're migrating from v3 or using v4 for the first time, read the [upgrade guide](references/features-upgrade.md) — but here are the top trip-ups:
+
+| v3 (old) | v4 (correct) | Why it changed |
+|----------|-------------|----------------|
+| `!bg-red-500` | `bg-red-500!` | Important modifier moved from prefix to suffix |
+| `bg-opacity-75` | `bg-red-500/75` | Opacity modifiers removed; use slash syntax on the color |
+| `shadow` | `shadow-sm` | Shadow scale shifted down one step |
+| `shadow-sm` | `shadow-xs` | Shadow scale shifted down one step |
+| `rounded` | `rounded-sm` | Border radius scale shifted down one step |
+| `rounded-sm` | `rounded-xs` | Border radius scale shifted down one step |
+| `ring` | `ring-3` | Default ring width changed from 3px to 1px |
+| `outline-none` | `outline-hidden` | Renamed for clarity |
+| `flex-shrink-0` | `shrink-0` | Shorter alias is now the only form |
+| `flex-grow` | `grow` | Shorter alias is now the only form |
+| `overflow-ellipsis` | `text-ellipsis` | Renamed for consistency |
+| `blur` | `blur-sm` | Blur scale shifted down one step |
+| `@tailwind base/components/utilities` | `@import "tailwindcss"` | Single CSS import replaces three directives |
+| `tailwind.config.js` | `@theme { }` in CSS | CSS-first configuration replaces JS config |
+| `darkMode: 'class'` | `@custom-variant dark (&:where(.dark, .dark *));` | Dark mode config moves to CSS |
+| `bg-[--var]` | `bg-(--var)` | CSS variable arbitrary values use parentheses |
+| `theme(screens.xl)` | `theme(--breakpoint-xl)` | Theme function uses CSS variable names |
+| `@layer utilities { }` | `@utility name { }` | Custom utilities use dedicated directive |
+| `start-*` / `end-*` | `inset-s-*` / `inset-e-*` | Deprecated in v4.2 |
+
+## Core References
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Installation | Vite, PostCSS, Webpack, CLI, and CDN setup | [core-installation](references/core-installation.md) |
+| Utility Classes | Understanding Tailwind's utility-first approach | [core-utility-classes](references/core-utility-classes.md) |
+| Theme Variables | Design tokens, `@theme` directive, theme variable namespaces | [core-theme](references/core-theme.md) |
+| Responsive Design | Mobile-first breakpoints, responsive variants, container queries | [core-responsive](references/core-responsive.md) |
+| Variants | Conditional styling with state, pseudo-class, media query, and pointer variants | [core-variants](references/core-variants.md) |
+| Preflight | Tailwind's base styles and how to extend or disable them | [core-preflight](references/core-preflight.md) |
+| Source Detection | How Tailwind detects classes, `@source`, `@source not`, `@source inline()` | [core-source-detection](references/core-source-detection.md) |
+
+## Layout
+
+### Display & Flexbox & Grid
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Display | flex, grid, block, inline, hidden, sr-only, flow-root, contents | [layout-display](references/layout-display.md) |
+| Flexbox | flex-direction, justify, items, gap, grow, shrink, wrap, order | [layout-flexbox](references/layout-flexbox.md) |
+| Grid | grid-cols, grid-rows, gap, place-items, col-span, row-span, subgrid | [layout-grid](references/layout-grid.md) |
+| Aspect Ratio | Controlling element aspect ratio for responsive media | [layout-aspect-ratio](references/layout-aspect-ratio.md) |
+| Columns | Multi-column layout for magazine-style or masonry layouts | [layout-columns](references/layout-columns.md) |
+
+### Positioning
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Position | Controlling element positioning with static, relative, absolute, fixed, and sticky | [layout-position](references/layout-position.md) |
+| Inset | Placement of positioned elements with inset, logical inset (`inset-s-*`, `inset-bs-*`), and deprecated `start-*`/`end-*` | [layout-inset](references/layout-inset.md) |
+
+### Sizing
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Width | Setting element width with spacing scale, fractions, container sizes, viewport units | [layout-width](references/layout-width.md) |
+| Height | Setting element height with spacing scale, fractions, viewport units | [layout-height](references/layout-height.md) |
+| Min & Max Sizing | min-width, max-width, min-height, max-height constraints | [layout-min-max-sizing](references/layout-min-max-sizing.md) |
+| Logical Sizing | Writing-mode-aware sizing: `inline-*`, `block-*`, `min-inline-*`, `max-block-*` (v4.2) | [layout-logical-properties](references/layout-logical-properties.md) |
+
+### Spacing
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Margin | Margins with spacing scale, negative values, logical properties (`mbs-*`, `mbe-*`) | [layout-margin](references/layout-margin.md) |
+| Padding | Padding with spacing scale, logical properties (`pbs-*`, `pbe-*`) | [layout-padding](references/layout-padding.md) |
+
+### Overflow
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Overflow | Controlling how elements handle content that overflows | [layout-overflow](references/layout-overflow.md) |
+
+### Images & Replaced Elements
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Object Fit & Position | Controlling how images and video are resized and positioned | [layout-object-fit-position](references/layout-object-fit-position.md) |
+
+### Tables
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Table Layout | border-collapse, table-auto, table-fixed | [layout-tables](references/layout-tables.md) |
+
+## Transforms
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Transform Base | Base transform utilities, hardware acceleration, custom transform values | [transform-base](references/transform-base.md) |
+| Translate | Translating elements on x, y, z axes with spacing scale and percentages | [transform-translate](references/transform-translate.md) |
+| Rotate | Rotating elements in 2D and 3D space | [transform-rotate](references/transform-rotate.md) |
+| Scale | Scaling elements uniformly or on specific axes | [transform-scale](references/transform-scale.md) |
+| Skew | Skewing elements on x and y axes | [transform-skew](references/transform-skew.md) |
+
+## Typography
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Font & Text | Font size, weight, color, line-height, letter-spacing, decoration, truncate, `wrap-break-word`, `wrap-anywhere` | [typography-font-text](references/typography-font-text.md) |
+| Text Align | Controlling text alignment with left, center, right, justify | [typography-text-align](references/typography-text-align.md) |
+| List Style | list-style-type, list-style-position for bullets and markers | [typography-list-style](references/typography-list-style.md) |
+
+## Visual
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Background | Background color, gradient, image, size, position | [visual-background](references/visual-background.md) |
+| Border | Border width, color, radius, divide, ring, block border utilities (`border-bs-*`, `border-be-*`) | [visual-border](references/visual-border.md) |
+| Effects | Box shadow, opacity, mix-blend, backdrop-blur, filter, colored drop shadows | [visual-effects](references/visual-effects.md) |
+| SVG | fill, stroke, stroke-width for SVG and icon styling | [visual-svg](references/visual-svg.md) |
+| Text Shadow | Text shadow sizes, colors, and opacity modifiers (v4.1) | [effects-text-shadow](references/effects-text-shadow.md) |
+| Mask | Composable mask utilities with gradient and radial masks (v4.1) | [effects-mask](references/effects-mask.md) |
+
+## Effects & Interactivity
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Transition & Animation | CSS transitions, animation keyframes, reduced motion | [effects-transition-animation](references/effects-transition-animation.md) |
+| Visibility & Interactivity | Visibility, cursor, pointer-events, user-select, z-index | [effects-visibility-interactivity](references/effects-visibility-interactivity.md) |
+| Form Controls | accent-color, appearance, caret-color, resize | [effects-form-controls](references/effects-form-controls.md) |
+| Scroll Snap | scroll-snap-type, scroll-snap-align for carousels | [effects-scroll-snap](references/effects-scroll-snap.md) |
+
+## Features
+
+### Dark Mode
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Dark Mode | Dark mode with `dark:` variant, `@custom-variant`, class and data-attribute strategies | [features-dark-mode](references/features-dark-mode.md) |
+
+### Migration
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Upgrade Guide | Migrating from v3 to v4, all renamed/removed utilities, scale shifts, config migration | [features-upgrade](references/features-upgrade.md) |
+
+### Customization
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Custom Styles | Adding custom styles, utilities with `@utility`, variants with `@custom-variant`, arbitrary values | [features-custom-styles](references/features-custom-styles.md) |
+| Functions & Directives | Tailwind's CSS directives (`@theme`, `@utility`, `@custom-variant`, `@source`) and functions | [features-functions-directives](references/features-functions-directives.md) |
+| Content Detection | How Tailwind detects classes, `@source` configuration, safelisting with `@source inline()` | [features-content-detection](references/features-content-detection.md) |
+
+## Best Practices
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Utility Patterns | Managing duplication, conflicts, important modifier, when to use components | [best-practices-utility-patterns](references/best-practices-utility-patterns.md) |
+
+## Key Recommendations
+
+- **Use utility classes directly in markup** — compose designs by combining utilities
+- **Customize with `@theme` directive** — define design tokens as CSS variables, not in JS config
+- **Mobile-first responsive design** — unprefixed utilities for mobile, prefixed for breakpoints
+- **Use complete class names** — never construct classes dynamically with string interpolation
+- **Leverage variants** — stack variants for complex conditional styling (`dark:md:hover:bg-blue-600`)
+- **Prefer CSS-first configuration** — use `@theme`, `@utility`, and `@custom-variant` over JavaScript configs
+- **Use oklch for custom colors** — Tailwind v4 defaults to oklch; prefer it for perceptual uniformity
+- **Use rem for custom breakpoints** — e.g., `--breakpoint-3xl: 90rem` not `1440px`
+- **Know the scale shifts** — shadow, rounded, and blur all shifted down one step in v4
+- **Use `@custom-variant`** (not `@variant`) — for defining custom variants like class-based dark mode

package/src/skills/tailwindcss-best-practices/references/best-practices-utility-patterns.md

@@ -0,0 +1,87 @@
+---
+name: best-practices-utility-patterns
+description: Managing duplication, conflicts, important modifier, and when to use components
+---
+
+# Best Practices: Utility Patterns
+
+Practical patterns when building with Tailwind utilities.
+
+## Managing duplication
+
+**Use components** for repeated UI: Extract into React/Vue/Svelte components or template partials.
+
+```jsx
+function Button({ children, variant = 'primary' }) {
+  const base = 'px-4 py-2 rounded-lg font-medium'
+  const variants = {
+    primary: 'bg-blue-500 hover:bg-blue-600 text-white',
+    secondary: 'bg-gray-200 hover:bg-gray-300 text-gray-900',
+  }
+  return <button className={`${base} ${variants[variant]}`}>{children}</button>
+}
+```
+
+**Use loops** when markup is repeated from data—the class list is written once.
+
+**Multi-cursor editing** for localized duplication in a single file.
+
+## Managing conflicts
+
+When two utilities target the same property, the one **later in the stylesheet** wins. Avoid adding conflicting classes:
+
+```html
+<!-- Bad -->
+<div class="flex grid">Conflict</div>
+
+<!-- Good: conditional class -->
+<div class={gridLayout ? 'grid' : 'flex'}>
+```
+
+## Important modifier
+
+Add `!` suffix to force `!important`:
+
+```html
+<div class="bg-teal-500 bg-red-500!">Red wins</div>
+```
+
+Use sparingly; prefer fixing specificity properly.
+
+## Important flag (global)
+
+```css
+@import "tailwindcss" important;
+```
+
+Makes all utilities `!important`. Useful when integrating into existing high-specificity CSS.
+
+## Prefix option
+
+```css
+@import "tailwindcss" prefix(tw);
+```
+
+Generates `tw:text-red-500` etc. Use when project class names conflict with Tailwind.
+
+## When to use inline styles
+
+- Values from API/database (e.g. brand colors)
+- Dynamic values that change at runtime
+- Complex arbitrary values hard to read as class names
+- Pattern: set CSS variables via inline style, reference with `bg-(--my-var)`
+
+## Key Points
+
+- Extract repeated patterns into components
+- Never add two conflicting utilities—use conditional classes
+- `!` suffix = single utility `!important`
+- `important` flag = all utilities `!important`
+- `prefix(tw)` = prefix all utilities
+- Use inline styles for dynamic values; utilities for static design
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/utility-first#managing-duplication
+- https://tailwindcss.com/docs/utility-first#managing-style-conflicts
+-->

package/src/skills/tailwindcss-best-practices/references/core-installation.md

@@ -0,0 +1,109 @@
+---
+name: core-installation
+description: Installing Tailwind CSS with Vite, PostCSS, CLI, or CDN
+---
+
+# Installation
+
+How to add Tailwind CSS to a project.
+
+## Vite (Recommended)
+
+```bash
+npm install tailwindcss @tailwindcss/vite
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [tailwindcss()],
+})
+```
+
+```css
+/* style.css */
+@import "tailwindcss";
+```
+
+## PostCSS
+
+```bash
+npm install tailwindcss @tailwindcss/postcss postcss
+```
+
+```js
+// postcss.config.js
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+}
+```
+
+```css
+@import "tailwindcss";
+```
+
+## Tailwind CLI
+
+```bash
+npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch
+```
+
+```css
+/* input.css */
+@import "tailwindcss";
+```
+
+## Webpack (v4.2+)
+
+```bash
+npm install tailwindcss @tailwindcss/webpack
+```
+
+```js
+// webpack.config.js
+const tailwindcss = require('@tailwindcss/webpack')
+
+module.exports = {
+  plugins: [tailwindcss()],
+}
+```
+
+```css
+@import "tailwindcss";
+```
+
+## Play CDN (Development only)
+
+```html
+<script src="https://cdn.tailwindcss.com"></script>
+```
+
+Not for production: no purging, larger payload.
+
+## Framework guides
+
+- **Nuxt**: `@nuxtjs/tailwindcss` module or `@tailwindcss/vite`
+- **Next.js**: Use Vite or PostCSS with `tailwind.config.js` if needed
+- **React Router / SvelteKit / SolidJS**: Use `@tailwindcss/vite`
+
+## Key Points
+
+- Vite: `@tailwindcss/vite` plugin + `@import "tailwindcss"` (supports Vite 8+)
+- PostCSS: `@tailwindcss/postcss`
+- Webpack: `@tailwindcss/webpack` (v4.2+)
+- CLI: `npx @tailwindcss/cli`
+- v4 uses CSS-first config; no `tailwind.config.js` required for basics
+- Use `@theme` in CSS to customize design tokens
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/installation/using-vite
+- https://tailwindcss.com/docs/installation/using-postcss
+- https://tailwindcss.com/docs/installation/tailwind-cli
+- https://tailwindcss.com/docs/installation/play-cdn
+-->

package/src/skills/tailwindcss-best-practices/references/core-preflight.md

@@ -0,0 +1,200 @@
+---
+name: core-preflight
+description: Understanding Tailwind's Preflight base styles and how to extend or disable them
+---
+
+# Preflight
+
+Preflight is Tailwind's opinionated set of base styles that smooth over cross-browser inconsistencies.
+
+## Overview
+
+Built on top of modern-normalize, Preflight is automatically injected when you import `tailwindcss`:
+
+```css
+@layer theme, base, components, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
+@import "tailwindcss/utilities.css" layer(utilities);
+```
+
+## Key Resets
+
+### Margins Removed
+
+All default margins are removed from headings, paragraphs, blockquotes, etc:
+
+```css
+*,
+::after,
+::before {
+  margin: 0;
+  padding: 0;
+}
+```
+
+This prevents accidentally relying on browser default margins that aren't part of your spacing scale.
+
+### Border Styles Reset
+
+Borders are reset to make adding borders easier:
+
+```css
+*,
+::after,
+::before {
+  box-sizing: border-box;
+  border: 0 solid;
+}
+```
+
+Since the `border` utility only sets `border-width`, this ensures adding `border` always creates a solid `1px` border using `currentColor`.
+
+### Headings Unstyled
+
+All headings are unstyled by default:
+
+```css
+h1, h2, h3, h4, h5, h6 {
+  font-size: inherit;
+  font-weight: inherit;
+}
+```
+
+**Reasons:**
+- Avoids deviating from your type scale
+- In UI development, headings should often be visually de-emphasized
+
+### Lists Unstyled
+
+Ordered and unordered lists have no bullets or numbers:
+
+```css
+ol, ul, menu {
+  list-style: none;
+}
+```
+
+Style lists using utilities:
+
+```html
+<ul class="list-inside list-disc">
+  <li>One</li>
+  <li>Two</li>
+</ul>
+```
+
+**Accessibility:** Add `role="list"` for screen readers when keeping lists unstyled:
+
+```html
+<ul role="list">
+  <li>One</li>
+  <li>Two</li>
+</ul>
+```
+
+### Images Are Block-Level
+
+Images and replaced elements are `display: block`:
+
+```css
+img, svg, video, canvas, audio, iframe, embed, object {
+  display: block;
+  vertical-align: middle;
+}
+```
+
+Use `inline` utility if needed:
+
+```html
+<img class="inline" src="..." alt="..." />
+```
+
+### Images Are Constrained
+
+Images and videos are constrained to parent width:
+
+```css
+img, video {
+  max-width: 100%;
+  height: auto;
+}
+```
+
+Override with `max-w-none`:
+
+```html
+<img class="max-w-none" src="..." alt="..." />
+```
+
+### Hidden Attribute
+
+Elements with `hidden` attribute stay hidden:
+
+```css
+[hidden]:where(:not([hidden="until-found"])) {
+  display: none !important;
+}
+```
+
+## Extending Preflight
+
+Add base styles to the `base` layer:
+
+```css
+@layer base {
+  h1 {
+    font-size: var(--text-2xl);
+    font-weight: 600;
+  }
+  
+  h2 {
+    font-size: var(--text-xl);
+    font-weight: 600;
+  }
+  
+  a {
+    color: var(--color-blue-600);
+    text-decoration-line: underline;
+  }
+}
+```
+
+## Disabling Preflight
+
+Import Tailwind components individually, omitting Preflight:
+
+```css
+@layer theme, base, components, utilities;
+
+@import "tailwindcss/theme.css" layer(theme);
+/* @import "tailwindcss/preflight.css" layer(base); */ /* Omitted */
+@import "tailwindcss/utilities.css" layer(utilities);
+```
+
+## Working Around Third-Party Libraries
+
+Some libraries may conflict with Preflight. Override Preflight styles:
+
+```css
+@layer base {
+  .google-map * {
+    border-style: none;
+  }
+}
+```
+
+## Key Points
+
+- Preflight normalizes cross-browser inconsistencies
+- Margins, borders, headings, and lists are reset
+- Images are block-level and constrained by default
+- Extend Preflight with `@layer base`
+- Disable by omitting the preflight import
+- Override Preflight styles when needed for third-party libraries
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/preflight
+-->