From bf41df9ad631d3e826bd653832952a9d2a9c3104 Mon Sep 17 00:00:00 2001
From: Commander1024 <commander@commander1024.de>
Date: Sun, 26 Jul 2026 22:08:55 +0200
Subject: [PATCH] Document theme behavior and format editor styles

---
 404.php                    |  3 ++-
 archive.php                |  3 ++-
 assets/js/theme.js         |  4 ++++
 comments.php               |  4 +++-
 editor-style.css           | 42 +++++++++++++++++++++++++++++++++++++-
 footer.php                 |  3 ++-
 front-page.php             |  7 +++++--
 functions.php              |  5 +++++
 header.php                 |  7 +++++--
 index.php                  |  3 ++-
 page.php                   |  3 ++-
 search.php                 |  7 +++++--
 searchform.php             |  1 +
 single.php                 | 12 +++++++----
 style.css                  |  6 ++++++
 template-parts/content.php |  6 ++++--
 16 files changed, 97 insertions(+), 19 deletions(-)

diff --git a/404.php b/404.php
index f3d22e0..eb17d9b 100644
--- a/404.php
+++ b/404.php
@@ -1,3 +1,4 @@
-<?php get_header(); ?>
+<?php // WordPress uses this fallback template when no more-specific request template matches.
+get_header(); ?>
 <main id="main" class="site-main not-found"><p class="hero-eyebrow"><?php esc_html_e( 'Error 404', 'c1024-2026' ); ?></p><h1 class="page-title"><?php esc_html_e( 'Signal lost.', 'c1024-2026' ); ?></h1><p><?php esc_html_e( 'The page you requested could not be found. Search the archive or return to the home page.', 'c1024-2026' ); ?></p><?php get_search_form(); ?><p><a class="button" href="<?php echo esc_url( home_url( '/' ) ); ?>"><?php esc_html_e( 'Return home', 'c1024-2026' ); ?></a></p></main>
 <?php get_footer();
diff --git a/archive.php b/archive.php
index 3f0cb2d..84f8853 100644
--- a/archive.php
+++ b/archive.php
@@ -1,4 +1,5 @@
 <?php get_header(); ?>
 <header class="page-header"><h1 class="page-title"><?php the_archive_title(); ?></h1><?php the_archive_description( '<div class="archive-description">', '</div>' ); ?></header>
-<main id="main" class="site-main"><?php if ( have_posts() ) { while ( have_posts() ) { the_post(); get_template_part( 'template-parts/content' ); } the_posts_pagination( array( 'mid_size' => 1 ) ); } ?></main>
+<main id="main" class="site-main"><?php // Archive queries use the shared card template and WordPress pagination.
+if ( have_posts() ) { while ( have_posts() ) { the_post(); get_template_part( 'template-parts/content' ); } the_posts_pagination( array( 'mid_size' => 1 ) ); } ?></main>
 <?php get_footer();
diff --git a/assets/js/theme.js b/assets/js/theme.js
index 57da0d2..43db2ed 100644
--- a/assets/js/theme.js
+++ b/assets/js/theme.js
@@ -1,4 +1,5 @@
 (() => {
+	// Cycle the persisted preference; CSS resolves "auto" from the system setting.
 	const root = document.documentElement;
 	const colorModes = ['auto', 'light', 'dark'];
 	const storedTheme = localStorage.getItem('c1024-theme');
@@ -24,6 +25,7 @@
 		});
 	}
 
+	// Hide the sticky header only while scrolling down past its own height; batch scroll work per frame.
 	const header = document.querySelector('.site-header');
 	let lastY = window.scrollY;
 	let ticking = false;
@@ -38,6 +40,7 @@
 		});
 	}, { passive: true });
 
+	// Keep the search panel accessible and close it when focus moves outside its controls.
 	const searchToggle = document.querySelector('[data-search-toggle]');
 	const searchPanel = document.querySelector('[data-search-panel]');
 	if (searchToggle && searchPanel) {
@@ -54,6 +57,7 @@
 		});
 	}
 
