Skip to content
Tutorials Center
My learning

Topics

Lesson 62 of 68 ยท Real-World Projects

Project: A Block Theme Portfolio

Build a portfolio block theme step by step: theme.json design tokens, templates and parts, a project card pattern, and a query loop over a projects post type.

In this project you will build a small portfolio site as a block theme. Visitors see a home page with a hero section and a grid of projects, an archive of all projects, and a page for each project. You will define the design once in theme.json, split the layout into templates and template parts, add a reusable pattern for a project card, and use the Query Loop block to list a custom post type called project.

Everything in the theme is a file, so you can keep it in Git and deploy it like any other code (see testing and deployment). The project ties together lessons you have already read: block theme basics, theme.json, templates and parts, patterns and custom post types.

Block themes need a real WordPress site, so the theme files below are read-only. Two runnable stand-ins at the end turn design tokens into CSS variables (and check contrast) and render the finished page structure from a block tree. They imitate the ideas; the real work is done by WordPress.

What you will build

TEXT
portfolio/
  style.css
  theme.json
  functions.php
  templates/
    index.html
    front-page.html
    archive-project.html
    single-project.html
  parts/
    header.html
    footer.html
  patterns/
    project-card.php
flowchart TD
    FP["front-page.html"] --> H["parts/header.html"]
    FP --> HERO["Hero group"]
    FP --> Q["Query Loop<br/>postType: project"]
    Q --> CARD["Post template:<br/>image, title, excerpt"]
    FP --> F["parts/footer.html"]
    TJ["theme.json<br/>colors, fonts, spacing"] -.styles.-> FP

The front page is assembled from two parts, a hero and a query loop. theme.json styles all of it.

Step 1: the theme header and the projects post type

A theme needs a style.css whose only required job is the header comment. All real styling comes from theme.json:

CSS
/*
Theme Name: Portfolio
Description: A small portfolio block theme.
Version: 1.0.0
Requires at least: 6.4
Requires PHP: 7.4
License: GPL-2.0-or-later
Text Domain: portfolio
*/

The project post type is registered in functions.php. For a real client site you would normally put a content type in a plugin, so the content survives a theme switch (see custom post types). For a personal portfolio, keeping it in the theme is acceptable and keeps the project self-contained.

PHP
<?php
add_action( 'init', function () {
    register_post_type( 'project', [
        'labels'       => [
            'name'          => __( 'Projects', 'portfolio' ),
            'singular_name' => __( 'Project', 'portfolio' ),
        ],
        'public'       => true,
        'has_archive'  => true,
        'show_in_rest' => true,           // Needed for the block editor and the Query Loop.
        'menu_icon'    => 'dashicons-portfolio',
        'supports'     => [ 'title', 'editor', 'excerpt', 'thumbnail' ],
        'rewrite'      => [ 'slug' => 'projects' ],
    ] );
} );

show_in_rest is the setting beginners forget: without it the type cannot use the block editor, and it will not show up in the Query Loop's post type choices. After adding a type with a custom slug, visit Settings, Permalinks and press save once so the rewrite rules refresh (see permalinks and rewrite rules).

Step 2: design tokens in theme.json

Design tokens are the named values of your design: colors, font families, sizes and spacing. Defining them once means the editor offers them as palette swatches and dropdowns, and every block uses the same set.

