# Reusable Build Brief: Custom WordPress Theme ## How to use this brief This document is a reusable specification for building a custom WordPress theme with an AI coding assistant or a human developer. Complete every **USER INPUT REQUIRED** block before development begins. Delete unused options and replace all bracketed placeholders. The finished theme must be a classic/hybrid PHP theme. It should use the WordPress template hierarchy and standard WordPress menu functionality while also supporting current block-editor features through `theme.json` where appropriate. Do not begin development until the required user inputs are complete. If an answer is missing or contradictory, ask the user for clarification instead of inventing brand, content, layout, or business requirements. ## Goal Build a production-ready, responsive, accessible custom WordPress theme for the website described below. The theme should: - Match the selected visual direction and brand requirements. - Use standard WordPress pages, posts, featured images, menus, widgets, and the Media Library. - Include a polished header, primary navigation, mobile navigation, content templates, and styled footer. - Keep presentation in the theme and business functionality in plugins. - Be easy to update through versioned ZIP releases without losing content or theme settings. - Follow WordPress coding, security, accessibility, and performance standards. ## 1. Project identity > [!IMPORTANT] > **USER INPUT REQUIRED: Project identity** > > Provide all of the following: > > - Website or business name: `[REQUIRED]` > - Theme display name: `[REQUIRED]` > - Theme slug using lowercase letters and hyphens, such as `oak-studio-theme`: `[REQUIRED]` > - One-sentence description of the organization and website: `[REQUIRED]` > - Primary website goal, such as lead generation, online sales, bookings, publishing, memberships, or portfolio display: `[REQUIRED]` > - Target audience: `[REQUIRED]` > - Theme author name: `[REQUIRED]` > - Theme author URL: `[REQUIRED]` > - Text domain, normally identical to the theme slug: `[REQUIRED]` > - Existing website URL, if any: `[OPTIONAL]` > - Reference websites the user likes, with a short explanation of what they like about each: `[OPTIONAL]` ## 2. Source of truth > [!IMPORTANT] > **USER INPUT REQUIRED: Design and content source** > > Identify the authoritative source for the build: > > - Existing website to reproduce: `[URL OR NONE]` > - Approved design file: `[FIGMA, PDF, IMAGE, OR NONE]` > - Existing HTML/CSS prototype: `[PATH OR NONE]` > - Brand guide: `[PATH OR NONE]` > - Approved copy document: `[PATH OR NONE]` > - Content migration source: `[URL, EXPORT FILE, OR NONE]` > > State whether the source must be matched exactly or used only as inspiration: `[EXACT MATCH / CLOSE INTERPRETATION / NEW DESIGN]` If an approved source exists, treat it as authoritative for layout, copy, colors, typography, spacing, and links. Do not redesign an exact-match source without explicit approval. ## 3. Visual style direction > [!IMPORTANT] > **USER INPUT REQUIRED: Theme style** > > Choose one primary style and, optionally, one supporting style. Describe what the selected style means for this website. > > - **Boutique / luxury:** refined typography, generous spacing, editorial imagery, restrained color, premium details > - **Modern minimalist:** clean grid, strong whitespace, simple typography, limited palette, subtle motion > - **Classical / traditional:** serif typography, balanced symmetry, formal spacing, timeless colors, restrained decoration > - **Gaming / technology:** dark surfaces, vivid accents, energetic type, interface-inspired details, optional motion > - **eCommerce / retail:** product-first layouts, clear pricing and calls to action, filters, trust signals, conversion-focused design > - **Corporate / professional:** structured layouts, credible typography, clear hierarchy, service and case-study emphasis > - **Creative / portfolio:** large visual work, expressive typography, project grids, case studies, distinctive transitions > - **Editorial / publishing:** readable typography, article hierarchy, categories, author information, related content > - **Hospitality / local business:** location, hours, menus or services, reservations, reviews, maps, inviting photography > - **Nonprofit / community:** mission-led storytelling, impact content, donations, events, volunteer calls to action > - **Industrial / trades:** direct messaging, services, certifications, project proof, strong contact and quote actions > - **Custom direction:** `[DESCRIBE]` > > Required style decisions: > > - Primary style: `[REQUIRED]` > - Supporting style: `[OPTIONAL]` > - Three to five adjectives for the desired feeling: `[REQUIRED]` > - Light, dark, or mixed interface: `[REQUIRED]` > - Preferred corner treatment: `[SQUARE / SLIGHTLY ROUNDED / ROUNDED / MIXED]` > - Preferred spacing: `[COMPACT / BALANCED / SPACIOUS]` > - Motion level: `[NONE / SUBTLE / MODERATE / EXPRESSIVE]` > - Elements or styles to avoid: `[REQUIRED]` ## 4. Brand colors and typography > [!IMPORTANT] > **USER INPUT REQUIRED: Colors and fonts** > > Provide: > > - Primary color and hex value: `[REQUIRED]` > - Secondary color and hex value: `[REQUIRED]` > - Accent or call-to-action color and hex value: `[REQUIRED]` > - Background colors: `[REQUIRED]` > - Primary text color: `[REQUIRED]` > - Heading font: `[REQUIRED OR "RECOMMEND ONE"]` > - Body font: `[REQUIRED OR "RECOMMEND ONE"]` > - Font source or license information: `[GOOGLE FONTS / ADOBE / SELF-HOSTED / SYSTEM / OTHER]` > - Minimum normal body-text size: `[RECOMMENDED: 16PX OR LARGER]` Define the approved colors, spacing, typography, content width, breakpoints, borders, radii, and shadows as CSS custom properties. Mirror relevant editor settings in `theme.json` so the editor resembles the front end. Do not load unapproved font weights. Prefer system fonts or properly licensed, locally hosted font files when privacy or performance is important. ## 5. Branding and Media Library assets All logos, photographs, illustrations, hero images, background images, team photos, product images, and other content imagery must be uploaded to the WordPress Media Library. Do not hard-code content-image URLs, base64 images, or local computer paths into PHP, CSS, or JavaScript. Add support for the WordPress custom logo feature: ```php add_theme_support( 'custom-logo', array( 'height' => 160, 'width' => 480, 'flex-height' => true, 'flex-width' => true, ) ); ``` Render the selected logo with `the_custom_logo()` or the corresponding attachment functions. Use the WordPress Site Icon setting for the favicon. For user-selectable theme images, use the Customizer Media Control or an approved settings interface that stores attachment IDs. Render images with `wp_get_attachment_image()` so WordPress can provide responsive image sizes, `srcset`, dimensions, alt text, and lazy loading. Use featured images for posts, pages, products, portfolio entries, and other content types where appropriate. Register only the image sizes required by the design. > [!IMPORTANT] > **USER INPUT REQUIRED: Media and logo requirements** > > Provide or describe: > > - Primary logo file: `[REQUIRED; SVG OR HIGH-RESOLUTION PNG PREFERRED]` > - Alternate light or dark logo: `[OPTIONAL]` > - Site icon: `[REQUIRED; SQUARE IMAGE, AT LEAST 512×512]` > - Hero or banner images needed: `[LIST OR NONE]` > - Default featured image behavior when no image is assigned: `[HIDE IMAGE / USE GENERIC MEDIA-LIBRARY IMAGE / OTHER]` > - Photography treatment: `[FULL COLOR / MUTED / BLACK AND WHITE / OVERLAY / OTHER]` > - Required image aspect ratios or crops: `[LIST OR ASK FOR RECOMMENDATIONS]` > - Whether the theme should expose Media Library controls for hero and footer images: `[YES / NO]` Document the post-activation process for uploading each asset to **Media > Add New** and selecting it through WordPress settings. Never require the user to replace files inside the theme folder to change branding or content imagery. ## 6. Page and content architecture > [!IMPORTANT] > **USER INPUT REQUIRED: Pages and content types** > > List every required page and its purpose. At minimum, identify whether the site needs: > > - Home page: `[YES / NO; DESCRIBE SECTIONS]` > - About page: `[YES / NO]` > - Services or products: `[YES / NO; DESCRIBE]` > - Blog or news: `[YES / NO]` > - Portfolio, case studies, team, events, locations, testimonials, or other structured content: `[LIST OR NONE]` > - Contact page: `[YES / NO; DESCRIBE FORM OR CONTACT METHOD]` > - Search results: `[YES / NO]` > - WooCommerce shop: `[YES / NO]` > - Member-only or account content: `[YES / NO]` > - Legal pages: `[LIST]` > > For each custom content type, state whether it already exists through a plugin. Custom post types and business data should normally be registered in a plugin so the content survives a theme change. ## 7. Layout choices > [!IMPORTANT] > **USER INPUT REQUIRED: Layout behavior** > > Select or describe: > > - Maximum content width: `[REQUIRED OR "RECOMMEND"]` > - Header layout: `[LOGO LEFT + MENU RIGHT / CENTERED LOGO / SPLIT NAVIGATION / OTHER]` > - Header behavior: `[STATIC / STICKY / SHRINKING STICKY]` > - Mobile header behavior: `[DRAWER / DROPDOWN / FULL-SCREEN MENU / OTHER]` > - Standard page width: `[FULL WIDTH / CONTAINED / USER-SELECTABLE]` > - Blog archive: `[LIST / GRID / MAGAZINE / OTHER]` > - Single-post layout: `[FULL WIDTH / LEFT SIDEBAR / RIGHT SIDEBAR / USER-SELECTABLE]` > - Sidebar requirements: `[LIST OR NONE]` > - Breadcrumbs: `[YES / NO / PROVIDED BY SEO PLUGIN]` > - Homepage section order and required calls to action: `[REQUIRED]` ## 8. Standard WordPress menus The theme must use WordPress's standard menu system. Do not hard-code navigation links into `header.php` or JavaScript. Register menu locations during theme setup: ```php register_nav_menus( array( 'primary' => __( 'Primary Menu', 'THEME_TEXT_DOMAIN' ), 'footer' => __( 'Footer Menu', 'THEME_TEXT_DOMAIN' ), ) ); ``` Replace `THEME_TEXT_DOMAIN` with the approved text domain. Render the primary menu in the main theme header with `wp_nav_menu()`: ```php wp_nav_menu( array( 'theme_location' => 'primary', 'container' => 'nav', 'container_id' => 'site-navigation', 'container_class'=> 'site-navigation', 'menu_class' => 'primary-menu', 'fallback_cb' => false, 'depth' => 3, ) ); ``` The header's desktop navigation and mobile navigation must use the same assigned Primary Menu unless the user explicitly requests separate locations. The mobile toggle must be keyboard accessible, announce its expanded state with `aria-expanded`, close on Escape, and not trap users unexpectedly. Render the Footer Menu in `footer.php` when one is assigned. Style current-menu states, focus states, submenus, and mobile behavior. Document these setup steps in the theme readme: 1. In WordPress, go to **Appearance > Menus**. 2. Create a menu or select an existing menu. 3. Add the desired pages, posts, categories, and custom links. 4. Arrange menu items and submenus. 5. Under **Display location**, assign it to **Primary Menu**. 6. Save the menu and confirm it appears in the theme's main header. 7. Create or select a second menu and assign it to **Footer Menu**, if required. > [!IMPORTANT] > **USER INPUT REQUIRED: Menu design and structure** > > Provide: > > - Primary menu items and order: `[REQUIRED]` > - Required dropdown or nested items: `[LIST OR NONE]` > - Header call-to-action label and destination: `[OPTIONAL]` > - Whether the call to action is a menu item or a separate styled button: `[MENU ITEM / BUTTON / NONE]` > - Footer menu items: `[LIST OR NONE]` > - Maximum supported menu depth: `[RECOMMENDED: 2 OR 3]` > - Separate mobile menu location required: `[YES / NO]` ## 9. Header requirements The header must include: - The WordPress custom logo or site title fallback. - The assigned Primary Menu in the main header. - A keyboard-accessible mobile menu toggle. - Clearly visible hover, focus, active, and current-page states. - Optional search, account, cart, language, or call-to-action controls only when requested. - Correct `wp_body_open()`, semantic `
`, `