Abira — Documentation

A minimal WordPress block starter theme. Abira gives you a clean foundation — white, black, and one accent color — so you can build without clearing away what someone else put there first.

This document covers installation, customization, and the structure of the theme for developers who want to extend it.

Table of contents

1. Requirements
2. Installation
3. Quick start
4. Theme structure
5. Templates
6. Patterns
7. Style variations
8. Customizing colors, fonts, and spacing
9. Block styles
10. Accessibility
11. Using Abira as a parent theme
12. Translation
13. FAQ
14. License

Requirements

Abira is a full block theme. It does not support classic widgets, classic menus, or the Customizer color/font controls — everything is managed through the Site Editor.

Installation

1. In your WordPress admin, go to Appearance > Themes > Add New.
2. Search for "Abira", or click Upload Theme and select the abira.zip file.
3. Click Activate.
4. Go to Appearance > Editor to start customizing templates, patterns, and global styles.

Quick start

Abira ships with two pages prepared as examples of how the front page and posts page work together:

1. Go to Settings > Reading.
2. Under Your homepage displays, choose A static page.
3. Set Homepage to a page using the Front Page template (templates/front-page.html).
4. Set Posts page to a separate page. This page will automatically use templates/home.html and list your latest posts.

If you don't set a posts page, your homepage falls back to templates/home.html and shows the post list directly.

What the front page shows

templates/front-page.html renders, in order:

1. The header.
2. The Front Page Hero pattern (abira/front-page-hero) — an illustration and a short line of text. This appears even if the page itself has no content yet.
3. The page's own content (post-content) — whatever you write in the block editor for that page.
4. A "Latest Posts" heading followed by a 3-column grid of your 3 most recent posts (sticky posts excluded).
5. The footer.

This means you can leave the front page's content empty and still get a complete, populated homepage — or you can add your own blocks above the post grid.

Theme structure

abira/
├── style.css                 Theme header + base CSS reset, layout, card styles
├── theme.json                 Global settings and styles (v3)
├── functions.php              Theme setup, enqueueing, block style registration
├── readme.txt                 WordPress.org readme (changelog, credits, license)
├── screenshot.png             Theme screenshot shown in Appearance > Themes
├── accessibility.txt          Accessibility statement
│
├── templates/                 Full-page block templates
│   ├── index.html
│   ├── front-page.html
│   ├── home.html
│   ├── single.html
│   ├── page.html
│   ├── page-no-title.html     Custom template: Page (No Title)
│   ├── archive.html
│   ├── search.html
│   ├── 404.html
│   └── blank.html             Custom template: Blank
│
├── parts/                     Template parts (header, footer)
│
├── patterns/                  PHP-registered block patterns
│   ├── front-page-hero.php
│   ├── query-loop.php
│   ├── query-loop-card.php
│   ├── query-pagination.php
│   ├── query-no-results.php
│   ├── single-post-header.php
│   ├── single-post-content.php
│   ├── single-post-navigation.php
│   ├── single-comments.php
│   ├── single-author-bio.php
│   ├── search-content.php
│   ├── page-comments.php
│   └── 404-content.php
│
├── styles/                    Global style variations
│   ├── primary.json
│   ├── nordic.json
│   └── dusty-rose.json
│
├── assets/css/
│   ├── editor-style.css       Editor-only parity styles
│   ├── block-style.css        core/navigation specific CSS
│   └── block-styles.css       Custom block style CSS (button outline,
│                               separator wavy) + post-card layout CSS
│
└── languages/                 .pot/.po/.mo translation files

Templates

All templates and template parts are editable from Appearance > Editor > Templates. Changes you make there are saved as overrides and take precedence over the theme's files, the same way a child theme would.

Patterns

Abira's patterns are registered as PHP files under patterns/, using the standard WordPress pattern header format:

<?php
/**
 * Title: Pattern Name
 * Slug: abira/pattern-slug
 * Categories: abira
 */
?>
<!-- block markup -->

All patterns appear under the Abira category in the pattern inserter, and can be inserted into any page or post — not just the templates that use them by default.

Notable patterns:

• abira/front-page-hero — An inline SVG illustration (a minimal browser-window sketch) plus a short caption. Used at the top of the front page template. Edit the SVG directly in patterns/front-page-hero.php if you want a different illustration.
• abira/query-loop-card — A card layout for the query loop, used in front-page.html and archive.html. Featured images are wrapped in a fixed 16:9 container that reserves its place even when a post has no featured image, so cards in a grid stay aligned. Excerpts are clamped to 5 lines.
• abira/query-loop — A simpler list-row layout for the query loop, used in home.html.

