diff --git a/.claude/skills/README.md b/.claude/skills/README.md index a2da7a40..f8a0e4f8 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -10,14 +10,16 @@ Specialized knowledge for AI agents working on Video.js 10. | Building HTML components | `component` + `aria` | | Building React components | `component` + `aria` | | Writing documentation | `docs` | -| Writing component reference| `api-reference` | -| Writing Design Docs / RFCs | `design` or `rfc` | -| Reviewing API/architecture | `api` → `review/workflow.md` | +| Writing component reference| `api-reference` | +| Writing Design Docs / RFCs | `design` or `rfc` | +| Reviewing API/architecture | `api` → `review/workflow.md` | | Reviewing documentation | `docs` → `review/workflow.md` | | Reviewing components | `component` → `review/workflow.md` | | Reviewing accessibility | `aria` → `review/workflow.md` | | Accessibility audit | `aria` | | Committing / creating PRs | `git` or `/commit-pr` | +| CSS → Tailwind migration | `css-to-tailwind` | +| Reviewing Tailwind migration | `css-to-tailwind` → `review/workflow.md` | | Reviewing branch changes | `/review-branch` | | Analyzing GitHub issues | `/gh-issue` | | Creating GitHub issues | `/create-issue` | @@ -33,6 +35,7 @@ Specialized knowledge for AI agents working on Video.js 10. | [claude-update](claude-update/SKILL.md) | Update CLAUDE.md and skills when introducing new patterns | No | | [commit-pr](commit-pr/SKILL.md) | Commit changes and create/update PRs with conventions | No | | [component](component/SKILL.md) | Build headless UI components — compound patterns, state, styling | Yes | +| [css-to-tailwind](css-to-tailwind/SKILL.md) | Migrate CSS/SCSS/styled-components to Tailwind v4 — `@theme`, tokens, parity, reporting | Yes | | [create-issue](create-issue/SKILL.md) | Create GitHub issues with consistent formatting and conventions | No | | [create-skill](create-skill/SKILL.md) | Create new skills with proper structure and conventions | No | | [design](design/SKILL.md) | Write Design Docs — decisions you own, component specs, feature designs| No | @@ -60,9 +63,10 @@ skill/ | Skill | Review Focus | | ------------------- | ------------------------------------------------- | | `api/review/` | API design, architecture, DX, type safety | -| `docs/review/` | Documentation quality — tone, structure, examples | +| `docs/review/` | Documentation quality — tone, structure, examples | | `component/review/` | Component architecture, state, props, styling | | `aria/review/` | Accessibility — ARIA, keyboard, focus, WCAG | +| `css-to-tailwind/review/` | Tailwind migration — utilities, arbitrary values, theme gaps | ## Skill Structure @@ -101,7 +105,7 @@ skill-name/ When code changes introduce new patterns that a skill should cover: -1. Identify affected skill (component, aria, api, docs) +1. Identify affected skill (component, aria, api, docs, css-to-tailwind) 2. Update the relevant reference file or add a new one 3. If pattern is cross-cutting, update CLAUDE.md Code Rules instead @@ -111,5 +115,6 @@ When code changes introduce new patterns that a skill should cover: - New accessibility patterns (ARIA, keyboard, focus) - New API design decisions (extensibility, type safety) - New DX considerations (inference, defaults, naming) +- New Tailwind or skin parity patterns (`packages/skins`) For detailed guidance and consistency checklists, run `/claude-update`. diff --git a/.claude/skills/claude-update/SKILL.md b/.claude/skills/claude-update/SKILL.md index a0fb33d2..3e9e8d97 100644 --- a/.claude/skills/claude-update/SKILL.md +++ b/.claude/skills/claude-update/SKILL.md @@ -27,7 +27,8 @@ update AI documentation to incorporate them as appropriate. | Component patterns | `component` skill | | Accessibility | `aria` skill | | API design / DX | `api` skill | -| Documentation | `docs` skill | +| Documentation | `docs` skill | +| CSS → Tailwind migration | `css-to-tailwind` skill | **Decision:** Ask "Who needs this?" — if domain-specific, use a skill. diff --git a/.claude/skills/css-to-tailwind/SKILL.md b/.claude/skills/css-to-tailwind/SKILL.md new file mode 100644 index 00000000..4fe06190 --- /dev/null +++ b/.claude/skills/css-to-tailwind/SKILL.md @@ -0,0 +1,47 @@ +--- +name: css-to-tailwind +description: >- + Migrate vanilla CSS, CSS modules, SCSS, or styled-component styles to Tailwind + v4 utilities. Prefer @theme-backed tokens and semantic utilities; document + arbitrary values and parity gaps. For audits, load review/workflow.md. + Triggers: "CSS to Tailwind", "migrate to Tailwind", "tailwind migration", + "styled-components to Tailwind", "SCSS to Tailwind", "review Tailwind classes", + "tailwind parity". +--- + +# CSS to Tailwind + +Guidance for converting legacy CSS to Tailwind **v4** class strings while preserving behavior and readability. + +## Tailwind v4 in this workspace + +Theme and shared animation tokens are declared in CSS (**`@theme`**, keyed custom properties consumed by utilities). Apps use **`@import "tailwindcss"`**; **`packages/skins`** layers shared **`@keyframes` / `@property` / `@theme`** in **`shared/tailwind.css`**. When a pattern repeats across components, prefer **`@utility`** or **`@custom-variant`** in CSS (see **`site`** / **`apps/sandbox`** styles) rather than proliferating arbitrary values in TS presets. + +See [references/migration.md](references/migration.md) for v4-focused rules. + +## When to use + +- Migrating stylesheet-based styles to Tailwind utilities +- Ensuring **`packages/skins`** CSS and **`tailwind`** component modules stay visually and behaviorally aligned (parallel `css/` and `tailwind/` trees) +- Auditing Tailwind output for unnecessary arbitrary values or missing theme mappings + +## Reference + +| File | Contents | +| -------------------------------------------------------- | --------------------------------------- | +| [references/migration.md](references/migration.md) | Rules, priorities, migration report shape | + +## Review + +For checking a migration against these rules, load `review/workflow.md`. + +| File | Contents | +| ---------------------------------------------------------- | ------------------------------- | +| [review/workflow.md](review/workflow.md) | Review process | +| [review/checklist.md](review/checklist.md) | Quick single-pass checklist | + +## Related skills + +| Need | Use | +| ------------------------- | ---------------- | +| Headless UI + skin hooks | `component` skill | diff --git a/.claude/skills/css-to-tailwind/references/migration.md b/.claude/skills/css-to-tailwind/references/migration.md new file mode 100644 index 00000000..e5ee5a88 --- /dev/null +++ b/.claude/skills/css-to-tailwind/references/migration.md @@ -0,0 +1,102 @@ +# CSS to Tailwind Migration + +Use this guidance when migrating vanilla CSS, CSS modules, SCSS, or styled-components to Tailwind class names. + +Video.js 10 targets **Tailwind CSS v4** (CSS-first config: **`@import "tailwindcss"`**, **`@theme`**, **`@utility`**, **`@custom-variant`**). Skin packages extend shared theme and keyframes via **`packages/skins/src/shared/tailwind.css`**. + +## Goal + +Convert CSS declarations to readable Tailwind utilities while preserving behavior. Prefer **theme tokens exposed through `@theme`** (and the utilities they generate) plus semantic wrappers over arbitrary values. + +In this repo, skin work often means keeping **`packages/skins/*/css/`** and the matching **`packages/skins/*/tailwind/`** definitions in parity when both exist. + +## Tailwind v4 specifics + +| Concern | Prefer | +| ------- | ------ | +| New design tokens | Add to **`@theme { }`** (skin shared sheet or app entry CSS) so utilities like `rounded-*`, `gap-*`, and custom namespaces stay consistent | +| One-off escapes | Arbitrary utilities that reuse **`theme()`**, e.g. **`bg-[theme(--surface)]`**, whenever the backing variable already exists in **`@theme`** | +| Repeated arbitrary variants / long class strings | **`@utility`** blocks in CSS | +| Repeated selector shapes | **`@custom-variant`** (see **`site`** / **`apps/sandbox`** for examples) | +| Keyframes tied to animations | Registered in CSS (`@keyframes`) and wired through **`@theme`** (see comments in skins `input-feedback` tailwind components) | + +Legacy **`tailwind.config.js`** theme spreads are not the primary path here—extend the **CSS** theme surface when adding tokens. + +## Rules + +### 1. Prefer built-in Tailwind utilities + +- `display: flex` → `flex` +- `align-items: center` → `items-center` +- `gap: 1rem` → `gap-4` + +### 2. Prefer `@theme` / built-in scale before arbitrary values + +- `color: var(--color-text-muted)` → use an existing utility or add a token under **`@theme`** and use the generated class +- `border-radius: 8px` → prefer `rounded-lg` (or a theme radius key) if equivalent/acceptable +- `font-size`, `spacing`, `colors`, `shadow`, `z-index`, `radius` should map to **`@theme` or default v4 scales** when acceptable + +### 3. When arbitrary values are allowed + +Only when: + +- The value is truly one-off, +- No existing token matches closely, +- The value is required for pixel-perfect migration, **or** +- The CSS property has no Tailwind utility + +### 4. Avoid arbitrary values for common scale values + +Bad: + +- `mt-[16px]` +- `gap-[1rem]` +- `rounded-[8px]` +- `text-[14px]` + +Good: + +- `mt-4` +- `gap-4` +- `rounded-lg` +- `text-sm` + +### 5. Prefer theme-backed utilities (not raw `var()` in class strings) + +Avoid lots of: + +- `text-[var(--color-text)]` +- `bg-[var(--color-surface)]` + +Prefer: + +- Semantic utilities that map to **`@theme`** variables (`text-fg`, `bg-surface`, `border-border`, etc.) +- Or **`bg-[theme(--surface)]`**-style arbitrary values only until a dedicated utility exists (replace with **`@utility`** once repeated) + +(Adapt names to the project's **`@theme`** variable names; add tokens to CSS when missing.) + +### 6. Use arbitrary variants/properties sparingly + +Allowed examples: + +- `[container-type:inline-size]` +- Arbitrary positions that must reference a **`@theme`** custom property: **`bg-[theme(--color-fg)]`**-style values (use the actual **`--*`** names from your **`@theme`** block—see Tailwind v4 **`theme()`** documentation) + +If repeated, recommend **`@utility`** or extending **`@theme`** instead of copying the same arbitrary class everywhere. + +### 7. Preserve responsive, state, and media behavior + +- `@media (min-width: 768px)` → `md:` (match project breakpoints from **`@theme`** / default v4 screens) +- Named container queries (e.g. **`@container media-root`**) → match existing utilities such as **`@*/media-root:`** / **`max-*` / `@2xl`** patterns used in skins—do not silently switch to plain `md:` if the source is container-based +- `:hover` → `hover:` +- `:focus-visible` → `focus-visible:` +- `[data-state='open']` → `data-[state=open]:` + +### 8. After migration — short report + +Include: + +- Converted utilities (what replaced which declarations) +- Arbitrary values used and why each is justified +- Values that should become theme tokens later +- Any CSS that should remain CSS (-keyframes, `@property`, unsupported selectors, etc.) diff --git a/.claude/skills/css-to-tailwind/review/checklist.md b/.claude/skills/css-to-tailwind/review/checklist.md new file mode 100644 index 00000000..8e114325 --- /dev/null +++ b/.claude/skills/css-to-tailwind/review/checklist.md @@ -0,0 +1,33 @@ +# CSS → Tailwind review checklist + +Single-pass checklist against [references/migration.md](../references/migration.md). + +## Utilities and readability + +- [ ] Common layout/properties use core utilities (`flex`, `grid`, spacing, typography) not inlined longhand equivalents +- [ ] Class lists are grouped logically (layout → spacing → typography → visuals → states) consistent with nearby code + +## Theme tokens (Tailwind v4) + +- [ ] Colors, spacing, radii, fonts, shadows, and z-index prefer **`@theme`** / default v4 scales or semantic utilities over raw arbitrary values where a close match exists +- [ ] Repeated `*- [var(...)]` patterns are flagged for **`@theme`** entries and generated utilities (`theme(...)`) instead of one-off brackets + +## Arbitrary values + +- [ ] No arbitrary spacing/radius/type for values that fit the v4 scale or an existing **`@theme`** key (`mt-[16px]` → scale / theme token) +- [ ] Remaining arbitrary values are justified (one-off, pixel-perfect requirement, no utility/property gap) and noted in report; repeated patterns flagged for **`@utility`** + +## Variants and selectors + +- [ ] Breakpoints and **named container** variants match project conventions (viewport `md:` vs **`@container media-root`** variants such as **`@xl/media-root:`** — do not conflate them) +- [ ] Pseudos preserved (`hover:`, `focus-visible:`, `active:`, etc.) +- [ ] Data/state/`aria` attribute selectors preserved as Tailwind variants or justified as remaining CSS + +## Parity + +- [ ] Responsive and motion behavior unchanged vs source (including `motion-safe:` / reduced-motion where relevant) +- [ ] For skins: counterpart **CSS file** behavior considered when only Tailwind presets were touched (or vice versa) + +## Deliverables + +- [ ] Migration report present for non-trivial changes: converted mapping, arbitrary list, suggested tokens, leftover CSS rationale diff --git a/.claude/skills/css-to-tailwind/review/workflow.md b/.claude/skills/css-to-tailwind/review/workflow.md new file mode 100644 index 00000000..6f110b08 --- /dev/null +++ b/.claude/skills/css-to-tailwind/review/workflow.md @@ -0,0 +1,46 @@ +# CSS → Tailwind review workflow + +Reviews assume **Tailwind CSS v4**: theme lives in CSS (**`@theme`**), and repeated patterns belong in **`@utility`** / **`@custom-variant`**, not duplicated arbitrary classes. + +Use this workflow to verify Tailwind migrations and class strings follow [references/migration.md](../references/migration.md). + +## Process + +### 1. Gather context + +- **Source:** original CSS file, module, or styled-component snippet +- **Shared theme:** **`packages/skins/src/shared/tailwind.css`**, app entries with **`@import "tailwindcss"`** and local **`@theme`** +- **Target:** Tailwind class strings (preset templates, skin `tailwind/components/*.ts`, etc.) +- **Scope:** single component, single skin pair (`css/` + `tailwind/`), or PR diff + +### 2. Compare behavior + +Confirm layout, breakpoints, pseudos, data-attribute selectors, transitions, and `pointer-events`/stacking contexts still match intent — not only pixel values. + +### 3. Run the checklist + +Use [checklist.md](checklist.md) section by section. Flag issues with severity: + +| Level | Meaning | +| ----------- | -------------------------------------------- | +| **Blocker** | Wrong behavior or obvious rule violations | +| **Should fix** | Token misuse, fixable arbitrary values | +| **Consider** | Readability, future theme consolidation | + +### 4. Output + +Produce the **migration report** shape from migration rule 8: + +- Arbitrary values + justification or “remove and use scale” +- Suggested theme tokens for follow-up +- Any CSS intentionally left outside Tailwind + +## Quick path + +Small change: skim [checklist.md](checklist.md) only; skip formal report unless the PR is large. + +## References + +| File | Contents | +| ---------------------------------- | ------------ | +| [../references/migration.md](../references/migration.md) | Authoritative rules | diff --git a/CLAUDE.md b/CLAUDE.md index 85db2c91..c1049bb8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -557,6 +557,7 @@ CLAUDE.md contains repo-wide conventions. Domain-specific patterns live in skill | Documentation | `docs` skill | | Component reference pages | `api-reference` skill | | API design and DX | `api` skill | +| CSS → Tailwind migration | `css-to-tailwind` skill | | Updating AI docs | `claude-update` skill | When adding a new rule, ask: "Who needs this?" If it's domain-specific, put it in the relevant skill.