Project structure

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

• spacing.css — The foundational --line variable and all spacing tokens
• typography-base.css — Font stacks, weights, measures
• typography-scale-auto.css — Fluid type scale (ratio-based, Utopia-style)
• typography-scale-manual.css — Fluid type scale with manual minimum and maximum font sizes and baselines
• color.css — Color palette and schemes
• borders.css — Border radius tokens
• animation.css — Timing and easing tokens

2_tools/ — CSS tools

• properties.css — @property definitions for type-safe custom properties
• typography-scale-auto.css — Type scale calculations for auto mode
• typography-scale-manual.css — Type scale calculations for manual mode

3_generic/ — Reset

Modern CSS reset with sensible defaults to prepare for more predictable and consistent styling.

4_elements/ — Base element styles

• document.css — Root and body setup
• typography.css — Headings, paragraphs, code
• links.css — Link styles
• lists.css — List styles
• tables.css — Table defaults
• forms.css — Form elements
• media.css — Images and figures
• quotes.css — Blockquotes and smart quotes
• details.css — Disclosure widgets
• hr.css — Horizontal rules
• addresses.css — Address element
• nav.css — Nav element

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>

• stack.css — Vertical spacing
• cluster.css — Horizontal grouping with wrapping
• grid.css — Auto-responsive grid
• sidebar.css — Sidebar + main content
• center.css — Centered content with max-width
• box.css — Padding container
• section.css — Section wrapper (with container queries)
• cover.css — Full-height centering

See Layout primitives documentation for full usage.

6_components/ — UI components

• buttons.css — Button variants
• breadcrumbs.css — Breadcrumb navigation
• pagination.css — Page navigation
• tables.css — Enhanced table styles
• switches.css — Toggle switches
• dividers.css — Horizontal dividers
• images.css — Image treatments
• embeds.css — Responsive media embeds
• typography.css — Enhanced typography rules
• logo.css — Logo sizing

7_utilities/ — Utility classes

• spacing.css — Margin and padding
• typography.css — Text styling
• color.css — Colors and schemes
• display.css — Display and visibility
• flexbox.css — Flexbox utilities
• grid.css — Grid utilities
• sizing.css — Width and height
• borders.css — Border utilities
• media.css — Object-fit, filters, blend modes
• tables.css — Table column widths

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