# Volt CSS A classless CSS stylesheet for elegant, readable web documents. Drop it into any HTML page for instant, semantic styling without touching a single class name. ## Philosophy Volt CSS embraces semantic HTML5 and lets the content structure define the presentation. Inspired by academic typography and modern web design, it creates documents that are beautiful, accessible, and optimized for reading. ### Core Principles - **Classless**: Style semantic HTML elements directly. - **Accessible**: WCAG AA contrast ratios, keyboard navigation support, and semantic HTML patterns - Optimized line lengths, modular type scale, and whitespace optimized for reading - Automatic light and dark modes via `prefers-color-scheme` - Mobile-first (ish) design that doesn't compromise readability ## Inspiration Volt CSS synthesizes ideas from several excellent classless CSS frameworks: - **magick.css**: Tufte-style [sidenotes](#tufte-style-sidenotes), playful personality, well-commented code - **LaTeX.css**: Academic typography, wide margins, optimized for technical content - **Sakura**: Minimal duotone color palettes, rapid prototyping - **Matcha**: Semantic hierarchy, CSS custom properties architecture - **MVP.css**: Sensible defaults, zero configuration needed ## Features ### Complete Element Coverage All semantic HTML5 elements are styled out of the box: - Typography: headings, paragraphs, links, lists (ordered, unordered, description) - Content: blockquotes, code blocks, tables, figures with captions - Forms: inputs, textareas, selects, buttons, checkboxes, radio buttons, file uploads - Media: images, video, audio, iframes - Semantic: article, section, aside, header, footer, nav, details/summary ### Tufte-Style Sidenotes Inspired by Edward Tufte's design principles, margin notes can be added using simple `` elements within paragraphs. **Desktop**: Notes appear in the right margin **Mobile**: Notes appear inline with subtle styling ### Example ```html

The framework handles reactivity through signals. Signals are similar to reactive primitives in Solid.js and Vue 3's ref() system, but with a simpler API surface. This approach keeps the mental model straightforward.

``` ### Modular Type Scale Font sizes use a 1.25 ratio (major third) for "harmonious" hierarchy: - Base: `18px` (`1rem`) - Scale: `0.889rem`, `1.125rem`, `1.266rem`, `1.424rem`, `1.802rem`, `2.027rem`, `2.566rem` - Headings use larger sizes from the scale, body text uses base and smaller sizes ### Optimized Reading Width Main content is constrained to approximately 70 characters per line, around the optimal range for comfortable reading. Sidenotes extend into the right margin when space allows. ### Dark Mode Support The stylesheet automatically switches to dark mode when the user's system preference is set to dark: ```css @media (prefers-color-scheme: dark) { /* Dark theme colors applied automatically */ } ``` ## Usage ### Basic Setup Include the stylesheet in your HTML ``: ```html My Document ``` Or import in JavaScript/TypeScript: ```js import 'volt/styles'; ``` ### Example Document Structure ```html

Document Title

Subtitle or introduction

Section Heading

Your content flows naturally. Add sidenotes for additional context. The stylesheet handles all the styling.

Quotes are styled with subtle backgrounds and borders.

Author Name 
      
        // Code blocks use monospace fonts
        const example = "syntax highlighting not included";
Feature Status
Tables Styled with zebra striping
``` ### Forms Forms get styling with focus states, required field indicators, and spacing between controls: ```html
User Information
``` ## Customization ### CSS Custom Properties All design tokens are defined as CSS custom properties (CSS variables) in `variables.css`. Override them in your own stylesheet to customize the appearance: ```css /* Load Volt CSS first */ @import 'volt.css'; /* Then override variables */ :root { /* Change the accent color */ --color-accent: #d63384; --color-accent-hover: #b02a6b; /* Adjust spacing */ --space-md: 1.25rem; /* Change fonts */ --font-sans: "Your Font", system-ui, sans-serif; /* Modify content width */ --content-width: 60ch; } ``` See `variables.css` for the complete list of available tokens. ### Available Properties **Typography**: - `--font-sans`, `--font-serif`, `--font-mono`: Font families - `--font-size-*`: Size scale from sm to 5xl - `--line-height-tight`, `--line-height-base`, `--line-height-relaxed` **Colors**: - `--color-bg`: Background color - `--color-bg-alt`: Alternate background (code blocks, table stripes) - `--color-text`: Primary text color - `--color-text-muted`: Secondary text color - `--color-accent`: Accent color for links, buttons - `--color-accent-hover`: Hover state for accent color - `--color-border`: Border color - `--color-code-bg`: Code block background - `--color-mark`: Highlighted text background - `--color-success`, `--color-warning`, `--color-error`: Semantic colors **Spacing**: - `--space-xs` through `--space-3xl`: Spacing scale **Layout**: - `--content-width`: Maximum width for readable content - `--sidenote-width`: Width of margin notes - `--sidenote-gap`: Space between content and sidenotes **Effects**: - `--shadow-sm`, `--shadow-md`, `--shadow-lg`: Box shadows - `--radius-sm`, `--radius-md`, `--radius-lg`: Border radius - `--transition-fast`, `--transition-base`: Transition durations ### Dark Mode Customization Override dark mode colors specifically: ```css @media (prefers-color-scheme: dark) { :root { --color-accent: #f0f; --color-bg: #000; } } ``` ### Scoped Customization Apply custom styling to specific sections without affecting the whole document: ```html

This section uses different colors and fonts

All nested elements inherit the custom properties.

``` ## Browser Support Volt CSS uses modern CSS features and targets evergreen browsers: - Chrome/Edge 90+ - Firefox 88+ - Safari 14+ Specifically relies on: - CSS custom properties (CSS variables) - CSS Grid and Flexbox - `:has()` selector (for sidenote positioning) - `prefers-color-scheme` media query For older browsers, content remains readable but may lack advanced layout features like margin sidenotes. ## Accessibility - All color combinations meet WCAG AA standards (4.5:1 for normal text, 3:1 for large text) - Clear, visible focus states for keyboard navigation - Encourages logical heading hierarchy, landmark regions, and form labels - Works on all devices and respects user font size preferences - No animations that could trigger vestibular disorders ## Size & Performance The complete stylesheet is approximately 15KB uncompressed, 3-4KB when gzipped For maximum performance: 1. Serve with compression (gzip or brotli) 2. Set cache headers 3. Consider inlining in `