@biggora/claude-plugins 1.2.0 → 1.2.2

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

@@ -0,0 +1,163 @@
+---
+name: core-responsive
+description: Building responsive designs with Tailwind's mobile-first breakpoint system and container queries
+---
+
+# Responsive Design
+
+Every utility class in Tailwind can be applied conditionally at different breakpoints using responsive variants.
+
+## Mobile-First Breakpoints
+
+Tailwind uses a mobile-first approach. Unprefixed utilities apply to all screen sizes, while prefixed utilities apply at that breakpoint and above.
+
+```html
+<!-- Center text on mobile, left align on sm screens and up -->
+<div class="text-center sm:text-left">Content</div>
+```
+
+## Default Breakpoints
+
+| Breakpoint | Minimum Width | CSS |
+|------------|---------------|-----|
+| `sm` | 40rem (640px) | `@media (width >= 40rem)` |
+| `md` | 48rem (768px) | `@media (width >= 48rem)` |
+| `lg` | 64rem (1024px) | `@media (width >= 64rem)` |
+| `xl` | 80rem (1280px) | `@media (width >= 80rem)` |
+| `2xl` | 96rem (1536px) | `@media (width >= 96rem)` |
+
+## Usage
+
+Prefix any utility with a breakpoint name:
+
+```html
+<!-- Width of 16 by default, 32 on medium screens, 48 on large screens -->
+<img class="w-16 md:w-32 lg:w-48" src="..." />
+```
+
+## Example: Responsive Card
+
+```html
+<div class="mx-auto max-w-md md:max-w-2xl">
+  <div class="md:flex">
+    <div class="md:shrink-0">
+      <img class="h-48 w-full object-cover md:h-full md:w-48" src="..." />
+    </div>
+    <div class="p-8">
+      <h2 class="text-lg font-semibold">Title</h2>
+      <p class="text-gray-500">Description</p>
+    </div>
+  </div>
+</div>
+```
+
+## Targeting Mobile Screens
+
+Use unprefixed utilities for mobile, not `sm:`. Think of `sm:` as "at the small breakpoint", not "on small screens".
+
+```html
+<!-- ❌ Only centers on screens 640px+, not mobile -->
+<div class="sm:text-center"></div>
+
+<!-- ✅ Centers on mobile, left aligns on 640px+ -->
+<div class="text-center sm:text-left"></div>
+```
+
+## Breakpoint Ranges
+
+Target a specific breakpoint range by stacking responsive variants with `max-*` variants:
+
+```html
+<!-- Only applies between md and xl -->
+<div class="md:max-xl:flex">Content</div>
+```
+
+## Max-Width Variants
+
+Tailwind generates `max-*` variants for each breakpoint:
+
+| Variant | Media Query |
+|---------|-------------|
+| `max-sm` | `@media (width < 40rem)` |
+| `max-md` | `@media (width < 48rem)` |
+| `max-lg` | `@media (width < 64rem)` |
+| `max-xl` | `@media (width < 80rem)` |
+| `max-2xl` | `@media (width < 96rem)` |
+
+## Custom Breakpoints
+
+Add custom breakpoints using `--breakpoint-*` theme variables:
+
+```css
+@theme {
+  --breakpoint-xs: 30rem;
+  --breakpoint-3xl: 120rem;
+}
+```
+
+```html
+<div class="xs:grid-cols-2 3xl:grid-cols-6">Content</div>
+```
+
+## Arbitrary Breakpoints
+
+Use arbitrary values for one-off breakpoints:
+
+```html
+<div class="min-[320px]:text-center max-[600px]:bg-sky-300">
+  Content
+</div>
+```
+
+## Container Queries
+
+Style elements based on parent container size instead of viewport:
+
+```html
+<!-- Mark container -->
+<div class="@container">
+  <!-- Style based on container size -->
+  <div class="flex flex-col @md:flex-row">
+    Content
+  </div>
+</div>
+```
+
+### Container Query Variants
+
+| Variant | Minimum Width |
+|---------|---------------|
+| `@3xs` | 16rem (256px) |
+| `@xs` | 20rem (320px) |
+| `@sm` | 24rem (384px) |
+| `@md` | 28rem (448px) |
+| `@lg` | 32rem (512px) |
+| `@xl` | 36rem (576px) |
+| `@2xl` | 42rem (672px) |
+| `@3xl` | 48rem (768px) |
+| ... up to `@7xl` | 80rem (1280px) |
+
+### Named Containers
+
+Name containers to target specific ones in nested structures:
+
+```html
+<div class="@container/main">
+  <div class="flex flex-row @sm/main:flex-col">
+    Content
+  </div>
+</div>
+```
+
+## Key Points
+
+- Mobile-first: unprefixed = mobile, prefixed = breakpoint and up
+- Use unprefixed utilities for mobile, not `sm:`
+- Stack variants for complex responsive behavior
+- Container queries enable component-based responsive design
+- Customize breakpoints with theme variables
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/responsive-design
+-->

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

