7 · Theme & system pages

TL;DR

Objective — finish the “does this look like our product?” pass: apply brand colours (or defer to code), brand the 404/500/503 error pages, and prep a maintenance-mode page with a bypass token so the first outage isn’t your first time using it.

User part + done-when

👤 User part — set the brand colours in the panel if it exposes them (a visual choice from the brand profile), and eyeball the branded 404/503 in a browser; an agent publishes the error views and tests php artisan down/up.

Done when colours are applied in-panel (or deferred to Phase 8 and logged), a nonexistent URL renders the branded 404, and 503.blade.php is branded with the bypass token stored.  ·  ⏱ 20–40 min  ·  🔀 mixed (👤 colours, 🤖 error/maintenance pages).

Background

Three small, mostly-visual tasks that finish the “does this look like our product?” pass: theme colours, error pages, and maintenance mode. Colours are a SHOULD (often deferred to code in Phase 8); error pages and maintenance mode are LATER polish but cheap to do now while you’re already in the codebase.

SSH artisan uses $PHP_BIN

Publishing error views or toggling maintenance mode on staging runs artisan over SSH. Use the $PHP_BIN you resolved on page 3 — never bare php.

Steps

1. Apply app colours / theme

Check first (per the pattern from page 1): does the panel expose colours? If so, setting them is a panel action a person performs against the brand profile.

Who does this

👤 User sets primary/secondary/accent in Admin → Settings → Appearance from the brand profile and confirms the frontend reflects them — a visual panel choice an agent can’t make.

1. Set the colours or defer to code.

   • Admin → Settings → Appearance / Theme / Colors. If present, set primary, secondary, and accent to the values from your brand profile (_CUSTOMIZATIONS.md → ## Project Brand Profile). Save and confirm the frontend reflects them, not the vendor defaults.

   • If absent, colours live in CSS / tailwind.config.js. Don’t hand-edit them mid-deploy — defer to Phase 8 (code customization) and log it in the task ledger. Recolouring a Tailwind build is a code task with its own verify loop, not an admin-panel config.

   • ✅ Colours are applied in-panel and reflected on the frontend, or explicitly deferred to Phase 8 and logged.

Verify both modes

Verify in both light and dark mode if the vendor theme supports a toggle — a primary colour that passes contrast on white may fail on the dark surface.

2. Brand the error pages

These live in the codebase at resources/views/errors/, not the admin panel — so publishing and editing them is agent-runnable.

1. Inventory — check for 403, 404, 419, 429, 500, 503 blade files.

   • ✅ You know which error views exist and which are missing.

2. Brand existing views — confirm the styling matches your brand; swap in your logo and brand-voice copy where the vendor left demo text.

   • ✅ Existing error views carry your logo + brand voice (no vendor demo text).

3. Publish the customizable set if missing.

   php artisan vendor:publish --tag=laravel-errors
   # Expected: the error views are published to resources/views/errors/

   • ✅ The customizable error views exist after publishing.

4. Verify — visit a nonexistent URL and confirm a branded 404 renders, not the raw Laravel default.

   • ✅ A nonexistent URL renders the branded 404.

3. Prepare maintenance mode

Laravel’s built-in feature (php artisan down) — no admin panel involved. Prepare it now so the first real outage isn’t your first time using it.

1. Brand the 503 — customize resources/views/errors/503.blade.php (the maintenance template) to match your error-page set.

   • ✅ 503.blade.php matches the branded error-page set.

2. Test enable / disable with a bypass token.

   BYPASS=$(openssl rand -hex 16)   # generate once — never use a literal placeholder
   php artisan down --render="errors::503" --secret="$BYPASS"
   php artisan up
   # Expected: the site goes into maintenance, then back up

   • ✅ down/up both work; visiting /$BYPASS once sets a cookie that lets you browse the live site while others see the 503. Store the token in _CUSTOMIZATIONS.md (or your vault) — not in git.

LATER

Maintenance mode isn’t a launch blocker — it’s operational readiness. Branding the 503 now means it’s ready when you need it (deploys, incidents).

Checklist

Do not mark this step done until every box below is checked.

• 👤 Colours applied — brand colours applied in-panel, or explicitly deferred to Phase 8 and logged in the task ledger.
• 🤖 Error pages branded — at least 404 + 500 are branded; a nonexistent URL renders the branded 404.
• 🤖 Maintenance ready — 503.blade.php is branded; php artisan down --secret=… / up tested; bypass token stored in _CUSTOMIZATIONS.md.

→Next step

8 · Engagement & SEO