Expand README with features and usage examples. Fixes #277

vanvianen · vanvianen · commit b9ef80271c56 · 2025-12-21T09:59:17.000+01:00
Added detailed documentation to the README, including a comprehensive features list, quick start guide, common layout patterns, TypeScript integration, best practices, visual references, and accessibility considerations for the unit.gl toolkit.
diff --git a/README.md b/README.md
@@ -33,6 +33,40 @@
 
 `unit.gl` is a comprehensive design toolkit focused on fluid typography, responsive design, and advanced SCSS functions. It's crafted to empower designers and developers to create harmonious, scalable, and accessible web experiences efficiently.
 
+---
+
+## Features
+
+`unit.gl` provides a robust set of features for building dynamic, responsive layouts with precision and flexibility:
+
+### Core Layout System
+
+- **Kyū Unit System** – A base-16 measurement system (`1q = 1/16rem = 1px`) for precise, consistent spacing and sizing across all screen sizes
+- **Fluid Typography** – Dynamic font scaling with `fluid_type()` mixin that smoothly interpolates between min/max sizes across viewport breakpoints
+- **Modular Scale** – Musical interval-based typographic scales (minor second, golden ratio, perfect fifth, etc.) for harmonious type hierarchies
+- **Baseline Grid** – Visual rhythm system with configurable baseline increments for vertical alignment
+
+### Responsive Design Tools
+
+- **Viewport Breakpoints** – Predefined breakpoint system (xs, sm, md, lg, xl, sl) with `view()` mixin for mobile-first media queries
+- **Device Profiles** – Pre-configured device-specific media queries for iPhone, iPad, Samsung Galaxy, and more
+- **Aspect Ratio Utilities** – Maintain proportions with `display_ratio()` mixin supporting common ratios (16:9, 4:3, golden ratio)
+- **Orientation Helpers** – Landscape/portrait-specific styling with `display_orientation_*` mixins
+
+### Advanced SCSS Functions
+
+- **Unit Conversion** – Seamless conversion between px, rem, em with `px_to_rem()`, `rem_to_px()`, `em_to_px()` functions
+- **Math Operations** – `add()`, `subtract()` with intelligent unit handling; `modular_scale()` for ratio-based scaling
+- **Layer Management** – z-index token system via `$layers` map and `z()` function for consistent stacking order
+- **Paper Sizes** – ISO (A-series, B-series), ANSI, and custom Q-series paper dimensions for print layouts
+
+### Developer Experience
+
+- **Modern Sass** – Uses `sass:math`, `sass:map`, `sass:color` modules; no deprecated syntax
+- **TypeScript Support** – Grid utilities and layout helpers with full type definitions
+- **Visual Guides** – Built-in overlay system for baseline grids, margins, and alignment verification during development
+- **Customizable Variables** – Override defaults for base units, breakpoints, scales, and colors via Sass variables
+
 ## Installation
 
 ### HTML Script Tag
@@ -49,6 +83,298 @@ npm i unit.gl
 
 ---
 
