@lmy54321/design-system 1.1.4 → 1.3.0

package/.codebuddy/rules/init-project.mdc

@@ -16,6 +16,46 @@ provider:
 
 ## 自动执行步骤
 
+### 0. 环境检测（新电脑必须先过这一关）
+
+在执行任何操作前，**自动检测**以下依赖，缺什么装什么，全程自动，不要让用户手动操作：
+
+#### 检测 Node.js
+```bash
+node -v
+```
+- 如果命令不存在或版本 < 18：
+  - **macOS**：先检查 `brew -v`，如果没有 Homebrew，先安装：
+    ```bash
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    ```
+    然后安装 Node.js：
+    ```bash
+    brew install node
+    ```
+  - **Windows**：通过 winget 安装（Windows 10/11 自带）：
+    ```bash
+    winget install OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements
+    ```
+    如果 winget 不可用，提示用户前往 https://nodejs.org 下载 LTS 版本安装包，安装后重启 CodeBuddy。
+  - **Linux**：
+    ```bash
+    curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
+    sudo apt-get install -y nodejs
+    ```
+- 安装完成后**再次验证** `node -v` 和 `npm -v`，确认可用后才继续。
+
+#### 检测 npm
+```bash
+npm -v
+```
+npm 随 Node.js 一起安装，正常情况下不需要单独处理。如果 Node 装好了但 npm 异常，运行：
+```bash
+node -e "console.log('node ok')" && npm -v
+```
+
+> **原则：** 环境检测和安装全程自动执行，用户只需等待。如果某步安装需要管理员权限，告诉用户「需要输入电脑密码来安装 XXX」即可，不要让用户去搜教程或手动下载。
+
 ### 1. 创建 React + Vite 项目
 ```bash
 npm create vite@latest . -- --template react-ts
@@ -27,6 +67,7 @@ npm create vite@latest . -- --template react-ts
 npm install
 npm install @lmy54321/design-system
 npm install tailwindcss @tailwindcss/vite
+npm install react-router-dom motion
 ```
 
 ### 3. 同步设计系统 AI 规则
@@ -39,54 +80,51 @@ cp node_modules/@lmy54321/design-system/.codebuddy/rules/init-project.mdc .codeb
 
 > **说明：** 规则文件随 npm 包版本同步发布，每次升级设计系统版本后应重新执行此复制命令以获取最新规范。`init-project.mdc` 也会被复制，这样项目后续可以再次执行初始化或帮助其他同事同步规则。
 
-### 4. 配置 Vite（添加 Tailwind 插件）
-修改 `vite.config.ts`：
-```ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
+### 4. 复制完整 Demo 模板
 
-export default defineConfig({
-  plugins: [react(), tailwindcss()],
-})
-```
+设计系统 npm 包中内置了完整的 Demo 项目模板（地图首页、探索页、行程规划、个人中心、开发者入口、组件库展示等），直接复制即可运行。
 
