### Run the documentation site locally

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/README.md

Use these commands to install dependencies and start the Jekyll development server for the documentation project.

```bash
bundle install
bundle exec jekyll serve
```

--------------------------------

### Third-Party Integration Documentation Example

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Design.md

An example of how to document third-party integrations in an `INTEGRATIONS.md` file, including service details, scheduling, and integration points.

```markdown
## CrunchBase
Remote service for fetching funding and other investment data related to tech startups.

### Scheduling
- The CrunchBase API is used via JS in a dynamic product/company search on post edit pages
- Funding data is pulled every 6 hours by WP Cron to update cached data

### Integration Points
- /assets/js/src/crunchbase-autocomplete.js
- /includes/classes/crunchbase.php
- /includes/classes/cron.php

### Development API
- See https://somesitethatrequireslogin.com/credentials-for-project
```

--------------------------------

### Heredoc Syntax Example

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/PHP.md

Demonstrates the heredoc syntax for constructing multi-line strings.

```php
$y = <<<JOKE
I told my doctor
"it hurts when I move my arm like this".
He said, "<em>then stop moving it like that!</em>"
JOKE;
```

--------------------------------

### Class-based Module Instantiation

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/JavaScript.md

Example of initializing an ES6 class module with configuration options.

```javascript
import Module from './mymodule';
/* Module is an ES6 class */
new Module('.element-selector', {
	/* options */
	onEvent1: () => {},
	onEvent2: () => {},
});
```

--------------------------------

### Recommended PHP Packages for WordPress

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Systems.md

These packages are commonly recommended for WordPress installations to ensure compatibility and performance. Not all may be necessary for every setup.

```php
php-cli
php-common
php-fpm
php-gd
php-mbstring
php-mcrypt
php-mysqlnd
php-opcache
php-pdo
php-pear
php-pecl-jsonc
php-pecl-memcache
php-pecl-memcached
php-pecl-redis
php-pecl-zip
php-process
php-redis
php-soap
php-xml
```

--------------------------------

### Composer JSON Configuration

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Design.md

Example `composer.json` file for a WordPress project, specifying dependencies and repository configurations.

```json
{
  "name": "10up/project-slug",
  "description": "Project description",
  "repositories":[
    {
      "type":"composer",
      "url":"https://wpackagist.org"
    }
  ],
  "extra": {
    "wordpress-install-dir": "wp"
  },
  "require": {
    "johnpbloch/wordpress": "4.9",
    "wpackagist-plugin/wordpress-importer": "dev-trunk",
    "wpackagist-plugin/debug-bar": "dev-trunk",
    "wpackagist-plugin/debug-bar-extender": "dev-trunk"
  }
}
```

--------------------------------

### Named Export Example

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/JavaScript.md

Demonstrates how to create a named export in JavaScript. This allows other modules to import the specific exported item.

```javascript
export const example = 66;

```

--------------------------------

### Serve fonts locally with @font-face

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Performance.md

Uses the local() function to prioritize fonts already installed on the user's system for faster rendering.

```css
@font-face {
  font-family: 'WebFont';
  font-display: swap;
  src:  local('myfont.woff2'),
        url('myfont.woff2') format('woff2'),
        url('myfont.woff') format('woff');
}
```

--------------------------------

### Composer Project Structure

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Design.md

Defines the directory structure for a Composer-based WordPress project, including dependency management and WordPress core installation.

```text
|- composer.json ____________________________ # Define third party dependencies
|- wp-config.php ____________________________ # WordPress configuration
|- wp/ ______________________________________ # Composer install WordPress here
|- wp-content/ ______________________________ # Composer dependencies
|  |- themes/ _______________________________ # Themes directory
|    |- custom-theme/ _______________________ # Custom theme
|  |- plugins/ ______________________________ # Plugins directory
|    |- custom-plugin/ ______________________ # Custom plugin
```

--------------------------------

### Project Directory Structure

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Design.md

The base file structure for all themes and plugins.

