diff --git a/README.md b/README.md index 15d384f..6837ffc 100644 --- a/README.md +++ b/README.md @@ -1,602 +1,954 @@ -# LotusGuild Terminal Design System v1.0 +# LotusGuild Terminal Design System — v1.2 -Unified layout, styling, and JavaScript utilities for all LotusGuild web applications. +**Aesthetic:** Anduril × Hacker Terminal — dark military-tech, multi-accent neon, angular clip-path frames, glitch effects. -**Applies to:** Tinker Tickets (PHP) · PULSE (Node.js) · GANDALF (Flask) +A single-file design system (`base.css` + `base.js`) used across all LotusGuild internal services. `base.html` is a living reference template that demonstrates every component and pattern. + +--- + +## Table of Contents + +1. [Overview](#overview) +2. [Quick Start](#quick-start) +3. [Design Tokens](#design-tokens) +4. [Breakpoints](#breakpoints) +5. [Typography](#typography) +6. [Color Palette](#color-palette) +7. [Component Catalog](#component-catalog) +8. [JavaScript API](#javascript-api) +9. [Theming (Dark / Light)](#theming) +10. [Accessibility](#accessibility) +11. [File Structure](#file-structure) +12. [Changelog](#changelog) + +--- + +## Overview + +| File | Purpose | +|------|---------| +| `base.css` | All styles — ~5,200 lines, 79 sections | +| `base.js` | All JS — vanilla IIFE, `window.lt` namespace, 55+ modules | +| `base.html` | Full component reference / demo page | + +No build step. No npm. No framework. Drop in the two files and go. --- ## Quick Start -**Core files** (needed by every app): - -``` -base.css → all variables, components, animations, responsive rules -base.js → toast, modal, tabs, CSRF, fetch helpers, keyboard shortcuts -base.html → full component reference (static demo, not for production) -``` - -**Platform-specific helpers** (one per backend): - -``` -php/layout.php → PHP base layout with CSP nonce + CSRF injection -python/auth.py → Flask @require_auth / @require_admin decorators -python/base.html → Jinja2 base template with block inheritance -node/middleware.js → Express requireAuth, csrfMiddleware, cspNonce, etc. -``` - -Then load them in your HTML: - ```html - - - + + +
+ + + + + + + + + + + + + +``` - - - +### `lt.init()` — master initializer + +`lt.init(opts?)` runs all standard auto-init modules in one call. Safe to call multiple times — a guard prevents double-initialization. + +```js +lt.init({ + bootName: 'MY APP', // shown in CRT boot overlay (optional) + skipBoot: false, // set true to skip the boot sequence + csrf: 'token', // CSRF token string (optional; overrides meta-tag detection) +}); +``` + +Modules initialized automatically: `tabs`, `accordion`, `tooltip`, `clipboard.initCopyButtons`, `alerts`, `sidebar`, `keys.initDefaults`, `mobileNav`. + +--- + +## Design Tokens + +All tokens are CSS custom properties on `:root`. Override any token in your app stylesheet **after** importing `base.css`. + +### Backgrounds + +| Token | Dark | Light | +|-------|------|-------| +| `--bg-primary` | `#030508` | `#edf0f5` | +| `--bg-secondary` | `#060c14` | `#e2e8f0` | +| `--bg-tertiary` | `#0d1520` | `#cdd5e0` | +| `--bg-card` | `#07101a` | `#f5f7fb` | +| `--bg-terminal` | `#010304` | `#d8dfe8` | +| `--bg-overlay` | `rgba(3,5,8,0.94)` | `rgba(237,240,245,0.96)` | + +### Text + +| Token | Dark | Light | +|-------|------|-------| +| `--text-primary` | `#e8edf5` | `#1a2233` | +| `--text-secondary` | `#8899b0` | `#3a4a60` | +| `--text-muted` | `#4a5a70` | `#6a7a90` | +| `--text-accent` | `#FF6B00` | `#c44e00` | + +### Borders + +| Token | Dark | Light | +|-------|------|-------| +| `--border-color` | `rgba(255,107,0,0.25)` | `rgba(130,140,160,0.5)` | +| `--border-dim` | `rgba(255,107,0,0.10)` | `rgba(130,140,160,0.25)` | +| `--border-bright` | `rgba(255,107,0,0.6)` | `rgba(196,78,0,0.5)` | + +### Spacing + +`--space-xs` (0.25rem) · `--space-sm` (0.5rem) · `--space-md` (1rem) · `--space-lg` (1.5rem) · `--space-xl` (2rem) · `--space-2xl` (3rem) + +### Layout + +| Token | Value | +|-------|-------| +| `--sidebar-width` | `240px` | +| `--header-height` | `56px` | +| `--container-max` | `1600px` | + +### Transitions + +| Token | Value | +|-------|-------| +| `--transition-fast` | `all 0.12s ease` | +| `--transition-default` | `all 0.25s ease` | + +### Corner Cuts + +| Token | Value | Usage | +|-------|-------|-------| +| `--corner-cut` | `8px` | Standard clip-path notch | +| `--corner-cut-sm` | `5px` | Small elements | +| `--corner-cut-lg` | `16px` | Large modals / hero cards | + +### Z-Index Ladder + +| Token | Value | Layer | +|-------|-------|-------| +| `--z-base` | `1` | Stacking context base | +| `--z-dropdown` | `100` | Dropdowns, autocomplete | +| `--z-sticky` | `200` | Sticky elements | +| `--z-fixed` | `300` | Fixed header/sidebar | +| `--z-overlay` | `9999` | CRT scanlines / boot overlay | +| `--z-modal-backdrop` | `10010` | Modal scrim | +| `--z-modal` | `10011` | Modal dialogs | +| `--z-popover` | `10012` | Popovers | +| `--z-tooltip` | `10013` | Tooltips | +| `--z-toast` | `10014` | Toast notifications | +| `--z-panel` | `10020` | Notification / dropdown panels | + +--- + +## Breakpoints + +Mobile-first. 8 tiers: + +| Name | Range | CSS min-width | +|------|-------|---------------| +| `xs` | ≤ 479px | — (base) | +| `sm` | 480–767px | `480px` | +| `md` | 768–1023px | `768px` | +| `lg` | 1024–1279px | `1024px` | +| `xl` | 1280–1535px | `1280px` | +| `2xl` | 1536–1919px | `1536px` | +| `3xl` | 1920–2559px | `1920px` | +| `4k` | ≥ 2560px | `2560px` | + +Check breakpoints in JavaScript: + +```js +lt.viewport.bp() // → 'xs' | 'sm' | 'md' | ... | '4k' +lt.viewport.is('md') // → true if current bp >= md +lt.viewport.on(cb) // subscribe to resize/bp changes +lt.viewport.touch() // true if primary pointer is coarse +lt.viewport.landscape() ``` --- -## Aesthetic at a Glance +## Typography -| Property | Value | -|---|---| -| Background | `#0a0a0a` (near-black) | -| Primary accent | `#00ff41` (phosphor green) | -| Secondary accent | `#ffb000` (amber) | -| Tertiary accent | `#00ffff` (cyan) | -| Error / critical | `#ff4444` (red) | -| Font | `'Courier New', 'Consolas', 'Monaco', 'Menlo', monospace` | -| Border radius | `0` — no rounded corners ever | -| Box shadow | Glow halos only (`0 0 Xpx color`) — no drop shadows | -| Borders | `2px solid` standard · `3px double` for outer frames / modals | -| CRT effects | Scanline animation · screen flicker at 30s · binary corner watermark | +**Font:** JetBrains Mono (Google Fonts) — weights 400, 600, 700; italic 400. + +Load via: +```html + +``` + +| Token | Value | +|-------|-------| +| `--font-mono` | `'JetBrains Mono', 'Cascadia Code', 'Fira Code', monospace` | +| `--font-size-base` | `0.875rem` (14px) | +| `--line-height` | `1.6` | + +Heading classes: `.lt-h1` through `.lt-h6`. Utility: `.lt-text-xs`, `.lt-text-sm`, `.lt-text-lg`, `.lt-text-xl`, `.lt-text-muted`, `.lt-text-accent`, `.lt-font-mono`, `.lt-font-bold`. --- -## CSS Prefix +## Color Palette -All classes use the `.lt-` prefix (*LotusGuild Terminal*) to prevent collisions with app-specific CSS. +### Dark Mode (default) -```css -.lt-btn /* buttons */ -.lt-card /* cards */ -.lt-frame /* ASCII outer frames */ -.lt-modal-overlay /* modals */ -.lt-toast /* toasts */ -.lt-status-* /* status badges */ -.lt-p1 … .lt-p5 /* priority badges */ -/* etc. */ -``` +| Name | Hex | Variable | +|------|-----|----------| +| Orange (primary) | `#FF6B00` | `--accent-orange` | +| Cyan | `#00D4FF` | `--accent-cyan` | +| Green | `#00FF88` | `--accent-green` | +| Red | `#FF2D55` | `--accent-red` | +| Purple | `#BF5FFF` | `--accent-purple` | +| Amber | `#FFB300` | `--accent-amber` | + +### Light Mode + +All accents are desaturated for readability on light backgrounds: + +| Name | Dark | Light | +|------|------|-------| +| Orange | `#FF6B00` | `#c44e00` | +| Cyan | `#00D4FF` | `#0062b8` | +| Green | `#00FF88` | `#006d35` | +| Red | `#FF2D55` | `#b8001f` | +| Purple | `#BF5FFF` | `#7c22cc` | + +Glows in dark mode use `box-shadow` with color spread. Light mode replaces neon glows with drop-shadow rings (e.g., `0 0 0 1px rgba(196,78,0,0.25), 0 1px 6px rgba(196,78,0,0.18)`). --- -## CSS Custom Properties +## Component Catalog -All colour, spacing, and layout values are CSS custom properties on `:root`. -Override them per-app in your `app.css`: +All components use the `.lt-` prefix. -```css -/* Example: app-specific accent on top of base */ -:root { - --terminal-amber: #ffd000; /* slightly brighter amber */ -} -``` - -### Key Variables - -```css -/* Backgrounds */ ---bg-primary: #0a0a0a ---bg-secondary: #1a1a1a ---bg-tertiary: #2a2a2a ---bg-terminal: #001a00 - -/* Terminal colours */ ---terminal-green: #00ff41 ---terminal-amber: #ffb000 ---terminal-cyan: #00ffff ---terminal-red: #ff4444 - -/* Glow stacks (text-shadow) */ ---glow-green ---glow-green-intense ---glow-amber ---glow-amber-intense ---glow-cyan ---glow-red - -/* Box-shadow halos */ ---box-glow-green ---box-glow-amber ---box-glow-red - -/* Z-index ladder */ ---z-dropdown: 100 --z-modal: 500 --z-toast: 800 --z-overlay: 9999 -``` - ---- - -## Components - -### Buttons +### Layout ```html - - - - - -Link Button + +| Name | -Status | -||
|---|---|---|---|
| ticket-001 | -Open | +||
| + | Name ↕ |