Game Loopers CSS BEM Audit & Refactor Skill

Skill Name

**css-bem-auditor**

Purpose

Audit, normalize, and refactor CSS across the Game Loopers application to comply with the project's **BEM (Block–Element–Modifier)** methodology and design system, ensuring maintainability, consistency, and scalability.

This skill identifies non-compliant selectors, design token violations, naming collisions, overly-specific rules, and architectural inconsistencies, then proposes or applies BEM-aligned fixes specific to Game Loopers.

**Critical**: This project uses **strict BEM with NO utility-first CSS** (no Tailwind, no inline utilities). All styles must use component-scoped CSS with BEM naming.

---

Scope

This skill operates on:

Astro component styles (`.astro` files with `<style>` blocks)

SolidJS component stylesheets (`.tsx` files with co-located `.css` files)

Global stylesheets (`/src/styles/global.css`)

Component-specific CSS files (e.g., `product-files-form.css`)

It does **not** redesign UI or change visual intent unless explicitly requested.

---

Design System Reference

Game Loopers has a comprehensive design system defined in `DESIGN_SYSTEM.md` (co-located in this directory). All CSS must comply with:

Color System (CSS Custom Properties)

**Semantic Colors**:

```css

--primary /* Black in light mode */

--primary-foreground /* White text on primary */

--secondary /* Light gray */

--secondary-foreground

--destructive /* Red for errors/delete */

--destructive-foreground

--accent /* Highlights, hover states */

--accent-foreground

--background /* Page background */

--foreground /* Primary text */

--card /* Card backgrounds */

--card-foreground

--muted /* Low emphasis backgrounds */

--muted-foreground /* Secondary text */

--border /* Default borders */

--input /* Input borders */

--ring /* Focus ring color */

```

**Status Colors**:

```css

--color-success /* Green - confirmations */

--color-success-foreground

--color-warning /* Yellow - cautions */

--color-warning-foreground

--color-error /* Red - failures */

--color-error-foreground

--color-info /* Blue - notifications */

--color-info-foreground

```

Typography Scale

```css

--text-xs: 0.75rem; /* 12px */

--text-sm: 0.875rem; /* 14px */

--text-base: 1rem; /* 16px */

--text-lg: 1.125rem; /* 18px */

--text-xl: 1.25rem; /* 20px */

--text-2xl: 1.5rem; /* 24px */

--text-3xl: 1.875rem; /* 30px */

--text-4xl: 2.25rem; /* 36px */

--text-5xl: 3rem; /* 48px */

--font-weight-normal: 400;

--font-weight-medium: 500;

--font-weight-semibold: 600;

--font-weight-bold: 700;

--leading-tight: 1.25;

--leading-snug: 1.375;

--leading-normal: 1.5;

--leading-relaxed: 1.625;

```

Spacing Scale (8px Grid)

```css

--spacing-xs: 0.25rem; /* 4px */

--spacing-sm: 0.5rem; /* 8px */

--spacing-md: 1rem; /* 16px */

--spacing-lg: 1.5rem; /* 24px */

--spacing-xl: 2rem; /* 32px */

--spacing-2xl: 3rem; /* 48px */

--spacing-3xl: 4rem; /* 64px */

--spacing-4xl: 6rem; /* 96px */

--gap-xs: 0.25rem;

--gap-sm: 0.5rem;

--gap-md: 1rem;

--gap-lg: 1.5rem;

--gap-xl: 2rem;

--gap-2xl: 3rem;

```

Border Radius

```css

--radius-sm: 0.125rem; /* 2px */

--radius-md: 0.375rem; /* 6px */

--radius-lg: 0.5rem; /* 8px */

--radius-xl: 0.75rem; /* 12px */

--radius-2xl: 1rem; /* 16px */

--radius-full: 9999px; /* Fully rounded */

```

Shadows

```css

--shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);

--shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);

--shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);

--shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);

```

---

BEM Rules Enforced

Naming Convention

