@whykusanagi/corrupted-theme 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -21,6 +21,168 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.1.2] - 2025-11-26
+
+### Added
+
+#### Extension Components (`src/css/extensions.css`)
+Production-tested components from whykusanagi.xyz, now part of the core package:
+
+- **Gallery System**
+  - `.gallery-container` - Responsive grid layout with variants (compact, large)
+  - `.gallery-item` - Image cards with aspect ratio options (square, portrait, landscape)
+  - `.filter-bar` and `.filter-btn` - Category filtering with animated transitions
+  - `gallery.js` - JavaScript module for filtering, lightbox, and NSFW handling
+
+- **Lightbox Component**
+  - `.lightbox` - Fullscreen image viewer overlay
+  - `.lightbox-image`, `.lightbox-close`, `.lightbox-prev`, `.lightbox-next`
+  - `.lightbox-caption`, `.lightbox-counter`
+  - Keyboard navigation (Arrow keys, Escape)
+  - Touch gesture support for mobile
+
+- **NSFW Content Blur**
+  - `.nsfw-content` - Click-to-reveal blur overlay
+  - Custom warning text via `data-warning` attribute
+  - `.revealed` state for toggling visibility
+  - Auto-reveal in lightbox mode
+
+- **Social Links List**
+  - `.social-links-container` - Link-in-bio layout
+  - `.profile-avatar` - Circular avatar with glow (sm, default, lg sizes)
+  - `.profile-name`, `.profile-bio` - Profile text components
+  - `.link-list`, `.link-item` - Styled link buttons
+  - Platform-specific hover colors (twitter, instagram, youtube, github, discord, twitch)
+
+- **Countdown Widget**
+  - `.countdown-container`, `.shape-container` - Event countdown layout
+  - Shape variants: diamond, circle, heart, star, hexagon, octagon
+  - `.countdown-box`, `.countdown-timer` - Timer display
+  - `.countdown-popup` - Animated popup messages
+  - `.countdown-character`, `.countdown-overlay-wrapper` - Image support
+  - `countdown-widget.js` - JavaScript module with JSON config support
+
+#### New JavaScript Modules (`src/lib/`)
+- `gallery.js` - Gallery system with filtering, lightbox, and NSFW handling
+- `countdown-widget.js` - Countdown widget with JSON configuration
+
+#### New Package Exports
+```javascript
+'@whykusanagi/corrupted-theme/extensions' // extensions.css
+'@whykusanagi/corrupted-theme/gallery'    // gallery.js
+'@whykusanagi/corrupted-theme/countdown'  // countdown-widget.js
+```
+
+#### Example Pages
+- `examples/extensions-showcase.html` - Interactive demo for all extension components
+- `examples/index.html` - Central landing hub for the design system with categorized navigation
+- `examples/assets/celeste-avatar.png` - Local avatar image for demos
+
+#### Design System Architecture
+- **Central Landing Hub** (`examples/index.html`)
+  - Hero section with quick install instructions
+  - Categorized cards linking to Core Components, Extensions, Glass Components, API Docs, Nikke, Animations
+  - Quick links for common component pages
+  - Professional Netflix/Meta-level information architecture
+
+- **Global Navigation System**
+  - Consistent navigation bar across all 9 example pages
+  - Home, Components (dropdown), Extensions (dropdown), Examples (dropdown), Docs links
+  - Section anchors in dropdowns for quick navigation
+  - Proper active state highlighting
+
+### Fixed
+
+#### Chrome White Background Flash
+- **Added:** `background-color: var(--bg)` to both `html` and `body` in `typography.css`
+- **Why:** Chrome browsers showed white flash before CSS variables loaded
+- **Impact:** Consistent dark background across all browsers immediately on load
+
+#### Navigation Consistency
+- **Updated:** All 9 example pages now have identical global navigation
+- **Why:** Some pages (button.html, card.html, form.html, layout.html) had minimal "Back" links only
+- **Impact:** Users can navigate the entire design system from any page
+
+#### Dead Links Fixed
+- **Fixed:** "Customization" links pointed to non-existent `CUSTOMIZATION.md`
+- **Changed to:** `COMPONENTS_REFERENCE.md#customization`
+- **Fixed:** Backgrounds section link added to Components dropdown
+
+#### Image Hotlinking
+- **Removed:** All Unsplash hotlinks (9 instances)
+- **Replaced with:** Local `assets/celeste-avatar.png` and `placehold.co` placeholders
+- **Why:** External hotlinks may break, cause CORS issues, or violate terms
+- **Impact:** All demo images load reliably in any environment
+
+### Changed
+
+#### Documentation Updates
+- **README.md** - Added "Extension Components" section with usage examples
+- **COMPONENTS_REFERENCE.md** - Added full documentation for all extension components
+- Updated table of contents in both files
+
+#### CSS Architecture
+- `theme.css` now imports `extensions.css` automatically
+- Cleaned up duplicate NSFW styles (now in extensions.css only)
+- Added explicit background color to `html` element for faster paint
+
+#### Example Page Updates
+- All example pages updated with consistent global navigation
+- `showcase-complete.html` - Added `id="backgrounds"` anchor and dropdown link
+- `index.html` - Transformed into design system landing hub
+- Layouts page added to Examples dropdown across all pages
+
+### Files Added
+- `src/css/extensions.css`
+- `src/lib/gallery.js`
+- `src/lib/countdown-widget.js`
+- `examples/extensions-showcase.html`
+- `examples/assets/celeste-avatar.png`
+
+---
+
+## [0.1.1] - 2025-11-26
+
+### Fixed
+
+#### Navbar Z-Index Issue
+- **Changed:** `--z-navbar` from `500` to `1000` in `variables.css`
+- **Why:** Navbar was appearing behind content when using video backgrounds with `.app-shell` structure
+- **Impact:** Navbar now always renders above all content layers
+
+#### Navbar Styles Not Available with Modular Imports
+- **Moved:** All navbar styles (`nav.navbar`, `.navbar-content`, `.navbar-logo`, `.navbar-links`) from `theme.css` to `components.css`
+- **Why:** When using modular imports (as documented), navbar styles were missing because they only existed in `theme.css`
+- **Impact:** Navbar now works correctly with both single-file and modular import methods
+
+### Changed
+
+#### Documentation Improvements
+- **Added:** "Video Backgrounds with Navigation" section to README
+  - Proper navbar placement outside `.app-shell` for z-index stacking
+  - Complete z-index hierarchy table with all tokens
+  - HTML structure example for video backgrounds with navigation
+
+- **Added:** "HTML Import Methods" section to README
+  - Method 1: Single file import (recommended)
+  - Method 2: Modular imports with correct dependency order
+  - CSS `@import` syntax examples
+  - HTML `<link>` tag syntax examples
+  - Explanation of why import order matters
+
+#### CSS Architecture
+- Navbar responsive styles consolidated in `components.css`
+- Removed duplicate navbar styles from `theme.css`
+- Z-index values now use CSS custom properties consistently (`var(--z-negative)`, `var(--z-background)`, etc.)
+
+### Files Modified
+- `src/css/variables.css` - Z-index value change
+- `src/css/components.css` - Added navbar base styles and responsive styles
+- `src/css/theme.css` - Removed navbar styles (now imported via components.css)
+- `README.md` - Enhanced documentation
+
+---
+
 ## [0.1.0] - 2025-11-23
 
 ### Added