-### 5. 配置入口样式
-将 `src/index.css` 内容替换为：
-```css
-@import "@lmy54321/design-system/styles";
+**模板会覆盖 Vite 默认文件**（`vite.config.ts`、`tsconfig.json`、`index.html`、`src/` 下的所有文件），已包含正确的 Tailwind + 设计系统样式配置，无需手动修改：
 
-@source "../src";
-@source "../node_modules/@lmy54321/design-system/dist";
-```
+```bash
+# 复制 Demo 模板文件（覆盖 Vite 默认生成的文件）
+cp -r node_modules/@lmy54321/design-system/template/src/* src/
+cp node_modules/@lmy54321/design-system/template/index.html index.html
+cp node_modules/@lmy54321/design-system/template/vite.config.ts vite.config.ts
+cp node_modules/@lmy54321/design-system/template/tsconfig.json tsconfig.json
+
+# 复制 public 资源（manifest 等，图片通过 CDN 加载无需复制）
+cp node_modules/@lmy54321/design-system/template/public/manifest.json public/manifest.json 2>/dev/null || true
 
-> **注意：** 不要在 `src/index.css` 中单独写 `@import "tailwindcss"`，设计系统的样式文件内部已包含 Tailwind 初始化，重复导入会导致样式冲突。
-> `src/main.tsx` 中也不需要通过 JS 导入样式（不需要 `import '@lmy54321/design-system/styles'`），CSS 的 `@import` 已经处理了。
-
-### 6. 清理 Vite 默认模板
-- 清空 `src/App.css` 的内容
-- 将 `src/App.tsx` 替换为一个简单的欢迎页面，使用设计系统组件：
-```tsx
-import { Btn, IconFont } from '@lmy54321/design-system'
-
-function App() {
-  return (
-    <div style={{ minHeight: '100dvh', display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 16, fontFamily: 'var(--font-family-sans)' }}>
-      <IconFont name="map-location" size="48px" />
-      <h1 style={{ fontSize: 24, fontWeight: 600 }}>项目已就绪</h1>
-      <p style={{ fontSize: 14, color: 'rgba(0,0,0,0.42)' }}>设计系统已加载，可以开始创建页面了</p>
-      <Btn variant="primary" label="开始" />
-    </div>
-  )
-}
-
-export default App
+# 删除 Vite 默认生成的无用文件
+rm -f src/App.css src/assets/react.svg public/vite.svg
 ```
 
+> **说明：** 模板包含以下路由页面，启动后可通过浏览器访问：
+> - `/` — 开发者入口（默认首页，四个功能卡片导航）
+> - `/dev` — 开发者入口（同上）
+> - `/demo` — Demo 手机预览（地图首页、探索、行程、我的四个 Tab）
+> - `/components` — 组件库交互式展示
+> - `/sync` — 规范同步工具
+> - `/deploy` — 部署预览
+>
+> **注意：** 模板中的图片资源通过 CDN 加载（jsDelivr + GitHub），无需在本地存放图片文件。
+>
+> **注意：** 模板中的 `src/index.css` 已配置好样式导入，不需要手动修改。不要在其中单独写 `@import "tailwindcss"`，设计系统样式内部已包含 Tailwind 初始化。
+
 ### 7. 启动开发服务器
 ```bash
 npm run dev
 ```
 
-### 8. 完成后告诉用户
-告诉用户：「项目已初始化完成，设计系统已加载。你可以直接描述你想要的页面，比如：做一个地图首页 / 做一个搜索页面 / 做一个 POI 列表页。」
+### 6. 完成后告诉用户
+告诉用户：
+
+「项目已初始化完成！已加载完整的 Demo 项目，包含多个示例页面。
+
+**访问地址：**
+- 开发者入口（默认首页）：http://localhost:5173/
+- Demo 手机预览：http://localhost:5173/demo
+- 组件库：http://localhost:5173/components
+
+你可以在这些 Demo 的基础上修改，或者描述你想要的新页面。」

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lmy54321/design-system",
-  "version": "1.1.4",
+  "version": "1.3.0",
   "description": "A comprehensive React component library and design system based on Tailwind CSS and Motion.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -18,6 +18,8 @@
   "files": [
     "dist",
     "styles",
+    "template",
+    "!template/public/images",
     ".codebuddy/rules/design-system.mdc",
     ".codebuddy/rules/init-project.mdc"
   ],

package/template/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
+    <!-- PWA 全屏模式，添加到主屏幕后无地址栏 -->
+    <meta name="mobile-web-app-capable" content="yes">
+    <meta name="apple-mobile-web-app-capable" content="yes">
+    <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
+    <meta name="theme-color" content="#4B526B">
+    <link rel="manifest" href="/manifest.json">
+    <title>Design Demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/public/manifest.json

@@ -0,0 +1,9 @@
+{
+  "name": "Design System Demo",
+  "short_name": "Demo",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#4B526B",
+  "orientation": "any"
+}

package/template/src/App.tsx

@@ -0,0 +1,55 @@
+import { useState, useCallback } from "react";
+import type { TabId } from "@lmy54321/design-system";
+import { MapHome } from "./pages/MapHome";
+import { ExplorePage } from "./pages/ExplorePage";
+import { PlanPage } from "./pages/PlanPage";
+import { MePage } from "./pages/MePage";
+
+export interface NewPlanPayload {
+  title: string;
+  spots: number;
+  image: string;
+  stops: { name: string; icon: string; dur: string }[];
+}
+
+export default function App() {
+  const [activeTab, setActiveTab] = useState<TabId>("home");
+  const [newPlan, setNewPlan] = useState<NewPlanPayload | null>(null);
+
+  const handleCreatePlan = useCallback((plan: NewPlanPayload) => {
+    setNewPlan(plan);
+    setActiveTab("plan");
+  }, []);
+
+  const handlePlanConsumed = useCallback(() => {
+    setNewPlan(null);
+  }, []);
+
+  const renderPage = () => {
+    switch (activeTab) {
+      case "home":
+        return <MapHome activeTab={activeTab} onTabChange={setActiveTab} />;
+      case "explore":
+        return <ExplorePage activeTab={activeTab} onTabChange={setActiveTab} onCreatePlan={handleCreatePlan} />;
+      case "plan":
+        return (
+          <PlanPage
+            activeTab={activeTab}
+            onTabChange={setActiveTab}
+            newPlan={newPlan}
+            onNewPlanConsumed={handlePlanConsumed}
+          />
+        );
+      case "me":
+        return <MePage activeTab={activeTab} onTabChange={setActiveTab} />;
+      default:
+        return <MapHome activeTab={activeTab} onTabChange={setActiveTab} />;
+    }
+  };
+
+  return (
+    <div className="w-full max-w-[100vw] h-[100dvh] overflow-hidden relative">
+      {renderPage()}
+    </div>
+  );
+}

package/template/src/config/cdn.ts

@@ -0,0 +1,12 @@
+/**
+ * CDN 资源配置
+ * 图片托管在 GitHub，通过 jsDelivr CDN 全球加速访问
+ */
+
+const CDN_BASE =
+  "https://cdn.jsdelivr.net/gh/lmy910510/design-system-assets@main";
+
+/** 拼接 CDN 图片完整 URL */
+export function cdnImage(path: string): string {
+  return `${CDN_BASE}${path}`;
+}

package/template/src/index.css

@@ -0,0 +1,4 @@
+@import "@lmy54321/design-system/styles";
+
+@source "../src";
+@source "../node_modules/@lmy54321/design-system/dist";

package/template/src/main.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { BrowserRouter, Routes, Route } from "react-router-dom";
+import App from "./App";
+import { DevPortal } from "./pages/DevPortal";
+import { ComponentLibrary } from "./pages/ComponentLibrary";
+import { SyncTool } from "./pages/SyncTool";
+import { DeployPage } from "./pages/DeployPage";
+import "./index.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <Routes>
+        {/* 开发者入口（默认首页） */}
+        <Route path="/" element={<DevPortal />} />
+        {/* 开发者入口别名 */}
+        <Route path="/dev" element={<DevPortal />} />
+        {/* 组件库展示 */}
+        <Route path="/components" element={<ComponentLibrary />} />
+        {/* 规范同步 */}
+        <Route path="/sync" element={<SyncTool />} />
+        {/* 部署预览 */}
+        <Route path="/deploy" element={<DeployPage />} />
+        {/* Demo 手机预览内容（通配符放最后作为 fallback） */}
+        <Route path="/demo/*" element={<App />} />
+      </Routes>
+    </BrowserRouter>
+  </React.StrictMode>
+);