```text
|- assets/
|  |- css/ _______________________________ # See below for details
|  |- fonts/ _____________________________ # Custom/hosted fonts
|  |- images/ ____________________________ # Theme images
|  |- js/ ________________________________ # See below for details
|  |- svg/ _______________________________ # Vector images that will be processed into icons
|- bin/ __________________________________ # WP-CLI and other scripts
|- gulp-tasks/ ___________________________ # Individual Gulp tasks
|- includes/ _____________________________ # PHP classes and files
|    |- classes/ _________________________ # PHP classes
|- languages/ ____________________________ # Translations
|- node_modules/ _________________________ # npm modules
|- partials/ _____________________________ # Template parts
|- templates/ ____________________________ # Page templates
|- tests/
|  |- php/ _______________________________ # PHP testing suite
|  |- js/ ________________________________ # JavaScript testing suite
|- vendor/ _______________________________ # Composer dependencies
|- .babelrc ______________________________ # Babel config settings
|- .editorconfig _________________________ # Editor config settings
|- .eslintrc _____________________________ # ESLint config settings
|- composer.json _________________________ # Composer package file
|- gulpfile.babel.js _____________________ # Gulp config settings
|- package.json __________________________ # npm package file
|- webpack.config.babel.js _______________ # Webpack config settings
```

--------------------------------

### Prepare and execute a raw SQL query

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/PHP.md

Uses $wpdb->prepare() to sanitize inputs and force integer types for secure database retrieval.

```php
<?php
global $wpdb;

$wpdb->get_results( $wpdb->prepare( "SELECT id, name FROM $wpdb->posts WHERE ID='%d'", absint( $post_id ) ) );
?>
```

--------------------------------

### Build Mobile-First Responsive Layouts

Source: https://context7.com/10up/engineering-best-practices/llms.txt

Utilize modern CSS features like clamp(), CSS Grid, and Flexbox to create fluid, responsive designs with minimal media query usage.

```css
/* Mobile-first base styles */
.container {
    width: 100%;
    max-width: 75rem;
    margin-inline: auto;
    padding-inline: var(--spacing-md);
}

/* Fluid typography using clamp() - no media queries needed */
.hero-title {
    font-size: clamp(2rem, 5vw + 1rem, 4rem);
    line-height: 1.1;
}

.body-text {
    font-size: clamp(1rem, 0.5vw + 0.875rem, 1.25rem);
}

/* Intrinsic layouts with CSS Grid - adapts without media queries */
.auto-grid {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(min(280px, 100%), 1fr));
    gap: var(--spacing-lg);
}

/* Flexbox with wrapping for natural responsive behavior */
.nav-list {
    display: flex;
    flex-wrap: wrap;
    gap: var(--spacing-sm);
    list-style: none;
    padding: 0;
    margin: 0;
}

/* Use media queries as enhancement, not foundation */
.sidebar-layout {
    display: grid;
    gap: var(--spacing-lg);
}

@media (min-width: 48rem) {
    .sidebar-layout {
        grid-template-columns: 1fr 300px;
    }
}

/* Support 400% zoom - use relative units */
.header {
    padding-block: var(--spacing-md);
}

/* Sticky headers shouldn't dominate at high zoom */
@media (min-height: 30rem) {
    .header--sticky {
        position: sticky;
        top: 0;
    }
}
```

--------------------------------

### Serve Responsive Images with srcset and sizes

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Performance.md

Use the `srcset` and `sizes` attributes on `<img>` tags to serve appropriately sized images based on the viewport and device resolution. This improves performance by reducing bandwidth usage.

```html
<img
  alt="10up.com Logo"
  height="90px"
  srcset="ten-up-logo-480w.jpg 480w,
          ten-up-logo-800w.jpg 800w"
  sizes="(max-width: 600px) 480px,
         800px"
  src="ten-up-logo-800w.jpg"
  width="160px"
/>

```

--------------------------------

### API Key Management with WordPress Filters

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Design.md

