Theme architecture
Theme architecture defines how templates, sections, and reusable components are organized for long-term maintainability. The baseline favors semantic HTML and explicit responsibility per file.
Structure model
| Layer | Purpose | Typical files |
|---|---|---|
| Template layer | Page-level rendering and route-specific layout | front-page.php, page-templates/*.php |
| Partial layer | Reusable structural fragments | partials/*.php, header*.php, footer*.php |
| Content layer | Doc body content separated from shell | docs-content/*.php |
| Asset layer | Scoped style and behavior per page | assets/css/pages/*.css, assets/js/pages/*.js |
Semantic rules
- Use landmark elements (header, main, section, article, nav, footer) intentionally.
- Keep heading order valid and avoid skipping hierarchy levels.
- Keep presentation classes separate from document meaning.
Component boundaries
✓ Expected pattern
Helpers render reusable markup blocks
Page templates orchestrate structure only
Content files remain focused on copy and section flow
Page assets are loaded only where needed
✕ Avoid
Duplicating large markup blocks across pages
Mixing routing logic into content files
Adding global CSS for single-page components
Tightly coupling JS behavior to fragile markup assumptions
Implementation noteWhen introducing a new component, add helper + CSS + JS support together so behavior and markup remain synchronized.