Verbolus brand and navigation rollout¶
Status: implementation brief
Date: 2026-08-16
Audience: product-design, frontend implementation, testing, and code-review agents
Lifecycle: implementation brief and rollout record. The platform roadmap owns current delivery status.
Purpose¶
This document is the implementation-ready direction for adopting the approved Verbolus assets and making navigation feel like one product across the landing page, gameplay, Groups, player pages, and public content pages. It also records how the same identity should appear later in the PWA, push notifications, email signatures, Store listings, Patreon, WhatsApp Business, and similar external channels.
The desired result is recognizably Verbolus without turning the interface into a marketing site. The puzzle remains the quietest screen. Brand and navigation should add orientation and trust, not consume the space needed to play.
This brief complements:
frontend/minigames/brand/README.mdfor the asset inventory and identity vocabulary;- Engagement platform plan for PWA, notification, account, social, and monetization policy;
- Advertising strategy for placement and trust constraints;
- Platform roadmap for phase ownership and delivery status.
When these documents overlap, this document owns the visual/navigation rollout, the engagement plan owns notification and PWA product behavior, and the roadmap owns sequencing of numbered product phases.
Agent operating instructions¶
Do not implement this entire document as one undifferentiated change. Use the pull-request sequence near the end. Each PR must leave the app coherent and deployable.
Before editing:
- Read
AGENTS.mdand the applicable files in.github/instructions/. - Read the four related documents listed above.
- Inspect the current route and its nearest shared component before changing it.
- Preserve unrelated work on
feat/prep-adsenseand do not regenerate approved artwork merely to achieve a different visual style. - Treat light theme, dark theme, narrow mobile, desktop, 200% zoom, and installed-PWA safe areas as first-class states.
The coding agent should make the smallest reusable component set that expresses the decisions below. The design agent should review layout, scale, contrast, and crop behavior. The testing agent should verify behavior and accessibility, not merely take screenshots. The review agent should reject duplicated navigation, misleading placeholders, inaccessible icon links, or a second visual identity invented alongside these assets.
Locked product decisions¶
- The Verbolus mark is the V and three colored tiles. It represents the whole product.
- Letter Golf and Reverse Cross artwork identifies an individual game. It must not replace the Verbolus mark in site chrome, metadata, notifications, or company profiles.
- In application UI, pair the transparent mark with live HTML text reading
Verbolus. Do not use an image containing the wordmark when live text is practical. - Use the fixed navy app icon in contexts that crop unpredictably or need a self-contained square image: installed-app icons, profile pictures, favicons, and notification icons.
- Do not use
public/logo.pngfor new work. Keep it until the rollout is verified and a separate cleanup confirms it has no consumers. - Do not add a large site-wide masthead, a sticky promotional header, or a second navigation row over active gameplay.
- A home link and a contextual back link solve different problems. The home link is deterministic; a back link returns to the player's previous task. Where both are useful, keep both.
- The hamburger remains the full site directory. Its trigger must have an accessible name, and its opened surface begins with the branded home link.
- The site remains usable without an account, installation, notification permission, ads, or external membership.
- No navigation or branding element may resemble an advertisement or be placed inside an ad slot.
Current state to preserve or improve¶
Recent commit c645275 correctly addressed a real problem: About, Contact, Privacy, and How to Play
had no in-app route home, while Updates combined home and section identity into one link. It added
PageNav and separated the Updates links. Keep that intent, but evolve it into shared site chrome
rather than accumulating unrelated text-link treatments.
Current inconsistencies that this rollout should resolve:
- The landing page shows a greeting and hamburger but no visible Verbolus identity.
- Public content pages use a small text-only
Verboluslink and no full menu. - Updates has its own blue banner navigation treatment.
- Scorecard, Settings, and Groups use
BackLink; some also use the genericHeader, which embeds the hamburger. - Gameplay uses the same generic
Header, but its three-column constraints are materially different from a content or account page. - The open hamburger renders
Verbolusas plain text rather than as the branded home identity. - Privacy is reachable from content but is not currently in the central
linkscollection/menu. - The approved favicon, Apple icon, and PWA icons exist but are not wired into application metadata.
Do not erase useful route-specific character. The Updates section may still have a distinct masthead, and game screens should remain compact. Consistency comes from shared identity, spacing, interaction, and information architecture—not from making every route use an identical box.
Identity asset map¶
In-product UI¶
| Context | Asset | Treatment |
|---|---|---|
| Light surface | /brand/verbolus-mark-on-light.svg |
Transparent mark next to live Verbolus text |
| Dark surface | /brand/verbolus-mark-on-dark.svg |
Transparent mark next to live Verbolus text |
| Forced-color or single-color fallback | verbolus-mark-monochrome-*.svg |
Use only after testing the actual context |
| Tiny raster proof | /brand/ui/mark-on-*-24.png, 32.png, 48.png |
QA/reference or clients that cannot use SVG; not the default web-header source |
Use the on-light art when the actual rendered surface is light and on-dark when it is dark.
This must follow the app's selected theme class, not only the operating-system media query, because
the player can override the system theme.
Browser, installed app, and external profile¶
| Context | Asset |
|---|---|
| Browser favicon | /brand/icons/favicon.ico |
| Apple Home Screen | /brand/icons/apple-touch-icon-180.png |
| Standard PWA icons | /brand/icons/pwa-icon-192.png and pwa-icon-512.png |
| Maskable PWA icons | /brand/icons/pwa-maskable-192.png and pwa-maskable-512.png |
| Large square profile/master | /brand/icons/app-icon-1024.png |
| Vector app-icon master | /brand/verbolus-app-icon.svg |
Maskable images and ordinary images must remain separate manifest entries with their correct
purposes. Do not label the standard image any maskable; the maskable export intentionally has a
different safe area.
Marketing and Store¶
Assets in frontend/minigames/brand/store/ and brand/windows/ are submission/marketing exports,
not runtime web assets. Source SVGs live in brand/source/. Store screenshots are still missing on
purpose and must be captured from a finished, production-like PWA later.
Component model¶
Use four concepts. Names may vary if neighboring code makes another name clearer, but keep the responsibilities separate.
1. BrandMark¶
A small, theme-aware, non-interactive visual component.
- Default UI size: 28–32 CSS pixels high. Preserve its intrinsic aspect ratio.
- Render the light-surface and dark-surface SVG variants according to the active theme class.
- Avoid JavaScript theme resolution solely to choose an image; it can cause hydration flicker. A CSS-driven pair of tiny SVG images is acceptable if the hidden copy is also hidden from assistive technology.
- Accept a narrow
className/size override only if a real caller needs it. - Do not embed a home link or accessible name into this primitive.
- When paired with text, the image is decorative:
alt=""and/oraria-hidden="true".
2. BrandHomeLink¶
The canonical in-app Verbolus identity and home affordance.
- Render
BrandMarkplus live textVerbolusin one Next.jsLinkto/. - The text supplies the accessible name; do not make a screen reader announce both the SVG title
and
Verbolus. - Use a semibold or bold treatment consistent with the current Geist font. Do not reproduce the Segoe wordmark from the lockup SVG in normal application chrome.
- Minimum interactive height: 44 CSS pixels, even if the visible mark is smaller.
- Normal state should feel like identity, not a blue inline hyperlink. Use a restrained opacity or color change on hover plus a clear keyboard focus ring.
- Accessible name may simply be
Verbolus; an icon-only variant, if ever required, must be namedVerbolus home.
3. SiteHeader¶
The browsing/account/content shell for every non-game surface.
- Left:
BrandHomeLink. - Right:
HeaderMenutrigger. - One row, approximately 56–64 CSS pixels high, with a quiet bottom border if separation is needed.
- Not sticky in the first rollout. A sticky header costs valuable mobile space and has not yet demonstrated a need.
- Align to the page's content width: the landing/account/group shell is narrow (currently 600px);
editorial pages are wider (currently
max-w-4xl). Reuse a small number of deliberate container widths rather than hard-coding a unique width per route. - Account for
env(safe-area-inset-top)and horizontal safe areas when the PWA runs standalone, without adding visible padding in an ordinary browser. - Do not put ads, announcements, install prompts, unread lists, or account prompts in this row.
4. GameHeader and page headings¶
The existing Header currently mixes two jobs: an action-heavy three-column game header and a
generic page title. Separate those concepts instead of making SiteHeader imitate the game grid.
GameHeaderretains the current three-column behavior: game name on the left, timer/streak/mode content centered, How to Play/owner actions and hamburger on the right.- Keep the fixed-size How to Play action introduced by
330fb87; do not restore variable-width text that overlaps the center column on narrow phones. - Do not add the
Verboluswordmark to the visible game row. The branded home link is at the top of the opened menu. This protects the board from another persistent label. - If renaming
Headerwould create noisy churn, introduce the new semantic component and migrate callers in a focused change. Do not leave two vaguely named headers indefinitely. - Non-game page titles/actions should be ordinary semantic page-heading rows below
SiteHeader. They do not own another hamburger.
Navigation information architecture¶
Closed state¶
On non-game pages, players see a visible Verbolus home identity at top left and the hamburger at top right. On game pages, they see the game-specific compact header and hamburger. This is an intentional difference based on task mode.
Open state¶
Both the mobile sheet and desktop dropdown use the same ordered information architecture:
- Branded
BrandHomeLinkin the menu header. Activating it closes the menu and navigates home. - Play: Letter Golf and Reverse Cross.
- Player: My scorecard, Groups, Settings.
- Verbolus: Updates, About, Contact, Privacy.
- Feature-flagged internal/debug tools, separated and labeled so they cannot be mistaken for player navigation.
Do not add disabled placeholders for Inbox, accounts, tournaments, Patreon, notifications, or other future features. Insert them into the appropriate group when the destination and behavior exist. The eventual Inbox belongs at the beginning of Player and can show an unread count in text.
Implementation details:
- Replace
links.filter(link.image)as the long-term grouping mechanism. An image's presence is a presentation detail, not information architecture. Give links an explicit group/kind or define small typed arrays for game, player, and company destinations. - Include Privacy in central navigation even though it also appears in the footer.
- Give both menu triggers
aria-label="Open navigation menu"(or equivalent). Mark the hamburger SVG decorative. - Preserve Radix focus trapping, Escape behavior, focus return, and menu-close-on-navigation.
- The mobile sheet must scroll if viewport height is small. Keep controls at least 44px tall.
- Do not use color alone for active/current state. If active-route treatment is added, also use
aria-current="page". - Do not add a dedicated bell now. The engagement plan intentionally puts the future Inbox in the menu until usage justifies permanent header space.
Route-by-route UI direction¶
Landing page /¶
Target structure:
[ Verbolus mark + Verbolus ] [ menu ]
Good evening, Justin
New for Aug …
[ Reverse Cross card ]
[ Letter Golf card ]
[ compact public-site footer ]
- Replace the greeting/hamburger row with
SiteHeaderfollowed by a separate greeting. - The mark is present but modest; the individual game illustrations remain the visual focus.
- Keep the update teaser quiet and subordinate to play.
- Do not use the horizontal or stacked marketing lockup here. The mark plus live text is cleaner, sharper, localizable, and consistent with every other page.
- Keep mobile width fluid. Revisit the current
w-[50%] min-w-[380px]because 380px minimum plus padding can create horizontal pressure on 320–375px devices. Preferw-fullwith a narrowmax-w-*container and responsive padding. - Add the public-site footer after game cards without forcing it to the bottom of a fixed
h-screen; the page must scroll naturally at zoom and on short screens.
Active game routes¶
- Preserve the full-screen game layout and current
GameHeaderdensity. - Do not add
SiteHeader, footer, promotional lockup, install prompt, or company navigation around the board. - Brand the opened hamburger header using
BrandHomeLink. - Continue to expose the game-specific How to Play icon outside the menu.
- Test the longest current game name, timer/streak center content, How to Play, and hamburger at 320px, 360px, and 390px widths. Nothing may overlap or reduce the game board below usability.
- In standalone PWA mode, apply safe-area padding to the game header without changing the board's scoring/layout calculations unexpectedly.
How to Play pages¶
- Add
SiteHeaderat the top. - Replace the current
PageNavhome crumb with a contextualBackLinkor deterministic link labeledBack to Letter Golf/Back to Reverse Crossbeneath the site header. - Keep one
h1, instructional content, and ad placement rules unchanged. - A content-page ad remains outside navigation and outside the worked example. Branding must not visually imply that third-party creative is a Verbolus recommendation.
- Add
SiteFooterat the end.
About, Contact, and Privacy¶
- Add
SiteHeader; remove the now-redundant text-onlyPageNavhome link. - Keep page title and content inside the existing editorial-width container.
- Add
SiteFooter. - About and Privacy remain ad-free. Contact remains ad-free unless the advertising strategy is explicitly revised.
- Use
support@verbolus.comas the publicly surfaced support address unless product copy is changed in a separate reviewed task. Do not accidentally reintroduce personal addresses. - Do not describe Verbolus as an LLC, corporation, or other legal entity that does not exist.
Updates index and articles¶
- Put
SiteHeaderabove the Updates section. - Refactor
UpdatesBannerinto a section masthead/breadcrumb rather than a second version of global home navigation. It can retain the blue editorial treatment, but should sayUpdatesand optional article crumb without repeating a second Verbolus home link immediately below the real one. - Preserve article previous/next navigation and the
substantialrule for content ads. - Add
SiteFooterafter the index/article content. - On small screens, article titles and breadcrumbs wrap or truncate intentionally; they must not widen the viewport.
Scorecard /me and Settings /settings¶
- Add the narrow
SiteHeader. - Keep the contextual history-aware
BackLink; it serves a different purpose from the home link and lets a player return to a game. Ensure its fallback remains/. - Use a normal semantic page heading below the back link. The scorecard should visibly identify
itself (
My scorecard) even in the empty state; do not rely only on menu context. - Do not add a footer inside these focused/private tools unless later user testing shows value.
- Keep these pages entirely ad-free.
- When notification settings arrive, they remain under Settings; do not put a permission prompt in global navigation.
Groups and group-scoped routes¶
- Add the narrow
SiteHeaderonce per route/layout, not once per tab or child page. - Retain explicit contextual links such as
Back to groupsandBack to standings. - Convert the current generic
Headeruses into page-heading/action rows so there is only one hamburger on screen. - Preserve group owner actions, Today/Members tabs, status text, member privacy boundaries, and all Phase 5 behavior.
- Create/Join flows get the same
SiteHeader. Keep Cancel/back destinations explicit. - Error, empty, loading, forbidden, and not-found states must still include a deterministic path to Groups and/or Home; a failed data fetch must not remove all navigation.
- Do not add placeholder tournament, round, nudge, or notification controls as part of this rollout.
Public-site footer¶
Create one compact footer for the landing page and public/editorial pages. Suggested content:
Implementation direction:
- The first
Verbolusmay be a smallBrandHomeLink, or plain text if the same page already has the branded header and repeating the mark feels heavy. Test both rather than stacking logos. - “How to Play” is ambiguous across multiple games. Prefer a small
Games/How to Playgroup with separate Letter Golf and Reverse Cross destinations, or omit it until a games help index exists. - Do not say
Verbolus LLCorVerbolus Inc.. - Do not add Patreon until the real destination and support copy exist. When it exists, use
Support Verboluson About and optionally in the footer; clearly indicate an external destination. - External links opened in a new tab need the usual security attributes and an accessible indication only when opening a new tab is actually necessary. Same-site routes remain ordinary links.
- Keep the footer low contrast but WCAG AA compliant. It must not resemble an ad unit.
Metadata, favicon, social sharing, and baseline manifest¶
This can ship independently of the service worker and notification backend.
Browser metadata¶
- Replace the active
src/app/favicon.icowith the approved candidate, or adopt Next.js metadata file conventions in a way that produces exactly one authoritative favicon. Do not leave competing icon declarations. - Expose the approved Apple touch icon through the corresponding App Router metadata convention or root metadata.
- Preserve the root title/description, then improve per-route metadata as a separate content/SEO task where useful.
- Add a social share image only if it is a deliberate export. Create a deterministic 1200×630 PNG
from
brand/source/verbolus-store-hero.svg, store the runtime result underpublic/brand/social/, and name it for social use. Do not silently point Open Graph metadata at a Store-only file outsidepublic. - Social preview alt text should describe the image succinctly, for example
Verbolus word games.
Baseline web app manifest¶
Use src/app/manifest.ts and the repository's installed Next.js types. Initial values:
| Field | Direction |
|---|---|
id |
/ |
name |
Verbolus Word Games |
short_name |
Verbolus |
description |
Short, truthful description of quick original word games |
start_url |
/ |
scope |
/ |
display |
standalone |
background_color |
Fixed navy app-icon/splash family, after launch-screen review |
theme_color |
Choose and test a single safe default; theme-specific browser chrome can be refined later |
categories |
games, word, puzzle where supported |
Manifest icons:
- standard 192 and 512 icons with
purpose: "any"; - maskable 192 and 512 icons with
purpose: "maskable"; - correct
image/pngtype and exact sizes.
Initial shortcuts, ordered by usefulness:
Play Letter Golf Daily→/games/letter-golfPractice Letter Golf→ the tested URL that generates/restores Practice correctlyPlay Reverse Cross→/games/reverse-crossGroups→/groups
Before adding the Practice shortcut, verify that its deep link works in a fresh browser and an installed app. Do not publish a shortcut that accidentally opens Daily or loops through stale practice state. Shortcuts are progressive enhancement; every target must work as an ordinary URL.
A manifest alone is not a claim that offline play or push works. Do not advertise those benefits until the service worker and end-to-end flows exist.
Push notification identity (future push implementation)¶
When Web Push is implemented, Verbolus should look like the same app on the lock screen and in the notification tray.
- Notification
icon: begin with/brand/icons/pwa-icon-192.png. - Notification
badge: add a purpose-built transparent monochrome PNG around 96×96 fromverbolus-app-icon-monochrome.svg, then test it on physical Android devices. Do not assume the full-color icon will work as the masked status-bar badge. - Keep notification title/body useful even where the OS omits the icon.
- Put only a same-origin, allowlisted deep-link path in notification data.
- Use stable notification IDs/tags so replacements and deduplication match the engagement plan.
- The icon is brand identity, not permission to include words, solutions, scores, email addresses, or private group details in a push payload.
- Never put ads or sponsor logos in push notifications.
- Do not request permission on first visit. Follow the explicit Settings/earned-prompt journey in
doc/engagement-platform-plan.md. - Test icon rendering, click behavior, foreground deduplication, denied permission, revoked subscription, and missing-asset/offline behavior on supported desktop and mobile platforms.
An eventual Inbox unread badge should use the platform Badging API only when supported and should count unread Inbox items—not friends who have failed to play.
External identity usage¶
External platforms crop, resize, compress, and recolor images unpredictably. Use the fixed-background app icon as the safe default, not the transparent mark or a lockup with small text.
Email signature¶
Use a small, restrained signature:
- Use an HTTPS-hosted PNG at a stable URL, initially
https://verbolus.com/brand/icons/app-icon-1024.png, displayed at 40–48 CSS pixels square. - A dedicated 96px email export may be added later to reduce unnecessary download size, but the current 1024px file is only about 25 KB and is acceptable for a first trial.
- Include width and height attributes to prevent layout shift.
- Use
alt="Verbolus", but keep the company name and URL as real text because many email clients block images. - Avoid large banners, animated images, social-icon clutter, legal-entity suffixes, or claims such as “official app” before the relevant listings exist.
- Test in Zoho webmail plus common recipient clients and both light/dark email appearances. Email clients may apply their own dark-mode transformations, which is why the fixed navy square is safer than a transparent theme-specific mark.
WhatsApp Business and similar messaging profiles¶
- Use
app-icon-1024.pngas the profile picture. - Preview the platform's circular crop before publishing. The approved mark was designed with a self-contained background, but final crop behavior must be checked in the actual service.
- Do not use the Letter Golf or Reverse Cross game art for the business account; those identify products, not the company.
- Keep the profile display name
Verbolusand description factual. Do not imply incorporation or platform verification that does not exist.
Patreon and supporter profiles¶
- Use
app-icon-1024.pngas the Patreon profile image. - Use
store-hero-1920x1080.pngonly if Patreon's current banner crop accepts it after preview; otherwise derive a platform-specific crop from the source SVG rather than stretching it. - The public CTA should say
Support Verbolus, notRemove ads, until an entitlement system actually verifies membership and suppresses ads reliably. - Do not manually promise permanent ad removal tied only to an anonymous
userId. Follow the entitlement/account guidance indoc/engagement-platform-plan.md.
Social profiles, directories, and future channels¶
- Square/circular avatar:
app-icon-1024.png. - Wide cover: derive from the Store hero source at the platform's published dimensions and preview its safe areas.
- Posts about a specific game may use that game's artwork; the account avatar remains Verbolus.
- Keep one shared inventory of active external profiles, owner access, asset used, and last-reviewed date outside source control if it contains sensitive account details. Never commit passwords, recovery codes, or private platform IDs.
Store listings¶
- Use exports from
brand/store/andbrand/windows/only after checking the current portal's exact requirements. - Capture truthful screenshots from the production-like installed app after the navigation/PWA work.
- Include both games in screenshots; do not make a Verbolus listing appear to contain only Letter Golf unless that becomes the chosen product scope.
- Verify every crop at actual listing size. A file having nominal dimensions is not proof that text and marks survive Store UI overlays.
Accessibility requirements¶
- Use semantic
header,nav,main, andfooterlandmarks. Do not create multiple unlabelednavlandmarks with identical purposes. - Exactly one page-level
h1on ordinary content/account pages. The brand link is not a heading. - Decorative marks use empty alt text. Icon-only interactive elements require accessible names.
- All navigation and menu actions work with keyboard only; focus is visible in both themes.
- Radix sheet/dropdown opening moves focus correctly, Escape closes, and focus returns to trigger.
- Touch targets are at least 44×44 CSS pixels without making the visible art oversized.
- Text and focus indicators meet WCAG 2.2 AA contrast. Check the gray tile separately against both themes and forced colors.
- At 200% zoom and 320px CSS width, no horizontal scrolling is introduced by the header, breadcrumb, footer, title, menu, or logo.
- Respect reduced motion. Brand hover states need no transform or flourish.
- Route changes and menu closing must not strand focus. Where necessary, focus the destination's main heading without causing scroll surprises.
Performance and implementation constraints¶
- Prefer the approved SVGs for visible UI. They are tiny and crisp; do not substitute the 1024px PNG into a 28px web header.
- Give images intrinsic dimensions/aspect ratio to avoid layout shift.
- Keep
SiteHeaderand brand primitives as Server Components unless interactivity truly requires a client boundary.HeaderMenumay remain client-side. - Do not add a new icon, PWA, or component library.
- Do not inline duplicate SVG path data into several components. The files in
public/brand/are the source for runtime UI. - Do not add theme-detection effects that flash the wrong asset during hydration.
- Do not place personalized data in shared cached layouts.
- No backend, Cosmos, Terraform, or deployment change is needed for the navigation/metadata PRs.
- Keep the current analytics-consent and ad feature-flag behavior unchanged.
Analytics guidance¶
Do not add telemetry for ordinary home-link clicks merely because the component is new. Existing page-view/navigation measurement is enough.
Useful one-time product events later include:
- install prompt shown/accepted/dismissed;
- manifest shortcut launch, only if a privacy-respecting attribution parameter is deliberately designed;
- notification permission explanation shown and explicit enable action;
- push opened by category;
- footer support link selected.
All optional analytics must continue to honor stored analytics consent. Do not encode user IDs, group names, notification text, or puzzle words in event parameters.
Pull-request sequence¶
PR 1 — Shared identity primitives and menu¶
Implement:
BrandMarkandBrandHomeLink;- branded sheet/dropdown header;
- explicit menu groups and Privacy destination;
- accessible menu trigger names;
- focused tests for link destinations, accessible names, menu grouping, and close behavior where the current test environment supports them.
Do not migrate every route yet. The existing text home links remain valid during this intermediate state.
PR 2 — Non-game site shell and route migration¶
Implement:
SiteHeaderand publicSiteFooter;- landing-page header/greeting restructuring and narrow-screen width fix;
- About, Contact, Privacy, How to Play, and Updates migration;
- Scorecard, Settings, Groups, group detail, Create/Join, and relevant error-state migration;
- separation of game header from non-game page headings;
- removal or narrowing of
PageNavonly after every caller is migrated.
Do not add PWA or push behavior in this PR.
PR 3 — Metadata and baseline manifest¶
Implement:
- approved favicon and Apple touch icon;
- root metadata icon declarations using one authoritative Next.js approach;
- deliberate Open Graph/Twitter image export and metadata if included;
app/manifest.ts, standard/maskable icons, and tested deep-link shortcuts;- manifest/icon validation in browser developer tools.
Do not add a service worker merely to make an installability audit turn green. Service-worker scope, cache invalidation, offline failure behavior, and push receipt belong to the PWA implementation in the engagement plan.
PR 4 — PWA shell and installation experience (later roadmap work)¶
Implement only when scheduled:
- narrowly controlled service worker;
- install education/prompt after an earned moment;
- standalone safe-area and launch testing;
- truthful offline behavior;
- platform screenshots and Store packaging readiness.
PR 5 — Notification identity (with Web Push work)¶
Implement only with the complete notification preference/subscription design:
- 96px monochrome notification badge export;
- service-worker notification icon/badge usage;
- click/deep-link validation;
- platform test matrix;
- Inbox/badge behavior from the engagement plan.
External-channel checklist (operational, not a code PR)¶
- Publish the stable runtime icon URL.
- Trial the email signature in Zoho and several receiving clients.
- Apply the square icon to Patreon/WhatsApp only when those profiles are created.
- Record platform owners and recovery access securely.
- Preview every crop before publishing.
- Keep screenshots of the approved result for future consistency checks.
Test plan¶
Automated¶
- Run
npm test --prefix .\frontend\minigames. - Run
npm run lint --prefix .\frontend\minigames. - Run
npx --prefix .\frontend\minigames tsc --noEmit. - Run
npm run build --prefix .\frontend\minigames. - Add pure tests for navigation grouping/configuration.
- If component-testing dependencies are introduced, justify them and use Testing Library queries by role/name. Do not install a large framework solely to snapshot static markup.
- Add a small Playwright journey when browser test infrastructure exists: Home → game → menu → Settings → back, and Home → How to Play → game.
Manual browser matrix¶
At minimum:
- 320×568, 360×800, 390×844, tablet portrait, 1280px desktop, and 1440px desktop;
- light, dark, and system themes;
- 200% zoom and increased text size;
- keyboard-only navigation;
- one screen-reader pass;
- forced-colors/high-contrast mode;
- short viewport height with the mobile menu open;
- direct navigation to every page in a fresh tab so fallbacks do not depend on history;
- browser back/forward after using the history-aware back link;
- ad-preview flags on and off to ensure navigation does not shift or merge visually with ads.
For PR 3+, also test:
- favicon in a normal tab and pinned/bookmarked context where available;
- Apple touch and PWA icon declarations in developer tools;
- standard and maskable icon safe areas;
- every manifest shortcut URL in an ordinary tab before installed-app testing;
- standalone-mode safe areas and orientation changes.
Visual review questions¶
- Is Verbolus clearly identifiable on Home and content pages without overpowering game art?
- Does gameplay remain as calm and spacious as before?
- Is there exactly one obvious hamburger and one deterministic home action?
- Do back links communicate context instead of duplicating Home?
- Does the Updates section still feel editorial while belonging to the same site?
- Are public trust pages easy to find from both menu and footer?
- Are the mark and word
Verboluslegible at phone scale in both themes? - Does anything look like an ad, sponsor badge, or platform-verification mark when it is not one?
Code-review rejection checklist¶
Request changes if a PR:
- uses Letter Golf/Reverse Cross art as the Verbolus company mark;
- introduces a new logo or recolors the approved app icon;
- uses
logo.pngfor new UI instead of the approved assets; - duplicates a hamburger or branded header on a route;
- adds the full site header above an active puzzle;
- removes contextual back behavior without an equally useful replacement;
- relies on browser history as the only way home;
- has an unlabeled icon button/link or announces the logo twice;
- chooses theme art only from
prefers-color-schemeand ignores the stored theme override; - adds future disabled navigation or claims that push/install/offline/support benefits already work;
- combines standard and maskable icon purposes incorrectly;
- loads Store-only assets directly from a non-public source directory;
- makes private/account/Settings navigation resemble or contain advertising;
- breaks route error/empty states, mobile reflow, keyboard focus, or dark theme;
- changes notification, ad, analytics, account, group, or puzzle behavior outside the PR's scope.
Definition of done for the pre-AdSense UI rollout¶
The immediate rollout is complete when PRs 1 and 2 are merged and verified, with the favicon/metadata portion of PR 3 strongly preferred before the AdSense application review:
- Home visibly identifies Verbolus and still prioritizes games.
- All public pages have consistent home/menu navigation and a compact trust footer.
- Scorecard, Settings, and Groups have consistent site identity plus useful contextual navigation.
- Game screens retain their compact layout and expose the branded home link through the menu.
- Menu grouping is explicit, Privacy is discoverable, and no placeholder destinations exist.
- Light/dark/mobile/accessibility checks pass.
- Existing ad-placement and consent rules are unchanged.
- Approved assets are used from their canonical paths, with no alternate logo system.
The full PWA, push-notification badge, Store listing, Patreon, WhatsApp Business, and email-signature work is not a prerequisite for AdSense. Those uses are recorded here so every future channel starts from the same identity instead of re-deciding the logo each time.
Copy/paste agent kickoff prompts¶
Use one prompt per agent or task. Replace the PR number only when the previous increment is complete.
Product/design agent¶
Read
doc/brand-navigation-rollout-plan.md,frontend/minigames/brand/README.md, and the current frontend implementation. Review the proposed PR 1 and PR 2 navigation system against every route named in the brief. Produce mobile (320/360/390px), desktop, light-theme, and dark-theme annotated layouts for Home, one active game, one public content page, Settings, Groups, the mobile sheet, and desktop dropdown. Use only the approved assets. Identify any conflict with current gameplay space, route hierarchy, accessibility, or ad-placement rules. Do not invent new product destinations or change game mechanics. Record decisions that the coding agent can implement directly.
Coding agent — PR 1¶
Implement only PR 1 from
doc/brand-navigation-rollout-plan.md: shared Verbolus identity primitives and the regrouped, accessible mobile/desktop menu. Read all linked source-of-truth docs and current neighboring code first. Preserve gameplay, route behavior, feature-flagged god-view tools, consent, and ads. Add proportionate tests, run the frontend test/lint/typecheck/build gates, inspect the final diff, and report any pre-existing failures separately. Do not start the route migration, manifest, service worker, push, or external-platform work.
Coding agent — PR 2¶
With PR 1 merged, implement only PR 2 from
doc/brand-navigation-rollout-plan.md: the non-game site header/footer, route migrations, page-heading/game-header separation, and responsive Home correction. Preserve the recent PageNav/BackLink intent and all route-specific behavior. Verify every listed route, including loading/error/empty states, on narrow mobile and both themes. Add proportionate tests and run test/lint/typecheck/build. Do not add PWA, service-worker, push, or external-account behavior.
Coding agent — PR 3¶
With the navigation rollout merged, implement only PR 3 from
doc/brand-navigation-rollout-plan.md: authoritative favicon/Apple icon metadata, a deliberate social-card export if approved, and the baseline typed Next.js manifest with standard and maskable icons plus tested shortcuts. Follow the repository's installed Next.js version and current primary documentation. Do not add a service worker or claim offline/push support. Validate metadata, manifest responses, icon dimensions/purposes, shortcut deep links, production build output, and mobile/desktop browser behavior.
Testing agent¶
Treat
doc/brand-navigation-rollout-plan.mdas the acceptance specification for the current PR. Inspect the actual diff and test the changed PR slice only, while checking its interactions with every affected route. Cover link destinations, menu semantics/focus, direct-load fallbacks, browser history, 320/360/390px reflow, desktop, 200% zoom, light/dark/system themes, forced colors, keyboard, screen reader, and ad-preview flags. For manifest work also validate standard/maskable icons and every shortcut. Report reproducible failures with route, viewport, theme, steps, expected, and actual result; distinguish pre-existing defects from regressions.
Code-review agent¶
Review the diff against
doc/brand-navigation-rollout-plan.md,AGENTS.md, the applicable.github/instructions/, and the current route behavior. Prioritize regressions, accessibility, duplicated or missing navigation, theme correctness, mobile overlap, hydration/performance, incorrect asset choice, broken history/direct-load behavior, scope creep, and test gaps. Apply the brief's rejection checklist. Do not request speculative abstractions or later-phase features. Return findings ordered by severity with exact file/line references; explicitly say when there are no actionable findings.
Standards references for implementation agents¶
- Next.js App Router metadata files and generated manifests: https://nextjs.org/docs/app/api-reference/file-conventions/metadata
- Next.js
manifest.ts: https://nextjs.org/docs/app/api-reference/file-conventions/metadata/manifest - Next.js favicon/icon/Apple icon conventions: https://nextjs.org/docs/app/api-reference/file-conventions/metadata/app-icons
- Web app manifest shortcuts: https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Manifest/Reference/shortcuts
- Service-worker notification
iconandbadgeoptions: https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/showNotification - Maskable icon safe-area guidance: https://web.dev/articles/maskable-icon
Check these primary references again when implementing later platform phases; browser and Store capabilities evolve, while this document intentionally records product direction rather than freezing vendor behavior forever.