# 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](#requirements)
2. [Installation](#installation)
3. [Quick start](#quick-start)
4. [Theme structure](#theme-structure)
5. [Templates](#templates)
6. [Patterns](#patterns)
7. [Style variations](#style-variations)
8. [Customizing colors, fonts, and spacing](#customizing-colors-fonts-and-spacing)
9. [Block styles](#block-styles)
10. [Accessibility](#accessibility)
11. [Using Abira as a parent theme](#using-abira-as-a-parent-theme)
12. [Translation](#translation)
13. [FAQ](#faq)
14. [License](#license)

---

## Requirements

| | |
|---|---|
| WordPress | 6.5 or later |
| PHP | 7.4 or later |
| Tested up to | WordPress 7.0 |

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-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

| Template | File | Used for |
|---|---|---|
| Index | `index.html` | Fallback for any context with no more specific template |
| Front Page | `front-page.html` | The site's homepage, when set under Settings > Reading |
| Home | `home.html` | The posts page (blog list view) |
| Single | `single.html` | Individual blog posts |
| Page | `page.html` | Static pages |
| Page (No Title) | `page-no-title.html` | Static pages without a visible title (custom template, selectable per-page in the editor) |
| Archive | `archive.html` | Category, tag, author, and date archives |
| Search | `search.html` | Search results |
| 404 | `404.html` | Not found |
| Blank | `blank.html` | Header/footer only, no content area (custom template, for landing pages built entirely in the editor) |

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
<?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`.

| Variation | Description |
|---|---|
| Default | White, black, and Sage Green |
| Primary | Classic, deep colors |
| Nordic | Cool, fjord-inspired tones |
| Dusty Rose | Soft, warm rose accent |

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:

```css
/*
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, and a `languages/` folder is included
with a starter `.pot` file. To add a new language:

1. Use a tool like Poedit, Loco Translate, or `wp i18n` to generate a
   `.po`/`.mo` pair from `languages/abira.pot`.
2. Name the files using the locale code, e.g. `abira-ja.po` /
   `abira-ja.mo`.
3. Place them in `languages/`.

---

## FAQ

**Can I use Abira as a parent theme?**
Yes — see [Using Abira as a parent theme](#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.