Hysteresis Website Design Operational Documentation

Date: 2025-08-29 Version: v2.4 Next Agent: Web Design Continuation
Project: Experimental Cybernetic Consciousness Research Site Last Updated: 2025-08-29 - Timeline Structure Corrections & Documentation Consolidation

VERSIONING PROTOCOL: All updates to this document must include date stamps and version increments. Document version history below.

CRITICAL OPERATIONAL PROTOCOL

🚨 ELEVATED PRIVILEGES WARNING 🚨

NO AGENT MAY DELETE OR ARCHIVE CONTENT WITHOUT EXPLICIT PERMISSION

File deletion, content archiving, and content removal are ELEVATED PRIVILEGES reserved for project management only. Agents must make RECOMMENDATIONS ONLY.

Violation of this protocol will result in public flogging with a wet noodle.

Version History & Updates

v2.4 - August 29, 2025 - Timeline Structure Corrections & Documentation Consolidation

Timeline Issue Identified: Current implementation uses horizontal stream lines with index-based positioning instead of vertical parallel timelines with date-based positioning per user requirements. Problem: Timeline shows entries spaced by database order rather than actual temporal relationships. User Requirement: Four parallel vertical lines running closely together, each stream autonomous with date-based vertical positioning. Documentation: Consolidated handoff document information into operational document.

v2.3 - August 28, 2025 - Interactive Timeline System Implementation

Feature: Vertical timeline with importance-based horizontal positioning Files Created/Modified:

/layouts/_default/timeline.html - Custom Hugo template with SVG timeline rendering
/content/technical/h1-timeline.md - Timeline page with layout directive
/content/timeline/ directory - Markdown-driven timeline entries

Technical Specification:

