Aegis

Welcome to the Aegis Theme development repository.

Status

Table of Contents

• Introduction
• Working with Block Themes
  • Site Editor
  • Patterns
  • Global Styles
  • Template Parts
  • Export Your Site
• Presets
  • Layout Presets
  • Spacing Presets
  • Typography Presets
  • Shadow Presets
  • Gradient Presets
• Features
  • Enhanced Core Blocks
  • Custom Blocks
  • Block Variations
  • Plugin Integrations
• Getting Started
  • Requirements
  • Release version
  • Server deployment
• Local development (wp-env)
• Default credentials (wp-env)
• Contributing
  • Communication and Collaboration
  • Code Quality
  • Testing and Validation
  • Version Control
  • Pull Requests and Reviews
  • Final Checks
• Development Philosophy
• Technical Architecture
• Integration Capabilities
• Pattern Creation Guidelines
• Experimenting
• Resources
• Demos
• Roadmap
• Credits
• Suggestions?

Introduction

Aegis is a cutting-edge Full Site Editing (FSE) theme that combines performance with aesthetics. Built with Vanilla JavaScript and Flexbox Grid, Aegis provides a lightweight yet powerful foundation for modern WordPress development.

Upholding the highest coding standards, Aegis is engineered for scalability—from personal blogs to professional portfolios and expansive business sites. The theme seamlessly supports multisite configurations, WooCommerce, SEO optimization, and learning management systems.

Every detail emphasizes performance, accessibility, and user experience. Aegis is particularly optimized for users with color vision deficiency, making it a truly inclusive design solution built to remain relevant for years to come.

Working with Block Themes

When you activate Aegis, it operates in a manner similar to traditional WordPress themes, allowing you to seamlessly create posts and pages as you are accustomed to. However, Aegis distinguishes itself as a block theme, offering enhanced features such as the site editor, patterns, global styles, and much more.

In essence, a block theme like Aegis is a WordPress theme constructed entirely of blocks. This means that in addition to editing the content of posts and pages, you have the capability to use the block editor for modifying every other component of your website, including headers, footers, and various templates. It serves as a comprehensive editor for your website's entire design and layout.

Site Editor

The WordPress site editor heralds a transformative phase in the art of website creation with WordPress. Utilizing the capabilities of blocks, patterns, and a wide array of drag-and-drop design tools, the site editor enables you to construct pages directly within WordPress, obviating the need for a separate page builder.

To refine your website through the site editor, simply navigate to Appearance → Editor. This interface grants you the ability to create and modify templates, develop menus, tailor your site's styles, choose your color palette, fine-tune typography, adjust block styles, and much more. Essentially, this platform serves as your digital canvas, allowing you to design, build, and perfect your website prior to its official launch.

Patterns

Patterns are carefully designed page components that provide a quick method for constructing a specific section of a page or even an entire page layout. Instead of building a page from scratch, WordPress users can now leverage these handy patterns for efficient website design directly within the WordPress Site Editor.

To make use of Aegis's patterns, simply access them via the block inserter while working on posts, pages, or within the site editor itself. These patterns function as flexible design elements that significantly streamline the website construction process.

Creating page designs with patterns

Creating pages featured in the Aegis theme is a streamlined process. Simply insert Aegis's full-page patterns onto any page you desire to design.

For optimal compatibility with the full-page patterns, select the No Page Title template via the editor sidebar. This template effectively removes the default page title from your design. Nevertheless, it is imperative to incorporate an H1 tag within your design to comply with SEO best practices, thereby enabling search engines to accurately identify the primary subject of your page and enhance its ranking.

Global Styles

Global styles constitute a robust feature that enables the comprehensive customization of your website's appearance through the Site Editor. This feature offers a centralized hub where you can modify various styling elements such as typography, fonts, and colors for buttons and links, as well as layout defaults.

Under the hood, the Global styles functionality is driven by a configuration file named theme.json, situated at the root of the theme's directory. This file allows the theme to establish default styles on both a site-wide and block-specific basis. These default styles are then applied universally across your website and can be further customized by users via the Global styles interface.

By leveraging the theme.json file, you can achieve a uniform aesthetic across your website while also providing avenues for customization to meet particular needs or branding objectives. The ultimate outcome is a website that not only exudes a professional design but is also amenable to customization by you or your clients to suit specific requirements.

Template Parts

Template parts in WordPress serve as reusable sections of your website that can be applied across multiple pages or templates. They operate similarly to reusable blocks but function at the template level, making them ideal for elements like headers, footers, or sidebars—components that usually remain constant across most or all pages on your site.

For instance, to maintain a uniform header across all pages, you could create a header template part. Any modifications made to this template part will be automatically reflected on all pages where it is implemented, thereby enhancing the efficiency of site-wide updates.

This methodology not only expedites the design process but also reinforces consistency throughout your website. Instead of laboriously updating identical elements across individual pages, a single modification to the template part will propagate the changes universally.

Within the framework of Full Site Editing (FSE), these template parts can be created and edited directly via the WordPress site editor, offering a cohesive and simplified approach to site construction.

Export Your Site

Here is a comprehensive, step-by-step guide on how to export your custom theme:

1. Navigate to Appearance → Editor to open the WordPress site editor.
2. Upon entering the site editor, locate the Options menu, typically symbolized by three vertical dots, often referred to as the "kebab" menu, situated in the upper right-hand corner of the interface.
3. Click on the Options menu, and under the Tools section, you'll find the Export option.
4. Select Export, at which point WordPress will begin compiling all the modifications and customizations you've made through the site editor. This includes custom blocks, global styles, patterns, templates, and template parts.
5. WordPress will package these custom elements into a .zip file, effectively creating your new custom theme.
6. This .zip file will then automatically download to your computer.

This functionality essentially transforms the site editor into a theme builder. After downloading the .zip file, you can upload and install it on any other WordPress website, much like you would with a conventional theme. This feature serves as a convenient mechanism for migrating your custom designs from a local development environment to a live production site, or for sharing your design work with others.

Presets

Layout Presets

