Site and theme
Change the site's name, links, logo, metadata, colors and fonts - which file holds what, and what to ask the agent.
Outcome: your name, logo and colors everywhere: header, footer, dashboard, browser tab, home-screen icon, and the preview card when someone shares a link.
Tell the agent the new name, tagline and description, give it your logo files, and say which colors you want. This page lists where each of those lives so you can check its work.
config/site.ts
| Field | What it does |
|---|---|
name |
the site name: the end of every page title (Pricing | <name>), the home-screen app name, the dashboard |
description |
the description in the web app manifest |
url |
the site address; read from NEXT_PUBLIC_SITE_URL, with a fallback in BASE_URL at the top of the file |
authors, creator |
author metadata; creator is your X (Twitter) handle for the share card |
socialLinks |
GitHub, X, YouTube, Instagram, TikTok, Discord, email. The footer shows an icon for each one that is set; the constants at the top of the file hold the URLs. Discord comes from NEXT_PUBLIC_DISCORD_INVITE_URL |
themeColors |
the color the browser gives its own bars, one for light and one for dark; keep them equal to your page background |
defaultNextTheme |
the theme a first-time visitor sees: "dark" (the starter's default), "light" or "system". Visitors can switch in the header |
icons |
the favicon (/favicon.ico), the shortcut icon (/logo.svg) and the Apple touch icon (/apple-touch-icon.png) |
The visible title, tagline and description are not in this file. They are translated, so they live in i18n/messages/<code>/common.json under Home: title, tagLine, description. The home page title is <title> - <tagLine>. Ask the agent to change them in all eight languages.
Logo and images in public/
Replace these files with your own, keeping the names:
| File | Used for |
|---|---|
logo.svg |
the logo in the header, mobile menu and dashboard sidebar; the shortcut icon |
favicon.ico |
the browser tab |
apple-touch-icon.png |
the icon on an iPhone home screen. It must be opaque, with the background color baked in: iOS ignores transparency and shows white edges |
logo.png (192×192), logo-512.png |
app icons in the web app manifest; logo.png also appears on the generated preview images of blog and glossary posts |
logo-maskable.png (192×192), logo-512-maskable.png |
app icons Android may crop to a circle or rounded square; keep the logo inside the central safe area |
og.png, og_<code>.png |
the preview image when a page is shared, one per language (og_zh.png, og_ja.png …). Commonly 1200×630 |
Icon generators such as realfavicongenerator.net or icon.kitchen produce the whole set from one image.
app/manifest.ts describes the installable web app. It reads the name from config/site.ts, but background_color, theme_color and categories are written in the file; ask the agent to set them to your colors and product type.
Metadata
Every page builds its <head> tags through constructMetadata() in lib/metadata.ts:
- Title:
<page title> | <site name>, or<title> - <tagLine>on the home page. - Description: the page's own, or the
Home.descriptiontext. - Canonical URL and language alternates: one
hreflanglink per language, plusx-defaultpointing to English. - Open Graph and X (Twitter) card: title, description, and the image
og.png(English) orog_<code>.png. Blog and glossary posts generate their own image (opengraph-image.tsxnext to each post page). - Robots: a page passes
noIndex: trueto keep itself out of search results.
You rarely change lib/metadata.ts itself. When you ask for a new page, the agent gives it a title, a description and its path; the rest follows.
To check a page, open it, view the source, and look at the <title>, og: and hreflang tags; or paste the URL into a social preview checker after deploying.
Colors: styles/globals.css
The colors are CSS variables in two blocks: :root for the light theme and .dark for the dark theme. The main ones:
| Variable | What it colors |
|---|---|
--background, --foreground |
the page and its text |
--card, --popover (and -foreground) |
cards, menus, dialogs |
--primary, --primary-foreground |
buttons, links, focus rings (--ring) |
--secondary, --muted, --accent (and -foreground) |
quieter surfaces and hover states |
--destructive |
delete buttons and errors |
--border, --input |
lines and form fields |
--sidebar… |
the dashboard sidebar |
--chart-1 … --chart-5 |
the admin charts |
--credit… |
the credit balance badge |
--radius |
corner rounding |
--ok, --wait, --bad |
status colors: passed, waiting for a person, failed. They show check marks and status in the landing page's session demo and on the pricing cards. They carry meaning; keep green, amber and red (or your equivalents) and do not reuse them for decoration |
Both blocks must define every variable. The starter's colors are written as hex values (#0f9d58); any CSS color works.
A theme editor such as tweakcn.com exports :root and .dark blocks you can hand to the agent: "Use these colors; keep --ok, --wait, --bad and the --credit variables." Pasting the export over the whole blocks would drop those variables.
Fonts: app/fonts.ts
Three fonts, self-hosted from assets/fonts/ as .woff2 files (Latin characters, OFL license):
| Font | Variable | Used for |
|---|---|---|
| Instrument Sans 400/500/600 | --font-instrument → --font-sans |
body text |
| IBM Plex Mono 400/600 | --font-plex → --font-mono |
code and labels |
| Syne 800 | --font-syne → font-brand, font-display |
the brand name and landing headlines |
They are self-hosted on purpose: next/font/google downloads fonts during the build and fails on networks that block Google.
To change a font, give the agent the .woff2 files (or name an open-license font) and say which role it takes. It puts the files in assets/fonts/, updates app/fonts.ts, and keeps the variable names so styles/globals.css and styles/custom.utilities.css keep working. Chinese, Japanese and Korean pages fall back to the visitor's system font, since the bundled files cover Latin characters only.
When it fails
| What you see | Cause | Fix |
|---|---|---|
| The old name still shows in the tab title or on the home page | Home.title / Home.tagLine in common.json were not changed in every language |
ask the agent to update all eight |
| White corners around the iPhone home-screen icon | apple-touch-icon.png has transparency |
export it opaque, with the background filled |
| A shared link shows the old preview | social networks cache previews | use the network's preview debugger to refresh it |
| A shared link in one language has no preview image | og_<code>.png is missing |
add the file |
| Some text is unreadable in one theme | a variable was changed in :root but not in .dark, or the other way round |
set both blocks |
| A new font does not load | the path in app/fonts.ts does not match the file name |
fix the path; restart pnpm dev |