Site Theming Research

Introduction

Site Structure Overview

Directory Organization

The Johnsen AI website follows a clean, modular organization pattern with clear separation of concerns:

/
├── index.html           # Main landing page
├── apps/                # Application pages
│   ├── apps.html        # Apps directory index
│   ├── coffee-app.html  # Coffee Journal app
│   ├── disc-app.html    # Disc collection tracker
│   ├── strong-app.html  # Workout tracker
│   ├── sunlight-app.html # Sunlight tracking app
│   └── tea-time-app.html # Tea timer app
├── research/            # Research and documentation
│   ├── research.html    # Research directory index
│   ├── hello-local.html # Hello Local Framework
│   ├── site-theming.html # Site theming documentation
│   ├── local-first-network.html # Local-first network architecture
│   └── home-lab.html    # Home lab setup documentation
├── games/               # Games and interactive experiences
│   ├── games.html       # Games directory index
│   ├── gone-fishing.html # Fishing game
│   └── kettlebell-game.html # Kettlebell workout game
├── tools/               # Utility tools
│   ├── tools.html       # Tools directory index
│   ├── coffee-timer.html # Coffee brewing timer
│   └── tea-timer.html   # Tea brewing timer
├── assets/              # Shared assets
│   ├── css/             # Stylesheets
│   │   ├── global/      # Global styles
│   │   │   ├── styles.css  # Base styles
│   │   │   ├── header.css  # Header styles
│   │   │   └── cards.css   # Card component styles
│   │   └── pages/       # Page-specific styles
│   │       ├── apps.css    # Apps page styles
│   │       └── research.css # Research page styles
│   ├── js/              # JavaScript files
│   │   ├── theme-toggle.js # Theme toggling functionality
│   │   └── app-specific/   # App-specific scripts
│   └── images/          # Image assets
│       ├── backgrounds/ # Ghibli-mode images
│       ├── app-banners/ # Real-mode images
│       └── icons/       # Site icons and logos
├── pwa/                 # Progressive Web App support
│   ├── manifest.json    # PWA manifest
│   └── sw.js            # Service worker
└── scripts/             # PowerShell utility scripts

File Naming Conventions

The Johnsen AI website follows consistent naming conventions for all files and assets:

# HTML Files
- Use lowercase with hyphens for multi-word filenames (e.g., disc-app.html)
- App pages use the app name followed by "-app" (e.g., coffee-app.html, strong-app.html)

# CSS Files
- Component-specific CSS uses kebab-case (e.g., jai-card.css, header.css)
- Global styles use descriptive names (e.g., styles.css)

# JavaScript Files
- Feature-specific JS files use kebab-case (e.g., theme-toggle.js, data-center.js)

# Image Assets
- All image assets use kebab-case with descriptive names (e.g., coffee-journal.webp)
- Ghibli-style images use descriptive names (e.g., tea-time.webp, disc-tracker.webp)
- Real-mode images use the app name followed by "-banner" (e.g., coffee-app-banner.svg)
- No spaces in filenames - always use hyphens for word separation

Apps

• coffee-app - Coffee Journal application
• disc-app - Disc collection tracker
• strong-app - Workout tracker
• sunlight-app - Sunlight tracking app
• tea-time-app - Tea timer application
• local-first-demo - Local-first network demo
• data-center-app - Data center management

Research

• hello-local - Hello Local Framework
• site-theming - Site theming documentation
• local-first-network - Local-first network architecture
• home-lab - Home lab setup documentation
• local-first-phone - Local-first phone integration
• claudoodle - Claudoodle research project

Games

• gone-fishing - Fishing game
• kettlebell-game - Kettlebell workout game

Tools

• coffee-timer - Coffee brewing timer
• tea-timer - Tea brewing timer

Page Types

• Apps: Utility web applications like Coffee Timer, Disc App, Strong App, etc.
• Games: Interactive games and entertainment projects
• Research: Experimental projects and research demonstrations like Hello Local Framework

File Naming Convention

All HTML files follow a consistent naming convention using kebab-case (hyphenated lowercase):

• Multi-word filenames: Words are separated by hyphens for better readability (e.g., coffee-app.html, tea-time-app.html)
• Single-word filenames: Remain as simple lowercase (e.g., index.html, apps.html)
• Benefits: Improves URL readability, SEO-friendly, and maintains consistency across the project

Common Header

Every page includes a standardized header for consistent navigation and branding:

• Structure: Logo + Site Name + Page Title, with responsive design for all screen sizes
• Implementation: Uses header.css for styling and may include header.js for interactive elements
• Accessibility: Includes skip-to-content link and proper semantic HTML structure

Navigation Structure

