Compare commits

...
Author SHA1 Message Date
que01 083a323c1f feat: 搭建设计生成工作台骨架 2026-10-15 15:54:21 +08:00
20 changed files with 587 additions and 1 deletions

No files matched your search

+27
View File
@@ -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 不连接业务数据库,也不直接写入生产模板包。
+12
View File
@@ -0,0 +1,12 @@
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Personal Brand Design Lab</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
+24
View File
@@ -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"
}
}
+74
View File
@@ -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;
}
+57
View File
@@ -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 (
<div className="app">
<aside>
<header>
<strong>Design Lab</strong>
<span>DesignSpec v{DESIGN_SPEC_VERSION}</span>
</header>
<textarea
value={specText}
spellCheck={false}
onChange={(event) => setSpecText(event.target.value)}
/>
<button type="button" onClick={handleRender} disabled={errors.length > 0}>
生成设计稿
</button>
<ul className="errors">
{errors.map((error) => (
<li key={error}>{error}</li>
))}
</ul>
</aside>
<main>
<iframe title="设计稿预览" srcDoc={previewSrcDoc} />
</main>
</div>
);
}
export default App;
+9
View File
@@ -0,0 +1,9 @@
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<App />
</StrictMode>,
);
+35
View File
@@ -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: "提交预约",
},
],
};
+11
View File
@@ -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"/);
});
+13
View File
@@ -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"]
}
+10
View File
@@ -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),
},
});
+43
View File
@@ -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. 用至少两个真实行业需求验证完整链路后,再考虑持久化和多人协作。
+3
View File
@@ -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",
+2 -1
View File
@@ -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"
},
+11
View File
@@ -0,0 +1,11 @@
# Design Spec
DesignSpec 是 Design Lab 的唯一设计源头。它描述品牌信息、设计 token 和受限 section 结构,不包含业务数据库访问或小程序实现细节。
当前能力:
- `DesignSpec` TypeScript 契约
- `validateDesignSpec` 结构校验
- `renderDesignSpec` 生成带 `data-template-section` / `data-field` / `data-action` 标注的移动端 HTML
输出 HTML 只作为设计稿和转换依据,不直接复制进线上项目。
+14
View File
@@ -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"
}
}
+103
View File
@@ -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<DesignSpec>;
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<string>();
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";
+62
View File
@@ -0,0 +1,62 @@
import type { DesignSpec } from "./index.ts";
function escapeHtml(value: string): string {
return value
.replaceAll("&", "&amp;")
.replaceAll("<", "&lt;")
.replaceAll(">", "&gt;")
.replaceAll('"', "&quot;");
}
export function renderDesignSpec(spec: DesignSpec): string {
const sections = spec.sections
.map((section) => {
const content = (section.content ?? [])
.map((item) => `<p data-field="content">${escapeHtml(item)}</p>`)
.join("");
const action = section.action
? `<button type="button" data-action="${escapeHtml(section.type)}">${escapeHtml(section.action)}</button>`
: "";
return `<section data-template-section="${escapeHtml(section.type)}"><h2 data-field="title">${escapeHtml(section.title)}</h2>${content}${action}</section>`;
})
.join("");
return `<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>${escapeHtml(spec.displayName)}</title>
<style>
:root {
--color-primary: ${spec.theme.primaryColor};
--color-bg: ${spec.theme.backgroundColor};
--color-surface: ${spec.theme.surfaceColor};
--color-text: ${spec.theme.textColor};
--color-muted: ${spec.theme.mutedTextColor};
--radius: ${spec.theme.borderRadius}px;
}
* { box-sizing: border-box; }
body { margin: 0; background: var(--color-bg); color: var(--color-text); font-family: system-ui, sans-serif; }
main { max-width: 375px; margin: 0 auto; padding: 24px 20px 48px; }
header { padding: 12px 0 28px; }
h1 { font-size: 28px; margin: 0; }
header p { color: var(--color-muted); margin: 8px 0 0; }
section { background: var(--color-surface); border-radius: var(--radius); padding: 20px; margin-bottom: 16px; }
h2 { font-size: 17px; margin: 0 0 12px; }
p { color: var(--color-muted); font-size: 14px; line-height: 1.7; margin: 0 0 10px; }
p:last-of-type { margin-bottom: 0; }
button { background: var(--color-primary); color: #fff; border: 0; border-radius: var(--radius); padding: 10px 16px; font-size: 14px; margin-top: 12px; }
</style>
</head>
<body>
<main>
<header>
<h1 data-field="displayName">${escapeHtml(spec.displayName)}</h1>
<p data-field="tone">${escapeHtml(spec.tone)}</p>
</header>
${sections}
</main>
</body>
</html>`;
}
@@ -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"/);
});
+9
View File
@@ -0,0 +1,9 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"allowJs": true,
"allowImportingTsExtensions": true,
"noEmit": true
},
"include": ["src/**/*.ts", "test/**/*.mjs"]
}
+27
View File
@@ -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':