@@ -0,0 +1,114 @@
+---
+name: core-source-detection
+description: How Tailwind v4 detects classes in source files, @source directives, @source not, and @source inline() for safelisting
+---
+
+# Source Detection & Configuration
+
+Tailwind v4 automatically scans your project for utility classes. This page covers how detection works and how to customize it.
+
+## Automatic Detection
+
+By default, Tailwind scans all files in your project except:
+
+- Files matching `.gitignore` patterns
+- `node_modules/` directory (ignored since v4.1)
+- Binary files (images, videos, zips)
+- CSS files
+- Package manager lock files
+
+Files are scanned as **plain text** — Tailwind does not parse your code. It looks for token patterns that match utility class names.
+
+## Source Configuration
+
+### Register additional sources
+
+Scan files outside the project root (e.g., UI library in node_modules):
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@acmecorp/ui-lib";
+```
+
+### Set a base path
+
+Restrict scanning to a specific directory (useful for monorepos):
+
+```css
+@import "tailwindcss" source("../src");
+```
+
+### Disable automatic detection
+
+Scan only explicitly listed paths:
+
+```css
+@import "tailwindcss" source(none);
+@source "../admin";
+@source "../shared";
+```
+
+## Excluding Sources (v4.1+)
+
+Exclude paths from scanning:
+
+```css
+@source not "../src/components/legacy";
+@source not "./generated";
+```
+
+## Safelisting with @source inline() (v4.1+)
+
+Force generation of classes not found in source files. This replaces the v3 `safelist` config option.
+
+```css
+/* Single utility */
+@source inline("underline");
+
+/* With variants */
+@source inline("{hover:,focus:,}underline");
+
+/* Color palette with brace expansion */
+@source inline("{hover:,}bg-red-{50,{100..900..100},950}");
+
+/* Exclude specific classes */
+@source not inline("{hover:,focus:,}bg-red-{50,{100..900..100},950}");
+```
+
+Brace expansion follows shell-style syntax:
+- `{a,b,c}` — list of values
+- `{100..900..100}` — range with step (100, 200, 300, ..., 900)
+
+## Dynamic Class Names
+
+Because Tailwind scans files as plain text, it cannot detect dynamically constructed class names:
+
+```jsx
+// BAD — Tailwind won't detect these
+const color = 'red';
+<div className={`bg-${color}-500`} />
+
+// GOOD — Use complete class names
+const colorClasses = {
+  red: 'bg-red-500',
+  blue: 'bg-blue-500',
+};
+<div className={colorClasses[color]} />
+```
+
+If you must use dynamic classes, safelist them with `@source inline()`.
+
+## Key Points
+
+- Automatic detection scans all non-ignored, non-binary files
+- `@source "path"` adds additional scan paths
+- `@source not "path"` excludes paths (v4.1+)
+- `@source inline("classes")` safelists classes (v4.1+), replaces v3 `safelist`
+- `source(none)` on the import disables auto-detection
+- Always use complete class names — never string-interpolate utility names
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/detecting-classes-in-source-files
+- https://tailwindcss.com/blog/tailwindcss-v4-1
+-->

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

@@ -0,0 +1,108 @@
+---
+name: core-theme
+description: Understanding theme variables, design tokens, and customizing Tailwind's default theme
+---
+
+# Theme Variables
+
+Theme variables are special CSS variables defined using the `@theme` directive that influence which utility classes exist in your project.
+
+## Overview
+
+Theme variables store design tokens like colors, fonts, spacing, shadows, and breakpoints. They're defined using the `@theme` directive:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-mint-500: oklch(0.72 0.11 178);
+  --font-display: "Satoshi", "sans-serif";
+  --breakpoint-3xl: 120rem;
+}
+```
+
+Now utilities like `bg-mint-500`, `font-display`, and `3xl:grid-cols-6` become available.
+
+## Why @theme Instead of :root?
+
+Theme variables aren't just CSS variables - they also instruct Tailwind to create new utility classes. Using `@theme` makes this explicit and ensures variables are defined top-level.
+
+Use `@theme` for design tokens that map to utilities. Use `:root` for regular CSS variables that shouldn't have corresponding utilities.
+
+## Theme Variable Namespaces
+
+Theme variables are organized into namespaces that map to utility classes:
+
+| Namespace | Utility Classes |
+|-----------|----------------|
+| `--color-*` | `bg-red-500`, `text-sky-300`, `border-indigo-600`, etc. |
+| `--font-*` | `font-sans`, `font-serif`, `font-mono` |
+| `--breakpoint-*` | Responsive variants like `md:`, `lg:`, `xl:` |
+| `--spacing-*` | Spacing scale for padding, margin, gap utilities |
+| `--shadow-*` | `shadow-sm`, `shadow-md`, `shadow-lg` |
+| `--ease-*` | Transition timing functions |
+
+## Extending the Default Theme
+
+Add new theme variables to extend the default theme:
+
+```css
+@import "tailwindcss";
+
+@theme {
+  /* Add new color */
+  --color-brand-500: oklch(0.65 0.2 250);
+  
+  /* Add new breakpoint */
+  --breakpoint-3xl: 120rem;
+  
+  /* Add new font */
+  --font-display: "Satoshi", "sans-serif";
+}
+```
+
+## Using Theme Variables
+
+Tailwind generates CSS variables for your theme variables, so you can reference them:
+
+```html
+<!-- Use utility classes -->
+<div class="bg-brand-500 text-display">Content</div>
+
+<!-- Reference CSS variables directly -->
+<div style="background-color: var(--color-brand-500)">
+  Content
+</div>
+```
+
+## Default Theme
+
+When you import `tailwindcss`, it includes default theme variables:
+
+```css
+@layer theme, base, components, utilities;
+
+@import "./theme.css" layer(theme);
+@import "./preflight.css" layer(base);
+@import "./utilities.css" layer(utilities);
+```
+
+The default theme includes:
+- Color palette (red, blue, green, etc. with 50-950 shades)
+- Font families (sans, serif, mono)
+- Spacing scale
+- Shadows
+- Breakpoints (sm, md, lg, xl, 2xl)
+
+## Key Points
+
+- Theme variables define which utilities exist in your project
+- Use `@theme` directive to define design tokens
+- Variables must be defined top-level, not nested
+- Tailwind generates both utilities and CSS variables
+- Default theme provides a solid starting point
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/theme
+-->

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