Aegis utilizes responsive layout constraints that ensure optimal content width across all devices:

theme.json preset	theme.json value
contentSize	min(calc(100dvw - var(--wp--preset--spacing--lg,2rem) * 2), 720px)
wideSize	min(calc(100dvw - var(--wp--preset--spacing--lg,2rem) * 2), 1620px)

Spacing Presets

Aegis employs a fluid spacing system that scales intelligently across viewport sizes:

Name	Slug	CSS Variable	Size
XXXS (4px)	xxxs	--wp--preset--spacing--xxxs	4px
XXS (8px)	xxs	--wp--preset--spacing--xxs	var(--wp--preset--font-size--8)
XS (16px)	xs	--wp--preset--spacing--xs	var(--wp--preset--font-size--16)
S (24px)	sm	--wp--preset--spacing--sm	var(--wp--preset--font-size--24)
M (32px)	md	--wp--preset--spacing--md	var(--wp--preset--font-size--32)
ML (40px)	ml	--wp--preset--spacing--ml	var(--wp--preset--font-size--40)
L (48px)	lg	--wp--preset--spacing--lg	var(--wp--preset--font-size--48)
XL (64px)	xl	--wp--preset--spacing--xl	var(--wp--preset--font-size--64)
XLL (80px)	xll	--wp--preset--spacing--xll	var(--wp--preset--font-size--80)
XXL (96px)	xxl	--wp--preset--spacing--xxl	var(--wp--preset--font-size--96)

Typography Presets

Aegis features a comprehensive fluid typography system with 23 font size presets:

Name	Slug	Size	Fluid Range
96px	96	clamp(80px,9.6vw,96px)	80px → 96px
88px	88	clamp(72px,8.8vw,88px)	72px → 88px
80px	80	clamp(64px,8vw,80px)	64px → 80px
72px	72	clamp(56px,7.2vw,72px)	56px → 72px
64px	64	clamp(52px,6.4vw,64px)	52px → 64px
60px	60	clamp(48px,6vw,60px)	48px → 60px
52px	52	clamp(44px,5.2vw,52px)	44px → 52px
48px	48	clamp(40px,4.8vw,48px)	40px → 48px
44px	44	clamp(40px,4.4vw,44px)	40px → 44px
40px	40	clamp(36px,4vw,40px)	36px → 40px
36px	36	clamp(32px,3.6vw,36px)	32px → 36px
32px	32	clamp(28px,3.2vw,32px)	28px → 32px
28px	28	clamp(24px,2.8vw,28px)	24px → 28px
24px	24	clamp(22px,2.4vw,24px)	22px → 24px
22px	22	clamp(20px,2.2vw,22px)	20px → 22px
20px	20	clamp(19px,2vw,20px)	19px → 20px
18px	18	clamp(17px,1.8vw,18px)	17px → 18px
16px	16	clamp(15px,1.6vw,16px)	15px → 16px
14px	14	clamp(13px,1.4vw,14px)	13px → 14px
12px	12	clamp(11px,1.2vw,12px)	11px → 12px
10px	10	clamp(9px,1vw,10px)	9px → 10px
8px	8	clamp(7px,0.8vw,8px)	7px → 8px
Inherit	inherit	inherit	—

Font Families

Name	Slug	Font Family	Weight Range
Lexend	lexend	Lexend, var(--wp--preset--font-family--sans-serif)	300–900
Lexend Deca	lexend-deca	Lexend Deca, var(--wp--preset--font-family--lexend)	300–900
JetBrains	jetbrains	JetBrains, var(--wp--preset--font-family--monospace)	100–900

Shadow Presets

Aegis provides eight box shadow presets for depth and elevation:

Name	Slug	Shadow Value
None	none	none
XX Small	xxs	0 1px 2px 0 var(--wp--custom--box-shadow--color)
X Small	xs	0 1px 2px var(--wp--custom--box-shadow--color), 0 2px 4px 0 var(--wp--custom--box-shadow--color)
Small	sm	0 1px 2px 0 var(--wp--custom--box-shadow--color), 0 4px 12px -4px var(--wp--custom--box-shadow--color)
Medium	md	0 1px 2px 0 var(--wp--custom--box-shadow--color), 0 4px 8px var(--wp--custom--box-shadow--color)
Large	lg	0 2px 4px 0 var(--wp--custom--box-shadow--color), 0 8px 24px var(--wp--custom--box-shadow--color)
X Large	xl	0 4px 8px -4px var(--wp--custom--box-shadow--color), 0 16px 24px -4px var(--wp--custom--box-shadow--color)
XX Large	xxl	0 4px 8px 0 var(--wp--custom--box-shadow--color), 0 24px 48px 0 var(--wp--custom--box-shadow--color)

Gradient Presets

Aegis includes 31 pre-configured gradients for sophisticated visual effects:

