livewires

Live Wires CSS Framework

Philosophy

Good defaults + additive art direction. Semantic HTML looks good with zero classes. Utility classes provide precise control for art direction.

Nothing gets thrown away. The prototype becomes the product. Every step builds on the last.

---

CRITICAL: Prototyping Mindset

DO NOT Create New CSS Classes

Live Wires has comprehensive layout primitives and utilities. Never invent new class names. If you think you need a new class, you're probably:

• Missing an existing utility (check the reference files)
• Over-engineering the solution
• Not trusting the defaults

<!-- WRONG: Inventing classes -->
<div class="hero-container">
<div class="article-meta-wrapper">
<p class="subtitle-text">

<!-- RIGHT: Use existing primitives -->
<div class="cover">
<div class="cluster">
<p class="lead">

Minimal Styling During Prototyping

Prototyping is about structure and content, not visual polish. Resist the urge to over-style.

Headlines: Let the semantic HTML work. <h1> through <h6> have good defaults. Only add size utilities (text-4xl, etc.) when there's a specific design reason.

<!-- WRONG: Over-styled headline -->
<h1 class="text-6xl font-bold text-center mb-4 leading-tight">Article Title</h1>

<!-- RIGHT: Trust the defaults -->
<h1>Article Title</h1>

Spacing: Layout primitives handle spacing. Don't manually add mt-*, mb-*, py-* everywhere.

<!-- WRONG: Manual spacing chaos -->
<section class="py-6">
  <h2 class="mb-4">Section Title</h2>
  <p class="mb-2">Paragraph one.</p>
  <p class="mb-2">Paragraph two.</p>
</section>

<!-- RIGHT: Let stack handle it -->
<section class="section">
  <h2>Section Title</h2>
  <p>Paragraph one.</p>
  <p>Paragraph two.</p>
</section>

Supporting text: Use .lead for intro paragraphs. Otherwise, let paragraph defaults work.

<!-- WRONG: Over-styled supporting text -->
<p class="text-lg text-muted font-light leading-relaxed">Introduction to the article.</p>

<!-- RIGHT: Semantic and minimal -->
<p class="lead">Introduction to the article.</p>

Page Types, Not Individual Pages

Think like a rapid prototyper. Build reusable page templates, not a page for every piece of content.

BAD approach:

/users/john-profile.html
/users/jane-profile.html
/users/bob-profile.html
/articles/article-one.html
/articles/article-two.html

GOOD approach:

/users/show.html        ← User profile template
/users/edit.html        ← User edit template
/articles/show.html     ← Article template
/articles/index.html    ← Article listing template

When building a prototype:

1. Identify the page types (list, detail, form, dashboard, etc.)
2. Build one template per type with realistic placeholder content
3. Reuse templates - don't duplicate for each item
4. Use the same edit page for create and edit flows

The Prototyping Test

Before adding any class, ask:

1. Does semantic HTML already handle this? → Use no class
2. Does a layout primitive handle this? → Use .stack, .grid, .section, etc.
3. Is this a scheme/theme concern? → Use .scheme-*
4. Is this specific art direction? → Only then use utilities

Goal: The cleanest possible HTML that's ready for styling later.

---

The Design Process

Live Wires follows a sculptural approach—start with raw material, shape the form, refine the details, add expression.

Step 1: Prototype in HTML

Build page templates using semantic HTML and layout primitives in the public/ folder. Your prototype is instantly viewable in real browsers across devices.

Step 2: Set Your Tokens

Adjust design tokens (colors, typography, spacing) in src/css/1_tokens/. Watch the Manual transform in real time.

Step 3: Refine and Express

Expand your CSS. Add utility classes for art direction. Refine components. Each iteration takes you from coarse to detailed.

Step 4: Apply to Production

Connect your templates to your CMS or framework. Your prototype becomes the product.

---

Quick Reference

Supporting Files

For detailed reference, see these files in the same directory:

• layouts.md — Stack, Grid, Cluster, Sidebar, Center, Section, Cover, Box, Reel, Imposter
• components.md — Dialogs, Popups, Status Indicators, Badges, Progress Bars
• utilities.md — Typography, Spacing, Color Schemes, Container Queries
• patterns.md — Article Structure, Hero, Statistics Grid, Responsive Picture
• theming.md — Visual transformation workflow, color scales, typography, accessibility
• code-style.md — CUBE CSS mapping, data-* state patterns, class/attribute ordering, inline styles, schemes, placeholders
• qa-testing.md — QA testing system for prototypes

---

Typographic Foundations

