Project structure

How Live Wires is organized and where everything lives.

Directory overview

livewires/
├── src/
│   ├── css/                  # All CSS source files
│   │   ├── 0_config/         # Cascade layer definitions
│   │   ├── 1_tokens/         # Design tokens
│   │   ├── 2_tools/          # CSS functions & properties
│   │   ├── 3_generic/        # Reset
│   │   ├── 4_elements/       # Base HTML element styling
│   │   ├── 5_layouts/        # Layout primitives
│   │   ├── 6_components/     # UI components
│   │   ├── 7_utilities/      # Utility classes
│   │   ├── main.css          # Entry point
│   │   ├── print.css         # Print styles
│   │   └── prototyping.css   # Dev tools (baseline grid, etc.)
│   └── js/
│       ├── main.js           # Vite entry point
│       ├── html-include.js   # Include Web Component
│       └── prototyping.js    # Prototyping utilities
├── public/                   # Your prototype (site root)
│   ├── index.html            # Your pages
│   ├── _includes/            # HTML fragments (header, footer, nav)
│   ├── docs/                 # Technical documentation
│   ├── manual/               # Style guide & component library
│   ├── example/              # Example editorial site
│   │   └── _components/      # Reusable HTML patterns
│   ├── fonts/                # Web fonts
│   └── img/                  # Images
├── extras/                   # Optional extras (skills, etc.)
├── vite.config.js            # Vite configuration
├── postcss.config.js         # PostCSS (autoprefixer only)
└── package.json              # Dependencies

To top

CSS architecture

CSS is organized using ITCSS (Inverted Triangle CSS) principles with CSS Cascade Layers for explicit specificity control.

The cascade layers

Defined in 0_config/layers.css:

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

This ensures utilities always win over components, components over layouts, and so on. No !important needed.

Layer breakdown

0_config/:Configuration
Cascade layer definitions. The foundation that makes everything else work.
1_tokens/:Design tokens
2_tools/:CSS tools
3_generic/:Reset
Modern CSS reset with sensible defaults to prepare for more predictable and consistent styling.
4_elements/:Base element styles
5_layouts/:Layout primitives

All layout primitives follow the base + modifier pattern. The base class provides core behavior and sets CSS custom properties; modifiers only override specific variables. Always use both:

<div class="stack stack-compact">...</div>
<section class="section section-wide">...</section>

See Layout primitives documentation for full usage.

6_components/:UI components
7_utilities/:Utility classes

To top

JavaScript

Minimal JavaScript. Just what's needed for the development environment and HTML includes.

/src/js/main.js
Vite entry point. Loads CSS and initializes Web Components.
/src/js/html-include.js
Zero-dependency Web Component for including HTML fragments. See HTML includes documentation.
/src/js/prototyping.js
Development utilities: keyboard shortcuts for baseline grid, column overlays, and dark mode toggle.

To top

Public folder

The /public/ folder is your site root. Everything in here is your prototype.

/public/index.html
Your homepage and any other pages you create.
/public/_includes/
Reusable HTML fragments (header, footer, navigation) loaded via <html-include>. Easy to convert to any CMS templating system.
/public/fonts/
Web font files. Reference them in 1_tokens/typography-base.css.
/public/img/
Images and graphics for your prototype.
/public/docs/
Technical documentation for Live Wires itself.
/public/manual/
Style guide and component library. Contains brand identity, component documentation, and usage examples.
/public/example/
A complete example editorial site demonstrating Live Wires in action.
  • _components/:Reusable HTML patterns (article teasers, etc.) loaded via <html-include>
  • _includes/:Site-specific includes (header, navigation)
  • article/:Example article pages

To top

Configuration files

vite.config.js
Vite configuration. Sets /public/ as root, configures dev server on port 3000.
postcss.config.js
PostCSS configuration. Only uses Autoprefixer. No other processing.
package.json
Project dependencies. Just Vite, Autoprefixer, and the static copy plugin for print styles.

To top