Name	Slug	Gradient
Primary 700/500	primary-700-500	linear-gradient(135deg,var(--wp--preset--color--primary-700) 0%,var(--wp--preset--color--primary-500) 100%)
Primary 500/300	primary-500-300	linear-gradient(135deg,var(--wp--preset--color--primary-500) 0%,var(--wp--preset--color--primary-300) 100%)
Primary Transparent	primary-transparent	linear-gradient(180deg,var(--wp--preset--color--transparent) 0%,var(--wp--preset--color--primary-100) 100%)
Primary Foreground	primary-foreground	linear-gradient(135deg,var(--wp--preset--color--primary-900) 0%,var(--wp--preset--color--neutral-950) 100%)
Body/Heading	body-heading	linear-gradient(135deg,var(--wp--preset--color--neutral-600) 0%,var(--wp--preset--color--neutral-950) 100%)
Surface/Border	surface-border	linear-gradient(135deg,var(--wp--preset--color--neutral-100) 0%,var(--wp--preset--color--neutral-200) 100%)
Background/Transparent	background-transparent	linear-gradient(0deg,var(--wp--custom--body--background) 50%,transparent 50%)
Transparent/Background	transparent-background	linear-gradient(180deg,var(--wp--custom--body--background) 50%,transparent 50%)
Fade Left	fade-left	linear-gradient(90deg,var(--wp--preset--color--neutral-0) 0%,transparent 100%)
Fade Right	fade-right	linear-gradient(-90deg,var(--wp--preset--color--neutral-0) 0%,transparent 100%)
Checkerboard	checkerboard	repeating-conic-gradient(var(--wp--preset--color--neutral-200) 0% 25%, transparent 0% 50%) 50% / 16px 16px
Grid	grid	conic-gradient(from 90deg at 1px 1px,transparent 90deg,var(--wp--custom--gradient-grid--color,var(--wp--preset--color--neutral-100)) 0) -1px -1px / var(--wp--custom--gradient-grid--size,40px) var(--wp--custom--gradient-grid--size,40px)
Diagonal Cut Dark Left	diagonal-cut-dark-left	linear-gradient(135deg,var(--wp--preset--color--primary-950) 0%,var(--wp--preset--color--primary-950) 50%,transparent 50%)
Diagonal Cut Dark Right	diagonal-cut-dark-right	linear-gradient(-135deg,var(--wp--preset--color--primary-950) 0%,var(--wp--preset--color--primary-950) 50%,transparent 50%)
Diagonal Cut Light Left	diagonal-cut-light-left	linear-gradient(135deg,transparent 0%,transparent 50%,var(--wp--preset--color--neutral-0) 50%)
Diagonal Cut Light Right	diagonal-cut-light-right	linear-gradient(-135deg,transparent 0%,transparent 50%,var(--wp--preset--color--neutral-0) 50%)
Fade Dark Top	fade-dark-top	linear-gradient(180deg,rgba(9,9,11,0.80) 0%,rgba(9,9,11,0.4) 50%,transparent 100%)
Fade Dark Bottom	fade-dark-bottom	linear-gradient(0deg,rgba(9,9,11,0.80) 0%,rgba(9,9,11,0.4) 50%,transparent 100%)
Long Top Short Bottom	long-top-short-bottom	linear-gradient(180deg,var(--wp--preset--color--primary-950) 0%,var(--wp--preset--color--primary-950) 70%,transparent 70%)
Short Top Long Bottom	short-top-long-bottom	linear-gradient(0deg,var(--wp--preset--color--primary-950) 0%,var(--wp--preset--color--primary-950) 70%,transparent 70%)
Vignette Vertical	vignette-vertical	linear-gradient(180deg,rgba(9,9,11,0.9) 0%,rgba(9,9,11,0.6) 30%,transparent 60%,rgba(9,9,11,0.6) 80%,rgba(9,9,11,0.9) 100%)
Vignette Radial	vignette-radial	radial-gradient(ellipse at center,transparent 0%,rgba(9,9,11,0.8) 100%)
Diagonal Vignette	diagonal-vignette	linear-gradient(135deg,rgba(9,9,11,0.9) 0%,transparent 50%,rgba(9,9,11,0.9) 100%)
Scrim Bottom	scrim-bottom	linear-gradient(180deg,transparent 0%,transparent 60%,rgba(9,9,11,0.95) 100%)
Scrim Top	scrim-top	linear-gradient(0deg,transparent 0%,transparent 60%,rgba(9,9,11,0.95) 100%)
Diagonal Triple	diagonal-triple	linear-gradient(135deg,var(--wp--preset--color--primary-950) 0%,var(--wp--preset--color--primary-950) 33%,var(--wp--preset--color--primary-700) 33%,var(--wp--preset--color--primary-700) 66%,transparent 66%)
Layered Bands	layered-bands	linear-gradient(180deg,var(--wp--preset--color--primary-950) 0%,var(--wp--preset--color--primary-950) 25%,rgba(9,9,11,0.5) 25%,rgba(9,9,11,0.5) 75%,transparent 75%)
Spotlight Bottom Left	spotlight-bottom-left	radial-gradient(circle at 0% 100%,rgba(9,9,11,0.9) 0%,transparent 70%)
Spotlight Top Right	spotlight-top-right	radial-gradient(circle at 100% 0%,rgba(9,9,11,0.9) 0%,transparent 70%)
Cinematic Bars	cinematic-bars	linear-gradient(90deg,rgba(9,9,11,0.9) 0%,transparent 40%,transparent 60%,rgba(9,9,11,0.9) 100%)
Diagonal Stripes	diagonal-stripes	repeating-linear-gradient(135deg,transparent 0px,transparent 10px,rgba(9,9,11,0.1) 10px,rgba(9,9,11,0.1) 20px)

Token Cheat-sheet

Default Global Style

The Aegis theme features a comprehensive color system with Primary, Neutral, and Semantic colors optimized for accessibility and visual hierarchy:

Primary Colors

CSS Variable	Color	Name	Slug	Visual
--wp--preset--color--primary-950	#09090b	Primary 950	primary-950
--wp--preset--color--primary-900	#18181b	Primary 900	primary-900
--wp--preset--color--primary-800	#27272a	Primary 800	primary-800
--wp--preset--color--primary-700	#3f3f47	Primary 700	primary-700
--wp--preset--color--primary-600	#52525c	Primary 600	primary-600
--wp--preset--color--primary-500	#71717b	Primary 500	primary-500
--wp--preset--color--primary-400	#9f9fa9	Primary 400	primary-400
--wp--preset--color--primary-300	#d4d4d8	Primary 300	primary-300
--wp--preset--color--primary-200	#e4e4e7	Primary 200	primary-200
--wp--preset--color--primary-100	#f4f4f5	Primary 100	primary-100
--wp--preset--color--primary-50	#fafafa	Primary 50	primary-50
--wp--preset--color--primary-25	#fcfcfd	Primary 25	primary-25

Neutral Colors

