@lmy54321/design-system 1.1.3 → 1.2.0

package/{rules → .codebuddy/rules}/design-system.mdc

@@ -10,6 +10,34 @@ provider:
 
 本项目使用团队设计系统 `@lmy54321/design-system`，所有 UI 开发必须优先使用该组件库。
 
+## 用户画像与交互原则
+
+> **核心原则：本设计系统的目标用户是纯设计师，没有编程背景。**
+
+### 必须遵守的交互规范
+
+1. **完全可视化操作** — 所有功能必须通过界面点击完成，禁止要求用户输入命令行指令
+2. **零代码门槛** — 不要让用户手动编辑代码文件、配置文件或 JSON
+3. **直观的交互方式** — 优先使用拖拽、点击、下拉选择等图形化操作
+4. **友好的文案** — 避免技术术语（如 "npm"、"diff"、"merge"），使用设计师能理解的语言
+
+### AI 生成代码时的注意事项
+
+- 当需要文件操作时，**自动完成**，不要告诉用户去执行命令
+- 当遇到冲突或选择时，**提供可视化界面**让用户点击选择，而非要求手动操作
+- 当解释功能时，**用界面截图或示意图**而非代码片段
+- 错误提示要**友好清晰**，告诉用户如何通过界面解决，而非给出技术排查步骤
+
+### 禁止的交互方式
+
+| 禁止 | 替代方案 |
+|------|----------|
+| 要求用户运行命令行指令 | AI 自动执行，或提供一键操作按钮 |
+| 要求用户手动对比代码差异 | 提供可视化对比界面 |
+| 要求用户手动编辑配置文件 | 提供设置面板，点击切换选项 |
+| 输出大段代码让用户复制粘贴 | AI 直接写入文件，用户只需确认 |
+| 使用技术术语解释问题 | 用通俗语言 + 图示说明 |
+
 ## 可用组件清单
 
 生成 UI 代码时，**必须优先**从以下组件中选用，禁止重复造轮子：

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

@@ -0,0 +1,127 @@
+---
+description: 当用户说"初始化项目"、"新建项目"、"搭建项目"、"项目初始化"时触发，自动完成 React + Vite + 团队设计系统的完整初始化。
+alwaysApply: false
+enabled: true
+updatedAt: 2026-03-02T10:03:20.525Z
+provider: 
+---
+
+# 项目一键初始化流程
+
+当用户说「初始化项目」「新建项目」「搭建项目」时，按以下步骤自动执行，**无需用户确认每一步**：
+
+## 环境要求
+
+- **Node.js >= 18**（Vite 5+ 和 Tailwind CSS 4 均要求 Node 18 以上）
+
+## 自动执行步骤
+
+### 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
+```
+如果当前目录已有 package.json，则跳过此步。
+
+### 2. 安装依赖
+```bash
+npm install
+npm install @lmy54321/design-system
+npm install tailwindcss @tailwindcss/vite
+npm install react-router-dom motion
+```
+
+### 3. 同步设计系统 AI 规则
+将 npm 包中附带的 CodeBuddy 规则文件复制到项目的 `.codebuddy/rules/` 目录，确保 AI 辅助开发时能识别组件库规范：
+```bash
+mkdir -p .codebuddy/rules
+cp node_modules/@lmy54321/design-system/.codebuddy/rules/design-system.mdc .codebuddy/rules/design-system.mdc
+cp node_modules/@lmy54321/design-system/.codebuddy/rules/init-project.mdc .codebuddy/rules/init-project.mdc
+```
+
+> **说明：** 规则文件随 npm 包版本同步发布，每次升级设计系统版本后应重新执行此复制命令以获取最新规范。`init-project.mdc` 也会被复制，这样项目后续可以再次执行初始化或帮助其他同事同步规则。
+
+### 4. 复制完整 Demo 模板
+
+设计系统 npm 包中内置了完整的 Demo 项目模板（地图首页、探索页、行程规划、个人中心、开发者入口、组件库展示等），直接复制即可运行。
+
+**模板会覆盖 Vite 默认文件**（`vite.config.ts`、`tsconfig.json`、`index.html`、`src/` 下的所有文件），已包含正确的 Tailwind + 设计系统样式配置，无需手动修改：
+
+```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 等）
+cp -r node_modules/@lmy54321/design-system/template/public/* public/ 2>/dev/null || true
+
+# 删除 Vite 默认生成的无用文件
+rm -f src/App.css src/assets/react.svg public/vite.svg
+```
+
+> **说明：** 模板包含以下路由页面，启动后可通过浏览器访问：
+> - `/` — Demo 首页（手机预览效果，含地图首页、探索、行程、我的四个 Tab）
+> - `/dev` — 开发者入口（四个功能卡片导航）
+> - `/components` — 组件库交互式展示
+> - `/sync` — 规范同步工具
+> - `/deploy` — 部署预览
+>
+> **注意：** 模板中的 `src/index.css` 已配置好样式导入，不需要手动修改。不要在其中单独写 `@import "tailwindcss"`，设计系统样式内部已包含 Tailwind 初始化。
+
+### 7. 启动开发服务器
+```bash
+npm run dev
+```
+
+### 6. 完成后告诉用户
+告诉用户：
+
+「项目已初始化完成！已加载完整的 Demo 项目，包含多个示例页面。
+
+**访问地址：**
+- 首页（手机预览）：http://localhost:5173/
+- 开发者入口：http://localhost:5173/dev
+- 组件库：http://localhost:5173/components
+
+你可以在这些 Demo 的基础上修改，或者描述你想要的新页面。」

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lmy54321/design-system",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "A comprehensive React component library and design system based on Tailwind CSS and Motion.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -12,13 +12,15 @@
       "require": "./dist/index.js"
     },
     "./styles": "./styles/globals.css",
-    "./rules/*": "./rules/*"
+    "./rules/*": "./.codebuddy/rules/*"
   },
   "sideEffects": false,
   "files": [
     "dist",
     "styles",
-    "rules"
+    "template",
+    ".codebuddy/rules/design-system.mdc",
+    ".codebuddy/rules/init-project.mdc"
   ],
   "scripts": {
     "dev": "vite",
@@ -38,6 +40,7 @@
     "clsx": "^2.1.0",
     "lucide-react": "^0.330.0",
     "motion": "^12.0.0",
+    "react-router-dom": "^7.13.1",
     "tailwind-merge": "^2.2.1",
     "tdesign-icons-react": "^0.6.2"
   },

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/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,28 @@
+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>
+        {/* Demo 首页 — 手机预览的内容 */}
+        <Route path="/*" element={<App />} />
+        {/* 开发者入口 */}
+        <Route path="/dev" element={<DevPortal />} />
+        {/* 组件库展示 */}
+        <Route path="/components" element={<ComponentLibrary />} />
+        {/* 规范同步 */}
+        <Route path="/sync" element={<SyncTool />} />
+        {/* 部署预览 */}
+        <Route path="/deploy" element={<DeployPage />} />
+      </Routes>
+    </BrowserRouter>
+  </React.StrictMode>
+);