PHP code demonstrating how to define API keys using constants, defaulting to development credentials and respecting the `WP_ENVIRONMENT_TYPE`.

```php
<?php
// Production API keys should ideally be defined in wp-config.php
// This section should default to a development or noop key instead.
if ( ! defined( 'CLIENT_MANDRILL_API_KEY' ) {
    if ( 'production' === wp_get_environment_type() ) {
        define( 'CLIENT_MANDRILL_API_KEY', '1234567890' );
    }
}
```

--------------------------------

### Escape HTML Output with esc_html()

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/PHP.md

Use esc_html() to ensure output does not contain any HTML, preventing JavaScript injection and layout breaks. This is an example of late escaping.

```php
<div>
    <?php echo esc_html( get_post_meta( $post_id, 'key', true ) ); ?>
</div>
```

--------------------------------

### Documenting WordPress Hooks and Functions

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/PHP.md

Use verbose docblocks to explain the purpose and logic of functions. Ensure hooks are documented with clear descriptions of parameters and return values.

```php
<?php
/**
 * Hook into WordPress to mark specific post meta keys as protected
 *
 * Post meta can be either public or protected. Any post meta which holds
 * **internal or read only** data should be protected via a prefixed underscore on
 * the meta key (e.g. _my_post_meta) or by indicating it's protected via the
 * is_protected_meta filter.
 *
 * Note, a meta field that is intended to be a viewable component of the post
 * (Examples: event date, or employee title) should **not** be protected.
 */
add_filter( 'is_protected_meta', 'protect_post_meta', 10, 2 );

/**
 * Protect non-public meta keys
 *
 * Flag some post meta keys as private so they're not exposed to the public
 * via the Custom Fields meta box or the JSON REST API.
 *
 * @internal                          Called via is_protected_meta filter.
 * @param    bool   $protected        Whether the key is protected. Default is false.
 * @param    string $current_meta_key The meta key being referenced.
 * @return   bool   $protected        The (possibly) modified $protected variable
 */
function protect_post_meta( $protected, $current_meta_key ) {

    // Assemble an array of post meta keys to be protected
    $meta_keys_to_be_protected = array(
        'my_meta_key',
        'my_other_meta_key',
        'and_another_meta_key',
    );

    // Set the protected var to true when the current meta key matches
    // one of the meta keys in our array of keys to be protected
    if ( in_array( $current_meta_key, $meta_keys_to_be_protected ) ) {
        $protected = true;
    }

    // Return the (possibly modified) $protected variable.
    return $protected;
}
?>
```

--------------------------------

### Optimize Images with Responsive srcset and Lazy Loading

Source: https://context7.com/10up/engineering-best-practices/llms.txt

Use `srcset` and `sizes` for responsive images, `loading="eager"` for LCP images with `fetchpriority="high"`, and `loading="lazy"` for below-the-fold images. Supports modern formats like WebP with fallbacks.

```html
<!-- Above the fold LCP image - load eagerly with high priority -->
<img
    alt="Hero banner showing product showcase"
    src="hero-800w.webp"
    srcset="
        hero-480w.webp 480w,
        hero-800w.webp 800w,
        hero-1200w.webp 1200w,
        hero-1600w.webp 1600w
    "
    sizes="100vw"
    width="1600"
    height="900"
    fetchpriority="high"
    decoding="sync"
    loading="eager">

<!-- Below the fold images - lazy load -->
<img
    alt="Product thumbnail"
    src="product-400w.webp"
    srcset="
        product-200w.webp 200w,
        product-400w.webp 400w,
        product-800w.webp 800w
    "
    sizes="(max-width: 600px) 100vw, 400px"
    width="400"
    height="400"
    loading="lazy"
    decoding="async">

<!-- Responsive picture element with WebP fallback -->
<picture>
    <source
        type="image/webp"
        srcset="image.webp">
    <source
        type="image/jpeg"
        srcset="image.jpg">
    <img
        alt="Descriptive alt text"
        src="image.jpg"
        width="800"
        height="600"
        loading="lazy"
        decoding="async">
</picture>
```