+## Quick Start
+
+### Basic Usage (SCSS)
+
+Import `unit.gl` into your Sass/SCSS files:
+
+```scss
+@use "unit.gl" as *;
+
+// Use the Kyū unit system
+.container {
+  padding: q(4);        // 4q = 4 × (1/16rem) = 0.25rem = 4px
+  margin-bottom: q(8);  // 8q = 0.5rem = 8px
+}
+
+// Apply fluid typography
+.heading {
+  @include fluid_type(
+    $min-size: 16px,
+    $max-size: 48px,
+    $min-vw: 320px,
+    $max-vw: 1280px
+  );
+}
+
+// Responsive breakpoints
+.grid {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: q(4);
+
+  @include view(md) {
+    grid-template-columns: repeat(2, 1fr);
+  }
+
+  @include view(lg) {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+```
+
+### Common Layout Patterns
+
+#### Fluid Card Grid with Consistent Spacing
+
+```scss
+@use "unit.gl" as *;
+
+.card-grid {
+  display: grid;
+  gap: q(8);                          // 0.5rem spacing
+  padding: q(8);
+
+  // Mobile: 1 column
+  grid-template-columns: 1fr;
+
+  // Tablet: 2 columns
+  @include view(sm) {
+    grid-template-columns: repeat(2, 1fr);
+    gap: q(12);                       // 0.75rem
+  }
+
+  // Desktop: 3 columns
+  @include view(md) {
+    grid-template-columns: repeat(3, 1fr);
+    gap: q(16);                       // 1rem
+  }
+}
+
+.card {
+  padding: q(12);
+  border-radius: q(2);
+  background: #fff;
+  box-shadow: 0 q(1) q(4) rgba(0, 0, 0, 0.1);
+}
+```
+
+#### Typography Scale with Modular Rhythm
+
+```scss
+@use "unit.gl" as *;
+
+// Use golden ratio (1.618) for harmonious type scale
+$scale-ratio: map.get($ratio_map, golden);
+
+h1 {
+  font-size: modular_scale(4, 1rem, $scale-ratio);  // ~6.85rem
+  line-height: baseline(6);                          // 6 baseline units
+  margin-bottom: baseline(2);
+}
+
+h2 {
+  font-size: modular_scale(3, 1rem, $scale-ratio);  // ~4.236rem
+  line-height: baseline(5);
+  margin-bottom: baseline(2);
+}
+
+h3 {
+  font-size: modular_scale(2, 1rem, $scale-ratio);  // ~2.618rem
+  line-height: baseline(4);
+  margin-bottom: baseline(1);
+}
+
+p {
+  font-size: modular_scale(0, 1rem, $scale-ratio);  // 1rem
+  line-height: baseline(3);                          // Vertical rhythm
+  margin-bottom: baseline(2);
+}
+```
+
+#### Aspect Ratio Container (e.g., Video Embed)
+
+```scss
+@use "unit.gl" as *;
+
+.video-wrapper {
+  width: 100%;
+  max-width: 800px;
+  margin: 0 auto;
+
+  // Maintain 16:9 aspect ratio
+  @include display_ratio(16, 9);
+
+  iframe {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+  }
+}
+```
+
+#### Device-Specific Styling
+
+```scss
+@use "unit.gl" as *;
+
+.app-header {
+  height: q(80);  // 5rem = 80px
+
+  // iPhone-specific adjustments
+  @include device-media-query('iphone_x') {
+    padding-top: env(safe-area-inset-top);  // Notch support
+  }
+
+  // Tablet landscape
+  @include display_orientation_landscape {
+    @include view(sm) {
+      height: q(64);  // Shorter header in landscape
+    }
+  }
+}
+```
+
+### TypeScript Integration
+
+```typescript
+import { GridManager } from 'unit.gl';
+
+// Initialize grid overlay for development
+const grid = new GridManager({
+  columns: 12,
+  gutter: 16,       // 16px gutter
+  baseline: 8,      // 8px baseline grid
+  color: 'rgba(255, 0, 0, 0.1)'
+});
+
+// Toggle grid visibility
+grid.toggle();
+
+// Update grid configuration
+grid.updateConfig({ columns: 16 });
+```
+
+---
+
+## Usage Guidelines & Best Practices
+
+### Performance Optimization
+
+1. **Minimize Media Query Complexity**
+   - Use the `view()` mixin for standard breakpoints instead of custom media queries
+   - Consolidate similar breakpoint rules to reduce CSS output
+
+2. **Leverage Sass Variables**
+   - Override defaults at the top of your main stylesheet:
+     ```scss
+     @use "unit.gl" with (
+       $q: 0.0625rem,           // Customize base unit if needed
+       $base_screen_unit: 16px  // Adjust breakpoint base
+     );
+     ```
+
+3. **Selective Imports**
+   - Import only the modules you need to reduce compilation time:
+     ```scss
+     @use "unit.gl/scss/functions" as fn;
+     @use "unit.gl/scss/mixins/view" as view;
+     ```
+
+### Design System Integration
+
+- **Consistent Spacing**: Use Kyū multiples (4q, 8q, 12q, 16q) as your spacing scale
+- **Type Hierarchy**: Choose one modular scale ratio and stick with it across all typographic elements
+- **Z-Index Management**: Define your layer stack in `$layers` map at project start
+- **Breakpoint Strategy**: Use mobile-first approach with `view()` mixins; avoid `max-width` queries
+
+### Accessibility Considerations
+
+- **Relative Units**: `unit.gl` uses `rem` internally, respecting user font-size preferences
+- **Viewport Scaling**: `fluid_type()` ensures readable text across all devices
+- **Visual Guides**: Enable baseline grid during development to verify vertical rhythm alignment
+
+### Common Pitfalls to Avoid
+
+❌ **Don't mix unit systems**
+```scss
+.bad {
+  padding: 10px;      // Hardcoded px
+  margin: q(8);       // Kyū unit
+}
+```
+
+✅ **Use consistent units**
+```scss
+.good {
+  padding: q(10);     // All Kyū
+  margin: q(8);
+}
+```
+
+❌ **Don't nest too many breakpoints**
+```scss
+.bad {
+  @include view(md) {
+    @include view(lg) {  // Nested breakpoint = bad specificity
+      // ...
+    }
+  }
+}
+```
+
+✅ **Keep breakpoints flat**
+```scss
+.good {
+  @include view(md) { /* md styles */ }
+  @include view(lg) { /* lg styles */ }
+}
+```
+
+---
+
+## Visual Reference
+
+### Kyū Unit System Diagram
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  1rem = 16q = 16px (default browser font size)          │
+├─────────────────────────────────────────────────────────┤
+│  1q   = 0.0625rem = 1px    │  Base unit               │
+│  4q   = 0.25rem   = 4px    │  Small spacing           │
+│  8q   = 0.5rem    = 8px    │  Medium spacing          │
+│  16q  = 1rem      = 16px   │  Large spacing           │
+│  32q  = 2rem      = 32px   │  Extra-large spacing     │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Modular Scale Visualization (Golden Ratio 1.618)
+
+```
+h1 ████████████████ (6.854rem) ← modular_scale(4)
+h2 ██████████       (4.236rem) ← modular_scale(3)
+h3 ██████           (2.618rem) ← modular_scale(2)
+h4 ████            (1.618rem) ← modular_scale(1)
+p  ██              (1.000rem) ← modular_scale(0)
+```
+
+### Breakpoint Reference
+
+| Name | Min Width | Device Target          |
+|------|-----------|------------------------|
+| xs   | 320px     | Mobile (portrait)      |
+| sm   | 480px     | Mobile (landscape)     |
+| md   | 768px     | Tablet                 |
+| lg   | 1024px    | Desktop                |
+| xl   | 1280px    | Large Desktop          |
+| sl   | 1920px    | Extra Large Display    |
+
+---
+
 ## Colophon
 
 ### Authors
