One Theme - WordPress Theme for Government Benefits Sites

A modern, ACF-powered WordPress theme designed for government benefits information websites.

Version: 2.0

Features

• ACF-Driven Content — All content managed through Advanced Custom Fields
• Modular ACF Architecture — 18 field group files, each handling a specific feature
• LESS CSS Pipeline — Organized LESS partials compiled to a single minified style.css
• Section Toggles — Show/hide blog CTA and newsletter via Theme Settings
• Responsive Design — Mobile-first approach
• Custom Post Types — Glossary & Directory types included
• SEO Ready — Schema markup for FAQs, breadcrumbs
• Cloud Optimized — Works on Railway, AWS, or any cloud platform
• Reusable Partials — Newsletter, breadcrumbs, byline, etc. shared across templates

Installation

Via GitHub (Recommended for Railway)

1. Clone into themes directory:

   cd wp-content/themes/
   git clone https://github.com/YOUR_USERNAME/one-theme.git one

2. Activate in WordPress:

   • Go to Appearance → Themes
   • Activate "Ampry One"

Manual Upload

1. Download ZIP from GitHub
2. WordPress Admin → Appearance → Themes → Add New → Upload
3. Activate theme

Required Plugins

Must Install:

• Advanced Custom Fields PRO (for all theme options)

Recommended:

• Yoast SEO (for better SEO)
• WP Mail SMTP (for form emails)

Configuration

All theme settings are in WordPress Admin → Theme Settings:

1. Colors & Typography

• Primary colors (outputs CSS :root variables)
• Font families
• Button styles

2. Identity

• Site logo, favicon (via WordPress Customizer → Site Identity)
• Google Analytics & Facebook Pixel tracking codes
• Custom CSS injection

3. Header / Navigation

• Logo upload
• Top bar text
• CTA button
• Menu items

4. Footer Settings

• Footer logo
• Footer columns (3 columns with links)
• Copyright text
• Social media links (Facebook, X, Instagram, YouTube, LinkedIn)

5. Homepage Sections

Toggle each section on/off:

• Hero Banner
• Perks (3 feature boxes)
• Get Started
• Featured Programs
• Mission Statement
• As Seen In
• Recent Articles
• Testimonials
• FAQ
• Newsletter

6. Blog Settings

• Header — Eyebrow text, hero background image
• Visibility — Toggle CTA and Newsletter sections on/off
• Categories — Blog menu pill-link categories
• CTA — Title, description, button text/URL, background type (image or color), section background color

7. Custom Post Types

• Glossary Terms — For benefits glossary
• Directory — State-by-state directories

File Structure