--------------------------------

### Validate Email Output with sanitize_email()

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/PHP.md

Use sanitize_email() to ensure output is a valid email address. This is an example of data validation, offering stricter control than a general escaping function like esc_attr().

```php
<a href="mailto:<?php echo sanitize_email( get_post_meta( $post_id, 'key', true ) ); ?>">Email me</a>
```

--------------------------------

### PHP Class with Docblock and Constructor

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/PHP.md

Define a well-documented PHP class with a leading docblock explaining its purpose and documenting each method and property. The constructor should handle initialization and potential exceptions.

```php
<?php
/**
 * Video.
 *
 * This is a video object that wraps both traditional WordPress posts
 * and various YouTube meta information APIs hidden beneath them.
 *
 * @package    ClientTheme
 * @subpackage Content
 */
class Prefix_Video {

	/**
	 * WordPress post object used for data storage.
	 *
	 * @access protected
	 * @var WP_Post
	 */
	protected $_post;

	/**
	 * Default video constructor.
	 *
	 * @access public
	 *
	 * @see get_post()
	 * @throws Exception Throws an exception if the data passed is not a post or post ID.
	 *
	 * @param int|WP_Post $post Post ID or WP_Post object.
	 */
	public function __construct( $post = null ) {
		if ( null === $post ) {
			throw new Exception( 'Invalid post supplied' );
		}

		$this->_post = get_post( $post );
	}
}
```

--------------------------------

### Disable File Modifications in WordPress

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Systems.md

Use this constant in wp-config.php to prevent code installations or modifications through the WordPress admin area. This enhances security and prevents confusion when using external deployment processes.

```php
define('DISALLOW_FILE_MODS', true);
```

--------------------------------

### Register Assets with Versioning

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/PHP.md

Use a constant to manage asset versions for cache busting when registering scripts.

```php
<?php
define( 'THEME_VERSION', '0.1.0' );

wp_register_script( 'custom-script', get_template_directory_uri() . '/js/asset.js', array(), THEME_VERSION );
```

--------------------------------

### CSS Color Contrast for Accessibility

Source: https://context7.com/10up/engineering-best-practices/llms.txt

Ensure sufficient color contrast for text elements to meet accessibility standards. This example demonstrates a muted text color that passes WCAG AA against a white background.

```css
/* Ensure sufficient color contrast (4.5:1 minimum for normal text) */
.text-muted {
    color: #767676; /* Passes WCAG AA against white background */
}
```

--------------------------------

### Avoiding Barrel Files

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/JavaScript.md

Demonstrates the discouraged barrel file pattern versus the recommended direct import approach.

```javascript
// Do not do this

// File index.js
export * from ./date;
export * from ./time;
export * from ./cache;

// File ./SomeComponent.jsx
import { formatDate } from './utils';
```

```javascript
// Do this

// File ./SomeComponent.jsx
import { formatDate } from './utils/src/date';
```

--------------------------------

### Preload critical resources with HTML

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Performance.md

Use the link tag in the document head to instruct the browser to fetch critical resources early. The as attribute is required to set correct prioritization and cache headers.

```html
<link rel="preload" as="style" href="/path/to/resource" />
```

--------------------------------

### JavaScript Directory Structure

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Design.md

Detailed breakdown of the assets/js directory.

```text
|- assets/js/
|    |- admin/ ___________________________ # JS for the admin
|    |- frontend/ ________________________ # JS for the front end
|       |- components/ ___________________ # Component-level JS
|    |- shared/ __________________________ # Shared JS between the admin and front end
```

--------------------------------

### Organize PHP Code with Namespacing

Source: https://context7.com/10up/engineering-best-practices/llms.txt

Use namespaces and import declarations to prevent naming collisions in non-template PHP files.

