a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
desertthunder.dev
hypermedia
frontend
signals
1# Volt CSS
2
3A classless CSS stylesheet for elegant, readable web documents. Drop it into any HTML page for instant, semantic styling without touching a single class name.
4
5## Philosophy
6
7Volt 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.
8
9### Core Principles
10
11- **Classless**: Style semantic HTML elements directly.
12- **Accessible**: WCAG AA contrast ratios, keyboard navigation support, and semantic HTML patterns
13
14- Optimized line lengths, modular type scale, and whitespace optimized for reading
15- Automatic light and dark modes via `prefers-color-scheme`
16- Mobile-first (ish) design that doesn't compromise readability
17
18## Inspiration
19
20Volt CSS synthesizes ideas from several excellent classless CSS frameworks:
21
22- **magick.css**: Tufte-style [sidenotes](#tufte-style-sidenotes), playful personality, well-commented code
23- **LaTeX.css**: Academic typography, wide margins, optimized for technical content
24- **Sakura**: Minimal duotone color palettes, rapid prototyping
25- **Matcha**: Semantic hierarchy, CSS custom properties architecture
26- **MVP.css**: Sensible defaults, zero configuration needed
27
28## Features
29
30### Complete Element Coverage
31
32All semantic HTML5 elements are styled out of the box:
33
34- Typography: headings, paragraphs, links, lists (ordered, unordered, description)
35- Content: blockquotes, code blocks, tables, figures with captions
36- Forms: inputs, textareas, selects, buttons, checkboxes, radio buttons, file uploads
37- Media: images, video, audio, iframes
38- Semantic: article, section, aside, header, footer, nav, details/summary
39
40### Tufte-Style Sidenotes
41
42Inspired by Edward Tufte's design principles, margin notes can be added using simple `<small>` elements within paragraphs.
43
44**Desktop**: Notes appear in the right margin
45**Mobile**: Notes appear inline with subtle styling
46
47### Example
48
49```html
50<p>
51 The framework handles reactivity through signals.
52 <small>
53 Signals are similar to reactive primitives in Solid.js and Vue 3's
54 ref() system, but with a simpler API surface.
55 </small>
56 This approach keeps the mental model straightforward.
57</p>
58```
59
60### Modular Type Scale
61
62Font sizes use a 1.25 ratio (major third) for "harmonious" hierarchy:
63
64- Base: `18px` (`1rem`)
65- Scale: `0.889rem`, `1.125rem`, `1.266rem`, `1.424rem`, `1.802rem`, `2.027rem`, `2.566rem`
66- Headings use larger sizes from the scale, body text uses base and smaller sizes
67
68### Optimized Reading Width
69
70Main content is constrained to approximately 70 characters per line, around the optimal range for comfortable reading.
71Sidenotes extend into the right margin when space allows.
72
73### Dark Mode Support
74
75The stylesheet automatically switches to dark mode when the user's system preference is set to dark:
76
77```css
78@media (prefers-color-scheme: dark) {
79 /* Dark theme colors applied automatically */
80}
81```
82
83## Usage
84
85### Basic Setup
86
87Include the stylesheet in your HTML `<head>`:
88
89```html
90<!DOCTYPE html>
91<html lang="en">
92 <head>
93 <meta charset="UTF-8">
94 <meta name="viewport" content="width=device-width, initial-scale=1.0">
95 <link rel="stylesheet" href="volt.css">
96 <title>My Document</title>
97 </head>
98 <body>
99 <!-- Your markup -->
100 </body>
101</html>
102```
103
104Or import in JavaScript/TypeScript:
105
106```js
107import 'volt/styles';
108```
109
110### Example Document Structure
111
112```html
113<body>
114 <header>
115 <h1>Document Title</h1>
116 <p>Subtitle or introduction</p>
117 </header>
118
119 <article>
120 <h2>Section Heading</h2>
121 <p>
122 Your content flows naturally.
123 <small>Add sidenotes for additional context.</small>
124 The stylesheet handles all the styling.
125 </p>
126
127 <blockquote>
128 <p>Quotes are styled with subtle backgrounds and borders.</p>
129 <cite>Author Name</cite>
130 </blockquote>
131
132 <pre>
133 <code>
134 // Code blocks use monospace fonts
135 const example = "syntax highlighting not included";
136 </code>
137 </pre>
138
139 <table>
140 <thead>
141 <tr>
142 <th>Feature</th>
143 <th>Status</th>
144 </tr>
145 </thead>
146 <tbody>
147 <tr>
148 <td>Tables</td>
149 <td>Styled with zebra striping</td>
150 </tr>
151 </tbody>
152 </table>
153 </article>
154
155 <footer>
156 <p>Footer content, copyright, etc.</p>
157 </footer>
158</body>
159```
160
161### Forms
162
163Forms get styling with focus states, required field indicators, and spacing between controls:
164
165```html
166<form>
167 <fieldset>
168 <legend>User Information</legend>
169
170 <label for="name">Name</label>
171 <input type="text" id="name" name="name" required>
172
173 <label for="email">Email</label>
174 <input type="email" id="email" name="email" required>
175
176 <label for="message">Message</label>
177 <textarea id="message" name="message"></textarea>
178
179 <button type="submit">Send Message</button>
180 <input type="reset" value="Clear Form">
181 </fieldset>
182</form>
183```
184
185## Customization
186
187### CSS Custom Properties
188
189All design tokens are defined as CSS custom properties (CSS variables) in `variables.css`.
190Override them in your own stylesheet to customize the appearance:
191
192```css
193/* Load Volt CSS first */
194@import 'volt.css';
195
196/* Then override variables */
197:root {
198 /* Change the accent color */
199 --color-accent: #d63384;
200 --color-accent-hover: #b02a6b;
201
202 /* Adjust spacing */
203 --space-md: 1.25rem;
204
205 /* Change fonts */
206 --font-sans: "Your Font", system-ui, sans-serif;
207
208 /* Modify content width */
209 --content-width: 60ch;
210}
211```
212
213See `variables.css` for the complete list of available tokens.
214
215### Available Properties
216
217**Typography**:
218
219- `--font-sans`, `--font-serif`, `--font-mono`: Font families
220- `--font-size-*`: Size scale from sm to 5xl
221- `--line-height-tight`, `--line-height-base`, `--line-height-relaxed`
222
223**Colors**:
224
225- `--color-bg`: Background color
226- `--color-bg-alt`: Alternate background (code blocks, table stripes)
227- `--color-text`: Primary text color
228- `--color-text-muted`: Secondary text color
229- `--color-accent`: Accent color for links, buttons
230- `--color-accent-hover`: Hover state for accent color
231- `--color-border`: Border color
232- `--color-code-bg`: Code block background
233- `--color-mark`: Highlighted text background
234- `--color-success`, `--color-warning`, `--color-error`: Semantic colors
235
236**Spacing**:
237
238- `--space-xs` through `--space-3xl`: Spacing scale
239
240**Layout**:
241
242- `--content-width`: Maximum width for readable content
243- `--sidenote-width`: Width of margin notes
244- `--sidenote-gap`: Space between content and sidenotes
245
246**Effects**:
247
248- `--shadow-sm`, `--shadow-md`, `--shadow-lg`: Box shadows
249- `--radius-sm`, `--radius-md`, `--radius-lg`: Border radius
250- `--transition-fast`, `--transition-base`: Transition durations
251
252### Dark Mode Customization
253
254Override dark mode colors specifically:
255
256```css
257@media (prefers-color-scheme: dark) {
258 :root {
259 --color-accent: #f0f;
260 --color-bg: #000;
261 }
262}
263```
264
265### Scoped Customization
266
267Apply custom styling to specific sections without affecting the whole document:
268
269```html
270<style>
271 .special-section {
272 --color-accent: #e74c3c;
273 --font-sans: "Georgia", serif;
274 }
275</style>
276
277<div class="special-section">
278 <h2>This section uses different colors and fonts</h2>
279 <p>All nested elements inherit the custom properties.</p>
280</div>
281```
282
283## Browser Support
284
285Volt CSS uses modern CSS features and targets evergreen browsers:
286
287- Chrome/Edge 90+
288- Firefox 88+
289- Safari 14+
290
291Specifically relies on:
292
293- CSS custom properties (CSS variables)
294- CSS Grid and Flexbox
295- `:has()` selector (for sidenote positioning)
296- `prefers-color-scheme` media query
297
298For older browsers, content remains readable but may lack advanced layout features like margin sidenotes.
299
300## Accessibility
301
302- All color combinations meet WCAG AA standards (4.5:1 for normal text, 3:1 for large text)
303- Clear, visible focus states for keyboard navigation
304- Encourages logical heading hierarchy, landmark regions, and form labels
305- Works on all devices and respects user font size preferences
306- No animations that could trigger vestibular disorders
307
308## Size & Performance
309
310The complete stylesheet is approximately 15KB uncompressed, 3-4KB when gzipped
311
312For maximum performance:
313
3141. Serve with compression (gzip or brotli)
3152. Set cache headers
3163. Consider inlining in `<style>` tags for above-the-fold content on single-page sites
317
318## Design Decisions
319
320### Sans-Serif
321
322While serif fonts are traditional for long-form reading, modern screens render sans-serif fonts with excellent clarity. The system font stack ensures fast loading and familiar reading experience while maintaining personality through spacing, hierarchy, and layout.
323
324### `<small>` Sidenotes?
325
326The `<small>` element semantically represents side comments and fine print, making it a natural choice for sidenotes. This approach requires no custom attributes or classes, keeping markup clean and portable.
327
328### 70 Characters Line Length
329
330Research shows optimal reading comprehension occurs with 45-75 characters per line. 70 characters balances readability with efficient use of screen space.
331
332### Automatic Dark Mode
333
334Respecting user preferences improves accessibility and reduces eye strain. Automatic theme switching via `prefers-color-scheme` requires zero configuration while providing the best experience for each user.
335
336## License
337
338Part of the VoltX project. MIT licensed.
339
340## Further Reading
341
342- [Tufte CSS](https://edwardtufte.github.io/tufte-css/)
343- [Practical Typography by Matthew Butterick](https://practicaltypography.com/)
344- [The Elements of Typographic Style Applied to the Web](http://webtypography.net/)
345- [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/WCAG21/quickref/)