@biggora/claude-plugins 1.2.0 → 1.2.2

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

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

@@ -0,0 +1,112 @@
+---
+name: layout-flexbox
+description: Flexbox layout utilities including flex-direction, justify, items, gap, grow, shrink, and wrap
+---
+
+# Flexbox
+
+Utilities for building flex layouts: direction, alignment, gap, and item sizing.
+
+## Usage
+
+### Flex direction and wrap
+
+```html
+<div class="flex flex-row">Horizontal (default)</div>
+<div class="flex flex-row-reverse">Reversed</div>
+<div class="flex flex-col">Vertical</div>
+<div class="flex flex-col-reverse">Vertical reversed</div>
+
+<div class="flex flex-wrap">Wrap when needed</div>
+<div class="flex flex-nowrap">No wrap (default)</div>
+<div class="flex flex-wrap-reverse">Wrap reversed</div>
+```
+
+### Justify content
+
+```html
+<div class="flex justify-start">Start</div>
+<div class="flex justify-end">End</div>
+<div class="flex justify-center">Center</div>
+<div class="flex justify-between">Space between</div>
+<div class="flex justify-around">Space around</div>
+<div class="flex justify-evenly">Space evenly</div>
+```
+
+### Align items
+
+```html
+<div class="flex items-start">Align start</div>
+<div class="flex items-end">Align end</div>
+<div class="flex items-center">Center (common)</div>
+<div class="flex items-baseline">Baseline</div>
+<div class="flex items-stretch">Stretch (default)</div>
+```
+
+### Align self (on flex children)
+
+```html
+<div class="flex">
+  <div class="self-auto">Auto</div>
+  <div class="self-start">Start</div>
+  <div class="self-center">Center</div>
+  <div class="self-stretch">Stretch</div>
+</div>
+```
+
+### Gap
+
+```html
+<div class="flex gap-4">gap-4 (1rem)</div>
+<div class="flex gap-x-2 gap-y-4">Different x/y gap</div>
+<div class="flex gap-0">No gap</div>
+```
+
+### Flex grow, shrink, basis
+
+```html
+<div class="flex">
+  <div class="w-14 flex-none">Fixed</div>
+  <div class="flex-1">Grows and shrinks</div>
+  <div class="flex-initial">Shrink only</div>
+  <div class="flex-auto">Grow/shrink with initial size</div>
+</div>
+```
+
+- `flex-1` = `flex: 1 1 0%` - equal distribution
+- `flex-initial` = `flex: 0 1 auto` - shrink, don't grow
+- `flex-auto` = `flex: 1 1 auto` - grow/shrink from content size
+- `flex-none` = `flex: none` - no grow or shrink
+
+### Order
+
+```html
+<div class="flex">
+  <div class="order-2">Second</div>
+  <div class="order-1">First</div>
+  <div class="order-last">Last</div>
+</div>
+```
+
+## Key Points
+
+- Use `flex` or `inline-flex` as container (see layout-display)
+- Direction: `flex-row`, `flex-col`, `flex-row-reverse`, `flex-col-reverse`
+- Justify: `justify-start`, `justify-center`, `justify-between`, `justify-evenly`
+- Align: `items-center`, `items-start`, `items-stretch`
+- Gap: `gap-{n}`, `gap-x-{n}`, `gap-y-{n}` (spacing scale)
+- Item sizing: `flex-1`, `flex-none`, `flex-auto`, `flex-initial`
+- Self alignment: `self-center`, `self-start`, etc.
+- Safe alignment (v4.1): `justify-center-safe`, `items-center-safe` (falls back to `start` on overflow)
+- Order: `order-{n}`, `order-first`, `order-last`
+- **v4 note**: `flex-shrink-*` → `shrink-*`, `flex-grow-*` → `grow-*` (old names removed)
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/flex-direction
+- https://tailwindcss.com/docs/justify-content
+- https://tailwindcss.com/docs/align-items
+- https://tailwindcss.com/docs/gap
+- https://tailwindcss.com/docs/flex
+- https://tailwindcss.com/docs/order
+-->

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

