diff --git a/apps/design-lab/README.md b/apps/design-lab/README.md
new file mode 100644
index 0000000..5cbe56f
--- /dev/null
+++ b/apps/design-lab/README.md
@@ -0,0 +1,27 @@
+# Personal Brand Design Lab
+
+Design Lab 是内部设计生产工具,用 `DesignSpec` 生成可预览、可校验的移动端 HTML 设计稿。
+
+## 开发
+
+```bash
+pnpm --filter @personal-brand/design-lab dev
+```
+
+默认端口是 `3010`,可通过 `DESIGN_LAB_PORT` 覆盖。
+
+## 验证
+
+```bash
+pnpm --filter @personal-brand/design-spec test
+pnpm --filter @personal-brand/design-lab test
+pnpm --filter @personal-brand/design-spec typecheck
+pnpm --filter @personal-brand/design-lab typecheck
+pnpm --filter @personal-brand/design-lab build
+```
+
+## 边界
+
+- DesignSpec 是唯一源头。
+- HTML 是设计稿和转换依据,不直接进入线上项目。
+- Design Lab 不连接业务数据库,也不直接写入生产模板包。
diff --git a/apps/design-lab/index.html b/apps/design-lab/index.html
new file mode 100644
index 0000000..ebdddc8
--- /dev/null
+++ b/apps/design-lab/index.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+ Personal Brand Design Lab
+
+
+
+
+
+
diff --git a/apps/design-lab/package.json b/apps/design-lab/package.json
new file mode 100644
index 0000000..d732bee
--- /dev/null
+++ b/apps/design-lab/package.json
@@ -0,0 +1,24 @@
+{
+ "name": "@personal-brand/design-lab",
+ "private": true,
+ "type": "module",
+ "dependencies": {
+ "@personal-brand/design-spec": "workspace:*",
+ "react": "^19.3.0",
+ "react-dom": "^19.3.0"
+ },
+ "scripts": {
+ "dev": "vite",
+ "build": "vite build",
+ "test": "node --experimental-strip-types --test test/*.test.mjs",
+ "lint": "eslint .",
+ "typecheck": "tsc -p tsconfig.json --noEmit",
+ "clean": "rimraf dist"
+ },
+ "devDependencies": {
+ "@types/react": "^19.3.0",
+ "@types/react-dom": "^19.3.0",
+ "@vitejs/plugin-react": "^6.1.1",
+ "vite": "^8.3.0"
+ }
+}
diff --git a/apps/design-lab/src/App.css b/apps/design-lab/src/App.css
new file mode 100644
index 0000000..76733fe
--- /dev/null
+++ b/apps/design-lab/src/App.css
@@ -0,0 +1,74 @@
+:root {
+ font-family: system-ui, sans-serif;
+ color: #1f2328;
+ background: #f3f4f6;
+}
+
+body {
+ margin: 0;
+}
+
+.app {
+ display: grid;
+ grid-template-columns: minmax(360px, 34%) 1fr;
+ min-height: 100vh;
+}
+
+.app aside {
+ display: flex;
+ flex-direction: column;
+ gap: 16px;
+ padding: 20px;
+ background: #ffffff;
+ border-right: 1px solid #e5e7eb;
+}
+
+.app header {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+}
+
+textarea {
+ min-height: 420px;
+ resize: vertical;
+ border: 1px solid #d1d5db;
+ border-radius: 8px;
+ padding: 12px;
+ font-family: ui-monospace, monospace;
+ font-size: 13px;
+}
+
+button {
+ border: 0;
+ border-radius: 8px;
+ background: #111827;
+ color: #ffffff;
+ font-size: 14px;
+ padding: 10px 16px;
+}
+
+button:disabled {
+ background: #9ca3af;
+}
+
+.errors {
+ margin: 0;
+ padding-left: 20px;
+ color: #dc2626;
+ font-size: 13px;
+}
+
+main {
+ display: grid;
+ place-items: center;
+ padding: 32px;
+}
+
+iframe {
+ width: 375px;
+ height: 720px;
+ border: 1px solid #d1d5db;
+ border-radius: 24px;
+ background: #ffffff;
+}
diff --git a/apps/design-lab/src/App.tsx b/apps/design-lab/src/App.tsx
new file mode 100644
index 0000000..05a5235
--- /dev/null
+++ b/apps/design-lab/src/App.tsx
@@ -0,0 +1,57 @@
+import { useMemo, useState } from "react";
+import {
+ DESIGN_SPEC_VERSION,
+ renderDesignSpec,
+ validateDesignSpec,
+ type DesignSpec,
+} from "@personal-brand/design-spec";
+import { sampleSpec } from "./samples";
+import "./App.css";
+
+function App() {
+ const [specText, setSpecText] = useState(JSON.stringify(sampleSpec, null, 2));
+ const [previewSrcDoc, setPreviewSrcDoc] = useState(() => renderDesignSpec(sampleSpec));
+
+ const parsed = useMemo(() => {
+ try {
+ return { value: JSON.parse(specText) as DesignSpec };
+ } catch (error) {
+ return { error: error instanceof Error ? error.message : "JSON 解析失败" };
+ }
+ }, [specText]);
+ const errors = "value" in parsed ? validateDesignSpec(parsed.value) : [parsed.error];
+
+ function handleRender() {
+ if (!("value" in parsed) || validateDesignSpec(parsed.value).length > 0) return;
+ setPreviewSrcDoc(renderDesignSpec(parsed.value));
+ }
+
+ return (
+
+
+
+
+
+
+ );
+}
+
+export default App;
diff --git a/apps/design-lab/src/main.tsx b/apps/design-lab/src/main.tsx
new file mode 100644
index 0000000..f8fc6f5
--- /dev/null
+++ b/apps/design-lab/src/main.tsx
@@ -0,0 +1,9 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+
+createRoot(document.getElementById("root")!).render(
+
+
+ ,
+);
diff --git a/apps/design-lab/src/samples.ts b/apps/design-lab/src/samples.ts
new file mode 100644
index 0000000..229ff15
--- /dev/null
+++ b/apps/design-lab/src/samples.ts
@@ -0,0 +1,35 @@
+import { DESIGN_SPEC_VERSION, type DesignSpec } from "@personal-brand/design-spec";
+
+export const sampleSpec: DesignSpec = {
+ version: DESIGN_SPEC_VERSION,
+ templateKey: "acheng-campus-food",
+ displayName: "阿成校园餐",
+ tone: "干净、亲切、可信",
+ theme: {
+ primaryColor: "#f2683c",
+ backgroundColor: "#f7f7f4",
+ surfaceColor: "#ffffff",
+ textColor: "#1f2328",
+ mutedTextColor: "#6b7280",
+ borderRadius: 16,
+ },
+ sections: [
+ {
+ type: "hero",
+ title: "每天现做的校园餐",
+ content: ["周三到周日供应", "下单后统一配送"],
+ action: "查看菜单",
+ },
+ {
+ type: "services",
+ title: "供应方式",
+ content: ["单餐预订", "周餐预订", "宿舍团购"],
+ },
+ {
+ type: "contact",
+ title: "联系阿成",
+ content: ["微信预约", "当天 16:00 截单"],
+ action: "提交预约",
+ },
+ ],
+};
diff --git a/apps/design-lab/test/render.test.mjs b/apps/design-lab/test/render.test.mjs
new file mode 100644
index 0000000..ff0085a
--- /dev/null
+++ b/apps/design-lab/test/render.test.mjs
@@ -0,0 +1,11 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { renderDesignSpec } from "@personal-brand/design-spec";
+import { sampleSpec } from "../src/samples.ts";
+
+test("sample renders a design preview", () => {
+ const html = renderDesignSpec(sampleSpec);
+ assert.match(html, /data-template-section="contact"/);
+ assert.match(html, /data-action="contact"/);
+});
diff --git a/apps/design-lab/tsconfig.json b/apps/design-lab/tsconfig.json
new file mode 100644
index 0000000..aa11716
--- /dev/null
+++ b/apps/design-lab/tsconfig.json
@@ -0,0 +1,13 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "jsx": "react-jsx",
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "noEmit": true,
+ "types": ["vite/client"]
+ },
+ "include": ["src", "test", "vite.config.ts"]
+}
diff --git a/apps/design-lab/vite.config.ts b/apps/design-lab/vite.config.ts
new file mode 100644
index 0000000..ccf6e3a
--- /dev/null
+++ b/apps/design-lab/vite.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+ plugins: [react()],
+ server: {
+ host: "0.0.0.0",
+ port: Number(process.env.DESIGN_LAB_PORT ?? 3010),
+ },
+});
diff --git a/docs/adr/0028-design-lab-boundaries.md b/docs/adr/0028-design-lab-boundaries.md
new file mode 100644
index 0000000..315ba3b
--- /dev/null
+++ b/docs/adr/0028-design-lab-boundaries.md
@@ -0,0 +1,43 @@
+# 0028. Design Lab 边界与设计中间层
+
+## Context
+
+Stitch 不再可用,但产品仍需要把客户需求转化为可预览的小程序设计稿,并保留足够结构化的信息供后续 AI 或确定性工具转换。直接把图片转成 HTML 的保真度不足;直接生成自由 React 代码会破坏现有模板系统和管理端边界。
+
+## Decision
+
+- Design Lab 在当前 monorepo 内实现,暂不新开仓库。
+- `packages/design-spec` 是唯一设计源头,定义 `DesignSpec`、校验器和 HTML renderer。
+- `apps/design-lab` 是独立内部工具,只负责编辑 DesignSpec、展示校验结果和渲染预览。
+- DesignSpec 只允许使用受控 section 类型与设计 token,不允许描述数据库访问或小程序实现细节。
+- 渲染出的 HTML 是设计稿和机器可读中间层,必须携带 `data-template-section`、`data-field`、`data-action` 标注。
+- Design Lab 第一阶段不直接修改生产模板包,也不直接连接 API 数据库。
+
+## Alternatives
+
+1. 新建独立仓库:共享 schema 与工程门槛成本更高,等出现独立产品化边界后再拆。
+2. 放入 Admin:会让后台管理职责和设计生产工具耦合,增加后台 bundle 与权限复杂度。
+3. 直接生成 React / Taro:容易形成第二套 UI 架构,也无法稳定保证字段契约。
+4. 图片直接转 HTML:缺少语义结构,保真度和可回溯性不足。
+
+## Consequences
+
+### Positive
+
+- 设计可以版本化、校验和回滚。
+- HTML 对 AI 转换友好,同时保留人可预览的视觉结果。
+- 设计工具与线上管理系统、模板包保持隔离。
+- 后续可以扩展截图、视觉回归和 manifest 生成,而不改变源头模型。
+
+### Negative
+
+- 第一版只能覆盖受限 section 和设计 token,无法表达任意视觉稿。
+- 需要 DesignSpec schema 与模板 manifest 的映射文档持续维护。
+- 多一个内部应用,需要纳入全局检查流程。
+
+## Migration Plan
+
+1. 先提供 DesignSpec schema、校验器、HTML renderer 和基础工作台。
+2. 加入 Playwright 截图与视觉检查,形成可归档的设计稿。
+3. 补充 DesignSpec 到 template manifest / Taro 模板的半自动转换流程。
+4. 用至少两个真实行业需求验证完整链路后,再考虑持久化和多人协作。
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 4bb5779..f4bad7e 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -12,6 +12,9 @@ export default tseslint.config(
"apps/api/test/**/*.test.js",
"apps/api/test/**/*.cjs",
"apps/admin/test/**/*.test.mjs",
+ "packages/design-spec/test/**/*.test.mjs",
+ "apps/design-lab/test/**/*.test.mjs",
+ "apps/design-lab/vite.config.ts",
"apps/admin/public/**",
"packages/types/test/**/*.test.mjs",
"apps/taro/test/**/*.test.mjs",
diff --git a/package.json b/package.json
index abd3417..328e40a 100644
--- a/package.json
+++ b/package.json
@@ -13,7 +13,7 @@
"typecheck": "turbo run typecheck",
"format": "prettier --write .",
"format:check": "prettier --check .",
- "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm template:check",
+ "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test:design-lab && pnpm template:check",
"db:migrate": "pnpm --filter @personal-brand/api db:migrate",
"db:seed": "pnpm --filter @personal-brand/api db:seed",
"test:api-client": "pnpm --filter @personal-brand/api exec tsx --test ../../packages/api-client/test/**/*.test.ts",
@@ -38,6 +38,7 @@
"build:taro:food": "pnpm --filter @personal-brand/taro build:h5 && pnpm --filter @personal-brand/taro build:weapp",
"build:taro:linjing": "TEMPLATE_KEY=linjing-editorial pnpm --filter @personal-brand/taro build:h5 && TEMPLATE_KEY=linjing-editorial pnpm --filter @personal-brand/taro build:weapp",
"template:doctor": "node scripts/template-doctor.mjs",
+ "test:design-lab": "pnpm --filter @personal-brand/design-spec test && pnpm --filter @personal-brand/design-lab test",
"check:local-media": "node scripts/check-local-media.mjs",
"test:template-doctor": "node --test scripts/test/template-doctor.test.mjs"
},
diff --git a/packages/design-spec/README.md b/packages/design-spec/README.md
new file mode 100644
index 0000000..e90bcb1
--- /dev/null
+++ b/packages/design-spec/README.md
@@ -0,0 +1,11 @@
+# Design Spec
+
+DesignSpec 是 Design Lab 的唯一设计源头。它描述品牌信息、设计 token 和受限 section 结构,不包含业务数据库访问或小程序实现细节。
+
+当前能力:
+
+- `DesignSpec` TypeScript 契约
+- `validateDesignSpec` 结构校验
+- `renderDesignSpec` 生成带 `data-template-section` / `data-field` / `data-action` 标注的移动端 HTML
+
+输出 HTML 只作为设计稿和转换依据,不直接复制进线上项目。
diff --git a/packages/design-spec/package.json b/packages/design-spec/package.json
new file mode 100644
index 0000000..76f386b
--- /dev/null
+++ b/packages/design-spec/package.json
@@ -0,0 +1,14 @@
+{
+ "name": "@personal-brand/design-spec",
+ "version": "0.1.0",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "scripts": {
+ "typecheck": "tsc -p tsconfig.json --noEmit",
+ "lint": "eslint .",
+ "test": "node --experimental-strip-types --test test/*.test.mjs"
+ }
+}
diff --git a/packages/design-spec/src/index.ts b/packages/design-spec/src/index.ts
new file mode 100644
index 0000000..717a012
--- /dev/null
+++ b/packages/design-spec/src/index.ts
@@ -0,0 +1,103 @@
+export const DESIGN_SPEC_VERSION = "0.1" as const;
+
+export type DesignSpecSectionType =
+ | "hero"
+ | "positioning"
+ | "biography"
+ | "credentials"
+ | "portfolio"
+ | "services"
+ | "process"
+ | "expectations"
+ | "availability"
+ | "contact";
+
+export type DesignSpecSection = {
+ type: DesignSpecSectionType;
+ title: string;
+ content?: string[];
+ action?: string;
+};
+
+export type DesignSpec = {
+ version: typeof DESIGN_SPEC_VERSION;
+ templateKey: string;
+ displayName: string;
+ tone: string;
+ theme: {
+ primaryColor: string;
+ backgroundColor: string;
+ surfaceColor: string;
+ textColor: string;
+ mutedTextColor: string;
+ borderRadius: number;
+ };
+ sections: DesignSpecSection[];
+};
+
+const SECTION_TYPES: DesignSpecSectionType[] = [
+ "hero",
+ "positioning",
+ "biography",
+ "credentials",
+ "portfolio",
+ "services",
+ "process",
+ "expectations",
+ "availability",
+ "contact",
+];
+
+const HEX_COLOR_PATTERN = /^#[0-9a-f]{6}$/i;
+
+export function validateDesignSpec(value: unknown): string[] {
+ const errors: string[] = [];
+ if (!value || typeof value !== "object") return ["DesignSpec must be an object"];
+
+ const spec = value as Partial;
+ if (spec.version !== DESIGN_SPEC_VERSION) errors.push(`version must be ${DESIGN_SPEC_VERSION}`);
+ if (!spec.templateKey?.trim()) errors.push("templateKey is required");
+ if (!spec.displayName?.trim()) errors.push("displayName is required");
+ if (!spec.tone?.trim()) errors.push("tone is required");
+
+ if (!spec.theme || typeof spec.theme !== "object") {
+ errors.push("theme is required");
+ } else {
+ const theme = spec.theme;
+ for (const key of [
+ "primaryColor",
+ "backgroundColor",
+ "surfaceColor",
+ "textColor",
+ "mutedTextColor",
+ ] as const) {
+ if (!HEX_COLOR_PATTERN.test(theme[key] ?? ""))
+ errors.push(`theme.${key} must be a six-digit hex color`);
+ }
+ if (!Number.isFinite(theme.borderRadius) || theme.borderRadius < 0 || theme.borderRadius > 32)
+ errors.push("theme.borderRadius must be between 0 and 32");
+ }
+
+ if (!Array.isArray(spec.sections) || !spec.sections.length)
+ errors.push("sections must not be empty");
+ else {
+ const sectionTypes = new Set();
+ spec.sections.forEach((section, index) => {
+ const prefix = `sections.${index}`;
+ if (!section || typeof section !== "object") {
+ errors.push(`${prefix} must be an object`);
+ return;
+ }
+ if (!SECTION_TYPES.includes(section.type)) errors.push(`${prefix}.type is invalid`);
+ if (!section.title?.trim()) errors.push(`${prefix}.title is required`);
+ if (section.content !== undefined && !Array.isArray(section.content))
+ errors.push(`${prefix}.content must be an array`);
+ if (section.type === "contact") sectionTypes.add(section.type);
+ });
+ if (!sectionTypes.has("contact")) errors.push("sections must include a contact section");
+ }
+
+ return errors;
+}
+
+export { renderDesignSpec } from "./render.ts";
diff --git a/packages/design-spec/src/render.ts b/packages/design-spec/src/render.ts
new file mode 100644
index 0000000..da03280
--- /dev/null
+++ b/packages/design-spec/src/render.ts
@@ -0,0 +1,62 @@
+import type { DesignSpec } from "./index.ts";
+
+function escapeHtml(value: string): string {
+ return value
+ .replaceAll("&", "&")
+ .replaceAll("<", "<")
+ .replaceAll(">", ">")
+ .replaceAll('"', """);
+}
+
+export function renderDesignSpec(spec: DesignSpec): string {
+ const sections = spec.sections
+ .map((section) => {
+ const content = (section.content ?? [])
+ .map((item) => `${escapeHtml(item)}
`)
+ .join("");
+ const action = section.action
+ ? ``
+ : "";
+ return `${escapeHtml(section.title)}
${content}${action}`;
+ })
+ .join("");
+
+ return `
+
+
+
+
+ ${escapeHtml(spec.displayName)}
+
+
+
+
+
+ ${escapeHtml(spec.displayName)}
+ ${escapeHtml(spec.tone)}
+
+ ${sections}
+
+
+`;
+}
diff --git a/packages/design-spec/test/design-spec.test.mjs b/packages/design-spec/test/design-spec.test.mjs
new file mode 100644
index 0000000..e5070b4
--- /dev/null
+++ b/packages/design-spec/test/design-spec.test.mjs
@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { DESIGN_SPEC_VERSION, validateDesignSpec } from "../src/index.ts";
+import { renderDesignSpec } from "../src/render.ts";
+
+const validSpec = {
+ version: DESIGN_SPEC_VERSION,
+ templateKey: "acheng-campus-food",
+ displayName: "阿成校园餐",
+ tone: "干净、亲切、可信",
+ theme: {
+ primaryColor: "#f2683c",
+ backgroundColor: "#f7f7f4",
+ surfaceColor: "#ffffff",
+ textColor: "#1f2328",
+ mutedTextColor: "#6b7280",
+ borderRadius: 16,
+ },
+ sections: [
+ { type: "hero", title: "每天现做的校园餐", content: ["周三到周日供应"], action: "查看菜单" },
+ { type: "services", title: "供应方式", content: ["单餐预订", "周餐预订"] },
+ { type: "contact", title: "联系阿成", content: ["微信预约"] },
+ ],
+};
+
+test("accepts a valid DesignSpec", () => {
+ assert.deepEqual(validateDesignSpec(validSpec), []);
+});
+
+test("requires a contact section", () => {
+ const errors = validateDesignSpec({ ...validSpec, sections: validSpec.sections.slice(0, 2) });
+ assert.equal(errors.includes("sections must include a contact section"), true);
+});
+
+test("renders machine-readable HTML", () => {
+ const html = renderDesignSpec(validSpec);
+ assert.match(html, /data-template-section="hero"/);
+ assert.match(html, /data-field="displayName"/);
+ assert.match(html, /data-action="hero"/);
+});
diff --git a/packages/design-spec/tsconfig.json b/packages/design-spec/tsconfig.json
new file mode 100644
index 0000000..816dd1b
--- /dev/null
+++ b/packages/design-spec/tsconfig.json
@@ -0,0 +1,9 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "allowJs": true,
+ "allowImportingTsExtensions": true,
+ "noEmit": true
+ },
+ "include": ["src/**/*.ts", "test/**/*.mjs"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index feddc4c..32a7f74 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -134,6 +134,31 @@ importers:
specifier: ^4.19.2
version: 4.23.13
+ apps/design-lab:
+ dependencies:
+ '@personal-brand/design-spec':
+ specifier: workspace:*
+ version: link:../../packages/design-spec
+ react:
+ specifier: ^19.3.0
+ version: 19.3.0
+ react-dom:
+ specifier: ^19.3.0
+ version: 19.3.0(react@19.3.0)
+ devDependencies:
+ '@types/react':
+ specifier: ^19.3.0
+ version: 19.3.0
+ '@types/react-dom':
+ specifier: ^19.3.0
+ version: 19.3.0(@types/react@19.3.0)
+ '@vitejs/plugin-react':
+ specifier: ^6.1.1
+ version: 6.1.1(vite@8.3.0(@types/node@22.20.3)(esbuild@0.28.2)(jiti@2.7.0)(less@4.5.1)(sass@1.105.1)(terser@5.51.2)(tsx@4.23.13)(yaml@2.9.1))
+ vite:
+ specifier: ^8.3.0
+ version: 8.3.0(@types/node@22.20.3)(esbuild@0.28.2)(jiti@2.7.0)(less@4.5.1)(sass@1.105.1)(terser@5.51.2)(tsx@4.23.13)(yaml@2.9.1)
+
apps/miniapp:
dependencies:
'@personal-brand/api-client':
@@ -226,6 +251,8 @@ importers:
packages/config: {}
+ packages/design-spec: {}
+
packages/template-acheng-campus-food:
dependencies:
'@personal-brand/types':