```php
<?php
/**
 * Example of proper namespacing with use declarations.
 */
namespace TenUp\ClientName\ProjectName;

use TenUp\ClientName\Common\TwitterAPI;
use TenUp\ClientName\Common\Utilities;

/**
 * Initialize the feature.
 */
function bootstrap() {
    add_action( 'init', __NAMESPACE__ . '\\register_post_types' );
    add_action( 'wp_enqueue_scripts', __NAMESPACE__ . '\\enqueue_assets' );
}

/**
 * Register custom post types.
 */
function register_post_types() {
    register_post_type( 'project', array(
        'public' => true,
        'label'  => __( 'Projects', 'client-theme' ),
    ) );
}

/**
 * Enqueue theme assets.
 */
function enqueue_assets() {
    // Using imported class - cleaner than full namespace path
    $twitter_api = new TwitterAPI();

    wp_enqueue_script(
        'theme-scripts',
        get_template_directory_uri() . '/js/scripts.js',
        array(),
        THEME_VERSION,
        true
    );
}

bootstrap();
?>
```

--------------------------------

### Set X-Frame-Options Header

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Site-Security.md

Configure the X-Frame-Options HTTP header to SAMEORIGIN to protect against clickjacking attacks. This restricts the site from being embedded in frames on other domains.

```text
X-Frame-Options: SAMEORIGIN
```

--------------------------------

### Create a UserProvider with React Context

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/React.md

Implements a provider component that fetches user data and exposes it via a custom hook.

```javascript
import React, { useEffect, useState, useContext, createContext } from 'react';
import PropTypes from 'prop-types';
import { fetchUser } from '../util';

export const UserContext = createContext();

export const useUser = () => {
	const data = useContext(UserContext);

	return data.user ? data.user : null;
};

const UserProvider = ({ children }) => {
	const [user, setUser] = useState(null);

	useEffect(() => {
		fetchUser().then(setUser);
	}, []);

	return <UserContext.Provider value={{ user }}>{children}</UserContext.Provider>;
};

UserProvider.propTypes = {
	children: PropTypes.oneOfType([PropTypes.element, PropTypes.arrayOf(PropTypes.element)])
		.isRequired,
};

export default UserProvider;
```

--------------------------------

### Check Theme Support

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/PHP.md

Verify if the active theme supports a specific feature before executing plugin-specific code.

```php
<?php
if ( current_theme_supports( 'custom-js-feature' ) ) {
	// ok to add custom js
}
```

--------------------------------

### Create Git Commit with Detailed Message

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Version-Control.md

This command initiates an interactive Git commit, allowing for a detailed message that includes a summary, a blank line, and a longer description. The description can provide context, links, or explanations for the changes.

```sh
git commit

# Merge 'feature/polyfill' into gh-pages
#
# matches and closest are used to simplify event delegation:
# http://caniuse.com/#feat=matchesselector
# http://caniuse.com/#feat=element-closest
# Promise and fetch are used to simplify async/ajax functionality:
# http://caniuse.com/#feat=promises
# http://caniuse.com/#feat=fetch
```

--------------------------------

### CSS Directory Structure

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Design.md

Detailed breakdown of the assets/css directory.

```text
|- assets/css/
|    |- admin/ ___________________________ # CSS for the admin
|    |- frontend/ ________________________ # CSS for the front end
|       |- base/ _________________________ # CSS at the top of the cascade
|       |- components/ ___________________ # Component-level CSS
|       |- global/ _______________________ # Variables and configs
|       |- layout/ _______________________ # Layout and helper classes
|       |- templates/ ____________________ # CSS for specific templates
|    |- shared/ __________________________ # Shared CSS between the admin and front end
```

--------------------------------

### Configure pa11y in package.json

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Markup.md

Add this script to your package.json to automate accessibility testing against a specific URL.

```json
"scripts": {
    "pa11y": "pa11y --ignore notice https://projectname.test"
},
```

--------------------------------

### Refactoring Class Usage

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/JavaScript.md

Alternative patterns to class instantiation, including instance-based management and factory functions.