CSS Variable	Color	Name	Slug	Visual
--wp--preset--color--neutral-950	#0a0a0a	Neutral 950	neutral-950
--wp--preset--color--neutral-900	#171717	Neutral 900	neutral-900
--wp--preset--color--neutral-800	#262626	Neutral 800	neutral-800
--wp--preset--color--neutral-700	#404040	Neutral 700	neutral-700
--wp--preset--color--neutral-600	#525252	Neutral 600	neutral-600
--wp--preset--color--neutral-500	#737373	Neutral 500	neutral-500
--wp--preset--color--neutral-400	#a1a1aa	Neutral 400	neutral-400
--wp--preset--color--neutral-300	#d4d4d4	Neutral 300	neutral-300
--wp--preset--color--neutral-200	#e5e5e5	Neutral 200	neutral-200
--wp--preset--color--neutral-100	#f5f5f5	Neutral 100	neutral-100
--wp--preset--color--neutral-50	#fafaf9	Neutral 50	neutral-50
--wp--preset--color--neutral-0	#ffffff	Neutral 0	neutral-0

Semantic Colors

CSS Variable	Color	Name	Slug	Visual
--wp--preset--color--success-950	#032e15	Success 950	success-950
--wp--preset--color--success-900	#0d542b	Success 900	success-900
--wp--preset--color--success-800	#016630	Success 800	success-800
--wp--preset--color--success-700	#008236	Success 700	success-700
--wp--preset--color--success-600	#00a63e	Success 600	success-600
--wp--preset--color--success-500	#00c950	Success 500	success-500
--wp--preset--color--success-400	#05df72	Success 400	success-400
--wp--preset--color--success-300	#7bf1a8	Success 300	success-300
--wp--preset--color--success-200	#b9f8cf	Success 200	success-200
--wp--preset--color--success-100	#dcfce7	Success 100	success-100
--wp--preset--color--success-50	#f0fdf4	Success 50	success-50
--wp--preset--color--warning-950	#451605	Warning 950	warning-950
--wp--preset--color--warning-900	#80310e	Warning 900	warning-900
--wp--preset--color--warning-800	#9f390d	Warning 800	warning-800
--wp--preset--color--warning-700	#c84806	Warning 700	warning-700
--wp--preset--color--warning-600	#e85d04	Warning 600	warning-600
--wp--preset--color--warning-500	#ff7c0e	Warning 500	warning-500
--wp--preset--color--warning-400	#ff9a35	Warning 400	warning-400
--wp--preset--color--warning-300	#ffbf6f	Warning 300	warning-300
--wp--preset--color--warning-200	#ffdaa7	Warning 200	warning-200
--wp--preset--color--warning-100	#ffefd4	Warning 100	warning-100
--wp--preset--color--warning-50	#fff7ec	Warning 50	warning-50
--wp--preset--color--error-950	#460d04	Error 950	error-950
--wp--preset--color--error-900	#82200c	Error 900	error-900
--wp--preset--color--error-800	#a2230a	Error 800	error-800
--wp--preset--color--error-700	#dc2f02	Error 700	error-700
--wp--preset--color--error-600	#f63f00	Error 600	error-600
--wp--preset--color--error-500	#ff5909	Error 500	error-500
--wp--preset--color--error-400	#ff7c31	Error 400	error-400
--wp--preset--color--error-300	#ffab6c	Error 300	error-300
--wp--preset--color--error-200	#ffcea5	Error 200	error-200
--wp--preset--color--error-100	#ffe8d3	Error 100	error-100
--wp--preset--color--error-50	#fff5ec	Error 50	error-50

Utility Colors

CSS Variable	Color	Name	Slug	Visual
--wp--preset--color--transparent	transparent	Transparent	transparent	—
--wp--preset--color--current	currentcolor	Current	current	—
--wp--preset--color--inherit	inherit	Inherit	inherit	—

Features

Aegis is a comprehensive Full Site Editing (FSE) theme that extends the capabilities of WordPress with powerful features designed for modern web development. Built with performance, accessibility, and developer experience in mind, Aegis provides an extensive toolkit for creating stunning, high-performance websites.

Core Architecture

Enhanced Block Supports: Aegis extends WordPress core blocks with additional appearance controls including box shadows, absolute positioning, CSS transforms, and CSS filters. These enhancements provide granular control over block presentation without requiring custom code.

Advanced Global Styles: Leveraging the full power of theme.json, Aegis implements a sophisticated design system with comprehensive color palettes, fluid typography scales, intelligent spacing presets, and responsive layout constraints. Includes 60 style variations with Tailwind-aligned color palettes and dark mode support. All styling is managed through the Site Editor for a seamless customization experience.

Optimized CSS Framework: The theme features a minimal, performance-focused CSS framework where all stylesheets are conditionally loaded only when required by a page. This intelligent asset loading ensures optimal performance while addressing common core CSS issues.

Content & Design Tools

SVG Icon System: Create inline SVG icons directly within the image block or as inline text. Aegis includes WordPress, Dashicons, and Social Icons by default, with full support for custom SVGs. Simply search for "Icon" in the block inserter to get started.

Variable Font Library: Access a curated collection of popular variable Google Fonts, with fonts conditionally loaded based on selections made in Site Editor > Styles. This ensures optimal typography without unnecessary asset bloat.

Gradient Toolset: Rich text gradient formats and comprehensive gradient settings for text blocks enable sophisticated visual treatments. The theme includes pre-configured gradients for common use cases, with support for custom gradient creation.

Advanced Text Formats: Extended text formatting options including clear formatting, underline, gradient text, dynamic font sizes, and more. These formatting tools provide fine-grained control over typography and text presentation.

Pattern Library: Comprehensive collection of 145+ block patterns organized across 15 categories including author pages, blog layouts, commerce templates, contact forms, CTAs, FAQs, features, footers, headers, heroes, modals, page layouts, portfolios, pricing, testimonials, and utility patterns. All patterns are designed for performance and accessibility.

Enhanced Core Blocks

Aegis extends the following WordPress core blocks with additional functionality, styling options, and performance optimizations:

