20261008173212

code/g3soft-libs/docs/app/app.config.ts

@@ -0,0 +1,9 @@
+export default defineAppConfig({
+  // Docus 默认把「整棵导航树」渲染进侧边栏；设置 navigation.sub 后，
+  // 侧边栏只显示当前顶级板块的页面。
+  // 见 docus/app/composables/useSubNavigation.ts
+  // 注意：sub='aside' 本会在侧边栏顶部渲染板块切换，已被本地 DocsAsideLeftTop 覆盖为空。
+  navigation: {
+    sub: 'aside',
+  },
+})

code/g3soft-libs/docs/app/app.css

@@ -0,0 +1,5 @@
+/**
+ * Docus 会把本文件追加进 Nuxt 的 css[]（见 docus/modules/css.ts）。
+ * 这里只引入设计令牌的编译产物；不要在此引入 Tailwind（会被 Docus 判为重复引入并告警）。
+ */
+@import '@g3soft/tokens';

code/g3soft-libs/docs/app/components/app/AppHeaderCTA.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+// Docus 在 header 右上角渲染的占位组件，本地同名文件会覆盖 Layer 里的空实现。
+// 两个文档区入口：图标 + 文字（窄屏只留图标），并按当前路由所属板块高亮。
+const route = useRoute()
+
+const sections = [
+  { to: '/ui/usage/getting-started', prefix: '/ui', icon: 'i-lucide-component', label: 'UI 组件库' },
+  { to: '/api/getting-started', prefix: '/api', icon: 'i-lucide-cable', label: '接口文档' },
+]
+
+function isSectionActive(prefix: string) {
+  return route.path === prefix || route.path.startsWith(`${prefix}/`)
+}
+</script>
+
+<template>
+  <UButton
+    v-for="section in sections"
+    :key="section.prefix"
+    :to="section.to"
+    :icon="section.icon"
+    color="neutral"
+    variant="ghost"
+    :active="isSectionActive(section.prefix)"
+    active-color="primary"
+    active-variant="soft"
+    :aria-label="section.label"
+  >
+    <span class="hidden lg:inline">{{ section.label }}</span>
+  </UButton>
+</template>

code/g3soft-libs/docs/app/components/docs/DocsAsideLeftTop.vue

@@ -0,0 +1,8 @@
+<template>
+  <!--
+    覆盖 Docus 的 DocsAsideLeftTop（默认在侧边栏顶部渲染板块切换）。
+    这里留空，详情页侧边栏就不再出现板块切换；板块改由右上角入口按钮切换。
+    navigation.sub='aside' 仍需保留，它负责「侧边栏只显示当前板块」的隔离行为。
+  -->
+  <div />
+</template>

code/g3soft-libs/docs/content/api/.navigation.yml

@@ -0,0 +1,2 @@
+title: 接口文档
+icon: i-lucide-cable

code/g3soft-libs/docs/content/api/getting-started.md

@@ -0,0 +1,10 @@
+---
+title: 快速开始
+description: 前后端接口的接入说明
+---
+
+# 快速开始
+
+本页说明前后端接口的接入方式，内容包括接口约定、鉴权与联调步骤。
+
+> 内容待补充。

code/g3soft-libs/docs/content/guide/.navigation.yml

@@ -0,0 +1,2 @@
+title: 指南
+icon: i-lucide-rocket

code/g3soft-libs/docs/content/guide/getting-started.md

@@ -1,68 +1,22 @@
 ---
 title: 快速开始
-description: 安装组件库并在项目中用起来
+description: 认识 G3Soft 技术文档站，快速找到需要的内容
 ---
 
 # 快速开始
 
-## 安装
+G3Soft 技术文档站汇总前端基础设施的文档：自研 Vue 3 组件库、设计变量、前后端接口，以及工程规范与设计决策。
 
-```bash
-pnpm add @g3soft/ui @g3soft/tokens
-```
+这一页帮你先建立整体认知，再快速跳到对应板块。
 
-`vue` 由宿主项目提供（`peerDependencies`），请确保已安装 Vue 3。
+## 站点结构
 
