@its-thepoe/tailwindcss 1.0.0

package/README.md

@@ -0,0 +1,25 @@
+# @its-thepoe/tailwindcss
+
+**Agent Skill** — implement Tailwind CSS reliably (v3 or v4), wire it into the build, and debug "Tailwind classes not applying" without guessing.
+
+## Install into your agents
+
+```bash
+npx @its-thepoe/skills@latest install tailwindcss
+```
+
+## What it focuses on
+
+- Detect Tailwind major version first (v3 vs v4).
+- Ensure CSS entry is correct and imported.
+- Ensure content scanning/build plugin is correct for the version.
+- Add dark mode + tokens without breaking accessibility.
+
+## Contents
+
+- `SKILL.md` — required workflow + minimal correct setups
+- `reference.md` — deeper checklist and migration notes
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: tailwindcss
+description: >-
+  Implement Tailwind CSS in an app without guessing version, config, or build
+  wiring. Use when adding Tailwind, fixing "classes not applying", setting up
+  dark mode, tokens/themes, setting up Tailwind v3 or v4, or migrating a
+  project from Tailwind v3 to v4.
+argument-hint: "[project-or-component]"
+---
+
+# Tailwind CSS
+
+Use this skill when implementing Tailwind CSS (v3 or v4) or debugging why Tailwind utilities are not applying.
+
+## Non-negotiable first step: detect Tailwind major version
+
+1. Read `package.json`.
+2. Determine Tailwind major version from the installed dependency:
+   - Tailwind v4 rules are not the same as v3.
+3. Apply the matching setup below.
+
+If Tailwind is not installed yet, decide up front:
+
+- New project that can follow modern guidance: prefer **Tailwind v4**.
+- Existing project already on Tailwind v3: stay on v3 unless explicitly migrating.
+- If the user asks for v3 specifically: install v3.
+
+## Quick diagnosis (when styles are not applying)
+
+Before changing anything:
+
+1. Confirm Tailwind is installed (and the version).
+2. Find the CSS entry file that should include Tailwind.
+3. Confirm that CSS entry is imported by the app entrypoint.
+4. Confirm content scanning includes your source files (v3 config) or you are using v4 correctly.
+5. Add a visible test element and verify it renders with Tailwind classes.
+
+Example test:
+
+```html
+<div class="m-4 rounded-md bg-blue-600 px-3 py-2 text-white">Tailwind OK</div>
+```
+
+## Setup selection (pick one)
+
+- Tailwind v4 + Vite plugin (`@tailwindcss/vite`) is the clean default for Vite apps.
+- Tailwind v3 often uses PostCSS (`tailwindcss` + `autoprefixer`) and a `tailwind.config.*` file with `content` globs.
+
+## Tailwind v4 setup rules
+
+- CSS entry must include:
+
+```css
+@import "tailwindcss";
+```
+
+- Do not use `@tailwind base/components/utilities` (those are v3 only).
+- PostCSS plugin is `@tailwindcss/postcss` when using PostCSS.
+
+### Vite (v4)
+
+Install:
+
+```bash
+npm install -D tailwindcss @tailwindcss/vite
+```
+
+Vite config:
+
+```ts
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [tailwindcss()],
+});
+```
+
+CSS entry:
+
+```css
+@import "tailwindcss";
+```
+
+## Tailwind v3 setup rules
+
+- CSS entry must include:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+- `tailwind.config.js` (or `.ts`) must exist and include correct `content` globs.
+- PostCSS uses `tailwindcss` + `autoprefixer`.
+
+Install (v3):
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+`tailwind.config.js` example:
+
+```js
+module.exports = {
+  content: ["./src/**/*.{js,jsx,ts,tsx}", "./index.html"],
+  theme: { extend: {} },
+  plugins: [],
+};
+```
+
+## Migrate v3 -> v4 (safe workflow)
+
+Do not “half migrate”. Pick one commit where Tailwind is definitely v4 and definitely wired correctly.
+
+1. Confirm current v3 setup works (baseline).
+2. Upgrade deps to v4 (and whichever integration you are using).
+3. Replace CSS entry directives:
+
+From v3:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+To v4:
+
+```css
+@import "tailwindcss";
+```
+
+4. Update the build integration:
+   - For Vite: add `@tailwindcss/vite` plugin (recommended path for v4 + Vite).
+   - For PostCSS: switch to `@tailwindcss/postcss` (only if the project uses PostCSS).
+5. Validate `content`/scanning assumptions:
+   - If you are still relying on v3-style `tailwind.config.*` `content` globs, keep them correct during the migration.
+6. Add a visible test element and confirm Tailwind applies again.
+7. Run typecheck/build/tests and fix class-name changes or plugin differences as needed.
+
+If the user says “migrate v4 -> v3”, treat it as a downgrade: do the inverse steps and expect more friction.
+
+## Dark mode
+
+Decide which mode the project wants:
+
+- `media` (system-driven): use `dark:` classes, no toggle required.
+- `class` (manual toggle): add/remove `dark` class on `document.documentElement`.
+
+When adding a toggle, persist preference in `localStorage`, and respect system preference on first load.
+
+## Tokens and theming
+
+Prefer built-in tokens over arbitrary values. Use opacity suffixes like `bg-black/10` instead of custom alpha literals.
+
+If v4: prefer `@theme` in CSS for tokens.
+
+If v3: prefer `theme.extend` in `tailwind.config.*` or CSS variables referenced by utilities.
+
+## Common gotchas (don’t let the agent hallucinate)
+
+- If Tailwind is installed but nothing works, it is almost always:
+  - The CSS entry file is not imported.
+  - The content scan does not include the files where classes are used (v3).
+  - You used v3 directives in v4 or v4 import in v3.
+  - You used dynamic class strings that Tailwind can’t statically detect.
+
+Bad (won’t be detected reliably):
+
+```tsx
+<div className={`text-${color}-500`} />
+```
+
+Good (explicit options):
+
+```tsx
+<div className={color === "blue" ? "text-blue-500" : "text-red-500"} />
+```
+
+## Accessibility defaults
+
+- Always include visible focus styles (`focus-visible:` ring/outline).
+- Do not remove focus outlines unless you replace them with a better visible treatment.
+- Ensure color contrast in dark mode, not just light mode.
+
+## References
+
+- Tailwind v3 installation: https://v3.tailwindcss.com/docs/installation
+- Tailwind v4 + Vite installation: https://tailwindcss.com/docs/installation/using-vite

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@its-thepoe/tailwindcss",
+  "version": "1.0.0",
+  "description": "Agent Skill: implement Tailwind CSS (v3/v4), debug setup issues, and apply consistent utility-first patterns.",
+  "license": "MIT",
+  "keywords": [
+    "agent-skills",
+    "tailwindcss",
+    "tailwind",
+    "css",
+    "frontend",
+    "design-system"
+  ],
+  "files": ["README.md", "SKILL.md", "reference.md", "package.json"],
+  "exports": {
+    ".": "./SKILL.md",
+    "./SKILL.md": "./SKILL.md",
+    "./reference": "./reference.md",
+    "./reference.md": "./reference.md"
+  }
+}

