bem-wind 0.1.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "bem-wind",
+  "version": "0.1.0",
+  "description": "CLI tool to setup BEM-Wind design system with Tailwind, SCSS, and linting rules",
+  "main": "index.js",
+  "bin": {
+    "bem-wind": "./bin/bem-wind.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npm run build && jest --passWithNoTests",
+    "sync-skill": "node scripts/sync-skill.js",
+    "prepack": "npm run build && npm run sync-skill",
+    "prepublishOnly": "npm run build",
+    "publish:beta": "npm publish --tag beta"
+  },
+  "keywords": [
+    "bem",
+    "tailwind",
+    "design-system",
+    "scss",
+    "linting",
+    "cli"
+  ],
+  "author": "Taryn Southern",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tarynstark/bem-wind.git",
+    "directory": "tools/bem-wind-cli"
+  },
+  "homepage": "https://github.com/tarynstark/bem-wind#readme",
+  "bugs": {
+    "url": "https://github.com/tarynstark/bem-wind/issues"
+  },
+  "dependencies": {
+    "commander": "^11.1.0",
+    "inquirer": "^9.2.12",
+    "chalk": "^5.3.0",
+    "ora": "^7.0.1",
+    "fs-extra": "^11.1.1",
+    "mustache": "^4.2.0",
+    "semver": "^7.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.8.0",
+    "@types/inquirer": "^9.0.3",
+    "@types/fs-extra": "^11.0.2",
+    "@types/mustache": "^4.2.2",
+    "typescript": "^5.2.2",
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.5"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "dist/**/*",
+    "templates/**/*",
+    "bin/**/*",
+    "scripts/**/*",
+    "skill/**/*"
+  ]
+}

package/scripts/sync-skill.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Sync the source-of-truth Claude skill into this package so it ships in the
+ * npm tarball. Runs automatically on `prepack` (before `npm pack`/`npm publish`).
+ *
+ * Source of truth: <repo>/skill/bem-wind  (edit there, never in the copy below)
+ * Bundled copy:    tools/bem-wind-cli/skill/bem-wind  (gitignored, generated)
+ */
+const fs = require('fs');
+const path = require('path');
+
+const source = path.resolve(__dirname, '..', '..', '..', 'skill', 'bem-wind');
+const dest = path.resolve(__dirname, '..', 'skill', 'bem-wind');
+
+if (!fs.existsSync(source)) {
+  console.error(`[sync-skill] source skill not found at ${source}`);
+  process.exit(1);
+}
+
+fs.rmSync(path.dirname(dest), { recursive: true, force: true });
+fs.cpSync(source, dest, { recursive: true });
+console.log(`[sync-skill] copied skill → ${path.relative(process.cwd(), dest)}`);