one/
├── assets/
│   ├── css/
│   │   ├── style.less              # LESS entry point (imports all partials)
│   │   ├── style.css               # Compiled & minified CSS
│   │   ├── _reset.less             # CSS reset
│   │   ├── _mixins.less            # LESS mixins (.rounded, .clearfix, etc.)
│   │   ├── _grid.less              # Grid system
│   │   ├── _colors.less            # Color variables (@grey-100, @grey-200, etc.)
│   │   ├── _typography.less        # Font styles
│   │   ├── _base.less              # Base element styles
│   │   ├── _responsive.less        # Media queries
│   │   ├── sections/               # Section-specific styles
│   │   │   ├── _header.less
│   │   │   ├── _footer.less
│   │   │   ├── _breadcrumbs.less
│   │   │   ├── _article-header.less
│   │   │   ├── _article.less
│   │   │   └── _category-header.less
│   │   └── pages/                  # Page-specific styles
│   │       ├── _front-page.less
│   │       ├── _about.less
│   │       ├── _how-it-works.less
│   │       ├── _blog.less
│   │       └── _category.less
│   ├── js/
│   │   └── app.js                  # Theme JS
│   └── images/                     # Default images
├── inc/
│   ├── auto-update.php             # Theme updates
│   ├── setup-pages.php             # Page creation & CPT registration
│   ├── ajax-handlers.php           # AJAX functions
│   └── settings/                   # ACF settings (modular architecture)
│       ├── options-pages.php       # Options page registration
│       ├── defaults.php            # Default ACF values on activation
│       ├── css-output.php          # :root CSS variable generation
│       ├── head-output.php         # Analytics, pixels, custom CSS
│       ├── helpers.php             # Utility functions
│       └── field-groups/           # One file per feature
│           ├── about.php
│           ├── banner.php
│           ├── blog.php
│           ├── category.php
│           ├── colors.php
│           ├── directory.php
│           ├── faqs.php
│           ├── featured-post.php
│           ├── footer.php
│           ├── front-page.php
│           ├── how-it-works.php
│           ├── identity.php
│           ├── navigation.php
│           ├── page.php
│           ├── reviewer.php
│           ├── survey.php
│           ├── typography.php
│           └── user.php
├── templates/                      # Custom page templates
│   ├── about.php
│   ├── blog.php
│   ├── how-it-works.php
│   ├── survey.php
│   └── glossary.php
├── template-parts/
│   ├── components/                 # Reusable UI components
│   │   ├── article.php
│   │   ├── article-header.php
│   │   ├── breadcrumbs.php
│   │   ├── byline.php
│   │   ├── category-header.php
│   │   └── featured-image.php
│   └── sections/                   # Page sections & layouts
│       ├── nav.php
│       ├── page-header.php
│       ├── page-menu.php
│       ├── sidebar-widgets.php
│       ├── blog-header.php
│       ├── blog-menu.php
│       ├── newsletter.php
│       ├── author-header.php
│       ├── single-post.php
│       └── map.php
├── acf-json/                       # ACF JSON (Directory post type fields)
├── front-page.php                  # Homepage template
├── single.php                      # Single post
├── page.php                        # Generic page
├── 404.php                         # 404 page
├── index.php                       # Fallback archive
├── category.php                    # Category archive
├── author.php                      # Author archive
├── archive-directory.php           # Directory archive
├── archive-glossary.php            # Glossary archive
├── single-directory.php            # Single directory entry
├── single-glossary.php             # Single glossary term
├── functions.php                   # Theme functions
├── header.php                      # Site header
├── footer.php                      # Site footer
├── style.css                       # Theme info (WP metadata)
└── package.json                    # LESS build scripts

---

Developer Guide

Compiling LESS to CSS

The theme uses LESS as a CSS preprocessor. The compiled style.css is committed to the repo (there is no CI/CD build step), so you must compile locally after any .less changes.

Setup (one-time)

cd one-theme-repo
npm install

This installs less and nodemon as dev dependencies.

Compile

# One-time build (minified)
npm run build:css

# Watch mode (auto-recompiles on any .less file change)
npm run watch:css

Both commands run:

lessc --compress assets/css/style.less assets/css/style.css

LESS File Conventions

• Entry point: assets/css/style.less — imports all partials in order
• Partials are prefixed with _ (e.g., _header.less) and are never compiled on their own
• Import order matters: reset → mixins → grid → colors → typography → base → sections → pages → responsive
• Variables & mixins go in _colors.less and _mixins.less

Adding a New LESS Partial

1. Create the file in the appropriate folder:
   • assets/css/sections/_my-section.less for section styles
   • assets/css/pages/_my-page.less for page-specific styles
2. Add the import to assets/css/style.less:

   @import "sections/_my-section";

3. Run npm run build:css to compile
4. Commit both the .less file and the updated style.css

---

ACF Settings Architecture

v2.0 uses a modular architecture — field groups are split into individual files under inc/settings/field-groups/. The loader in functions.php auto-includes all PHP files in that directory.

Key Files

File	Purpose
inc/settings/options-pages.php	Registers all ACF options pages and sub-pages
inc/settings/defaults.php	Populates default ACF values on theme activation
inc/settings/css-output.php	Generates :root CSS variables from color/typography settings
inc/settings/head-output.php	Outputs analytics, pixels, custom CSS to <head>
inc/settings/helpers.php	Utility functions used across settings
inc/settings/field-groups/*.php	One file per feature (blog, footer, colors, etc.)

Field Group Files

Each file in field-groups/ follows this pattern:

<?php
add_action('acf/init', 'one_register_FEATURE_fields');
function one_register_FEATURE_fields() {
    if (!function_exists('acf_add_local_field_group')) return;

    acf_add_local_field_group(array(
        'key' => 'group_FEATURE',
        'title' => 'Feature Name',
        'fields' => array( /* ... */ ),
        'location' => array(
            array(
                array(
                    'param' => 'options_page',
                    'operator' => '==',
                    'value' => 'theme-settings',
                ),
            ),
        ),
    ));
}