Block	WordPress Block	Description
Button	core/button	Enhanced button styling with additional appearance controls and hover effects
Buttons	core/buttons	Extended button group layouts with responsive alignment options
Calendar	core/calendar	Improved calendar styling and DOM manipulation
Code	core/code	Enhanced code block with syntax highlighting support
Columns	core/columns	Extended column layouts with responsive controls
Cover	core/cover	Advanced cover block with overlay and positioning options
Details	core/details	Styled accordion/disclosure elements
Group	core/group	Enhanced group block with additional layout options
Heading	core/heading	Extended heading styles with gradient and decoration support
Image	core/image	SVG icon support and advanced image controls
List	core/list	Enhanced list styling with custom markers
Navigation	core/navigation	Mega menu support and advanced navigation styles
Navigation Submenu	core/navigation-submenu	Multi-column dropdown menu support
Page List	core/page-list	Improved page list rendering
Paragraph	core/paragraph	Extended text formatting and gradient support
Post Author	core/post-author	Enhanced author display options
Post Comments Form	core/post-comments-form	Styled comment form with accessibility improvements
Post Content	core/post-content	Extended post content rendering
Post Date	core/post-date	Flexible date formatting options
Post Excerpt	core/post-excerpt	Enhanced excerpt display with length controls
Post Featured Image	core/post-featured-image	Advanced featured image options with aspect ratios
Post Template	core/post-template	Extended query loop template options
Post Terms	core/post-terms	Enhanced taxonomy term display
Post Title	core/post-title	Extended title styling options
Query	core/query	Advanced query block configurations
Query Pagination	core/query-pagination	Styled pagination with multiple layouts
Query Title	core/query-title	Enhanced query title rendering
Search	core/search	CSS-only search toggle with full-screen mode
Shortcode	core/shortcode	Improved shortcode block rendering
Social Link	core/social-link	Extended social icon options
Social Links	core/social-links	Enhanced social links container styling
Spacer	core/spacer	Responsive spacer with breakpoint controls
Table of Contents	core/table-of-contents	Styled TOC with smooth scrolling
Tag Cloud	core/tag-cloud	Enhanced tag cloud styling
Template Part	core/template-part	Extended template part rendering
Video	core/video	Advanced video block with lazy loading

Custom Blocks

Aegis includes the following custom blocks built specifically for the theme:

Block	Block Name	Description
Countdown	aegis/countdown	Animated countdown timer with customizable target dates and styling
Map	aegis/map	Interactive Google Maps with custom markers, styles, and geolocation
Modal	aegis/modal	An accessible modal dialog with popup, off-canvas, bottom sheet, and fullscreen modes
Related Posts	aegis/related-posts	Automatically displays related posts based on taxonomy or custom criteria
Slider	aegis/slider	A responsive slider/carousel with multiple slide types, transitions, and navigation options
Slide	aegis/slide	An individual slide within a slider block with support for content, image, and video slide types
Toggle	aegis/toggle	Collapsible content toggle with smooth animations
Toggle Content	aegis/toggle-content	Nested toggle content for complex accordion structures
Video	aegis/video	Advanced video player with custom controls and features

Block Variations

Aegis includes the following custom block variations that extend WordPress core blocks with specialized functionality:

Block Variation	Base Block	Description
Accordion List	core/list	Transforms list blocks into interactive accordion/collapsible elements
Counter	core/paragraph	Animated number counter with customizable start/end values and duration
Curved Text	core/paragraph	Text displayed along a curved SVG path for creative typography
Grid	core/group	Advanced CSS grid layout with responsive column controls
Icon	core/image	Inline SVG icons with WordPress, Dashicons, and Social Icons support
Marquee	core/group	Continuously scrolling horizontal content ticker animation
Newsletter	core/group	Pre-styled newsletter signup form layout
Related Posts	core/query	Automatically queries and displays related posts based on taxonomy
SVG	core/image	Inline SVG rendering with sanitization and styling support

Plugin Integrations

Aegis provides seamless integration with popular WordPress plugins, automatically applying theme styling and enhancing compatibility:

Plugin	Category	Description
Advanced Custom Fields	Custom Fields	ACF JSON save/load paths, theme color palette integration, Block Bindings source for Query Loop
BunnyCDN	Media/CDN	Theme border radius for iframe embeds, dark/light mode styling for player containers
Code Block Pro	Development	Conditional style registration with theme compatibility
Fluent Booking	Scheduling	Dark/light mode support for booking calendars, theme-styled patterns
Fluent Forms	Forms	Theme-styled form elements and layouts
LearnDash	LMS	Focus Mode integration, theme colors and typography, custom block patterns
LifterLMS	LMS	Theme colors and typography, custom block patterns replacing defaults
Rank Math	SEO	Fallback meta description support, hook integration
Sensei LMS	LMS	Theme support declaration, colors and typography, custom block patterns
Syntax Highlighting Code Block	Development	Theme color integration for code highlighting
WooCommerce	E-commerce	Plugin detection and conditional hook registration

Layout & Navigation

Full Site Editing Support: Enhanced page, post, and template part settings make customizing individual pages intuitive and powerful. Aegis provides additional controls and options beyond core WordPress FSE capabilities.

Responsive Controls: Built-in responsive utilities including reverse-on-mobile layouts, hide-on-mobile visibility controls, and intelligent breakpoint management ensure your designs look perfect on all devices.

Flexible Header Styles: Support for absolute positioned headers, transparent header overlays, and sticky navigation styles. These options enable sophisticated header designs that adapt to different page contexts.

Mega Menu System: Create sophisticated multi-column dropdown menus using the core submenu block. Aegis's mega menu implementation leverages native WordPress blocks for maximum compatibility and ease of use.

CSS-Only Search Toggle: Full-screen search functionality with a pure CSS implementation—no JavaScript required. This search toggle provides an elegant user experience while maintaining optimal performance.

User Experience

Intelligent Dark Mode: Automatic dark mode support that adapts to user preferences and system settings. Dark mode can be customized or deactivated through the Blockify settings in the page editor, providing flexibility for different use cases.

Accessibility First: Designed with accessibility at its core, Aegis prioritizes WCAG compliance, semantic HTML, proper heading hierarchies, and keyboard navigation. The theme is optimized for users with color vision deficiency.

