Develop a child theme

Prepare a local development community#

Use a disposable local database, synthetic accounts and private uploads. Install dependencies and build assets. Never develop against the production database or commit .env and generated accounts.

Scaffold your theme#

php artisan forum:make-theme sunrise

The command creates themes/sunrise/theme.json, assets/custom.css and an empty views/. IDs start with a lowercase letter, use lowercase letters/digits/single hyphens and are at most 32 characters. Existing directories are not overwritten.

Customize light and dark tokens#

Edit assets/custom.css. Parent assets load before child assets. Tokens include --bg, --surface, --text, --muted, --line, --accent, --accent-hover, --button-text, --tint and --radius.

:root { --accent: #5c3fc4; --accent-hover: #4930a5; --button-text: #fff; }
:root[data-mode=dark] { --accent: #b5a0ff; --accent-hover: #cbbcff; --button-text: #171326; }

Check text contrast in both states. Activate with php artisan forum:theme sunrise. Confirm the declared stylesheet loads through /theme-assets/sunrise/custom.css. Only flat declared CSS/JS files are part of that endpoint; images/fonts need separately managed public assets.

Override only what you need#

Copy one current view from themes/default/views/ into the child views/ directory, retaining the filename. Declare its current revision from config/theme_views.php in view_revisions in theme.json. Uncopied views inherit from the active parent/default chain.

Preserve authorized payloads, hooks, named fields, CSRF, validation messages, required acceptance/CAPTCHA, attachment routes and accessible no-JavaScript forms. Escape user text with Blade's escaped output. Never load unrestricted relationships or compute global counts inside templates. Administration views are core views, outside the public theme contract.

Test and package#

Check real screens and the showcase in both appearances, at desktop/mobile widths, by keyboard and with guest/member/staff roles. Test validation, empty, locked and access-denied states. Recover with php artisan forum:theme default if a view breaks. Package only your theme directory, document supported versions and review warnings on each core upgrade.

Use the complete tutorial and view/payload reference for exact contracts.