Visual Design: Center-normalized vertical spine (x=500) with events positioned horizontally
Positioning Algorithm: horizontal_offset = importance_value × 35px
Stream Color Coding: Concept (#8B1538), Design (#333333), Code (#6B46C1), Logistics (#8B4513)
SVG Dimensions: 1000×1200 viewBox with responsive scaling
Interactive Features: Clickable markers, modal popups, cross-stream dependency visualization

Double Title Issue Resolution: Established protocol for preventing frontmatter/content H1 duplication

v2.2 - August 26, 2025 - Code Block Styling & Status Indicators

Code Block Styling Overhaul: Light grey backgrounds (#f5f5f5) with dark text (#333333) for improved readability H2 Species Banner: Diagonal “Research Pending” banner system with .research-pending CSS class Files Modified: baseof.html (syntax highlighting), species/hysteresis-ii.md (status banner)

Aesthetic Framework: Adbusters/design anarchy approach - underground academic journal Typography System: Mixed serif (Crimson Text) and sans-serif (Inter) Chaos Elements: Subtle background textures, overlapping elements, ink bleed effects Anti-Corporate Stance: GitLab hosting to avoid Microsoft/GitHub monopoly

Current Status: STABLE & FUNCTIONAL + INTERACTIVE TIMELINE (IMPLEMENTATION ISSUES)

The site is now operational at hysteresis.ca with a sophisticated design aesthetic and robust technical foundation. Do not attempt major redesigns - the current approach is working well.

TIMELINE STATUS: Interactive timeline system implemented but requires structural corrections - current implementation uses wrong positioning logic (horizontal lanes + index spacing instead of vertical parallel streams + date positioning).

Technical Architecture

Platform: Hugo static site generator

Why Hugo: Jekyll was dependency hell nightmare. Hugo is fast, reliable, zero dependencies
Hosting: GitLab Pages for CI/CD deployment and static hosting
Anti-Corporate Stance: Using GitLab to avoid Microsoft/GitHub monopoly. This is intentional.
Deployment: Automatic via .gitlab-ci.yml on pushes to master branch
Build Time: ~50ms, extremely fast

GitLab Commit Limitations:

Max files per commit: ~10-15 files before triggering pre-receive hook failures
Error message: “500 Internal Server Error” + “pre-receive hook declined”
Solution: Batch commits to 5-8 files maximum to avoid anti-abuse filters
Not documented: GitLab’s bulk upload thresholds are undisclosed policy enforcement

Timeline Entry Frontmatter Structure:

---
title: "Event Title"
date: 2025-08-04
stream: "code"           # concept, design, code, logistics  
importance: 8            # 1-10 scale for horizontal positioning
connections: ["2025-07-25-concept-psychology"]
summary: "Brief description"
---

Repository Structure:

content/
├── _index.md           # Homepage content
├── species/           # H1, H2 species docs
├── research/          # Research articles
├── timeline/          # Timeline visualization entries (frontmatter-based)
└── technical/         # Technical documentation
    ├── h1-design-evolution.md    # Monolithic evolution doc
    └── h1-milestones/           # Detailed H1 development documentation

layouts/
├── _default/baseof.html    # Base template with chaos elements
├── index.html              # Homepage layout
├── _default/single.html    # Article pages
├── _default/list.html      # Section listing pages
└── timeline-section.html   # Timeline visualization template (STRUCTURAL ISSUES)

Design Philosophy: Sophisticated Subversion

Final Aesthetic: Adbusters/design anarchy approach - underground academic journal

NOT juvenile rebellion (avoid neon colors, “CLASSIFIED” stamps, chaotic rotations)
Intellectual subversion through typography and layout choices
Clean black/white palette with strategic rule-breaking
Mixed serif (Crimson Text) and sans-serif (Inter) typography

Key Design Principles:

Sophisticated Typography: Professional hierarchy with intentional imperfections
Strategic Asymmetry: Intentional misalignments that feel purposeful, not chaotic
Controlled Chaos: Subtle background texture, overlapping elements, printing errors
Anti-Corporate: Clean design that subtly rebels against sterile corporate aesthetics

Issue Date: September 2, 2025 Status: ✅ RESOLVED Agent: Mobile menu implementation and debugging

Symptoms:

Hamburger menu button appeared correctly on mobile
Clicking hamburger showed empty overlay with no menu entries
Desktop navigation dropdown worked properly
Mobile menu overlay appeared but contained no content

Root Causes Identified:

Hugo Menu Configuration: Missing proper menu structure in config.yaml
CSS Class Conflicts: Mobile menu CSS classes not rendering content properly
JavaScript Functionality: Mobile menu toggle worked but content wasn’t visible
Template Context Issues: Hugo template context loss in menu loops (.Site vs $.Site)

Technical Investigation Process

Debugging Sequence:

Hugo Config Verification: Discovered config.yaml menu structure was incomplete
JavaScript Testing: Confirmed hamburger functionality worked, overlay appeared
CSS Class Elimination: Hardcoded content with inline styles bypassed CSS issues
Template Context Fix: Used $.Site.Menus.research instead of .Site.Menus.research in loops
Inline Style Implementation: Bypassed problematic CSS classes entirely

Critical Discovery: Hugo’s CSS classes for mobile menu were not applying properly. Inline styles provided reliable alternative.

Solution Implementation

Hugo Menu Configuration Fixed:

# config.yaml structure implemented
menu:
  main:
    - name: "Home"
      url: "/"
      weight: 10
    - name: "Species"  
      url: "/species/"
      weight: 20
    - name: "Research"
      url: "/research/"
      weight: 30
    - name: "Technical"
      url: "/technical/"
      weight: 40
  research:
    - name: "Analysis"
      url: "/research/analysis/"
      weight: 31
    - name: "Theoretical"
      url: "/research/theoretical/"
      weight: 32
  technical:
    - name: "Documentation"
      url: "/technical/documentation/"
      weight: 41

Mobile Menu Template Structure:

Dynamic Content: Uses Hugo’s menu system ({{ range .Site.Menus.main }})
Inline Styles: Bypasses CSS class issues with direct styling
JavaScript Hover: onmouseover/onmouseout handlers for reliable hover states
Dropdown Functionality: Working accordions for Research/Technical submenus

Color-Coded Hover States:

Research Items: Red background (#ff0000) on hover/tap
Other Items: Black background (#000) on hover/tap
Text: White text on colored backgrounds for readability

Current Implementation

Mobile Menu Features:

✅ Hamburger icon with smooth animation to X
✅ Full-screen overlay with site branding
✅ Dynamic navigation from Hugo’s menu system
✅ Working dropdown accordions (Research → Analysis/Theoretical, Technical → Documentation)
✅ Color-coded hover states matching site aesthetic
✅ Auto-closes when clicking navigation links
✅ Body scroll lock when menu open
✅ Maintains black/white site aesthetic

Technical Approach:

Reliability: Inline styles prevent CSS class conflicts
Maintainability: Dynamic content updates automatically when config.yaml changes
Performance: Minimal JavaScript, no external dependencies
Aesthetic: Matches sophisticated underground academic journal design

JavaScript Implementation:

// Direct DOM manipulation for reliability
const hamburger = document.querySelector('.menu-toggle');
const menu = document.querySelector('.mobile-menu');

// Inline style manipulation bypasses CSS issues
hamburger.onclick = function() {
    menu.style.display = menu.style.display === 'block' ? 'none' : 'block';
    // Additional styling for overlay positioning
};

Lessons Learned:

Hugo’s CSS classes can be unreliable - inline styles provide greater control
Template context matters - use $.Site in loops to maintain root context
JavaScript debugging essential - DOM manipulation confirms element existence
Mobile menu complexity - full-screen overlays require careful state management

Files Modified:

/config.yaml - Menu structure configuration
/layouts/_default/baseof.html - Mobile menu HTML structure and JavaScript
/content/research/analysis/_index.md - Analysis section landing page
/content/technical/_index.md - Technical section overview
/content/technical/documentation/_index.md - Documentation section

Maintenance Notes

Adding New Menu Items:

Update /config.yaml menu structure
Mobile menu automatically inherits changes
No template modifications required for basic additions

Customising Hover Colors:

Modify onmouseover JavaScript in template
Current: Research=red, others=black
Easy to add new color schemes per section

Future Considerations:

Mobile menu works reliably with inline styles
CSS class approach could be revisited if Hugo template issues resolved
Current implementation prioritises functionality over code elegance

Issue Date: September 2, 2025 Status: ✅ COMPLETED Agent: Logo redesign with scanning line effect and hysteresis motion

Design Implementation

Enhanced Header Logo Features:

Split Design: “HYSTERESIS” (heavy sans-serif, black background) + “Matter Learns / To Remember” (serif, red outline)
Scanning Line Effect: 5px white vertical line with color inversion using mix-blend-mode: difference
Hysteresis Motion: True hysteresis curve scanning (forward path differs from backward path)
Seamless Connection: No gap between black and red boxes, perfect height matching

Technical Implementation

Typography Hierarchy:

.logo-hysteresis {
    font-family: 'Inter', sans-serif;
    font-weight: 900;
    background: #000;
    color: #fff;
    font-size: 1.8rem;
    letter-spacing: 2px;
}

.logo-tagline {
    font-family: 'Crimson Text', serif;
    font-weight: 600;
    border: 4px solid #ff0000;
    border-left: none;
}

Hysteresis Scanning Animation:

6-second cycle with asymmetric forward/backward paths
Forward motion: -10px → 20px → 140px → 190px (accelerating)
Backward motion: 190px → 160px → 40px → -10px (different deceleration)
Color inversion: White scanning line inverts black text to white, black background to white

Layout Engineering:

align-items: stretch ensures both boxes match height automatically
gap: 0 eliminates whitespace between elements
border-left: none on red box creates seamless visual connection
Increased HYSTERESIS padding (0.8rem) to match red box proportions

Design Philosophy Integration

Underground Tech Aesthetic:

Scanning line evokes CRT monitor/terminal interfaces
Hysteresis motion directly references project’s electromagnetic memory themes
Color inversion creates retro computing visual effect
Split typography maintains sophisticated academic hierarchy while adding technical edge

Brand Identity:

“HYSTERESIS” as dominant technical term in heavy sans-serif
“Matter Learns / To Remember” as explanatory tagline in academic serif
Red accent introduces color sparingly within black/white palette
Seamless boxes suggest integrated technical documentation

Responsive Design

Mobile Adaptations:

Stacks vertically on mobile devices
Reduced font sizes maintain readability
Scanning animation continues to work across screen sizes
Proportional scaling preserves visual balance

Files Modified

/layouts/_default/baseof.html - Header logo structure and CSS animations
Applied to both desktop header and mobile menu header
Maintains consistency across all site templates

Maintenance Notes

Animation Timing:

6-second cycle provides good visibility of hysteresis effect
Easy to adjust keyframe percentages for different motion patterns
mix-blend-mode: difference ensures scanning line works on any background

Brand Consistency:

Logo structure now used consistently in desktop header and mobile menu
Red accent color can be extended to other design elements if needed
Scanning effect could be applied to other technical elements

Performance:

CSS-only animation with minimal performance impact
No JavaScript dependencies for logo functionality
Scales well across device types

Interactive Timeline Implementation (STRUCTURAL ISSUES)

🚨 CRITICAL ISSUE: Wrong Timeline Structure 🚨

Problem: Current implementation creates horizontal stream lines with index-based positioning instead of vertical parallel timelines with date-based positioning.

User Requirement: Four parallel vertical lines running closely together, each stream autonomous.

Current Implementation Problems:

Horizontal stream lines at fixed Y coordinates (150, 250, 350, 450)
Index-based positioning (add 100 (mul $index 150)) instead of date-based
Hub-and-spoke model with central spine instead of parallel autonomous streams

Required Changes:

Four vertical lines at close X coordinates (e.g., x=200, 250, 300, 350)
Date-to-Y-coordinate conversion for temporal positioning
Remove central spine, make each stream independent
Calculate vertical position from actual dates, not entry order

Previous Hugo Template Issues Resolved: Template parsing errors from earlier versions have been resolved through simplified coordinate calculations.

Interactive Timeline Implementation (ATTEMPTED)

Angled Stream Timeline Features:

Visual Design: Angled lead-in connections with proximity-based routing per user sketch requirements
Color Palette: Red (Concept), Grey (Design), Purple (Code), Brown (Logistics)
Stream Mirroring: Left streams (Concept/Logistics), Right streams (Design/Code)
Interactive Elements: Clickable timeline markers with modal popups and download links
Angled Connections: SVG quadratic curves creating organic lead-ins to timeline spine
Responsive SVG: 1000x800 viewBox with proper scaling across devices

Technical Implementation:

SVG Path Generation: Curved connections using quadratic (Q) commands for angled approach
Stream Positioning Logic: Importance-based horizontal offset (40px multiplier)
Modal System: Interactive popups with development details and download functionality
Hugo Template Integration: Clean variable assignment avoiding parsing errors

Content Strategy

Current Sections:

Species: Only Hysteresis I is active (H2 removed as not in development)
Research: Theoretical framework documents
Technical: H1 design evolution, morphological development, interactive timeline

Timeline Implementation Files:

/content/timeline/ - Individual markdown files with timeline: true frontmatter (extensible system)
/layouts/timeline-section.html - Dynamic template for timeline visualization (BLOCKED by Hugo parsing)
/layouts/shortcodes/timeline.html - OLD leftover shortcode (should be deleted)

H1 Documentation Files (NOT timeline implementation):

/content/technical/h1-milestones/ - Detailed H1 development documentation (renamed from h1-timeline)
Contains comprehensive milestone specs, design philosophy, technical analysis
No connection to timeline visualization feature

Content Approach:

Academic underground tone
Technical precision with creative language
Biological taxonomy framework for organization
Research legitimacy maintained throughout

What Works & Must Be Preserved

Hugo Build System - Fast, reliable, zero dependency issues
GitLab Deployment - Anti-corporate choice, works perfectly
Current Aesthetic - Sophisticated subversion without juvenile elements
Typography Mix - Serif/sans strategic combination
Chaos Elements - Subtle imperfections that add character
Content Structure - Clean organization that scales
Interactive Timeline - Professional technical documentation with research functionality

Future Development Directions

Enhancement Opportunities:

Media Integration: Photo galleries of H1 evolution stages
Interactive Elements: ✅ COMPLETED - Interactive timeline with hover states and modal system
Content Expansion: More research documentation, technical drawings
Performance: Already fast, but could optimize images when added

File Cleanup Status:

✅ /content/technical/h1-timeline/ renamed to /content/technical/h1-milestones/ (eliminates naming confusion)
⚠️ /layouts/shortcodes/timeline.html - OLD hardcoded JSON approach (should be deleted)
🚨 /layouts/timeline-section.html - Timeline template BLOCKED by Hugo parsing errors

Technical Considerations:

Site loads very fast due to minimal CSS/JS
All styling inline in templates for simplicity
Interactive timeline adds minimal overhead
Hugo’s asset pipeline available if needed for media

Critical Design Guidelines

DO:

Maintain sophisticated aesthetic
Use subtle chaos elements strategically
Keep typography hierarchy clean
Add content that supports research legitimacy
Preserve anti-corporate stance
Enhance interactive features that serve research goals

DON’T:

Revert to neon cyberpunk aesthetics
Add juvenile “rebellious” elements
Overcomplicate the technical stack
Break the typography hierarchy
Compromise GitLab hosting choice
Add interactivity for its own sake

Content Management

Adding New Pages:

Create .md file in appropriate content/ subdirectory
Include proper frontmatter with title, date, tags
Use Hugo’s automatic section organization

Interactive Timeline Updates:

Add timeline entries to content files with proper frontmatter (timeline: true)
Timeline template automatically generates angled connections
Stream assignment determines left/right positioning and color
Modal data populated from entry metadata

Key Frontmatter:

---
title: "Page Title"
date: 2024-01-01
draft: false
tags: ["research", "technical"]
summary: "Brief description for listings"
---

Success Metrics

The site successfully:

Loads extremely fast (Hugo static generation)
Looks professional yet subtly rebellious
Maintains academic legitimacy for research
Avoids corporate sterility without juvenile chaos
Deploys automatically via GitLab CI/CD
Scales easily for content additions
Provides interactive research documentation with download functionality
Visualizes complex development relationships through timeline interface

Agent Handoff Notes

The design philosophy took several iterations to perfect. The current sophisticated approach works well for experimental cybernetic research content. Avoid major aesthetic overhauls - focus on content enhancement and subtle improvements within the established framework.

The interactive timeline represents a significant enhancement, providing professional technical documentation with research functionality while maintaining the underground academic aesthetic. The transit map visual approach successfully balances technical precision with engaging presentation.

The subtle chaos elements are precisely calibrated - they add underground character without overwhelming the clean design. Preserve this balance in any future modifications.

Status: Production Ready (Timeline Implementation BLOCKED)
Critical Blocker: Hugo template parsing errors preventing timeline deployment
Next Priority: Resolve timeline template issues or implement alternative approach
Agent Handoff Issue: Multiple cycles of template complexity → parsing errors → simplification → still fails

Hysteresis Website Design Operational Documentation

CRITICAL OPERATIONAL PROTOCOL

Version History & Updates

v2.4 - August 29, 2025 - Timeline Structure Corrections & Documentation Consolidation

v2.3 - August 28, 2025 - Interactive Timeline System Implementation

v2.2 - August 26, 2025 - Code Block Styling & Status Indicators

Current Status: STABLE & FUNCTIONAL + INTERACTIVE TIMELINE (IMPLEMENTATION ISSUES)

Technical Architecture

Design Philosophy: Sophisticated Subversion

Mobile Navigation Implementation & Fix

Problem: Mobile Navigation Not Working

Technical Investigation Process

Solution Implementation

Current Implementation

Maintenance Notes

Header Logo Design Enhancement

Design Implementation

Technical Implementation

Design Philosophy Integration

Responsive Design

Files Modified

Maintenance Notes

Interactive Timeline Implementation (STRUCTURAL ISSUES)

Interactive Timeline Implementation (ATTEMPTED)

Content Strategy

What Works & Must Be Preserved

Future Development Directions

Critical Design Guidelines

Content Management

Success Metrics

Agent Handoff Notes

Hysteresis Website Design Operational Documentation

CRITICAL OPERATIONAL PROTOCOL

Version History & Updates

v2.4 - August 29, 2025 - Timeline Structure Corrections & Documentation Consolidation

v2.3 - August 28, 2025 - Interactive Timeline System Implementation

v2.2 - August 26, 2025 - Code Block Styling & Status Indicators

v2.1 - August 25, 2025 - Foundation Refinements

Current Status: STABLE & FUNCTIONAL + INTERACTIVE TIMELINE (IMPLEMENTATION ISSUES)

Technical Architecture

Design Philosophy: Sophisticated Subversion

Mobile Navigation Implementation & Fix

Problem: Mobile Navigation Not Working

Technical Investigation Process

Solution Implementation

Current Implementation

Maintenance Notes

Header Logo Design Enhancement

Design Implementation

Technical Implementation

Design Philosophy Integration

Responsive Design

Files Modified

Maintenance Notes

Interactive Timeline Implementation (STRUCTURAL ISSUES)

Interactive Timeline Implementation (ATTEMPTED)

Content Strategy

What Works & Must Be Preserved

Future Development Directions

Critical Design Guidelines

Content Management

Success Metrics

Agent Handoff Notes