Performance Optimized: Every aspect of Aegis is engineered for speed. From conditional asset loading to optimized CSS delivery and minimal JavaScript footprint, the theme ensures fast page loads and excellent Core Web Vitals scores.

Developer Tools & Framework

Custom Block Collection: Aegis includes 9 custom blocks built for modern web development: Countdown, Map, Modal, Related Posts, Slider, Slide, Toggle, Toggle Content, and Video. Each block is engineered for performance and extensibility.

Analytics System: Privacy-first analytics framework with Tracker and ScriptProxy components. Provides comprehensive site analytics while respecting user privacy and GDPR compliance.

Supported Analytics Services:

• Free Tier: Google Analytics 4 (GA4), Google Tag Manager (GTM), Microsoft Clarity, Plausible Analytics, Fathom Analytics, basic GDPR compliance
• Pro Tier: Matomo Analytics, Meta Pixel, Google Consent Mode v2, Data Layer integration, Debug Mode
• Script Proxy: Secure proxy for external scripts with additional privacy controls

Hook Patterns System: Dynamic content injection framework with Manager and Renderer components. Enables sophisticated content manipulation and conditional display logic.

Conditional Logic Settings: Advanced conditional settings system for blocks and patterns. Provides granular control over content display based on user roles, device types, and custom conditions.

Framework Architecture: Built on the Aegis Framework (vendor/aegis/framework) with ServiceProvider pattern. Provides a robust foundation for theme development and extensibility.

Core Block Extensions: Enhanced core WordPress blocks including advanced Breadcrumbs with taxonomy support. Extends block functionality while maintaining compatibility.

Video Editor Extensions: Advanced video editing capabilities in the block editor. Provides comprehensive video controls and customization options.

WooCommerce Integration: Full WooCommerce support with store templates, mini-cart variants, and multi-step checkout enhancements. Optimized for e-commerce performance.

Pattern Creation Guidelines

For the construction of patterns pertaining to the default theme, kindly consult the guidelines delineated in the block-patterns handbook.

• Category Selection

When crafting block patterns for WordPress, it is imperative to judiciously select the appropriate category for each pattern. WordPress offers a predefined set of categories, each designed to serve a distinct purpose. We would recommend adhering to these default categories. Multiple categories may be applied by separating them with commas. A list of the relevant slugs is available for your reference.

• Hiding patterns from the inserter

To regulate the visibility of your block pattern within the WordPress inserter, one can include a specific line of code during the pattern's registration process. This practice is generally employed for utility patterns that are not intended for direct user access via the inserter or the pattern library.

Such utility patterns are often created for specialized purposes, like translation, as exemplified by the 404 pattern.

The requisite line of code to accomplish this is provided below:

* Inserter: no

For the purpose of maintaining consistency and clarity, we would recommend prefixing the filenames of hidden block patterns with hidden- when naming the pattern files. This convention will facilitate easier identification and management of such patterns.

• Different translation functions and when to use them

In software development, especially in the context of internationalization, various translation functions serve distinct purposes. Understanding when to use each one is crucial for effective localization. Here is an overview of different types of translation functions and their recommended use-cases:

esc_html_x(): Utilize this function when translation and HTML safety are required for text display. It is particularly beneficial for multilingual websites, as it offers both translation support and HTML security.

esc_html__(): Utilize the esc_html__() function for the translation and secure rendering of text embedded in HTML, especially when context-specific translations are not necessary. This function serves as a simpler alternative to esc_html_x().

esc_attr__() and esc_attr_x(): Employ the esc_attr__() and esc_attr_x() functions for the secure translation and rendering of text intended for HTML attributes, including elements like image source URLs or link targets. These functions contribute to security by sanitizing user inputs, making them safe for attribute usage.

esc_html_e: The esc_html_e function operates similarly to esc_html__(), with the added convenience of directly outputting the string, thereby eliminating the need for an explicit echo statement.

When dealing with simple HTML tags within translatable strings, employing echo wp_kses_post( __( 'Lorem ipsum <em>Hello</em> dolor sit amet.', 'textdomain' ) ); is advisable. This approach not only makes the syntax more transparent for translators but also affords them the flexibility to remove the markup should it prove incompatible with their respective languages.

These functions serve to bolster both security measures and localization initiatives within WordPress block patterns. They ensure that the text is not only secure for display but also readily translatable, thereby accommodating a global audience.

• Patterns with images

To generate dynamic image links within your block patterns, it is advisable to employ the get_template_directory_uri() function. This function fetches the URL of the active theme's directory, thereby ensuring that the image links remain relative to the theme. This is crucial for maintaining link integrity, particularly if the website's directory structure undergoes changes or if a child theme is in use. Such a practice is integral for ensuring the long-term stability and portability of your patterns.

It is imperative to include alternative text (alt text) for your images to enhance accessibility. Additionally, removing the IDs from these images is crucial for ensuring their versatility across different implementations.