```css

.block {}

.block__element {}

.block--modifier {}

.block__element--modifier {}

```

**Block Naming**:

Lowercase only

Hyphens for word separation (e.g., `.product-card`, `.browse-cta`)

Describes component purpose

**Element Naming**:

Double underscore (`__`) separates block from element

Lowercase with hyphens (e.g., `.button__text`, `.card__header`)

**Modifier Naming**:

Double hyphen (`--`) separates block/element from modifier

Lowercase with hyphens (e.g., `.button--primary`, `.card--elevated`)

Existing BEM Blocks (Reference)

**Core Components**:

`.button` (Button.astro)

`.card` (Card.astro)

`.page-header` (PageHeader.astro)

`.navigation` (Navigation.astro)

`.browse-cta` (BrowseCTA.astro)

**Browse Components** (global.css):

`.browse-search`

`.browse-tags`

`.browse-grid`

`.browse-card`

`.browse-empty`

`.browse-pagination`

**Product Components**:

`.product-chat`

`.add-to-cart`

`.add-to-cart-modal`

`.product-documents-form`

`.document-list`

`.product-contributors`

`.price-breakdown`

`.status-editor`

`.status-badge`

`.revenue-preview`

`.royalty-breakdown`

`.product-files-form`

`.product-royalty-breakdown`

`.product-status-editor`

`.product-embeddable-toggle`

`.product-embedded-products`

**Document Components**:

`.document-chat`

**Interactive Components**:

`.confirm-dialog`

`.modal-overlay`, `.modal-content`, `.modal-header`, `.modal-body`

Prohibited Patterns

❌ **Strictly Forbidden**:

```css

/* NO Tailwind-style utilities */

.flex { display: flex; }

.text-center { text-align: center; }

.mt-4 { margin-top: 1rem; }

/* NO chained selectors (breaks BEM) */

.card .title { }

.button .icon { }

/* NO tag-qualified classes */

div.card { }

a.button { }

/* NO ID selectors */

#header { }

/* NO deep nesting beyond 2 levels */

.card__header__title__icon { } /* Too deep */

/* NO generic state classes without block context */

.is-active { } /* Use .button--active instead */

.has-error { } /* Use .input--error instead */

/* NO hardcoded colors/sizes (use design tokens) */

.card {

color: #333; /* ❌ Use var(--foreground) */

padding: 24px; /* ❌ Use var(--spacing-lg) */

border-radius: 8px; /* ❌ Use var(--radius-lg) */

}

```

Allowed Patterns

✅ **Correct Usage**:

```css

/* Flat class selectors with design tokens */

.card {

background-color: var(--card);

border: 1px solid var(--border);

border-radius: var(--radius-lg);

padding: var(--spacing-3xl);

}

/* Explicit block ownership */

.card__title {

font-size: var(--text-xl);

font-weight: var(--font-weight-semibold);

color: var(--card-foreground);

}

/* Boolean and value modifiers */

.button--primary { }

.button--lg { }

.card--elevated { }

/* Pseudo-states on BEM classes */

.button:hover { }

.button:focus-visible { }

.button:disabled { }

/* Global page utilities (limited exceptions) */

.page { }

.page__container { }

/* Third-party libraries (unmodifiable) */

.tiptap { }

.astro-* { }

```

---

Audit Process

1. Inventory Phase

Extract all class selectors from `.astro` and `.css` files

Map class usage across templates (Astro pages, SolidJS islands)

Identify design token violations (hardcoded colors, spacing, typography)

Detect duplicates and collisions

Find orphaned selectors (defined but not used)

2. Classification Phase

Each selector is categorized as:

**Block** (component root)

**Element** (component part)

**Modifier** (component variation)

**Global Utility** (allowed: `.page`, `.page__container`)

**Third-party** (allowed: `.tiptap`, `.astro-*`)

**Invalid** (Tailwind-style utilities, non-BEM patterns)

3. Violation Detection

**Naming Violations**:

Incorrect separator usage (`_` instead of `__`, `-` instead of `--`)

