JustFlows

Theme development

Build a block-first theme

A Justflows theme is a portable design system: CSS, tokens, block templates, reusable template parts, patterns, and optional demo layouts. Public pages use the core renderer—there are no executable PHP or EJS theme templates.

Theme anatomy

Project structure
acme-theme/
├── justflows.json
├── justflows-theme.json
├── styles/global.css
├── templates/
│   ├── index.json
│   ├── front-page.json
│   └── single.json
├── parts/
│   ├── header.json
│   └── footer.json
├── patterns/
└── demo/

Styles

styles/global.css, components.css, and blocks.css are concatenated into /theme.css.

Templates

templates/*.json define page structure with the same block-document shape used by the visual builder.

Template parts

parts/header.json and parts/footer.json provide reusable site chrome.

Patterns & demo

patterns/*.json are insertable designs; demo/ provides initial home, blog, header, and footer layouts.

Runtime metadata

justflows-theme.json
{
  "id": "acme.studio",
  "name": "Studio",
  "version": "1.0.0",
  "license": "GPL-2.0-or-later",
  "engines": { "justflows": ">=0.1.8 <0.2.0" },
  "styles": ["styles/global.css"],
  "templates": {
    "index": "./templates/index.json",
    "front-page": "./templates/front-page.json"
  },
  "parts": {
    "header": "./parts/header.json",
    "footer": "./parts/footer.json"
  },
  "supports": { "blockEditor": true, "patterns": true }
}

Template hierarchy

The host chooses the most specific available JSON template and falls back to index.json. A theme may provide these slots:

text
front-page → home → single-{type}-{slug} → single-{type}
→ single → page-{slug} → page → singular
→ archive-{type} → archive → search → 404 → index

Every template is a block document. Context blocks such as core.post-title and core.post-content resolve against the current request, while the content row’s own blocks fill the page body.

Patterns

patterns/landing.json
{
  "id": "landing",
  "title": "Landing page",
  "description": "Hero, proof, and call to action",
  "category": "marketing",
  "requiresBlockTypes": ["acme.forms.form"],
  "blocks": []
}

Use requiresBlockTypes whenever a pattern depends on plugin blocks. The builder then shows an installation notice instead of importing a broken design.

Design tokens and cascade

Expose documented custom properties for colors, spacing, type, widths, radii, and shadows. This allows the Customizer and third-party plugins to inherit the active visual language.

  1. Theme CSS
  2. Customizer tokens and platform animation CSS
  3. Active plugin styles
  4. Site owner’s Additional CSS

Package and test

Validate every JSON document, confirm the fallback templates/index.json exists, test missing optional plugins, preview responsive layouts, and verify both light and dark modes before creating the archive.

Package from the theme directory
COPYFILE_DISABLE=1 tar -czf ../../acme-studio.jfpkg \
  justflows.json justflows-theme.json styles templates parts patterns demo