<!-- wp:image {"id":125,"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="https://aegis.local/wp-content/themes/aegis/assets/images/project.webp" alt="" class="wp-image-125"/></figure>
<!-- /wp:image -->

For example, turns into:

<!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large"><img src="<?php echo esc_url( get_template_directory_uri() ); ?>/assets/images/project.webp" alt="<?php echo esc_attr_x( 'Picture of a Project', 'Alt text for project picture', 'aegis' ); ?>"/></figure>
<!-- /wp:image -->

• Use of Post Types, Block Types and Template Types

We employ Block Types when a pattern incorporates custom markup tailored for a specific block or one of the default template parts, such as the footer or header. Utilizing Block Types will prompt the pattern as a suggestion when a user inserts the corresponding block or template part. This is particularly useful for specialized blocks like query and post-content, as well as for template parts like the footer.

Template Types are used when we wish to offer our pattern as a suggestion for a specific template. In such instances, we provide the template slug, which could be identifiers like 404, home, or single, among others.

Post Types serve to limit the types of posts for which a pattern can be used. This is most commonly employed for full-page patterns, allowing you to specify the kind of posts that can utilize the particular pattern.

• Spacing, Colors and Font Sizes

Utilizing presets for elements like spacing, font sizes, and colors in WordPress block patterns is favored over using hardcoded values, and this preference is underpinned by three primary considerations:

Consistency: Presets contribute to a harmonious design throughout the theme, thereby fostering a unified visual aesthetic.

Scalability: Employing presets simplifies the process of making global design adjustments, thereby conserving both time and development effort.

Accessibility: The use of presets aids in complying with accessibility guidelines, thereby rendering your patterns more usable and legible for a diverse audience.

• Additional Tips

It is essential to maintain a clean and adaptable codebase when working with WordPress themes and blocks. Just as it is prudent to remove IDs from image blocks for versatility and broader applicability, it is similarly important to remove the queryId attribute from query blocks. This practice enhances the flexibility of your query blocks, making them more reusable and portable.

Additionally, if any of your template parts possess a theme attribute, this should be eliminated as well. Removing the theme attribute ensures that the template parts can be easily transferred and reused across different themes without being tightly bound to a specific one.

By adhering to these guidelines, you further standardize your blocks and template parts, thereby making them more universally applicable and easier to manage.

<!-- wp:query {"queryId":18,"query":{"perPage":8,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true}} -->

Turns into:

<!-- wp:query {"query":{"perPage":8,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true}} -->

And:

<!-- wp:template-part {"slug":"header","theme":"aegis","area":"header"} /-->

Turns into:

<!-- wp:template-part {"slug":"header","area":"header"} /-->

Here are some best practices that can optimize your workflow and enhance our theme's functionality:

1. Centralizing Common Properties: If you find yourself repeatedly assigning the same properties to a particular block type—such as applying a border radius to image blocks—consider consolidating these recurring settings in the theme.json file. This promotes a more efficient, DRY (Don't Repeat Yourself) approach to theme development.

2. Prefixing Full-Page Patterns: For clarity and ease of identification, prefix all full-page patterns with page-. This nomenclature makes it easier to distinguish these patterns from others and streamlines the pattern selection process.

3. Pattern Order in the Inserter: The order in which patterns appear in the inserter is determined alphabetically by the name of the file. If you wish to influence this order, consider renaming the files accordingly.

By adhering to these practices, you can make your development process more streamlined, your codebase more maintainable, and your user experience more intuitive.

Development

Getting Started with Aegis

To get started with Aegis development:

1. Set up a WordPress instance locally.
2. Download Aegis.
3. Unzip and upload the theme into your /wp-content/themes/ directory.

If you find setting up WordPress locally overwhelming, consider using wp-env, Local, or DevKinsta.

Requirements

• Aegis
• WordPress 6.6+ (Tested up to 6.9.4)
• PHP 8.1+ (Node 20+ and npm 9+ for building blocks and running wp-env; see package.json engines and .nvmrc)
• License: GPLv2 or later.

Release version

The theme release number is the single value defined in three places: style.css (Version), package.json (version), and composer.json (version). When you cut a release, update all three to match (for example 1.0.0-rc.3).

PHP dependencies are pinned by composer.lock. After cloning, run composer update once in the theme directory (with Git network access) to generate or refresh the lockfile, then commit composer.lock. If Composer reports an SSL or certificate error when using GitHub, fix your system or PHP CA bundle (see the Composer doc on local issuers). Use composer install in CI, and run composer update only when you intend to change dependency revisions and then re-test.

Server deployment

functions.php requires vendor/autoload.php, so a complete vendor/ directory must exist in the active theme on the server. Deploying the theme without it will cause a fatal error when WordPress loads the theme.

• Default production flow: in the theme directory (where composer.json and composer.lock are present), run composer install --no-dev. That installs only require packages, not require-dev (the usual choice for public sites). Use plain composer install only on hosts where you truly need dev dependencies.
• Alternative: build a release package in CI and upload a zip (or use your deploy pipeline) that already includes vendor/, so the server never runs Composer—as long as that artifact is what you install.

Note Some features may require the latest WordPress version or the Gutenberg plugin for full functionality.

Some Aegis features and/or pull requests may require the Gutenberg plugin trunk and will be described or tagged accordingly.

To optionally run tests locally, it will also be required:

• Node.js
• Composer

Install dev tooling from the theme directory: npm install and composer install. Use a Node.js 20+ LTS (see package.json engines and .nvmrc).

JavaScript / CSS (block source)

• npm run lint:js — ESLint (via wp-scripts)
• npm run lint:css — stylelint (via wp-scripts); can fix where configured

PHP (WordPress Coding Standards & tests)

• composer run standards:check — PHPCS using phpcs.xml (WordPress Coding Standards). To scan one file: composer run standards:check -- path/to/file.php
• composer run standards:fix — PHPCBF auto-fix
• composer run analyze — alias for standards:check
• composer run lint — alias for standards:check
• composer run test or composer run test:php — theme PHPUnit (phpunit.xml, tests/Unit)
• npm run test:php — same PHPUnit run via npm (requires composer install so vendor/bin/phpunit exists)
• composer run test:wpaudit — in-house aegis/wpaudit suite in tools/wpaudit (same as CI; tools/wpaudit is committed so the path require-dev works)

Local development (wp-env)

wp-env is bundled as a dev dependency. It needs Docker (Windows: WSL2 backend recommended) and Git.

From your clone of this repository (theme root, where package.json lives):

1. npm install
2. composer install
3. npm run build (or npm run build:dev for an unminified development build with source maps) to compile block assets
4. npm run env:start — boots WordPress with this theme mapped from .wp-env.json as wp-content/themes/aegis
5. npm run env:install — one-time: wp core install and wp theme activate aegis (safe to re-run; install step is ignored if the site already exists)

Default site URL: http://localhost:8888 (set port in .wp-env.json or WP_ENV_PORT if 8888 is in use). Local overrides: copy options into .wp-env.override.json (gitignored).

Ongoing work

• npm run dev or npm start — webpack watch for src/Blocks and related build entries
• npm run env:cli -- plugin list — run WP-CLI inside the container (prefix is wp; anything after env:cli -- is passed to wp)
• npm run env:restart — wp-env stop then wp-env start after you change environment config
• npm run env:stop — stop containers
• npm run env:clean — wp-env clean all to reset downloaded volumes (destructive; use when you need a clean WP core)

Other local stacks — Local, DevKinsta, Laragon, MAMP, etc. work the same as any WordPress site: place or symlink the theme in wp-content/themes/aegis, run composer install and npm install && npm run build, then activate Aegis in the admin.

Default credentials (wp-env)

Database (inside Docker): user root, password password, host from wp-env (see wp-env MySQL).

WordPress admin (after env:install): open http://localhost:8888/wp-admin — username admin, password password unless you changed them

To generate a new password (recommended):

1. Go to the Dashboard.
2. Click the Users menu on the left.
3. Click the Edit link below the admin user.
4. Scroll down and click 'Generate password'. Either use this password (recommended) or change it, then click 'Update User'. If you use the generated password be sure to save it somewhere (password manager, etcetera).

Contributing

Contributing to the Aegis theme or any other open-source project can be a rewarding experience, both for personal growth and for the community at large. Here are some advices for contributors to ensure a smooth and effective contribution process:

Communication and Collaboration

Read the Documentation: Always start by reading the project's documentation and guidelines. Understanding the project's structure and coding standards is crucial for effective contribution.

Join Community Channels: Most projects have a community chat or forum. Join these channels to ask questions, share ideas, and stay updated.

Start Small: If you are new to the project, begin with "good first issue" or "beginner-friendly" tags. These are usually easier to tackle and a good place to start.

Code Quality

Follow Coding Standards: Adhere to the coding standards and guidelines provided by the project. This ensures consistency and readability.

Write Clean Code: Keep your code as clean and as simple as possible. Simplicity often leads to fewer bugs and easier maintenance.

Comment Wisely: Comment your code to explain why you did something, not what you did. Good code mostly speaks for itself.

Testing and Validation

Test Thoroughly: Before submitting a pull request, test your changes rigorously to ensure they do not introduce new bugs.

Cross-Browser Compatibility: Make sure to test the features in various browsers to ensure compatibility.

Version Control

Use Descriptive Commit Messages: Your commit messages should be descriptive enough to let other contributors understand the changes you have made.

Keep Commits Focused: Each commit should represent a single logical change. Avoid mixing multiple changes into a single commit.

Pull Requests and Reviews

Pull Requests Descriptions: When submitting a pull request, include a comprehensive description explaining the need for the changes, how you have implemented them, and any additional context.

Be Open to Feedback: Once you submit a Pull Request, maintainers or other community members may suggest changes. Be open to feedback and willing to make revisions.

Final Checks

Check for Upstream Changes: Before making a pull request, make sure you have updated your fork with the latest changes from the main repository to minimize merge conflicts.

Documentation: If your changes include new features or significant modifications, update the relevant documentation.

By adhering to these tips and best practices, you will be making a valuable contribution to the project and fostering a healthy, collaborative community.

Before contributing, please read the contributors' Code of Conduct and Contributing for information about how to open bug reports, contribute patches, test changes, write documentation, or get involved in any way you can.

If after reading you still wish to contribute with code, the list of open issues is a superb place to start scrutinising for tasks. However, pull requests are preferred when linked to an existing issue.

Be advised that contributing is not just for developers. We welcome anyone willing to contribute with code, testing, triage, discussion, designing while building patterns and templates, making Aegis more accessible, etcetera. So please, feel free to look through open issues, and join wherever you feel most comfortable.

Development

Aegis aims to minimize asset loading through a highly performant approach. The theme relies on the Block Editor and Global Styles for most visual rendering, embracing a Full Site Editing philosophy.

Avoid building custom PHP or JavaScript workarounds for functionality already provided by Aegis or the Block Editor. Aegis is minimalistic, lightweight, and performant—designed with accessibility in mind, particularly for users with color vision deficiency. Keep the code simple.

Aegis has no unnecessary build process, maintaining simplicity and performance.

If you have contributed to Aegis, you will receive proper credit. We update CONTRIBUTORS.md periodically. If we have missed anyone, please open a pull request or issue.

Technical Architecture

• Zero-Base Loading Strategy — Assets loaded conditionally based on page content
• Conditional Asset Loading — Smart asset enqueuing via AssetManager
• Hook Patterns System — Dynamic content injection with Manager/Renderer pattern
• PSR-4 Autoloading — Modern PHP class loading with Composer
• ServiceProvider Pattern — Framework service registration and management
• Interactivity API Usage — WordPress Interactivity API integration
• TypeScript Support — Type-safe block development with TSX

Integration Capabilities

• Plugin Integration Framework — Extensible architecture for third-party plugins
• Block Extension System — Core block enhancements via filters and hooks
• Template System — Full template hierarchy with block markup support
• Asset Pipeline — Webpack-based build system with WordPress externals

Experimenting

If you wish to experiment with custom code, consider using the Aegis Child Theme for customization or extending functionality with code snippets.

Repository	Description
Aegis Child Theme	Official Aegis Child Theme
Aegis Code Snippets	Official Aegis Code Snippets

Resources

Here are some resources that may be helpful to context for learning more about developing block-based themes:

• Create a Block Theme (tutorial)
• Full site editing development in the Gutenberg Repository
• Block-based Theme Documentation
• Global Styles and theme.json Documentation
• Global Styles development in the Gutenberg Repository
• theme.json Documentation

Demos

Explore Aegis in action through our official child themes:

Child Theme	Description
Aegis Child Theme	Official starter child theme for Aegis
Aegis Code Snippets	Collection of code snippets and customizations

Roadmap

Is there a public roadmap?

No, and this is by design. Although we follow a strict internal roadmap, we choose not to broadcast it to protect our innovations and give our team the peace of mind to perfect complex features without public pressure. We prefer the element of surprise by delivering unique tools that delight you rather than just ticking boxes on a public list.

Credits

The thumbnail on this README.md file:

Aegis by Atmostfear Entertainment S.A.S., CCO

Suggestions?

To propose improvements to this repository, please open an issue or pull request.