Live Wires' typography system implements principles from the Design Machines typography skill -- fluid scaling, modular scales, progressive line-height, and vertical rhythm rooted in Müller-Brockmann, Bringhurst, Brown, and Latin. For the why behind these decisions (measure rules, typeface selection, evaluation frameworks), load the typography skill from the design-practice plugin.

The Typography Triplet

When using var(--text-XX) directly in CSS, you MUST apply all three properties together. The .text-* utility classes do this automatically, but custom CSS often misses the line-height and tracking.

/* WRONG: font-size alone */
.component-title {
  font-size: var(--text-2xl);
}

/* RIGHT: complete triplet */
.component-title {
  font-size: var(--text-2xl);
  line-height: var(--line-height-2xl);
  letter-spacing: var(--tracking-2xl);
}

The scales share suffixes (xs through 9xl). Line-heights use progressive ratios: 1.5 for body sizes (xs to base), 1.3 for heading sizes (lg to 2xl), and 1.0 for display sizes (3xl to 9xl). Tracking goes from slightly positive (small text) to negative (large display text).

When in doubt, use the utility class (.text-2xl) instead of the variable. Only use the variable when you need to set font-size inside a component or element rule.

---

The Sacred Baseline System

All spacing derives from --line. Use --line-* tokens for spacing:

--line-0, --line-025, --line-05, --line-075, --line-1, --line-15, --line-2, --line-3, --line-4, --line-5, --line-6, --line-7, --line-8, --line-1px

CUBE CSS Methodology

Live Wires uses CUBE CSS by Andy Bell — a methodology that embraces the cascade rather than fighting it.

CUBE stands for Composition, Utility, Block, Exception. Compositions are layout primitives (single-dash variants). Blocks are components (double-dash variants). Utilities are single-purpose classes. Exceptions are state changes via data-* attributes. See code-style.md for the full layer mapping table.

The key insight: Most styling is handled by global defaults and utilities. By the time you reach "blocks" (components), there's minimal work left. This is why inventing new component classes is almost always wrong — the answer is usually a layout primitive, a utility, or a scheme.

CSS Cascade Layers

@layer tokens, reset, base, layouts, components, utilities;

Utilities always win over components, components over layouts, etc. No !important needed — cascade layers handle specificity.

Modern CSS Features

Live Wires uses native CSS only — no preprocessors. Key features: cascade layers, native nesting (& syntax), container queries, logical properties (margin-block-start not margin-top), fluid typography via clamp(), and custom properties throughout. PostCSS config is autoprefixer only.

---

CSS Nesting Over BEM Child Selectors

BEM __ child element selectors are an anti-pattern in Live Wires. Native CSS nesting makes them unnecessary.

/* WRONG: BEM child element selectors */
.card__title { font-weight: bold; }
.card__body { padding: var(--line-1); }
.card__footer { border-top: var(--line-1px) solid var(--color-border); }

/* RIGHT: CSS nesting inside the block */
.card {
  & .title { font-weight: bold; }
  & .body { padding: var(--line-1); }
  & footer { border-top: var(--line-1px) solid var(--color-border); }
}

Double-dash modifiers (--variant) are still correct for component variants:

.card--featured { border: 2px solid var(--color-accent); }  /* correct */
.card__featured { }  /* wrong — this is a child selector, not a variant */

In HTML templates: Child elements don't need the parent class prefix. CSS nesting scopes them. Keep names short:

<!-- WRONG: BEM in HTML -->
<div class="workspace-switcher">
  <summary class="workspace-switcher__trigger">
  <div class="workspace-switcher__menu">
    <li class="workspace-switcher__item workspace-switcher__item--current">

<!-- RIGHT: Short names, styled via nesting in CSS -->
<div class="workspace-switcher">
  <summary class="cluster cluster-compact">
  <div class="menu box">
    <li class="item--current">

Use semantic element selectors where the element is unique in context (e.g., summary inside details, caption inside a table). Only add a class when the element selector is ambiguous.

---

When to Write New Component CSS

Before writing any CSS, work through this decision tree in order:

1. Layout/flow problem? → Use a primitive (.stack, .cluster, .grid, .sidebar, .box)
2. Color/theme problem? → Use a scheme (.scheme-accent, .scheme-subtle)
3. One-off override? → Use a utility (.text-sm, .font-semibold, .text-muted)
4. State change? → Use a data attribute (data-state="active", data-open)
5. Truly unique structure that repeats 3+ times? → Write a minimal CSS component

<!-- WRONG: Writing custom CSS for what's already a primitive -->
<style>
  .co-op-list { display: flex; flex-direction: column; gap: var(--line-1); }
</style>
<div class="co-op-list">