@@ -0,0 +1,59 @@
+---
+name: core-utility-classes
+description: Understanding Tailwind's utility-first approach and how to style elements with utility classes
+---
+
+# Utility Classes
+
+Tailwind CSS uses a utility-first approach where you style elements by combining many single-purpose utility classes directly in your markup.
+
+## Overview
+
+Instead of writing custom CSS, you compose designs using utility classes:
+
+```html
+<div class="mx-auto flex max-w-sm items-center gap-x-4 rounded-xl bg-white p-6 shadow-lg">
+  <img class="size-12 shrink-0" src="/logo.svg" alt="Logo" />
+  <div>
+    <div class="text-xl font-medium text-black">ChitChat</div>
+    <p class="text-gray-500">You have a new message!</p>
+  </div>
+</div>
+```
+
+## Benefits
+
+- **Faster development** - No need to come up with class names or switch between HTML and CSS files
+- **Safer changes** - Adding or removing utilities only affects that element
+- **Easier maintenance** - Find the element and change classes, no need to remember custom CSS
+- **More portable** - Copy entire UI chunks between projects easily
+- **Smaller CSS** - Utilities are reusable, so CSS doesn't grow linearly
+
+## Why Not Inline Styles?
+
+Utility classes have important advantages over inline styles:
+
+- **Design constraints** - Choose from a predefined design system instead of magic numbers
+- **State variants** - Target hover, focus, and other states with variants like `hover:bg-blue-600`
+- **Responsive design** - Use responsive variants like `md:flex` for media queries
+
+## Utility Class Structure
+
+Utility classes follow consistent naming patterns:
+
+- **Property-value**: `bg-blue-500`, `text-lg`, `rounded-xl`
+- **Responsive**: `md:flex`, `lg:text-center`
+- **State variants**: `hover:bg-blue-600`, `focus:outline-2`
+- **Arbitrary values**: `top-[117px]`, `bg-[#bada55]`
+
+## Key Points
+
+- Every utility class is single-purpose and composable
+- Utilities can be combined with variants for conditional styling
+- Use complete class names - Tailwind scans your files as plain text
+- Avoid dynamically constructing class names with string interpolation
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/styling-with-utility-classes
+-->

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