-## 引入设计变量
+- **指南** —— 站点总览与工程规范，帮助你了解全局约定。
+- **UI 组件库** —— 自研 Vue 3 组件库的安装、使用与组件 API。
+- **接口文档** —— 前后端接口约定与联调说明。
 
-在应用入口引入一次，组件样式全部依赖这套变量：
+## 快速导航
 
-```ts
-// main.ts
-import '@g3soft/tokens'
-```
-
-## 使用组件
-
-按需引入：
-
-```vue
-<script setup lang="ts">
-import { G3Button } from '@g3soft/ui'
-</script>
-
-<template>
-  <G3Button type="primary" @click="handleClick">主要按钮</G3Button>
-</template>
-```
-
-或全量注册：
-
-```ts
-import { G3UI } from '@g3soft/ui'
-import { createApp } from 'vue'
-
-createApp(App).use(G3UI).mount('#app')
-```
-
-## 换肤
-
-组件的颜色与尺寸一律引用 `--g3-*` 变量，定制只需覆盖同名变量，不必改组件代码：
-
-```css
-:root {
-  --g3-color-primary: #1677ff;
-  --g3-radius: 6px;
-}
-```
-
-暗色主题由 `html[data-g3-theme='dark']` 触发：
-
-```ts
-document.documentElement.dataset.g3Theme = 'dark'
-```
-
-## 下一步
-
-- 浏览[组件参考](/reference/ui/button)
-- 了解[设计变量](/explain/why-tokens)的设计取舍
+- 想用组件库？从 [UI 组件库 · 快速上手](/ui/usage/getting-started) 开始。
+- 想看某个组件？见 [通用组件 · Button 按钮](/ui/general/button)。
+- 要对接接口？看 [接口文档 · 快速开始](/api/getting-started)。

code/g3soft-libs/docs/content/index.md

@@ -28,7 +28,7 @@ color: neutral
 variant: outline
 size: xl
 icon: i-lucide-book-open
-to: /reference/ui/button
+to: /ui/general/button
 ---
 浏览组件
 :::
@@ -48,13 +48,13 @@ to: /guide/getting-started
 指南
 
 #description
-从安装到上手，以及版本升级与迁移说明。
+文档站总览与快速导航，帮你先建立整体认知。
 :::
 
 :::u-page-feature
 ---
 icon: i-lucide-component
-to: /reference/ui/button
+to: /ui/general/button
 ---
 #title
 参考

code/g3soft-libs/docs/content/ui/.navigation.yml

@@ -0,0 +1,2 @@
+title: UI 组件库
+icon: i-lucide-component

code/g3soft-libs/docs/content/ui/1.usage/.navigation.yml

@@ -0,0 +1,2 @@
+title: 使用
+icon: i-lucide-book-open

code/g3soft-libs/docs/content/ui/1.usage/getting-started.md

@@ -0,0 +1,70 @@
+---
+title: 快速上手
+description: 安装、引入并在项目中使用 UI 组件库
+---
+
+# 快速上手
+
+本节介绍如何在项目中安装、引入并使用 UI 组件库。
+
+## 安装
+
+```bash
+pnpm add @g3soft/ui @g3soft/tokens
+```
+
+`vue` 由宿主项目提供（`peerDependencies`），请确保已安装 Vue 3。
+
+## 引入设计变量
+
+在应用入口引入一次，组件样式全部依赖这套变量：
+
+```ts
+// main.ts
+import '@g3soft/tokens'
+```
+
+## 使用组件
+
+按需引入：
+
+```vue
+<script setup lang="ts">
+import { G3Button } from '@g3soft/ui'
+</script>
+
+<template>
+  <G3Button type="primary" @click="handleClick">主要按钮</G3Button>
+</template>
+```
+
+或全量注册：
+
+```ts
+import { G3UI } from '@g3soft/ui'
+import { createApp } from 'vue'
+
+createApp(App).use(G3UI).mount('#app')
+```
+
+## 换肤
+
+组件的颜色与尺寸一律引用 `--g3-*` 变量，定制只需覆盖同名变量，不必改组件代码：
+
+```css
+:root {
+  --g3-color-primary: #18181b;
+  --g3-radius: 6px;
+}
+```
+
+暗色主题由 `html[data-g3-theme='dark']` 触发：
+
+```ts
+document.documentElement.dataset.g3Theme = 'dark'
+```
+
+## 下一步
+
+- 浏览[组件参考](/ui/general/button)
+- 了解[设计变量](/explain/why-tokens)的设计取舍

