Themes

Theme scaffold is an example of a Drupal theme.

We recommend creating a custom your_site_theme theme for your project to place custom styling and front-end functionality specific to your site.

The theme uses the site machine name convention (your_site_theme in this case), while modules use the abbreviated prefix (ys_ for your_site).

info

We understand that front-end theming is often highly project-specific and subject to team preferences. The provided your_site_theme scaffold is not intended to dictate how your theme should be built - it demonstrates how custom themes can integrate with the Vortex tooling and automations.

Feel free to adapt or replace it with your preferred theme.

Build system

The theme includes a complete Node.js-based build system composed of npm scripts over Sass, PostCSS with Autoprefixer, Terser and chokidar:

• SCSS compilation
• JavaScript concatenation and minification
• CSS auto-prefixing for browser compatibility
• Linting for both CSS (Stylelint) and JavaScript (ESLint)
• Watch mode for development

Build commands

cd web/themes/custom/your_site_theme

# Install dependencies
npm ci

# Build production assets
npm run build

# Build development assets (unminified)
npm run build-dev

# Run linting
npm run lint

# Auto-fix linting issues
npm run lint-fix

# Watch for changes during development
npm run watch

Ahoy commands are configured to call the appropriate npm scripts from the theme directory:

# Install front-end dependencies
ahoy fei

# Build production assets
ahoy fe

# Build development assets (unminified)
ahoy fed

# Watch for changes during development
ahoy few

# Lint front-end code
ahoy lint-fe

# Fix front-end lint issues
ahoy lint-fe-fix

These commands run within the container to use the Node.js environment and tools installed there, ensuring consistency across development environments.

tip

When adding your own theme with a custom build system, it's a good idea to follow the same command structure and naming conventions. This keeps things consistent across projects and makes it easier for other developers to work with the build system without learning a new process.

File structure

The main directories and files (build outputs, lint configuration files, and static assets are trimmed for brevity):

your_site_theme/
├── components/                    # Single Directory Components (SDC)
│   └── button/                    # Sample button component
│       ├── button.component.yml   # Component schema (props and slots)
│       ├── button.twig            # Component template
│       └── button.css             # Component styles
├── scss/                          # Sass source files
│   ├── _variables.scss            # Theme variables
│   ├── _mixins.scss               # Sass mixins
│   ├── _fonts.scss                # Font definitions
│   ├── _rem.scss                  # REM unit utilities
│   ├── styles.scss                # Main stylesheet
│   └── components/                # Component-specific styles
│       └── _header.scss           # Header component styles
├── js/                            # JavaScript source files
│   └── your_site_theme.js         # Main theme JavaScript
├── templates/                     # Twig template overrides
│   └── layout/
│       └── region--footer-bottom.html.twig  # Renders the button component
├── tests/                         # Theme tests
│   └── src/
│       ├── Unit/                  # Unit tests
│       ├── Kernel/                # Kernel tests
│       └── Functional/            # Functional tests
├── your_site_theme.info.yml       # Theme definition
├── your_site_theme.libraries.yml  # Asset libraries
├── your_site_theme.theme          # Theme functions
├── package.json                   # Node.js dependencies
└── logo.svg                       # Theme logo

Libraries

The theme defines asset libraries in your_site_theme.libraries.yml for organized CSS and JavaScript loading with proper dependencies and browser compatibility.

Single Directory Components

The theme ships a sample Single Directory Component (SDC) in components/button and uses it from templates/layout/region--footer-bottom.html.twig to render a "back to top" link, demonstrating real component usage from a template.

Components are validated with SDC Devel:

ahoy lint-sdc

➡️ See SDC Devel for how the validator is set up and where it runs.

Tests scaffold

The tests directory contains working examples of tests that can be used as a starting point in your project.

It also has a set of helper Traits that you may find useful when writing your tests. Remove them if you do not need them.