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. Depending on the template, the app name may live in one source-of-truth module or be spread across several files — either way, a partial rename leaves the app half-branded (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.

Locate the layout first

Branding lives in different places depending on the template. Detect which layout you are in before editing:

• Centralized layout — app/lib/app-config.ts exists. It is the single source of truth for the name and title; the frontend surfaces (<title>, route meta(), header, sidebar, index heading, apple-mobile-web-app-title) derive from its APP_NAME / APP_TITLE exports, so you change the name in one place.
• Inlined layout — no app/lib/app-config.ts. The name and title are written directly into package.json, each route's meta(), and app/root.tsx. You must update each surface individually.

When in doubt, grep -rn the current title and slug across app/, server/, package.json, and public/ and fix every real hit — the two layouts share the manifest and icon steps regardless.

The Checklist

Step 1 — App name + title source

Centralized layout (app/lib/app-config.ts): change both constants and stop — the rest of the frontend derives from them.

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

Inlined layout (no app-config.ts): set the title/slug at each surface.

• Every route meta() title under app/routes/*.tsx (e.g. _index.tsx, agent.tsx, settings.tsx) — replace the app title. These are seeded from a {{APP_TITLE}} placeholder at scaffold time and become plain literals afterward.
• Any useActionQuery("hello", { name: … }) in app/routes/_index.tsx seeded with the title.
• app/root.tsx apple-mobile-web-app-title — a literal (often "App"); set it to the title.

Step 2 — package.json (both layouts)

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

Step 3 — Login / auth title (centralized layout only)

If server/plugins/auth.ts exists it keeps its own duplicate rawAppTitle, used on the login/signup pages. Set it to the same title as app/lib/app-config.ts. (The inlined layout's server/middleware/auth.ts carries no app title — skip this step there.)

Step 4 — public/manifest.json (both layouts)

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 (both layouts)

Replace the icon files with a new mark that reflects the app's identity. The set present depends on the template; update each one you find:

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. All 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:

• configureTracking({ app, template }) in app/root.tsx — analytics identifiers seeded at scaffold time; leave them. This holds even in the inlined layout, where app was seeded from the slug — changing it re-keys analytics history.
• server/plugins/agent-chat.ts appId (centralized layout) — a stable platform analytics/routing key; leave it exactly as scaffolded.
• .github/workflows/*.yml — template automation; references the repo/template identity, not the running app.
• AGENTS.md / DEVELOPING.md — developer docs for the 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.