@biggora/claude-plugins 1.1.1 → 1.2.2

package/src/skills/tailwindcss-best-practices/references/features-functions-directives.md

@@ -0,0 +1,241 @@
+---
+name: features-functions-directives
+description: Tailwind's CSS directives (@import, @theme, @utility, @variant) and functions (--alpha, --spacing)
+---
+
+# Functions and Directives
+
+Tailwind provides custom CSS directives and functions for working with your design system.
+
+## Directives
+
+Directives are custom Tailwind-specific at-rules that offer special functionality.
+
+### @import
+
+Import CSS files, including Tailwind:
+
+```css
+@import "tailwindcss";
+```
+
+### @theme
+
+Define your project's design tokens:
+
+```css
+@theme {
+  --font-display: "Satoshi", "sans-serif";
+  --breakpoint-3xl: 120rem;
+  --color-brand-500: oklch(0.65 0.2 250);
+  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
+}
+```
+
+### @source
+
+Explicitly specify source files for class detection:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@my-company/ui-lib";
+```
+
+### @utility
+
+Add custom utilities:
+
+```css
+@utility tab-4 {
+  tab-size: 4;
+}
+```
+
+Custom utilities work with variants:
+
+```html
+<div class="tab-4 hover:tab-8">Content</div>
+```
+
+### @variant
+
+Apply Tailwind variants to styles in your CSS:
+
+```css
+.my-element {
+  background: white;
+  
+  @variant dark {
+    background: black;
+  }
+}
+```
+
+### @custom-variant
+
+Add custom variants:
+
+```css
+@custom-variant theme-midnight (&:where([data-theme="midnight"] *));
+```
+
+```html
+<div class="theme-midnight:bg-black">Content</div>
+```
+
+### @apply
+
+Inline existing utility classes into custom CSS:
+
+```css
+.select2-dropdown {
+  @apply rounded-b-lg shadow-md;
+}
+
+.select2-search {
+  @apply rounded border border-gray-300;
+}
+```
+
+### @reference
+
+Import stylesheet for reference without including styles (useful for Vue/Svelte components):
+
+```html
+<style>
+  @reference "../../app.css";
+  
+  h1 {
+    @apply text-2xl font-bold text-red-500;
+  }
+</style>
+```
+
+Or reference Tailwind directly:
+
+```html
+<style>
+  @reference "tailwindcss";
+  
+  h1 {
+    @apply text-2xl font-bold;
+  }
+</style>
+```
+
+### Subpath Imports
+
+Directives support subpath imports (like TypeScript path aliases):
+
+```json
+{
+  "imports": {
+    "#app.css": "./src/css/app.css"
+  }
+}
+```
+
+```html
+<style>
+  @reference "#app.css";
+  
+  h1 {
+    @apply text-2xl font-bold;
+  }
+</style>
+```
+
+## Functions
+
+Tailwind provides build-time functions for working with colors and spacing.
+
+### --alpha()
+
+Adjust the opacity of a color:
+
+```css
+.my-element {
+  color: --alpha(var(--color-lime-300) / 50%);
+}
+```
+
+Compiles to:
+
+```css
+.my-element {
+  color: color-mix(in oklab, var(--color-lime-300) 50%, transparent);
+}
+```
+
+### --spacing()
+
+Generate spacing values based on your theme:
+
+```css
+.my-element {
+  margin: --spacing(4);
+}
+```
+
+Compiles to:
+
+```css
+.my-element {
+  margin: calc(var(--spacing) * 4);
+}
+```
+
+Useful in arbitrary values with `calc()`:
+
+```html
+<div class="py-[calc(--spacing(4)-1px)]">
+  Content
+</div>
+```
+
+## Compatibility Directives
+
+For compatibility with Tailwind CSS v3.x:
+
+### @config
+
+Load a legacy JavaScript-based configuration:
+
+```css
+@config "../../tailwind.config.js";
+```
+
+### @plugin
+
+Load a legacy JavaScript-based plugin:
+
+```css
+@plugin "@tailwindcss/typography";
+```
+
+### theme()
+
+Access theme values using dot notation (deprecated):
+
+```css
+.my-element {
+  margin: theme(spacing.12);
+}
+```
+
+**Note:** Prefer using CSS theme variables instead.
+
+## Key Points
+
+- Directives are Tailwind-specific at-rules
+- `@theme` defines design tokens
+- `@utility` creates custom utilities
+- `@custom-variant` creates custom variants
+- `@apply` inlines utilities into CSS
+- `--alpha()` and `--spacing()` are build-time functions
+- Compatibility directives support v3.x configs
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/functions-and-directives
+-->

package/src/skills/tailwindcss-best-practices/references/features-upgrade.md

@@ -0,0 +1,160 @@
+---
+name: features-upgrade
+description: Migrating from Tailwind CSS v3 to v4, all renamed utilities, scale shifts, config migration, and v4.1/v4.2 changes
+---
+
+# Upgrade Guide (v3 → v4)
+
+Key changes when upgrading from Tailwind CSS v3 to v4. Use the automated upgrade tool when possible.
+
+## Upgrade Tool
+
+```bash
+npx @tailwindcss/upgrade
+```
+
+Requires Node.js 20+. Run in a new branch, review diff, test. Handles most migration automatically.
+
+## Installation Changes
+
+- **PostCSS**: Use `@tailwindcss/postcss`; remove `postcss-import` and `autoprefixer` (handled by v4)
+- **Vite**: Prefer `@tailwindcss/vite` over PostCSS (supports Vite 8+ as of v4.2.2)
+- **Webpack**: Use `@tailwindcss/webpack` (new in v4.2)
+- **CLI**: Use `npx @tailwindcss/cli` instead of `npx tailwindcss`
+
+## Import Change
+
+```css
+/* v3 */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* v4 */
+@import "tailwindcss";
+```
+
+## Renamed Utilities — Scale Shifts
+
+These are the most commonly missed renames because the entire scale shifted down by one step:
+
+| v3 | v4 | What happened |
+|----|-----|---------------|
+| `shadow-sm` | `shadow-xs` | Scale shifted down |
+| `shadow` | `shadow-sm` | Scale shifted down |
+| `rounded-sm` | `rounded-xs` | Scale shifted down |
+| `rounded` | `rounded-sm` | Scale shifted down |
+| `blur-sm` | `blur-xs` | Scale shifted down |
+| `blur` | `blur-sm` | Scale shifted down |
+
+## Renamed Utilities — Other
+
+| v3 | v4 |
+|----|-----|
+| `outline-none` | `outline-hidden` |
+| `ring` | `ring-3` (default width changed from 3px to 1px) |
+
+## Important Modifier
+
+```html
+<!-- v3: ! at start -->
+<div class="!bg-red-500">
+
+<!-- v4: ! at end -->
+<div class="bg-red-500!">
+```
+
+## Removed / Replaced
+
+| v3 | v4 |
+|----|-----|
+| `bg-opacity-*`, `text-opacity-*`, etc. | `bg-black/50`, `text-black/50` (slash syntax) |
+| `flex-shrink-*` | `shrink-*` |
+| `flex-grow-*` | `grow-*` |
+| `overflow-ellipsis` | `text-ellipsis` |
+| `decoration-slice` / `decoration-clone` | `box-decoration-slice` / `box-decoration-clone` |
+
+## Ring & Border Defaults
+
+- `ring` width: 3px → 1px; use `ring-3` for v3 behavior
+- `ring` / `border` default color: `currentColor` (was gray-200 / blue-500 in v3)
+- Always specify color: `ring-3 ring-blue-500`, `border border-gray-200`
+
+## Configuration Migration
+
+| v3 Concept | v4 Equivalent |
+|------------|---------------|
+| `tailwind.config.js` | Removed. Use CSS directives. |
+| `darkMode: 'class'` | `@custom-variant dark (&:where(.dark, .dark *));` |
+| `darkMode: 'media'` | Default in v4 (uses `prefers-color-scheme`). No config needed. |
+| `theme.extend.colors` | `@theme { --color-*: value; }` |
+| `theme.extend.screens` | `@theme { --breakpoint-*: value; }` |
+| `theme.extend.fontFamily` | `@theme { --font-*: value; }` |
+| `content: [...]` | Automatic detection. Use `@source` to add/exclude paths. |
+| `safelist: [...]` | `@source inline("classes")` (v4.1+) |
+| `@layer utilities { }` | `@utility name { }` |
+| `plugins: [...]` | `@plugin "./my-plugin.js"` |
+
+## CSS Variable Syntax Change
+
+```html
+<!-- v3: square brackets for CSS variables -->
+<div class="bg-[--my-var]">
+
+<!-- v4: parentheses for CSS variables -->
+<div class="bg-(--my-var)">
+```
+
+## Theme Function Change
+
+```css
+/* v3 */
+@media (min-width: theme(screens.xl)) { ... }
+
+/* v4 */
+@media (min-width: theme(--breakpoint-xl)) { ... }
+```
+
+## Other Breaking Changes
+
+- **Variant stacking**: Left-to-right in v4 (was right-to-left in v3)
+- **Transform reset**: `transform-none` no longer resets rotate/scale/translate; use `scale-none`, `rotate-none`, etc.
+- **Hover on mobile**: `hover` only applies when device supports hover; override with `@custom-variant hover (&:hover)` if needed
+- **Space/divide selectors**: Changed from `:not([hidden]) ~ :not([hidden])` to `:not(:last-child)`
+- **Sass/Less/Stylus**: v4 not designed for use with CSS preprocessors
+
+## Deprecations in v4.2
+
+- `start-*` / `end-*` → use `inset-s-*` / `inset-e-*`
+- `bg-left-top` style → use `bg-top-left` (position order reversed)
+- `object-left-top` style → use `object-top-left` (position order reversed)
+
+## Browser Support
+
+v4 targets Safari 16.4+, Chrome 111+, Firefox 128+. For older browsers, stay on v3.4.
+
+## Post-v4.0 Feature Additions
+
+### v4.1 (April 2025)
+- Text shadow utilities (`text-shadow-*`)
+- Mask utilities (`mask-*`)
+- Colored drop shadows (`drop-shadow-<color>`)
+- Text wrapping (`wrap-break-word`, `wrap-anywhere`)
+- Pointer device variants (`pointer-fine:`, `pointer-coarse:`)
+- Safe alignment (`justify-center-safe`, `items-center-safe`)
+- New variants: `details-content`, `inverted-colors`, `noscript`, `user-valid`, `user-invalid`
+- `@source not` and `@source inline()` directives
+
+### v4.2 (February 2025)
+- New colors: mauve, olive, mist, taupe
+- Webpack plugin (`@tailwindcss/webpack`)
+- Block logical property utilities (`pbs-*`, `mbs-*`, `border-bs-*`, `inline-*`, `block-*`)
+- Logical inset utilities (`inset-s-*`, `inset-e-*`, `inset-bs-*`, `inset-be-*`)
+- Font feature settings (`font-features-*`)
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/upgrade-guide
+- https://tailwindcss.com/blog/tailwindcss-v4-1
+- https://github.com/tailwindlabs/tailwindcss/releases/tag/v4.2.0
+-->

package/src/skills/tailwindcss-best-practices/references/layout-aspect-ratio.md

@@ -0,0 +1,39 @@
+---
+name: layout-aspect-ratio
+description: Controlling element aspect ratio for responsive media
+---
+
+# Aspect Ratio
+
+Utilities for controlling the aspect ratio of an element (e.g. video, images).
+
+## Usage
+
+```html
+<!-- 16:9 video container -->
+<div class="aspect-video">
+  <iframe src="..."></iframe>
+</div>
+
+<!-- 4:3 -->
+<div class="aspect-[4/3]">Content</div>
+
+<!-- Square -->
+<div class="aspect-square">1:1</div>
+
+<!-- Auto (intrinsic) -->
+<div class="aspect-auto">Natural ratio</div>
+```
+
+## Key Points
+
+- `aspect-video` - 16:9
+- `aspect-square` - 1:1
+- `aspect-auto` - browser default (intrinsic)
+- `aspect-[4/3]` - arbitrary ratio
+- Useful for responsive video embeds and image containers
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/aspect-ratio
+-->

package/src/skills/tailwindcss-best-practices/references/layout-columns.md

@@ -0,0 +1,80 @@
+---
+name: layout-columns
+description: Multi-column layout with columns utility for masonry-like or newspaper layouts
+---
+
+# Columns
+
+Utilities for CSS multi-column layout. Content flows into multiple columns within a single element.
+
+## Usage
+
+### By number of columns
+
+```html
+<div class="columns-3 gap-8">
+  <img class="aspect-3/2" src="1.jpg" />
+  <img class="aspect-square" src="2.jpg" />
+  <!-- Content flows into 3 columns -->
+</div>
+```
+
+### By column width
+
+Use container scale for ideal column width; column count adjusts automatically:
+
+```html
+<div class="columns-3xs gap-4">...</div>
+<div class="columns-sm gap-6">...</div>
+<div class="columns-md">...</div>
+```
+
+### Column gap
+
+Use `gap-*` utilities for space between columns:
+
+```html
+<div class="columns-3 gap-8">...</div>
+```
+
+### Responsive
+
+```html
+<div class="columns-2 gap-4 sm:columns-3 sm:gap-8">...</div>
+```
+
+### Custom value
+
+```html
+<div class="columns-[30vw]">...</div>
+<div class="columns-(--my-columns)">...</div>
+```
+
+### Column / page breaks
+
+Use with multi-column or print layouts:
+
+```html
+<div class="columns-2">
+  <p>Content...</p>
+  <p class="break-after-column">Force break after this</p>
+  <p>Next column...</p>
+</div>
+```
+
+- `break-after-column` / `break-before-column` - column break
+- `break-after-page` / `break-before-page` - page break (print)
+- `break-after-avoid` / `break-inside-avoid` - avoid breaking
+
+## Key Points
+
+- `columns-<n>` - fixed number of columns (e.g. `columns-3`)
+- `columns-3xs` through `columns-7xl` - column width from container scale
+- `columns-auto` - auto columns
+- `gap-*` controls column gap (same as flex/grid gap)
+- Use for magazine-style layouts, image galleries, long text
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/columns
+-->

package/src/skills/tailwindcss-best-practices/references/layout-display.md

@@ -0,0 +1,110 @@
+---
+name: layout-display
+description: Controlling element display type including flex, grid, block, inline, hidden, and sr-only
+---
+
+# Display
+
+Utilities for controlling the display box type of an element.
+
+## Usage
+
+### Basic display types
+
+```html
+<span class="inline">display: inline</span>
+<span class="inline-block">display: inline-block</span>
+<div class="block">display: block</div>
+```
+
+### Flex and Grid containers
+
+```html
+<!-- Flex container -->
+<div class="flex items-center gap-4">Flex layout</div>
+<span class="inline-flex items-baseline">Inline flex with text</span>
+
+<!-- Grid container -->
+<div class="grid grid-cols-3 gap-4">Grid layout</div>
+<span class="inline-grid grid-cols-3 gap-4">Inline grid</span>
+```
+
+### Flow root
+
+Use `flow-root` to create a block-level element with its own block formatting context (fixes margin collapse):
+
+```html
+<div class="flow-root">
+  <div class="my-4">Content with isolated BFC</div>
+</div>
+```
+
+### Contents
+
+Use `contents` for a "phantom" container whose children act like direct children of the parent:
+
+```html
+<div class="flex">
+  <div class="flex-1">01</div>
+  <div class="contents">
+    <div class="flex-1">02</div>
+    <div class="flex-1">03</div>
+  </div>
+  <div class="flex-1">04</div>
+</div>
+```
+
+### Table display
+
+```html
+<div class="table w-full">
+  <div class="table-header-group bg-gray-100">
+    <div class="table-row">
+      <div class="table-cell p-2">Header 1</div>
+      <div class="table-cell p-2">Header 2</div>
+    </div>
+  </div>
+  <div class="table-row-group">
+    <div class="table-row">
+      <div class="table-cell p-2">Cell 1</div>
+      <div class="table-cell p-2">Cell 2</div>
+    </div>
+  </div>
+</div>
+```
+
+### Hidden
+
+```html
+<div class="hidden">Removed from document flow</div>
+<div class="md:block hidden">Visible only on md+</div>
+```
+
+For visual-only hiding while keeping in DOM, use `invisible` or `opacity-0` instead.
+
+### Screen reader only
+
+```html
+<a href="#">
+  <svg><!-- icon --></svg>
+  <span class="sr-only">Settings</span>
+</a>
+```
+
+Use `not-sr-only` to undo: `<span class="sr-only sm:not-sr-only">Settings</span>`
+
+## Key Points
+
+- `flex` / `inline-flex` - Flexbox layout
+- `grid` / `inline-grid` - CSS Grid layout
+- `block` / `inline` / `inline-block` - Basic flow
+- `hidden` - `display: none` (removes from flow)
+- `sr-only` - Visually hidden but accessible to screen readers
+- `contents` - Children participate in parent's layout
+- `flow-root` - Establishes new BFC
+- Table utilities: `table`, `table-row`, `table-cell`, `table-header-group`, etc.
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/display
+-->