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 + +
+
+ +
+ +
+ + +
+
+
+
+
``` -All buttons: -- Transparent background, green border, `[ text ]` bracket decoration via `::before`/`::after` -- Hover → amber colour, `translateY(-2px)` lift, amber glow -- `border-radius: 0` — terminal style, no rounding +### ASCII Frame System -### Status Badges +The signature angled clip-path card border: ```html -Open -In Progress -Closed -Online -Failed -``` +
+
+
-Spinning `◐` indicator on `lt-status-in-progress` and `lt-status-running`. - -### Priority Badges - -```html -P1 Critical -P2 High -P3 Med -P4 Low -P5 Min -``` - -P1 has a pulsing glow animation. - -### Chips (compact inline status) - -```html -OK -Warn -Critical -Info -``` - -### Inline Messages - -```html -
Something went wrong
-
Saved successfully
-
Rate limit approaching
-
Auto-refresh every 30s
-``` - -### ASCII Frames - -Outer frame (double-line, for major sections): -```html +
- - -
Section Title
-
- -
+
SECTION HEADER
+ …content…
``` -Inner frame (single-line, for sub-panels): -```html -
-
Sub Section
- -
-``` - -The `::before` / `::after` pseudo-elements draw the top-left `╔`/`┌` and top-right `╗`/`┐` corners automatically. Bottom corners require explicit `` children because CSS cannot target `:nth-pseudo-element`. - ### Cards ```html
-
Card Title
- +
+
+ +
+
+
+``` + +### Buttons + +```html + + + + + + + + + + + + + +``` + +### Forms & Inputs + +```html +
+ + + Helper text
- -
-
-
-
+ + + + + + + + + + + + + +
+ Drop files here or click to browse +
``` +JS: `lt.dropzone.init(el, { onFiles(files){} })` + +Form validation: +```js +lt.validate.init(formEl, ({ data, errors }) => { + // called on submit when valid +}); +// Custom validator +lt.validate.custom['my-rule'] = (val) => val.length > 3 ? null : 'Too short'; +``` + +### Status Badges + +```html +Open +Closed +In Progress +Critical +High +Medium +Low + + + +``` + +JS: `lt.notif.set(el, n)` / `lt.notif.inc(el)` / `lt.notif.clear(el)` + ### Tables -Full-border table (simple data, terminal look): ```html
- - - - - - - - + + + + + - + + …
NameStatus
ticket-001Open
Accessible caption
Name ↕
- - - ``` -Data table (compact, row-only separators, for dense data): -```html -…
+JS: +```js +lt.tableNav.init('my-table'); // keyboard nav (arrow keys, enter) +lt.sortTable.init('my-table'); // click-to-sort columns +lt.tableColumns.init('my-table'); // show/hide columns ``` -Row classes: `lt-row-p1`–`lt-row-p5` (priority left border) · `lt-row-critical` · `lt-row-warning` · `lt-row-selected` (keyboard nav highlight) - -### Forms - -```html -
- - - Markdown supported. -
- -
- - -
- -
- -
- - - -``` - -Labels are amber-coloured and uppercase. Inputs: green border, focus → amber border + glow pulse. +Responsive: collapses to card layout below 767px. ### Modals ```html - - + - -