@@ -0,0 +1,204 @@
+---
+name: core-variants
+description: Using variants to apply utilities conditionally based on states, pseudo-classes, and media queries
+---
+
+# Variants
+
+Variants let you apply utility classes conditionally based on states, pseudo-classes, pseudo-elements, media queries, and more.
+
+## Overview
+
+Add a variant prefix to any utility class to apply it conditionally:
+
+```html
+<!-- Apply bg-sky-700 only on hover -->
+<button class="bg-sky-500 hover:bg-sky-700">Save</button>
+```
+
+Variants can be stacked to target specific situations:
+
+```html
+<!-- Dark mode, medium breakpoint, on hover -->
+<button class="dark:md:hover:bg-fuchsia-600">Save</button>
+```
+
+## Pseudo-Class Variants
+
+### Interactive States
+
+```html
+<button class="bg-violet-500 hover:bg-violet-600 focus:outline-2 focus:outline-violet-500 active:bg-violet-700">
+  Save changes
+</button>
+```
+
+Common interactive variants:
+- `hover:` - `:hover` pseudo-class
+- `focus:` - `:focus` pseudo-class
+- `active:` - `:active` pseudo-class
+- `focus-visible:` - `:focus-visible`
+- `focus-within:` - `:focus-within`
+- `visited:` - `:visited`
+
+### Structural Variants
+
+```html
+<ul>
+  <li class="py-4 first:pt-0 last:pb-0">Item 1</li>
+  <li class="py-4 first:pt-0 last:pb-0">Item 2</li>
+  <li class="py-4 first:pt-0 last:pb-0">Item 3</li>
+</ul>
+```
+
+Common structural variants:
+- `first:` - `:first-child`
+- `last:` - `:last-child`
+- `odd:` - `:nth-child(odd)`
+- `even:` - `:nth-child(even)`
+- `only:` - `:only-child`
+
+### Form States
+
+```html
+<input class="border-gray-300 required:border-red-500 invalid:border-red-500" />
+```
+
+Common form variants:
+- `required:` - `:required`
+- `optional:` - `:optional`
+- `invalid:` - `:invalid`
+- `valid:` - `:valid`
+- `disabled:` - `:disabled`
+- `enabled:` - `:enabled`
+- `checked:` - `:checked`
+- `user-valid:` - `:user-valid` (v4.1) — validation after user interaction
+- `user-invalid:` - `:user-invalid` (v4.1) — invalid after user interaction
+
+```html
+<!-- Better UX: only show validation state after user interacts -->
+<input required class="border user-valid:border-green-500 user-invalid:border-red-500" />
+```
+
+## Pseudo-Element Variants
+
+```html
+<input class="placeholder:text-gray-400 before:content-['*'] after:content-['required']" />
+```
+
+Common pseudo-element variants:
+- `before:` - `::before`
+- `after:` - `::after`
+- `placeholder:` - `::placeholder`
+- `selection:` - `::selection`
+- `first-line:` - `::first-line`
+- `first-letter:` - `::first-letter`
+
+## Media Query Variants
+
+### Responsive Variants
+
+```html
+<div class="text-sm md:text-base lg:text-lg">Responsive text</div>
+```
+
+### Dark Mode
+
+```html
+<div class="bg-white dark:bg-gray-800 text-gray-900 dark:text-white">
+  Content
+</div>
+```
+
+By default uses `prefers-color-scheme`, but can be customized to use a class or data attribute.
+
+### Reduced Motion
+
+```html
+<div class="transition-all motion-reduce:transition-none">
+  Animated content
+</div>
+```
+
+### Pointer Device Variants (v4.1+)
+
+Target specific input devices:
+
+```html
+<!-- Larger touch targets on touch devices -->
+<button class="p-2 pointer-coarse:p-4 pointer-coarse:text-lg">
+  Touch-friendly button
+</button>
+
+<!-- Fine details only on mouse/trackpad -->
+<div class="hidden pointer-fine:block">
+  Precise hover details
+</div>
+```
+
+- `pointer-fine:` — precise pointing device (mouse, trackpad)
+- `pointer-coarse:` — imprecise device (touchscreen)
+- `pointer-none:` — no pointing device
+- `any-pointer-fine:` / `any-pointer-coarse:` — any available device
+
+### Other New Variants (v4.1+)
+
+```html
+<!-- Style <details> content -->
+<details class="details-content:mt-3 details-content:p-4" open>
+  <summary>FAQ Question</summary>
+  <div>Answer content</div>
+</details>
+
+<!-- Show fallback when JS disabled -->
+<div class="hidden noscript:block">Please enable JavaScript.</div>
+
+<!-- Respect inverted colors preference -->
+<img class="inverted-colors:hue-rotate-180" />
+```
+
+- `details-content:` — target content inside `<details>`
+- `noscript:` — styles when JavaScript is disabled
+- `inverted-colors:` — when user has inverted colors preference
+
+## Attribute Selector Variants
+
+```html
+<!-- RTL support -->
+<div class="text-left rtl:text-right">Content</div>
+
+<!-- Open state -->
+<details class="[&[open]]:bg-gray-100">Details</details>
+```
+
+## Arbitrary Variants
+
+Use arbitrary variants for custom selectors:
+
+```html
+<ul>
+  <li class="lg:[&:nth-child(-n+3)]:hover:underline">Item</li>
+</ul>
+```
+
+## Child Selector Variants
+
+```html
+<div class="[&>*]:mb-4 [&>*:last-child]:mb-0">
+  <p>Paragraph 1</p>
+  <p>Paragraph 2</p>
+</div>
+```
+
+## Key Points
+
+- Variants prefix utilities to apply them conditionally
+- Variants can be stacked: `dark:md:hover:bg-blue-600`
+- Use variants for states, pseudo-classes, media queries, and more
+- Arbitrary variants enable custom selector patterns
+- Child selector variants target descendant elements
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/hover-focus-and-other-states
+-->