zoriya/v10
1
0
Fork 0
mirror of https://github.com/zoriya/v10.git synced 2026-08-04 21:27:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(claude): add css to tailwind migration skill (#1548)

Browse Source
This commit is contained in:
Sam Potts
2026-05-19 10:37:43 +10:00
committed by GitHub
parent e68ace82ff
commit e71014d2f6
7 changed files with 241 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/README.md
+10 -5
View File
@@ -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`.
.claude/skills/claude-update/SKILL.md
+2 -1
View File
@@ -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.
.claude/skills/css-to-tailwind/SKILL.md
+47
View File
@@ -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 |
.claude/skills/css-to-tailwind/references/migration.md
+102
View File
@@ -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.)
.claude/skills/css-to-tailwind/review/checklist.md
+33
View File
@@ -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
.claude/skills/css-to-tailwind/review/workflow.md
+46
View File
@@ -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 |
CLAUDE.md
+1
View File
@@ -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.