CSS and Styling System

Relevant source files

Purpose and Scope

This document describes the CSS and styling architecture used across all pages in the lzwjava.github.io repository. It covers the single-stylesheet approach, cache-busting strategy, theme color system, CSS class naming conventions, component styling patterns, and the dark mode CSS variable system. For information about the JavaScript-based dark mode toggle mechanism, see Theme Toggle System. For details on the HTML structure that these styles are applied to, see Common UI Components.

Stylesheet Architecture

The site uses a single centralized stylesheet with version-based cache-busting to ensure users always receive the latest styles after deployments.

Single Stylesheet Approach

All pages load the same CSS file located at /assets/css/style.css. The stylesheet link appears in the <head> section of every HTML page with a Git commit hash appended as a query parameter:

This approach provides several advantages:

Consistent styling across all pages without duplication
Browser caching for performance while ensuring updates are delivered
Single point of maintenance for all visual changes
Reduced bandwidth for repeat visitors due to caching

The version parameter (v=5afcd9d57c72b12a169e2425d6ace0c679143dd5) corresponds to the Git commit SHA, automatically updated by Jekyll during the build process. When the CSS file changes, the hash changes, forcing browsers to download the new version.

Stylesheet Loading Flow:

Sources: _site/01.ai-yi-fall-en.html80 _site/10yo-en.html80 _site/2025-llm-comparison-en.html80

Theme Color System

The site defines a primary theme color used throughout the interface and in mobile browser chrome.

Primary Color Definition

The primary theme color is #157878 (a teal/cyan shade). This color is declared in multiple contexts:

HTML Meta Tag for mobile browser UI:
Apple Mobile Web App Status Bar:

The theme-color meta tag instructs mobile browsers (Android Chrome, Safari) to color the browser's address bar and UI elements to match the site's color scheme. The black-translucent style for iOS provides a semi-transparent black status bar that overlays the content.

Theme Color Application

While the CSS file itself is not visible in the provided files, the #157878 color is likely used for:

Header backgrounds
Button hover states
Link colors
Accent borders and highlights

Theme Color Configuration:

Sources: _site/01.ai-yi-fall-en.html52-53 _site/10yo-en.html52-53 _site/2025-llm-comparison-en.html52-53

Responsive Design Configuration

The site implements mobile-first responsive design through viewport meta tags and CSS media queries.

Viewport Meta Tag

Every page includes a standard viewport configuration:

This configuration:

Sets the viewport width to match the device's screen width
Disables initial zoom (scale=1)
Enables responsive CSS media queries to function correctly
Prevents horizontal scrolling on mobile devices

The viewport tag is essential for the site's responsive behavior, ensuring content scales appropriately on devices ranging from smartphones (320px wide) to desktop monitors (1920px+ wide).

Viewport Configuration Impact:

Attribute	Value	Effect
`width`	`device-width`	Viewport width matches screen width
`initial-scale`	`1`	No zoom on page load
Default behavior	-	User can pinch-zoom (not disabled)
Maximum-scale	Not set	Unlimited zoom allowed (accessibility)

Sources: _site/01.ai-yi-fall-en.html51 _site/10yo-en.html51 _site/2025-llm-comparison-en.html51

CSS Class Naming Conventions

The HTML structure reveals a consistent class naming pattern that organizes styles by component type and purpose.

Layout Classes

Main Content Container:

main-content: Primary wrapper for page content
post-content: Additional class applied to blog post pages
content (id): Identifier for the main content area

Container Classes:

title-row: Wrapper for title sections
post-title-row: Specific to post title layout
button-container: Flex container for button groups
audio-container: Wrapper for audio player elements

Component Classes

Typography:

title: Generic title styling
post-title: Specific post title formatting

Interactive Elements:

button: Base button class shared by all buttons
left-button: Positioned to the left of button container
right-button: Positioned to the right of button container
icon-button: Button containing only an icon (theme toggle)
pdf-button: Commented out in current implementation

Icons:

sunIcon (id): SVG sun icon for light mode
moonIcon (id): SVG moon icon for dark mode

Class Hierarchy

Sources: _site/01.ai-yi-fall-en.html107-196 _site/10yo-en.html107-196 _site/2025-llm-comparison-en.html107-196

Component Styling Patterns

Each UI component follows consistent styling patterns across all pages.

Main Content Area

The main content wrapper uses multiple classes for layered styling:

id="content": Provides a unique anchor for navigation and JavaScript targeting
class="main-content": Applies base container styles (padding, max-width, centering)
class="post-content": Adds post-specific typography and spacing
role="main": ARIA landmark for accessibility

Title Row Component

The title row uses a double-class pattern (.title-row + .post-title-row) allowing for:

Base row styling (flex layout, alignment)
Post-specific overrides (font size, spacing)

Button Container Layout

The button container uses a flex-based layout for responsive button positioning:

Button Positioning Strategy:

