Matter

A custom Drupal 11 base theme built around atomic design principles and a modern PostCSS workflow.

Overview

Matter is a component-based Drupal base theme built on atomic design principles by Brad Frost — atoms, molecules, and organisms — for a consistent and maintainable design system. Styles are written in plain, modern CSS using native features exclusively — no preprocessors (Sass, Stylus) or utility frameworks (Bootstrap, Tailwind).

Requirements

Drupal

• Drupal 11 - Drupal core 11 or higher
• Components - Drupal module: maps source components to Twig templates
• UI Icons - Drupal module: integrates icon libraries
• UI Patterns - Drupal module: provides reusable UI patterns
• UI Skins - Drupal module: allows for themeable UI skins
• UI Styles - Drupal module: manages global UI styles

Development

• Apache - Apache 2.4 or higher for local development server
• PHP - PHP 8.0 or higher for Drupal and Composer (PHP 8.4 recommended)
• Composer - Composer 2 or higher for managing Drupal dependencies
• Node.js - Node.js 14 or higher for asset compilation
• Gulp - Gulp 4 for automating asset pipeline tasks
• PostCSS - PostCSS 8 for processing CSS with plugins (import resolution, polyfills, minification)

Structure

• assets/ — Browser-ready files served to the front end
• components/ — Drupal SDC definitions that map source components to Twig
• source/ — Authored source — CSS, JS, and Twig templates

matter/
├── assets/
│   ├── css/                 # Compiled and minified theme stylesheet
│   ├── js/                  # Compiled and minified theme scripts
│   └── images/              # Theme images and icon libraries
├── components/
│   ├── 01-atoms/            # SDC wiring for atom-level components
│   ├── 02-molecules/        # SDC wiring for molecule-level components
│   └── 03-organisms/        # SDC wiring for organism-level components
└── source/
    ├── 00-nucleus/          # Design tokens, custom properties, typography, and reset styles
    ├── 01-atoms/            # Foundational UI elements: buttons, inputs, images
    ├── 02-molecules/        # Composite patterns assembled from atoms
    ├── 03-organisms/        # Self-contained page sections built from molecules
    ├── 04-symbiosis/        # Cross-component utilities and shared relationships
    └── 05-synergy/          # Full layout compositions and page-level templates

Asset Pipeline

Styles and scripts are compiled with Gulp and PostCSS.

Install dependencies:

npm install

Watch for changes during development:

npx gulp

The styles pipeline processes source/matter.source.css through PostCSS (import resolution, container query polyfill, Lightning CSS minification) and outputs assets/css/matter.theme.css.

The scripts pipeline processes source/matter.source.js through UglifyJS (minification with top-level mangling) and outputs assets/js/matter.theme.js.

Regions

Key	Label	Description
branding	Branding	Site logo, name, and slogan
navigation	Navigation	Primary site navigation menus
focus	Focus	Navigation region for focused items
hero	Hero	Full-width introductory or promotional content
highlight	Highlight	Prominent callout content above the main area
content	Content	Main page content
sidebar	Sidebar	Supplementary content alongside the main area
footer	Footer	Site-wide footer content and secondary navigation
buffer	Buffer	Hidden region for parking blocks that must remain enabled but not render visibly

Icons

Font Awesome Free by Fonticons, Inc. is included as a dependency and available throughout the theme. Icons are licensed under CC BY 4.0, fonts under SIL OFL 1.1, and code under MIT.

Typography

Three members of the Roboto family are used throughout the theme, all designed by Christian Robertson and licensed under the Apache License 2.0.

Typeface	Role
Roboto	Primary sans-serif for body and UI text
Roboto Mono	Monospace for code and technical content
Roboto Slab	Serif for headings and editorial content