AI Collaboration for CSS Architecture
AI tools (Claude, ChatGPT, Cursor, Copilot) are most powerful when they know your system. Raw prompts produce generic, inconsistent CSS. Contextual prompts — where you've given the AI your methodology, tokens, and conventions — produce production-ready output that slots directly into your architecture.
1. The Core Principle: Give AI Your System First
AI doesn't know which methodology you're using, what your token names are, or how you prefer to name classes. The single biggest improvement to AI output is providing your project context upfront.
The Project Context Block (Copy–Paste This Every Session)
I'm working on a CSS project using this architecture:
- Methodology: BEM + SMACSS states (is-* / has-*)
- Layer approach: ITCSS with CSS @layer
- Prefix system: o- objects, c- components, u- utilities, l- layout, is-/has- states, js- JS hooks
- Naming: .c-block__element--modifier (always kebab-case)
My design tokens:
[PASTE YOUR :root BLOCK HERE]
Rules for all output:
- No inline styles
- No hardcoded hex colors — use CSS variables only
- No !important except in utilities (u-) classes
- JS events use js- prefixed classes (no CSS on js- classes)
- State changes use is-* or has-* classes toggled by JS
- Output clean HTML + separate CSS block — never combined
[!TIP] Save this context block as an Espanso snippet (
:cssctx→ expands to the whole block). Load it at the start of every AI session to get consistent, methodology-compliant output.
2. AI as Component Architect
Use AI to design the entire BEM structure of a component before writing CSS. This is the planning phase.
Prompt: Generate BEM Architecture Plan
Plan the BEM structure for a [COMPONENT NAME] component.
Context: [PASTE PROJECT CONTEXT BLOCK]
The component should:
- [DESCRIBE VISUAL DESIGN]
- [LIST INTERACTIVE STATES]
- [LIST VARIANTS NEEDED]
For each part, output:
1. Block name (.c-block)
2. All elements (.c-block__element)
3. All block modifiers (.c-block--modifier)
4. All element modifiers (.c-block__element--modifier)
5. Which states should be is-* vs BEM modifier
6. Which classes need js- hooks
Do NOT write CSS yet — just the naming plan in a structured list.
Example Output AI Might Give:
Component: Notification Toast
Block: .c-toast
Elements:
.c-toast__icon — Left icon
.c-toast__body — Text content area
.c-toast__title — Bold heading
.c-toast__message — Body text
.c-toast__close — Close button
.c-toast__progress — Auto-dismiss progress bar
Block Modifiers:
.c-toast--success — Green variant
.c-toast--danger — Red variant
.c-toast--warning — Yellow variant
.c-toast--info — Blue/purple variant
States (is-):
.is-visible — Toast is on screen (JS-animated in)
.is-dismissing — Exit animation triggered
JS Hooks:
.js-toast-close — Bound to close button click
.js-toast-container — Dynamic toast injection point
3. AI as CSS Generator (Methodology-Compliant)
Once you have the plan, AI writes the CSS:
Prompt: Generate Component CSS
Write the complete CSS for the .c-toast component.
Architecture rules: [PASTE PROJECT CONTEXT BLOCK]
BEM structure agreed:
Block: .c-toast
Elements: .c-toast__icon, .c-toast__body, .c-toast__title, .c-toast__message, .c-toast__close, .c-toast__progress
Modifiers: .c-toast--success, .c-toast--danger, .c-toast--warning, .c-toast--info
States: .is-visible, .is-dismissing
Visual specifications:
- Fixed position: bottom-right corner, stack vertically
- Width: 360px max
- Glass effect background with backdrop-filter
- Progress bar at bottom shows time remaining
- Slide-in from right, fade out on dismiss
- Each variant uses a different accent color
Output format:
1. HTML structure (one example toast)
2. CSS (organized: block → elements → modifiers → states → animations)
3. A comment header block with block name, elements list, modifiers list
4. AI as Architecture Reviewer
Paste your CSS and ask AI to review it against your methodology:
Prompt: Methodology Compliance Review
Review this CSS for BEM + ITCSS compliance.
My architecture rules:
- BEM naming: .c-block__element--modifier
- ITCSS prefixes: o- objects, c- components, u- utilities
- No hardcoded colors — CSS variables only
- No descendant selectors deeper than 2 levels
- No ID selectors
- State classes use is-* prefix
- No !important outside utilities
CSS to review:
[PASTE YOUR CSS]
For each violation, show:
1. The problematic line
2. The rule it violates
3. The corrected version
Prompt: Specificity Audit
Audit this CSS file for specificity problems.
[PASTE CSS]
For each selector:
1. Calculate its specificity score (A,B,C)
2. Flag any selector above (0,2,0)
3. Identify any !important usage
4. Identify ID selectors (#id)
5. Suggest a lower-specificity alternative for each flagged rule
Output as a table: | Selector | Score | Problem | Fix |
5. AI as Refactoring Assistant
Use AI to modernize legacy CSS one component at a time:
Prompt: Legacy CSS → BEM Refactor
Refactor this legacy CSS to BEM methodology.
Legacy CSS:
[PASTE LEGACY CSS]
The HTML context it styles:
[PASTE HTML]
My token system:
[PASTE :root BLOCK]
Rules:
- All classes become .c-[component]__[element] or .c-[component]--[modifier]
- Replace all hardcoded values with CSS tokens
- Eliminate descendant selectors — use BEM elements instead
- Replace location-dependent styles with modifiers
- Replace JS-toggled classes with is-* states
Output:
1. New HTML (updated class names)
2. New CSS (BEM-structured)
3. Migration notes (what changed and why)
Prompt: Identify Magic Numbers
Find every "magic number" in this CSS — hardcoded values that
should be CSS custom properties.
[PASTE CSS]
For each magic number:
1. The property and value
2. How many times it appears
3. Suggested token name (following this format: --[category]-[name])
4. The :root declaration to add
Output: Complete :root block with all new tokens,
then the CSS with all values replaced.
6. AI as ITCSS File Organizer
Use AI to sort unorganized CSS into the correct ITCSS layers:
Prompt: ITCSS Layer Sorting
Sort these CSS rules into the correct ITCSS @layer.
ITCSS layers to use (in order, lowest to highest priority):
1. @layer reset — Universal reset and box-sizing
2. @layer elements — Bare HTML element defaults (no classes)
3. @layer objects — Structural layout patterns (.o- prefix)
4. @layer components — Styled UI components (.c- prefix)
5. @layer utilities — Single-purpose overrides (.u- prefix)
CSS to sort:
[PASTE CSS]
Output:
@layer reset { ... }
@layer elements { ... }
@layer objects { ... }
@layer components { ... }
@layer utilities { ... }
For anything you're unsure about, add a comment: /* REVIEW: reason */
7. AI as Naming Decision Helper
Stuck on naming a BEM class? Ask AI:
Prompt: BEM Name Decision
I need a BEM name for this element. Help me choose.
Component I'm building: [DESCRIBE COMPONENT]
The specific element I need to name: [DESCRIBE THE ELEMENT]
My existing BEM names for this block:
Block: .c-[current-block]
Elements: [list existing elements]
Suggest 3 candidate names following .c-block__element convention.
For each, explain:
1. What the name communicates
2. Potential conflict or confusion
3. Your recommendation and why
My naming conventions:
- Always kebab-case
- Descriptive of role/purpose, not visual appearance
- Short but unambiguous (max 3 words in the name)
8. AI as State-Change Planner
For complex interactive components, use AI to map all state transitions:
Prompt: Component State Map
Map all CSS states for this component using SMACSS is-/has- convention.
Component: [DESCRIBE THE COMPONENT]
Interactions it supports: [LIST USER ACTIONS]
For each state:
1. What triggers it (user action or JS event)
2. The is-* or has-* class name
3. The CSS properties that change in this state
4. Which element the class is applied to
5. Whether it's additive (show something) or subtractive (hide something)
Then output:
- HTML template with all possible state class slots shown
- CSS state rules in SMACSS format
- A JavaScript snippet that toggles each state correctly
9. AI as Token System Designer
Start a new project with AI generating a complete design token system:
Prompt: Generate Design Token System
Generate a complete CSS custom property token system for a [PROJECT TYPE].
Design direction: [DESCRIBE THE AESTHETIC: dark/light, minimal/rich, corporate/creative]
Brand color hint: [HEX OR DESCRIPTION]
Generate tokens for:
1. Color palette (using OKLCH — include hue, chroma, lightness for each)
2. Semantic colors (primary, secondary, danger, success, warning, text, muted, bg, surface, border)
3. Typography scale (fluid, using clamp() for each step)
4. Font families (recommend 2 Google Fonts that match the aesthetic)
5. Spacing scale (4px base, powers of 2)
6. Border radius scale
7. Shadow system (3-4 levels)
8. Motion/animation tokens (duration + easing)
9. Z-index scale
Output: Complete :root { } block, production-ready.
Follow semantic naming: --color-primary, not --purple-600.
10. AI as Sass Architecture Generator
Have AI scaffold the entire Sass 7-1 file structure:
Prompt: Generate Sass 7-1 Scaffold
Generate the complete Sass 7-1 project scaffold for a WordPress child theme.
Project: [DESCRIBE PROJECT]
Methodology: ITCSS + BEM + SMACSS states
Prefix system: o- l- c- u- is- has- js-
Generate:
1. Full folder/file structure (all 11 folders + main.scss)
2. Complete abstracts/_variables.scss (Sass variables for breakpoints, z-index maps)
3. Complete abstracts/_mixins.scss (respond-to, focus-ring, line-clamp, glass, fluid-type)
4. Complete abstracts/_index.scss (@forward all)
5. base/_reset.scss (modern CSS reset)
6. base/_typography.scss (heading, paragraph, link defaults using CSS tokens)
7. main.scss (complete @use statements in correct order)
8. functions.php snippet to enqueue compiled CSS
9. package.json scripts (css:watch, css:build)
Use these design tokens: [PASTE :root BLOCK]
11. Session Workflow: AI Architecture Sprint
A repeatable workflow for starting a new component with AI collaboration:
Sprint Protocol (30–60 minutes per component)
Step 1: PLAN (5 min)
Prompt: "Plan the BEM structure for .c-[component]. [describe needs]"
Output: Agreed class names list
Action: Review and confirm naming — this is YOUR decision, AI suggests
Step 2: DESIGN TOKENS (5 min)
Prompt: "Do I need any component-scoped tokens for .c-[component]?
My global tokens are: [paste :root]"
Output: Any --c-component-* scoped tokens
Action: Add agreed tokens to :root or component CSS
Step 3: GENERATE (15 min)
Prompt: "Write HTML + CSS for .c-[component] using agreed structure.
Rules: [paste context block]. Tokens: [paste :root]"
Output: Full HTML + CSS
Action: Paste into your file
Step 4: REVIEW (5 min)
Prompt: "Review this CSS for BEM compliance and CSS token usage: [paste output]"
Output: Any violations flagged
Action: Fix violations
Step 5: STATE MAP (5 min — if interactive component)
Prompt: "Map is-* states and write the JS toggle code for .c-[component]"
Output: State CSS + JS
Action: Add to _states.css and your JS file
Step 6: DOCUMENT (5 min)
Prompt: "Write a CSS comment header for .c-[component] listing
all elements, modifiers, states, and js- hooks"
Output: Documentation comment block
Action: Paste at top of component file
12. Prompt Templates for Recurring Tasks
Daily Use Prompts (Save as Espanso Snippets)
:cssnew — New component
Build .c-[COMPONENT] using BEM + SMACSS states.
My tokens: [PASTE :root]
Rules: o-/c-/u-/l-/is-/has-/js- prefix system. No hardcoded colors. Pure CSS variables.
The component needs: [DESCRIBE]
Output: HTML + CSS block (no inline styles, no !important except utils).
:cssreview — Review output
Review this CSS for: 1) BEM naming compliance 2) token usage (no hardcoded colors) 3) specificity (flag >0,2,0) 4) !important outside utilities 5) descendant selectors >2 levels.
CSS: [PASTE]
:cssrefactor — Legacy refactor
Refactor to BEM. Map hardcoded values to my tokens: [PASTE :root].
Eliminate descendant selectors. Add is-* states for JS-toggled properties.
Legacy CSS: [PASTE]
HTML: [PASTE]
:cssname — BEM naming help
Suggest 3 BEM names for this element.
Block: .c-[block]. Element: [DESCRIBE]. Existing elements: [LIST].
Must be: kebab-case, descriptive of role not appearance, max 3 words.
:csstoken — Add a new token
I want to add a CSS token for [VALUE/CONCEPT].
My existing token system: [PASTE :root].
Suggest: 1) Token name following my convention, 2) Where in :root it belongs,
3) Other places this value appears that should use the new token.
13. Anti-Patterns in AI Collaboration
What AI Gets Wrong (Know to Fix It)
| AI Tendency | The Problem | How to Fix |
|---|---|---|
Uses hardcoded colors (#6c63ff) | Breaks token system | Add to prompt: "No hardcoded colors — CSS variables only" |
| Writes inline styles | Breaks methodology | Add: "No inline style="" attributes" |
| Creates overly specific selectors | Specificity war | Add: "Max selector depth: 2 levels" |
| Uses !important everywhere | Cascade corruption | Add: "No !important except in .u- utilities" |
| Mixes BEM and utility classes arbitrarily | Inconsistency | Add: "BEM for components, utilities only for single-property overrides" |
Creates --modifier--modifier names | Invalid BEM | Add: "Apply modifiers as separate classes, never compound modifiers" |
Generates js- classes WITH CSS | Breaks abstraction | Add: "js- classes have ZERO CSS properties" |
Uses vague state names (.active, .open) | No SMACSS prefix | Add: "States use is-* or has-* prefix exclusively" |
Numbers classes (.card-1, .card-2) | Not methodology | Add: "No numbered class names — use modifiers" |
| Wraps everything in one giant class | Breaks ITCSS | Add: "Separate objects (structure) from components (skin)" |
14. AI + Docusaurus: Keeping Your Docs in Sync
When you create a new component, ask AI to:
Prompt: Generate Component Documentation Page
Generate a Docusaurus MDX documentation page for this CSS component.
Component CSS: [PASTE CSS]
Component HTML: [PASTE HTML]
The page should include:
1. Frontmatter (title, sidebar_position)
2. Overview paragraph (what it is, when to use it)
3. HTML structure with class annotations
4. Complete CSS (in a code block)
5. All variants shown with HTML + description
6. All states shown with HTML + JS toggle code
7. Accessibility notes (focus, aria attributes)
8. WordPress usage notes (if applicable)
9. A quick reference table: class → purpose
Format: MDX with code blocks, tables, and > [!TIP] alerts where helpful.
This keeps your Docusaurus CSS curriculum up-to-date as you build new components — the documentation writes itself.