Adding a New Field Group

1. Create inc/settings/field-groups/my-feature.php
2. Follow the pattern above — use a unique group_ key and field_ prefixed field keys
3. The file is auto-loaded by functions.php — no manual include needed
4. Target the appropriate options page slug in the location array

Options Page Slugs

Page	Slug
Theme Settings (main)	theme-settings
Colors	acf-options-colors
Typography	acf-options-typography
Home Banner	acf-options-home-banner
Front Page Content	acf-options-front-page-content
Footer	acf-options-footer
About Page	acf-options-about-page
How It Works	acf-options-how-it-works
Navigation	acf-options-navigation

Hybrid ACF Approach

The theme uses a hybrid ACF strategy:

• PHP-registered fields (field-groups/*.php) — for all theme settings. These are version-controlled and portable.
• ACF JSON (acf-json/) — only for the Directory custom post type fields. These sync via ACF's built-in JSON sync.

Using Fields in Templates

// Options page fields — always pass 'option'
$value = get_field('field_name', 'option') ?: 'Fallback';

// Per-post fields — no second argument needed
$value = get_field('field_name');

Always provide a fallback with ?: in case the field hasn't been saved yet.

---

Customization

Change Brand Name

Default: "Ampry One". Update in:

1. style.css — Theme Name header
2. front-page.php — Mission text & FAQ answers
3. ACF Options (if values were already saved)

Modify Default Images

Replace images in assets/images/:

• shield.png — Hero stat icon
• edit_square.png — Get Started icon
• star.png, forum.png, thumb_up.png — Perk icons
• veteran.png, ssdi.png, grants.png — Program icons
• blog-header-bg.webp — Blog header hero
• blog-cta-bg.webp — Blog CTA default background

Favicon

Use the built-in WordPress Site Icon: Appearance → Customize → Site Identity → Site Icon

Deployment

Railway

This theme is optimized for Railway deployment:

1. Push theme to GitHub
2. Update WordPress Dockerfile to clone theme:

   RUN cd wp-content/themes && \
       git clone https://github.com/YOUR_USERNAME/one-theme.git one

3. Deploy to Railway
4. Configure ACF Options in WordPress admin

See railway-wordpress/ in the project root for Docker and Railway config files.

Troubleshooting

Issue: ACF fields not showing

• Install ACF PRO plugin
• Fields are auto-registered via PHP — no import needed

Issue: Default images not loading

• Check assets/images/ folder exists
• Verify file paths in templates

Issue: Custom Post Types not appearing

• Go to Settings → Permalinks
• Click "Save Changes" to flush rewrite rules

Issue: CSS changes not reflecting

• Run npm run build:css after editing any .less file
• Hard refresh browser (Ctrl+Shift+R)

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Credits

• Icons: Material Design Icons
• Fonts: Google Fonts (Inter, Roboto Serif)
• Maps: Custom SVG US map

License

This is proprietary software. All rights reserved. Unauthorized copying, distribution, or modification of this code is strictly prohibited.

Changelog

Version 2.0

• Modular ACF Architecture — Split monolithic theme-settings.php into 18 individual field group files under inc/settings/field-groups/
• LESS CSS Pipeline — Consolidated all CSS into organized LESS partials with --compress minification
• Blog Page Overhaul — Customizable eyebrow text, hero image, CTA (background type/color/image), newsletter toggle, menu categories via ACF
• Reusable Newsletter Partial — Shared across front page, blog, and category pages
• Full Hardcoded Audit — Replaced ~75 hardcoded values with ACF fields or sensible defaults
• Orphan Cleanup — Removed 7 unused files, fixed duplicate field name collisions
• Social Links in Footer — Facebook, X, Instagram, YouTube, LinkedIn from ACF
• Head Output — Google Analytics, Facebook Pixel, custom CSS injection
• Favicon — Uses WordPress built-in Site Icon (removed custom ACF field)
• CSS Variables — Dynamic :root color/typography variables from ACF settings
• Nav Styling Fix — Active menu item highlight
• 404 Console Error Fix — Removed broken JS reference

Version 1.1

• Added section visibility toggles
• Improved Railway compatibility
• Enhanced ACF defaults
• Fixed image fallbacks

Version 1.0

• Initial release