Initial commit

skills/migrating-from-v3/references/breaking-changes.md

@@ -0,0 +1,516 @@
+# Complete Breaking Changes List
+
+## Configuration System
+
+### JavaScript → CSS Configuration
+
+**Breaking:** No more `tailwind.config.js` file.
+
+**v3:**
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: { brand: '#3b82f6' },
+    },
+  },
+};
+```
+
+**v4:**
+
+```css
+@theme {
+  --color-brand: oklch(0.65 0.25 270);
+}
+```
+
+**Impact:** All theme customization moves to CSS.
+
+### Content Detection
+
+**Breaking:** No manual content array needed.
+
+**v3:**
+
+```javascript
+content: ['./src/**/*.{html,js}']
+```
+
+**v4:**
+
+Automatic detection. Manual control via `@source` if needed.
+
+**Impact:** Simplified setup, but less explicit control.
+
+## Import Directives
+
+### @tailwind → @import
+
+**Breaking:** Different import syntax.
+
+**v3:**
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**v4:**
+
+```css
+@import 'tailwindcss';
+```
+
+**Impact:** All templates need updating.
+
+## Utility Class Changes
+
+### Opacity Modifiers Removed
+
+**Breaking:** Separate opacity utilities removed.
+
+**v3:**
+
+```html
+<div class="bg-black bg-opacity-50"></div>
+<div class="text-gray-900 text-opacity-75"></div>
+<div class="border-blue-500 border-opacity-60"></div>
+<div class="ring-blue-500 ring-opacity-30"></div>
+```
+
+**v4:**
+
+```html
+<div class="bg-black/50"></div>
+<div class="text-gray-900/75"></div>
+<div class="border-blue-500/60"></div>
+<div class="ring-blue-500/30"></div>
+```
+
+**Impact:** Search and replace needed across entire codebase.
+
+**Automated fix:**
+
+```bash
+find . -name "*.html" -o -name "*.jsx" -o -name "*.tsx" | xargs sed -i '' 's/bg-\([a-z-]*\) bg-opacity-\([0-9]*\)/bg-\1\/\2/g'
+```
+
+### Flex Utility Renames
+
+**Breaking:** Utility names changed.
+
+**v3:**
+
+```html
+<div class="flex-shrink-0"></div>
+<div class="flex-shrink"></div>
+<div class="flex-grow-0"></div>
+<div class="flex-grow"></div>
+```
+
+**v4:**
+
+```html
+<div class="shrink-0"></div>
+<div class="shrink"></div>
+<div class="grow-0"></div>
+<div class="grow"></div>
+```
+
+**Impact:** All flex utilities need renaming.
+
+### Shadow Utility Rename
+
+**Breaking:** Smallest shadow renamed.
+
+**v3:**
+
+```html
+<div class="shadow-sm"></div>
+```
+
+**v4:**
+
+```html
+<div class="shadow-xs"></div>
+```
+
+**Impact:** Update all uses of `shadow-sm`.
+
+### Ring Default Width
+
+**Breaking:** Default ring width changed.
+
+**v3:**
+
+```html
+<input class="ring" />
+```
+
+Ring width: 3px
+
+**v4:**
+
+```html
+<input class="ring" />
+```
+
+Ring width: 1px
+
+**Fix for v3 behavior:**
+
+```html
+<input class="ring-3" />
+```
+
+**Impact:** All bare `ring` utilities render thinner.
+
+## Color System
+
+### Default Border Color
+
+**Breaking:** Border color changed from gray to currentColor.
+
+**v3:**
+
+```html
+<div class="border"></div>
+```
+
+Border color: gray-200
+
+**v4:**
+
+```html
+<div class="border"></div>
+```
+
+Border color: currentColor (inherits text color)
+
+**Fix for v3 behavior:**
+
+```html
+<div class="border border-gray-200"></div>
+```
+
+**Impact:** Borders may appear different colors.
+
+### Default Ring Color
+
+**Breaking:** Ring color changed from blue to currentColor.
+
+**v3:**
+
+```html
+<input class="ring" />
+```
+
+Ring color: blue-500
+
+**v4:**
+
+```html
+<input class="ring" />
+```
+
+Ring color: currentColor
+
+**Fix for v3 behavior:**
+
+```html
+<input class="ring ring-blue-500" />
+```
+
+**Impact:** Rings inherit text color.
+
+### OkLCh Color Space
+
+**Breaking:** Color values use OkLCh instead of RGB.
+
+**v3:**
+
+```javascript
+colors: {
+  brand: '#3b82f6',
+}
+```
+
+**v4:**
+
+```css
+@theme {
+  --color-brand: oklch(0.65 0.25 270);
+}
+```
+
+**Impact:** Custom colors need conversion. Colors may look slightly different (more vivid on modern displays).
+
+## PostCSS Changes
+
+### Plugin Name
+
+**Breaking:** Different PostCSS plugin.
+
+**v3:**
+
+```javascript
+plugins: {
+  'tailwindcss': {},
+  'autoprefixer': {},
+}
+```
+
+**v4:**
+
+```javascript
+plugins: {
+  '@tailwindcss/postcss': {},
+}
+```
+
+**Impact:** PostCSS config needs updating. Remove `autoprefixer` and `postcss-import` (no longer needed).
+
+## Preflight Changes
+
+### Placeholder Color
+
+**Breaking:** Placeholder text color changed.
+
+**v3:**
+
+```css
+::placeholder {
+  color: theme('colors.gray.400');
+}
+```
+
+**v4:**
+
+```css
+::placeholder {
+  color: currentColor;
+  opacity: 0.5;
+}
+```
+
+**Impact:** Placeholders inherit text color at 50% opacity.
+
+**Fix for v3 behavior:**
+
+```css
+@layer base {
+  ::placeholder {
+    color: theme('colors.gray.400');
+    opacity: 1;
+  }
+}
+```
+
+### Button Cursor
+
+**Breaking:** Button cursor changed.
+
+**v3:**
+
+```css
+button {
+  cursor: pointer;
+}
+```
+
+**v4:**
+
+```css
+button {
+  cursor: default;
+}
+```
+
+**Impact:** Buttons no longer show pointer cursor by default.
+
+**Fix for v3 behavior:**
+
+```css
+@layer base {
+  button {
+    cursor: pointer;
+  }
+}
+```
+
+Or add explicit classes:
+
+```html
+<button class="cursor-pointer">Click me</button>
+```
+
+## Arbitrary Values
+
+### Space Handling
+
+**Breaking:** Spaces in arbitrary values use underscores.
+
+**v3:**
+
+```html
+<div class="grid-cols-[1fr,500px,2fr]"></div>
+```
+
+**v4:**
+
+```html
+<div class="grid-cols-[1fr_500px_2fr]"></div>
+```
+
+**Impact:** All arbitrary values with commas need updating.
+
+## Browser Support
+
+### Minimum Versions
+
+**Breaking:** Dropped support for older browsers.
+
+**v3:**
+
+- IE 11+
+- Safari 10+
+- Chrome 60+
+
+**v4:**
+
+- Safari 16.4+
+- Chrome 111+
+- Firefox 128+
+
+**Impact:** Projects requiring older browser support cannot upgrade.
+
+## CSS Preprocessors
+
+### No Sass/Less/Stylus Support
+
+**Breaking:** Incompatible with CSS preprocessors.
+
+**v3:**
+
+Can use with Sass, Less, Stylus
+
+**v4:**
+
+Cannot use CSS preprocessors (Tailwind functions as preprocessing layer)
+
+**Impact:** Remove CSS preprocessors from build pipeline.
+
+## Plugin System
+
+### Plugin API Changes
+
+**Breaking:** Plugin API completely rewritten.
+
+**v3 plugin:**
+
+```javascript
+const plugin = require('tailwindcss/plugin');
+
+module.exports = plugin(function ({ addUtilities, theme }) {
+  addUtilities({
+    '.content-auto': {
+      'content-visibility': 'auto',
+    },
+  });
+});
+```
+
+**v4 equivalent:**
+
+```css
+@utility content-auto {
+  content-visibility: auto;
+}
+```
+
+**Impact:** All custom plugins need manual rewrite.
+
+## @apply Restrictions
+
+### Limited @apply Support
+
+**Breaking:** @apply only works for small subset of utilities.
+
+**v3:**
+
+```css
+.btn {
+  @apply px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700;
+}
+```
+
+**v4:**
+
+@apply has limited support. Use @utility instead:
+
+```css
+@utility btn {
+  padding: var(--spacing-2) var(--spacing-4);
+  background: var(--color-blue-600);
+  color: var(--color-white);
+  border-radius: var(--radius-md);
+}
+```
+
+**Impact:** Many @apply patterns need refactoring.
+
+## Mobile Hover Behavior
+
+### Hover on Touch Devices
+
+**Breaking:** Hover styles don't apply on touch devices.
+
+**v3:**
+
+Hover styles triggered on tap
+
+**v4:**
+
+Hover styles only on devices supporting hover
+
+**Impact:** Touch devices won't show hover states (improves UX).
+
+## Container Plugin
+
+### Built-in Container Queries
+
+**Breaking:** Container queries plugin no longer needed.
+
+**v3:**
+
+```javascript
+plugins: [require('@tailwindcss/container-queries')]
+```
+
+**v4:**
+
+Built-in. No plugin needed.
+
+**Impact:** Remove plugin dependency. Syntax remains same.
+
+## Summary Table
+
+| Change | v3 | v4 | Impact |
+|--------|----|----|--------|
+| Config | tailwind.config.js | @theme | High |
+| Import | @tailwind | @import | High |
+| Opacity | bg-opacity-50 | bg-{color}/50 | High |
+| Flex | flex-shrink | shrink | Medium |
+| Shadow | shadow-sm | shadow-xs | Low |
+| Ring width | 3px | 1px | Medium |
+| Border color | gray-200 | currentColor | Medium |
+| Color space | RGB | OkLCh | Medium |
+| PostCSS | tailwindcss | @tailwindcss/postcss | High |
+| Placeholder | gray-400 | currentColor/50 | Low |
+| Button cursor | pointer | default | Low |
+| Browsers | IE 11+ | Safari 16.4+ | High |
+| Preprocessors | Supported | Not supported | High |
+| Plugins | JS API | CSS @utility | High |

skills/migrating-from-v3/references/migration-checklist.md

@@ -0,0 +1,469 @@
+# Step-by-Step Migration Checklist
+
+## Pre-Migration
+
+- [ ] Create new git branch: `git checkout -b upgrade-tailwind-v4`
+- [ ] Commit all current changes
+- [ ] Document current Tailwind version
+- [ ] Backup tailwind.config.js
+- [ ] Review custom plugins in use
+- [ ] Check browser support requirements
+- [ ] Note any CSS preprocessor usage
+
+## Phase 1: Dependencies
+
+### Update Package Dependencies
+
+- [ ] Update Tailwind CSS to v4
+
+```bash
+npm install tailwindcss@next
+```
+
+- [ ] Install appropriate build tool plugin
+
+**For Vite:**
+
+```bash
+npm install @tailwindcss/vite
+```
+
+**For PostCSS:**
+
+```bash
+npm install @tailwindcss/postcss
+```
+
+**For CLI:**
+
+```bash
+npm install @tailwindcss/cli
+```
+
+- [ ] Remove deprecated dependencies
+
+```bash
+npm uninstall autoprefixer postcss-import @tailwindcss/container-queries
+```
+
+- [ ] Update package.json
+
+```json
+{
+  "dependencies": {
+    "tailwindcss": "^4.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0"
+  }
+}
+```
+
+## Phase 2: Build Configuration
+
+### Vite Configuration
+
+- [ ] Update vite.config.js
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+- [ ] Remove PostCSS config if using Vite plugin
+- [ ] Test build: `npm run build`
+
+### PostCSS Configuration
+
+- [ ] Update postcss.config.js
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+- [ ] Remove autoprefixer and postcss-import
+- [ ] Test build: `npm run build`
+
+### Next.js Configuration
+
+- [ ] Ensure postcss.config.js exists
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+- [ ] Test: `npm run dev`
+
+## Phase 3: CSS Configuration
+
+### Migrate tailwind.config.js to @theme
+
+- [ ] Open tailwind.config.js
+- [ ] Open main CSS file (e.g., src/index.css)
+- [ ] Replace @tailwind directives
+
+**Old:**
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**New:**
+
+```css
+@import 'tailwindcss';
+```
+
+- [ ] Convert theme.extend to @theme
+
+**Example conversion:**
+
+**tailwind.config.js:**
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: '#3b82f6',
+        accent: '#a855f7',
+      },
+      fontFamily: {
+        sans: ['Inter', 'sans-serif'],
+      },
+      spacing: {
+        18: '4.5rem',
+      },
+    },
+  },
+};
+```
+
+**CSS:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --font-sans: 'Inter', sans-serif;
+  --color-brand: oklch(0.65 0.25 270);
+  --color-accent: oklch(0.65 0.25 320);
+  --spacing-18: 4.5rem;
+}
+```
+
+- [ ] Convert hex colors to oklch() using https://oklch.com/
+- [ ] Test: colors render correctly
+
+### Content Detection
+
+- [ ] Remove content array (automatic detection)
+- [ ] Add @source directives if needed
+
+```css
+@source "../packages/ui";
+@source not "./legacy";
+```
+
+- [ ] Verify all template files are detected
+- [ ] Check .gitignore excludes node_modules
+
+### Custom CSS
+
+- [ ] Migrate @layer components to CSS
+
+```css
+@layer components {
+  .btn {
+    padding: var(--spacing-2) var(--spacing-4);
+    background: var(--color-blue-600);
+    border-radius: var(--radius-md);
+  }
+}
+```
+
+- [ ] Convert @layer utilities to @utility
+
+**Old:**
+
+```css
+@layer utilities {
+  .content-auto {
+    content-visibility: auto;
+  }
+}
+```
+
+**New:**
+
+```css
+@utility content-auto {
+  content-visibility: auto;
+}
+```
+
+## Phase 4: Utility Class Updates
+
+### Opacity Modifiers
+
+- [ ] Search for opacity utilities
+
+```bash
+grep -r "bg-opacity-" src/
+grep -r "text-opacity-" src/
+grep -r "border-opacity-" src/
+grep -r "ring-opacity-" src/
+```
+
+- [ ] Replace with slash syntax
+
+**Find and replace:**
+
+- `bg-{color} bg-opacity-{value}` → `bg-{color}/{value}`
+- `text-{color} text-opacity-{value}` → `text-{color}/{value}`
+- `border-{color} border-opacity-{value}` → `border-{color}/{value}`
+
+**Example:**
+
+```html
+<div class="bg-black bg-opacity-50"></div>
+→
+<div class="bg-black/50"></div>
+```
+
+- [ ] Test: opacity values render correctly
+
+### Flex Utilities
+
+- [ ] Search for flex utilities
+
+```bash
+grep -r "flex-shrink" src/
+grep -r "flex-grow" src/
+```
+
+- [ ] Replace with new names
+
+**Find and replace:**
+
+- `flex-shrink-0` → `shrink-0`
+- `flex-shrink` → `shrink`
+- `flex-grow-0` → `grow-0`
+- `flex-grow` → `grow`
+
+### Shadow Utilities
+
+- [ ] Search for shadow-sm
+
+```bash
+grep -r "shadow-sm" src/
+```
+
+- [ ] Replace with shadow-xs
+
+```
+shadow-sm → shadow-xs
+```
+
+### Ring Utilities
+
+- [ ] Search for bare `ring` class
+
+```bash
+grep -r 'class="[^"]*ring[^-"]' src/
+```
+
+- [ ] Add explicit width if expecting 3px default
+
+```html
+<input class="ring" />
+→
+<input class="ring-3" />
+```
+
+### Border Utilities
+
+- [ ] Search for bare `border` class
+
+```bash
+grep -r 'class="[^"]*border[^-"]' src/
+```
+
+- [ ] Add explicit color if expecting gray
+
+```html
+<div class="border"></div>
+→
+<div class="border border-gray-200"></div>
+```
+
+## Phase 5: Arbitrary Values
+
+### Space Handling
+
+- [ ] Search for arbitrary values with commas
+
+```bash
+grep -r "grid-cols-\[.*,.*\]" src/
+```
+
+- [ ] Replace commas with underscores
+
+```html
+<div class="grid-cols-[1fr,500px,2fr]"></div>
+→
+<div class="grid-cols-[1fr_500px_2fr]"></div>
+```
+
+## Phase 6: Testing
+
+### Build Tests
+
+- [ ] Run development build: `npm run dev`
+- [ ] Check console for errors
+- [ ] Verify styles load
+- [ ] Run production build: `npm run build`
+- [ ] Check build output
+- [ ] Test production bundle
+
+### Visual Testing
+
+- [ ] Test home page
+- [ ] Test all major pages
+- [ ] Check responsive breakpoints
+- [ ] Verify dark mode (if used)
+- [ ] Test hover states
+- [ ] Test focus states
+- [ ] Check form inputs
+- [ ] Verify buttons
+- [ ] Check modals/overlays
+- [ ] Test animations
+
+### Component Testing
+
+- [ ] Test each component in isolation
+- [ ] Verify colors match
+- [ ] Check spacing
+- [ ] Test typography
+- [ ] Verify shadows and borders
+- [ ] Check opacity values
+
+### Browser Testing
+
+- [ ] Safari 16.4+
+- [ ] Chrome 111+
+- [ ] Firefox 128+
+- [ ] Mobile Safari
+- [ ] Mobile Chrome
+
+## Phase 7: Cleanup
+
+### Remove Old Files
+
+- [ ] Delete tailwind.config.js
+- [ ] Remove old PostCSS config (if using Vite plugin)
+- [ ] Clean node_modules
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Update Documentation
+
+- [ ] Update README.md
+- [ ] Document new setup process
+- [ ] Update contribution guide
+- [ ] Note new browser requirements
+
+### Code Review
+
+- [ ] Review all changed files
+- [ ] Check for missed migrations
+- [ ] Verify no broken styles
+- [ ] Run linter: `npm run lint`
+- [ ] Run tests: `npm test`
+
+## Phase 8: Deploy
+
+### Pre-Deploy Checks
+
+- [ ] All tests passing
+- [ ] No console errors
+- [ ] Production build successful
+- [ ] Visual regression tests pass
+- [ ] Performance metrics acceptable
+
+### Deploy
+
+- [ ] Merge PR to main
+- [ ] Deploy to staging
+- [ ] Test staging environment
+- [ ] Deploy to production
+- [ ] Monitor for issues
+
+### Post-Deploy
+
+- [ ] Verify production site
+- [ ] Check analytics for errors
+- [ ] Monitor performance
+- [ ] Gather feedback
+
+## Common Issues Checklist
+
+- [ ] Styles not applying → Check @import syntax
+- [ ] Build errors → Verify PostCSS/Vite config
+- [ ] Colors different → Convert hex to oklch
+- [ ] Borders wrong color → Add explicit border color
+- [ ] Placeholders wrong → Check preflight changes
+- [ ] Buttons wrong cursor → Add cursor-pointer
+- [ ] Missing utilities → Check for typos
+- [ ] Dark mode broken → Verify class strategy
+
+## Rollback Plan
+
+If migration fails:
+
+- [ ] Revert git branch: `git checkout main`
+- [ ] Delete branch: `git branch -D upgrade-tailwind-v4`
+- [ ] Reinstall dependencies: `npm install`
+- [ ] Document issues encountered
+- [ ] Plan remediation
+
+## Success Criteria
+
+- [ ] All pages render correctly
+- [ ] No console errors
+- [ ] Production build successful
+- [ ] All tests passing
+- [ ] Performance maintained or improved
+- [ ] No visual regressions
+- [ ] Browser support verified
+- [ ] Documentation updated
+
+## Estimated Timeline
+
+- Pre-migration: 1 hour
+- Dependencies & build config: 1-2 hours
+- CSS migration: 2-4 hours
+- Utility updates: 4-8 hours
+- Testing: 4-8 hours
+- Cleanup & documentation: 1-2 hours
+- Deploy: 1-2 hours
+
+**Total: 14-27 hours** depending on project size