app-branding

name	app-branding
description	How to rename or rebrand the app so every surface — title, package metadata, PWA manifest, and icons — stays consistent. Use when a prompt establishes or implies a new app name, title, or visual identity, OR when you generate an app title, theme, or icon yourself while scaffolding an app from an initial prompt.
scope	dev
metadata	{"internal":true}

App Branding

Trigger

Read this skill whenever the app's name, title, or visual identity is being established or changed — whether the user states it or you derive it yourself.

• Explicit — the prompt names the app: "rename this app to …", "this is a Todo app called …", "call this app …".
• Implicit / agent-generated — the prompt describes what to build but leaves the branding to you: "build me a habit tracker", "turn this into a recipe manager", "make a CRM for my studio". The moment you decide on a title, theme color, or icon from that prompt, treat it as a branding change and apply the full checklist so your generated identity lands on every surface — not just the one screen you happen to be building.

If you are inventing an app title, theme, or icon as part of scaffolding a new app from an initial prompt, that counts — run the checklist in the same pass.

Rule

Apply all of the updates below in a single consistent pass. The app title lives in one source of truth (app/lib/app-config.ts), but several other surfaces carry their own copies of the name, description, and icon. Skipping any one leaves the app half-renamed — a stale tab title, launcher label, or icon.

Derive three values once, then reuse them everywhere:

• Title — human-readable display name, e.g. "My Task App".
• Slug — URL/npm-safe form: lowercase letters, digits, and hyphens only, e.g. "my-task-app".
• Description — one sentence describing what the app does.

The Checklist

Step 1 — app/lib/app-config.ts (source of truth)

Change both constants:

• rawAppName → the slug.
• rawAppTitle → the title.

Everything in the frontend (<title>, route meta(), header, sidebar, the index <h1>, and root.tsx's apple-mobile-web-app-title) derives from these automatically — no other frontend edits are needed.

Step 2 — server/plugins/auth.ts

This file keeps its own duplicate rawAppTitle, used on the login/signup pages. Set it to the same title as app/lib/app-config.ts.

Step 3 — package.json

• displayName → the title.
• description → the description.
• name → the slug. Only change this if the user explicitly asks to rename the package (it is the npm package identifier).

Step 4 — public/manifest.json

This is a static file (not generated by a plugin). Update:

• name → the title (full install name in OS app drawers).
• short_name → a compact launcher label; keep it ≤12 characters, abbreviating the title if needed.
• description → the same description used in package.json.

Step 5 — Icon SVG files

Replace all four icon files with a new mark that reflects the app's identity:

File	Purpose
public/favicon.svg	Browser tab favicon
public/icon-180.svg	Apple touch icon (iOS home screen)
public/icon-192.svg	PWA install icon (Android / Chrome)
public/icon-512.svg	PWA install icon (large / splash)

Build the icon from SVG primitives — do not embed a base64-encoded PNG (the current files do; replace that with clean, editable, scalable vector art). All four files should share the same visual design; only the width and height attributes differ. A simple, reliable approach: a filled rounded square in the brand color with the first letter (or a relevant glyph) centered in white.

Template to adapt (change fill, the letter/glyph, and rx to suit the brand):

<svg xmlns="http://www.w3.org/2000/svg" width="192" height="192" viewBox="0 0 192 192">
  <rect width="192" height="192" rx="40" fill="#2563EB"/>
  <text x="96" y="130" font-family="system-ui, sans-serif" font-size="110"
        font-weight="700" fill="white" text-anchor="middle">A</text>
</svg>

Keep width/height at 180, 192, and 512 for the respective icon files; favicon.svg can use any of these sizes (the viewBox keeps it scalable).

What NOT to change

These are stable identifiers or template-internal files, not user-facing brand:

• server/plugins/agent-chat.ts appId — leave as "builder-agent-native-starter"; it is a stable platform analytics/routing key.
• configureTracking({ app, template }) in app/root.tsx — analytics identifiers, not the display name; leave them.
• .github/workflows/*.yml — template automation; references the repo/template identity, not the running app.
• DEVELOPING.md — developer docs for the starter template itself.

Verification

• pnpm typecheck passes.
• Grep for the old title/slug across app/, server/, package.json, and public/ — no unintended leftovers remain (except the intentional "do not change" identifiers above).
• The browser tab title, sidebar, header, and index heading all show the new title.