@@ -0,0 +1,87 @@
+---
+name: layout-grid
+description: CSS Grid utilities including grid-cols, grid-rows, gap, place-items, and grid placement
+---
+
+# Grid
+
+Utilities for CSS Grid layouts: columns, rows, gap, and item placement.
+
+## Usage
+
+### Grid columns and rows
+
+```html
+<div class="grid grid-cols-3 gap-4">3 equal columns</div>
+<div class="grid grid-cols-2 md:grid-cols-4 lg:grid-cols-6 gap-4">Responsive</div>
+<div class="grid grid-cols-none">No explicit tracks</div>
+
+<div class="grid grid-rows-3 gap-2">3 rows</div>
+<div class="grid grid-rows-[auto_1fr_auto]">Custom rows</div>
+```
+
+### Custom grid template
+
+```html
+<div class="grid grid-cols-[200px_minmax(900px,1fr)_100px]">Custom template</div>
+<div class="grid grid-cols-(--my-cols)">CSS variable</div>
+```
+
+### Subgrid
+
+```html
+<div class="grid grid-cols-4 gap-4">
+  <div>01</div><div>02</div><div>03</div><div>04</div>
+  <div>05</div>
+  <div class="col-span-3 grid grid-cols-subgrid gap-4">
+    <div class="col-start-2">06</div>
+  </div>
+</div>
+```
+
+### Gap
+
+```html
+<div class="grid gap-4">Uniform gap</div>
+<div class="grid gap-x-2 gap-y-4">Different x/y</div>
+```
+
+### Place items (align + justify)
+
+```html
+<div class="grid place-items-center">Center both</div>
+<div class="grid place-items-start">Start both</div>
+<div class="grid items-center justify-center">Equivalent</div>
+```
+
+### Grid placement (col/row span and start)
+
+```html
+<div class="grid grid-cols-4 gap-4">
+  <div class="col-span-2">Spans 2 columns</div>
+  <div class="col-start-3">Starts at col 3</div>
+  <div class="row-span-2">Spans 2 rows</div>
+  <div class="col-span-full">Full width</div>
+</div>
+```
+
+## Key Points
+
+- `grid` / `inline-grid` - Grid container (see layout-display)
+- Columns: `grid-cols-{n}`, `grid-cols-none`, `grid-cols-subgrid`, `grid-cols-[...]`
+- Rows: `grid-rows-{n}`, `grid-rows-[...]`
+- Gap: `gap-{n}`, `gap-x-{n}`, `gap-y-{n}`
+- Placement: `col-span-{n}`, `col-start-{n}`, `row-span-{n}`, `row-start-{n}`
+- `col-span-full` / `row-span-full` - span all
+- `place-items-*` - shorthand for align + justify
+- Use `grid-cols-[...]` for custom templates like `minmax()` or `repeat()`
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/grid-template-columns
+- https://tailwindcss.com/docs/grid-template-rows
+- https://tailwindcss.com/docs/gap
+- https://tailwindcss.com/docs/place-items
+- https://tailwindcss.com/docs/grid-column
+- https://tailwindcss.com/docs/grid-row
+-->

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

@@ -0,0 +1,97 @@
+---
+name: layout-height
+description: Setting element height with spacing scale, fractions, viewport units, and content-based sizing
+---
+
+# Height
+
+Utilities for setting the height of an element.
+
+## Usage
+
+### Spacing scale
+
+Use `h-<number>` utilities based on the spacing scale:
+
+```html
+<div class="h-24">h-24</div>
+<div class="h-48">h-48</div>
+<div class="h-64">h-64</div>
+```
+
+### Percentage heights
+
+Use `h-full` or `h-<fraction>` for percentage-based heights:
+
+```html
+<div class="h-full">100%</div>
+<div class="h-1/2">50%</div>
+<div class="h-3/4">75%</div>
+<div class="h-9/10">90%</div>
+```
+
+### Viewport units
+
+Use `h-screen` for full viewport height, or dynamic viewport units:
+
+```html
+<div class="h-screen">Full viewport height (100vh)</div>
+<div class="h-dvh">Dynamic viewport height</div>
+<div class="h-svh">Small viewport height</div>
+<div class="h-lvh">Large viewport height</div>
+```
+
+### Content-based heights
+
+Use `h-auto`, `h-fit`, `h-min`, `h-max` for content-based sizing:
+
+```html
+<div class="h-auto">Auto height</div>
+<div class="h-fit">Fit content</div>
+<div class="h-min">Min content</div>
+<div class="h-max">Max content</div>
+```
+
+### Line height
+
+Use `h-lh` to match line height:
+
+```html
+<div class="h-lh">Matches line height</div>
+```
+
+### Size utility
+
+Use `size-<number>` to set both width and height:
+
+```html
+<div class="size-16">16x16</div>
+<div class="size-24">24x24</div>
+<div class="size-full">100% x 100%</div>
+```
+
+### Custom values
+
+Use arbitrary values for custom heights:
+
+```html
+<div class="h-[117px]">Custom pixel height</div>
+<div class="h-[50vh]">Custom viewport height</div>
+<div class="h-[calc(100vh-2rem)]">Custom calculation</div>
+```
+
+## Key Points
+
+- Spacing scale: `h-0` through `h-96` (and beyond)
+- Fractions: `h-1/2`, `h-1/3`, `h-2/3`, `h-1/4`, `h-3/4`, `h-9/10`
+- Viewport units: `h-screen` (100vh), `h-dvh`, `h-svh`, `h-lvh`
+- `h-dvh` adapts to browser UI (address bar, etc.)
+- `h-svh` uses smallest viewport height
+- `h-lvh` uses largest viewport height
+- `size-*` utilities set both width and height simultaneously
+- Use `h-auto` to reset height at specific breakpoints
+
+<!--
+Source references:
+- https://tailwindcss.com/docs/height
+-->