CamelCase or snake_case naming

Too-deep element nesting (`.block__element__subelement`)

**Design Token Violations**:

Hardcoded colors instead of `var(--primary)`, `var(--muted-foreground)`, etc.

Hardcoded spacing instead of `var(--spacing-*)` or `var(--gap-*)`

Hardcoded font sizes instead of `var(--text-*)`

Hardcoded border radius instead of `var(--radius-*)`

Hardcoded shadows instead of `var(--shadow-*)`

**Structural Violations**:

Cross-block element access (`.card .button__text`)

Tag-qualified classes (`div.button`)

ID selectors

Utility-first patterns (Tailwind-style)

4. Refactor Strategy

For each violation:

1. **Propose canonical BEM block name** (check existing blocks first)

2. **Replace hardcoded values with design tokens**

3. **Flatten selector structure** (convert nested to explicit elements)

4. **Normalize modifiers** (ensure `--` separator)

5. **Update markup** (Astro/TSX files) to match new class names

5. Design Token Compliance

Ensure all CSS uses design tokens:

```css

/* BEFORE (violations) */

.card {

color: #333;

background: #fff;

padding: 24px;

margin-bottom: 32px;

border-radius: 8px;

font-size: 18px;

box-shadow: 0 4px 6px rgba(0,0,0,0.1);

}

/* AFTER (compliant) */

.card {

color: var(--foreground);

background: var(--card);

padding: var(--spacing-lg);

margin-bottom: var(--spacing-xl);

border-radius: var(--radius-lg);

font-size: var(--text-lg);

box-shadow: var(--shadow-md);

}

```

6. Validation Phase

Ensure no orphaned selectors remain

Confirm visual intent preservation (run dev server, check pages)

Verify class usage consistency across Astro/SolidJS components

Check accessibility (focus states, ARIA compatibility)

---

Example Transformations

Example 1: Tailwind-style Utilities → BEM

**BEFORE (Violation)**:

```html

<h2 class="text-xl font-bold">Title</h2>

<p class="text-gray-600">Description</p>

</div>

<style>

.flex { display: flex; }

.gap-4 { gap: 1rem; }

.p-6 { padding: 1.5rem; }

.rounded-lg { border-radius: 0.5rem; }

.bg-white { background: white; }

.text-xl { font-size: 1.25rem; }

.font-bold { font-weight: bold; }

.text-gray-600 { color: #666; }

</style>

```

**AFTER (BEM Compliant)**:

```html

<h2 class="product-card__title">Title</h2>

<p class="product-card__description">Description</p>

</div>

<style>

.product-card {

display: flex;

gap: var(--gap-md);

padding: var(--spacing-lg);

border-radius: var(--radius-lg);

background: var(--card);

}

.product-card__title {

font-size: var(--text-xl);

font-weight: var(--font-weight-bold);

color: var(--card-foreground);

}

.product-card__description {

color: var(--muted-foreground);

}

</style>

```

Example 2: Nested Selectors → Flat BEM

**BEFORE (Violation)**:

```css

.card .header .title {

font-size: 20px;

}

.card.active {

border-color: blue;

}

.card .footer button {

padding: 12px 24px;

}

```

**AFTER (BEM Compliant)**:

```css

.card__title {

font-size: var(--text-xl);

}

.card--active {

border-color: var(--primary);

}

.card__footer-button {

padding: var(--spacing-sm) var(--spacing-lg);

}

```

```html

<h2 class="card__title">Title</h2>

</div>

<button class="card__footer-button">Action</button>

</div>

```

Example 3: Hardcoded Values → Design Tokens

**BEFORE (Violations)**:

```css

.product-card {

background: #ffffff;

color: #333333;

border: 1px solid #e0e0e0;

padding: 16px 24px;

margin-bottom: 32px;

border-radius: 8px;

font-size: 16px;

line-height: 1.5;

box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);

}

.product-card__title {

color: #000000;

font-size: 24px;

font-weight: 600;

margin-bottom: 8px;

}

.product-card__description {

color: #666666;

font-size: 14px;

line-height: 1.6;

}

.product-card:hover {

box-shadow: 0 4px 8px rgba(0, 0, 0, 0.15);

}

```

