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