JSON
{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "layout": { "contentSize": "720px", "wideSize": "1100px" },
    "color": {
      "defaultPalette": false,
      "palette": [
        { "slug": "ink",    "name": "Ink",    "color": "#14213d" },
        { "slug": "paper",  "name": "Paper",  "color": "#fdfbf7" },
        { "slug": "accent", "name": "Accent", "color": "#b5390b" },
        { "slug": "muted",  "name": "Muted",  "color": "#5c6370" }
      ]
    },
    "typography": {
      "fluid": true,
      "fontFamilies": [
        { "slug": "serif", "name": "Serif", "fontFamily": "Georgia, 'Times New Roman', serif" },
        { "slug": "sans",  "name": "Sans",  "fontFamily": "system-ui, -apple-system, 'Segoe UI', sans-serif" }
      ],
      "fontSizes": [
        { "slug": "small",  "name": "Small",  "size": "0.875rem" },
        { "slug": "medium", "name": "Medium", "size": "1.125rem" },
        { "slug": "large",  "name": "Large",  "size": "2rem", "fluid": { "min": "1.5rem", "max": "2.25rem" } }
      ]
    },
    "spacing": {
      "spacingSizes": [
        { "slug": "30", "name": "Small",  "size": "1rem" },
        { "slug": "50", "name": "Medium", "size": "2rem" },
        { "slug": "70", "name": "Large",  "size": "4rem" }
      ]
    }
  },
  "styles": {
    "color": { "background": "var(--wp--preset--color--paper)", "text": "var(--wp--preset--color--ink)" },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--sans)",
      "fontSize": "var(--wp--preset--font-size--medium)",
      "lineHeight": "1.6"
    },
    "elements": {
      "link": { "color": { "text": "var(--wp--preset--color--accent)" } },
      "heading": { "typography": { "fontFamily": "var(--wp--preset--font-family--serif)" } }
    },
    "blocks": {
      "core/post-title": { "typography": { "fontWeight": "700" } }
    }
  },
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ]
}

WordPress turns each preset into a CSS custom property named --wp--preset--{type}--{slug}, so accent becomes --wp--preset--color--accent. Because colors are tokens, always check that your text and background pairs are readable. You will do that in the first stand-in below.

Step 3: template parts

Parts are reusable pieces. The header is a group with the site title and a navigation:

HTML
<!-- wp:group {"tagName":"header","layout":{"type":"constrained"},"style":{"spacing":{"padding":{"top":"var:preset|spacing|30","bottom":"var:preset|spacing|30"}}}} -->
<header class="wp-block-group" style="padding-top:var(--wp--preset--spacing--30);padding-bottom:var(--wp--preset--spacing--30)">
  <!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
  <div class="wp-block-group">
    <!-- wp:site-title {"level":0,"isLink":true} /-->
    <!-- wp:navigation {"overlayMenu":"mobile"} /-->
  </div>
  <!-- /wp:group -->
</header>
<!-- /wp:group -->

The footer, parts/footer.html, can be much simpler: a group with a paragraph such as the copyright notice. The comments are not decoration. They are the block markup WordPress parses, with the JSON describing each block's settings (see templates and parts).

Step 4: templates

Every template includes the header and footer with template-part blocks. The front page adds a hero and a query loop. Because the Query Loop here has "inherit":false, it runs its own query for the project type instead of using the page's main query:

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

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">

  <!-- wp:heading {"level":1,"fontSize":"large"} -->
  <h1 class="wp-block-heading has-large-font-size">Hello, I design and build for the web.</h1>
  <!-- /wp:heading -->

  <!-- wp:heading {"level":2} -->
  <h2 class="wp-block-heading">Selected projects</h2>
  <!-- /wp:heading -->

  <!-- wp:query {"queryId":1,"query":{"perPage":6,"postType":"project","order":"desc","orderBy":"date","inherit":false},"align":"wide"} -->
  <div class="wp-block-query alignwide">
    <!-- wp:post-template {"layout":{"type":"grid","columnCount":3}} -->
      <!-- wp:post-featured-image {"isLink":true,"aspectRatio":"4/3"} /-->
      <!-- wp:post-title {"level":3,"isLink":true} /-->
      <!-- wp:post-excerpt {"excerptLength":20} /-->
    <!-- /wp:post-template -->
    <!-- wp:query-no-results -->
      <!-- wp:paragraph --><p>No projects yet.</p><!-- /wp:paragraph -->
    <!-- /wp:query-no-results -->
  </div>
  <!-- /wp:query -->

</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

The other templates follow the block theme template hierarchy:

  • templates/archive-project.html is picked for the /projects/ archive (it exists because has_archive is true). It uses a Query Loop with "inherit":true, which means "show whatever the main query found", so pagination and the archive URL work with no extra code.
  • templates/single-project.html is picked for one project. It shows the title, featured image and the wp:post-content block, and could add wp:post-navigation-link blocks for previous and next project.
  • templates/index.html is the required fallback and handles posts, pages and anything else with a plain loop.