**AFTER (Design Token Compliant)**:

```css

.product-card {

background: var(--card);

color: var(--card-foreground);

border: 1px solid var(--border);

padding: var(--spacing-md) var(--spacing-lg);

margin-bottom: var(--spacing-xl);

border-radius: var(--radius-lg);

font-size: var(--text-base);

line-height: var(--leading-normal);

box-shadow: var(--shadow-sm);

}

.product-card__title {

color: var(--foreground);

font-size: var(--text-2xl);

font-weight: var(--font-weight-semibold);

margin-bottom: var(--spacing-sm);

}

.product-card__description {

color: var(--muted-foreground);

font-size: var(--text-sm);

line-height: var(--leading-relaxed);

}

.product-card:hover {

box-shadow: var(--shadow-md);

}

```

---

Component-Specific Patterns

Button Component Pattern

```css

/* Base button block */

.button {

display: inline-flex;

align-items: center;

justify-content: center;

padding: var(--spacing-sm) var(--spacing-lg);

border-radius: var(--radius-md);

font-size: var(--text-base);

font-weight: var(--font-weight-medium);

transition: background-color 150ms;

}

/* Variant modifiers */

.button--primary {

background-color: var(--primary);

color: var(--primary-foreground);

}

.button--secondary {

background-color: var(--secondary);

color: var(--secondary-foreground);

}

.button--destructive {

background-color: var(--destructive);

color: var(--destructive-foreground);

}

/* Size modifiers */

.button--sm {

padding: var(--spacing-xs) var(--spacing-md);

font-size: var(--text-sm);

}

.button--lg {

padding: var(--spacing-md) var(--spacing-xl);

font-size: var(--text-lg);

}

/* Elements */

.button__icon {

margin-right: var(--spacing-xs);

}

.button__text { }

/* States */

.button:hover {

opacity: 0.9;

}

.button:focus-visible {

outline: 2px solid var(--ring);

outline-offset: 2px;

}

.button:disabled {

opacity: 0.5;

pointer-events: none;

}

```

Modal Component Pattern

```css

.modal-overlay {

position: fixed;

inset: 0;

background: rgb(0 0 0 / 0.5);

display: flex;

align-items: center;

justify-content: center;

padding: var(--spacing-lg);

z-index: 50;

}

.modal-content {

background: var(--card);

border-radius: var(--radius-xl);

box-shadow: var(--shadow-xl);

max-width: 32rem;

width: 100%;

max-height: 90vh;

overflow-y: auto;

}

.modal-header {

display: flex;

justify-content: space-between;

align-items: center;

padding: var(--spacing-lg);

border-bottom: 1px solid var(--border);

}

.modal-title {

font-size: var(--text-xl);

font-weight: var(--font-weight-semibold);

color: var(--foreground);

}

.modal-close {

padding: var(--spacing-xs);

color: var(--muted-foreground);

}

.modal-close:hover {

color: var(--foreground);

}

.modal-body {

padding: var(--spacing-lg);

}

```

---

Accessibility Compliance

All CSS must support accessibility standards:

Focus States

```css

/* All interactive elements MUST have visible focus indicators */

.button:focus-visible,

.browse-tags__tag:focus-visible,

.navigation__link:focus-visible {

outline: 2px solid var(--ring);

outline-offset: 2px;

}

```

Color Contrast

Body text: 4.5:1 minimum contrast ratio

Large text: 3:1 minimum contrast ratio

UI components: 3:1 against adjacent colors

**All semantic color tokens meet WCAG 2.1 Level AA standards.**

Screen Reader Compatibility

```css

/* Hidden but accessible to screen readers */

.sr-only {

position: absolute;

width: 1px;

height: 1px;

padding: 0;

margin: -1px;

overflow: hidden;

clip: rect(0, 0, 0, 0);

white-space: nowrap;

border-width: 0;

}

/* Decorative elements should be hidden from screen readers via aria-hidden="true" */

/* No CSS-only hiding for interactive elements */

```