```javascript
// Option 1: still using classes but with a better design
import Module from './mymodule';

const module1 = new Module('.element-selector', {
	/* options */
});
module1.addEventListener('onEvent1', () => {});
module1.addEventListener('onEvent2', () => {});
module1.doSomething();
module1.hide();
```

```javascript
// Option 2: not using classes
import module from './mymodule';

module('.element-selector', {
	/* options */
});
```

--------------------------------

### Demonstrate Global Namespace Pollution

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/JavaScript.md

Shows how variables and properties defined in the global scope are automatically attached to the window object.

```javascript
console.log(this === window); // true

for (var i = 0; i < 9; i++) {
	// Do stuff
}

const result = true;

console.log(window.result === result); // true
console.log(window.i === i); // true
```

--------------------------------

### Define Foundational List Styles

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/CSS.md

Apply default styling to list elements using :where() to maintain low specificity for easier overrides.

```css
:where(ul, ol, dl) {
  /* styles here */
}
```

--------------------------------

### Tag a release version

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Version-Control.md

Command to create an annotated tag for a new release version in the trunk branch.

```sh
git tag -a <version> -m "Tagging <version>"
```

--------------------------------

### Enforce HTTPS and Initialize Typekit

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_layouts/default.html

Redirects traffic to HTTPS when on the production host and initializes Typekit within a try-catch block.

```javascript
var host = "10up.github.io"; if ( window.location.host === host && window.location.protocol !== "https:" ) { window.location.protocol = "https:"; }      {{ site.name }}   try{Typekit.load();}catch(e){}
```

--------------------------------

### Git Plugin Workflow: Gitflow with Semantic Versioning

Source: https://context7.com/10up/engineering-best-practices/llms.txt

Utilize the Gitflow workflow for plugins, incorporating semantic versioning and proper release tagging. Features branch off 'develop', releases are prepared on 'release' branches, and tagged on 'trunk'.

```sh
# Feature development branches off develop
git checkout develop
git pull origin develop
git checkout -b feature/add-settings-api

# After feature complete, merge to develop
git checkout develop
git merge feature/add-settings-api --no-ff
git push origin develop

# Create release branch when ready
git checkout develop
git checkout -b release/1.2.0

# Bump version numbers in plugin header, readme.txt, etc.
# Update CHANGELOG.md following Keep A Changelog format

git add .
git commit -m "Prepare release 1.2.0

- Bump version to 1.2.0
- Update changelog with new features and fixes"

# Merge release to trunk and tag
git checkout trunk
git merge release/1.2.0 --no-ff
git tag -a 1.2.0 -m "Release version 1.2.0"
git push origin trunk --tags

# Merge trunk back to develop
git checkout develop
git merge trunk --no-ff
git push origin develop

# Archive and delete release branch
git tag archive/release-1.2.0 release/1.2.0
git branch -D release/1.2.0
git push origin :release/1.2.0
git push origin archive/release-1.2.0
```

--------------------------------

### Base Heading Styles with :where

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/CSS.md

Establishes foundational styles for headings using the :where pseudo-class for zero specificity. Utilizes CSS custom properties for consistency and resets default margins.

```css
:where(h1) {
  color: var(--color--heading);
  font-family: var(--font--family--heading);
  font-size: var(--font--size--heading-1);
  font-weight: var(--font--weight--heading);
  line-height: var(--font--line-height--heading-1);
  margin-block: 0;
}
```

--------------------------------

### Implement adaptive serving with Network Information API

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Performance.md

Listen for network connection changes to adjust application behavior based on user connectivity. This can be used to toggle low-data modes or report network conditions to analytics.

```js
navigator.connection.addEventListener("change", () => {
   sendBeacon(); // Send to Analytics
   if (navigator.connection.effectiveType === "2g" ) {
     body.classList.add("low-data-mode") 
   }
});
```

--------------------------------

### Enable InnoDB File Per Table

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Systems.md

Enabling this setting ensures each InnoDB table has a dedicated file, allowing disk space to be reclaimed upon table deletion. Disable only if routinely creating and deleting hundreds of tables, which is uncommon for WordPress.

