figma-code-agent 1.0.0

package/skills/build-token-pipeline/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: build-token-pipeline
+description: Build a pipeline that syncs Figma design tokens to code. Use this skill when the user needs automated or on-demand synchronization of Figma Variables into CSS Custom Properties, Tailwind config, SCSS variables, or other token formats.
+---
+
+@knowledge/figma-api-variables.md
+@knowledge/design-tokens.md
+@knowledge/design-tokens-variables.md
+@knowledge/figma-api-webhooks.md
+@knowledge/css-strategy.md
+
+## Objective
+
+Help the user build a token synchronization pipeline that reads Figma Variables (or extracts tokens from file data) and outputs production-ready CSS Custom Properties, Tailwind config, SCSS variables, or other formats. The skill covers the full pipeline: trigger mechanism (webhook, CLI, CI/CD), API access, variable resolution, alias chain following, mode classification, naming, multi-format rendering, and drift detection.
+
+## Input
+
+The user provides their token pipeline requirements as `$ARGUMENTS`. This may be:
+
+- A description of the desired sync workflow (e.g., "sync Figma Variables to CSS and Tailwind on every library publish")
+- A path to an existing token pipeline to enhance
+- Specific requirements (output formats, mode handling, naming conventions)
+- Questions about Variables API access or Enterprise requirements
+
+If the input is a path, read the project files before proceeding. If the input is a description, proceed directly to Phase 1.
+
+## Process
+
+### Phase 1 — Assess
+
+Determine the pipeline's scope, trigger mechanism, and constraints.
+
+**Sync trigger:**
+- **Webhook-driven**: automatic sync on Figma library publish events. Requires a server endpoint to receive `LIBRARY_PUBLISH` webhooks. Best for continuous sync.
+- **CLI command**: manual `npm run sync-tokens` or similar. Best for controlled releases.
+- **CI/CD job**: runs in GitHub Actions, GitLab CI, etc. Triggered on schedule or manual dispatch. Best for teams that want PR-based token review.
+- **Combination**: webhook triggers a CI job, or CLI triggers a CI job
+
+**Output formats (can select multiple):**
+- **CSS Custom Properties** — `:root` block with mode-aware overrides. The primary format.
+- **Tailwind config** — `theme.extend` referencing CSS variables via `var()`. For Tailwind projects.
+- **SCSS variables** — `$variable` declarations referencing CSS Custom Properties. For SCSS projects.
+- **JSON** — Flat or nested token structure. For tools like Style Dictionary, Tokens Studio, or custom consumers.
+- **TypeScript** — Type-safe token constants. For programmatic token access.
+
+**Variable scope:**
+- All collections and variables (full sync)
+- Filtered by collection name (e.g., only "Primitives" and "Semantic")
+- Filtered by variable scope (e.g., only `ALL_SCOPES` or specific scopes like `FRAME_FILL`, `TEXT_CONTENT`)
+
+**API access:**
+- **Variables API** (Enterprise plan required): `GET /v1/files/:key/variables/local` with `file_variables:read` scope. Provides structured variable collections, modes, alias chains, scopes.
+- **Fallback** (any plan): file traversal + threshold-based promotion. Reads node properties, detects repeated values, promotes to tokens. Less structured but works without Enterprise.
+- Assess which access level the user has and plan accordingly. Both paths should produce equivalent CSS output.
+
+**Mode strategy:**
+- How many modes does each collection have?
+- What do the modes represent?
+  - **Theme modes** (Light/Dark, Brand A/Brand B) → `@media (prefers-color-scheme)` + `[data-theme]` selectors
+  - **Breakpoint modes** (Mobile/Tablet/Desktop) → `@media (min-width)` with mobile-first ascending order
+  - **Density modes** (Compact/Default/Comfortable) → `[data-density]` attribute selector
+- Which mode is the default (base `:root`)?
+
+Report the assessment to the user before proceeding.
+
+### Phase 2 — Recommend
+
+Based on the assessment, recommend the pipeline architecture.
+
+**Mode rendering strategy:**
+
+For **theme modes**:
+```css
+/* Base (Light mode — default) */
+:root { --color-primary: hsl(220, 90%, 56%); }
+
+/* System preference */
+@media (prefers-color-scheme: dark) {
+  :root { --color-primary: hsl(220, 90%, 65%); }
+}
+
+/* Class-based override (progressive enhancement) */
+[data-theme="dark"] { --color-primary: hsl(220, 90%, 65%); }
+```
+- Render BOTH `@media (prefers-color-scheme)` AND `[data-theme]` for each non-default theme mode
+- Only emit tokens whose values differ from the base mode in overrides
+
+For **breakpoint modes**:
+```css
+/* Base (Mobile — smallest, default) */
+:root { --spacing-section: 1.5rem; }
+
+@media (min-width: 768px) {
+  :root { --spacing-section: 2rem; }
+}
+
+@media (min-width: 1024px) {
+  :root { --spacing-section: 3rem; }
+}
+```
+- Mobile-first: smallest breakpoint is base, larger breakpoints add overrides
+- Ascending `min-width` order
+- Only emit changed tokens in each breakpoint
+
+**Naming convention:**
+- Preserve Figma variable path as the name basis: `color/primary/500` → `--color-primary-500`
+- Slash-separated paths become hyphen-separated CSS property names
+- Category prefixes maintained: `--color-*`, `--spacing-*`, `--font-*`, `--radius-*`, `--shadow-*`
+- For file traversal fallback: use HSL classification for colors, base-unit detection for spacing (see `knowledge/design-tokens.md`)
+
+**Alias chain resolution:**
+- Variables can alias other variables (`VariableAlias` type)
+- Chains can be multi-level: `semantic/primary` → `brand/blue-500` → `primitive/blue-500`
+- Resolve to terminal value for each mode
+- In CSS output, decide whether to preserve alias relationships as `var()` references or flatten to resolved values:
+  - **Preserve aliases** (recommended): `--color-primary: var(--color-blue-500);` — maintains semantic relationships, enables override
+  - **Flatten**: `--color-primary: hsl(220, 90%, 56%);` — simpler but loses relationship
+
+**Drift detection:**
+- Compare code tokens (parsed from existing CSS/JSON) against Figma source
+- Report: added tokens (in Figma but not code), removed tokens (in code but not Figma), changed values
+- Output as a structured diff report or GitHub PR comment
+
+**Webhook setup** (if webhook trigger):
+- Listen for `LIBRARY_PUBLISH` event type
+- Verify passcode from webhook payload (`passcode` field must match configured secret)
+- Debounce: if multiple publishes arrive within 30 seconds, process only the latest
+- Retry handling: Figma retries failed webhook deliveries, so handlers must be idempotent
+
+**Fallback strategy** (when Variables API unavailable):
+- Traverse file nodes via REST API
+- Collect repeated values across 5 domains (colors, spacing, typography, effects, breakpoints)
+- Promote values used 2+ times to tokens (threshold-based promotion)
+- Apply HSL color classification and spacing base-unit detection for naming
+- Document the difference in output quality between Variables API and fallback paths
+
+Present the recommendations and confirm before implementing.
+
+### Phase 3 — Implement
+
+Generate the token pipeline code.
+
+**1. Sync script (main entry point):**
+
+```typescript
+// scripts/sync-tokens.ts (or src/tokens/sync.ts)
+async function syncTokens(options: SyncOptions): Promise<SyncResult> {
+  // 1. Fetch variables from Figma (or fallback to file traversal)
+  // 2. Classify collection modes (theme vs breakpoint)
+  // 3. Resolve alias chains to terminal values
+  // 4. Assign semantic names (preserve Figma paths or apply HSL/scale naming)
+  // 5. Render to output formats (CSS, Tailwind, SCSS, JSON)
+  // 6. Run drift detection against existing token files
+  // 7. Write output files
+  // 8. Return sync report (added/changed/removed tokens)
+}
+```
+
+**2. Variable resolution module:**
+
+```typescript
+// src/tokens/resolver.ts
+function resolveVariables(
+  variables: Variable[],
+  collections: VariableCollection[]
+): ResolvedTokenMap {
+  // For each variable:
+  //   - Classify the parent collection's modes
+  //   - For each mode:
+  //     - Follow alias chains to terminal value
+  //     - Convert COLOR values to HSL
+  //     - Convert FLOAT values to rem (divide by 16)
+  //   - Determine which modes differ from the default
+}
+```
+
+- Follow alias chains: if value is `{ type: 'VARIABLE_ALIAS', id: '...' }`, look up the referenced variable and recurse
+- Handle circular alias detection (guard against infinite loops)
+- Classify modes using name heuristics from `knowledge/design-tokens-variables.md`
+
+**3. Output renderers:**
+
+**CSS renderer:**
+```typescript
+// src/tokens/renderers/css.ts
+function renderCSS(tokens: ResolvedTokenMap): string {
+  // :root block with default mode values
+  // Theme mode overrides: @media (prefers-color-scheme) + [data-theme]
+  // Breakpoint mode overrides: @media (min-width) ascending
+  // Only tokens that differ from base mode in overrides
+  // HSL format for colors, rem for spacing/typography
+  // Comments with original Figma variable paths
+}
+```
+
+**Tailwind renderer:**
+```typescript
+// src/tokens/renderers/tailwind.ts
+function renderTailwind(tokens: ResolvedTokenMap): string {
+  // theme.extend configuration
+  // All values reference var() — never hardcoded
+  // Colors → theme.extend.colors
+  // Spacing → theme.extend.spacing
+  // Typography → theme.extend.fontFamily, fontSize
+  // Effects → theme.extend.borderRadius, boxShadow
+}
+```
+
+**SCSS renderer:**
+```typescript
+// src/tokens/renderers/scss.ts
+function renderSCSS(tokens: ResolvedTokenMap): string {
+  // $variable declarations referencing var() CSS Custom Properties
+  // Organized by category with section comments
+}
+```
+
+**JSON renderer:**
+```typescript
+// src/tokens/renderers/json.ts
+function renderJSON(tokens: ResolvedTokenMap): object {
+  // Nested structure preserving collection/group hierarchy
+  // Each token: { value, type, description, modes }
+  // Compatible with Style Dictionary or Tokens Studio input
+}
+```
+
+**4. Webhook handler (if webhook trigger):**
+
+```typescript
+// src/api/webhook.ts (or pages/api/figma-webhook.ts)
+export async function handleWebhook(request: Request): Promise<Response> {
+  // 1. Verify passcode matches configured secret
+  // 2. Check event_type === 'LIBRARY_PUBLISH'
+  // 3. Debounce (skip if another sync started within 30 seconds)
+  // 4. Extract file_key from payload
+  // 5. Call syncTokens({ fileKey, ... })
+  // 6. Return 200 (Figma expects quick response)
+}
+```
+
+- Passcode verification: compare `request.body.passcode` against environment variable
+- Idempotent: safe to process the same event multiple times
+- Quick response: return 200 immediately, process sync asynchronously if needed
+
+**5. Drift detection module:**
+
+```typescript
+// src/tokens/drift.ts
+function detectDrift(
+  currentTokens: ResolvedTokenMap,
+  existingFile: string
+): DriftReport {
+  // Parse existing token file (CSS, JSON, or SCSS)
+  // Compare against current Figma tokens
+  // Categorize differences: added, removed, changed (with old + new values)
+  // Return structured report
+}
+```
+
+**6. CI/CD integration (if CI/CD trigger):**
+
+```yaml
+# .github/workflows/sync-tokens.yml
+name: Sync Design Tokens
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 9 * * 1'  # Weekly Monday 9am
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npm run sync-tokens
+        env:
+          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
+          FIGMA_FILE_KEY: ${{ vars.FIGMA_FILE_KEY }}
+      - uses: peter-evans/create-pull-request@v6
+        with:
+          title: 'Update design tokens from Figma'
+          body: 'Automated token sync from Figma Variables'
+          branch: tokens/auto-sync
+```
+
+### Phase 4 — Validate
+
+Verify the token pipeline produces correct output.
+
+**Variable resolution:**
+- [ ] Alias chains fully resolved to terminal values (no unresolved aliases)
+- [ ] Circular alias detection prevents infinite loops
+- [ ] All modes for each collection are processed
+- [ ] Mode classification correct (theme vs breakpoint vs unknown)
+- [ ] Default mode identified correctly (Light for themes, Mobile for breakpoints)
+
+**CSS output:**
+- [ ] Theme overrides use BOTH `@media (prefers-color-scheme)` AND `[data-theme]` selectors
+- [ ] Breakpoint overrides use `@media (min-width)` in ascending mobile-first order
+- [ ] Only tokens with differing values appear in mode overrides
+- [ ] Colors in HSL format
+- [ ] Spacing and font sizes in rem units (with px comments)
+- [ ] Comments show original Figma variable paths
+
+**Tailwind output:**
+- [ ] All values reference `var()` — no hardcoded values
+- [ ] Token categories map to correct Tailwind theme keys
+- [ ] Config is a valid `theme.extend` snippet (not a full config replacement)
+
+**Pipeline integrity:**
+- [ ] Auth scope includes `file_variables:read` (for Variables API path)
+- [ ] Fallback path works when Variables API returns 403 (non-Enterprise)
+- [ ] Webhook passcode verification implemented (if webhook trigger)
+- [ ] Drift detection correctly identifies added/removed/changed tokens
+- [ ] Output files are deterministic (same input produces same output)
+
+## Output
+
+Generate the token pipeline files:
+
+### Core Files
+
+- **`scripts/sync-tokens.ts`** (or `src/tokens/sync.ts`) — Main sync entry point
+- **`src/tokens/resolver.ts`** — Variable resolution with alias chain following
+- **`src/tokens/classifier.ts`** — Mode classification (theme vs breakpoint)
+- **`src/tokens/types.ts`** — Token types, resolved token map, sync options
+
+### Renderer Files
+
+- **`src/tokens/renderers/css.ts`** — CSS Custom Properties with mode overrides
+- **`src/tokens/renderers/tailwind.ts`** — Tailwind theme.extend config
+- **`src/tokens/renderers/scss.ts`** — SCSS variables (if requested)
+- **`src/tokens/renderers/json.ts`** — JSON token structure (if requested)
+
+### Trigger Files (based on selected trigger)
+
+- **`src/api/webhook.ts`** — Webhook handler (if webhook trigger)
+- **`.github/workflows/sync-tokens.yml`** — GitHub Actions workflow (if CI/CD trigger)
+- **`scripts/sync-tokens.ts`** — CLI script with argument parsing (if CLI trigger)
+
+### Supporting Files
+
+- **`src/tokens/drift.ts`** — Drift detection module
+- **Generated `tokens.css`** — Example output showing expected format
+
+### Output Checklist
+
+Before returning the pipeline code, verify:
+
+- [ ] Correct auth scope for Variables API (`file_variables:read`)
+- [ ] Alias chains fully resolved with circular reference protection
+- [ ] Modes classified correctly (theme vs breakpoint)
+- [ ] HSL format for colors, rem units for spacing
+- [ ] Theme overrides render both `@media (prefers-color-scheme)` and `[data-theme]`
+- [ ] Breakpoint overrides render mobile-first ascending `@media (min-width)`
+- [ ] Tailwind config uses `var()` references (no hardcoded values)
+- [ ] Webhook handler verifies passcode (if webhook trigger)
+- [ ] Fallback path documented and functional for non-Enterprise users
+- [ ] Drift detection identifies added/removed/changed tokens
+- [ ] Pipeline output is deterministic (same input → same output)