Each section has its own landing page that displays cards for the various projects within that category. These landing pages (projects.html, games.html, research.html) use a consistent card-based layout that works with both theme modes.

Project Card

Project Card

Project Card

CSS Organization

Modular CSS Structure

The site uses a modular CSS architecture with clear separation of concerns across different directories:

• /assets/css/global/ - Site-wide styles and common elements
• /assets/css/components/ - Reusable component styles
• /assets/css/pages/ - Page-specific styles

Key CSS Files

The CSS is organized into the following key files:

• global/styles.css: Base styles, utility classes, and common elements
• global/theme.css: CSS custom properties and theme variables
• global/components.css: Unified card system and reusable components
• layout/header.css: Standardized header implementation
• pages/apps.css: Styles specific to application pages
• pages/home.css: Styles specific to the homepage
• pages/research.css: Styles for research pages
• pages/games.css: Styles for game pages

Consistent Spacing

The site maintains consistent spacing across all pages:

• Header spacing: 60px margin-top for main content
• Content padding: 20px padding-top for content areas
• Component spacing: Standardized margins and padding for cards and sections

CSS Variables

The site uses CSS variables (custom properties) for consistent theming across both Ghibli and Real modes:

Global vs. Component Styles

The CSS architecture follows these principles:

• Global styles: Common elements, typography, and utility classes
• Component styles: Self-contained styles for reusable components
• Page-specific styles: Unique styling needs for individual pages

Responsive Design

The site follows mobile-first responsive design principles with consistent breakpoints:

Responsive Design

The Johnsen AI website follows a mobile-first responsive design approach, ensuring optimal user experience across all device sizes from smartphones to large desktop displays.

Mobile-First Philosophy

The site is built with a mobile-first philosophy, meaning that the base styles are designed for mobile devices, and then progressively enhanced for larger screens:

/* Base styles for mobile devices first */
.jai-container {
    display: grid;
    grid-template-columns: 1fr;  /* Single column on mobile */
    gap: 20px;
    width: 100%;
}

/* Tablet breakpoint */
@media (min-width: 768px) {
    .jai-container {
        grid-template-columns: repeat(2, 1fr);  /* Two columns on tablets */
        gap: 25px;
    }
}

/* Desktop breakpoint */
@media (min-width: 992px) {
    .jai-container {
        grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));  /* Multi-column on desktop */
        gap: 30px;
        max-width: 1000px;
    }
}

Consistent Breakpoints

The site uses consistent breakpoints across all components and pages:

• Small devices: Base styles (up to 767px)
• Medium devices: @media (min-width: 768px)
• Large devices: @media (min-width: 992px)
• Extra large devices: @media (min-width: 1200px)

Responsive Components

All components are designed to be fully responsive:

/* Base mobile header */
.site-logo span {
    display: block;  /* Show full logo text */
}

/* On smaller screens, hide the logo text */
@media (max-width: 768px) {
    .site-logo span {
        display: none;  /* Hide logo text, show only icon */
    }

    .header-title {
        font-size: 16px;  /* Smaller title */
    }
}

/* Ensure all images are responsive */
img {
    max-width: 100%;
    height: auto;
}

/* Specific handling for card images */
.jai-image img {
    width: 100%;
    height: 100%;
    object-fit: cover;  /* Maintain aspect ratio while filling container */
}

Viewport Configuration

All pages include proper viewport configuration to ensure correct rendering on mobile devices:

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

Responsive Considerations

The responsive design approach considers a variety of device types and screen sizes:

• Mobile phones: Small screens with touch interactions
• Tablets: Medium-sized screens in both portrait and landscape
• Desktops: Various window sizes from 1024px to 1920px+
• Different browsers: Consideration for various rendering engines

Ghibli Theme System

Theme Toggle Implementation

The theme toggle is implemented using JavaScript and CSS. A toggle button in the header allows users to switch between the two themes:

The theme toggle is implemented in theme-toggle.js. It provides a switch between "Ghibli Mode" (the default) and "Real Mode":

Core Functionality

💾

Theme Storage

User preference is stored in localStorage as "johnsenAI-themeMode"

localStorage.setItem('johnsenAI-themeMode', mode);

🔄

Toggle Button

A visual slider indicates the current theme with animated transitions

toggleSlider.style.transform = 'translateX(33px)';

🎨

Theme Application

Theme-specific styles and images are applied based on the selected mode

updateImages(currentMode);

Code Structure

The theming system is primarily handled by theme-toggle.js, which:

• Checks localStorage for saved theme preference
• Updates the toggle appearance based on the current mode
• Swaps images and applies CSS styles based on the selected theme
• Handles toggle button click events and updates localStorage