package/reference.md

@@ -0,0 +1,59 @@
+# Tailwind CSS Reference
+
+Use this when setup is non-standard or the project is mid-migration.
+
+## Preflight checklist
+
+- Identify framework (Next.js, Vite, Remix, Astro, CRA, etc.).
+- Identify Tailwind major version (v3 vs v4).
+- Identify CSS entry file and confirm it is imported.
+- Identify build pipeline (Vite plugin vs PostCSS).
+- Confirm content scanning covers files that contain class strings.
+
+## Setup recipes (minimal)
+
+### V4 + Vite
+
+- Install: `tailwindcss` + `@tailwindcss/vite`
+- Vite plugin enabled in `vite.config.*`
+- CSS entry uses `@import "tailwindcss";`
+
+### V3 + PostCSS
+
+- Install: `tailwindcss` + `postcss` + `autoprefixer`
+- `postcss.config.*` includes `tailwindcss` and `autoprefixer`
+- `tailwind.config.*` exists with correct `content` globs
+- CSS entry uses `@tailwind base/components/utilities`
+
+## Migration notes (v3 -> v4)
+
+- Replace v3 directives with `@import "tailwindcss";`.
+- Replace PostCSS plugin config (`tailwindcss`) with `@tailwindcss/postcss` only if using PostCSS.
+- Delete/adjust obsolete `tailwind.config.*` patterns when the project adopts v4 conventions.
+
+## Migration checklist (v3 -> v4)
+
+1. Snapshot the v3 baseline:
+   - Identify current CSS entry file and verify classes apply.
+   - Note current `tailwind.config.*`, PostCSS config, and integration points.
+2. Upgrade dependencies (Tailwind v4 + integration).
+3. Update CSS entry to v4 import.
+4. Update build integration (Vite plugin or PostCSS plugin).
+5. Keep `content` scanning accurate during migration (avoid “classes missing” false alarms).
+6. Add a visible Tailwind test element and verify on a real page.
+7. Fix plugin differences and any deprecated class usage surfaced by lint/build.
+8. Re-run build/tests and confirm production build is correct.
+
+## Troubleshooting checklist
+
+- Is the CSS file with Tailwind imported?
+- Are class names present as string literals in the built source?
+- Does the framework use a non-standard source folder that content scanning missed (v3)?
+- Are you using `class` vs `className` correctly for the framework?
+- Are you fighting CSS specificity from an existing component library?
+
+## Recommended UX defaults
+
+- Buttons: `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2`
+- Inputs: same focus-visible ring + clear invalid states
+- Layout: mobile-first `sm:` `md:` `lg:` with small deltas