Readme

Moontheme v1

A dual-mode WordPress theme framework built for small companies. Light and dark modes, a 12-column CSS grid, prefab marketing layouts, and full blogging — all on system fonts with a neutral color palette. No plugin dependencies, no custom post types, no framework lock-in.

What’s in the box

Design token system — All colors, spacing, typography, and radii are CSS custom properties in css/design-tokens.css. The --mv-* namespace covers light mode defaults, dark mode via prefers-color-scheme, and manual toggle via data-theme attribute on <html>. Swap the palette by editing one file.

12-column grid — css/grid.css provides the structural layout system: .mv-docs-layout (12-col CSS Grid, 1420px max-width), sidebar + content split, .mv-docs-prose (720px text measure with full typographic styles), card grids, pagination, search, and 404 layouts. All responsive at 1024px and 768px breakpoints.

14 marketing components — BEM-named PHP template parts in template-parts/marketing/. Hero (default, centered, split), content section, two-column, asymmetric (60-40, 55-45, 70-30), CTA, card grid (2/3/4 col), logo grid, comparison table, contact form, button, eyebrow, section label, divider, and background graphic. All argument-driven via get_template_part() with $args.

Full template hierarchy — index, single, page, archive, search, 404, header, footer, sidebar, comments, searchform. Plus 4 content template parts (content, content-page, content-none, content-search).

Modular functions.php — Slim loader that requires 6 modules from inc/: setup (theme supports, menus, widgets), enqueue (all CSS/JS loading), template-tags (post meta helpers), template-functions (body classes), content-filters (standfirst injection, table wrapping), performance (emoji removal, version stripping).

Tailwind v3 build — npm run build compiles src/input.css to dist/style.css. Preflight disabled. Custom spacing scale (mv-1 through mv-32), border radii, and max-widths mapped to the design token system. npm run dev for watch mode.

theme.json v3 — Exposes the neutral color palette, system font stacks, type scale, and spacing scale to the Gutenberg block editor. Block editor shows Moontheme’s tokens instead of WordPress defaults.

Architecture

CSS load order: design-tokens.css → grid.css → components.css → marketing.css → dist/style.css (Tailwind) → style.css (structural). All enqueued via wp_enqueue_style() with proper dependencies.

Light/dark mode: Inline script in <head> reads localStorage before paint (no flash). Toggle sets data-theme on <html> and persists. Three CSS selectors handle the modes: :root (light default), @media (prefers-color-scheme: dark) :root:not([data-theme="light"]) (system dark), [data-theme="dark"] (manual dark).

Navigation: Two registered menu locations — primary and footer — rendered via wp_nav_menu(). Mobile hamburger at 768px with Escape-to-close.

Current state

This is a v1 scaffold. What’s done:

  • Full template hierarchy renders pages, posts, archives, search, 404
  • Light/dark toggle works with localStorage persistence
  • Dynamic menus via wp_nav_menu
  • Design tokens, grid, component CSS, and marketing CSS all load
  • Tailwind build pipeline works
  • Block editor picks up theme.json tokens

What’s not built yet:

  • No Customizer or theme options panel
  • No editor-style.css (block editor doesn’t visually match front-end yet)
  • Marketing components exist as template parts but aren’t registered as Gutenberg block patterns
  • No screenshot.png

File structure

moontheme/
├── style.css                     # Theme header + structural styles
├── functions.php                 # Slim loader
├── theme.json                    # Gutenberg design tokens
├── package.json / tailwind.config.js
│
├── index.php / single.php / page.php / archive.php
├── search.php / 404.php / sidebar.php
├── header.php / footer.php / comments.php / searchform.php
│
├── inc/
│   ├── setup.php                 # Theme supports, menus, widgets
│   ├── enqueue.php               # CSS/JS loading
│   ├── template-tags.php         # Post meta helpers
│   ├── template-functions.php    # Body classes
│   ├── content-filters.php       # Standfirst, table wrapper
│   └── performance.php           # Cleanup
│
├── css/
│   ├── design-tokens.css         # Light/dark tokens, spacing, type scale
│   ├── grid.css                  # 12-column layout system
│   ├── components.css            # BEM marketing component styles
│   └── marketing.css             # Marketing page base styles
│
├── js/
│   ├── theme-toggle.js           # Light/dark toggle
│   └── navigation.js             # Mobile menu
│
├── template-parts/
│   ├── content.php / content-page.php
│   ├── content-none.php / content-search.php
│   └── marketing/                # 14 prefab layout components
│
├── src/input.css                 # Tailwind entry
└── dist/style.css                # Compiled Tailwind (gitignored)