7 · Theme & system pages

TL;DR

Objective — finish the “does this look like our product?” pass: apply brand colours or capture the Phase 8 code task, 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.

Steps at a glance:

1. Apply app colours / theme — Check first (per the pattern from page 1): does the panel expose colours? If so, the human approves the palette and the agent can drive non-secret panel fields when browser automation is available.
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.
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.

User part + done-when

🔀 User part — the human approves visual choices from the brand profile. The agent sets non-secret panel colour fields when browser automation is available, snapshots the branded 404/503, publishes the error views, and tests php artisan down/up.

Done when colours are applied in-panel (or captured in Zaj-BACKLOG.md for Phase 8 with owner, trigger, and acceptance criterion), 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; if they require code, capture the Phase 8 owner/trigger/acceptance in Zaj-BACKLOG.md. Error pages and maintenance mode are operational-readiness polish, but they are cheap to do now while you’re already in the codebase.

SSH artisan uses $PHP_BIN

Publishing error views or toggling maintenance mode on the selected non-production environment 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, the human approves the brand values and the agent can set the panel fields from the brand profile.

Who does this

🔀 User + Agent — 👤 User approves the visual choice. 🤖 Agent sets primary/secondary/accent in Admin → Settings → Appearance from the brand profile and verifies the frontend reflects them when browser automation is available.

1. Set the colours or capture the code task.

   • Admin → Settings → Appearance / Theme / Colors. If present, set primary, secondary, and accent to the values from your brand profile (Zaj-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; capture the Phase 8 code customization in Zaj-BACKLOG.md with owner, trigger, and acceptance criterion. 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 captured in Zaj-BACKLOG.md for Phase 8 with owner, trigger, and acceptance criterion.

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 Zaj-CUSTOMIZATIONS.md (or your vault) — not in git.

Operational readiness

Maintenance mode is not a launch blocker, but it is still part of this page’s in-phase readiness check. Branding the 503 now means it is 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 captured in Zaj-BACKLOG.md for Phase 8 with owner, trigger, and acceptance criterion.
• 🤖 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 Zaj-CUSTOMIZATIONS.md.

→Next step

8 · Engagement & SEO