Class	Position	Typical Use
`.button.left-button`	Left-aligned	Home, Back buttons
`.button` (no modifier)	Center/flow	Date display button
`.button.icon-button`	Right (via inline style)	Theme toggle
`.button.right-button`	Right-aligned	Language selector, Donate

Note: The theme toggle uses style="float: right; margin-bottom: 5px;" for positioning, combining inline styles with class-based styling.

Icon Visibility States

SVG icons within the theme toggle button are initially hidden:

The dark-mode.js script controls visibility by toggling between these states. This prevents a flash of unstyled content (FOUC) before JavaScript loads.

Component Styling Architecture:

Sources: _site/01.ai-yi-fall-en.html115-188 _site/10yo-en.html115-188 _site/2025-llm-comparison-en.html115-188

Dark Mode CSS Architecture

The dark mode system relies on CSS variables and class-based theming controlled by the dark-mode.js module.

CSS Variable System

While the actual CSS file is not provided, the HTML structure and JavaScript interactions reveal the dark mode implementation pattern:

CSS Variables are defined in the stylesheet for theme-dependent values:
- Background colors
- Text colors
- Border colors
- Button styles
Body Class Toggling: The dark-mode.js script adds/removes a class on the <body> element (likely .dark-mode or similar) that triggers CSS variable changes.
LocalStorage Persistence: Theme preferences are stored in localStorage and restored on page load.

Icon State Management

The theme toggle button controls two SVG icons that swap visibility:

Light Mode State:

#sunIcon → display: block (visible)
#moonIcon → display: none (hidden)

Dark Mode State:

#sunIcon → display: none (hidden)
#moonIcon → display: block (visible)

The aria-label="Toggle Theme" attribute provides accessibility for screen readers.

Theme Application Flow

Assumed CSS Variable Structure:

Sources: _site/01.ai-yi-fall-en.html153-172 _site/10yo-en.html153-172 _site/2025-llm-comparison-en.html153-172 _site/01.ai-yi-fall-en.html259

Mobile and Cross-Platform Styling

The styling system includes platform-specific optimizations for iOS and Android devices.

iOS-Specific Configuration

The site includes iOS-specific meta tags:

This creates a semi-transparent black status bar that overlays the content when the site is added to the iOS home screen as a web app.

iOS Status Bar Styles:

Value	Effect
`default`	White status bar
`black`	Black status bar
`black-translucent`	Black translucent overlay

The black-translucent value chosen allows content to extend behind the status bar, creating an immersive full-screen experience.

Mobile Button Considerations

The button container's inline styles include mobile-specific adjustments:

The margin-bottom: 5px provides additional touch target spacing on mobile devices, improving usability on smaller screens.

Audio Player Mobile Behavior

The audio player is initially hidden with inline styles:

This prevents layout shifts on mobile devices. The audio.js module controls when the player becomes visible, ensuring responsive behavior across screen sizes.

Mobile Styling Considerations:

Sources: _site/01.ai-yi-fall-en.html51-53 _site/01.ai-yi-fall-en.html153 _site/01.ai-yi-fall-en.html192

Inline Style Override Patterns

While the site primarily uses class-based styling, several components use inline styles for specific positioning needs.

Theme Toggle Positioning

The inline float: right ensures the theme toggle always appears on the right side of the button container, regardless of button order in the HTML.

Audio Player Initial State

The inline display:none hides the audio player until audio.js determines it should be shown, preventing layout jumps during page load.

SVG Icon Initial State

Both icons start hidden to prevent a flash where both icons are visible before JavaScript initializes the correct theme state.

Inline vs. Class-Based Styling:

Element	Inline Styles	Class Styles	Reason for Inline
`#themeTogglePost`	`float: right; margin-bottom: 5px;`	`.button .icon-button`	Override flex layout for fixed position
`#audioPlayer`	`display:none;`	`.audio-container` styles	Prevent FOUC, controlled by JS
`#sunIcon`, `#moonIcon`	`display: none;`	SVG styles	Prevent dual icon flash

This progressive enhancement approach ensures the page is usable even before JavaScript loads, with inline styles providing critical initial states that JavaScript later manipulates.

Sources: _site/01.ai-yi-fall-en.html153 _site/01.ai-yi-fall-en.html155-171 _site/01.ai-yi-fall-en.html192

Cache-Busting Strategy

The stylesheet versioning system ensures users always receive the latest CSS updates after deployments.

Git Commit-Based Versioning

The version hash appended to the stylesheet URL is generated from the Git commit SHA:

This approach provides:

Automatic versioning: Jekyll generates the hash during build
Cache invalidation: Browser requests new CSS when version changes
No manual intervention: Developers don't need to update version numbers
Deterministic: Same commit always produces same hash

Browser Caching Behavior

Cache Flow:

Benefits of This Strategy:

Performance: Unchanged CSS is cached indefinitely
Consistency: All users see the same styles after update
Simplicity: No complex cache headers needed
Reliability: Hash collision is virtually impossible with full Git SHA