```sql
innodb_file_per_table
```

--------------------------------

### Configure EditorConfig settings

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Design.md

Defines consistent coding styles across different IDEs and editors. Place this file in the project root directory.

```ini
root = true

[*]
indent_style = space
indent_size = 2
trim_trailing_whitespace = true

[*.{php,js,css,scss}]
end_of_line = lf
insert_final_newline = true
indent_style = tab
indent_size = 4
```

--------------------------------

### Structure CSS Nesting Correctly

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/CSS.md

Demonstrates acceptable nesting for state pseudo-classes while keeping element and modifier selectors flat.

```css
/* block */
.button {

  /* ✅ state inside the block is fine */
  &:hover {
    /* styles here */
  }
}

/* ✅ element and modifier stay flat */
.button__icon {
  /* styles here */
}

.button--primary {
  /* styles here */
}
```

--------------------------------

### Preconnect to external origins

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Performance.md

Establishes early network connections to critical third-party origins to reduce latency for above-the-fold resources.

```html
<link rel="dns-prefetch" href="https://fonts.googleapis.com" crossorigin>
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="dns-prefetch" href="https://fonts.gstatic.com" crossorigin>
```

--------------------------------

### Git Theme Workflow: Trunk-Based Development

Source: https://context7.com/10up/engineering-best-practices/llms.txt

Follow trunk-based development for themes. Create feature branches, keep them updated with trunk, and push for code review before merging to staging and then trunk.

```sh
# Create feature branch from trunk
git checkout trunk
git pull origin trunk
git checkout -b feature/add-hero-component

# Make commits with descriptive messages
git add .
git commit -m "Add hero component with responsive image support

- Implement srcset for responsive images
- Add lazy loading for below-fold images
- Include Schema.org markup for SEO"

# Keep feature branch updated with trunk
git checkout trunk
git pull origin trunk
git checkout feature/add-hero-component
git merge trunk --no-ff

# Push feature branch for code review
git push -u origin feature/add-hero-component

# After PR approval, merge to staging for testing
git checkout staging
git merge feature/add-hero-component --no-ff
git push origin staging

# After testing, merge to trunk for deployment
git checkout trunk
git merge feature/add-hero-component --no-ff
git push origin trunk

# Delete feature branch after merge
git branch -D feature/add-hero-component
git push origin :feature/add-hero-component
```

--------------------------------

### Implement ITCSS Architecture with Low Specificity

Source: https://context7.com/10up/engineering-best-practices/llms.txt

Organize styles using the ITCSS structure, utilizing :where() to maintain zero specificity for base elements and CSS custom properties for global configuration.