+	// The mobile trigger controls the header class consumed by the responsive navigation CSS.
 	const menuToggle = document.querySelector('[data-menu-toggle]');
 	if (menuToggle && header) menuToggle.addEventListener('click', () => {
 		const open = header.classList.toggle('menu-open');
diff --git a/comments.php b/comments.php
index b43285b..9bc7262 100644
--- a/comments.php
+++ b/comments.php
@@ -1,4 +1,5 @@
 <?php
+// Protected posts must not expose their discussion until WordPress grants access.
 if ( post_password_required() ) { return; }
 ?>
 <section id="comments" class="comments-area">
@@ -8,5 +9,6 @@ if ( post_password_required() ) { return; }
 		<?php the_comments_navigation(); ?>
 	<?php } ?>
 	<?php if ( ! comments_open() && get_comments_number() ) { ?><p><?php esc_html_e( 'Comments are closed.', 'c1024-2026' ); ?></p><?php } ?>
-	<?php comment_form(); ?>
+	<?php // WordPress provides the form so it respects discussion settings and logged-in state.
+	comment_form(); ?>
 </section>
diff --git a/editor-style.css b/editor-style.css
index 950993a..77cb63b 100644
--- a/editor-style.css
+++ b/editor-style.css
@@ -1 +1,41 @@
-@font-face{font-family:'Alpha Lyrae';src:url('fonts/AlphaLyrae-Medium.woff2') format('woff2')}@font-face{font-family:'Crimson Pro';src:url('fonts/crimson-pro-latin-ext-wght-normal.woff2') format('woff2')}@font-face{font-family:'Berkeley Mono';src:url('fonts/BerkeleyMono-Regular.woff2') format('woff2')}body{font-family:'Crimson Pro',Georgia,serif;font-size:22px;line-height:1.55;color:#1d1b19}h1,h2,h3,h4{font-family:'Alpha Lyrae',sans-serif;font-weight:500;letter-spacing:.025em}code,pre{font-family:'Berkeley Mono',monospace}a{color:#c3480b}
+/* Editor previews use the same self-hosted faces as the front end; keep paths stylesheet-relative. */
+@font-face {
+  font-family: 'Alpha Lyrae';
+  src: url('fonts/AlphaLyrae-Medium.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Crimson Pro';
+  src: url('fonts/crimson-pro-latin-ext-wght-normal.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Berkeley Mono';
+  src: url('fonts/BerkeleyMono-Regular.woff2') format('woff2');
+}
+
+/* Static editor equivalents of the front-end light-mode typography and accent tokens. */
+body {
+  font-family: 'Crimson Pro', Georgia, serif;
+  font-size: 22px;
+  line-height: 1.55;
+  color: #1d1b19;
+}
+
+h1,
+h2,
+h3,
+h4 {
+  font-family: 'Alpha Lyrae', sans-serif;
+  font-weight: 500;
+  letter-spacing: .025em;
+}
+
+code,
+pre {
+  font-family: 'Berkeley Mono', monospace;
+}
+
+a {
+  color: #c3480b;
+}
diff --git a/footer.php b/footer.php
index 0c8f237..8ea720d 100644
--- a/footer.php
+++ b/footer.php
@@ -4,6 +4,7 @@
 		<?php wp_nav_menu( array( 'theme_location' => 'footer', 'menu_class' => 'footer-menu', 'container' => false, 'fallback_cb' => false ) ); ?>
 	</div>
 </footer>
-<?php wp_footer(); ?>
+<?php // Required hook for enqueued footer scripts and plugin output.
+wp_footer(); ?>
 </body>
 </html>
diff --git a/front-page.php b/front-page.php
index dccb7fa..a43f5cb 100644
--- a/front-page.php
+++ b/front-page.php
@@ -1,16 +1,19 @@
 <?php get_header();
+// The Customizer stores a media attachment ID; resolve it only for the front-page hero.
 $video_id = absint( get_theme_mod( 'c1024_2026_hero_video' ) );
 $video_url = $video_id ? wp_get_attachment_url( $video_id ) : '';
 $hero_title = get_theme_mod( 'c1024_2026_hero_title', get_bloginfo( 'name' ) );
 $hero_text = get_theme_mod( 'c1024_2026_hero_text' );
 ?>
-<?php if ( $video_url || $hero_title || $hero_text ) { ?>
+<?php // Keep the hero available for text-only configurations when no video is selected.
+if ( $video_url || $hero_title || $hero_text ) { ?>
 <section class="hero" aria-label="<?php esc_attr_e( 'Introduction', 'c1024-2026' ); ?>">
 	<?php if ( $video_url ) { ?><video class="hero-video" autoplay muted loop playsinline><source src="<?php echo esc_url( $video_url ); ?>" type="<?php echo esc_attr( get_post_mime_type( $video_id ) ); ?>"></video><?php } ?>
 	<div class="hero-content"><div class="hero-eyebrow"><?php bloginfo( 'name' ); ?></div><?php if ( $hero_title ) { ?><h1 class="hero-title"><?php echo esc_html( $hero_title ); ?></h1><?php } ?><?php if ( $hero_text ) { ?><p class="hero-text"><?php echo esc_html( $hero_text ); ?></p><?php } ?></div>
 </section>
 <?php } ?>
 <main id="main" class="site-main">
-<?php if ( is_home() ) { if ( have_posts() ) { while ( have_posts() ) { the_post(); get_template_part( 'template-parts/content' ); } the_posts_pagination( array( 'mid_size' => 1 ) ); } } else { while ( have_posts() ) { the_post(); ?><article id="post-<?php the_ID(); ?>" <?php post_class(); ?>><div class="entry-content"><?php the_content(); ?></div></article><?php if ( comments_open() || get_comments_number() ) { comments_template(); } } } ?>
+<?php // On a static front page, is_home() identifies the separate posts index; it uses archive cards.
+if ( is_home() ) { if ( have_posts() ) { while ( have_posts() ) { the_post(); get_template_part( 'template-parts/content' ); } the_posts_pagination( array( 'mid_size' => 1 ) ); } } else { while ( have_posts() ) { the_post(); ?><article id="post-<?php the_ID(); ?>" <?php post_class(); ?>><div class="entry-content"><?php the_content(); ?></div></article><?php if ( comments_open() || get_comments_number() ) { comments_template(); } } } ?>
 </main>
 <?php get_footer();
diff --git a/functions.php b/functions.php
index fa4f34e..ba9d870 100644
--- a/functions.php
+++ b/functions.php
@@ -16,14 +16,17 @@ function c1024_2026_setup() {
 		'footer'  => __( 'Footer menu', 'c1024-2026' ),
 	) );
 }
+// Register theme capabilities before WordPress initializes theme-dependent features.
 add_action( 'after_setup_theme', 'c1024_2026_setup' );
 
 function c1024_2026_assets() {
 	wp_enqueue_style( 'c1024-2026-style', get_stylesheet_uri(), array(), '1.0.0' );
 	wp_enqueue_script( 'c1024-2026-theme', get_template_directory_uri() . '/assets/js/theme.js', array(), '1.0.0', true );
 }
+// Load public assets through WordPress so dependencies and plugin integrations remain ordered.
 add_action( 'wp_enqueue_scripts', 'c1024_2026_assets' );
 
+// These settings drive the optional front-page hero without hard-coding media or copy.
 function c1024_2026_customize_register( $wp_customize ) {
 	$wp_customize->add_section( 'c1024_2026_home_hero', array(
 		'title'       => __( 'Home page video hero', 'c1024-2026' ),
@@ -39,9 +42,11 @@ function c1024_2026_customize_register( $wp_customize ) {
 	$wp_customize->add_setting( 'c1024_2026_hero_text', array( 'sanitize_callback' => 'sanitize_textarea_field' ) );
 	$wp_customize->add_control( 'c1024_2026_hero_text', array( 'label' => __( 'Overlay text', 'c1024-2026' ), 'section' => 'c1024_2026_home_hero', 'type' => 'textarea' ) );
 }
+// Customize controls are registered only while the Customizer API is available.
 add_action( 'customize_register', 'c1024_2026_customize_register' );
 
 function c1024_2026_excerpt_more( $more ) {
 	return '…';
 }
+// Keep generated excerpts visually concise across all card-based archive loops.
 add_filter( 'excerpt_more', 'c1024_2026_excerpt_more' );
diff --git a/header.php b/header.php
index 2106ee5..b9aeeee 100644
--- a/header.php
+++ b/header.php
@@ -3,10 +3,13 @@
 <head>
 	<meta charset="<?php bloginfo( 'charset' ); ?>">
 	<meta name="viewport" content="width=device-width, initial-scale=1">
-	<?php wp_head(); ?>
+	<?php // Required hook for WordPress, plugins, and enqueued head assets.
+	wp_head(); ?>
 </head>
 <body <?php body_class(); ?>>
-<?php wp_body_open(); ?>
+<?php // Allows integrations to inject markup immediately after the opening body tag.
+wp_body_open(); ?>
+<?php // Lets keyboard users bypass repeated site navigation. ?>
 <a class="screen-reader-text" href="#main"><?php esc_html_e( 'Skip to content', 'c1024-2026' ); ?></a>
 <header class="site-header" id="masthead">
 	<div class="header-inner">
diff --git a/index.php b/index.php
index 7af178b..85f1172 100644
--- a/index.php
+++ b/index.php
@@ -1,6 +1,7 @@
 <?php get_header(); ?>
 <main id="main" class="site-main">
-	<?php if ( is_home() && ! is_front_page() ) { ?><header class="page-header"><h1 class="page-title"><?php single_post_title(); ?></h1></header><?php } ?>
+	<?php // Show the assigned posts-page title, but not when it is also the front page.
+if ( is_home() && ! is_front_page() ) { ?><header class="page-header"><h1 class="page-title"><?php single_post_title(); ?></h1></header><?php } ?>
 	<?php if ( have_posts() ) { while ( have_posts() ) { the_post(); get_template_part( 'template-parts/content' ); } the_posts_pagination( array( 'mid_size' => 1 ) ); } else { ?><p><?php esc_html_e( 'No posts found.', 'c1024-2026' ); ?></p><?php } ?>
 </main>
 <?php get_footer();
diff --git a/page.php b/page.php
index 433c4c3..4000e94 100644
--- a/page.php
+++ b/page.php
@@ -1,5 +1,6 @@
 <?php get_header(); ?>
 <main id="main" class="site-main">
-<?php while ( have_posts() ) { the_post(); ?><article id="post-<?php the_ID(); ?>" <?php post_class(); ?>><header class="entry-header"><?php the_title( '<h1 class="entry-title">', '</h1>' ); ?></header><div class="entry-content"><?php the_content(); wp_link_pages(); ?></div></article><?php if ( comments_open() || get_comments_number() ) { comments_template(); } } ?>
+<?php // Preserve existing discussions even after new comments have been closed.
+while ( have_posts() ) { the_post(); ?><article id="post-<?php the_ID(); ?>" <?php post_class(); ?>><header class="entry-header"><?php the_title( '<h1 class="entry-title">', '</h1>' ); ?></header><div class="entry-content"><?php the_content(); wp_link_pages(); ?></div></article><?php if ( comments_open() || get_comments_number() ) { comments_template(); } } ?>
 </main>
 <?php get_footer();
diff --git a/search.php b/search.php
index e62c5db..78caa83 100644
--- a/search.php
+++ b/search.php
@@ -1,4 +1,7 @@
-<?php get_header(); ?>
+<?php // This search template is selected by the WordPress template hierarchy.
+get_header(); ?>
+<?php // The user-supplied search term is escaped before it enters the translated heading. ?>
 <header class="page-header"><h1 class="page-title"><?php printf( esc_html__( 'Results for “%s”', 'c1024-2026' ), esc_html( get_search_query() ) ); ?></h1></header>
-<main id="main" class="site-main"><?php if ( have_posts() ) { while ( have_posts() ) { the_post(); get_template_part( 'template-parts/content' ); } the_posts_pagination( array( 'mid_size' => 1 ) ); } else { ?><p><?php esc_html_e( 'Nothing matched your search. Try another term.', 'c1024-2026' ); ?></p><?php get_search_form(); } ?></main>
+<main id="main" class="site-main"><?php // Empty result sets offer another search form instead of an empty archive.
+if ( have_posts() ) { while ( have_posts() ) { the_post(); get_template_part( 'template-parts/content' ); } the_posts_pagination( array( 'mid_size' => 1 ) ); } else { ?><p><?php esc_html_e( 'Nothing matched your search. Try another term.', 'c1024-2026' ); ?></p><?php get_search_form(); } ?></main>
 <?php get_footer();
diff --git a/searchform.php b/searchform.php
index 8882af5..fb79d27 100644
--- a/searchform.php
+++ b/searchform.php
@@ -1,4 +1,5 @@
 <form role="search" method="get" class="search-form" action="<?php echo esc_url( home_url( '/' ) ); ?>">
+	<?php // A visually hidden label supplies the search input accessible name. ?>
 	<label class="screen-reader-text" for="site-search-field"><?php esc_html_e( 'Search for:', 'c1024-2026' ); ?></label>
 	<input id="site-search-field" class="search-field" type="search" value="<?php echo esc_attr( get_search_query() ); ?>" name="s" placeholder="<?php esc_attr_e( 'Search …', 'c1024-2026' ); ?>">
 	<button class="search-submit" type="submit"><?php esc_html_e( 'Search', 'c1024-2026' ); ?></button>
diff --git a/single.php b/single.php
index 78000da..6f3c572 100644
--- a/single.php
+++ b/single.php
@@ -1,13 +1,17 @@
 <?php get_header(); ?>
 <main id="main" class="site-main">
-<?php while ( have_posts() ) { the_post(); ?>
+<?php // The singular main query normally has one post, but retain the standard loop contract.
+while ( have_posts() ) { the_post(); ?>
 <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
-	<header class="entry-header"><div class="entry-meta"><time datetime="<?php echo esc_attr( get_the_date( DATE_W3C ) ); ?>"><?php echo esc_html( get_the_date() ); ?></time> · <?php the_author_posts_link(); ?></div><?php the_title( '<h1 class="entry-title">', '</h1>' ); ?><?php if ( has_category() ) { ?><div class="taxonomy post-categories"><?php the_category( ' ' ); ?></div><?php } ?></header>
+	<header class="entry-header"><div class="entry-meta"><time datetime="<?php echo esc_attr( get_the_date( DATE_W3C ) ); ?>"><?php echo esc_html( get_the_date() ); ?></time> · <?php the_author_posts_link(); ?></div><?php the_title( '<h1 class="entry-title">', '</h1>' ); ?><?php // Omit category markup entirely when the post has no assigned categories.
+if ( has_category() ) { ?><div class="taxonomy post-categories"><?php the_category( ' ' ); ?></div><?php } ?></header>
 	<?php if ( has_post_thumbnail() ) { ?><div class="entry-thumbnail"><?php the_post_thumbnail( 'large' ); ?></div><?php } ?>
 	<div class="entry-content"><?php the_content(); wp_link_pages(); ?></div>
-	<footer class="entry-footer"><?php if ( has_tag() ) { ?><div class="tags-links"><?php the_tags( '', ' ', '' ); ?></div><?php } ?></footer>
+	<footer class="entry-footer"><?php // Tags render separately so untagged posts avoid empty taxonomy output.
+if ( has_tag() ) { ?><div class="tags-links"><?php the_tags( '', ' ', '' ); ?></div><?php } ?></footer>
 </article>
-<?php if ( comments_open() || get_comments_number() ) { comments_template(); } the_post_navigation(); ?>
+<?php // Retain existing discussions even after comments are closed.
+if ( comments_open() || get_comments_number() ) { comments_template(); } the_post_navigation(); ?>
 <?php } ?>
 </main>
 <?php get_footer();
diff --git a/style.css b/style.css
index 5419ada..c3d5a32 100644
--- a/style.css
+++ b/style.css
@@ -9,6 +9,7 @@ License: GNU General Public License v2 or later
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
 */
 
+/* Self-hosted typefaces: keep these paths relative to the theme stylesheet. */
 @font-face {
   font-family: "Alpha Lyrae";
   src: url("fonts/AlphaLyrae-Medium.woff2") format("woff2");
@@ -45,6 +46,7 @@ License URI: https://www.gnu.org/licenses/gpl-2.0.html
   font-display: swap;
 }
 
+/* Shared palette, layout, and code tokens; dark mode overrides the same names below. */
 :root {
   color-scheme: light;
   --bg: #f8f5f0;
@@ -73,6 +75,7 @@ License URI: https://www.gnu.org/licenses/gpl-2.0.html
   --code-text: #f5eee5;
   --shadow: 0 10px 30px rgba(0, 0, 0, 0.25);
 }
+/* Automatic mode (and no saved preference) follows the operating-system color scheme. */
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme]),
   :root[data-theme="auto"] {
@@ -626,6 +629,7 @@ h4 {
     font-size: 1.25rem;
   }
 }
+/* Desktop submenus are positioned from their parent; nested menus fly out to the side. */
 .primary-menu > li {
   position: relative;
 }
@@ -668,6 +672,7 @@ h4 {
 .primary-menu .sub-menu a:focus {
   background: var(--bg);
 }
+/* On small screens, expose the menu hierarchy inline instead of relying on hover. */
 @media (max-width: 760px) {
   .primary-menu .sub-menu {
     position: static;
@@ -758,6 +763,7 @@ h4 {
 .primary-menu > li.menu-item-has-children > a::after {
   vertical-align: -0.2em;
 }
+/* Keep the sticky header below WordPress's admin bar at each core bar height. */
 body.admin-bar .site-header {
   top: 32px;
 }
diff --git a/template-parts/content.php b/template-parts/content.php
index edfe927..08c62f8 100644
--- a/template-parts/content.php
+++ b/template-parts/content.php
@@ -2,8 +2,10 @@
 	<header class="entry-header">
 		<div class="entry-meta"><time datetime="<?php echo esc_attr( get_the_date( DATE_W3C ) ); ?>"><?php echo esc_html( get_the_date() ); ?></time><?php if ( get_the_author() ) { ?> · <?php the_author_posts_link(); ?><?php } ?></div>
 		<?php the_title( sprintf( '<h2 class="entry-title"><a href="%s">', esc_url( get_permalink() ) ), '</a></h2>' ); ?>
-		<?php if ( has_category() ) { ?><div class="taxonomy post-categories"><?php the_category( ' ' ); ?></div><?php } ?>
+		<?php // Avoid an empty category container when no categories are assigned.
+if ( has_category() ) { ?><div class="taxonomy post-categories"><?php the_category( ' ' ); ?></div><?php } ?>
 	</header>
-	<?php if ( has_post_thumbnail() ) { ?><a class="entry-thumbnail" href="<?php the_permalink(); ?>" aria-hidden="true" tabindex="-1"><?php the_post_thumbnail( 'large' ); ?></a><?php } ?>
+	<?php // This repeats the title link, so exclude it from keyboard and assistive-tech navigation.
+if ( has_post_thumbnail() ) { ?><a class="entry-thumbnail" href="<?php the_permalink(); ?>" aria-hidden="true" tabindex="-1"><?php the_post_thumbnail( 'large' ); ?></a><?php } ?>
 	<div class="entry-summary"><?php the_excerpt(); ?></div>
 </article>