STAIR Theme

A custom WordPress theme for the STAIR student association at HSLU.

Original version by jackra1n and Toemmsen96

Features

• Dark Mode - System preference detection with manual toggle, persisted in localStorage
• Events Integration - Displays upcoming events via The Events Calendar plugin
• Contact Forms - Integration with Contact Form 7
• Responsive Design - Mobile-first approach with Tailwind CSS
• Auto Setup - Automatically creates required pages and navigation menu on theme activation

Tech Stack

• Tailwind CSS v4 - Utility-first CSS framework
• Lucide Icons - Icon library (loaded via CDN)
• TGM Plugin Activation - Manages required plugin dependencies
• Bun - JavaScript runtime and package manager

Requirements

• WordPress 6.8+
• PHP 8.0+
• Bun or Node.js
• Composer

Required Plugins

The theme will prompt you to install these plugins on activation:

• The Events Calendar — Event management
• Contact Form 7 — Contact forms
• Advanced Custom Fields — Custom fields
• FluentSMTP — SMTP email delivery

Installation

Development Setup

First, create a shared directory into which this repo and stairch/website-docker will be cloned

# Clone the repository
git clone https://github.com/stairch/website-theme.git
cd website-theme

# Install all dependencies (bun + composer)
bun run setup

# Build CSS
bun run build

# Or watch for changes during development
bun run dev

Production

To deploy a new version of the theme, you need to create a tag following Semantic Versioning (e.g. v1.1.0). After that the production deployment workflow starts and automatically deploys it to the production server. Finally, activate the theme in WordPress Admin → Appearance → Themes.

If you somehow need to deploy manually (e.g. fallback to an older version), follow these steps:

1. Copy .env.example to .env and change the values of the variables respectively. Make sure REMOTE_PATH is set to ~/public_html/wp-content/themes/stair-theme-<VERSION>

2. Run bun run setup and bun run build to generate the compiled CSS

3. Run the deploy.sh script

4. Activate the theme in WordPress Admin → Appearance → Themes

5. Install the required plugins when prompted

Available Scripts

Command	Description
bun run setup	Install bun and Composer dependencies
bun run build	Build production CSS
bun run dev	Watch mode — rebuilds CSS on file changes
bun run build:css	Build CSS only
bun run watch:css	Watch CSS only

Code Quality

Linting & Formatting

Command	Description
bun run lint	Check PHP and Wordpress security and compatibility issues (phpcs)
bun run format	Shows PHP code style issues (php-cs-fixer dry-run)
bun run format:fix	Fix PHP code style issues (php-cs-fixer)

PHP linting uses PHP_CodeSniffer configured in phpcs.xml.
PHP formatting uses PHP CS Fixer configured in .php-cs-fixer.dist.php.

CI

Every push and pull request to main runs the check workflow, which verifies lint and format. The deploy workflow additionally requires both checks to pass before deploying.

Development Notes

Adding New Required Plugins

Edit inc/tgm-config.php and add to the $plugins array:

array(
    'name'     => 'Plugin Name',
    'slug'     => 'plugin-slug',
    'required' => true,  // or false for recommended
),

Tailwind Configuration

Tailwind v4 configuration is in input.css using the new CSS-based config:

• Custom colors defined in @theme block
• Dark mode variant: @custom-variant dark (&:where(.dark, .dark *))