// Core theme toggle functionality toggleBtn.addEventListener('click', function() { currentMode = currentMode === 'ghibli' ? 'real' : 'ghibli'; // Save preference to localStorage localStorage.setItem('johnsenAI-themeMode', currentMode); // Update UI updateUI(currentMode); });

Image Swapping

One of the most visible aspects of the theme system is the automatic swapping of images between Ghibli-style illustrations and vector graphics:

Ghibli Mode

Features hand-drawn, Studio Ghibli-inspired artwork with forest scenes and whimsical illustrations.

Real Mode

Uses clean, professional vector graphics with a modern, minimalist aesthetic.

This is handled programmatically in the updateImages() function, which updates image sources based on the current theme and page.

Theme Switching Flow

1

User Clicks Toggle

The theme toggle button is clicked

↓

2

Update Mode Variable

currentMode is switched between 'ghibli' and 'real'

↓

3

Save Preference

New preference is saved to localStorage

↓

4

Update UI

Toggle appearance and page images are updated

JAI Card System

To ensure visual consistency across the site, we implemented a unified JAI (Johnsen AI) card system that standardizes the appearance and behavior of all card-based components. This system provides a consistent user experience while allowing for theme-specific styling.

Key Files

• assets/css/global/components.css - Core card styles and layout
• apps/apps.html - Implementation for apps page
• research/research.html - Implementation for research page
• games/games.html - Implementation for games page

Key Features

• Responsive Grid Layout: Automatically adjusts columns based on screen size
• Consistent Card Dimensions: Standardized height and proportions
• Interactive Elements: Hover effects, transitions, and focus states
• Proper Z-indexing: Ensures interactive elements are accessible
• Theme Compatibility: Works with both Ghibli and Real modes

Benefits

• Consistency: Unified appearance across all card-based pages
• Maintainability: Single source of truth for card styles
• Responsive: Adapts to different screen sizes
• Themeable: Uses CSS variables for easy theme switching
• Accessible: Built with proper ARIA labels and semantic HTML

The JAI card system is a core component of our design system, ensuring that all project cards, whether they're apps, research papers, or games, have a consistent and professional appearance while maintaining the unique character of each section.

Best Practices

The Johnsen AI website follows a set of established coding standards and best practices to ensure maintainability, readability, and consistency across the codebase.

CSS Naming Conventions

The site uses a consistent naming convention for CSS classes:

• Component-based naming: Classes are prefixed with component names (e.g., jai-card, header-title)
• Kebab-case format: Multi-word class names use hyphens (e.g., site-logo, theme-toggle)
• Descriptive names: Class names clearly describe their purpose (e.g., toggle-slider, back-button-container)

HTML Structure Guidelines

• Semantic HTML: Using appropriate elements (<header>, <main>, <footer>)
• Accessibility attributes: Including aria-label, alt text, and proper heading hierarchy
• Consistent indentation: 4-space indentation for nested elements
• Logical grouping: Related elements grouped in appropriate containers

Performance Considerations

• Image optimization: Using WebP format and appropriate sizing
• CSS minification: Production CSS is minified to reduce file size
• Efficient selectors: Avoiding deep nesting and overly specific selectors
• Reduced dependencies: Minimal use of external libraries and frameworks

Maintenance Guidelines

To maintain the codebase effectively, follow these guidelines:

1. Place new styles in the appropriate CSS file based on their scope (global, component, or page-specific)
2. Reuse existing components and styles whenever possible
3. Document any complex or non-obvious code with comments
4. Consider how changes will appear across different devices and browsers
5. Update this documentation when making significant architectural changes

Standardized Header Implementation

A consistent static header has been implemented across all pages of the Johnsen AI website to ensure a unified user experience and maintain brand identity. This standardized header replaces the previous JavaScript-generated headers with a more efficient and maintainable solution.

Header Structure

The standardized header consists of three main components in a grid layout:

• Site Logo (Left): Johnsen AI branding with navigation to homepage
• Page Title (Center): Context-specific title centered in the header
• Theme Toggle (Right): Ghibli/Real mode toggle button

CSS Implementation

The header styling is centralized in assets/css/global/header.css with these key features:

/* Fixed header styles for all pages */
.page-header {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    background-color: rgba(255, 255, 255, 0.95);
    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
    z-index: 100;
    backdrop-filter: blur(10px);
    -webkit-backdrop-filter: blur(10px);
    border-bottom: 1px solid var(--border-color);
}

.header-container {
    max-width: 1200px;
    margin: 0 auto;
    padding: 12px 20px;
    display: grid;
    grid-template-columns: 1fr auto 1fr;
    align-items: center;
}

/* Adjust main content to account for fixed header */
main {
    margin-top: 60px; /* Consistent space for the fixed header */
    padding-top: 20px; /* Consistent padding for content */
}

HTML Structure

