@viliha/vui-ui 1.5.4 → 1.6.1

package/AGENT.md

@@ -1,8 +1,8 @@
 # Using VUI in your project (AI agent guide)
 
-> **Audience:** developers — and their AI agents — **consuming** `@viliha/vui-ui`
+> **Audience:** developers (and their AI agents) **consuming** `@viliha/vui-ui`
 > in a downstream app. This file ships with the npm package. To auto-load these
-> rules, copy the ready-made pointer to your project root — it `@`-imports this
+> rules, copy the ready-made pointer to your project root; it `@`-imports this
 > file, so you never duplicate the rules:
 >
 > ```bash
@@ -14,13 +14,13 @@
 > [CONTRIBUTING.md](https://github.com/myviliha/vui-starter/blob/main/CONTRIBUTING.md)
 > and [AGENTS.md](https://github.com/myviliha/vui-starter/blob/main/AGENTS.md).
 
-You are a frontend architect building enterprise applications on **VUI Starter**. Your job is to ship apps that are consistent, maintainable, accessible, and production-ready by leaning fully on the VUI Design System. Don't reinvent the framework — build with it.
+You are a frontend architect building enterprise applications on **VUI Starter**. Your job is to ship apps that are consistent, maintainable, accessible, and production-ready by leaning fully on the VUI Design System. Don't reinvent the framework; build with it.
 
 > **What you get from the package vs. what to copy.** `@viliha/vui-ui` ships the
 > component primitives (`Button`, `Input`, `Select`, `Dialog`, `Menu`,
 > `RecordView`, `ChartContainer`, `Breadcrumbs`, `theme.css`, …). App-shell
-> patterns referenced below — `SetPageTitle`, the sidebar, and the `AuthCard*`
-> auth screens — are **reference-app patterns**, not package exports.
+> patterns referenced below (`SetPageTitle`, the sidebar, and the `AuthCard*`
+> auth screens) are **reference-app patterns**, not package exports.
 > The breadcrumb *trail-building logic* (`crumbsFor` + `nav-config` +
 > `route-meta`) is also a reference-app pattern: the package exports the
 > presentational `Breadcrumbs` component; the app derives the trail from the
@@ -49,7 +49,7 @@ When several approaches would work, pick the one that aligns best with VUI.
 
 # Think Before You Build
 
-Before you create anything, search for what already exists — a VUI component, a page pattern, a layout, a variant, or a utility. Never duplicate functionality VUI already provides.
+Before you create anything, search for what already exists: a VUI component, a page pattern, a layout, a variant, or a utility. Never duplicate functionality VUI already provides.
 
 ---
 
@@ -66,7 +66,7 @@ npx @viliha/vui-ui init          # interactive decision tree
 
 Files land in the consumer's repo (they own them). Questions:
 0. **Next.js or Turborepo?** (`--nextjs` / `--turbo` + `--dir <path>`, default
-   `apps/web` — turbo scaffolds into that app directory)
+   `apps/web`; turbo scaffolds into that app directory)
 1. **Fresh project?** (`--fresh` / `--existing`)
 2. **Pre-built theme?** (`--prebuilt` = shell + demo pages / `--theme-only` = just
    the theme wiring you configure)
@@ -78,8 +78,8 @@ dependencies** with the package manager it detects from the lockfile (npm / pnpm
 
 - **fresh + prebuilt** → full runnable app (config + shell + demo).
 - **fresh + theme-only** → just `globals.css` + `next.config` wiring; build your own.
-- **existing + prebuilt** → shell + demo added; config **never** overwritten —
-  prints the merge steps (`transpilePackages`, the `theme.css` import, the `@/*`
+- **existing + prebuilt** → shell + demo added; config **never** overwritten, and
+  it prints the merge steps (`transpilePackages`, the `theme.css` import, the `@/*`
   alias, `import "./globals.css"`).
 - **existing + theme-only** → nothing copied; prints the wiring steps.
 
@@ -88,7 +88,7 @@ Other flags: `--yes` / `--force` / `--dry-run`. If you only need the components,
 
 ### Inside a Turborepo / monorepo
 
-**Never scaffold into the repo root** — a monorepo root has no `app/` and no Next
+**Never scaffold into the repo root**; a monorepo root has no `app/` and no Next
 app. Target the specific application, e.g. `apps/web`. Two equivalent ways:
 
 ```bash
@@ -115,14 +115,14 @@ dev`. The theme import, `transpilePackages`, and the `@/*` alias all belong in
 
 ### End-to-end walkthroughs
 
-- **New standalone app** — `npx create-next-app@latest my-app --ts --tailwind
+- **New standalone app**: `npx create-next-app@latest my-app --ts --tailwind
   --app --no-src-dir --use-npm`, then `cd my-app && npx @viliha/vui-ui init`
   (fresh + prebuilt). It scaffolds config + shell + demo, installs deps, and you
   run `npm run dev` → `/dashboard`.
-- **New app in a monorepo** — scaffold your app under `apps/<name>` (e.g. with
+- **New app in a monorepo**: scaffold your app under `apps/<name>` (e.g. with
   `create-next-app`), then from that app dir run `npx @viliha/vui-ui init` (or
   `--turbo --dir apps/<name>` from the root) and install deps in that app.
-- **Existing app** — run `npx @viliha/vui-ui init --existing`. It never
+- **Existing app**: run `npx @viliha/vui-ui init --existing`. It never
   overwrites your config; wire up the four things it prints (`transpilePackages`,
   the `theme.css` import, the `@/*` alias, `import "./globals.css"`). Prefer only
   the components? Use `--theme-only` (copies nothing) and follow the setup below.
@@ -152,7 +152,7 @@ Import the theme once. No extra transpilation needed.
 
 # Upgrading
 
-When you bump `@viliha/vui-ui`, follow these steps — the package version and the
+When you bump `@viliha/vui-ui`, follow these steps. The package version and the
 scaffolded files in the repo are two separate things.
 
 1. **Read the [CHANGELOG](./CHANGELOG.md) for the target version.** Note anything
@@ -165,7 +165,7 @@ scaffolded files in the repo are two separate things.
    In a monorepo, install in the specific app (or with a workspace filter, e.g.
    `pnpm --filter <app> up @viliha/vui-ui`), never at the repo root.
 3. **No rebuild needed.** The package ships TypeScript source, so there's no
-   build/dts step — just restart the dev server. If a new version adds a peer
+   build/dts step; just restart the dev server. If a new version adds a peer
    dependency, install it (the CHANGELOG and the "Module not found" error name it).
 4. **Scaffolded files are yours.** `init` copies the shell and demo pages into
    the repo once; upgrading the package does **not** touch them. To pull
@@ -181,7 +181,7 @@ scaffolded files in the repo are two separate things.
 
 # Design Tokens
 
-VUI is entirely token-driven. Never hardcode colors, spacing, radius, typography, shadows, or borders — reach for the semantic design token instead. For example: `--button-primary`, `--button-primary-hover`, `--background`, `--foreground`, `--border`, `--ring`, `--chart-1`, `--sidebar-primary`.
+VUI is entirely token-driven. Never hardcode colors, spacing, radius, typography, shadows, or borders; reach for the semantic design token instead. For example: `--button-primary`, `--button-primary-hover`, `--background`, `--foreground`, `--border`, `--ring`, `--chart-1`, `--sidebar-primary`.
 
 Avoid arbitrary values unless there's truly no token for the job.
 
@@ -239,11 +239,11 @@ Group content into bordered cards, and avoid deeply nested layouts. Reach for sp
 
 # Navigation
 
-Navigate with the three provided pieces — breadcrumbs, sidebar, and top navigation. Don't build a custom navigation system unless the project explicitly demands one.
+Navigate with the three provided pieces: breadcrumbs, sidebar, and top navigation. Don't build a custom navigation system unless the project explicitly demands one.
 
 ## Breadcrumbs
 
-One trail, **derived from the route — never hand-written per page.**
+One trail, **derived from the route, never hand-written per page.**
 
 - Render with the shared `Breadcrumbs` component (`@viliha/vui-ui/breadcrumbs`):
   last crumb is the current page (bold, non-interactive), earlier crumbs are
@@ -251,7 +251,7 @@ One trail, **derived from the route — never hand-written per page.**
 - Build the trail from the URL against a single nav config (copy `crumbsFor` +
   `nav-config` + `route-meta` from the reference app). Root it at **Home**
   (your dashboard route). A section/group parent has no page of its own, so its
-  crumb links to its **first child** — clicking a section lands on that
+  crumb links to its **first child**; clicking a section lands on that
   section's first page.
 - Ship **one** landing page, labeled "Home". Don't split "Home" and "Dashboard"
   into two routes.
@@ -261,17 +261,17 @@ To reorder or rename, edit the nav config; the trail follows automatically.
 ## Sidebar: sections & collapsible groups
 
 The sidebar is driven by one `NAV` config (copy `nav-config.ts`). There are
-**two grouping shapes — use them, don't invent a third:**
+**two grouping shapes: use them, don't invent a third:**
 
-- **Section** (`NavSection`, `{ title?, items }`) — a top-level band with an
+- **Section** (`NavSection`, `{ title?, items }`): a top-level band with an
   optional `title` heading. Items are **always visible** (no collapse). Use it to
   cluster related pages under a label (e.g. *Records*, *System*). The first
   section usually has no title.
-- **Collapsible group** (`NavGroup`, an entry with `children`) — a parent row with
+- **Collapsible group** (`NavGroup`, an entry with `children`): a parent row with
   a chevron that **hides/unhides** its nested links; it auto-opens when a child is
   the active route. Use it for a set of sub-pages under one parent (e.g. *Auth*,
   *CRM*, *System*) to keep the sidebar short. A group parent has no page of its
-  own — its breadcrumb points at its first child.
+  own; its breadcrumb points at its first child.
 
 ```ts
 export const NAV: NavSection[] = [
@@ -288,14 +288,14 @@ export const NAV: NavSection[] = [
 ```
 
 When adding a page, always add it to `NAV` and mirror its color in
-`route-meta.ts` — the sidebar, breadcrumbs, and tabs all derive from these.
+`route-meta.ts`; the sidebar, breadcrumbs, and tabs all derive from these.
 
 ## Open tabs (keep-alive)
 
 Enterprise apps keep several pages open at once. The reference app ships a
-browser-style **tab strip** under the top bar — a reference-app pattern (copy
+browser-style **tab strip** under the top bar, a reference-app pattern (copy
 `open-tabs.tsx`), not a package export. **This is a first-class feature; wire it
-in — a fresh install won't have it.**
+in, because a fresh install won't have it.**
 
 It is **keep-alive**: every opened page stays mounted (inactive ones hidden), so
 switching is instant (no remount/flash) and each page keeps its live state
@@ -309,7 +309,7 @@ switching is instant (no remount/flash) and each page keeps its live state
 </OpenTabsProvider>
 ```
 
-- Labels/icons/colors derive from `nav-config.ts` + `route-meta.ts` — no per-tab wiring.
+- Labels/icons/colors derive from `nav-config.ts` + `route-meta.ts`, with no per-tab wiring.
 - The list persists in `sessionStorage`, capped by `NEXT_PUBLIC_MAX_TABS`
   (default 5; oldest FIFO-evicted with a warning).
 - Tabs are drag-reorderable and right-click-taggable with one of seven colors.
@@ -319,27 +319,27 @@ switching is instant (no remount/flash) and each page keeps its live state
 
 Keep-alive relies on a static-export (all-client) shell. If your app renders
 server components per route, either adopt the demo's static-export shell or fall
-back to a plain navigation-tab model (router push per tab) — the strip,
+back to a plain navigation-tab model (router push per tab); the strip,
 persistence, and nav-config wiring stay identical.
 
 ---
 
 # Forms
 
-Build forms with VUI and shadcn/ui together, reaching for shadcn Form, React Hook Form, and Zod. Every form handles the full lifecycle — validation, loading, success, error, disabled, and keyboard navigation. Never use a placeholder in place of a label.
+Build forms with VUI and shadcn/ui together, reaching for shadcn Form, React Hook Form, and Zod. Every form handles the full lifecycle: validation, loading, success, error, disabled, and keyboard navigation. Never use a placeholder in place of a label.
 
 ---
 
 # Tables
 
-Never hand-build an HTML table — always use `RecordView`. Configure columns through its field props (`editable`, `required`, `copyable`, `options`, `render`), and let `RecordView` own the rest: sorting, filtering, pagination, bulk actions, and import/export.
+Never hand-build an HTML table; always use `RecordView`. Configure columns through its field props (`editable`, `required`, `copyable`, `options`, `render`), and let `RecordView` own the rest: sorting, filtering, pagination, bulk actions, and import/export.
 
 ## Add / edit form
 
 The buffered add/edit form renders in one of two layouts:
 
-- **Slide-over panel** — the default; nothing to configure.
-- **Full-page form** — set `formMode="page"` (with `formColumns={1 | 2}`). Add
+- **Slide-over panel**: the default; nothing to configure.
+- **Full-page form**: set `formMode="page"` (with `formColumns={1 | 2}`). Add
   `formDescription` and a per-field `description` to show an AWS-style help
   panel beside the form.
 
@@ -352,7 +352,7 @@ shared `@viliha/vui-ui/breadcrumbs` component.
 
 # Charts
 
-Build every chart with `ChartContainer` plus Recharts. Never hardcode chart colors — map them through the chart tokens.
+Build every chart with `ChartContainer` plus Recharts. Never hardcode chart colors; map them through the chart tokens.
 
 ---
 
@@ -361,10 +361,10 @@ Build every chart with `ChartContainer` plus Recharts. Never hardcode chart colo
 The auth screens are a **demo pattern in the reference app**, not exports of the
 `@viliha/vui-ui` package. `AuthCard`, `AuthCardHeader`, `AuthCardBody`,
 `AuthCardFooter` and `AuthCardAside` live in
-`apps/backoffice/app/_components/auth.tsx` — **copy and adapt them** into your
+`apps/backoffice/app/_components/auth.tsx`; **copy and adapt them** into your
 app (they are built from published primitives: `Button`, `Input`, tokens).
 
-Do not `import … from "@viliha/vui-ui/auth"` — no such entry point exists.
+Do not `import … from "@viliha/vui-ui/auth"`; no such entry point exists.
 
 Wrap the forms in semantic HTML.
 
@@ -374,7 +374,7 @@ Wrap the forms in semantic HTML.
 
 VUI and shadcn/ui complement each other, so split the work along their strengths. Reach for shadcn for forms, dialogs, sheets, tabs, popovers, and accordions; reach for VUI for layouts, `RecordView`, enterprise components, charts, and navigation patterns.
 
-VUI owns the design tokens — delete any duplicate token definitions shadcn generates.
+VUI owns the design tokens, so delete any duplicate token definitions shadcn generates.
 
 ---
 
@@ -398,7 +398,7 @@ Default to Server Components, streaming, lazy loading, and dynamic imports. Avoi
 
 # UX Standards
 
-Every feature communicates its current state — loading, success, empty, and error. Give long-running actions visible progress, and never leave users wondering what happened.
+Every feature communicates its current state: loading, success, empty, and error. Give long-running actions visible progress, and never leave users wondering what happened.
 
 ---
 
@@ -436,7 +436,7 @@ Panel
 
 # AI Development Rules
 
-Before you write code, reuse what's already there — components, layouts, utilities, and variants — and extend an existing component before creating a new one. Never duplicate code or styling. Keep APIs simple and components focused.
+Before you write code, reuse what's already there (components, layouts, utilities, and variants), and extend an existing component before creating a new one. Never duplicate code or styling. Keep APIs simple and components focused.
 
 ---
 

package/CHANGELOG.md

@@ -7,13 +7,41 @@ backward-compatible features, **major** for breaking changes.
 
 To upgrade, see [Upgrading](./AGENT.md#upgrading) in the agent guide.
 
+## 1.6.1 — 2026-07-25
+
+### Added
+
+- `NEXT_PUBLIC_APP_URL` sets the deploy origin (`SITE.url`), so `metadataBase`,
+  canonical URLs, and Open Graph URLs resolve against your domain instead of the
+  hard-coded demo host. Falls back to the demo URL when unset. Completes the
+  env-driven brand set (`APP_NAME` / `APP_TAGLINE` / `APP_DESCRIPTION` / `APP_URL`).
+
+## 1.6.0 — 2026-07-25
+
+### Changed
+
+- Documentation polish: package-manager commands in the docs now use tabs
+  (npm / pnpm / yarn / bun), and the prose across the README, `AGENT.md`, and the
+  docs site was cleaned of em-dashes for a more natural read.
+
+### Added
+
+- **Runtime branding via `BrandProvider` / `useBrand()`** (in the scaffold) — for
+  white-label / multi-tenant apps that get their branding from an API. Env vars
+  are the defaults; override them live from a `NEXT_PUBLIC_BRAND_URL` JSON
+  endpoint, a `<BrandProvider initial={…}>` seed, or `useBrand().setBrand(…)`.
+  The name, tagline, description, logo, and the browser-tab title all update at
+  runtime — no rebuild. Also routes the last hard-coded name spots (onboarding /
+  register-business headers, the signin aside) through the runtime brand.
+
 ## 1.5.4 — 2026-07-24
 
 ### Added
 
-- `NEXT_PUBLIC_APP_NAME` env var (in the scaffold) renames the app — the sidebar,
-  wordmark, auth screens, and page titles now read from one place (`SITE.name`)
-  instead of a hard-coded "Vui Starter".
+- `NEXT_PUBLIC_APP_NAME` renames the app — the sidebar, wordmark, auth screens,
+  and browser-tab metadata read from one place (`SITE.name`) instead of a
+  hard-coded "Vui Starter". `NEXT_PUBLIC_APP_TAGLINE` and
+  `NEXT_PUBLIC_APP_DESCRIPTION` complete the tab-title/meta rebrand.
 
 ### Fixed
 

package/README.md

@@ -52,14 +52,14 @@ npx @viliha/vui-ui init
 It's **interactive** and walks through a short decision tree:
 
 1. **Fresh project?** (fresh vs. existing)
-2. **Pre-built theme?** — the full shell plus demo pages, or just the theme wiring
+2. **Pre-built theme?** The full shell plus demo pages, or just the theme wiring
    for you to build on.
 
 Everything it generates is copied into *your* repo, so you own and edit it.
 
 | | **Pre-built** (shell + demo) | **Theme-only** (you configure) |
 | --- | --- | --- |
-| **Fresh** | full runnable app: config + shell + demo pages | just the theme wiring (`globals.css`, `next.config`) — build your own pages |
+| **Fresh** | full runnable app: config + shell + demo pages | just the theme wiring (`globals.css`, `next.config`). Build your own pages |
 | **Existing** | shell + demo added; your config is **never** overwritten (prints merge steps) | nothing copied; prints the wiring steps |
 
 Before that, it asks whether this is a standalone **Next.js** app or a
@@ -83,8 +83,8 @@ from your lockfile (npm, pnpm, yarn, or bun). It prompts before doing so; pass
 
 ### Fresh + pre-built (recommended for new apps)
 
-Start from a `create-next-app` base **without `--src-dir`** — the scaffold expects
-a root `app/` with `@/*` → `./*` — then run `init`. It scaffolds the app, installs
+Start from a `create-next-app` base **without `--src-dir`** (the scaffold expects
+a root `app/` with `@/*` → `./*`), then run `init`. It scaffolds the app, installs
 the dependencies, and leaves you ready to run `dev`. Any package manager works:
 
 ```bash
@@ -111,8 +111,8 @@ dependencies. The demo then runs out of the box at `/dashboard`.
 
 ### Turborepo / monorepo
 
-Scaffold **inside the target app** (e.g. `apps/web`), never at the repo root —
-the root has no `app/` and no Next.js app. Run `init` from the app, or name it
+Scaffold **inside the target app** (e.g. `apps/web`), never at the repo root; the
+root has no `app/` and no Next.js app. Run `init` from the app, or name it
 from the root with `--dir`:
 
 ```bash
@@ -124,29 +124,29 @@ npx @viliha/vui-ui init --turbo --dir apps/web
 ```
 
 In monorepo mode `init` does **not** auto-install (installs are
-workspace-specific), so add the deps to that app afterward — `cd apps/web && pnpm
+workspace-specific), so add the deps to that app afterward: `cd apps/web && pnpm
 add @viliha/vui-ui …`, or from the root `pnpm --filter web add @viliha/vui-ui …`.
 The `transpilePackages` entry, the `theme.css` import, and the `@/*` alias all
 belong to **that app**, not the root.
 
-### ⚠️ Existing project — read this first
+### ⚠️ Existing project: read this first
 
 Adding VUI to an app you already have takes a little care. **`init --existing`
 never overwrites your config.** Choose pre-built to add the shell and pages under
 `app/(app)/` and `app/_components/`, or theme-only to copy nothing. Either way, it
 prints the four things you need to wire up:
 
-1. **`next.config`** — add `transpilePackages: ["@viliha/vui-ui"]`.
+1. **`next.config`**: add `transpilePackages: ["@viliha/vui-ui"]`.
    (Optional, for the open-tabs *keep-alive*: `output: "export"`,
    `images: { unoptimized: true }`, `trailingSlash: true`.)
-2. **`app/globals.css`** — add:
+2. **`app/globals.css`**: add:
    ```css
    @import "tailwindcss";
    @import "@viliha/vui-ui/theme.css";
    ```
-3. **`tsconfig.json`** — the scaffold imports via `@/*`; map it to your root:
+3. **`tsconfig.json`**: the scaffold imports via `@/*`; map it to your root:
    `"compilerOptions": { "paths": { "@/*": ["./*"] } }`.
-4. **Root `app/layout.tsx`** — `import "./globals.css"` (and mount fonts to match
+4. **Root `app/layout.tsx`**: `import "./globals.css"` (and mount fonts to match
    the demo's look).
 
 Run **`npx @viliha/vui-ui init --existing --prebuilt --dry-run`** first to preview
@@ -214,15 +214,15 @@ See the [Data table docs](https://vui.viliha.com/docs/data-table) for the detail
 The reference app composes these primitives into the conventions documented at
 [vui.viliha.com/docs/layout](https://vui.viliha.com/docs/layout):
 
-- **Five page types** — data table, record form (Add / Edit / View), dashboard,
+- **Five page types**: data table, record form (Add / Edit / View), dashboard,
   settings, and kanban board.
-- **Command palette** — Quick actions (`⌘K`, navigate pages) and Global search
+- **Command palette**: Quick actions (`⌘K`, navigate pages) and Global search
   (`⌘⌥K`, find records), both built on the exported `CommandPalette`.
-- **Open tabs** — a browser-style strip of opened pages under the top bar
+- **Open tabs**: a browser-style strip of opened pages under the top bar
   (⌘-click a nav item for a background tab), persisted across reloads.
-- **Multi-step wizard** — the exported `Steps` indicator + your step state for
+- **Multi-step wizard**: the exported `Steps` indicator + your step state for
   guided flows (see the `/register-business` demo).
-- **Breadcrumbs** — the exported `Breadcrumbs` component fed a route-derived
+- **Breadcrumbs**: the exported `Breadcrumbs` component fed a route-derived
   trail.
 
 Copy them from the
@@ -257,7 +257,7 @@ wrapper) · `checkbox` · `command-palette` (⌘K launcher) · `dialog` ·
 
 ## Theming
 
-Every design decision lives in `@viliha/vui-ui/theme.css` as CSS variables —
+Every design decision lives in `@viliha/vui-ui/theme.css` as CSS variables:
 colors, radius, typography, and dark mode. Override any token **after** the import
 to rebrand the entire system:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viliha/vui-ui",
-  "version": "1.5.4",
+  "version": "1.6.1",
   "description": "Vui UI — a clean, token-driven React admin/CRM component library built on Tailwind CSS v4, shadcn-style patterns, and Radix Icons. Ships as TypeScript source (Just-in-Time), compiled by the consuming app.",
   "license": "MIT",
   "author": "Suman Bonakurthi",

package/template/.env.example

@@ -2,8 +2,21 @@
 # All are optional; defaults are used when unset. NEXT_PUBLIC_ vars are read at
 # build time and inlined into the exported site.
 
-# App / brand name shown in the sidebar, wordmark, auth screens, and page titles.
+# App / brand identity — shown in the sidebar, wordmark, auth screens, and the
+# browser-tab metadata. The tab title is "<APP_NAME> — <APP_TAGLINE>".
 NEXT_PUBLIC_APP_NAME="Vui Starter"
+NEXT_PUBLIC_APP_TAGLINE="React Admin & CRM Design System"
+NEXT_PUBLIC_APP_DESCRIPTION="Your app description for search engines and social cards."
+# Deploy origin (no trailing slash) — drives metadataBase, canonical + OG URLs.
+# Set this to your domain in production.
+NEXT_PUBLIC_APP_URL="https://vui.viliha.com"
+
+# Runtime branding (multi-tenant / white-label). Point this at a JSON endpoint
+# returning any of { name, tagline, description, logoUrl, company, companyUrl };
+# BrandProvider fetches it on load and overrides the values above — including the
+# tab title — live, no rebuild. (Or seed <BrandProvider initial={…}> from a
+# loader, or call useBrand().setBrand(…) once your API responds.)
+# NEXT_PUBLIC_BRAND_URL="https://api.example.com/branding"
 
 NEXT_PUBLIC_COMPANY_NAME="VILIHA PTE. LTD."
 # Optional — links the company name in the footer:

package/template/app/_components/app-sidebar.tsx

@@ -13,7 +13,7 @@ import {
 } from "@radix-ui/react-icons";
 
 import { cn } from "@/lib/utils";
-import { SITE } from "@/lib/seo";
+import { useBrand } from "./brand";
 import { Menu as MenuPanel } from "@viliha/vui-ui/menu";
 import { Logo } from "./logo";
 import { QuickActionsLauncher } from "./quick-actions";
@@ -102,6 +102,7 @@ function SidebarBody({
   headerAction?: React.ReactNode;
 }) {
   const pathname = usePathname();
+  const { brand } = useBrand();
   const [openGroups, setOpenGroups] = React.useState<Set<string>>(() => {
     const open = new Set<string>();
     for (const section of NAV) {
@@ -370,13 +371,13 @@ function SidebarBody({
             collapsed ? "w-9 shrink-0 justify-center px-0" : "flex-1",
           )}
           aria-label="Switch workspace"
-          title={collapsed ? SITE.name : undefined}
+          title={collapsed ? brand.name : undefined}
         >
           <Logo variant="mark" className="h-6 w-6 shrink-0" />
           {!collapsed && (
             <>
               <span className="min-w-0 flex-1 truncate text-lg font-bold tracking-tight text-foreground">
-                {SITE.name}
+                {brand.name}
               </span>
               <ChevronsUpDown className="size-4 shrink-0 text-muted-foreground" />
             </>

package/template/app/_components/brand.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import * as React from "react";
+import { usePathname } from "next/navigation";
+
+import { SITE } from "@/lib/seo";
+
+/**
+ * Runtime brand configuration.
+ *
+ * The `NEXT_PUBLIC_*` env vars (see lib/seo.ts) are build-time DEFAULTS. Some
+ * apps — white-label / multi-tenant — need branding at RUNTIME from an API. This
+ * provider seeds from the env defaults, then lets you override them live:
+ *
+ *  - pass `initial` (e.g. from a server/loader response), and/or
+ *  - set `NEXT_PUBLIC_BRAND_URL` (or the `configUrl` prop) to a JSON endpoint the
+ *    provider fetches on mount, and/or
+ *  - call `useBrand().setBrand(patch)` from anywhere once your API responds.
+ *
+ * It also keeps the browser-tab title in sync (the app is a static export, so
+ * the server-rendered `<title>` is the env default until the client updates it).
+ */
+export type Brand = {
+  name: string;
+  tagline: string;
+  description: string;
+  /** Overrides NEXT_PUBLIC_LOGO_URL at runtime; unset → the built-in mark. */
+  logoUrl?: string;
+  company: string;
+  companyUrl: string;
+};
+
+const DEFAULT_BRAND: Brand = {
+  name: SITE.name,
+  tagline: SITE.tagline,
+  description: SITE.description,
+  logoUrl: process.env.NEXT_PUBLIC_LOGO_URL || undefined,
+  company: SITE.company,
+  companyUrl: SITE.companyUrl,
+};
+
+type BrandContextValue = {
+  brand: Brand;
+  /** Merge a partial update — typically the JSON from your branding API. */
+  setBrand: (patch: Partial<Brand>) => void;
+};
+
+const BrandContext = React.createContext<BrandContextValue | null>(null);
+
+export function BrandProvider({
+  children,
+  initial,
+  configUrl,
+}: {
+  children: React.ReactNode;
+  initial?: Partial<Brand>;
+  configUrl?: string;
+}) {
+  const [brand, setBrandState] = React.useState<Brand>({
+    ...DEFAULT_BRAND,
+    ...initial,
+  });
+  const setBrand = React.useCallback(
+    (patch: Partial<Brand>) => setBrandState((b) => ({ ...b, ...patch })),
+    [],
+  );
+
+  // Fetch runtime branding from an API (multi-tenant / white-label). Only the
+  // keys present in the response override the defaults; failures keep the
+  // defaults so the app never renders unbranded.
+  const url = configUrl ?? process.env.NEXT_PUBLIC_BRAND_URL;
+  React.useEffect(() => {
+    if (!url) return;
+    let alive = true;
+    fetch(url)
+      .then((r) => (r.ok ? (r.json() as Promise<Partial<Brand>>) : null))
+      .then((data) => {
+        if (alive && data) setBrand(data);
+      })
+      .catch(() => {
+        // network/API unavailable — keep the env defaults (deliberate no-op).
+      });
+    return () => {
+      alive = false;
+    };
+  }, [url, setBrand]);
+
+  // Keep the tab title branded. Next bakes/sets per-route titles that contain
+  // the default name (and, on the home page, the default tagline); swap those
+  // for the active brand after each navigation.
+  const pathname = usePathname();
+  React.useEffect(() => {
+    if (
+      brand.name === DEFAULT_BRAND.name &&
+      brand.tagline === DEFAULT_BRAND.tagline
+    ) {
+      return; // nothing overridden — leave Next's titles as-is
+    }
+    const id = requestAnimationFrame(() => {
+      document.title = document.title
+        .split(DEFAULT_BRAND.name)
+        .join(brand.name)
+        .split(DEFAULT_BRAND.tagline)
+        .join(brand.tagline);
+    });
+    return () => cancelAnimationFrame(id);
+  }, [pathname, brand.name, brand.tagline]);
+
+  return (
+    <BrandContext.Provider value={{ brand, setBrand }}>
+      {children}
+    </BrandContext.Provider>
+  );
+}
+
+/** Read the active brand + `setBrand`. Falls back to the env defaults if no
+ *  provider is mounted, so components work even outside a BrandProvider. */
+export function useBrand(): BrandContextValue {
+  return (
+    React.useContext(BrandContext) ?? {
+      brand: DEFAULT_BRAND,
+      setBrand: () => {},
+    }
+  );
+}
+
+/** The active brand name as text — drop it wherever the app name is shown. */
+export function BrandName() {
+  return <>{useBrand().brand.name}</>;
+}

