@bndynet/vue-site 1.4.1 → 1.8.0

package/README.md

@@ -38,6 +38,7 @@ You can also create the configuration manually:
 import { defineConfig } from '@bndynet/vue-site'
 
 export default defineConfig({
+  name: 'My Project',
   title: 'My Project',
   favicon: '/favicon.ico',
   nav: [
@@ -100,10 +101,11 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 
 | Property | Description |
 |----------|-------------|
-| `title` | Site title (sidebar + tab). `LocalizedString` |
+| `name` | Brand name shown next to the logo (header + sidebar). `LocalizedString`. Optional — omitted or empty means no brand text is rendered |
+| `title` | Browser tab title. `LocalizedString`. Optional — omitted or empty means the document title is left unchanged |
 | `nav` | `NavItem[]` |
 | `navPosition` | Optional navigation placement: `'top'` forces the top/tiered layout, `'sidebar'` forces the full nav tree into the sidebar. Omit to keep automatic behavior based on nav depth |
-| `defaultPath` | Path the site opens at; `/` and unknown paths redirect here. Must match a registered route (a `nav` item's resolved path or a `pages` entry's `path`). Defaults to the first top-level `nav` item |
+| `defaultPath` | Path the site opens at; `/` and unknown paths redirect here. Must match a registered route (a `nav` item's resolved path or a `pages` entry's `path`). Defaults to the first registered page in navigation order, then the first visible standalone page |
 | `favicon` | Browser tab icon URL. Use a public asset path, remote URL, or imported asset URL |
 | `logo` | Logo URL or imported image |
 | `theme` | See `ThemeConfig` below; set to `false` to disable theming (hides the switcher, forces a fixed `light` palette, no localStorage persistence) |
@@ -117,7 +119,7 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 | `auth` | Central authorization policy (`AuthConfig`) — see [Per-page authorization](#per-page-authorization-auth) |
 | `router` | History mode (`RouterConfig`) — `hash` (default) or HTML5 `web`; see [Router history](#router-history-router) |
 | `packageRepository` | Usually set by CLI from `package.json`; omit when using `createSiteApp` alone |
-| `custom` | Public application-specific values, available from `useSiteConfig().config.custom`; see [Custom client configuration](#custom-client-configuration-custom) |
+| `custom` | Public application-specific values, available from `useSiteConfig().config.custom` in components or `getSiteConfig().custom` elsewhere; see [Custom client configuration](#custom-client-configuration-custom) |
 | `env` | Dev/build options — see below |
 | `bootstrap` | Optional path from site root (e.g. `./bootstrap.ts`) — module loaded once before the Vue app |
 | `configureApp` | Optional `(app) => void \| Promise<void>` after router install, before `mount` (see [Local packages in `configureApp`](#local-packages-in-configureapp)) |
@@ -125,7 +127,7 @@ Add `"dev": "vue-site dev"` (or `vs dev`) in `package.json` scripts if you like.
 ### Custom client configuration (`custom`)
 
 Use `custom` for public, application-specific values that the framework should preserve without
-interpreting. They are available to every component through `useSiteConfig()`:
+interpreting:
 
 ```typescript
 // site.config.ts
@@ -144,6 +146,21 @@ const { config } = useSiteConfig()
 const apiBaseUrl = config.custom?.apiBaseUrl
 ```
 
+Ordinary modules such as `utils.ts` do not have Vue's injection context. Read the active config
+with `getSiteConfig()` instead:
+
+```typescript
+// utils/api.ts
+import { getSiteConfig } from '@bndynet/vue-site'
+
+export function getApiBaseUrl() {
+  return getSiteConfig().custom?.apiBaseUrl
+}
+```
+
+Call `getSiteConfig()` at runtime, after `createSiteApp()` has started. Do not evaluate it at the
+top level of a module imported by `site.config.ts`; the active config has not been registered yet.
+
 Use a different config file when the value changes between builds:
 
 ```typescript
@@ -216,6 +233,20 @@ export default defineConfig({
 })
 ```
 
+### Responsive helpers
+
+Wide content — such as an Element Plus `el-table` or a multi-column `el-form` — can overflow on
+small screens. Wrap it in a `.site-responsive-scroll` container to give it a horizontal scrollbar
+(with momentum scrolling on touch and a visible scrollbar hint) instead of overflowing the page:
+
+```vue
+<template>
+  <div class="site-responsive-scroll">
+    <el-table :data="rows">…</el-table>
+  </div>
+</template>
+```
+
 ### Icon registry
 
 The CLI scans configured Lucide icon names in `nav`, `links`, `i18n.locales`, and `theme.extraThemes`
@@ -250,13 +281,84 @@ Built-in themes are `light`, `dark`, plus the always-on extras `sepia` and `ocea
 | `palettes` | — | Partial overrides for built-in light/dark only |
 | `extraThemes` | — | Extra themes: `id`, `label`, `icon`, optional `basedOn`, `palette`; reuse a built-in id (`sepia`/`ocean`) to override it. Import `builtinThemePalettes` for full defaults |
 
+### Semantic color tokens
+
+Every theme is driven by semantic `--color-*` CSS variables. Shared Element Plus variables are
+mapped to them in `element-plus-theme.css`, so common controls and surfaces follow the active theme.
+Some components also have component-specific variables; those may need additional mapping when
+adding new Element Plus components. Built-in palettes define seed colors and derive related values
+with `color-mix()` / `var()`, so `builtinThemePalettes` may contain CSS expressions rather than
+literal colors.
+
+| Token | Purpose |
+|-------|---------|
+| `--color-primary` | Brand / primary (`--el-color-primary` and its tints) |
+| `--color-primary-contrast` | Text color on filled primary controls; defaults to the theme background |
+| `--color-primary-hover` | Hover color for filled primary controls; derived from primary and text colors |
+| `--color-success` | Success |
+| `--color-warning` | Warning |
+| `--color-danger` | Danger / error (`--el-color-error` reuses it) |
+| `--color-info` | Info |
+| `--color-surface-raised` | Elevated surfaces: popovers, dropdowns, dialogs, masks |
+| `--color-overlay` | Modal / loading overlay |
+
+Define just these base colors in a custom theme; the framework derives Element Plus's
+`light-3/5/7/8/9` and `dark-2` shades with `color-mix()`:
+
+```typescript
+theme: {
+  extraThemes: [
+    {
+      id: 'forest',
+      label: 'Forest',
+      basedOn: 'light',
+      palette: {
+        '--color-primary': '#2f855a',
+        '--color-surface-raised': '#f7faf8',
+      },
+    },
+  ],
+}
+```
+
+If a custom primary/background pair has low contrast, set `--color-primary-contrast` explicitly.
+It is used for text on filled primary buttons, tags, and selected button groups.
+
+### Overriding any token
+
+Every token can be overridden, not just the base colors. Overrides are applied in three levels,
+from lowest to highest precedence:
+
+1. `palettes.light` / `palettes.dark`, or an `extraThemes[].palette` — merged onto the built-in
+   palette for that theme.
+2. `colors` — applied globally after the active palette, so it wins across every theme.
+3. Runtime `document.documentElement.style.setProperty('--color-…', …)`.
+
+Overriding a **seed** color (e.g. `--color-border`) also updates the derived tokens that
+reference it (`--color-sidebar-border`, `--color-code-border`, `--color-table-border`,
+`--color-blockquote-border`). Overriding a **derived** token affects only that token. Prefer
+overriding seeds when the value should adapt across themes.
+
+```typescript
+theme: {
+  colors: {
+    '--color-theme-switch-hover': 'rgba(0, 0, 0, 0.08)',
+  },
+  palettes: {
+    light: {
+      '--color-sidebar-bg': '#f0f2f5',
+    },
+  },
+}
+```
+
 ## Shell actions (`shell.actions`)
 
 Use `shell.actions` to render app-specific Vue components in the active layout's global toolbar.
-In top/tiered navigation they appear at the end of the top header; in sidebar-only navigation they
-appear in the sidebar footer after the built-in links, locale switcher, and theme switcher. This is
-the recommended place for a signed-in user avatar, notification button, help menu, or tenant
-switcher.
+On mobile, they appear at the right side of the mobile header. On desktop, they appear at the end
+of the top header in tiered navigation, or in the sidebar footer after the built-in controls in
+sidebar-only navigation. This is the recommended place for a signed-in user avatar, notification
+button, help menu, or tenant switcher.
 
 ```typescript
 export default defineConfig({
@@ -292,8 +394,8 @@ Set `align` to `'left'`, `'center'`, or `'right'` for sidebar-footer placement;
 ## Internationalization (`i18n`)
 
 Set `i18n` to enable multi-language support. The framework adds a locale switcher to the header,
-resolves every `LocalizedString` field (`title`, `nav[].label`, `footer`, `links[].title`) against
-the active locale, and exposes the current locale via `useLocale()` / `useLocalize()`.
+resolves every `LocalizedString` field (`name`, `title`, `nav[].label`, `footer`, `links[].title`)
+against the active locale, and exposes the current locale via `useLocale()` / `useLocalize()`.
 
 ```typescript
 import { defineConfig } from '@bndynet/vue-site'
@@ -306,7 +408,8 @@ export default defineConfig({
     ],
     defaultLocale: 'en',
   },
-  title: { en: 'My Site', zh: '我的站点' }, // a LocalizedString
+  name: { en: 'My Site', zh: '我的站点' }, // brand text next to the logo
+  title: { en: 'My Site', zh: '我的站点' }, // browser-tab title
   footer: { en: '© 2026', zh: '© 2026 版权所有' },
   nav: [
     { label: { en: 'Home', zh: '首页' }, icon: 'home', page: '../README.md' },
@@ -408,8 +511,8 @@ base file → first entry).
 
 | Property | Default | Description |
 |----------|---------|-------------|
-| `locales` | discovered `locales/*.json` | `{ code, label, icon? }[]` — supported languages, in display order. Optional: derived from the auto-loaded file names (with built-in labels) when omitted. First entry is the fallback |
-| `defaultLocale` | `locales[0].code` | Initial locale when nothing is stored and detection finds no match |
+| `locales` | discovered `locales/*.json` | `{ code, label, icon? }[]` — supported languages, in display order. Optional in CLI mode; without the CLI, codes are derived from `i18n.messages` keys, or from `defaultLocale` / `en` if omitted. First entry is the fallback |
+| `defaultLocale` | first resolved locale, or `en` | Initial locale when nothing is stored and browser detection finds no match |
 | `detectBrowser` | `true` | Detect the initial locale from `navigator.language(s)` on first visit |
 | `storageKey` | `vue-site-locale` | localStorage key for the chosen locale |
 | `messages` | auto-loaded from `locales/<code>.json` | `Record<LocaleCode, Record<string, string>>` — extra/override translations, merged over the auto-loaded files and built-in UI strings |
@@ -424,7 +527,7 @@ no `messages` field) and you don't even have to list the languages.
 ```jsonc
 // locales/en.json — nested groups (recommended), flattened to dotted ids
 {
-  "site": { "title": "My Site" },
+  "site": { "name": "My Site", "title": "My Site" },
   "nav": { "home": "Home", "guide": "Guide" }
 }
 ```
@@ -432,7 +535,7 @@ no `messages` field) and you don't even have to list the languages.
 ```jsonc
 // locales/zh.json
 {
-  "site": { "title": "我的站点" },
+  "site": { "name": "我的站点", "title": "我的站点" },
   "nav": { "home": "首页", "guide": "指南" }
 }
 ```
@@ -454,6 +557,7 @@ export default defineConfig({
     ],
     defaultLocale: 'en',
   },
+  name: tk('site.name'),
   title: tk('site.title'),
   nav: [
     { label: tk('nav.home'), icon: 'home', page: '../README.md' },
@@ -476,9 +580,12 @@ mixed freely — use `tk()` for shared/centrally managed text and an inline map
   relative to the config directory. `code` is the file name (a `LocaleCode` like `en` or `zh-TW`).
 - An explicit `i18n.messages` is still supported and **overrides** auto-loaded keys (per id); an
   explicit `i18n.locales` controls the label/icon/order. Both are optional.
-- Auto-discovery is a **CLI** feature. If you embed the library yourself (calling `createSiteApp`
-  without the `vue-site` CLI), pass `i18n.messages` directly — e.g. build it from JSON with explicit
-  imports (avoid `import.meta.glob` inside `site.config.ts`, which the CLI pre-loads in Node).
+- Auto-discovery of `locales/<code>.json` is a **CLI** feature. If you embed the library yourself
+  (calling `createSiteApp` without the `vue-site` CLI), pass `i18n.messages` directly — e.g. build it
+  from JSON with explicit imports (avoid `import.meta.glob` inside `site.config.ts`, which the CLI
+  pre-loads in Node). When `i18n.locales` is omitted, the library derives locale codes from the
+  `messages` keys and uses those codes as display labels. For localized content without a messages
+  catalog, provide `locales` explicitly so the locale switcher has the intended options and labels.
 
 ### Localizing in your own pages
 
@@ -592,7 +699,7 @@ Notes:
 | Property | Description |
 |----------|-------------|
 | `port` | Dev server port |
-| `outDir` | Build output (relative to site root; default `{folder}-dist`) |
+| `outDir` | Build output (relative to site root; default `dist`) |
 | `customElements` | Tag prefixes for custom elements (e.g. `['chat-', 'i-']`) |
 | `watchPackages` | Local packages — see [env.watchPackages](#envwatchpackages) |
 | `vite` | Vite overrides (not `root`); framework merges aliases, `server.fs.allow`, `build.outDir`, etc. |
@@ -639,11 +746,11 @@ app.mount('#app')
 
 Use a top-level `await` in your entry (or an async IIFE): `createSiteApp` is async and **awaits** `configureApp` when it returns a `Promise`. If you set optional `bootstrap` in config, that module loads before the app is created; if you omit `bootstrap`, that step is skipped.
 
-Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useSiteConfig`, `useLocale`, `useLocalize`, `tk`, `resolveLocalized`, `resolveField`, `resolveMessage`, `mergeCatalog`, `flattenMessages`, `isMessageRef`, `localizedPage`, `builtinMessages`, `themeRefKey`, `localeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteCustomConfig`, `SiteExternalLink`, `ShellConfig`, `ShellAction`, `ShellActionLoader`, `NavItem`, `StandalonePage`, `PageLayout`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`, `I18nConfig`, `LocaleOption`, `LocaleCode`, `LocalizedString`, `IconRegistry`, `MessageRef`, `MessageTree`, `MessageCatalog`, `PageLoader`, `LocalizedPageOptions`.
+Exports: `createSiteApp`, `defineConfig`, `useTheme`, `useMobileViewport`, `useSiteConfig`, `getSiteConfig`, `useLocale`, `useLocalize`, `tk`, `resolveLocalized`, `resolveField`, `resolveMessage`, `mergeCatalog`, `flattenMessages`, `isMessageRef`, `localizedPage`, `builtinMessages`, `themeRefKey`, `localeRefKey`. Types: `SiteConfig`, `SiteEnvConfig`, `SiteViteConfig`, `SiteCustomConfig`, `SiteExternalLink`, `ShellConfig`, `ShellAction`, `ShellActionLoader`, `NavItem`, `StandalonePage`, `PageLayout`, `AuthRule`, `AuthContext`, `AuthConfig`, `RouterConfig`, `ThemeConfig`, `ThemeOption`, `ThemePaletteVars`, `ResolvedNavItem`, `I18nConfig`, `LocaleOption`, `LocaleCode`, `LocalizedString`, `IconRegistry`, `MessageRef`, `MessageTree`, `MessageCatalog`, `PageLoader`, `LocalizedPageOptions`.
 
 ### Theme in Vue pages (`useTheme`)
 
-Import `useTheme` from `@bndynet/vue-site`. It returns a reactive `theme` ref (the active theme id, e.g. `light`, `dark`, or an `extraThemes[].id`) plus `setTheme` and `toggleTheme`. The root layout also sets `document.documentElement` attribute `data-theme` and applies CSS variables, so you can style with `var(--color-*)` without JavaScript.
+Import `useTheme` from `@bndynet/vue-site`. It returns a reactive `theme` ref (the active theme id, e.g. `light`, `dark`, or an `extraThemes[].id`) plus `setTheme` and `toggleTheme`. The root layout also sets `document.documentElement` attribute `data-theme`, applies CSS variables, and updates `color-scheme` so native browser controls and scrollbars use the active theme's light or dark scheme.
 
 The theme ref is **provided** by `createSiteApp()` (same Vue runtime as your app), so `watch(theme, …)` works reliably even when another tool would otherwise load a second copy of `vue` from nested `node_modules`.
 
@@ -666,6 +773,28 @@ watch(theme, (next, prev) => {
 
 `watch` only runs when the theme **changes** after your component is set up (for example after the user clicks the theme control). It does not run on the initial value unless you pass `{ immediate: true }`.
 
+### Responsive viewport state (`useMobileViewport`)
+
+Import `useMobileViewport` when component behavior needs to react to the same mobile breakpoint as
+the site layout. It returns a read-only ref that is `true` at viewport widths of 840 CSS pixels or
+narrower. The layout provides one shared ref, so components do not need to create their own media
+query listeners. For visual-only changes, prefer CSS media queries.
+
+```vue
+<script setup lang="ts">
+import { useMobileViewport } from '@bndynet/vue-site'
+
+const isMobileViewport = useMobileViewport()
+</script>
+
+<template>
+  <button v-if="isMobileViewport">Open compact menu</button>
+</template>
+```
+
+Call the composable from a Vue component rendered inside the site layout. It throws a `[vue-site]`
+error when used outside that context.
+
 ## Upgrade
 
 ```bash
@@ -678,7 +807,7 @@ npm update @bndynet/vue-site
 git clone https://github.com/bndynet/vue-site.git && cd vue-site
 npm install
 npm run dev    # watch-build lib + example site
-npm run build  # `dist/` + `example/example-dist`
+npm run build  # `dist/` + `example/dist`
 ```
 
 ### Using a local build in another project

package/README.zh.md

@@ -100,7 +100,7 @@ npx vue-site build --base /app/
 | `title` | 站点标题（侧边栏 + 标签页）。`LocalizedString` |
 | `nav` | `NavItem[]` |
 | `navPosition` | 可选的导航位置：`'top'` 强制使用顶部/分层导航，`'sidebar'` 强制将完整导航树放在侧边栏。不传时保持基于导航深度的自动行为 |
-| `defaultPath` | 站点打开时的路径；`/` 和未知路径会重定向到此。必须匹配一个已注册的路由（某个 `nav` 条目解析后的路径，或某个 `pages` 条目的 `path`）。默认为第一个顶级 `nav` 条目 |
+| `defaultPath` | 站点打开时的路径；`/` 和未知路径会重定向到此。必须匹配一个已注册的路由（某个 `nav` 条目解析后的路径，或某个 `pages` 条目的 `path`）。默认选择导航顺序中的第一个已注册页面；如果导航中没有页面，则选择第一个可见的独立页面 |
 | `favicon` | 浏览器标签页图标 URL。可使用 public 资源路径、远程 URL 或导入后的资源 URL |
 | `logo` | Logo 的 URL 或导入的图片 |
 | `theme` | 见下方 `ThemeConfig`；设为 `false` 可禁用主题（隐藏切换器、强制使用固定的 `light` 调色板、不进行 localStorage 持久化） |
@@ -112,15 +112,14 @@ npx vue-site build --base /app/
 | `auth` | 中心化的授权策略（`AuthConfig`）—— 参见[按页面授权](#按页面授权-auth) |
 | `router` | 历史模式（`RouterConfig`）—— `hash`（默认）或 HTML5 `web`；参见[路由历史](#路由历史-router) |
 | `packageRepository` | 通常由 CLI 从 `package.json` 设置；单独使用 `createSiteApp` 时可省略 |
-| `custom` | 公开的业务自定义配置，可通过 `useSiteConfig().config.custom` 读取；参见[自定义客户端配置](#自定义客户端配置-custom) |
+| `custom` | 公开的业务自定义配置；组件内通过 `useSiteConfig().config.custom` 读取，其他代码通过 `getSiteConfig().custom` 读取；参见[自定义客户端配置](#自定义客户端配置-custom) |
 | `env` | 开发/构建选项 —— 见下文 |
 | `bootstrap` | 可选的站点根目录相对路径（如 `./bootstrap.ts`）—— 在 Vue 应用之前加载一次的模块 |
 | `configureApp` | 可选的 `(app) => void \| Promise<void>`，在路由安装之后、`mount` 之前执行（参见 [`configureApp` 中的本地包](#在-configureapp-中使用本地包)） |
 
 ### 自定义客户端配置（`custom`）
 
-`custom` 用于存放框架无需解释、只需原样保留的公开业务配置。任何组件都可以通过
-`useSiteConfig()` 读取：
+`custom` 用于存放框架无需解释、只需原样保留的公开业务配置：
 
 ```typescript
 // site.config.ts
@@ -139,6 +138,20 @@ const { config } = useSiteConfig()
 const apiBaseUrl = config.custom?.apiBaseUrl
 ```
 
+`utils.ts` 等普通模块没有 Vue 注入上下文，应改用 `getSiteConfig()` 读取当前配置：
+
+```typescript
+// utils/api.ts
+import { getSiteConfig } from '@bndynet/vue-site'
+
+export function getApiBaseUrl() {
+  return getSiteConfig().custom?.apiBaseUrl
+}
+```
+
+请在 `createSiteApp()` 已开始执行后的运行时代码中调用 `getSiteConfig()`。不要在被
+`site.config.ts` 导入的模块顶层立即求值，因为此时当前配置尚未注册。
+
 如果不同构建环境使用不同的值，可以选择不同的配置文件：
 
 ```typescript
@@ -209,6 +222,20 @@ export default defineConfig({
 })
 ```
 
+### 响应式辅助
+
+宽内容——例如 Element Plus 的 `el-table` 或多列 `el-form`——在小屏幕上可能溢出。把它包进一个
+`.site-responsive-scroll` 容器，即可获得横向滚动条（触屏惯性滚动 + 可见的滚动条提示），而不是
+溢出页面：
+
+```vue
+<template>
+  <div class="site-responsive-scroll">
+    <el-table :data="rows">…</el-table>
+  </div>
+</template>
+```
+
 ### `ThemeConfig`
 
 内置主题为 `light`、`dark`，外加始终可用的额外主题 `sepia` 和 `ocean`（在每个站点的切换器中都会显示）。在 `SiteConfig` 上设置 `theme: false` 可完全禁用主题。
@@ -220,6 +247,73 @@ export default defineConfig({
 | `palettes` | — | 仅针对内置 light/dark 的部分覆盖 |
 | `extraThemes` | — | 额外主题：`id`、`label`、`icon`，可选 `basedOn`、`palette`；复用内置 id（`sepia`/`ocean`）即可覆盖它。导入 `builtinThemePalettes` 获取完整默认值 |
 
+### 语义化颜色变量
+
+每个主题都由语义化的 `--color-*` CSS 变量驱动。Element Plus 的通用变量在
+`element-plus-theme.css` 中映射到这些变量，因此常见控件和表面会跟随当前主题。部分组件
+还有专属变量；新增 Element Plus 组件时，可能需要补充对应映射。内置调色板定义种子色，
+其余值通过 `color-mix()` / `var()` 派生，因此 `builtinThemePalettes` 中可能包含 CSS 表达式，
+而不只是字面色值。
+
+| 变量 | 用途 |
+|------|------|
+| `--color-primary` | 品牌/主色（映射到 `--el-color-primary` 及其色阶） |
+| `--color-primary-contrast` | 主色填充控件上的文字色，默认取当前主题背景色 |
+| `--color-primary-hover` | 主色填充控件的悬停色，由主色和文字色派生 |
+| `--color-success` | 成功 |
+| `--color-warning` | 警告 |
+| `--color-danger` | 危险/错误（`--el-color-error` 复用该值） |
+| `--color-info` | 信息 |
+| `--color-surface-raised` | 浮层表面：下拉、对话框、遮罩背景 |
+| `--color-overlay` | 弹窗 / 加载遮罩 |
+
+自定义主题只需定义这些基础色，框架会用 `color-mix()` 自动派生 Element Plus 的
+`light-3/5/7/8/9` 与 `dark-2` 色阶：
+
+```typescript
+theme: {
+  extraThemes: [
+    {
+      id: 'forest',
+      label: 'Forest',
+      basedOn: 'light',
+      palette: {
+        '--color-primary': '#2f855a',
+        '--color-surface-raised': '#f7faf8',
+      },
+    },
+  ],
+}
+```
+
+如果自定义主色与背景的对比度不足，可以显式设置 `--color-primary-contrast`。它用于主色按钮、
+深色标签和选中按钮组等填充控件上的文字。
+
+### 覆盖任意 token
+
+不只是基础色，**任何 token 都可以覆盖**。覆盖按三级优先级从低到高应用：
+
+1. `palettes.light` / `palettes.dark`，或 `extraThemes[].palette` —— 合并到该主题的内置调色板。
+2. `colors` —— 在激活调色板之后全局应用，对所有主题生效。
+3. 运行时直接调用 `document.documentElement.style.setProperty('--color-…', …)`。
+
+覆盖 **种子色**（如 `--color-border`）会同时更新引用它的派生 token（`--color-sidebar-border`、
+`--color-code-border`、`--color-table-border`、`--color-blockquote-border`）；覆盖 **派生 token**
+则只影响它本身。如果希望颜色能随主题自动适配，优先覆盖种子色。
+
+```typescript
+theme: {
+  colors: {
+    '--color-theme-switch-hover': 'rgba(0, 0, 0, 0.08)',
+  },
+  palettes: {
+    light: {
+      '--color-sidebar-bg': '#f0f2f5',
+    },
+  },
+}
+```
+
 ## 国际化（`i18n`）
 
 设置 `i18n` 以启用多语言支持。框架会在头部添加语言切换器，
@@ -327,8 +421,8 @@ export default defineConfig({
 
 | 属性 | 默认值 | 说明 |
 |----------|---------|-------------|
-| `locales` | 自动发现的 `locales/*.json` | `{ code, label, icon? }[]` —— 支持的语言，按显示顺序排列。可选：省略时从自动加载的文件名派生（使用内置标签）。第一个条目为回退项 |
-| `defaultLocale` | `locales[0].code` | 当没有存储值且检测未命中时使用的初始语言 |
+| `locales` | 自动发现的 `locales/*.json` | `{ code, label, icon? }[]` —— 支持的语言，按显示顺序排列。CLI 模式下可省略；不使用 CLI 时，省略后从 `i18n.messages` 的键派生，若也没有则使用 `defaultLocale` 或 `en`。第一个条目为回退项 |
+| `defaultLocale` | 第一个解析出的语言，或 `en` | 当没有存储值且检测未命中时使用的初始语言 |
 | `detectBrowser` | `true` | 首次访问时从 `navigator.language(s)` 检测初始语言 |
 | `storageKey` | `vue-site-locale` | 用于存储所选语言的 localStorage 键 |
 | `messages` | 自动从 `locales/<code>.json` 加载 | `Record<LocaleCode, Record<string, string>>` —— 额外/覆盖的翻译，会合并到自动加载的文件和内置 UI 字符串之上 |
@@ -394,9 +488,11 @@ export default defineConfig({
   `code` 即文件名（一个 `LocaleCode`，如 `en` 或 `zh-TW`）。
 - 仍支持显式的 `i18n.messages`，并会**覆盖**自动加载的键（按 id）；显式的 `i18n.locales`
   控制 label/icon/顺序。两者均为可选。
-- 自动发现是 **CLI** 特性。如果你自行嵌入该库（不使用 `vue-site` CLI 而直接调用 `createSiteApp`），
-  请直接传入 `i18n.messages` —— 例如用显式 import 从 JSON 构建（避免在 `site.config.ts` 中使用
-  `import.meta.glob`，CLI 会在 Node 中预加载它）。
+- 自动发现 `locales/<code>.json` 是 **CLI** 特性。如果你自行嵌入该库（不使用 `vue-site` CLI 而直接调用
+  `createSiteApp`），请直接传入 `i18n.messages` —— 例如用显式 import 从 JSON 构建（避免在
+  `site.config.ts` 中使用 `import.meta.glob`，CLI 会在 Node 中预加载它）。省略 `i18n.locales` 时，库会
+  从 `messages` 的键派生语言代码，并直接用代码作为显示名称。若本地化内容没有消息目录，请显式提供
+  `locales`，以设置语言切换器的选项和名称。
 
 ### 在你自己的页面中本地化
 
@@ -577,14 +673,15 @@ app.mount('#app')
 返回 `Promise` 时会 **await** 它。如果你在配置中设置了可选的 `bootstrap`，该模块会在应用创建前加载；
 如果省略 `bootstrap`，则跳过该步骤。
 
-导出：`createSiteApp`、`defineConfig`、`useTheme`、`useSiteConfig`、`useLocale`、`useLocalize`、`tk`、`resolveLocalized`、`resolveField`、`resolveMessage`、`mergeCatalog`、`flattenMessages`、`isMessageRef`、`localizedPage`、`builtinMessages`、`themeRefKey`、`localeRefKey`。类型：`SiteConfig`、`SiteEnvConfig`、`SiteViteConfig`、`SiteCustomConfig`、`SiteExternalLink`、`NavItem`、`StandalonePage`、`PageLayout`、`AuthRule`、`AuthContext`、`AuthConfig`、`RouterConfig`、`ThemeConfig`、`ThemeOption`、`ThemePaletteVars`、`ResolvedNavItem`、`I18nConfig`、`LocaleOption`、`LocaleCode`、`LocalizedString`、`MessageRef`、`MessageTree`、`MessageCatalog`、`PageLoader`、`LocalizedPageOptions`。
+导出：`createSiteApp`、`defineConfig`、`useTheme`、`useMobileViewport`、`useSiteConfig`、`getSiteConfig`、`useLocale`、`useLocalize`、`tk`、`resolveLocalized`、`resolveField`、`resolveMessage`、`mergeCatalog`、`flattenMessages`、`isMessageRef`、`localizedPage`、`builtinMessages`、`themeRefKey`、`localeRefKey`。类型：`SiteConfig`、`SiteEnvConfig`、`SiteViteConfig`、`SiteCustomConfig`、`SiteExternalLink`、`NavItem`、`StandalonePage`、`PageLayout`、`AuthRule`、`AuthContext`、`AuthConfig`、`RouterConfig`、`ThemeConfig`、`ThemeOption`、`ThemePaletteVars`、`ResolvedNavItem`、`I18nConfig`、`LocaleOption`、`LocaleCode`、`LocalizedString`、`MessageRef`、`MessageTree`、`MessageCatalog`、`PageLoader`、`LocalizedPageOptions`。
 
 ### 在 Vue 页面中使用主题（`useTheme`）
 
 从 `@bndynet/vue-site` 导入 `useTheme`。它返回一个响应式的 `theme` ref（当前激活的主题 id，
 如 `light`、`dark` 或某个 `extraThemes[].id`），外加 `setTheme` 和 `toggleTheme`。
 根布局还会在 `document.documentElement` 上设置 `data-theme` 属性并应用 CSS 变量，
-因此你可以用 `var(--color-*)` 来设置样式，无需 JavaScript。
+因此你可以用 `var(--color-*)` 来设置样式，无需 JavaScript。它还会更新 `color-scheme`，
+让浏览器原生控件和滚动条跟随当前主题的亮色或暗色模式。
 
 theme ref 由 `createSiteApp()` **提供**（与你的应用同一个 Vue 运行时），所以 `watch(theme, …)`
 能可靠工作，即使其他工具可能会从嵌套的 `node_modules` 加载第二份 `vue`。
@@ -609,6 +706,26 @@ watch(theme, (next, prev) => {
 `watch` 仅在你的组件初始化之后主题**发生变化**时运行（例如用户点击主题控件之后）。
 除非你传入 `{ immediate: true }`，否则它不会在初始值上运行。
 
+### 响应式视口状态（`useMobileViewport`）
+
+当组件行为需要和站点布局使用相同的移动端断点时，导入 `useMobileViewport`。它返回一个只读 ref；
+视口宽度不超过 840 CSS 像素时值为 `true`。站点布局提供的是共享 ref，因此组件无需各自创建媒体查询监听器。
+如果只是调整视觉样式，优先使用 CSS 媒体查询。
+
+```vue
+<script setup lang="ts">
+import { useMobileViewport } from '@bndynet/vue-site'
+
+const isMobileViewport = useMobileViewport()
+</script>
+
+<template>
+  <button v-if="isMobileViewport">打开紧凑菜单</button>
+</template>
+```
+
+请在站点布局内部渲染的 Vue 组件中调用此 composable。在该上下文之外调用时，会抛出 `[vue-site]` 错误。
+
 ## 升级
 
 ```bash

package/bin/vue-site.mjs

@@ -129,6 +129,7 @@ const configCandidates = [
 const initSiteConfig = `import { defineConfig } from '@bndynet/vue-site'
 
 export default defineConfig({
+  name: 'My Site',
   title: 'My Site',
   // Public client configuration. Never place secrets here.
   custom: {
@@ -227,6 +228,7 @@ function resolveSiteConfig(cliConfig) {
       'Run `npx vue-site init` to create starter files, or create site.config.ts manually:\n\n' +
       '  import type { SiteConfig } from \'@bndynet/vue-site\'\n\n' +
       '  export default {\n' +
+      '    name: \'My Site\',\n' +
       '    title: \'My Site\',\n' +
       '    nav: [\n' +
       '      { label: \'Home\', icon: \'home\', page: () => import(\'./README.md?raw\') },\n' +
@@ -443,7 +445,7 @@ function buildHtmlShell(scriptTag, siteConfig) {
 <html lang="en">
 <head>
   <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
 ${buildFaviconLink(siteConfig)}  <title></title>
 </head>
 <body>
@@ -1057,7 +1059,7 @@ async function buildViteConfig(options = {}) {
       },
     },
     build: {
-      outDir: resolve(cwd, outDir || `${basename(cwd)}-dist`),
+      outDir: resolve(cwd, outDir || 'dist'),
       emptyOutDir: true,
     },
     ...(cliBase != null && { base: cliBase }),

package/dist/components/AppLayout.vue.d.ts

@@ -1,2 +1,6 @@
-declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, HTMLDivElement>;
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {
+    menuButton: HTMLButtonElement;
+    mobileDrawer: HTMLElement;
+    drawerCloseButton: HTMLButtonElement;
+}, HTMLDivElement>;
 export default _default;

package/dist/components/LocaleSwitch.vue.d.ts

@@ -6,5 +6,6 @@ declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
     detailsRef: HTMLDetailsElement;
     summaryRef: HTMLElement;
+    menuRef: HTMLDivElement;
 }, HTMLDetailsElement>;
 export default _default;

package/dist/components/NavGroup.vue.d.ts

@@ -1,6 +1,14 @@
 import { ResolvedNavItem } from '../types';
 type __VLS_Props = {
     item: ResolvedNavItem;
+    collapsed?: boolean;
+    hoverExpand?: boolean;
 };
-declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    collapsed: boolean;
+    hoverExpand: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    trigger: HTMLButtonElement;
+    popup: HTMLDivElement;
+}, HTMLDivElement>;
 export default _default;

package/dist/components/NavItem.vue.d.ts

@@ -2,8 +2,10 @@ import { ResolvedNavItem } from '../types';
 type __VLS_Props = {
     item: ResolvedNavItem;
     indent?: boolean;
+    collapsed?: boolean;
 };
 declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
     indent: boolean;
+    collapsed: boolean;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
 export default _default;

package/dist/components/SideNav.vue.d.ts

@@ -1,2 +1,13 @@
-declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, HTMLElement>;
+import { ResolvedNavItem } from '../types';
+type __VLS_Props = {
+    /** Optional navigation tree override, used by the mobile drawer. */
+    items?: ResolvedNavItem[];
+    /** Whether desktop navigation is shown as an icon rail. */
+    collapsed?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    "toggle-collapse": () => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onToggle-collapse"?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLElement>;
 export default _default;

package/dist/components/ThemeSwitch.vue.d.ts

@@ -6,5 +6,6 @@ declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
     detailsRef: HTMLDetailsElement;
     summaryRef: HTMLElement;
+    menuRef: HTMLDivElement;
 }, HTMLDetailsElement>;
 export default _default;