Each page includes this standardized header markup:

<header class="page-header">
    <div class="header-container">
        <div class="site-logo">
            <a href="../index.html" aria-label="Go to homepage">
                <img src="../assets/images/icons/favicon.svg" alt="Johnsen AI Logo" width="32" height="32">
                <span>Johnsen AI</span>
            </a>
        </div>
        <h1 class="header-title">Page Title</h1>
        <div class="header-theme-toggle">
            <button id="theme-toggle-btn" aria-label="Toggle between Studio Ghibli and Real mode">
                <span class="toggle-icon ghibli-icon">🌳</span>
                <span class="toggle-icon real-icon">🌲</span>
                <span class="toggle-slider"></span>
            </button>
        </div>
    </div>
</header>

Key Features

• Consistent Spacing: 60px margin-top for main content with 20px padding-top
• Responsive Design: Adapts to different screen sizes with appropriate styling
• Accessibility: Proper aria-labels, semantic HTML, and skip-to-content link
• Performance: Static HTML implementation with optimized CSS
• Maintainability: Centralized styling in global/header.css

Implementation Across Site Sections

The standardized header has been implemented across all site sections:

• Main Pages: index.html, apps.html, research.html, games.html
• App Pages: All application pages (coffee-app.html, disc-app.html, etc.)
• Research Pages: All research pages including this site-theming document
• Special Pages: Limited access pages, error pages, and utility pages

This unified approach ensures that users have a consistent navigation experience throughout the site while maintaining the theme toggle functionality that is central to the site's dual-theme system.

Conclusion

The Johnsen AI website demonstrates thoughtful design and engineering practices through its dual-theme system and modular organization. The Ghibli/Real mode toggle provides a unique user experience while maintaining functionality and usability.

The CSS architecture, including the modular organization, standardized header, and JAI card system, enhances the maintainability and consistency of the site.

These approaches align with modern web development best practices, emphasizing:

• User-centered design
• Persistent user preferences
• Responsive layouts
• Progressive enhancement
• Modular code organization
• Accessibility and inclusivity

The Johnsen AI website serves as a showcase of effective web design and development practices, demonstrating how thoughtful architecture and consistent design principles can create a cohesive and maintainable codebase.

Local-First Network Approach

A key architectural decision in the Johnsen AI site is the implementation of a local-first network approach for applications. This approach includes:

• Local Storage: Using IndexedDB via the localForage library for reliable data persistence
• Data Organization: Separate stores for each application to maintain clean data boundaries
• Optional Cloud Sync: Encrypted synchronization for users who want to access their data across devices
• User Control: Complete control over viewing, modifying, and deleting personal data
• Offline-First: Applications function fully even without an internet connection
• Hello Local Framework: Following architectural principles detailed in the Hello Local research

This approach enhances user privacy, improves application performance, and ensures a seamless experience regardless of network conditions.

Local-First Network Approach

The Johnsen AI website implements a local-first network approach for its applications, prioritizing local data storage and offline functionality while providing optional cloud synchronization.

Core Components

• IndexedDB Storage: Using the localForage library to provide a simple key-value API with robust storage capabilities
• Application Data Isolation: Each application maintains its own data store for clean separation of concerns
• Offline-First Design: All core functionality works without an internet connection
• Optional Encrypted Sync: Data can be synchronized across devices with end-to-end encryption

This approach aligns with the Hello Local Framework principles, giving users control over their data while providing a seamless experience.

PWA Support

The Johnsen AI website is designed as a Progressive Web App (PWA), allowing users to install it on their devices and use it offline.

PWA Features

• Service Worker: Caches essential assets for offline use
• Web App Manifest: Defines how the app appears when installed
• Offline Functionality: Core features work without an internet connection
• Installation Prompt: Users can add the site to their home screen

Accessibility Features

The Johnsen AI website prioritizes accessibility to ensure all users can navigate and interact with the content effectively.

Implemented Features

• Semantic HTML: Proper use of headings, landmarks, and ARIA attributes
• Keyboard Navigation: All interactive elements are accessible via keyboard
• Skip to Content: Link at the top of each page to bypass navigation
• Focus Management: Visible focus indicators for keyboard users
• Color Contrast: WCAG AA-compliant color contrast ratios
• Alternative Text: Descriptive alt text for all images
• ARIA Attributes: Used appropriately to enhance screen reader compatibility
• Responsive Text Sizing: Text scales appropriately with browser settings

Customer Browser Resolutions

The Johnsen AI website is meticulously designed and optimized for specific customer browser resolutions. Rather than a generic responsive approach, each page and component is crafted to provide a perfect experience at these exact viewport dimensions. This precision ensures optimal layout, spacing, and functionality for our users' actual browsing environments.