# Theming and branding exploration

Status: presentation and recording page designs accepted with Technical mono; original D mascot selected.
Decision: https://github.com/CosticaPuntaru/SnagBadger/issues/31
Starting commit: 54668458ff020b72d92efbe1ea458a66d42602d2.

Question: which structure makes manual reporting and agent run review useful
inside a host product while keeping supplied components easy to restyle?

The implementation stacks on verified bootstrap
`d6dc3a4ab667e80c5d5b18ca78e95bf3f86dead9` (#32) and verification harness
`045809c7b487adcf7ac971a353f52c68258a5689` (#34), plus architecture enforcement
`f49b8c1e385c35054cae90185ae2a5e836260f77` (#35, including #33 and the reviewed inline-type eager-loading fix). Frozen installation and full
prerequisite verification were reproduced, including the harness in a separate
clean checkout. Node 24.21.0 and pnpm 12.10.1 remain pinned.

The maintained playground handoff is still pending. User-authorized scoped
component development lives in reporting's browser prototype area; a read-only
host fixture uses the existing browser harness, not a second playground.
Coordination and dependency choices are recorded on #25.
The unified verification command retains the custom lint rules, architecture
gate and regression fixtures as well as the browser harness. Public prototype
entries sit outside private browser folders; internals retain the private-import
gate. Optional stylesheet exports use exact registered CSS targets, with passing
and failing fixtures that preserve the functions-only/UI loading boundary.

## Run and integrate

Run `pnpm install --frozen-lockfile`, then `pnpm prototype:theming` and open
http://localhost:4186/branding/?variant=A. The same route supports A through E.
The command builds the scoped assets before starting the existing Vite fixture
server. Restart it after component edits. Theme and draft state stay in memory.
The fixture's TypeScript environment resolves the supported prototype entry to
source for pre-build checking; Vite and the Node consumer test resolve its built
package export at runtime. A fresh checkout needs no preliminary build to verify.

The future playground route can import `ThemingPrototype` from
`@snagbadger/reporting/theming-prototype`, pass its host scenario as `host`, and
pass `import.meta.env.DEV` as `development`. The floating switcher is absent by
default, and the review fixture also gates it on the development build flag.
Styles are separate imports:

- `@snagbadger/reporting/theming-prototype/layout.css`: scoped structure and
  experiment controls, compiled with prefixed Tailwind utilities; no preflight.
- `@snagbadger/reporting/theming-prototype/default-skin.css`: optional supplied
  skin, active only for `data-skin="default"`.
- `@snagbadger/reporting/theming-prototype/host-skin.css`: independent Northstar
  host stylesheet, active only for `data-skin="host"`.

The component entry imports no CSS, and the portable entry imports no React or
styles. Hosts can omit the default skin entirely and restyle the predefined
components using the prototype's scoped variables/classes. These experimental
exports are not accepted product contracts. The review fixture's
`?omitDefaultSkin=1` demonstrates omission; choose the Northstar preset there.

React/react-dom/types 19.3.0 and Tailwind/Vite plugin 4.3.3 use compatible official
registry metadata and passed strict peer/release-age installation policy.
The Button adapts the [shadcn/ui registry source](https://ui.shadcn.com/r/styles/new-york/button.json);
its MIT notice is retained in `sdk/reporting/third-party.md`. Tailwind follows
the [official Vite integration](https://tailwindcss.com/docs/installation/using-vite).

## Current five brand worlds

The user requested five vastly different, bold, funny designs, with the
personality of [PostHog](https://posthog.com/) but more color and cheer. This
expands the earlier warm palette exploration without choosing a winner.
The mascot is an original repo-native SVG badger; no PostHog artwork or logo is
copied. No external font, image, or runtime dependency is introduced.

| URL | Brand world    | Composition and character                                                                                                    |
| --- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| A   | Oops! Club     | Oversized orange type, scattered pink/blue/yellow stickers, an irreverent badge mascot, ticker; companion reporter below.    |
| B   | Bug Arcade     | Purple arcade cabinet, lime controls, mint visor, score display and chunky monospace; workbench report below.                |
| C   | Happy Trails   | Centered serif typography, rolling green hills, sunshine/coral flowers and a trail-guide badger; narrative report below.     |
| D   | Snag! Comics   | Yellow/pink/cyan comic panels, speech bubbles, superhero cape, dramatic headlines; reporter-first two-panel evidence layout. |
| E   | Cosmic Cleanup | Blue orbital composition, peach planet/button, astronaut badger and three-step mission strip; run-first mission report.      |

Every invitation opens the same local illustrative failure draft. Each direction
retains its own edited tokens in memory when cycling; appearance preference is
shared across directions, still System by default with manual overrides. Reset
restores the current world's palette. Host styling and the no-skin option remain
independent of the optional decorative skin. Tests compare supplied host styles
against a standalone baseline in all five worlds.

The private theme coordinator owns edits, appearance observation, host presets,
and reset for both the five-world study and the single product theme. Controls
render its state and invoke its actions. Device changes apply only to themes
following System; manual appearance changes replace the palette color tokens
as before. Reset resumes System, restores the active world's defaults, and
retains Technical mono on the product pages. Observation is removed on unmount.

## Selected mascot

On 2026-10-10, the user locked in the original mascot from **D: Snag! Comics**.
Use the existing repo-native SVG badger with its pink superhero cape: plum body,
cream facial stripe and belly, rosy cheeks, small friendly eyes, crooked smile,
and raised paw. Its source is `Badger` with `accessory="cape"` in
`sdk/reporting/src/browser/theming-prototype/badger.tsx`.

The initial selection covered the mascot only. At that stage the brand world, layout, typography, and
palette remained open; the preference for Oops! Club informed the follow-up pages.
Subsequent generated mascot alternatives are exploration references, not the
selected artwork. Preserve the original D character in further branding work.

## Original three layout studies (preserved design brief)

| Direction     | In-app reporter                                                                                         | Agent test-run report                                                                      | Visual character                                            |
| ------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
| A: Companion  | Narrow side panel keeps the host scenario visible; summary and evidence disclosure lead to local review | Compact outcome summary with expandable failure rows and adjacent bug-report composer      | Quiet, compact, restrained brand accent                     |
| B: Workbench  | Wide split view with evidence canvas and persistent report inspector                                    | Section/result navigation, central evidence and right-side failure details                 | Technical, dense, strong dividers and typographic hierarchy |
| C: Fieldnotes | Guided single-column sequence: describe, inspect illustrative evidence, review                          | Readable run narrative with chronological observations and inline failure-to-report action | Spacious, editorial, warm and approachable                  |

These original structures underpin the first three current brand worlds.
The first visible variant is a navigation default, never a winning decision.

## Illustrative content and local interaction

Use the playground's form-save scenario once its author establishes the fixture.
Until then, the review host is deliberately read-only profile context.
Show a mixed-outcome run with passed, failed and skipped results. Clearly mark
screenshots, recorded steps, console snippets and timings as illustrative.
Selecting a failed result populates a local bug-report draft; it never converts
the whole test run into a bug report. Editing drafts, toggling evidence inclusion,
reviewing and simulating completion must produce visible state. No real capture,
network submission, credentials or implied final product schema.

## Styling experiment

User feedback Q3/Q4 selects the warm, approachable palette direction and
device-following appearance with a manual override. Light uses burnt orange
`#b84418`, sand `#fff8ed`, and dark brown `#34231c`. Dark uses warm orange
`#ff9c66`, deep brown `#241a16`, and cream `#f8ead7`. Exact shades remain
reviewable. System is the initial appearance preference; live device changes
apply only while System is selected. Reset resumes System. Preferences remain
in memory. The subsequent five-world request broadens palette exploration;
neither a brand world nor a layout is selected.

Keep the experiment controls outside the branded preview. Apply the same token
state to the reporter and run report, without leaking it into the host page.
Compare the supplied default skin, a fictional host brand and skin-off supplied
components. Host restyling must not require reconstructing components.

Expose brand name/mark, accent, surface, text and border colors, radius,
typography, spacing/density and light/dark appearance. Include reset controls
and a readable current-state summary. Preserve token values across variant
switches in memory; variant links remain reload-stable. Do not add persistence
or establish public theme APIs in this experiment.

Optional default skin means a real optional styling layer, not simply removing
the brand name. The exact distribution mechanism remains an implementation
question to evaluate against the verified playground and consumer checks.

## Route and controls

Mount within the maintained playground following its established convention.
One route uses `?variant=A` through `?variant=E`. Invalid variants fall
back predictably. A shared floating bottom bar cycles in both directions with
wraparound. Arrow-key cycling must not interfere with inputs, textareas,
contenteditable areas or native selection controls. Preserve unrelated search
parameters and handle browser navigation. Keep content clear of the switcher.
Gate the experimental switcher out of production builds as the prototype skill
requires; development remains the interactive review mode. The explicitly
requested hosted PR review uses a separate `pr-preview` build mode that keeps
the controls available in an optimized static artifact. Normal production mode
continues to hide the switcher.

## Static phone preview

`pnpm build` also produces `dist/pr-preview/` using the existing branding fixture.
`pnpm build:pr-preview` rebuilds only that artifact after the reporting package
has been built. Relative asset URLs allow publication under a repository and PR
subdirectory. The build reads no environment files and emits no source maps.
Only the generated artifact is intended for hosting; it contains the compiled
illustrative demo, including all five directions and theme controls.

`pnpm test:pr-preview` checks the optimized artifact with a phone viewport under
`/SnagBadger/pr-36/`, including direct direction links, styles, wrapping,
reload, local drafting, white-label controls, overflow and resource failures.
This check is included in `pnpm verify`.

Hosting is not yet configured. GitHub rejected Pages creation for the private
repository with HTTP 422: the current plan does not support Pages for this
repository. The user must choose an eligible plan or a public artifact-only
preview repository before deployment automation can be completed. Source
repository visibility remains private. No live preview URL exists yet.

## Verification before prototype handoff

Run the inherited complete production command with no prototype exclusions.
Test observable behavior: direct URLs and invalid fallback, wrapping and browser
navigation, editing without keyboard interception, shared styling on both
surfaces, independent host styles, reset, draft-from-failure, and local-only
completion. Exercise the actual default-skin boundary where applicable.

Review all directions in T3 collaborative preview at desktop and narrow widths,
including keyboard focus, long host names, evidence expansion and edited tokens.
Check default/host presets for legibility and contrast; arbitrary custom colors
must remain inspectable and resettable. Verify the built artifact and development
switcher behavior. Reproduce installation and complete checks in a clean checkout.
Record exact prerequisite commits and distinguish environmental blockers from
code failures. Publish reviewable code and evidence to issue #31 when ready.

## Feedback gate

Do not select a direction, close the decision issue, or promote a winner until
the user reviews the interactive alternatives. Feedback may combine elements
from multiple directions. T3 browser review covers all five worlds at desktop
and narrow widths; automated journeys cover switching, editing, local completion,
host styling without the default skin, and overflow. Integration with the actual
maintained scenario remains pending #25's verified handoff.

## Presentation and recording studies

The user requested two follow-up prototype pages using the selected D mascot:

- `/branding/?page=presentation`: a presentation page combining the caped badger
  with the preferred Oops! Club warmth, large type, stickers, and a short product story.
- `/branding/?page=recording`: the record launcher in an illustrative host workspace,
  followed by a modal ready/recording/paused/review/saved flow.

Both reuse the existing supported entry, optional skin, theme controls, and browser
fixture. They introduce no playground scaffold or shared fixture edits. Recording
is simulated: no screen, audio, activity collection, upload, or tracker submission.
The elapsed timer stops on pause and close; draft review and evidence inclusion
stay local. Native modal behavior supplies focus containment, Escape dismissal,
and focus return. Overall brand and capture interaction remain reviewable.
Ticket-link executable replay (#38) is future scope and is not implemented here.

## Accepted page designs and typography

The user subsequently accepted the presentation and recording page designs,
combining the original D caped badger with the warm Oops! Club treatment.
SnagBadger-owned pages use **Technical mono** by default and after resetting the
product-page theme: `ui-monospace, Consolas, monospace`. Theme controls remain
available for host customization. The original five studies remain reference
material; this acceptance applies to the two follow-up page designs.

The embedded record button inherits its host page's font family, including after
host font changes. It loads no font files and does not apply the SnagBadger font
token. The illustrative host workspace chooses system sans independently, making
that boundary visible next to the monospace product page and recording dialog.

This follow-up is isolated from reviewed PR #36 at
`915349ba5945716ed08e9df4aa9177fa1fcce0f3`. Design acceptance does not authorize
merging, deploying, real capture, or ticket replay; #37 and #38 remain deferred.