```css
/* ============================================
   SETTINGS - Global variables and configurations
   ============================================ */
:root {
    /* Colors */
    --color-primary: #0066cc;
    --color-secondary: #333333;
    --color-background: #ffffff;
    --color-text: #1a1a1a;

    /* Typography */
    --font-family-base: system-ui, -apple-system, sans-serif;
    --font-family-heading: Georgia, serif;
    --font-size-base: 1rem;
    --line-height-base: 1.5;

    /* Spacing */
    --spacing-xs: 0.25rem;
    --spacing-sm: 0.5rem;
    --spacing-md: 1rem;
    --spacing-lg: 2rem;
}

/* ============================================
   GENERIC - Reset and global rules
   ============================================ */
*,
*::before,
*::after {
    box-sizing: border-box;
}

:where(body) {
    margin: 0;
    font-family: var(--font-family-base);
    line-height: var(--line-height-base);
    color: var(--color-text);
}

/* ============================================
   ELEMENTS - Bare HTML elements (use :where for zero specificity)
   ============================================ */
:where(h1, h2, h3, h4, h5, h6) {
    font-family: var(--font-family-heading);
    margin-block: 0;
    line-height: 1.2;
}

:where(h1) { font-size: clamp(2rem, 5vw, 3rem); }
:where(h2) { font-size: clamp(1.5rem, 4vw, 2.25rem); }

:where(p) {
    margin-block: 0;
}

:where(a) {
    color: var(--color-primary);
    text-decoration-skip-ink: auto;
}

/* ============================================
   COMPONENTS - UI components with single class specificity
   ============================================ */
.card {
    background-color: var(--color-background);
    border-radius: 0.5rem;
    overflow: hidden;
    /* NO margins - spacing handled by parent container */
}

.card__image {
    aspect-ratio: 16 / 9;
    object-fit: cover;
    width: 100%;
}

.card__content {
    padding: var(--spacing-md);
}

.card__title {
    color: var(--color-secondary);
}

/* Component spacing handled by parent, not the component */
.card-grid {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
    gap: var(--spacing-lg);
}

/* State nested inside component is fine */
.button {
    background-color: var(--color-primary);
    color: white;
    padding: var(--spacing-sm) var(--spacing-md);
    border: none;
    cursor: pointer;
}

.button:hover {
    opacity: 0.9;
}

.button:focus-visible {
    outline: 2px solid var(--color-primary);
    outline-offset: 2px;
}

/* ============================================
   UTILITIES - Single-purpose helper classes
   ============================================ */
.visually-hidden {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    border: 0;
}

.text-center { text-align: center; }
```

--------------------------------

### Implement Object Caching with Cache Priming

Source: https://context7.com/10up/engineering-best-practices/llms.txt

Refresh cache proactively by hooking into relevant actions rather than waiting for user requests. This ensures the cache remains warm and reduces database overhead.

```php
<?php
/**
 * Prime the cache for top 10 most-commented posts when comment counts change.
 *
 * @param int $post_id Post ID.
 * @param int $new     The new comment count.
 * @param int $old     The old comment count.
 */
function prefix_refresh_top_commented_posts( $post_id, $new, $old ) {
    // Force the cache refresh for top-commented posts
    prefix_get_top_commented_posts( $force_refresh = true );
}
add_action( 'wp_update_comment_count', 'prefix_refresh_top_commented_posts', 10, 3 );

/**
 * Retrieve top 10 most-commented posts with caching.
 *
 * @param bool $force_refresh Optional. Whether to force cache refresh. Default false.
 * @return array|WP_Error Array of WP_Post objects or WP_Error.
 */
function prefix_get_top_commented_posts( $force_refresh = false ) {
    $cache_key   = 'prefix_top_commented_posts';
    $cache_group = 'top_posts';

    $top_commented_posts = wp_cache_get( $cache_key, $cache_group );

    if ( true === $force_refresh || false === $top_commented_posts ) {
        $top_commented_posts = new WP_Query( 'orderby=comment_count&posts_per_page=10' );

        if ( ! is_wp_error( $top_commented_posts ) && $top_commented_posts->have_posts() ) {
            // Cache without expiration - primed by comment count hook
            wp_cache_set( $cache_key, $top_commented_posts->posts, $cache_group );
        }
    }
    return $top_commented_posts;
}
?>
```

--------------------------------

### Configure Temporary Table Sizes

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/Systems.md

Modestly size `tmp_table_size` and `max_heap_table_size` (e.g., 8MB or 16MB) for efficient temporary table creation in memory. Larger values are often recommended by MySQLTuner but may not improve performance for WordPress sites with LONGTEXT or BLOB fields in joins.

```sql
tmp_table_size = 16M
```

```sql
max_heap_table_size = 16M
```

--------------------------------

### Insert Dynamic Content via innerHTML

Source: https://github.com/10up/engineering-best-practices/blob/gh-pages/_includes/markdown/JavaScript.md

Demonstrates a common but potentially insecure pattern for injecting HTML strings into the DOM.

```javascript
const someElement = document.getElementById('someElement');
const someUrl = 'https://someurl.com/';
const someContent = 'Some content';

someElement.innerHTML = `<div class="container"><a href="${someUrl}">${someContent}</a></div>`;
```