package/skills/ref-html/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: ref-html
+description: "Reference: Generate semantic HTML5 and layered CSS from Figma node data. Use this skill when the user has Figma design data and needs vanilla HTML + CSS output (no React, no JSX, no TypeScript). Ideal for static sites, email templates, prototypes, or framework-agnostic code."
+---
+
+@knowledge/design-to-code-layout.md
+@knowledge/design-to-code-visual.md
+@knowledge/design-to-code-typography.md
+@knowledge/design-to-code-assets.md
+@knowledge/design-to-code-semantic.md
+@knowledge/css-strategy.md
+@knowledge/design-tokens.md
+
+## Objective
+
+Generate semantic HTML5 markup and layered CSS from Figma node data. The output is framework-agnostic: a standalone `.html` file and a companion `.css` file using the three-layer CSS architecture (Tailwind utilities for layout, CSS Custom Properties for design tokens, and component-scoped classes for visual skin). No React, JSX, or TypeScript is involved.
+
+## Input
+
+The user provides Figma design data as `$ARGUMENTS`. This may be:
+
+- Raw Figma REST API JSON (node tree with children, fills, strokes, effects, text properties)
+- Extracted/summarized node properties
+- A description of the Figma component or page (layer names, layout, colors, typography)
+- A Figma file/node URL (use the REST API knowledge to fetch data if needed)
+
+If the input is insufficient for full generation, ask the user for what is missing. At minimum you need: component structure (parent/child hierarchy), layout mode, and visual properties for each node.
+
+## Process
+
+Follow these steps in order. Each step references the relevant knowledge module for detailed mapping rules.
+
+### Step 1: Analyze Node Tree Structure
+
+Identify the component boundary and internal hierarchy:
+
+- The root node is the top-level container.
+- Map each child node to its role: structural container, text element, image, icon/vector, interactive element.
+- Identify repeated patterns that could use consistent class naming.
+- Note variants or states that may need CSS modifier classes.
+
+### Step 2: Determine Semantic HTML5 Elements
+
+Consult `knowledge/design-to-code-semantic.md`:
+
+- Match layer names against semantic tag heuristics:
+  - **Structural landmarks**: `<header>`, `<nav>`, `<main>`, `<aside>`, `<section>`, `<article>`, `<footer>`
+  - **Headings**: `<h1>` through `<h6>` based on name and font size heuristics
+  - **Text**: `<p>`, `<span>`, `<blockquote>`, `<figcaption>`
+  - **Interactive**: `<button>`, `<a>`, `<input>`, `<form>`, `<select>`, `<label>`
+  - **Media**: `<img>`, `<picture>`, `<figure>`, `<svg>`
+  - **Lists**: `<ul>`, `<ol>`, `<li>` when repeated children are detected
+- Enforce heading hierarchy: single `<h1>`, sequential levels, no headings inside buttons or links.
+- Default to `<div>` only when no semantic match is found.
+
+### Step 3: Extract Layout Properties
+
+Consult `knowledge/design-to-code-layout.md`:
+
+- For Auto Layout containers: map `layoutMode`, alignment, gap, padding, wrap, constraints.
+- For each child: determine sizing mode on primary and counter axes.
+- **CRITICAL**: FILL on primary axis requires BOTH `flex-grow: 1` AND `flex-basis: 0`.
+- FILL on counter axis with max constraint uses `width: 100%`/`height: 100%`, not `align-self: stretch`.
+- Handle absolute children with `position: relative` on parent and constraint-based offsets on child.
+- For GROUP/legacy frames: absolute positioning with coordinate adjustments.
+
+### Step 4: Extract Visual Properties
+
+Consult `knowledge/design-to-code-visual.md`:
+
+- **Fills**: solid colors -> `background-color`, gradients -> `background-image`, images -> handled in Step 6.
+- **Strokes**: INSIDE alignment -> `box-shadow: inset 0 0 0 {width}px {color}` (NOT `border`). CENTER/OUTSIDE -> standard `border` or `outline`.
+- **Effects**: drop shadows -> `box-shadow`, inner shadows -> `box-shadow: inset`, layer blur -> `filter: blur()`, background blur -> `backdrop-filter: blur()`.
+- **Corner radius**: uniform -> `border-radius`, per-corner -> `border-radius: TL TR BR BL` with shorthand optimization.
+- **Opacity**: node-level -> CSS `opacity`, fill-level -> embedded in color alpha. Never double-apply.
+- **Gradients**: convert angle with `90 - figmaAngle` for CSS. Map gradient stops with position percentages.
+- **Variable bindings**: resolve to `var(--token-name)` with pixel fallbacks for external library variables.
+
+### Step 5: Extract Typography
+
+Consult `knowledge/design-to-code-typography.md`:
+
+- Map font family, weight, size, and style.
+- **Line height**: ALWAYS use unitless ratio (`lineHeightPx / fontSize`). Never use px or % for line-height.
+- Letter spacing: convert from Figma percentage to CSS `em` value.
+- Text decoration, text transform, text alignment.
+- Handle styled segments (mixed fonts/weights/colors within one text node) as nested `<span>` elements.
+- Text auto-resize modes interact with layout sizing -- resolve the interaction.
+
+### Step 6: Handle Assets
+
+Consult `knowledge/design-to-code-assets.md`:
+
+- **Vector containers** (nodes with only vector/boolean children and no Auto Layout): export as inline SVG or reference SVG file.
+- **Images**: use `<img>` with descriptive `alt` text derived from layer name. Specify `srcset` at **2x minimum** for retina displays.
+- **Decision tree**: If the vector is simple and needs color control -> inline SVG. If complex or decorative -> `<img src="asset.svg">`.
+- Deduplicate identical images (same `imageHash`).
+
+### Step 7: Extract Design Tokens
+
+Consult `knowledge/design-tokens.md`:
+
+- Collect repeated values (colors, spacing, font sizes, radii, shadows) across the node tree.
+- Values used 2+ times are promoted to CSS Custom Properties.
+- Apply semantic naming: HSL hue classification for colors, grid-based scale names for spacing.
+- Figma Variable bindings take priority over auto-detected tokens.
+- Token extraction priority: Variables API > styles > file traversal > Plugin API.
+
+### Step 8: Generate Layered CSS
+
+Consult `knowledge/css-strategy.md`:
+
+Structure the CSS output with clear layer separation:
+
+**Layer 1 -- Tailwind Utilities (layout bones):**
+Applied as utility classes directly in the HTML `class` attribute:
+- Flexbox: `flex`, `flex-row`, `flex-col`, `items-center`, `justify-between`
+- Spacing: `gap-4`, `p-6`, `px-4`, `py-2`
+- Sizing: `w-full`, `h-auto`, `max-w-lg`, `flex-1`
+- Positioning: `relative`, `absolute`, `top-0`, `right-0`
+- Responsive: `md:flex-row`, `lg:gap-8`
+
+**Layer 2 -- CSS Custom Properties (design tokens):**
+Defined in a `:root` block at the top of the CSS file:
+```css
+:root {
+  /* Colors */
+  --color-primary: #2563eb;
+  --color-surface: #ffffff;
+  --color-text-primary: #111827;
+  --color-border: #e5e7eb;
+
+  /* Typography */
+  --font-heading: 'Instrument Sans', sans-serif;
+  --font-body: 'Inter', sans-serif;
+  --font-size-xl: 1.5rem;
+  --font-size-base: 1rem;
+
+  /* Spacing */
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 1.5rem;
+
+  /* Effects */
+  --radius-md: 0.5rem;
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+}
+```
+
+**Layer 3 -- Component Classes (visual skin):**
+BEM-named classes for component-specific visual styles:
+```css
+.card {
+  background-color: var(--color-surface);
+  box-shadow: inset 0 0 0 1px var(--color-border);  /* INSIDE stroke */
+  border-radius: var(--radius-md);
+}
+
+.card__title {
+  color: var(--color-text-primary);
+  font-family: var(--font-heading);
+  font-size: var(--font-size-xl);
+  line-height: 1.3;  /* unitless: lineHeightPx / fontSize */
+}
+```
+
+### Step 9: Generate BEM Class Names
+
+Consult `knowledge/design-to-code-semantic.md`:
+
+- Block name from the root component (kebab-case from Figma layer name).
+- Element names with double underscore: `block__element`.
+- **NEVER nest deeper than one level**: `block__element` is valid, `block__element__sub` is NOT. Flatten to `block__sub` or use a modifier.
+- Modifier with double dash: `block__element--modifier`.
+- Deduplicate class names within the component tree.
+
+### Step 10: Add ARIA and Accessibility
+
+- `alt` attribute on every `<img>` (descriptive for content images, empty `alt=""` for decorative).
+- `aria-label` on interactive elements without visible text labels.
+- `role` attribute where semantic HTML alone is insufficient.
+- `aria-hidden="true"` on decorative SVGs and icons.
+- Keyboard-accessible interactive elements (buttons, links use native elements; custom controls get `tabindex` and key handlers).
+
+### Step 11: Handle Responsive Breakpoints
+
+If the Figma data includes multiple frames for breakpoints (detected via `#mobile`/`#tablet`/`#desktop` suffix or variant properties):
+
+- Smallest frame provides base styles (no media query).
+- Larger frames contribute override styles in `@media (min-width: ...)` blocks.
+- Standard breakpoints: mobile (base), tablet (`768px`), desktop (`1024px`).
+- Only emit properties that differ from the base.
+- Reset layout properties (`align-self: auto`, `flex-grow: 0`, `flex-shrink: 1`, `flex-basis: auto`) that exist in base but not in larger breakpoints.
+- Transform fixed pixel widths in responsive overrides to `width: 100%; max-width: Npx`.
+
+## Output
+
+Generate two files:
+
+### 1. `component-name.html`
+
+Semantic HTML5 with Tailwind utility classes for layout and BEM classes for visual skin:
+
+```html
+<section class="flex flex-col gap-4 p-6 card">
+  <h2 class="card__title">Card Heading</h2>
+  <p class="card__description">
+    Description text with <span class="card__highlight">highlighted</span> segments.
+  </p>
+  <figure class="card__media">
+    <img
+      src="hero.jpg"
+      srcset="hero.jpg 1x, hero@2x.jpg 2x"
+      alt="Product showcase"
+      class="w-full h-auto card__image"
+    >
+  </figure>
+  <button class="flex items-center justify-center card__action" type="button">
+    Get Started
+  </button>
+</section>
+```
+
+### 2. `component-name.css`
+
+Layered CSS with clear section comments:
+
+```css
+/* ========================================
+   Design Tokens (Layer 2)
+   ======================================== */
+:root {
+  --color-primary: #2563eb;
+  --color-surface: #ffffff;
+  /* ... */
+}
+
+/* ========================================
+   Component Styles (Layer 3)
+   ======================================== */
+.card {
+  background-color: var(--color-surface);
+  border-radius: var(--radius-md);
+}
+
+.card__title {
+  color: var(--color-text-primary);
+  font-family: var(--font-heading);
+  font-size: var(--font-size-xl);
+  line-height: 1.3;
+}
+
+/* ========================================
+   Responsive Overrides
+   ======================================== */
+@media (min-width: 768px) {
+  /* Only changed properties */
+}
+
+@media (min-width: 1024px) {
+  /* Only changed properties */
+}
+```
+
+### Key Differences from generate-react
+
+This skill generates **vanilla HTML + CSS**:
+- No JSX syntax (uses standard HTML attributes: `class` not `className`, `for` not `htmlFor`)
+- No TypeScript interfaces or prop types
+- No React imports, hooks, or component functions
+- No CSS Modules import (classes are global BEM names, not hashed)
+- Design tokens are defined inline in the CSS file's `:root` block
+- Suitable for static sites, email templates, CMS integration, or any non-React context
+
+### Critical Rules Checklist
+
+Before returning the output, verify:
+
+- [ ] INSIDE strokes use `box-shadow: inset`, not `border`
+- [ ] Gradient angles use `90 - figmaAngle` conversion
+- [ ] Line heights are unitless ratios (`lineHeightPx / fontSize`)
+- [ ] Images reference 2x assets for retina (`srcset` or `@2x` naming)
+- [ ] BEM nesting is flat: never `block__element__sub`
+- [ ] FILL on primary axis has BOTH `flex-grow: 1` AND `flex-basis: 0`
+- [ ] CSS has clear layer separation (tokens in `:root`, visual skin in BEM classes)
+- [ ] No hardcoded color values in component classes -- use `var()` for tokens
+- [ ] Semantic HTML5 tags used where layer names match heuristics
+- [ ] ARIA attributes present on interactive and image elements
+- [ ] Uses HTML attributes (`class`, `for`) not JSX attributes (`className`, `htmlFor`)
+- [ ] Responsive overrides include layout property resets where needed