code/g3soft-libs/docs/content/ui/2.general/.navigation.yml

@@ -0,0 +1,2 @@
+title: 通用组件
+icon: i-lucide-boxes

code/g3soft-libs/docs/data/api/config-provider.json

@@ -0,0 +1,50 @@
+{
+  "displayName": "G3ConfigProvider",
+  "description": "ConfigProvider —— 全局/子树配置。 theme.local（默认）：把派生出的 CSS 变量挂到子树根节点（cloneVNode 合并 style，不额外包 DOM）， 支持同一页面多主题共存。 theme.global：挂到 :root 做整站换肤，卸载时只清理自己设置过的变量。 用 render function 实现（而非 <template>），因为 local 作用域需要 cloneVNode 精确注入。",
+  "props": [
+    {
+      "name": "namespace",
+      "description": "",
+      "type": "string",
+      "defaultValue": "undefined"
+    },
+    {
+      "name": "theme",
+      "description": "",
+      "type": "G3ThemeConfig",
+      "defaultValue": "undefined"
+    },
+    {
+      "name": "zIndex",
+      "description": "",
+      "type": "number",
+      "defaultValue": "undefined"
+    },
+    {
+      "name": "locale",
+      "description": "",
+      "type": "Locale",
+      "defaultValue": "undefined"
+    },
+    {
+      "name": "popupContainer",
+      "description": "",
+      "type": "PopupContainer",
+      "defaultValue": "undefined"
+    },
+    {
+      "name": "componentDefaults",
+      "description": "",
+      "type": "Record<string, Record<string, unknown>>",
+      "defaultValue": "undefined"
+    },
+    {
+      "name": "emptyText",
+      "description": "",
+      "type": "string",
+      "defaultValue": "undefined"
+    }
+  ],
+  "events": [],
+  "slots": []
+}

code/g3soft-libs/docs/nuxt.config.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url'
  * 几个刻意的选择：
  *  - extends: ['docus'] —— Docus 是 Nuxt Layer，全部能力（导航、搜索、主题）由它提供
  *  - alias 直连 packages 源码 —— 组件库尚未构建也能开发，改组件即时热更
+ *    （tokens 例外：它是 SCSS 编译产物，alias 指向 dist/index.css，需先 build tokens）
  *
  * 部署到子路径时用环境变量 NUXT_APP_BASE_URL=/docs/，不在配置里写死。
  */
@@ -27,12 +28,21 @@ export default defineNuxtConfig({
 
   vite: {
     resolve: {
-      alias: {
-        '@g3soft/ui': fileURLToPath(new URL('../packages/ui/src/index.ts', import.meta.url)),
-        '@g3soft/tokens': fileURLToPath(
-          new URL('../packages/tokens/src/index.css', import.meta.url),
-        ),
-      },
+      // 用正则做“精确匹配”：否则 '@g3soft/tokens' 的前缀别名会把
+      // '@g3soft/tokens/scss' 也一并改写掉，导致组件里的 @use 找不到 SCSS。
+      alias: [
+        {
+          find: /^@g3soft\/ui$/,
+          replacement: fileURLToPath(new URL('../packages/ui/src/index.ts', import.meta.url)),
+        },
+        {
+          // tokens 是 SCSS 编译产物：仅裸导入指向 dist/index.css（由 @g3soft/tokens 的 build 生成）
+          find: /^@g3soft\/tokens$/,
+          replacement: fileURLToPath(
+            new URL('../packages/tokens/dist/index.css', import.meta.url),
+          ),
+        },
+      ],
     },
     server: {
       fs: {

code/g3soft-libs/docs/package.json

@@ -16,5 +16,8 @@
     "docus": "^5.14.0",
     "nuxt": "4.4.8",
     "vue": "catalog:"
+  },
+  "devDependencies": {
+    "sass": "catalog:"
   }
 }