The hierarchy file names are plain: single-{post_type}.html and archive-{post_type}.html. If a more specific file does not exist, WordPress falls back to single.html, archive.html and finally index.html.

Step 5: a project card pattern

Patterns are blocks you can insert from the editor. Any PHP file in patterns/ with a header comment is registered automatically. This one lets the site owner drop a three-project showcase anywhere, such as the "About" page:

PHP
<?php
/**
 * Title: Featured projects
 * Slug: portfolio/featured-projects
 * Description: A heading and a three-column grid of the latest projects.
 * Categories: featured
 * Keywords: portfolio, projects, grid
 */
?>
<!-- wp:group {"align":"wide","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignwide">
  <!-- wp:heading {"level":2} -->
  <h2 class="wp-block-heading"><?php echo esc_html_x( 'Featured projects', 'Pattern heading', 'portfolio' ); ?></h2>
  <!-- /wp:heading -->
  <!-- wp:query {"queryId":2,"query":{"perPage":3,"postType":"project","inherit":false}} -->
  <div class="wp-block-query">
    <!-- wp:post-template {"layout":{"type":"grid","columnCount":3}} -->
      <!-- wp:post-featured-image {"isLink":true,"aspectRatio":"4/3"} /-->
      <!-- wp:post-title {"level":3,"isLink":true} /-->
    <!-- /wp:post-template -->
  </div>
  <!-- /wp:query -->
</div>
<!-- /wp:group -->

Because it is a PHP file, strings can be translated with esc_html_x() and friends, which is a real advantage over plain HTML templates.

Step 6: add content and test

  1. Zip the folder (or copy it into wp-content/themes/) and activate Portfolio.
  2. Under Projects, Add New, create three projects with a title, excerpt and featured image.
  3. Open Appearance, Editor to see the templates and parts. Change a color in Styles and watch it update everywhere.
  4. Visit /projects/ and a single project. Resize the window to check the grid collapses on narrow screens.
  5. Run a quick accessibility pass: heading order, color contrast, link text, keyboard navigation.

A design-token generator you can run

This stand-in reads a palette like the one in theme.json, prints the CSS custom properties WordPress would create, and computes WCAG contrast ratios for text and background pairs. The formula is the standard relative-luminance one; a ratio of at least 4.5 is the usual target for normal-size text.

PHP Tokens to CSS variables, with contrast checks (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The pair of accent on ink is the kind of mistake the check catches: both colors look fine alone, but the combination is hard to read. Fix such pairs in theme.json before building templates on top of them.

A page renderer you can run

The second stand-in shows the page structure of the finished front page. A template is a tree of blocks; template parts are looked up by name; the query block loops over projects. The renderer is deliberately tiny, and real WordPress does much more (block supports, styles, escaping through the block API), but you can see how a tree becomes HTML.

PHP Render the front page block tree (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Change perPage to 0 and run it again: the "no results" branch appears, just like the query-no-results block in the real template.

Ideas to extend it

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which post type setting must be true for a custom type to work in the block editor and the Query Loop block?

    The block editor loads and saves content through the REST API, so a post type must have show_in_rest enabled.
  2. 2. What does "inherit":false mean on a Query Loop block?

    With inherit false you choose the post type, count and order yourself. With inherit true the block uses whatever the main query found, which is what archives need.
  3. 3. Which file does a block theme use for the archive of a custom post type named project?

    The template hierarchy uses archive-{post_type}.html first, then falls back to archive.html and index.html.
  4. 4. What CSS custom property does a color preset with the slug accent become?

    theme.json presets follow the pattern --wp--preset--{type}--{slug}.

Summary

  • A block theme is files: style.css header, theme.json, templates/, parts/ and patterns/.
  • theme.json holds the design tokens; WordPress exposes them as --wp--preset--* CSS variables and editor controls.
  • Templates are block markup; template-part blocks pull in the header and footer.
  • Use single-{post_type}.html and archive-{post_type}.html; give the post type show_in_rest and has_archive.
  • The Query Loop lists any post type: inherit:false for your own query, inherit:true for archives.
  • PHP patterns can be translated and are registered automatically from the patterns folder.
  • The runnable code is a plain-PHP stand-in, not real WordPress.

Next: Project: An Events Plugin