@convertex/skill 1.0.0

package/cli.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, rmSync, readdirSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ANSI colors
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+const SKILL_NAME = 'convertex';
+const SOURCE = resolve(__dirname, 'skills', SKILL_NAME);
+const TARGET_DIR = resolve(process.cwd(), '.claude', 'skills');
+const TARGET = resolve(TARGET_DIR, SKILL_NAME);
+
+const command = process.argv[2] || 'install';
+
+function countFiles(dir) {
+  let count = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    if (entry.isDirectory()) count += countFiles(join(dir, entry.name));
+    else count++;
+  }
+  return count;
+}
+
+function install() {
+  const isUpdate = existsSync(TARGET);
+
+  cpSync(SOURCE, TARGET, { recursive: true });
+
+  const fileCount = countFiles(TARGET);
+  const action = isUpdate ? 'updated' : 'installed';
+
+  console.log('');
+  console.log(`  ${green('✓')} Convertex skill ${bold(action)} successfully`);
+  console.log(`    ${dim(`${fileCount} files → .claude/skills/${SKILL_NAME}/`)}`);
+  console.log('');
+
+  if (!isUpdate) {
+    console.log(`  ${cyan('→')} Run ${bold('claude')} in your terminal to start using the skill.`);
+    console.log(`    Claude will automatically detect and use it for Webflow code generation.`);
+    console.log('');
+  }
+}
+
+function uninstall() {
+  if (!existsSync(TARGET)) {
+    console.log('');
+    console.log(`  ${dim('Convertex skill is not installed.')}`);
+    console.log('');
+    return;
+  }
+
+  rmSync(TARGET, { recursive: true });
+
+  console.log('');
+  console.log(`  ${green('✓')} Convertex skill ${bold('uninstalled')} successfully`);
+  console.log(`    ${dim(`Removed .claude/skills/${SKILL_NAME}/`)}`);
+  console.log('');
+}
+
+function help() {
+  console.log('');
+  console.log(`  ${bold('@convertex/skill')} — Install Convertex skills for Claude Code`);
+  console.log('');
+  console.log(`  ${bold('Usage:')}`);
+  console.log(`    npx @convertex/skill install     Install the skill ${dim('(default)')}`);
+  console.log(`    npx @convertex/skill update      Update to the latest version`);
+  console.log(`    npx @convertex/skill uninstall    Remove the skill`);
+  console.log(`    npx @convertex/skill help         Show this help`);
+  console.log('');
+  console.log(`  ${dim('Skills are installed into .claude/skills/convertex/ in your project root.')}`);
+  console.log(`  ${dim('Learn more at https://convertex.ai')}`);
+  console.log('');
+}
+
+switch (command) {
+  case 'install':
+  case 'update':
+    install();
+    break;
+  case 'uninstall':
+  case 'remove':
+    uninstall();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    help();
+    break;
+  default:
+    console.log('');
+    console.log(`  ${red('✗')} Unknown command: ${bold(command)}`);
+    help();
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@convertex/skill",
+  "version": "1.0.0",
+  "description": "Install Convertex skills for Claude Code — Webflow-compatible HTML/CSS generation with Client-First methodology",
+  "bin": {
+    "convertex-skill": "./cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "skills/"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "webflow",
+    "convertex",
+    "skill",
+    "mcp",
+    "client-first",
+    "html-to-webflow"
+  ],
+  "author": "Convertex",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/convertex/skill"
+  },
+  "homepage": "https://convertex.ai"
+}