package/README.md

@@ -11,13 +11,14 @@ A production-ready glassmorphic design system for cinematic, cyberpunk-inspired
 6. [Component Quick Reference](#component-quick-reference)
 7. [Animations & Experience Layer](#animations--experience-layer)
 8. [Nikke Utilities](#nikke-utilities)
-9. [Customization & Tokens](#customization--tokens)
-10. [Coding Standards](#coding-standards)
-11. [Development Workflow](#development-workflow)
-12. [Testing & QA Expectations](#testing--qa-expectations)
-13. [Support](#support)
-14. [Celeste Widget Integration](#celeste-widget-integration-optional)
-15. [License](#license)
+9. [Extension Components](#extension-components)
+10. [Customization & Tokens](#customization--tokens)
+11. [Coding Standards](#coding-standards)
+12. [Development Workflow](#development-workflow)
+13. [Testing & QA Expectations](#testing--qa-expectations)
+14. [Support](#support)
+15. [Celeste Widget Integration](#celeste-widget-integration-optional)
+16. [License](#license)
 
 ## Overview
 - **Glassmorphism-first** visual language with layered depth, gradients, and scanlines.
@@ -76,6 +77,16 @@ Copy `src/css` into your project (or use `dist/theme.min.css`) and import it loc
 - `npm run dev:proxy` – Celeste proxy (port 5000)
 
 ## Base Layout & Background
+
+### Static Background
+```html
+<body>
+  <div class="glass-backdrop"></div>
+  <main class="app-shell"><!-- your glass UI --></main>
+</body>
+```
+
+### Video Background
 ```html
 <body>
   <video class="background-media" autoplay muted loop playsinline>
@@ -85,27 +96,128 @@ Copy `src/css` into your project (or use `dist/theme.min.css`) and import it loc
   <main class="app-shell"><!-- your glass UI --></main>
 </body>
 ```
+
+### Required CSS
 ```css
 html, body { min-height: 100vh; background: var(--bg); margin: 0; }
-.background-media { position: fixed; inset: 0; object-fit: cover; z-index: -2; }
-.glass-backdrop { position: fixed; inset: 0; background: linear-gradient(180deg, rgba(5,0,16,.85), rgba(10,10,10,.9)); z-index: -1; }
-.app-shell { position: relative; z-index: 1; padding: clamp(1.5rem, 3vw, 3rem); backdrop-filter: blur(0); }
+.background-media { position: fixed; inset: 0; object-fit: cover; z-index: var(--z-negative); }
+.glass-backdrop { position: fixed; inset: 0; background: linear-gradient(180deg, rgba(5,0,16,.85), rgba(10,10,10,.9)); z-index: var(--z-background); }
+.app-shell { position: relative; z-index: var(--z-elevated); padding: clamp(1.5rem, 3vw, 3rem); backdrop-filter: blur(0); }
+```
+
+### Video Backgrounds with Navigation
+
+When using video backgrounds, place the navbar **outside** `.app-shell` for proper z-index stacking:
+
+```html
+<body>
+  <!-- Background layer -->
+  <video class="background-media" autoplay muted loop playsinline>
+    <source src="/media/corruption-loop.mp4" type="video/mp4" />
+  </video>
+  <div class="glass-backdrop"></div>
+  
+  <!-- Navigation MUST be outside app-shell for proper stacking -->
+  <nav class="navbar">
+    <div class="navbar-content">
+      <a class="navbar-logo" href="/">Brand</a>
+      <ul class="navbar-links">
+        <li><a href="#home" class="active">Home</a></li>
+        <li><a href="#about">About</a></li>
+        <li><a href="#contact">Contact</a></li>
+      </ul>
+    </div>
+  </nav>
+  
+  <!-- Main content -->
+  <main class="app-shell">
+    <!-- your glass UI components -->
+  </main>
+</body>
 ```
-Use `.app-shell` as the only stacking context above the backdrop so containers never block the video/image layer.
+
+### Z-Index Hierarchy
+
+The theme uses a systematic z-index scale defined in `variables.css`:
+
+| Token | Value | Purpose |
+|-------|-------|---------|
+| `--z-negative` | `-2` | Background media (video/image) |
+| `--z-background` | `-1` | Glass backdrop overlay |
+| `--z-base` | `0` | Default stacking |
+| `--z-elevated` | `1` | App shell and content |
+| `--z-navbar` | `1000` | Navigation (always above content) |
+| `--z-modal` | `1000` | Modals and overlays |
+
+> **Important:** The navbar uses `z-index: 1000` to ensure it always appears above all content, including video backgrounds and elevated containers.
 
 ## CSS & JS Imports
+
+### Method 1: Single File Import (Recommended)
+
+The simplest approach — import everything in one line:
+
 ```html
-<link rel="stylesheet" href="@whykusanagi/corrupted-theme/dist/theme.min.css">
+<!-- HTML -->
+<link rel="stylesheet" href="node_modules/@whykusanagi/corrupted-theme/dist/theme.min.css">
+```
+
+```css
+/* CSS */
+@import '@whykusanagi/corrupted-theme';
+```
+
+✅ **Recommended for most projects.** Includes all styles in the correct order automatically.
+
+### Method 2: Modular Imports (Advanced)
+
+Import only the modules you need for smaller bundle sizes. 
+
+> ⚠️ **CRITICAL: Import order matters!** Modules have dependencies that require specific ordering.
+
+#### CSS @import Syntax
+```css
+/* Correct order (matches theme.css structure) */
+@import '@whykusanagi/corrupted-theme/variables';     /* 1. Foundation tokens */
+@import '@whykusanagi/corrupted-theme/typography';    /* 2. Font styles */
+@import '@whykusanagi/corrupted-theme/glassmorphism'; /* 3. Glass effects */
+@import '@whykusanagi/corrupted-theme/animations';    /* 4. Keyframes - MUST come before components */
+@import '@whykusanagi/corrupted-theme/components';    /* 5. UI components - MUST come after animations */
+@import '@whykusanagi/corrupted-theme/utilities';     /* 6. Utility classes */
+```
+
+#### HTML Link Tags
+```html
+<!-- Correct order (matches theme.css structure) -->
+<link rel="stylesheet" href="node_modules/@whykusanagi/corrupted-theme/src/css/variables.css">
+<link rel="stylesheet" href="node_modules/@whykusanagi/corrupted-theme/src/css/typography.css">
+<link rel="stylesheet" href="node_modules/@whykusanagi/corrupted-theme/src/css/glassmorphism.css">
+<link rel="stylesheet" href="node_modules/@whykusanagi/corrupted-theme/src/css/animations.css">    <!-- MUST come before components -->
+<link rel="stylesheet" href="node_modules/@whykusanagi/corrupted-theme/src/css/components.css">    <!-- MUST come after animations -->
+<link rel="stylesheet" href="node_modules/@whykusanagi/corrupted-theme/src/css/utilities.css">
+```
+
+#### Why Order Matters
+- `components.css` uses animation keyframes defined in `animations.css`
+- If `components.css` loads before `animations.css`, spinner and loading animations won't work
+- Always verify order by checking `src/css/theme.css` (shows canonical import structure)
+
+### JavaScript Imports
+
+```html
+<!-- HTML -->
 <script type="module" src="@whykusanagi/corrupted-theme/src/lib/corrupted-text.js"></script>
 <script type="module" src="@whykusanagi/corrupted-theme/src/lib/corruption-loading.js"></script>
 ```
+
 ```js
+// ES Modules
 import { initCorruptedText } from '@whykusanagi/corrupted-theme/src/lib/corrupted-text.js';
 import { showCorruptionLoading } from '@whykusanagi/corrupted-theme/src/lib/corruption-loading.js';
 
 document.addEventListener('DOMContentLoaded', () => {
-  initCorruptedText();                      // re-init if you stream new DOM
-  // showCorruptionLoading({ force: true }); // force-run outside 72h cadence
+  initCorruptedText();                       // Initialize glitch text effects
+  // showCorruptionLoading({ force: true }); // Force loader outside 72h cadence
 });
 ```
 
@@ -292,6 +404,89 @@ Class | Behavior
 ```
 All Nikke-specific helpers live alongside the main utilities (`src/css/nikke-utilities.css`) and observe the same token set, so there are no visual disconnects between game-specific and general UI.
 
+## Extension Components
+
+Production-tested components from whykusanagi.xyz for galleries, social links, countdowns, and more. All extension styles are included in `theme.css` or can be imported separately via `extensions.css`.
+
+### Gallery System
+
+Responsive gallery grid with filtering, lightbox, and NSFW content support.
+
+```html
+<div class="filter-bar">
+  <button class="filter-btn active" data-filter="all">All</button>
+  <button class="filter-btn" data-filter="photos">Photos</button>
+</div>
+
+<div class="gallery-container" id="my-gallery">
+  <div class="gallery-item" data-tags="photos">
+    <img src="image.jpg" alt="Description">
+    <div class="gallery-caption">Caption text</div>
+  </div>
+</div>
+```
+
+```javascript
+import { initGallery } from '@whykusanagi/corrupted-theme/gallery';
+
+const gallery = initGallery('#my-gallery', {
+  enableLightbox: true,
+  enableNsfw: true,
+  filterAnimation: true
+});
+
+gallery.filter('photos');     // Filter by category
+gallery.openLightbox(0);      // Open first image
+```
+
+### Social Links List
+
+Link-in-bio style layout with branded platform colors.
+
+```html
+<div class="social-links-container">
+  <img src="avatar.jpg" class="profile-avatar">
+  <h1 class="profile-name">@username</h1>
+  <p class="profile-bio">Your bio here</p>
+  <div class="link-list">
+    <a href="#" class="link-item twitter"><i class="fab fa-twitter"></i> Twitter</a>
+    <a href="#" class="link-item github"><i class="fab fa-github"></i> GitHub</a>
+  </div>
+</div>
+```
+
+### Countdown Widget
+
+Event countdown with configurable shapes (diamond, circle, heart, star, hexagon, octagon).
+
+```javascript
+import { initCountdown } from '@whykusanagi/corrupted-theme/countdown';
+
+initCountdown({
+  config: {
+    title: 'Launch Countdown',
+    eventDate: '2025-04-01T00:00:00-07:00',
+    completedMessage: 'Now Live!',
+    character: {
+      image: 'character.png',
+      background: { type: 'diamond' }
+    }
+  }
+});
+```
+
+### NSFW Content Blur
+
+Click-to-reveal overlay for sensitive content.
+
+```html
+<div class="gallery-item nsfw-content" data-warning="18+ Click to View">
+  <img src="sensitive-image.jpg" alt="Description">
+</div>
+```
+
+See `examples/extensions-showcase.html` for interactive demos and `docs/COMPONENTS_REFERENCE.md` for complete API documentation.
+
 ## Customization & Tokens
 Override only the tokens you need. The defaults intentionally mirror the showcase.
 ```css