@biggora/claude-plugins 1.2.0 → 1.3.0

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
+-->

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
+-->