<!-- RIGHT: Use the primitive -->
<div class="stack">

---

State with Data Attributes (Exceptions)

State changes use data-* attributes, NOT CSS classes. This is the Exception layer in CUBE CSS.

/* WRONG: state as CSS classes */
.nav-link.active { color: var(--color-accent); }
.nav-link.is-active { color: var(--color-accent); }
.button.disabled { opacity: 0.5; }

/* RIGHT: state as data attributes */
.nav-link {
  &[data-state="active"] {
    color: var(--color-accent);
    font-weight: var(--font-semibold);
  }
}
.button {
  &[data-state="disabled"] {
    opacity: 0.5;
    cursor: not-allowed;
    pointer-events: none;
  }
}

Named states for multi-value state: [data-state="active"], [data-state="loading"], [data-state="error"], [data-state="disabled"]

Boolean states for simple on/off: [data-open], [data-active], [data-expanded], [data-hidden]

<!-- Boolean state -->
<nav class="offcanvas" data-open>...</nav>

<!-- Named state -->
<a href="/" class="nav-link" data-state="active">Home</a>

Why data attributes over classes:

• Semantic: State is data, not styling
• JS-friendly: element.dataset.state = 'active' is cleaner than classList
• Queryable: document.querySelectorAll('[data-state="active"]')
• Explicit: Clear separation between structural classes and state

---

Best Practices

1. Start with semantic HTML -- it looks good with zero classes
2. Add layout primitives first: .stack, .grid, .cluster, .center
3. Add utilities for art direction
4. Use CSS nesting (&) for child elements -- never BEM __ child selectors
5. Use --line-* tokens -- never arbitrary pixel values
6. Use container queries (@md, @lg) over viewport media queries
7. Use HTML entities: —, ·, £
8. Use existing token variables (--color-fg, --color-subtle, --line-*) directly rather than creating component-specific custom properties (--card-bg, --card-text-color) unless you need scheme-context overrides or external theming hooks
9. Use data-* attributes for state -- never .is-active, .active, or .disabled classes
10. Order classes: layout/composition, then block/component, then variant, then utilities

    <section class="stack box callout callout--featured scheme-warm mt-4">
    

11. Order HTML attributes: class, id, data-, src/href/for, type/name/value, aria-/role

---

Documentation Sync Requirement

CRITICAL: When modifying Live Wires CSS or adding new features, you MUST update documentation across the full ecosystem.

Documentation Locations

All paths are relative to the livewires repo root unless noted.

Location	What lives here
CLAUDE.md	Primary technical reference for Claude Code
README.md	User-facing project overview
public/manual/components/	Visual component guides (22 HTML pages)
public/reference/components/	Raw HTML examples -- canonical source for templ components
public/reference/layouts/	Layout primitive HTML examples
public/reference/forms/	Form reference HTML examples
public/docs/	Framework documentation (getting started, theming, typography, etc.)
This file (SKILL.md)	Plugin skill definition (depot repo)
livewires-templ repo	Go/Templ component library -- must match reference HTML

After Any Code Change, Update:

Change Type	Files to Update
Layout primitives/variants	CLAUDE.md, this file, public/reference/layouts/, public/manual/components/layout.html, public/docs/ if applicable
Utility classes	CLAUDE.md, this file
Tokens (--line-*, --text-*)	CLAUDE.md, this file, README.md
Components	CLAUDE.md, public/manual/components/, public/reference/components/, livewires-templ if component exists there
Forms	CLAUDE.md, public/reference/forms/, livewires-templ form/ package
File structure	CLAUDE.md, README.md

Naming Conventions (MUST follow):

• Layout modifiers: single-dash (stack-compact, box-tight, sidebar-reverse)
• Component modifiers: double-dash (button--red, badge--success)
• Spacing tokens: --line-* pattern
• Typography: Tailwind-style (text-xs, text-sm, text-lg, text-2xl, etc.)

---

Companion Skills

Skill	Plugin	When to Load
typography	design-practice	Typographic theory behind Live Wires' type scale and rhythm
layout	design-practice	Grid and editorial layout philosophy
development	assembly	When building Assembly pages using Live Wires
wcag-audit-patterns	accessibility-compliance	Accessibility auditing for Live Wires markup

Ecosystem Integration

Official and third-party Claude Code plugins that complement this skill:

Plugin	Tool	When to Use
compound-engineering	css-reviewer agent	Automated CSS compliance and best practices checking
frontend-design	Frontend skills	UI/UX implementation guidance
figma	Design context tools	Extract design tokens and specs from Figma
playwright	Browser tools	Visual regression testing of components