Style variations

Global style variations let you switch the entire color palette from Appearance > Editor > Styles > Browse styles, without editing theme.json.

Each variation is a JSON file under styles/ and only overrides settings.color.palette (plus any related style references) — layout, spacing, and typography stay the same across all variations.

Customizing colors, fonts, and spacing

All of Abira's design tokens are defined in theme.json under settings, and are editable visually from Appearance > Editor > Styles without touching code:

• Colors — settings.color.palette. Six colors: Base, Contrast, Accent, Accent Light, Subtle, Muted. Custom colors are disabled by design ("custom": false) to keep the palette consistent; switch to a style variation instead, or edit theme.json directly if you need a fully custom palette.
• Fonts — settings.typography.fontFamilies. Three system font stacks: System Sans (default), System Serif, System Mono. No web fonts are loaded.
• Font sizes — settings.typography.fontSizes. Five fluid sizes from Small to XX-Large.
• Spacing — settings.spacing.spacingSizes. Six steps from XS (0.5rem) to XXL (6rem), used throughout the patterns and templates via var:preset|spacing|*.
• Layout widths — settings.layout.contentSize (800px) and wideSize (1200px). Increase these if you want wider content on large monitors.

Block styles

Abira registers two additional block styles via register_block_style() in functions.php:

• Button → Outline — a transparent button with a border, filling in on hover/focus.
• Separator → Wavy — a wavy line, available in addition to core's default and dots styles.

Both are selectable from the block toolbar in the editor, and their CSS lives in assets/css/block-styles.css.

Accessibility

Abira is built with WCAG 2.2 AA as a baseline target:

• Semantic HTML5 throughout (<header>, <main>, <footer>, proper heading levels).
• A visible skip link at the top of every page.
• Visible focus outlines on all interactive elements (links, buttons), using the accent color.
• prefers-reduced-motion support — animations and smooth scrolling are disabled when the user has this preference set.
• A render_block filter (abira_fix_nav_list_structure() in functions.php) ensures <ul> elements inside navigation and page-list blocks only contain valid children, since WordPress core can otherwise output non-<li> elements directly inside a list.
• Verified with NVDA.

See accessibility.txt for the full statement.

Using Abira as a parent theme

Abira works as a parent for a child block theme:

your-child-theme/
├── style.css
└── theme.json

Minimal style.css header:

/*
Theme Name: Your Child Theme
Template:   abira
*/

Your child theme's theme.json is deep-merged with Abira's. Override only what you need — colors, a different layout width, additional patterns — and everything else falls through to Abira. You can also override any template or template part by placing a file with the same path in your child theme (e.g. templates/front-page.html).

Translation

All theme strings are wrapped for translation (__(), _x(), etc.) with the abira text domain. A Japanese translation (languages/ja.po / ja.mo) is included. To add a new language:

1. Use a tool like Poedit, Loco Translate, or wp i18n make-pot to extract the theme's strings, or start from a copy of languages/ja.po.
2. Name the files using the locale code only, e.g. de_DE.po / de_DE.mo.
3. Place them in languages/.

FAQ

Can I use Abira as a parent theme? Yes — see Using Abira as a parent theme.

How do I change the accent color? Go to Appearance > Editor > Styles > Colors and change the Accent color, or switch to one of the bundled style variations (Primary, Nordic, Dusty Rose).

Why doesn't my front page show anything? Make sure you've set a page under Settings > Reading > Homepage with the Front Page template assigned. Even with empty page content, the hero pattern and latest-posts grid will still render — if you see a completely blank page, double check the template assigned to that page in the editor (Page panel > Template).

Why is my card grid misaligned when some posts have no featured image? This shouldn't happen — abira/query-loop-card reserves a fixed 16:9 space for the image area regardless of whether a featured image exists. If you've built a custom card pattern, wrap your post-featured-image block in a container with a fixed aspect-ratio to get the same behavior.

Can I add more style variations? Yes. Copy any file in styles/ to a new file, give it a title and adjust the settings.color.palette colors, and it will appear in Appearance > Editor > Styles > Browse styles automatically.

License

Abira WordPress Theme, Copyright 2026 369work. Licensed under the GNU General Public License v3 or later. See readme.txt for full license text and image/asset credits.