---

File Organization

CSS files must follow this structure:

```

src/

├── styles/

│ └── global.css # Global styles, shared .browse-* classes

├── components/

│ ├── Button.astro # <style> block in component

│ ├── Card.astro # <style> block in component

│ ├── products/

│ │ ├── ProductFilesForm.tsx # SolidJS component

│ │ ├── product-files-form.css # Co-located CSS

│ │ ├── ProductRoyaltyBreakdown.tsx

│ │ └── product-royalty-breakdown.css

```

**Rules**:

Astro components: Use `<style>` blocks in `.astro` files

SolidJS islands: Use co-located `.css` files with matching names

Shared browse styles: Use `.browse-*` classes in `global.css`

Page-specific styles: Use `<style>` blocks in page `.astro` files

---

Output Modes

Report Mode

Generates:

BEM compliance score (0-100%)

Design token compliance score (0-100%)

List of violations by severity (critical, high, medium, low)

Suggested renames and restructures

Hardcoded value inventory (colors, spacing, typography)

Unused selector report

Missing design token opportunities

Patch Mode

Generates:

Diff-style rename suggestions

Design token replacement mapping

Refactored selector examples

Migration mapping table (old → new)

Markup update requirements (`.astro` and `.tsx` files)

Auto-fix Mode

Generates:

Updated CSS files with BEM-compliant selectors

Design token replacements applied

Updated markup class names in Astro/TSX files

Migration notes for breaking changes

Before/after screenshots (if possible)

---

Safety & Constraints

**Never rename without updating all references** (search across `.astro`, `.tsx`, `.css`)

**Avoid visual regressions** - test in dev server before committing

**Preserve comments and documentation**

**Flag breaking changes clearly**

**Verify accessibility** - ensure focus states, contrast ratios, ARIA compatibility

**Test responsive behavior** - check mobile, tablet, desktop breakpoints

---

Success Criteria

✅ **Pass Conditions**:

All selectors follow valid BEM syntax (`.block__element--modifier`)

No cross-block coupling remains

No hardcoded colors, spacing, typography (all use design tokens)

No utility-first CSS patterns (Tailwind-style)

Reduced specificity and nesting

Clear, predictable class semantics

Accessibility standards maintained (focus states, contrast, ARIA)

Responsive design patterns preserved

---

Summary

This skill enforces Game Loopers' strict BEM architecture and design system compliance. It ensures:

1. **Consistent BEM naming** across all components

2. **Design token usage** for theming and maintainability

3. **No utility-first CSS** (Tailwind prohibition)

4. **Accessibility compliance** (WCAG 2.1 Level AA)

5. **Scalable architecture** for long-term maintenance

This is critical for a product-market fit focused MVP where consistency and maintainability enable rapid iteration.

audit-style

Game Loopers CSS BEM Audit & Refactor Skill

Skill Name

Purpose

Scope

Design System Reference

Color System (CSS Custom Properties)

Typography Scale

Spacing Scale (8px Grid)

Border Radius

Shadows

BEM Rules Enforced

Naming Convention

Existing BEM Blocks (Reference)

Prohibited Patterns

Allowed Patterns

Audit Process

1. Inventory Phase

2. Classification Phase

3. Violation Detection

4. Refactor Strategy

5. Design Token Compliance

6. Validation Phase

Example Transformations

Example 1: Tailwind-style Utilities → BEM

Example 2: Nested Selectors → Flat BEM

Example 3: Hardcoded Values → Design Tokens

Component-Specific Patterns

Button Component Pattern

Modal Component Pattern

Accessibility Compliance

Focus States

Color Contrast

Screen Reader Compatibility

File Organization

Output Modes

Report Mode

Patch Mode

Auto-fix Mode

Safety & Constraints

Success Criteria

Summary

Reviews (0)