package/skills/convertex/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: convertex
+description: "Generate Webflow-compatible HTML and CSS for Convertex. Triggers on: Convertex Capture, Webflow conversion, HTML to Webflow, recreate section, reproduce page, Client-First, Finsweet, w- classes."
+---
+
+# Convertex — Webflow HTML & CSS Generation
+
+Generate HTML and CSS compatible with Webflow's native element system. Output two separate blocks: one for HTML (body only), one for CSS.
+
+## Pre-Flight — Ask Before Generating
+
+Ask these 3 questions in ONE message, then WAIT for the answer:
+
+1. **Client-First or free naming?** — Client-First = apply the [Client-First rules](#client-first) below.
+2. **rem or px?** — rem: `1rem = 16px`. px: pixel values.
+3. **Content language?** — Adapt placeholder text, ARIA labels, and field names.
+
+Skip ONLY if the user already answered all 3 in their current message.
+
+## Output Format
+
+- **HTML block**: Body content only. No `<html>`, `<head>`, `<body>`, or `<style>` tags. Start with the first element.
+- **CSS block**: Separate from HTML. Flat selectors, concrete values, desktop-first with responsive overrides.
+- **JS block**: Separate from HTML. Never place `<script>` tags or inline JavaScript inside the HTML. All JavaScript must be pushed as a separate JS block via the `js` field of `create_page` / `update_page` / `patch_page`. Do NOT wrap JS in `<div class="w-embed">` or any HTML embed — the Convertex editor has a dedicated JS panel.
+- **Push, don't display**: If the Convertex MCP is connected, push code via `notify_sync_start()` then `create_page` / `update_page` / `patch_page`. Do NOT paste large code blocks in chat.
+
+---
+
+## 10 Golden Rules
+
+### 1. Flat CSS selectors only
+
+`.class` or `.class1.class2` (combo). **NEVER** use:
+- Descendant: `.parent .child` — use `.parent_child` instead
+- Child: `.parent > .child` — use `.parent_child` instead
+- Sibling: `.a + .b` — use separate classes
+- Tag-qualified: `div.container` — use `.container`
+
+### 2. Concrete values only — no CSS variables
+
+Write actual values: `color: #2563eb`, never `color: var(--primary)`. Webflow does not support CSS custom properties natively.
+
+### 3. Combo class pattern
+
+First class = base, additional classes = combos. `class="button is-primary"` means `.button` is the base, `.is-primary` is a combo. In CSS: `.button.is-primary { ... }`.
+
+### 4. Semantic HTML tags
+
+Use `<section>`, `<header>`, `<footer>`, `<nav>`, `<main>`, `<article>`, `<aside>` for their semantic purpose. These render as Block elements in Webflow with their HTML tag preserved.
+
+### 5. No hidden states in CSS
+
+**NEVER** set `display: none`, `opacity: 0`, `visibility: hidden`, or `height: 0` in base CSS. Elements must be visible in Webflow Designer for editing. Set initial hidden states via JavaScript on `DOMContentLoaded`. CSS only defines the active/visible state via combo classes: `.modal.is-open { opacity: 1; }`.
+
+### 6. CSS transitions for simple animations
+
+Use `transition` for hover effects and state changes. Only use JavaScript animation libraries (GSAP) for scroll-triggered, staggered, or complex timeline animations.
+
+### 7. Inline SVGs must be wrapped
+
+Raw `<svg>` elements **must** be inside `<div class="w-embed">`. Without the wrapper, SVGs render incorrectly in Webflow.
+
+### 8. Never use `<em>`
+
+`<em>` becomes a block-level element in Webflow. Use `<span>` with a class that sets `font-style: italic` instead.
+
+### 9. Never use inline `style` attributes
+
+All styling must go through CSS classes. The `style` attribute is not supported.
+
+### 10. Webflow components need exact `w-` structures
+
+Navbars, forms, sliders, tabs, dropdowns, lightboxes, and background videos require specific HTML structures with `w-` classes and data attributes. **Read the pattern file** before generating any of these. See [Component Patterns](#component-patterns).
+
+---
+
+## Responsive Breakpoints
+
+| Breakpoint | Media Query | Direction |
+|---|---|---|
+| XXL | `min-width: 1920px` | Upward override |
+| XL | `min-width: 1440px` | Upward override |
+| Large | `min-width: 1280px` | Upward override |
+| **Desktop** | _(no media query)_ | **Base styles** |
+| Tablet | `max-width: 991px` | Downward override |
+| Mobile Landscape | `max-width: 767px` | Downward override |
+| Mobile Portrait | `max-width: 479px` | Downward override |
+
+**Rules:**
+- Desktop-first: base styles have no media query
+- Override downward with `max-width`, upward (rare) with `min-width`
+- Only include properties that actually change — never repeat base values
+- Use **only** these exact breakpoint values
+
+---
+
+## Selector Reference
+
+### Allowed
+```css
+.hero_heading { }                /* Single class */
+.button.is-secondary { }        /* Combo class */
+.button:hover { }               /* Pseudo on class */
+.nav_link.is-active:hover { }   /* Combo + pseudo */
+```
+
+### Forbidden — will break conversion
+```css
+.hero .heading { }          /* Descendant → use .hero_heading */
+.card > .title { }          /* Child → use .card_title */
+.input + .error { }         /* Sibling → use .input_error */
+div.container { }           /* Tag-qualified → use .container */
+a.nav-link { }              /* Tag-qualified → use .nav-link */
+.list_item:nth-child(odd) { } /* Complex pseudo → needs ghost block */
+```
+
+---
+
+## Pseudo-Classes
+
+**Supported natively** (write in CSS): `:hover`, `:active`, `:focus`, `:visited`, `:focus-visible`, `:focus-within`, `::placeholder`
+
+**FORBIDDEN — never use, even in ghost blocks:**
+`::before`, `::after` — poorly supported by Webflow, not manageable in the Designer. Always use a real HTML element instead (e.g. a `<div>` with a class for decorative elements, icons, or separators).
+
+**Not supported natively** (may use a [ghost block](patterns/ghost-blocks.md) if necessary):
+`:nth-child()`, `:first-child`, `:last-child`, `:not()`, `@keyframes`
+
+```html
+<div class="w-embed"><style>
+  .card:first-child { border-top: none; }
+</style></div>
+```
+
+---
+
+## Contextual Styling
+
+Webflow has no descendant selectors. When a parent state must affect children, **propagate the combo class** to every affected child:
+
+```html
+<div class="pricing_card is-featured">
+  <h3 class="pricing_title is-featured">Pro</h3>
+  <p class="pricing_price is-featured">$99/mo</p>
+</div>
+```
+```css
+.pricing_card.is-featured { background-color: #0f172a; }
+.pricing_title.is-featured { color: #ffffff; }
+.pricing_price.is-featured { color: #60a5fa; }
+```
+
+---
+
+## Element Rules
+
+### Spans
+`<span>` is valid only inside text elements (`<p>`, `<h1>`–`<h6>`) or alongside text siblings. In all other cases, use `<div>`.
+
+### Links & Buttons
+**`<button>` is atomic in Webflow — it CANNOT have children.** It only holds plain text. If you need an icon or nested elements, use `<a>` (Link Block) instead.
+
+Inside `<a>` Link Blocks, **always use `<div>`** for child elements (text wrappers, icon containers). Never use `<span>` — it creates Text Spans in Webflow instead of Block elements, breaking layout control.
+
+**Link with icon — correct structure:**
+```html
+<a href="/page" class="button is-primary">
+  <div class="button_text">Get started</div>
+  <div class="w-embed">
+    <svg class="button_icon" width="10" height="10" viewBox="0 0 10 10" fill="none" aria-hidden="true">
+      <path d="M1 5h8M5 1l4 4-4 4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+    </svg>
+  </div>
+</a>
+```
+
+**Simple button — text only:**
+```html
+<button class="button">Get started</button>
+```
+
+**NEVER do this:**
+```html
+<!-- WRONG: children inside <button> -->
+<button class="button">
+  <div class="button_text">Get started</div>
+  <div class="w-embed"><svg>...</svg></div>
+</button>
+
+<!-- WRONG: text directly alongside w-embed -->
+<a href="/page" class="button">
+  Get started
+  <div class="w-embed"><svg>...</svg></div>
+</a>
+
+<!-- WRONG: span inside a link -->
+<a href="/page" class="button">
+  <span class="button_text">Get started</span>
+</a>
+```
+
+### Lists
+```html
+<ul class="features_list">
+  <li class="features_list-item">First feature</li>
+  <li class="features_list-item">Second feature</li>
+</ul>
+```
+Both `<ul>` and `<ol>` are supported. Style via classes on the list and list items.
+
+### Blockquote
+```html
+<blockquote class="testimonial_quote">Customer feedback here.</blockquote>
+```
+
+### Horizontal Rule
+```html
+<hr class="divider" />
+```
+
+---
+
+## Inline Components
+
+| Component | HTML | Notes |
+|---|---|---|
+| **Grid** | `<div class="w-layout-grid my-grid">` | Must have `display: grid` in CSS |
+| **Container** | `<div class="w-layout-blockcontainer my-container">` | Centered max-width block |
+| **Rich Text** | `<div class="w-richtext">` | CMS-style formatted content |
+| **HTML Embed** | `<div class="w-embed">` | Raw HTML, SVG, or `<style>` blocks |
+
+**Note:** `w-container` (used inside navbars) is different from `w-layout-blockcontainer` (general layout container). Don't mix them.
+
+---
+
+## Custom Attributes
+
+- **Standard**: `id`, `href`, `src`, `alt`, `loading`, `target` — set directly on the element
+- **Custom**: `data-*`, `aria-*`, `role`, `tabindex` — supported as custom attributes
+- **`style`** — **never use**
+
+---
+
+## Component Patterns
+
+These components require specific `w-` HTML structures. **Read the pattern file before generating any of them:**
+
+- [Navbar](elements/navbar.md) — `w-nav` with brand, menu, burger button
+- [Forms](elements/forms.md) — `w-form` wrapper with `w-form-done` / `w-form-fail` states
+- [Dropdown](elements/dropdown.md) — `w-dropdown` with toggle and list
+- [Slider](elements/slider.md) — `w-slider` with mask, slides, arrows, dot nav
+- [Tabs](elements/tabs.md) — `w-tabs` with `data-w-tab` matching between links and panes
+- [Lightbox](elements/lightbox.md) — `w-lightbox` with `w-json` config
+- [Background Video](elements/background-video.md) — `w-background-video` with data attributes
+- [Images](elements/images.md) — `<img>`, responsive `srcset`, SVG handling, `object-fit`
+- [Links & Buttons](elements/links-buttons.md) — `<button>` vs `<a>` detection, Link Block vs Text Link
+
+---
+
+## Advanced Reference
+
+- [Ghost Blocks & Dynamic States](patterns/ghost-blocks.md) — hidden states with JS, `::before`/`::after`, `@keyframes`, unsupported CSS via embed blocks
+- [CSS Property Reference](css/best-practices.md) — detailed writing guide for spacing, borders, gradients, transitions, grid, flexbox, typography, filters, effects
+
+---
+
+## Accessibility Checklist
+
+- Every `<img>` must have `alt` (empty `alt=""` for decorative images)
+- Form inputs must have `<label>` with matching `for`/`id`
+- Interactive elements must be keyboard-focusable with visible focus styles
+- Icon-only buttons/links need `aria-label`
+- Color contrast: WCAG AA minimum (4.5:1 normal text, 3:1 large text)
+- Don't rely on color alone to convey information
+- Use semantic tags (`<nav>`, `<main>`, `<section>`, `<article>`)
+
+---
+
+## Client-First
+
+**Only apply this section if the user chose Client-First.** Otherwise skip entirely.
+
+### 5 Rules
+
+1. **Page skeleton is mandatory** — `page-wrapper > main-wrapper > section_[id] > padding-global padding-section-[size] > container-[size] > content`
+2. **Underscore = custom, hyphen = utility** — `hero_heading` (custom), `text-size-large` (utility), `is-primary` (combo)
+3. **All units in rem** — Never px. Only exception: `border-width` can use px.
+4. **Max 2 utility classes per element** — 3+ utilities = create a custom class instead. Exception: `padding-global padding-section-large`.
+5. **Flat CSS selectors only** — Same as Webflow Rule #1.
+
+### 3 Class Types
+
+**Custom** — `[folder]_[element]`: specific to one component.
+`hero_heading`, `footer_link`, `pricing_card`
+
+**Utility** — `[category]-[property]-[value]`: reusable site-wide.
+`text-size-large`, `margin-bottom margin-medium`, `hide-tablet`
+
+**Combo** — `is-[variant]`: modifier on a base class. Never used alone.
+`is-secondary`, `is-featured`, `is-active`
+
+### Page Skeleton
+
+```html
+<div class="page-wrapper">
+  <main class="main-wrapper">
+    <section class="section_hero">
+      <div class="padding-global padding-section-large">
+        <div class="container-large">
+          <!-- content -->
+        </div>
+      </div>
+    </section>
+  </main>
+</div>
+```
+
+Nav and footer go **outside** `main-wrapper`, **inside** `page-wrapper`. `padding-global` and `padding-section-[size]` go on the **SAME div**.
+
+### Detailed Client-First Reference
+
+Read these files for complete patterns and values:
+
+- [Naming Conventions](client-first/naming/conventions.md) — full rules for custom, utility, and combo classes
+- [Page Skeleton](client-first/structure/page-skeleton.md) — 5-layer structure, container sizes, padding values, complete page example
+- [CSS Rules](client-first/css/rules.md) — rem values, core structure CSS, mandatory responsive overrides, typography base styles
+- [Typography Utilities](client-first/utilities/typography.md) — `heading-style-*`, `text-size-*`, `text-weight-*`, `text-color-*`, `text-align-*`
+- [Spacing Utilities](client-first/utilities/spacing.md) — margin/padding two-class system, spacer blocks, all size values
+- [Layout Utilities](client-first/utilities/layout.md) — `max-width-*`, `hide-*`, `background-color-*`, icons, positioning, aspect ratios
+- [Button Utilities](client-first/utilities/buttons.md) — `.button` base, `is-secondary`/`is-text`/`is-small`/`is-large` variants

package/skills/convertex/client-first/css/rules.md

@@ -0,0 +1,102 @@
+# CSS Rules for Client-First
+
+## Units: rem Only
+
+All sizes in rem (`1rem = 16px`). Use these standard values:
+
+| rem | px | | rem | px |
+|---|---|---|---|---|
+| `0.25` | 4 | | `2.5` | 40 |
+| `0.5` | 8 | | `3` | 48 |
+| `0.75` | 12 | | `4` | 64 |
+| `1` | 16 | | `5` | 80 |
+| `1.25` | 20 | | `6` | 96 |
+| `1.5` | 24 | | `8` | 128 |
+| `2` | 32 | | `12` | 192 |
+
+**Exception:** `border-width` values can use `px` (e.g., `border-width: 1px`).
+
+## Core Structure CSS
+
+Only include classes that appear in the HTML:
+
+```css
+/* Horizontal padding */
+.padding-global { padding-left: 2.5rem; padding-right: 2.5rem; }
+
+/* Containers */
+.container-large { max-width: 80rem; margin-left: auto; margin-right: auto; width: 100%; }
+.container-medium { max-width: 64rem; margin-left: auto; margin-right: auto; width: 100%; }
+.container-small { max-width: 48rem; margin-left: auto; margin-right: auto; width: 100%; }
+
+/* Section padding */
+.padding-section-large { padding-top: 8rem; padding-bottom: 8rem; }
+.padding-section-medium { padding-top: 5rem; padding-bottom: 5rem; }
+.padding-section-small { padding-top: 3rem; padding-bottom: 3rem; }
+```
+
+## Mandatory Responsive Overrides
+
+These must always be included when using the corresponding structure classes:
+
+```css
+@media (max-width: 991px) {
+  .padding-global { padding-left: 1.5rem; padding-right: 1.5rem; }
+  .padding-section-large { padding-top: 6rem; padding-bottom: 6rem; }
+  .padding-section-medium { padding-top: 4rem; padding-bottom: 4rem; }
+  .padding-section-small { padding-top: 2rem; padding-bottom: 2rem; }
+}
+
+@media (max-width: 479px) {
+  .padding-global { padding-left: 1.25rem; padding-right: 1.25rem; }
+  .padding-section-large { padding-top: 4rem; padding-bottom: 4rem; }
+  .padding-section-medium { padding-top: 3rem; padding-bottom: 3rem; }
+  .padding-section-small { padding-top: 1.5rem; padding-bottom: 1.5rem; }
+}
+```
+
+## CSS Organization Order
+
+Structure your CSS in this order for consistency:
+
+1. **Core structure** — `padding-global`, containers, `padding-section-*`
+2. **Typography utilities** — `text-size-*`, `text-weight-*`, `heading-style-*`
+3. **Button utilities** — `button`, `.button.is-*` variants
+4. **Spacing utilities** — `margin-*`, `padding-*`, `spacer-*`
+5. **Layout utilities** — `max-width-*`, `hide-*`, `overflow-*`
+6. **Custom classes** — grouped by section (`hero_*`, `features_*`, `footer_*`)
+7. **Responsive overrides** — tablet (991px) → mobile landscape (767px) → mobile portrait (479px)
+
+## Typography Base Styles
+
+Define tag-level styles for consistent typography across the site:
+
+```css
+/* Heading tag styles */
+h1 { font-size: 3.5rem; font-weight: 700; line-height: 1.1; letter-spacing: -0.02em; }
+h2 { font-size: 2.5rem; font-weight: 700; line-height: 1.2; letter-spacing: -0.02em; }
+h3 { font-size: 2rem; font-weight: 600; line-height: 1.3; }
+h4 { font-size: 1.5rem; font-weight: 600; line-height: 1.4; }
+h5 { font-size: 1.25rem; font-weight: 600; line-height: 1.4; }
+h6 { font-size: 1rem; font-weight: 600; line-height: 1.5; }
+
+/* Body text */
+p { font-size: 1rem; line-height: 1.6; color: #374151; }
+a { color: #2563eb; text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+/* Responsive typography */
+@media (max-width: 991px) {
+  h1 { font-size: 2.75rem; }
+  h2 { font-size: 2rem; }
+  h3 { font-size: 1.75rem; }
+}
+
+@media (max-width: 479px) {
+  h1 { font-size: 2.25rem; }
+  h2 { font-size: 1.75rem; }
+  h3 { font-size: 1.5rem; }
+}
+```
+
+**Note:** These are starting values. Adapt sizes, weights, and colors to the project's design system.

package/skills/convertex/client-first/naming/conventions.md

@@ -0,0 +1,92 @@
+# Client-First Naming Conventions
+
+## 3 Class Types
+
+### 1. Custom Classes — `[folder]_[element-name]`
+
+Underscore separates the component (folder) from the element: `hero_heading`, `footer_link`, `team-list_headshot-image`.
+
+Rules:
+- **One underscore only** — folder + element
+- **Hyphens for multi-word names** — `team-list_headshot-wrapper`
+- **Descriptive, not abbreviated** — `hero_description` not `hero_desc`
+- **Lowercase always** — never camelCase
+
+```html
+<section class="section_hero">
+  <div class="hero_content">
+    <h1 class="hero_heading">Welcome</h1>
+    <p class="hero_description">Build something great</p>
+    <div class="hero_button-wrapper">
+      <a href="/start" class="button">Get started</a>
+    </div>
+  </div>
+  <div class="hero_image-wrapper">
+    <img src="hero.jpg" alt="Hero" class="hero_image" />
+  </div>
+</section>
+```
+
+### 2. Utility Classes — `[category]-[property]-[value]`
+
+No underscore, hyphens only. Reusable across the entire site.
+
+```html
+<p class="text-size-large">Large text paragraph</p>
+<div class="margin-bottom margin-medium">Spaced element</div>
+<div class="hide-mobile-portrait">Hidden on small screens</div>
+```
+
+General → specific reading order: `text-size-large` reads as "text → size → large".
+
+### 3. Combo Classes — `is-[variant]`
+
+Applied ON TOP of a base class to create variants. **Never used alone.**
+
+```html
+<a class="button is-secondary">Learn more</a>
+<div class="card is-featured">Featured card</div>
+<a class="nav_link is-active">Current page</a>
+```
+
+```css
+.button.is-secondary { background-color: transparent; border-width: 1px; border-style: solid; }
+.card.is-featured { border-color: #2563eb; }
+.nav_link.is-active { color: #2563eb; font-weight: 700; }
+```
+
+## Decision Guide
+
+| Situation | Use | Example |
+|---|---|---|
+| Specific to one component | Custom | `hero_heading` |
+| Reused across multiple components | Utility | `text-size-large` |
+| Variant of a base style | Combo | `is-highlighted` |
+| 3+ utilities would stack | Custom class instead | `hero_stats` (not `text-size-large text-weight-bold text-color-primary`) |
+
+## No Deep Stacking
+
+Max 2 utility classes per element.
+
+**Exception:** `padding-global padding-section-large` (Layer 4 structure) — this specific combo is always allowed.
+
+**Wrong:**
+```html
+<p class="text-size-large text-weight-bold text-color-primary">Too many utilities</p>
+```
+
+**Right:**
+```html
+<p class="hero_stat-value">Clean custom class</p>
+```
+
+## Common Naming Patterns
+
+| Component | Custom classes |
+|---|---|
+| Hero section | `hero_content`, `hero_heading`, `hero_description`, `hero_button-wrapper`, `hero_image` |
+| Feature card | `feature_card`, `feature_icon`, `feature_title`, `feature_description` |
+| Testimonial | `testimonial_card`, `testimonial_quote`, `testimonial_author`, `testimonial_avatar` |
+| Pricing | `pricing_card`, `pricing_title`, `pricing_price`, `pricing_features`, `pricing_cta` |
+| Footer | `footer_component`, `footer_top`, `footer_bottom`, `footer_link`, `footer_social` |
+| CTA section | `cta_content`, `cta_heading`, `cta_description`, `cta_button-wrapper` |