package/skill/bem-wind/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: bem-wind
+description: Write, refactor, and review UI CSS using the BEM-Wind methodology — semantic BEM component classes built entirely from Tailwind utilities inside `@apply` directives, with a project prefix and design tokens. Use whenever styling a component, converting utility-heavy / inline-Tailwind HTML into named classes, setting up a design-token system, or reviewing CSS for design-system consistency. Triggers include "style this component", "convert these Tailwind classes", "clean up this CSS", "BEM-Wind", "@apply", "design tokens", "make this consistent".
+---
+
+# BEM-Wind
+
+BEM-Wind is a CSS methodology that keeps Tailwind's design system while removing utility soup from your markup. You write **semantic, prefixed BEM class names** in HTML and define them in CSS using **only `@apply` directives** built from standard Tailwind utilities. Markup reads like the design; styling stays in the stylesheet; the whole system stays consistent because every value comes from Tailwind's scale (or named design tokens).
+
+It is design-system-agnostic: one structural methodology, any visual identity, swapped via a theme layer.
+
+## The five rules
+
+1. **Everything inside `@apply`.** Never write a raw CSS property (`padding: 12px`) in a component. Compose from Tailwind utilities inside `@apply`. The only exceptions are `content:` for pseudo-elements and binding a CSS custom property (`border-radius: var(--ds-radius-button)`) in a theme.
+2. **Prefix every class** with a 2–4 character project prefix so components are instantly identifiable and searchable. Pick one per project (e.g. `ds-`, `app-`, `acme-`). This skill uses `ds-` in examples — **replace it with the project's actual prefix**, inferring it from existing classes in the codebase before introducing a new one.
+3. **BEM naming:** `[prefix]-block__element--modifier`. Block = component (`ds-card`), element = part of it (`ds-card__title`), modifier = variant/state (`ds-card--featured`). Nest elements/modifiers under the block with SCSS `&`.
+4. **Prefer standard Tailwind values.** Use the scale (`p-4`, `rounded-lg`, `bg-blue-500`, `text-lg`). Reach for an arbitrary bracket value (`max-w-[1200px]`, `bg-[#f7f0e9]`) **only when the design genuinely requires a value off the scale** — a brand color, an exact asset dimension, a specific container width. When you do, it still lives inside `@apply`, never as a standalone property and never as an inline `style=`.
+5. **No utilities in markup.** HTML/JSX carries semantic classes only — never `class="flex items-center p-4 hover:bg-gray-200"`. All of that moves into the `@apply` block.
+
+### Hard prohibitions
+- ❌ Standalone CSS properties inside a component (`display: flex`, `box-shadow: …`) — use `@apply flex`, `@apply shadow-md`.
+- ❌ Decimal off-scale utilities: `p-2.5`, `mb-1.5`, `-translate-y-0.5`. Snap to the nearest scale step (`p-2`/`p-3`, `-translate-y-1`).
+- ❌ Inline `style="…"` as an escape hatch — use an arbitrary value inside `@apply` instead.
+- ❌ Utility classes in HTML/JSX.
+- ❌ Inconsistent or missing prefix.
+
+## Authoring a component
+
+Structure every component block, then its elements, then its modifiers. Always include interactive states (`hover:`, `active:`, `focus:`) and a transition for anything interactive — accessibility and polish are part of the methodology, not an afterthought.
+
+```scss
+.ds-button {
+  @apply inline-flex items-center justify-center gap-2 cursor-pointer;
+  @apply px-4 py-2 text-base font-medium rounded-lg border border-transparent;
+  @apply transition-colors duration-200;
+  @apply focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2;
+
+  &__icon {
+    @apply h-4 w-4 shrink-0;
+  }
+
+  &--primary {
+    @apply bg-blue-500 text-white;
+    @apply hover:bg-blue-600 active:bg-blue-700;
+  }
+
+  &--secondary {
+    @apply bg-gray-200 text-gray-900 border-gray-300;
+    @apply hover:bg-gray-300 active:bg-gray-400;
+  }
+
+  &--large {
+    @apply px-6 py-3 text-lg;
+  }
+}
+```
+
+```html
+<button class="ds-button ds-button--primary ds-button--large">
+  <svg class="ds-button__icon">…</svg>
+  Get started
+</button>
+```
+
+See `reference/examples.md` for card, input, dropdown, modal, tooltip, responsive-grid, animation, and pseudo-element patterns.
+
+## Converting utility-heavy HTML
+
+When refactoring inline Tailwind into BEM-Wind:
+
+1. **Name the component** semantically by purpose, not appearance (`ds-vehicle-card`, not `ds-rounded-box`). Name elements by role (`__title`, `__media`, `__actions`).
+2. **Move every utility** from the markup into the component's `@apply` block, grouped logically (layout → box → color → states). Preserve exact visual output — this is a lift-and-rename, not a redesign.
+3. **Replace the markup** with semantic classes only.
+4. **Lift repeated arbitrary values** (a brand hex used 5×) into a design token / CSS variable and reference it via the theme.
+5. **Migrate gradually** on existing codebases — convert component-by-component, keep visual parity, don't rewrite the design.
+
+## Design tokens & theming
+
+Values map directly between Figma and code: Figma `spacing/large` → token `--ds-space-large` → used via the Tailwind scale or a utility. Keep **structure** (the component's `@apply` rules) separate from **identity** (colors, fonts, radii) so one component library can wear many brands.
+
+- **Core layer** — unstyled structural primitives (`@apply` for layout/spacing/states), no brand colors.
+- **Theme layer** — overrides CSS custom properties (`--ds-color-primary`, `--ds-radius-button`, `--ds-font-display`) and binds them where a token is genuinely dynamic.
+
+`reference/tokens.css` is a complete, ready-to-drop-in token scaffold (spacing, type scale, containers, radius, shadow, z-index, motion, breakpoints, color placeholders, fonts). Copy it, reprefix it, and override the color/font placeholders per project theme.
+
+## Review checklist
+
+When reviewing CSS for BEM-Wind compliance, verify:
+
+- [ ] Every property is inside `@apply` (only `content:` / CSS-var binding excepted)
+- [ ] Consistent project prefix on every class
+- [ ] Correct BEM: `[prefix]-block__element--modifier`, nested with `&`
+- [ ] Standard Tailwind values; arbitrary brackets only where the design truly needs them, and only inside `@apply`
+- [ ] No decimal off-scale utilities (`p-2.5`, `translate-y-0.5`)
+- [ ] Interactive elements have hover/active/focus states + a transition
+- [ ] No utility classes or inline `style=` in the markup
+- [ ] Semantic names describe purpose, not appearance
+- [ ] Primitives are structural; brand color/font/radius live in the theme layer
+
+## Decision flow for any value
+
+1. Is there a standard Tailwind utility? → use it.
+2. Is it near a scale step? → snap to the nearest step.
+3. Does the design genuinely demand an off-scale value? → arbitrary bracket value, inside `@apply`.
+4. Is this value reused or brand-defining? → promote it to a design token in the theme.
+5. Interactive? → add hover/active/focus + transition.

package/skill/bem-wind/reference/examples.md

@@ -0,0 +1,206 @@
+# BEM-Wind component patterns
+
+Reference implementations. Every example uses the `ds-` prefix as a placeholder — **swap in the project's real 2–4 char prefix**. All styling lives inside `@apply`; markup carries semantic classes only.
+
+## Card
+
+```scss
+.ds-card {
+  @apply flex flex-col bg-white rounded-xl border border-gray-200 shadow-sm;
+  @apply transition-shadow duration-200 hover:shadow-md;
+
+  &__media {
+    @apply aspect-video w-full object-cover rounded-t-xl;
+  }
+
+  &__body {
+    @apply flex flex-col gap-2 p-6;
+  }
+
+  &__title {
+    @apply text-lg font-semibold text-gray-900;
+  }
+
+  &__text {
+    @apply text-sm text-gray-600 leading-relaxed;
+  }
+
+  &__footer {
+    @apply mt-auto flex items-center justify-between p-6 border-t border-gray-200;
+  }
+
+  &--featured {
+    @apply border-blue-500 ring-1 ring-blue-500;
+  }
+}
+```
+
+```html
+<article class="ds-card ds-card--featured">
+  <img class="ds-card__media" src="…" alt="…" />
+  <div class="ds-card__body">
+    <h3 class="ds-card__title">Title</h3>
+    <p class="ds-card__text">Supporting copy.</p>
+  </div>
+  <div class="ds-card__footer">…</div>
+</article>
+```
+
+## Form input
+
+```scss
+.ds-input {
+  @apply w-full px-3 py-2 bg-white text-gray-900 placeholder-gray-400;
+  @apply border border-gray-300 rounded-lg;
+  @apply transition-colors duration-200;
+  @apply hover:border-gray-400 focus:border-blue-500 focus:ring-2 focus:ring-blue-500/20 focus:outline-none;
+
+  &--error {
+    @apply border-red-500 focus:border-red-500 focus:ring-red-500/20;
+  }
+
+  &:disabled {
+    @apply bg-gray-100 text-gray-400 cursor-not-allowed;
+  }
+}
+```
+
+## Dropdown
+
+```scss
+.ds-dropdown {
+  @apply relative inline-block;
+
+  &__trigger {
+    @apply inline-flex items-center gap-2 px-3 py-2 rounded-lg border border-gray-300 bg-white;
+    @apply hover:border-gray-400 transition-colors duration-200;
+  }
+
+  &__menu {
+    @apply absolute top-full left-0 mt-1 min-w-[12rem] py-1;
+    @apply bg-white rounded-lg border border-gray-200 shadow-lg;
+    @apply invisible opacity-0 transition-opacity duration-150;
+  }
+
+  &__item {
+    @apply flex items-center gap-2 px-3 py-2 text-sm text-gray-700;
+    @apply hover:bg-gray-100 active:bg-gray-200 cursor-pointer;
+  }
+
+  &--open &__menu {
+    @apply visible opacity-100;
+  }
+}
+```
+
+## Modal
+
+```scss
+.ds-modal {
+  @apply fixed inset-0 z-50 flex items-center justify-center p-4;
+
+  &__overlay {
+    @apply absolute inset-0 bg-black/50;
+  }
+
+  &__panel {
+    @apply relative z-10 w-full max-w-lg max-h-[90vh] overflow-y-auto;
+    @apply bg-white rounded-2xl shadow-2xl;
+  }
+
+  &__header {
+    @apply flex items-center justify-between p-6 border-b border-gray-200;
+  }
+
+  &__body {
+    @apply p-6;
+  }
+
+  &__footer {
+    @apply flex justify-end gap-3 p-6 border-t border-gray-200;
+  }
+}
+```
+
+## Responsive grid (mobile-first)
+
+```scss
+.ds-grid {
+  @apply grid grid-cols-1 gap-4;
+  @apply sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4;
+}
+```
+
+## Animation / loader
+
+```scss
+.ds-loader {
+  @apply h-6 w-6 rounded-full border-2 border-gray-200 border-t-blue-500;
+  @apply animate-spin;
+}
+```
+
+## Pseudo-element (tooltip) — the `content:` exception
+
+`content:` is one of the few raw properties allowed, since Tailwind has no `@apply` for it.
+
+```scss
+.ds-tooltip {
+  @apply relative;
+
+  &::before {
+    @apply absolute bottom-full left-1/2 mb-2 -translate-x-1/2;
+    @apply px-2 py-1 text-xs text-white bg-gray-900 rounded whitespace-nowrap;
+    @apply invisible opacity-0 transition-opacity duration-150;
+    content: attr(data-tooltip);
+  }
+
+  &:hover::before {
+    @apply visible opacity-100;
+  }
+}
+```
+
+## Gradients & shadows — keep them in Tailwind
+
+```scss
+/* ❌ Don't drop to raw CSS */
+.ds-banner {
+  background: linear-gradient(45deg, #ff0000, #00ff00);
+  box-shadow: 0 4px 8px rgba(0,0,0,0.1);
+}
+
+/* ✅ Compose from Tailwind utilities */
+.ds-banner {
+  @apply bg-gradient-to-r from-red-500 to-green-500 shadow-lg;
+}
+```
+
+## Theme override — structure vs. identity
+
+Core primitive (structural, brand-agnostic):
+
+```scss
+.ds-button {
+  @apply inline-flex items-center justify-center px-4 py-2 rounded-lg;
+  @apply transition-colors duration-200;
+}
+```
+
+Theme layer (brand identity via tokens — binding a CSS var is an allowed raw property):
+
+```scss
+:root {
+  --ds-color-primary: #371a1e;   /* burgundy */
+  --ds-radius-button: 5rem;      /* pill */
+}
+
+.ds-button {
+  border-radius: var(--ds-radius-button);
+
+  &--primary {
+    @apply text-white;
+    background-color: var(--ds-color-primary);
+  }
+}
+```

package/skill/bem-wind/reference/tokens.css

@@ -0,0 +1,134 @@
+/**
+ * BEM-Wind core design tokens (public scaffold)
+ *
+ * Drop-in starting point. Find/replace the `ds-` prefix with your project's
+ * prefix, then override the COLOR and FONT placeholders in a per-project theme.
+ * Spacing / type / radius mirror Tailwind's scale so `@apply` values and tokens
+ * stay in lockstep.
+ */
+
+:root {
+  /* ===== SPACING (maps to Figma spacing tokens) ===== */
+  --ds-space-0: 0;
+  --ds-space-1: 0.25rem;   /* 4px  */
+  --ds-space-2: 0.5rem;    /* 8px  */
+  --ds-space-3: 0.75rem;   /* 12px */
+  --ds-space-4: 1rem;      /* 16px - base */
+  --ds-space-5: 1.25rem;   /* 20px */
+  --ds-space-6: 1.5rem;    /* 24px */
+  --ds-space-8: 2rem;      /* 32px */
+  --ds-space-10: 2.5rem;   /* 40px */
+  --ds-space-12: 3rem;     /* 48px */
+  --ds-space-16: 4rem;     /* 64px */
+  --ds-space-20: 5rem;     /* 80px */
+  --ds-space-24: 6rem;     /* 96px */
+
+  --ds-space-xsmall: var(--ds-space-2);
+  --ds-space-small: var(--ds-space-3);
+  --ds-space-medium: var(--ds-space-4);
+  --ds-space-large: var(--ds-space-6);
+  --ds-space-xlarge: var(--ds-space-8);
+  --ds-space-xxlarge: var(--ds-space-12);
+
+  /* ===== TYPOGRAPHY ===== */
+  --ds-text-xs: 0.75rem;    /* 12px */
+  --ds-text-sm: 0.875rem;   /* 14px */
+  --ds-text-base: 1rem;     /* 16px */
+  --ds-text-lg: 1.125rem;   /* 18px */
+  --ds-text-xl: 1.25rem;    /* 20px */
+  --ds-text-2xl: 1.5rem;    /* 24px */
+  --ds-text-3xl: 1.875rem;  /* 30px */
+  --ds-text-4xl: 2.25rem;   /* 36px */
+  --ds-text-5xl: 3rem;      /* 48px */
+  --ds-text-6xl: 3.75rem;   /* 60px */
+  --ds-text-7xl: 4.5rem;    /* 72px */
+
+  --ds-text-display-sm: var(--ds-text-3xl);
+  --ds-text-display-md: var(--ds-text-4xl);
+  --ds-text-display-lg: var(--ds-text-5xl);
+  --ds-text-display-xl: var(--ds-text-6xl);
+
+  --ds-leading-tight: 1.25;
+  --ds-leading-normal: 1.5;
+  --ds-leading-relaxed: 1.625;
+
+  /* ===== CONTAINERS ===== */
+  --ds-container-narrow: 42rem;   /* 672px  */
+  --ds-container-content: 56rem;  /* 896px  */
+  --ds-container-wide: 72rem;     /* 1152px */
+  --ds-container-full: 100%;
+
+  /* ===== RADIUS ===== */
+  --ds-radius-sm: 0.25rem;   /* 4px  */
+  --ds-radius-md: 0.375rem;  /* 6px  */
+  --ds-radius-lg: 0.5rem;    /* 8px  */
+  --ds-radius-xl: 0.75rem;   /* 12px */
+  --ds-radius-2xl: 1rem;     /* 16px */
+  --ds-radius-full: 9999px;
+
+  /* ===== SHADOWS ===== */
+  --ds-shadow-sm: 0 1px 3px 0 rgba(0,0,0,0.1), 0 1px 2px -1px rgba(0,0,0,0.1);
+  --ds-shadow-md: 0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -2px rgba(0,0,0,0.1);
+  --ds-shadow-lg: 0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1);
+  --ds-shadow-xl: 0 20px 25px -5px rgba(0,0,0,0.1), 0 8px 10px -6px rgba(0,0,0,0.1);
+
+  /* ===== Z-INDEX ===== */
+  --ds-z-dropdown: 1000;
+  --ds-z-sticky: 1020;
+  --ds-z-overlay: 1040;
+  --ds-z-modal: 1050;
+  --ds-z-popover: 1060;
+  --ds-z-tooltip: 1070;
+  --ds-z-toast: 1080;
+
+  /* ===== MOTION ===== */
+  --ds-duration-fast: 150ms;
+  --ds-duration-normal: 300ms;
+  --ds-duration-slow: 500ms;
+  --ds-ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --ds-ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* ===== BREAKPOINTS ===== */
+  --ds-screen-sm: 640px;
+  --ds-screen-md: 768px;
+  --ds-screen-lg: 1024px;
+  --ds-screen-xl: 1280px;
+  --ds-screen-2xl: 1536px;
+
+  /* ===== COLOR (placeholders — OVERRIDE PER THEME) ===== */
+  --ds-color-white: #ffffff;
+  --ds-color-black: #000000;
+
+  --ds-color-gray-50: #f9fafb;
+  --ds-color-gray-100: #f3f4f6;
+  --ds-color-gray-200: #e5e7eb;
+  --ds-color-gray-300: #d1d5db;
+  --ds-color-gray-400: #9ca3af;
+  --ds-color-gray-500: #6b7280;
+  --ds-color-gray-600: #4b5563;
+  --ds-color-gray-700: #374151;
+  --ds-color-gray-800: #1f2937;
+  --ds-color-gray-900: #111827;
+
+  --ds-color-primary: var(--ds-color-gray-900);
+  --ds-color-secondary: var(--ds-color-gray-600);
+  --ds-color-accent: var(--ds-color-gray-700);
+
+  --ds-color-text-primary: var(--ds-color-gray-900);
+  --ds-color-text-secondary: var(--ds-color-gray-600);
+  --ds-color-text-muted: var(--ds-color-gray-400);
+  --ds-color-text-inverse: var(--ds-color-white);
+
+  --ds-color-bg-primary: var(--ds-color-white);
+  --ds-color-bg-secondary: var(--ds-color-gray-50);
+  --ds-color-border-primary: var(--ds-color-gray-200);
+
+  /* ===== FONTS (override per theme) ===== */
+  --ds-font-sans: ui-sans-serif, system-ui, sans-serif;
+  --ds-font-serif: ui-serif, Georgia, "Times New Roman", serif;
+  --ds-font-mono: ui-monospace, SFMono-Regular, Menlo, monospace;
+
+  --ds-font-display: var(--ds-font-serif);
+  --ds-font-body: var(--ds-font-sans);
+  --ds-font-code: var(--ds-font-mono);
+}