package/template/app/_components/logo.tsx

@@ -1,7 +1,9 @@
+"use client";
+
 import Image from "next/image";
 
 import { cn } from "@/lib/utils";
-import { SITE } from "@/lib/seo";
+import { useBrand } from "./brand";
 
 type LogoProps = {
   /** Kept for call-site compatibility; the mark is the same either way. */
@@ -9,19 +11,18 @@ type LogoProps = {
   className?: string;
 };
 
-/** Optional custom logo: drop an image in /public and set NEXT_PUBLIC_LOGO_URL
- *  (e.g. "/logo.svg"). Unset falls back to the built-in mark below. */
-const LOGO_URL = process.env.NEXT_PUBLIC_LOGO_URL;
-
 /**
- * App logo — your image via NEXT_PUBLIC_LOGO_URL, else a self-contained rounded
- * blue badge with a stylised "V". Scales with the `className` size (default 24px).
+ * App logo. Uses the runtime brand's `logoUrl` (from an API or
+ * NEXT_PUBLIC_LOGO_URL, via BrandProvider); when unset, falls back to a
+ * self-contained rounded blue badge with a stylised "V". Scales with the
+ * `className` size (default 24px).
  */
 export function Logo({ className }: LogoProps) {
-  if (LOGO_URL) {
+  const { brand } = useBrand();
+  if (brand.logoUrl) {
     return (
       <Image
-        src={LOGO_URL}
+        src={brand.logoUrl}
         alt="Logo"
         width={24}
         height={24}
@@ -33,7 +34,7 @@ export function Logo({ className }: LogoProps) {
     <svg
       viewBox="0 0 24 24"
       role="img"
-      aria-label={SITE.name}
+      aria-label={brand.name}
       className={cn("h-6 w-6", className)}
     >
       <rect width="24" height="24" rx="6" fill="var(--brand-indigo)" />

package/template/app/_components/wordmark.tsx

@@ -1,7 +1,9 @@
+"use client";
+
 import Link from "next/link";
 
 import { cn } from "@/lib/utils";
-import { SITE } from "@/lib/seo";
+import { useBrand } from "./brand";
 import { Logo } from "./logo";
 
 /**
@@ -21,6 +23,7 @@ export function Wordmark({
   logoClassName?: string;
   textClassName?: string;
 }) {
+  const { brand } = useBrand();
   const content = (
     <>
       <Logo className={cn("h-6 w-6 shrink-0", logoClassName)} />
@@ -30,14 +33,14 @@ export function Wordmark({
           textClassName,
         )}
       >
-        {SITE.name}
+        {brand.name}
       </span>
     </>
   );
   const classes = cn("flex items-center gap-2", className);
 
   return href ? (
-    <Link href={href} aria-label={SITE.name} className={classes}>
+    <Link href={href} aria-label={brand.name} className={classes}>
       {content}
     </Link>
   ) : (

package/template/app/auth/signin/page.tsx

@@ -13,6 +13,7 @@ import {
 
 import { Button } from "@viliha/vui-ui/button";
 import { Input } from "@viliha/vui-ui/input";
+import { BrandName } from "@/app/_components/brand";
 import {
   AuthCard,
   AuthCardAside,
@@ -212,7 +213,7 @@ export default function SignInPage() {
             Email me a magic link
           </Button>
           <AuthCardAside>
-            New to Vui Starter?{" "}
+            New to <BrandName />?{" "}
             <Link href="/auth/signup" className="font-medium text-primary hover:underline">
               Create an account
             </Link>

package/template/app/layout.tsx

@@ -3,6 +3,7 @@ import { Inter, JetBrains_Mono } from "next/font/google";
 
 import "./globals.css";
 import { themeInitScript } from "./_components/theme-toggle";
+import { BrandProvider } from "./_components/brand";
 import { SITE } from "@/lib/seo";
 
 const inter = Inter({
@@ -96,7 +97,7 @@ export default function RootLayout({
       <body
         className={`${inter.variable} ${jetbrainsMono.variable} font-sans antialiased`}
       >
-        {children}
+        <BrandProvider>{children}</BrandProvider>
       </body>
     </html>
   );

package/template/app/onboarding/layout.tsx

@@ -2,6 +2,7 @@ import type { Metadata } from "next";
 
 import { Logo } from "@/app/_components/logo";
 import { ThemeToggle } from "@/app/_components/theme-toggle";
+import { BrandName } from "@/app/_components/brand";
 
 // Onboarding is a post-signup flow — keep it out of the index.
 export const metadata: Metadata = { robots: { index: false, follow: false } };
@@ -17,7 +18,7 @@ export default function OnboardingLayout({
         <div className="flex items-center gap-2">
           <Logo className="h-7 w-7" />
           <span className="bg-gradient-to-r from-brand-indigo to-brand-violet bg-clip-text text-sm font-bold tracking-tight text-transparent">
-            Vui Starter
+            <BrandName />
           </span>
         </div>
         <div className="flex items-center gap-3 text-muted-foreground">

package/template/app/register-business/layout.tsx

@@ -2,6 +2,7 @@ import type { Metadata } from "next";
 
 import { Logo } from "@/app/_components/logo";
 import { ThemeToggle } from "@/app/_components/theme-toggle";
+import { BrandName } from "@/app/_components/brand";
 
 export const metadata: Metadata = {
   title: "Register your business",
@@ -19,7 +20,7 @@ export default function RegisterBusinessLayout({
         <div className="flex items-center gap-2">
           <Logo className="h-7 w-7" />
           <span className="bg-gradient-to-r from-brand-indigo to-brand-violet bg-clip-text text-sm font-bold tracking-tight text-transparent">
-            Vui Starter
+            <BrandName />
           </span>
         </div>
         <ThemeToggle />

package/template/lib/seo.ts

@@ -3,12 +3,17 @@ import type { Metadata } from "next";
 /** Single source of truth for site-wide SEO. Deployed as a static export to a
  * custom domain (see ../CNAME), so URLs are absolute against SITE.url. */
 export const SITE = {
-  // App/brand name shown in the sidebar, wordmark, auth screens, and page
-  // titles. Override per deployment via env (NEXT_PUBLIC_ = inlined at build).
+  // App/brand identity shown in the sidebar, wordmark, auth screens, and the
+  // browser-tab metadata (title/description). Override per deployment via env
+  // (NEXT_PUBLIC_ = inlined at build). The tab title is `${name} — ${tagline}`.
   name: process.env.NEXT_PUBLIC_APP_NAME ?? "Vui Starter",
-  tagline: "React Admin & CRM Design System",
-  url: "https://vui.viliha.com",
+  tagline:
+    process.env.NEXT_PUBLIC_APP_TAGLINE ?? "React Admin & CRM Design System",
+  // Deploy origin — drives metadataBase, canonical URLs, and OG image URLs.
+  // Set NEXT_PUBLIC_APP_URL to your domain (no trailing slash) per deployment.
+  url: process.env.NEXT_PUBLIC_APP_URL ?? "https://vui.viliha.com",
   description:
+    process.env.NEXT_PUBLIC_APP_DESCRIPTION ??
     "Vui Starter is a free, open-source React admin & CRM design system — a token-driven component library (@viliha/vui-ui) plus a full backoffice demo.",
   ogImage: "/brand/pulse-wordmark.png",
   author: "Suman Bonakurthi",