Customize branding and design tokens

When to use

Use this path when turning a fresh buyer scaffold into a named product or deliberately changing its visual identity. Run create-app --brand first; use the rest of this path for product description, sender identity, URLs, imagery, icons, typography, and color.

The CLI applies a safe display name to every counted static surface. It does not invent a logo, marketing promise, support address, social account, legal entity, or accessible color system.

Files and boundaries

• packages/create-app/src/core.ts: counted static brand manifest and safe name validation.
• apps/web/src/configs/config.ts: one runtime BRAND_NAME used by React UI.
• apps/web/index.html: browser, social, and application metadata.
• apps/web/public/favicon/site.webmanifest: PWA name, description, icons, theme, and start URL.
• apps/web/public/offline.html: standalone offline identity and colors.
• apps/web/src/components/brand/: runtime logo-mark and product-name composition.
• apps/web/public/logo.svg and apps/web/public/favicon/: source mark and generated image assets.
• apps/web/src/styles/_variables.css: font, surface, accent, and status tokens.
• packages/email/src/: email identity, logo URL, sender-facing copy, and footer links.
• apps/server/email-templates/: generated email HTML; update it through the email deploy command.
• apps/server/src/config/env.ts and .env.example: default sender identity.

Runtime React copy must read BRAND_NAME; static HTML, JSON, server, and email surfaces belong in the counted brand manifest. Product descriptions and support/legal URLs are explicit product decisions, not brand-name substitutions.

Procedure

1. Generate the buyer with a safe brand name:

   pnpm superslate proof-product \
     --from /absolute/path/to/template \
     --scope @proof \
     --brand "Proof Product" \
     --no-git

2. Open apps/web/src/configs/config.ts, index.html, site.webmanifest, offline.html, the auth pages, settings, and every email source. Confirm the generated name is correct and replace the neutral description with one accurate customer outcome.

3. Keep short_name concise enough for installed-app launchers. Remove every PWA shortcut that does not point to a real, authorized route.

4. Replace apps/web/public/logo.svg with an optimized, text-free source mark, then regenerate the favicon and splash raster set from that one reviewed master with vp run --filter @app/web assets:splash. Preserve declared dimensions, transparency, safe-zone behavior, and the maskable-icon requirement.

5. Set real alt text only where an image communicates information. Keep repeated marks decorative when adjacent text already names the product.

6. Change the semantic values in _variables.css: --surface-canvas, --surface-raised, --accent, --accent-strong, their opacity variants, and status colors. Do not replace semantic token names with a new product-color vocabulary.

7. Verify normal, hover, active, disabled, selected, error, and focus-visible states on both surfaces. Preserve visible keyboard focus and test text, icons, borders, and controls for contrast.

8. Update fonts deliberately. Ship required webfont files locally or document their provider, licensing, fallback, preload, and failure behavior.

9. Update packages/email/src/components/EmailLayout.tsx with a production PNG logo URL and real footer destinations. Set EMAIL_FROM to a verified sender owned by the product.

10. Regenerate email artifacts:

    vp run --filter @app/email deploy

11. Search buyer output for the placeholder and source-product markers. If a new static brand surface is intentional, add it to BRAND_MANIFEST with its exact occurrence count and update the contract test.

Verification

Run:

vp run --filter create-app test
vp run --filter @app/email deploy
vp check
vp run --filter @app/web test
vp run --filter @app/web build

Generate a product with a multiword custom brand and inspect:

• document title, metadata, install prompt, PWA manifest, offline page, auth, settings, and errors;
• navbar, narrow viewport, splash/loading, missing-route, and reduced-motion behavior;
• verification, magic-link, welcome, security, payment, and subscription email HTML;
• favicons, Apple touch icon, maskable icon, install prompt, and installed launcher name;
• email sender, logo, links, reply behavior, and inbox rendering.

Run a case-insensitive scan for the old product name, placeholder descriptions, retired analytics events, stale routes, and source-product class prefixes. A source-only pass is insufficient: inspect the generated buyer and its production build.

Security constraints

• Treat HTML, JSON, TypeScript, JSX, shell, and SVG as different escaping contexts. The CLI rejects punctuation that could break those formats; do not loosen validation without context-aware escaping and tests.
• Never put secret values in VITE_*, HTML metadata, the PWA manifest, source maps, or image files.
• Do not point email or web UI at unverified domains, sender addresses, support inboxes, or social accounts.
• Preserve CSP-compatible asset loading, HTTPS URLs, Sentry redaction, and authenticated-route behavior while replacing identity.
• Do not make focus indicators, status states, or legal/support links disappear for visual purity.

Failure modes

• Placeholder survives: a static surface is missing from BRAND_MANIFEST, or generated email HTML was not refreshed.
• Broken TypeScript/JSON/HTML after scaffold: brand validation or context handling was bypassed.
• Wrong installed-app name or icon: stale manifest, service worker, favicon cache, or maskable asset.
• Long name clips: a component embedded text in a fixed-size image instead of composing the runtime name with the text-free mark.
• Email shows the old identity: source was changed without running the email deploy command.
• New palette is unreadable: raw values were changed without testing semantic states and contrast.
• Production build keeps old assets: browser/PWA cache was not invalidated or the wrong source master was regenerated.

Rollback and diagnosis

Keep the last reviewed source mark, icon master, token values, and generated email artifact commit. Revert identity as one unit: runtime name, static metadata, PWA assets, design tokens, email source, sender configuration, and generated templates.

Diagnose from source to consumer: config → React UI; HTML/manifest → browser and installed PWA; email source → deploy output → provider; token definition → component state. Clear only disposable local browser/PWA caches during diagnosis; never delete customer data or external provider resources.

Acceptance criteria

• A fresh custom-brand scaffold passes without manual syntax or formatting repair.
• The counted manifest rewrites every intended static surface and rejects unsafe input.
• Runtime UI uses one brand constant and a text-free, size-independent mark.
• Metadata, PWA, offline, auth, billing, account, error, and email surfaces contain no source-product behavior or placeholder route.
• Semantic tokens cover canvas, raised surface, accent, strong accent, status, and focus states.
• Keyboard focus, contrast, reduced motion, narrow viewport, long-name, and missing-image behavior are reviewed.
• Generated email HTML matches source and uses an approved sender, logo, and destinations.
• The create-app test, email deploy, vp check, web test, and production build pass.

Agent prohibitions

• Do not lock or register a commercial product name, domain, organization, or account without owner approval.
• Do not inject arbitrary brand text into source contexts without validation and escaping.
• Do not edit generated email HTML manually.
• Do not embed a buyer name in fixed-size raster or SVG artwork when runtime text can own it.
• Do not ship stale PWA shortcuts, source-product copy, event names, class prefixes, or profile fields.
• Do not rename semantic tokens to colors such as pink or scatter raw brand hex values through components.
• Do not claim accessibility from a palette alone; verify actual rendered states and interactions.