# EXE Theme — Developer Handoff
**Project:** EXE Theme (EXE 2025) for executionspace.com  
**Prepared for:** Milton  
**Prepared by:** Erik  

---

## Overview

EXE Theme is a WordPress Full Site Editing (FSE) child theme of **Twenty Twenty-Five**, built to match custom Figma designs for Execution Space — a systems integration company. The theme lives in a Git repo and Erik reviews all changes via browser (he is not editing files directly). Your job is to build and push to the repo; Erik will interact with the live site.

---

## Dev Environment Setup

- **Theme type:** WordPress FSE child theme of Twenty Twenty-Five
- **Workflow:** Build locally → push to repo → Erik reviews in browser
- **Site Editor:** Used extensively for template parts and patterns — changes pushed via code should reflect in the editor
- **Tools you'll need:** WordPress local environment (e.g. LocalWP or similar), access to the Git repo, browser DevTools for CSS debugging

**To get started:**
1. Clone the repo and activate the theme on a local WordPress install
2. Ensure Twenty Twenty-Five is installed as the parent theme
3. Familiarize yourself with the WordPress Site Editor (Appearance → Editor)
4. Review `theme.json` first — it's the foundation of the entire design system

---

## Theme Architecture & File Structure

The theme follows standard WordPress FSE conventions:

```
exe-theme/
├── theme.json              # Design system: colors, typography, layout
├── style.css               # Theme declaration + base styles
├── functions.php           # Enqueues, block support registration
├── parts/
│   ├── header.html         # Site-wide header (logo + nav)
│   └── footer.html         # Site-wide footer
├── templates/
│   ├── index.html          # Default template
│   ├── single.html         # Single post
│   └── page.html           # Static page
├── patterns/               # Reusable block patterns for content sections
└── assets/
    └── css/                # Semantic CSS files (not inline styles)
```

**Key principle:** Single `header.html` and `footer.html` template parts are used site-wide. Any change there propagates everywhere automatically — be careful.

---

## Design System

### Typography

Font family: **Figtree** (Google Fonts)

| Token | Size | REM |
|-------|------|-----|
| H0 | 96px | 8rem |
| H1 | 64px | 5.33rem |
| H2 | 48px | 4rem |
| H3 | 40px | 3.33rem |
| H4 | 32px | 2.66rem |
| H5 | 24px | 2rem |
| H6 | 20px | 1.66rem |
| Paragraph Large | 18px | 1.5rem |
| Paragraph Medium | 16px | 1.33rem |
| Paragraph Small | 14px | 1.167rem |
| Paragraph Extra Small | 12px | 1rem |

Font size slugs in `theme.json` must match these exactly — mismatched slugs can break the entire theme.

### Color Palette

| Role | Notes |
|------|-------|
| Background | Primary background |
| Background Alt | Alternate background variant |
| Text | Primary text |
| Text Alt 1 | Secondary text variant |
| Text Alt 2 | Tertiary text variant |
| Accent | Brand accent |
| Black | Pure black |

Colors are defined as design tokens in `theme.json` and referenced throughout templates and patterns.

### Buttons

Two button styles are in use — standard case and uppercase (all-caps). Both are defined as block styles rather than custom HTML, so they're managed through the block editor's button styles system.

### Layout

- Content width and wide width are set in `theme.json` — Twenty Twenty-Five's defaults are narrow and have been overridden
- Use `theme.json` to adjust layout constraints, not custom CSS hacks

---

## Key Decisions & Known Issues

### Decisions Made

- **Child theme of Twenty Twenty-Five** — inherits core FSE support while allowing full customization
- **`theme.json` first approach** — all design tokens (colors, type, spacing, layout) are defined here before any CSS is written
- **Semantic CSS over inline styles** — all styling goes in `/assets/css/` files with meaningful class names, never inline
- **Block patterns for content sections** — reusable patterns registered in `/patterns/` keep content consistent and editable in the Site Editor
- **Template parts for global elements** — single source of truth for header and footer

### Known Issues & Gotchas

- **Header styling conflicts** — WordPress generates inline styles that can override background colors and sticky positioning on the header block. This has been a recurring pain point. If header styles aren't applying, check for WordPress-generated inline styles in DevTools before adding more CSS.
- **Sticky header + block styles** — sticky positioning on the header can conflict with WordPress's own generated styles. Test carefully after any header changes.
- **Font size slug mismatches** — if `theme.json` font size slugs don't exactly match what's referenced in templates/patterns, the theme styling can break silently. Always verify slugs are consistent.
- **Twenty Twenty-Five content width** — the parent theme has a narrow default content width. This has been overridden in `theme.json`. Don't revert these settings.
- **CSS variable conflicts** — the block editor can create CSS variable conflicts. If something looks right in the file but wrong in the browser, JavaScript-based solutions or direct edits via the WordPress Editor may be needed rather than external file changes.
- **Recent pattern breakage** — a previous attempt to push updated patterns broke the theme's styling and required a rollback. When adding or updating patterns, test incrementally and keep the last working version handy.

---

## Working with Claude

This handoff was prepared with Claude's help, and Claude has context on this project. When you want to continue work or ask questions, start a conversation and share this document. Claude can help you with:

- Writing or updating block patterns and template parts
- Debugging CSS conflicts with the block editor
- Extending `theme.json` with new tokens
- Reviewing Figma designs (from the mockups PDFs) and translating them to block markup

**Tip:** Be specific about what's broken, what you've already tried, and include relevant code snippets or DevTools output. Claude will ask clarifying questions if needed.

---

## Reference

- [WordPress FSE Documentation](https://developer.wordpress.org/block-editor/getting-started/full-site-editing/)
- [theme.json reference](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/)
- [Block Patterns](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-patterns/)
- Design files: Figma (ask Erik for access)
- Mockup PDFs: available in the project repo or from Erik