diff --git a/.gitignore b/.gitignore index 36998c47f..5c3515263 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,16 @@ dist .DS_Store *.log .vite + +# Local runtime data — auto-created by the daemon on first start. +# Holds app.sqlite (project metadata), projects// (per-project artifacts, +# the agent's CWD), and artifacts/ (one-off renders). Never commit. +.od + +# Legacy folder name from before the rename; keep ignored so existing +# clones don't accidentally stage stale runtime data. .ocd + tsconfig.tsbuildinfo .claude-sessions/* \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..410916487 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,266 @@ +# Contributing to Open Design + +Thanks for thinking about contributing. OD is small on purpose — most of the value lives in **files** (skills, design systems, prompt fragments) rather than framework code. That means the highest-leverage contributions are usually one folder, one Markdown file, or one PR-sized adapter. + +This guide tells you exactly where to look for each type of contribution and what bar a PR has to clear before we merge it. + +

English · 简体中文

+ +--- + +## Three things you can ship in one afternoon + +| If you want to… | You're really adding | Where it lives | Ship size | +|---|---|---|---| +| Make OD render a new kind of artifact (an invoice, an iOS Settings screen, a one-pager…) | a **Skill** | [`skills//`](skills/) | one folder, ~2 files | +| Make OD speak a new brand's visual language | a **Design System** | [`design-systems//DESIGN.md`](design-systems/) | one Markdown file | +| Hook up a new coding-agent CLI | an **Agent adapter** | [`daemon/agents.js`](daemon/agents.js) | ~10 lines in one array | +| Add a feature, fix a bug, lift a UX pattern from [`open-codesign`][ocod] | code | `src/`, `daemon/` | normal PR | +| Improve docs, port a section to 中文, fix typos | docs | `README.md`, `README.zh-CN.md`, `docs/`, `QUICKSTART.md` | one PR | + +If you're not sure which bucket your idea is in, [open a discussion / issue first](https://github.com/nexu-io/open-design/issues/new) and we'll point you at the right surface. + +--- + +## Local setup + +The full one-page setup lives in [`QUICKSTART.md`](QUICKSTART.md). The TL;DR for contributors: + +```bash +git clone https://github.com/nexu-io/open-design.git +cd open-design +pnpm install # or npm install +pnpm dev:all # daemon (:7456) + Vite (:5173) +pnpm typecheck # tsc -b --noEmit +pnpm build # production build +``` + +Node 18+ is required. macOS, Linux, and WSL2 are tested daily. Windows native should work but isn't a primary target — file an issue if it doesn't. + +You don't need any agent CLI on your `PATH` to develop OD itself — the daemon will tell you "no agents found" and fall back to the **Anthropic API · BYOK** path, which is the fastest dev loop anyway. + +--- + +## Adding a new Skill + +A skill is a folder under [`skills/`](skills/) with a `SKILL.md` at the root, following Claude Code's [`SKILL.md` convention][skill] plus our optional `od:` extension. **No registration step.** Drop the folder in, restart the daemon, the picker shows it. + +### Skill folder layout + +```text +skills/your-skill/ +├── SKILL.md # required +├── assets/template.html # optional but recommended — the seed file +├── references/ # optional — knowledge files the agent reads +│ ├── layouts.md +│ ├── components.md +│ └── checklist.md +└── example.html # strongly recommended — a real, hand-built sample +``` + +### `SKILL.md` frontmatter + +The first three keys are the Claude Code base spec — `name`, `description`, `triggers`. Everything under `od:` is OD-specific and optional, but **`od.mode`** decides which group the skill shows up in (Prototype / Deck / Template / Design system). + +```yaml +--- +name: your-skill +description: | + One-paragraph elevator pitch. The agent reads this verbatim to decide + if the user's brief matches. Be concrete: surface, audience, what's in + the artifact, what's not. +triggers: + - "your trigger phrase" + - "another phrase" + - "中文触发词" +od: + mode: prototype # prototype | deck | template | design-system + platform: desktop # desktop | mobile + scenario: marketing # free-form tag for grouping + featured: 1 # any positive integer surfaces it under "Showcase examples" + preview: + type: html # html | jsx | pptx | markdown + entry: index.html + design_system: + requires: true # does the skill read the active DESIGN.md? + sections: [color, typography, layout, components] + example_prompt: "A copy-pastable prompt that nicely shows what this skill does." +--- + +# Your Skill + +Body is free-form Markdown describing the workflow the agent should follow… +``` + +The full grammar — typed inputs, slider parameters, capability gating — lives in [`docs/skills-protocol.md`](docs/skills-protocol.md). + +### Bar for merging a new skill + +We're picky about skills because they're the user-facing surface. A new skill must: + +1. **Ship a real `example.html`.** Hand-built, opens straight from disk, looks like something a designer would actually deliver. No lorem ipsum, no `` placeholder hero. If you can't build the example yourself, the skill probably isn't ready. +2. **Pass the anti-AI-slop checklist** in the body. No purple gradients, no generic emoji icons, no rounded card with a left-border accent, no Inter as a *display* face, no invented stats. Read the **Anti-AI-slop machinery** section of the README for the full list. +3. **Honest placeholders.** When the agent doesn't have a real number, write `—` or a labelled grey block, not "10× faster". +4. **Have a `references/checklist.md`** with at least P0 gates (the stuff the agent has to pass before emitting ``). Lift the format from [`skills/guizang-ppt/references/checklist.md`](skills/guizang-ppt/) or [`skills/dating-web/references/checklist.md`](skills/dating-web/). +5. **Add a screenshot** at `docs/screenshots/skills/.png` if the skill is featured. PNG, ~1024×640 retina, captured from the real `example.html` at zoomed-out browser scale. +6. **Be a single self-contained folder.** No CDN imports beyond what other skills already use; no fonts you didn't license; no images larger than ~250 KB. + +If you fork an existing skill (e.g. start from `dating-web` and remix into a `recruiting-web`), keep the original LICENSE and authorship in `references/` and call it out in your PR description. + +### Skills that already ship — pick one to imitate + +- Visual showcase, single-screen prototype: [`skills/dating-web/`](skills/dating-web/), [`skills/digital-eguide/`](skills/digital-eguide/) +- Multi-frame mobile flow: [`skills/mobile-onboarding/`](skills/mobile-onboarding/), [`skills/gamified-app/`](skills/gamified-app/) +- Document / template (no design system required): [`skills/pm-spec/`](skills/pm-spec/), [`skills/weekly-update/`](skills/weekly-update/) +- Deck mode: [`skills/guizang-ppt/`](skills/guizang-ppt/) (bundled verbatim from [op7418/guizang-ppt-skill][guizang]) and [`skills/simple-deck/`](skills/simple-deck/) + +--- + +## Adding a new Design System + +A design system is a single [`DESIGN.md`](design-systems/README.md) file under `design-systems//`. **One file, no code.** Drop it in, restart the daemon, the picker shows it grouped by category. + +### Design system folder layout + +```text +design-systems/your-brand/ +└── DESIGN.md +``` + +### `DESIGN.md` shape + +```markdown +# Design System Inspired by YourBrand + +> Category: Developer Tools +> One-line summary that shows in the picker preview. + +## 1. Visual Theme & Atmosphere +… + +## 2. Color +- Primary: `#hex` / `oklch(...)` +- … + +## 3. Typography +… + +## 4. Spacing & Grid +## 5. Layout & Composition +## 6. Components +## 7. Motion & Interaction +## 8. Voice & Brand +## 9. Anti-patterns +``` + +The 9-section schema is fixed — that's what skill bodies grep for. The first H1 becomes the picker label (the `Design System Inspired by` prefix is stripped automatically), and the `> Category: …` line decides which group it lands in. Existing categories are listed in [`design-systems/README.md`](design-systems/README.md); if your brand truly doesn't fit, you can introduce a new one, but **try existing categories first**. + +### Bar for merging a new design system + +1. **All 9 sections present.** Empty section bodies are fine for hard-to-find data (e.g. motion tokens), but the headings have to be there or the prompt grep breaks. +2. **Hex codes are real.** Sample directly from the brand's site or product, not from memory or AI guesses. The README's "brand-spec extraction" 5-step protocol applies to maintainers too. +3. **OKLch values for accent colors** are nice-to-have. They make palettes lerp predictably across light/dark. +4. **No marketing fluff.** The brand's tagline is not a design token. Cut it. +5. **Slug uses ASCII** — `linear.app` becomes `linear-app`, `x.ai` becomes `x-ai`. The 69 imported systems already follow this convention; mirror it. + +The 69 product systems we ship are imported from [`VoltAgent/awesome-design-md`][acd2] via [`scripts/sync-design-systems.mjs`](scripts/sync-design-systems.mjs). If your brand belongs upstream, **send the PR there first** — we'll pick it up automatically on the next sync. The `design-systems/` folder is for systems that don't fit upstream, plus our two hand-authored starters. + +--- + +## Adding a new coding-agent CLI + +Hooking up a new agent (e.g. some new shop's `foo-coder` CLI) is one entry in [`daemon/agents.js`](daemon/agents.js): + +```javascript +{ + id: 'foo', + name: 'Foo Coder', + bin: 'foo', + versionArgs: ['--version'], + buildArgs: (prompt) => ['exec', '-p', prompt], + streamFormat: 'plain', // or 'claude-stream-json' if it speaks that +} +``` + +That's it — daemon will detect it on `PATH`, the picker shows it, the chat path works. If the CLI emits **typed events** (like Claude Code's `--output-format stream-json`), wire a parser in [`daemon/claude-stream.js`](daemon/claude-stream.js) and set `streamFormat: 'claude-stream-json'`. + +Bar for merging: + +1. **A real session works end-to-end** with the new agent — paste the daemon log into the PR description showing it streamed an artifact through. +2. **`docs/agent-adapters.md`** is updated with the CLI's quirks (does it require a key file? does it support image input? what's its non-interactive flag?). +3. **The README's "Supported coding agents" table** gets one row. + +--- + +## Code style + +We're not pedantic about formatting (Prettier on save is fine), but two rules are non-negotiable because they show up in the prompt stack and the user-facing API: + +1. **Single quotes in JS/TS.** Strings are single-quoted unless escaping makes them ugly. The codebase is already consistent — please match. +2. **Comments in English.** Even if the PR is translating something into 中文, code comments stay in English so we can keep one set of greppable references. + +Beyond that: + +- **Don't narrate.** No `// import the module`, no `// loop through items`. If the code reads obviously, the comment is noise. Save comments for non-obvious intent or constraints the code can't express. +- **TypeScript** for `src/`. The daemon (`daemon/`) is plain ESM JavaScript with JSDoc when types matter — keep it that way. +- **No new top-level dependencies** without a paragraph in the PR description on what we get vs. what bytes we ship. The dep list in [`package.json`](package.json) is small on purpose. +- **Run `pnpm typecheck`** before pushing. CI runs it; failing it earns a "please fix" comment. + +--- + +## Commits & pull requests + +- **One concern per PR.** Adding a skill + refactoring the parser + bumping a dep is three PRs. +- **Title is imperative + scope.** `add dating-web skill`, `fix daemon SSE backpressure when CLI hangs`, `docs: clarify .od layout`. +- **Body explains the why.** "What does this do" is usually obvious from the diff; "why does this need to exist" rarely is. +- **Reference an issue** if there is one. If there isn't and the PR is non-trivial, open one first so we can agree the change is wanted before you spend the time. +- **No squash-during-review.** Push fixups; we'll squash on merge. +- **No force-push to a shared branch** unless the reviewer asked. + +We don't enforce a CLA. Apache-2.0 covers us; your contribution is licensed under the same. + +--- + +## Reporting bugs + +Open an issue with: + +- What you ran (the exact `pnpm dev:all` / `npm start` invocation). +- Which agent CLI was selected (or whether you were on the BYOK path). +- The skill + design system pair that triggered it. +- The relevant **daemon stderr tail** — most "the artifact never rendered" reports get diagnosed in 30 seconds when we can see `spawn ENOENT` or the CLI's actual error. +- A screenshot if it's UI. + +For prompt-stack bugs ("the agent emitted a purple gradient hero, the slop blacklist was supposed to forbid that"), include the **full assistant message** so we can see whether the violation was the model or the prompt. + +--- + +## Asking questions + +- Architecture question, design question, "is this a bug or a misuse" → [GitHub Discussions](https://github.com/nexu-io/open-design/discussions) (preferred — searchable for the next person). +- "How do I write a skill that does X" → Open a discussion. We'll answer it and turn the answer into [`docs/skills-protocol.md`](docs/skills-protocol.md) if it's a missing pattern. + +--- + +## What we don't accept + +To keep the project focused, please don't open PRs that: + +- **Vendor a model runtime.** OD's whole bet is "your existing CLI is enough". We don't ship `pi-ai`, OpenAI keys, or model loaders. +- **Add a new framework to the frontend.** Vite + React 18 + TS is the line. No Next.js, Astro, Solid, Svelte rewrites. +- **Replace the daemon with a serverless function.** The daemon's whole point is owning a real `cwd` and spawning a real CLI. Vercel deployment of the SPA is fine; the daemon stays a daemon. +- **Add telemetry / analytics / phone-home.** OD is local-first. The only outbound calls are to providers the user explicitly configured. +- **Bundle a binary** without a license file and authorship attribution next to it. + +If you're not sure whether your idea fits, open a discussion before writing the code. + +--- + +## License + +By contributing, you agree your contribution is licensed under the [Apache-2.0 License](LICENSE) of this repository, with the exception of files inside [`skills/guizang-ppt/`](skills/guizang-ppt/), which retain their original MIT license and authorship attribution to [op7418](https://github.com/op7418). + +[skill]: https://docs.anthropic.com/en/docs/claude-code/skills +[guizang]: https://github.com/op7418/guizang-ppt-skill +[acd2]: https://github.com/VoltAgent/awesome-design-md +[ocod]: https://github.com/OpenCoworkAI/open-codesign diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md new file mode 100644 index 000000000..5e44c39f0 --- /dev/null +++ b/CONTRIBUTING.zh-CN.md @@ -0,0 +1,265 @@ +# 贡献指南 · Contributing to Open Design + +谢谢你愿意参与。OD 是有意做小的 —— 大部分价值在 **文件** 里（skill、design system、提示词片段），而不是框架代码。这意味着收益最高的贡献往往就是一个文件夹、一份 Markdown，或者一个 PR 大小的 adapter。 + +这份指南会告诉你：每种贡献该往哪里看、合并之前 PR 需要过哪些线。 + +

English · 简体中文

+ +--- + +## 一个下午就能交付的三件事 + +| 你想要…… | 你其实在加的是 | 它住在哪 | 体量 | +|---|---|---|---| +| 让 OD 渲染一种新的 artifact（一份发票、一个 iOS 设置页、一张 one-pager……） | 一个 **Skill** | [`skills//`](skills/) | 一个文件夹，约 2 个文件 | +| 让 OD 说一种新品牌的视觉语言 | 一套 **Design System** | [`design-systems//DESIGN.md`](design-systems/) | 一个 Markdown 文件 | +| 接入一个新的 coding-agent CLI | 一个 **Agent adapter** | [`daemon/agents.js`](daemon/agents.js) | 一个数组里 ~10 行 | +| 加功能、修 bug、从 [`open-codesign`][ocod] 移植一个 UX 模式 | 代码 | `src/`、`daemon/` | 普通 PR | +| 改文档、补中文翻译、修错别字 | 文档 | `README.md`、`README.zh-CN.md`、`docs/`、`QUICKSTART.md` | 一个 PR | + +不确定自己想做的属于哪一桶？[先开 issue / discussion](https://github.com/nexu-io/open-design/issues/new)，我们告诉你该改哪个面。 + +--- + +## 本地起跑 + +完整的一页式 setup 在 [`QUICKSTART.md`](QUICKSTART.md)。给贡献者的 TL;DR： + +```bash +git clone https://github.com/nexu-io/open-design.git +cd open-design +pnpm install # 或 npm install +pnpm dev:all # daemon (:7456) + Vite (:5173) +pnpm typecheck # tsc -b --noEmit +pnpm build # 生产构建 +``` + +要求 Node 18+。macOS、Linux、WSL2 每天都在跑。Windows 原生应该能跑但不是主要目标 —— 跑不起来请开 issue。 + +**开发 OD 本身不需要在 `PATH` 上装任何 agent CLI** —— daemon 会告诉你「找不到 agent」并落到 **Anthropic API · BYOK** 路径，反而是最快的开发循环。 + +--- + +## 加一个 Skill + +一个 skill 就是 [`skills/`](skills/) 下的一个文件夹，根目录放一个 `SKILL.md`，遵循 Claude Code 的 [`SKILL.md` 规范][skill]，再加上我们可选的 `od:` 扩展。**没有注册步骤。** 文件夹丢进来、重启 daemon、picker 里就出现了。 + +### Skill 文件夹结构 + +```text +skills/your-skill/ +├── SKILL.md # 必须 +├── assets/template.html # 可选但强烈推荐 —— seed 模板 +├── references/ # 可选 —— agent 在规划阶段会读的知识文件 +│ ├── layouts.md +│ ├── components.md +│ └── checklist.md +└── example.html # 强烈推荐 —— 一份手搓的真实样例 +``` + +### `SKILL.md` 的 frontmatter + +前三个字段是 Claude Code 的基础规范 —— `name`、`description`、`triggers`。`od:` 下面所有字段都是 OD 特有的、可选的，但 **`od.mode`** 决定 skill 出现在哪一组（Prototype / Deck / Template / Design system）。 + +```yaml +--- +name: your-skill +description: | + 一段电梯演讲。Agent 会原样读这段来判断用户的需求是否匹配。 + 写具体一点：surface、受众、artifact 里有什么、没有什么。 +triggers: + - "your trigger phrase" + - "another phrase" + - "中文触发词" +od: + mode: prototype # prototype | deck | template | design-system + platform: desktop # desktop | mobile + scenario: marketing # 自由 tag，用来分组 + featured: 1 # 任何正整数都会让它出现在「Showcase examples」 + preview: + type: html # html | jsx | pptx | markdown + entry: index.html + design_system: + requires: true # 这个 skill 是否会读激活的 DESIGN.md + sections: [color, typography, layout, components] + example_prompt: "一段可复制粘贴的提示词，最能体现这个 skill 的能力。" +--- + +# Your Skill + +正文是自由 Markdown，描述 agent 应该走的工作流…… +``` + +完整 grammar —— 类型化输入、滑块参数、能力 gating —— 在 [`docs/skills-protocol.md`](docs/skills-protocol.md)。 + +### 合并新 skill 的硬线 + +Skill 是用户直接看到的面，所以我们对它挑剔。一个新 skill 必须： + +1. **附一份真实的 `example.html`。** 手搓的、本地直接打开就能看、像设计师真的会交付的东西。不要 lorem ipsum，不要 `` 占位 hero。如果你自己都不能搓出 example，这个 skill 大概率还没准备好。 +2. **过 anti-AI-slop checklist**（写在 body 里）。不准紫色渐变、不准通用 emoji 图标、不准左 border 圆角卡片、不准把 Inter 当 *display* 字体、不准自编数据。完整黑名单看 README 的「Anti-AI-slop machinery」一节。 +3. **诚实占位。** Agent 没真数字时写 `—` 或一个标注的灰块，绝不写「快 10 倍」。 +4. **附 `references/checklist.md`**，至少要有 P0 关卡（agent emit `` 之前必须过的硬线）。格式照搬 [`skills/guizang-ppt/references/checklist.md`](skills/guizang-ppt/) 或 [`skills/dating-web/references/checklist.md`](skills/dating-web/)。 +5. **如果是 featured skill，加一张截图** 到 `docs/screenshots/skills/.png`。PNG 格式，约 1024×640 retina，从真实 `example.html` 上以缩小后的浏览器倍率截。 +6. **是一个自包含文件夹。** CDN 引入不能超过其他 skill 已经引入的；不准用没授权的字体；图片不要超过约 250 KB。 + +如果你 fork 了一个现有 skill（比如从 `dating-web` 改成 `recruiting-web`），保留原 LICENSE 和原作者归属在 `references/` 里，并在 PR 描述里点出来。 + +### 已有的 skill —— 挑一个像的来抄 + +- 视觉 showcase、单屏原型：[`skills/dating-web/`](skills/dating-web/)、[`skills/digital-eguide/`](skills/digital-eguide/) +- 多屏移动流程：[`skills/mobile-onboarding/`](skills/mobile-onboarding/)、[`skills/gamified-app/`](skills/gamified-app/) +- 文档 / 模板（不需要 design system）：[`skills/pm-spec/`](skills/pm-spec/)、[`skills/weekly-update/`](skills/weekly-update/) +- Deck 模式：[`skills/guizang-ppt/`](skills/guizang-ppt/)（来自 [op7418/guizang-ppt-skill][guizang]，原样捆绑）和 [`skills/simple-deck/`](skills/simple-deck/) + +--- + +## 加一套 Design System + +一套 design system 就是 `design-systems//` 下的一个 [`DESIGN.md`](design-systems/README.md) 文件。**一个文件，零代码。** 丢进来、重启 daemon、picker 按 category 分组显示出来。 + +### Design system 文件夹结构 + +```text +design-systems/your-brand/ +└── DESIGN.md +``` + +### `DESIGN.md` 形态 + +```markdown +# Design System Inspired by YourBrand + +> Category: Developer Tools +> 一行总结，会显示在 picker 的预览里。 + +## 1. Visual Theme & Atmosphere +… + +## 2. Color +- Primary: `#hex` / `oklch(...)` +- … + +## 3. Typography +… + +## 4. Spacing & Grid +## 5. Layout & Composition +## 6. Components +## 7. Motion & Interaction +## 8. Voice & Brand +## 9. Anti-patterns +``` + +9 段式 schema 是固定的 —— skill body 会按这个结构 grep 内容。第一行 H1 会成为 picker 的标签（`Design System Inspired by` 前缀会被自动剥掉），`> Category: …` 那一行决定它落到哪个组。已有的 category 列表在 [`design-systems/README.md`](design-systems/README.md)；如果你的品牌真的塞不进任何一个，可以新增 category，但**优先尝试现有 category**。 + +### 合并新 design system 的硬线 + +1. **9 个 section 都要在。** Section 内容空着可以（比如真的找不到 motion token），但标题必须保留，否则提示词的 grep 会断。 +2. **Hex 是真的。** 直接从品牌官网或产品里取色，不准从记忆里掏，不准让 AI 猜。README 里那套 5 步「品牌资产协议」对维护者一样适用。 +3. **强调色给 OKLch 是加分项。** 让色板在亮 / 暗模式之间能可预测地 lerp。 +4. **不要营销废话。** 品牌的 tagline 不是设计 token。删掉。 +5. **slug 用 ASCII** —— `linear.app` 写成 `linear-app`，`x.ai` 写成 `x-ai`。已经导入的 69 套都遵循这个约定，跟着写。 + +我们内置的 69 套产品系统是通过 [`scripts/sync-design-systems.mjs`](scripts/sync-design-systems.mjs) 从 [`VoltAgent/awesome-design-md`][acd2] 导入的。如果你的品牌应该归属在上游，**请先把 PR 发到那里** —— 我们下一次同步会自动收上来。`design-systems/` 文件夹用来放那些**不适合归到上游**的系统、加上我们手写的两套 starter。 + +--- + +## 接入一个新的 coding-agent CLI + +接入一个新 agent（比如某个新 shop 的 `foo-coder` CLI）就是在 [`daemon/agents.js`](daemon/agents.js) 里加一项： + +```javascript +{ + id: 'foo', + name: 'Foo Coder', + bin: 'foo', + versionArgs: ['--version'], + buildArgs: (prompt) => ['exec', '-p', prompt], + streamFormat: 'plain', // 如果它说 claude-stream-json 就写那个 +} +``` + +完事 —— daemon 会在 `PATH` 上检测到它、picker 显示出来、对话路径就通了。如果这个 CLI 吐 **类型化事件**（像 Claude Code 的 `--output-format stream-json`），在 [`daemon/claude-stream.js`](daemon/claude-stream.js) 里写一个 parser，并把 `streamFormat` 设成 `'claude-stream-json'`。 + +合并硬线： + +1. **真的跑通一次端到端会话** —— 把 daemon 日志贴在 PR 描述里，证明它流出了一个 artifact。 +2. **更新 [`docs/agent-adapters.md`](docs/agent-adapters.md)**，写清楚这个 CLI 的怪癖（要不要 key 文件？支不支持图片输入？非交互模式的 flag 是什么？）。 +3. **README 的「Supported coding agents」表里加一行**。 + +--- + +## 代码风格 + +格式我们不抠（保存时跑 Prettier 就行），但有两条不能让 —— 因为它们出现在提示词栈和用户可见的 API 里： + +1. **JS/TS 用单引号。** 字符串一律单引号，除非转义太丑。代码库已经是一致的，请保持一致。 +2. **代码注释用英文。** 即使 PR 是把某段翻译成中文，代码注释也保留英文，这样我们能维护一份可 grep 的引用集。 + +除此之外： + +- **不要写废话注释。** 不要 `// 引入这个模块`、不要 `// 遍历元素`。如果代码本身一眼能读，注释就是噪音。注释只用来说明非显而易见的意图、或者代码本身表达不出来的约束。 +- **`src/` 用 TypeScript。** Daemon (`daemon/`) 是纯 ESM JavaScript，类型重要的地方用 JSDoc —— 保持这样。 +- **不要随便加顶层依赖。** PR 描述里至少要有一段，说明引入它能换到什么、又新增了多少 bundle 字节。[`package.json`](package.json) 的依赖少是有意为之。 +- **推之前跑 `pnpm typecheck`。** CI 会跑；挂了会换来一句「请修一下」。 + +--- + +## Commit 与 PR + +- **一个 PR 只做一件事。** 加 skill + 重构 parser + 升依赖，是三个 PR。 +- **标题用动词起头 + 范围。** `add dating-web skill`、`fix daemon SSE backpressure when CLI hangs`、`docs: clarify .od layout`。 +- **正文解释 why。** 「这个 PR 改了什么」从 diff 一般能看出来；「为什么要改」很少能。 +- **如果有 issue，引用它。** 没有、且改动非平凡，请先开 issue 让我们先就「值不值得做」达成一致，再投入时间。 +- **Review 期间不要 squash。** 推 fixup commit；merge 时我们会 squash。 +- **不要 force-push 共享分支**，除非 reviewer 主动让你这么做。 + +我们不强制 CLA。Apache-2.0 已经覆盖；你的贡献按同样的 license 授权。 + +--- + +## 报 bug + +开 issue 时请带上： + +- 你跑的命令（精确到 `pnpm dev:all` / `npm start`）。 +- 选中的 agent CLI 是哪个（或者你走的是 BYOK 路径）。 +- 触发问题时的 skill + design system 组合。 +- 相关的 **daemon stderr 末尾几行** —— 大多数「artifact 没渲染出来」的报告，看到 `spawn ENOENT` 或 CLI 实际报错后 30 秒就能定位。 +- UI 问题贴一张截图。 + +提示词栈相关的 bug（「agent 吐了一个紫色渐变 hero，slop 黑名单不是禁了吗」），请贴 **完整的助手消息**，方便我们判断违规来自模型还是提示词。 + +--- + +## 提问 + +- 架构问题、设计问题、「这是 bug 还是误用」 → 请用 [GitHub Discussions](https://github.com/nexu-io/open-design/discussions)（首选 —— 下一个人能搜到）。 +- 「我想写一个干 X 的 skill 怎么写」 → 开一个 discussion。我们会回答，且如果是缺失的模式，答案会被收进 [`docs/skills-protocol.md`](docs/skills-protocol.md)。 + +--- + +## 我们不接收的 PR + +为了保持项目聚焦，请不要发以下类型的 PR： + +- **Vendor 一个模型运行时。** OD 整个赌注就是「你已有的 CLI 就够了」。我们不带 `pi-ai`、不带 OpenAI key、不带模型加载器。 +- **给前端加一个新框架。** Vite + React 18 + TS 是底线。不要 Next.js / Astro / Solid / Svelte 改写。 +- **把 daemon 换成 serverless function。** Daemon 的存在意义就是拥有真实的 `cwd` 和 spawn 真实的 CLI。SPA 部署 Vercel 没问题，daemon 仍然是 daemon。 +- **加 telemetry / 分析 / phone-home。** OD 是 local-first。唯一的对外请求是用户明确配置的 provider。 +- **打包二进制** 而没有附 license 文件和原作者归属。 + +不确定自己的想法合不合适？开个 discussion 再写代码。 + +--- + +## License + +提交贡献即代表你同意你的贡献按本仓库的 [Apache-2.0 License](LICENSE) 授权。例外是 [`skills/guizang-ppt/`](skills/guizang-ppt/) 下的所有文件，保留它们原始的 MIT license 和原作者 [op7418](https://github.com/op7418) 的归属。 + +[skill]: https://docs.anthropic.com/en/docs/claude-code/skills +[guizang]: https://github.com/op7418/guizang-ppt-skill +[acd2]: https://github.com/VoltAgent/awesome-design-md +[ocod]: https://github.com/OpenCoworkAI/open-codesign diff --git a/LICENSE b/LICENSE index 4e6e7ae10..eb79c35bd 100644 --- a/LICENSE +++ b/LICENSE @@ -186,7 +186,7 @@ same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright 2026 Open Claude Design contributors + Copyright 2026 Open Design contributors Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/QUICKSTART.md b/QUICKSTART.md index fd10eccfa..4925c0e5c 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -10,7 +10,7 @@ npm run dev:all # starts daemon (:7456) + Vite (:5173) together open http://localhost:5173 ``` -On first load, the app detects your installed code-agent CLI (Claude Code / Codex / Gemini / OpenCode / Cursor Agent / Qwen), picks it automatically, and defaults to `web-prototype` skill + `Neutral Modern` design system. Type a prompt and hit **Send**. The agent streams into the left pane; the `` tag is parsed out and the HTML renders live on the right. When it finishes, click **Save to disk** to persist the artifact under `./.ocd/artifacts/-/index.html`. +On first load, the app detects your installed code-agent CLI (Claude Code / Codex / Gemini / OpenCode / Cursor Agent / Qwen), picks it automatically, and defaults to `web-prototype` skill + `Neutral Modern` design system. Type a prompt and hit **Send**. The agent streams into the left pane; the `` tag is parsed out and the HTML renders live on the right. When it finishes, click **Save to disk** to persist the artifact under `./.od/artifacts/-/index.html`. The **Design system** dropdown ships with 71 built-in systems — 2 hand-authored starters (Neutral Modern, Warm Editorial) and 69 product systems imported from [`awesome-design-md`](https://github.com/VoltAgent/awesome-design-md), grouped by category (AI & LLM, Developer Tools, Productivity, Backend, Design Tools, Fintech, E-Commerce, Media, Automotive). Pick one to skin every prototype in that brand's aesthetic. @@ -57,9 +57,9 @@ Swap the skill or the design system in the top bar and the next send uses the ne ## File map ``` -open-claude-design/ +open-design/ ├── daemon/ # Node/Express — spawns local agents + serves APIs -│ ├── cli.js # `ocd` bin entry (also used by npm scripts) +│ ├── cli.js # `od` bin entry (also used by npm scripts) │ ├── server.js # /api/agents /api/skills /api/design-systems /api/chat /api/upload /api/artifacts/save │ ├── agents.js # PATH scanner for claude/codex/gemini/opencode/cursor-agent/qwen │ ├── skills.js # SKILL.md loader (frontmatter parser) @@ -96,7 +96,10 @@ open-claude-design/ │ ├── components/ # ChatPane, PreviewPane, AgentPicker, SkillPicker, DesignSystemPicker, SettingsDialog │ └── state/config.ts # localStorage persistence ├── docs/ # product vision + spec -├── .ocd/artifacts/ # saved HTML outputs (gitignored) +├── .od/ # runtime data (gitignored, auto-created) +│ ├── app.sqlite # projects / conversations / messages / tabs +│ ├── artifacts/ # one-off "Save to disk" renders +│ └── projects// # per-project working dir + agent cwd └── vite.config.ts # /api proxy to :7456 ``` @@ -111,6 +114,6 @@ open-claude-design/ This Quickstart is the runnable seed of the spec in [`docs/`](docs/). The spec describes where this grows (see [`docs/roadmap.md`](docs/roadmap.md)). Highlights: - `docs/architecture.md` proposes Next.js; we picked Vite for a simpler dev loop. The daemon contract is identical, so migrating is a port, not a rewrite. -- `docs/skills-protocol.md` describes the full `ocd:` frontmatter (typed inputs, sliders, capability gating). This MVP reads `name` / `description` / `triggers` / `ocd.mode` / `ocd.design_system.requires` only — extend `daemon/skills.js` to add the rest. +- `docs/skills-protocol.md` describes the full `od:` frontmatter (typed inputs, sliders, capability gating). This MVP reads `name` / `description` / `triggers` / `od.mode` / `od.design_system.requires` only — extend `daemon/skills.js` to add the rest. - `docs/agent-adapters.md` foresees richer dispatch (capability detection, streaming tool-calls). Our `daemon/agents.js` is a minimal dispatcher — enough to prove the wiring. - `docs/modes.md` lists four modes: prototype / deck / template / design-system. We ship skills for the first two; the picker already filters by `mode`. diff --git a/README.md b/README.md index c65be08b3..eb2107347 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -# Open Claude Design +# Open Design -> **Claude Code, but for design.** A local-first, web-deployable open replica of Anthropic's [Claude Design][cd] — your existing coding agent (Claude Code, Codex, Cursor Agent, Gemini CLI, OpenCode, Qwen) becomes the design engine, driven by composable **Skills** and **71 brand-grade Design Systems**. +> **The open-source alternative to [Claude Design][cd].** Local-first, web-deployable, BYOK at every layer — your existing coding agent (Claude Code, Codex, Cursor Agent, Gemini CLI, OpenCode, Qwen) becomes the design engine, driven by **19 composable Skills** and **71 brand-grade Design Systems**.

- Open Claude Design banner + Open Design — editorial cover: design with the agent on your laptop

@@ -20,15 +20,15 @@ ## Why this exists -Anthropic's [Claude Design][cd] (released 2026-04-17, Opus 4.7) showed what happens when an LLM stops writing prose and starts shipping design artifacts. It went viral — and stayed closed, paid-only, cloud-only, locked to Anthropic's model and Anthropic's skills. +Anthropic's [Claude Design][cd] (released 2026-04-17, Opus 4.7) showed what happens when an LLM stops writing prose and starts shipping design artifacts. It went viral — and stayed closed-source, paid-only, cloud-only, locked to Anthropic's model and Anthropic's skills. There is no checkout, no self-host, no Vercel deploy, no swap-in-your-own-agent. -**Open Claude Design (OCD) is the open substrate.** We don't build an agent — the strongest coding agents already live on your laptop. We wire them into a skill-driven design workflow that runs on `pnpm dev`, deploys to Vercel, and stays BYOK at every layer. +**Open Design (OD) is the open-source alternative.** Same loop, same artifact-first mental model, none of the lock-in. We don't ship an agent — the strongest coding agents already live on your laptop. We wire them into a skill-driven design workflow that runs on `pnpm dev`, deploys to Vercel, and stays BYOK at every layer. Type `make me a magazine-style pitch deck for our seed round`. The interactive question form pops up before the model improvises a single pixel. The agent picks one of five curated visual directions. A live `TodoWrite` plan streams into the UI. The daemon builds a real on-disk project folder with a seed template, layout library, and self-check checklist. The agent reads them — pre-flight enforced — runs a five-dimensional critique against its own output, and emits a single `` that renders in a sandboxed iframe seconds later. -That's not "AI tries to design something". That's an AI that has been trained, by the prompt stack, to behave like a senior designer with a working filesystem, a deterministic palette library, and a checklist culture. +That's not "AI tries to design something". That's an AI that has been trained, by the prompt stack, to behave like a senior designer with a working filesystem, a deterministic palette library, and a checklist culture — exactly the bar Claude Design set, but open and yours. -OCD stands on four open-source shoulders: +OD stands on four open-source shoulders: - [**`alchaincyf/huashu-design`**](https://github.com/alchaincyf/huashu-design) — the design-philosophy compass. Junior-Designer workflow, the 5-step brand-asset protocol, the anti-AI-slop checklist, the 5-dimensional self-critique, and the "5 schools × 20 design philosophies" idea behind our direction picker — all distilled into [`src/prompts/discovery.ts`](src/prompts/discovery.ts). - [**`op7418/guizang-ppt-skill`**](https://github.com/op7418/guizang-ppt-skill) — the deck mode. Bundled verbatim under [`skills/guizang-ppt/`](skills/guizang-ppt/) with original LICENSE preserved; magazine-style layouts, WebGL hero, P0/P1/P2 checklists. @@ -52,51 +52,130 @@ OCD stands on four open-source shoulders: ## Demo -> Screenshots are placeholders — the live UI is what the screenshots will be of. Replace the `docs/screenshots/*.png` files in PR. -
-Entry view: pick skill + design system + brief
+01 · Entry view
Entry view — pick a skill, pick a design system, type the brief. The same surface for prototypes, decks, mobile apps, dashboards, and editorial pages. 		-Turn-1 discovery question form
-Turn-1 discovery form — before the model writes a pixel, OCD locks the brief: surface, audience, tone, brand context, scale. 30 seconds of radios beats 30 minutes of redirects. +02 · Turn-1 discovery form
+Turn-1 discovery form — before the model writes a pixel, OD locks the brief: surface, audience, tone, brand context, scale. 30 seconds of radios beats 30 minutes of redirects.
-Direction picker — 5 deterministic visual directions
+03 · Direction picker
Direction picker — when the user has no brand, the agent emits a second form with 5 curated directions (Monocle / Modern Minimal / Tech Utility / Brutalist / Soft Warm). One radio click → a deterministic palette + font stack, no model freestyle. 		-Live TodoWrite plan streaming into the UI
+04 · Live todo progress
Live todo progress — the agent's plan streams as a live card. in_progress → completed updates land in real time. The user can redirect cheaply, mid-flight.
-Sandboxed iframe preview of the generated artifact
+05 · Sandboxed preview
Sandboxed preview — every <artifact> renders in a clean srcdoc iframe. Editable in place via the file workspace; downloadable as HTML, PDF, ZIP. 		-71-system design-system library with palette swatches
+06 · 71-system library
71-system library — every product system shows its 4-color signature. Click for the full DESIGN.md, swatch grid, and live showcase.
-Magazine-style horizontal deck output
+07 · Magazine deck
Deck mode (guizang-ppt) — the bundled guizang-ppt-skill drops in unchanged. Magazine layouts, WebGL hero backgrounds, single-file HTML output, PDF export. 		-Mobile app prototype with iPhone 15 Pro frame
+08 · Mobile prototype
Mobile prototype — pixel-accurate iPhone 15 Pro chrome (Dynamic Island, status bar SVGs, home indicator). Multi-screen prototypes use the shared /frames/ assets so the agent never re-draws a phone.
+## Skills + +19 skills ship in the box. Each is a folder under [`skills/`](skills/) following the Claude Code [`SKILL.md`][skill] convention with an extended `od:` frontmatter (`mode`, `platform`, `scenario`, `preview`, `design_system`). + +### Showcase examples + +The visually distinctive skills you'll most likely run first. Each ships a real `example.html` you can open straight from the repo to see exactly what the agent will produce — no auth, no setup. + + + + + + + + + + + + + + + + + + +
+dating-web
+dating-web · prototype
Consumer dating / matchmaking dashboard — left rail nav, ticker bar, KPIs, 30-day mutual-matches chart, editorial typography. +		 +digital-eguide
+digital-eguide · template
Two-spread digital e-guide — cover (title, author, TOC teaser) + lesson spread with pull-quote and step list. Creator / lifestyle tone. +
+email-marketing
+email-marketing · prototype
Brand product-launch HTML email — masthead, hero image, headline lockup, CTA, specs grid. Centered single-column, table-fallback safe. +		 +gamified-app
+gamified-app · prototype
Three-frame gamified mobile-app prototype on a dark showcase stage — cover, today's quests with XP ribbons + level bar, quest detail. +
+mobile-onboarding
+mobile-onboarding · prototype
Three-frame mobile onboarding flow — splash, value-prop, sign-in. Status bar, swipe dots, primary CTA. +		 +motion-frames
+motion-frames · prototype
Single-frame motion-design hero with looping CSS animations — rotating type ring, animated globe, ticking timer. Hand-off ready for HyperFrames. +
+social-carousel
+social-carousel · prototype
Three-card 1080×1080 social-media carousel — cinematic panels with display headlines that connect across the series, brand mark, loop affordance. +		 +sprite-animation
+sprite-animation · prototype
Pixel / 8-bit animated explainer slide — full-bleed cream stage, animated pixel mascot, kinetic Japanese display type, looping CSS keyframes. +
+ +### Design surfaces + +| Skill | Mode | Default for | What it produces | +|---|---|---|---| +| [`web-prototype`](skills/web-prototype/) | prototype | desktop | Single-page HTML — landings, marketing, hero pages | +| [`saas-landing`](skills/saas-landing/) | prototype | desktop | Hero / features / pricing / CTA marketing layout | +| [`dashboard`](skills/dashboard/) | prototype | desktop | Admin / analytics with sidebar + data dense layout | +| [`pricing-page`](skills/pricing-page/) | prototype | desktop | Standalone pricing + comparison tables | +| [`docs-page`](skills/docs-page/) | prototype | desktop | 3-column documentation layout | +| [`blog-post`](skills/blog-post/) | prototype | desktop | Editorial long-form | +| [`mobile-app`](skills/mobile-app/) | prototype | mobile | iPhone 15 Pro / Pixel framed app screen(s) | +| [`simple-deck`](skills/simple-deck/) | deck | desktop | Minimal horizontal-swipe deck | +| [`guizang-ppt`](skills/guizang-ppt/) | deck | **default** for deck | Magazine-style web PPT — bundled from [op7418/guizang-ppt-skill][guizang] | + +### Document / work-product surfaces + +| Skill | Mode | What it produces | +|---|---|---| +| [`pm-spec`](skills/pm-spec/) | template | PM specification doc with TOC + decision log | +| [`weekly-update`](skills/weekly-update/) | template | Team weekly with progress / blockers / next | +| [`meeting-notes`](skills/meeting-notes/) | template | Meeting decision log | +| [`eng-runbook`](skills/eng-runbook/) | template | Incident runbook | +| [`finance-report`](skills/finance-report/) | template | Exec finance summary | +| [`hr-onboarding`](skills/hr-onboarding/) | template | Role onboarding plan | +| [`invoice`](skills/invoice/) | template | Single-page invoice | +| [`kanban-board`](skills/kanban-board/) | template | Board snapshot | +| [`team-okrs`](skills/team-okrs/) | template | OKR scoresheet | + +Adding a skill takes one folder. Read [`docs/skills-protocol.md`](docs/skills-protocol.md) for the extended frontmatter, fork an existing skill, restart the daemon, it appears in the picker. + ## Six load-bearing ideas ### 1 · We don't ship an agent. Yours is good enough. @@ -113,13 +192,13 @@ The 9-section `DESIGN.md` schema from [`VoltAgent/awesome-design-md`][acd2] — ### 4 · The interactive question form prevents 80% of redirects. -OCD's prompt stack hard-codes a `RULE 1`: every fresh design brief begins with a `` instead of code. Surface · audience · tone · brand context · scale · constraints. A long brief still leaves design decisions open — visual tone, color stance, scale — exactly the things the form locks down in 30 seconds. The cost of a wrong direction is one chat round, not one finished deck. +OD's prompt stack hard-codes a `RULE 1`: every fresh design brief begins with a `` instead of code. Surface · audience · tone · brand context · scale · constraints. A long brief still leaves design decisions open — visual tone, color stance, scale — exactly the things the form locks down in 30 seconds. The cost of a wrong direction is one chat round, not one finished deck. This is the **Junior-Designer mode** distilled from [`huashu-design`](https://github.com/alchaincyf/huashu-design): batch the questions up front, show something visible early (even a wireframe with grey blocks), let the user redirect cheaply. Combined with the brand-asset protocol (locate · download · `grep` hex · write `brand-spec.md` · vocalise), it's the single biggest reason output stops feeling like AI freestyle and starts feeling like a designer who paid attention before painting. ### 5 · The daemon makes the agent feel like it's on your laptop, because it is. -The daemon spawns the CLI with `cwd` set to the project's artifact folder under `.ocd/projects//`. The agent gets `Read`, `Write`, `Bash`, `WebFetch` — real tools against a real filesystem. It can `Read` the skill's `assets/template.html`, `grep` your CSS for hex values, write a `brand-spec.md`, drop generated images, and produce `.pptx` / `.zip` / `.pdf` files that show up in the file workspace as download chips when the turn ends. Sessions, conversations, messages, tabs persist in a local SQLite DB — pop the project open tomorrow and the agent's todo card is right where you left it. +The daemon spawns the CLI with `cwd` set to the project's artifact folder under `.od/projects//`. The agent gets `Read`, `Write`, `Bash`, `WebFetch` — real tools against a real filesystem. It can `Read` the skill's `assets/template.html`, `grep` your CSS for hex values, write a `brand-spec.md`, drop generated images, and produce `.pptx` / `.zip` / `.pdf` files that show up in the file workspace as download chips when the turn ends. Sessions, conversations, messages, tabs persist in a local SQLite DB — pop the project open tomorrow and the agent's todo card is right where you left it. ### 6 · The prompt stack is the product. @@ -158,7 +237,7 @@ Every layer is composable. Every layer is a file you can edit. Read [`src/prompt │ /api/chat (SSE) │ │ │ └─────────┬────────────┘ - │ spawn(cli, [...], { cwd: .ocd/projects/ }) + │ spawn(cli, [...], { cwd: .od/projects/ }) ▼ ┌──────────────────────────────────────────────────────────┐ │ claude · codex · cursor-agent · gemini · opencode · qwen│ @@ -171,15 +250,15 @@ Every layer is composable. Every layer is a file you can edit. Read [`src/prompt | Frontend | Vite 5 + React 18 + TypeScript | | Daemon | Node 18+ · Express · SSE streaming · `better-sqlite3` for projects/conversations/messages/tabs | | Agent transport | `child_process.spawn` with `claude-stream-json` parser for Claude Code, line-buffered plain stdout for the rest | -| Storage | Plain files in `.ocd/projects//` + SQLite at `.ocd/db.sqlite` (gitignored) | +| Storage | Plain files in `.od/projects//` + SQLite at `.od/db.sqlite` (gitignored) | | Preview | Sandboxed iframe via `srcdoc` + per-skill `` parser | | Export | HTML (inline assets) · PDF (browser print) · PPTX (skill-defined) · ZIP (archiver) | ## Quickstart ```bash -git clone https://github.com//open-claude-design.git -cd open-claude-design +git clone https://github.com/nexu-io/open-design.git +cd open-design pnpm install # or npm install pnpm dev:all # daemon (:7456) + Vite (:5173) open http://localhost:5173 @@ -190,22 +269,40 @@ The first load: 1. Detects which agent CLIs you have on `PATH` and picks one automatically. 2. Loads 19 skills + 71 design systems. 3. Pops the welcome dialog so you can paste an Anthropic key (only needed for the BYOK fallback path). +4. **Auto-creates `./.od/`** — the local runtime folder for the SQLite project DB, per-project artifacts, and saved renders. There is no `od init` step; the daemon `mkdir`s everything it needs on boot. Type a prompt, hit **Send**, watch the question form arrive, fill it, watch the todo card stream, watch the artifact render. Click **Save to disk** or download as a project ZIP. +### First-run state (`./.od/`) + +The daemon owns one hidden folder at the repo root. Everything in it is gitignored and machine-local — never commit it. + +``` +.od/ +├── app.sqlite ← projects · conversations · messages · open tabs +├── artifacts/ ← one-off "Save to disk" renders (timestamped) +└── projects// ← per-project working dir, also the agent's cwd +``` + +| Want to… | Do this | +|---|---| +| Inspect what's in there | `ls -la .od && sqlite3 .od/app.sqlite '.tables'` | +| Reset to a clean slate | stop the daemon, `rm -rf .od`, run `pnpm dev:all` again | +| Move it elsewhere | not supported yet — the path is hard-coded relative to the repo | + Full file map, scripts, and troubleshooting → [`QUICKSTART.md`](QUICKSTART.md). ## Repository structure ``` -open-claude-design/ +open-design/ ├── README.md ← this file ├── README.zh-CN.md ← 简体中文 ├── QUICKSTART.md ← run / build / deploy guide -├── package.json ← pnpm workspace, single bin: ocd +├── package.json ← pnpm workspace, single bin: od │ ├── daemon/ ← Node + Express, the only server -│ ├── cli.js ← `ocd` bin entry point +│ ├── cli.js ← `od` bin entry point │ ├── server.js ← /api/* routes (projects, chat, files, exports) │ ├── agents.js ← PATH scanner + per-CLI argv builders │ ├── claude-stream.js ← streaming JSON parser for Claude Code stdout @@ -288,7 +385,7 @@ open-claude-design/ ├── docs/ │ ├── spec.md ← product spec, scenarios, differentiation │ ├── architecture.md ← topologies, data flow, components -│ ├── skills-protocol.md ← extended SKILL.md ocd: frontmatter +│ ├── skills-protocol.md ← extended SKILL.md od: frontmatter │ ├── agent-adapters.md ← per-CLI detection + dispatch │ ├── modes.md ← prototype / deck / template / design-system │ ├── references.md ← long-form provenance @@ -296,65 +393,16 @@ open-claude-design/ │ ├── schemas/ ← JSON schemas │ └── examples/ ← canonical artifact examples │ -└── .ocd/ ← runtime data, gitignored +└── .od/ ← runtime data, gitignored, auto-created + ├── app.sqlite ← projects / conversations / messages / tabs ├── projects// ← per-project working folder (agent's cwd) - ├── artifacts/ ← saved one-off renders - └── db.sqlite ← projects / conversations / messages / tabs + └── artifacts/ ← saved one-off renders ``` -## Skills - -19 skills ship in the box. Each is a folder under [`skills/`](skills/) following the Claude Code [`SKILL.md`][skill] convention with an extended `ocd:` frontmatter (`mode`, `platform`, `scenario`, `preview`, `design_system`). - -### Showcase examples - -The visually distinctive skills you'll most likely run first. Each ships a real `example.html` you can open straight from the repo to see what the agent will produce. - -| Skill | Mode | What it produces | -|---|---|---| -| [`dating-web`](skills/dating-web/) | prototype | Consumer dating / matchmaking dashboard — left rail nav, ticker bar, KPIs, 30-day mutual-matches chart, editorial typography | -| [`digital-eguide`](skills/digital-eguide/) | template | Two-spread digital e-guide — cover (title, author, TOC teaser) + lesson spread with pull-quote and step list. Creator / lifestyle tone | -| [`email-marketing`](skills/email-marketing/) | prototype | Brand product-launch HTML email — masthead, hero image, headline lockup, CTA, specs grid. Centered single-column, table-fallback safe | -| [`gamified-app`](skills/gamified-app/) | prototype | Three-frame gamified mobile-app prototype on a dark showcase stage — cover, today's quests with XP ribbons + level bar, quest detail | -| [`mobile-onboarding`](skills/mobile-onboarding/) | prototype | Three-frame mobile onboarding flow — splash, value-prop, sign-in. Status bar, swipe dots, primary CTA | -| [`motion-frames`](skills/motion-frames/) | prototype | Single-frame motion-design hero with looping CSS animations — rotating type ring, animated globe, ticking timer. Hand-off ready for HyperFrames | -| [`social-carousel`](skills/social-carousel/) | prototype | Three-card 1080×1080 social-media carousel — cinematic panels with display headlines that connect across the series, brand mark, loop affordance | -| [`sprite-animation`](skills/sprite-animation/) | prototype | Pixel / 8-bit animated explainer slide — full-bleed cream stage, animated pixel mascot, kinetic Japanese display type, looping CSS keyframes | - -### Design surfaces - -| Skill | Mode | Default for | What it produces | -|---|---|---|---| -| [`web-prototype`](skills/web-prototype/) | prototype | desktop | Single-page HTML — landings, marketing, hero pages | -| [`saas-landing`](skills/saas-landing/) | prototype | desktop | Hero / features / pricing / CTA marketing layout | -| [`dashboard`](skills/dashboard/) | prototype | desktop | Admin / analytics with sidebar + data dense layout | -| [`pricing-page`](skills/pricing-page/) | prototype | desktop | Standalone pricing + comparison tables | -| [`docs-page`](skills/docs-page/) | prototype | desktop | 3-column documentation layout | -| [`blog-post`](skills/blog-post/) | prototype | desktop | Editorial long-form | -| [`mobile-app`](skills/mobile-app/) | prototype | mobile | iPhone 15 Pro / Pixel framed app screen(s) | -| [`simple-deck`](skills/simple-deck/) | deck | desktop | Minimal horizontal-swipe deck | -| [`guizang-ppt`](skills/guizang-ppt/) | deck | **default** for deck | Magazine-style web PPT — bundled from [op7418/guizang-ppt-skill][guizang] | - -### Document / work-product surfaces - -| Skill | Mode | What it produces | -|---|---|---| -| [`pm-spec`](skills/pm-spec/) | template | PM specification doc with TOC + decision log | -| [`weekly-update`](skills/weekly-update/) | template | Team weekly with progress / blockers / next | -| [`meeting-notes`](skills/meeting-notes/) | template | Meeting decision log | -| [`eng-runbook`](skills/eng-runbook/) | template | Incident runbook | -| [`finance-report`](skills/finance-report/) | template | Exec finance summary | -| [`hr-onboarding`](skills/hr-onboarding/) | template | Role onboarding plan | -| [`invoice`](skills/invoice/) | template | Single-page invoice | -| [`kanban-board`](skills/kanban-board/) | template | Board snapshot | -| [`team-okrs`](skills/team-okrs/) | template | OKR scoresheet | - -Adding a skill takes one folder. Read [`docs/skills-protocol.md`](docs/skills-protocol.md) for the extended frontmatter, fork an existing skill, restart the daemon, it appears in the picker. - ## Design Systems

- 71 design systems library + The 71 design systems library — style guide spread

71 systems out of the box, each as a single [`DESIGN.md`](design-systems/README.md): @@ -386,7 +434,7 @@ The library is imported via [`scripts/sync-design-systems.mjs`](scripts/sync-des ## Visual directions -When the user has no brand spec, the agent emits a second form with five curated directions — the OCD adaptation of [`huashu-design`'s "5 schools × 20 design philosophies" fallback](https://github.com/alchaincyf/huashu-design#%E8%AE%BE%E8%AE%A1%E6%96%B9%E5%90%91%E9%A1%BE%E9%97%AE-fallback). Each direction is a deterministic spec — palette in OKLch, font stack, layout posture cues, references — that the agent binds verbatim into the seed template's `:root`. One radio click → a fully specified visual system. No improvisation, no AI-slop. +When the user has no brand spec, the agent emits a second form with five curated directions — the OD adaptation of [`huashu-design`'s "5 schools × 20 design philosophies" fallback](https://github.com/alchaincyf/huashu-design#%E8%AE%BE%E8%AE%A1%E6%96%B9%E5%90%91%E9%A1%BE%E9%97%AE-fallback). Each direction is a deterministic spec — palette in OKLch, font stack, layout posture cues, references — that the agent binds verbatim into the seed template's `:root`. One radio click → a fully specified visual system. No improvisation, no AI-slop. | Direction | Mood | Refs | |---|---|---| @@ -400,7 +448,7 @@ Full spec → [`src/prompts/directions.ts`](src/prompts/directions.ts). ## Anti-AI-slop machinery -The whole machinery below is the [`huashu-design`](https://github.com/alchaincyf/huashu-design) playbook, ported into OCD's prompt-stack and made enforceable per-skill via the side-file pre-flight. Read [`src/prompts/discovery.ts`](src/prompts/discovery.ts) for the live wording: +The whole machinery below is the [`huashu-design`](https://github.com/alchaincyf/huashu-design) playbook, ported into OD's prompt-stack and made enforceable per-skill via the side-file pre-flight. Read [`src/prompts/discovery.ts`](src/prompts/discovery.ts) for the live wording: - **Question form first.** Turn 1 is `` only — no thinking, no tools, no narration. The user chooses defaults at radio speed. - **Brand-spec extraction.** When the user attaches a screenshot or URL, the agent runs a five-step protocol (locate · download · grep hex · codify `brand-spec.md` · vocalise) before writing CSS. **Never guesses brand colors from memory.** @@ -411,7 +459,7 @@ The whole machinery below is the [`huashu-design`](https://github.com/alchaincyf ## Comparison -| Axis | [Claude Design][cd] (Anthropic) | [Open CoDesign][ocod] | **Open Claude Design** | +| Axis | [Claude Design][cd] (Anthropic) | [Open CoDesign][ocod] | **Open Design** | |---|---|---|---| | License | Closed | MIT | **Apache-2.0** | | Form factor | Web (claude.ai) | Desktop (Electron) | **Web app + local daemon** | @@ -432,7 +480,7 @@ The whole machinery below is the [`huashu-design`](https://github.com/alchaincyf | PPT skill reuse | N/A | Built-in | **[`guizang-ppt-skill`][guizang] drops in** | | Minimum billing | Pro / Max / Team | BYOK | **BYOK** | -[cd]: https://www.anthropic.com/news/claude-design +[cd]: https://x.com/claudeai/status/2045156267690213649 [ocod]: https://github.com/OpenCoworkAI/open-codesign [piai]: https://github.com/mariozechner/pi-ai [acd]: https://github.com/VoltAgent/awesome-claude-design @@ -461,7 +509,7 @@ Every external project this repo borrows from. Each link goes to the source so y | Project | Role here | |---|---| -| [`Claude Design`][cd] | The closed product this repo provides an open substrate for. | +| [`Claude Design`][cd] | The closed-source product this repo is the open-source alternative to. | | [**`alchaincyf/huashu-design`**](https://github.com/alchaincyf/huashu-design) | The design-philosophy core. Junior-Designer workflow, the 5-step brand-asset protocol, anti-AI-slop checklist, 5-dimensional self-critique, and the "5 schools × 20 design philosophies" library behind our direction picker — all distilled into [`src/prompts/discovery.ts`](src/prompts/discovery.ts) and [`src/prompts/directions.ts`](src/prompts/directions.ts). | | [**`op7418/guizang-ppt-skill`**][guizang] | Magazine-web-PPT skill bundled verbatim under [`skills/guizang-ppt/`](skills/guizang-ppt/) with original LICENSE preserved. Default for deck mode. P0/P1/P2 checklist culture borrowed for every other skill. | | [**`multica-ai/multica`**](https://github.com/multica-ai/multica) | The daemon + adapter architecture. PATH-scan agent detection, local daemon as the only privileged process, agent-as-teammate worldview. We adopt the model; we do not vendor the code. | @@ -481,8 +529,8 @@ Long-form provenance write-up — what we take from each, what we deliberately d - [ ] Comment-mode surgical edits (click element → instruction → patch) — pattern from [`open-codesign`][ocod] - [ ] AI-emitted tweaks panel (model surfaces the parameters worth tweaking) — pattern from [`open-codesign`][ocod] - [ ] Vercel + tunnel deployment recipe (Topology B) -- [ ] One-command `npx ocd init` to scaffold a project with `DESIGN.md` -- [ ] Skill marketplace (`ocd skills install `) +- [ ] One-command `npx od init` to scaffold a project with `DESIGN.md` +- [ ] Skill marketplace (`od skills install `) Phased delivery → [`docs/roadmap.md`](docs/roadmap.md). @@ -490,7 +538,15 @@ Phased delivery → [`docs/roadmap.md`](docs/roadmap.md). This is an early implementation — the closed loop (detect → pick skill + design system → chat → parse `` → preview → save) runs end-to-end. The prompt stack and skill library are where most of the value lives, and they're stable. The component-level UI is shipping daily. -Issues, PRs, new skills, and new design systems are all welcome. +## Contributing + +Issues, PRs, new skills, and new design systems are all welcome. The highest-leverage contributions are usually one folder, one Markdown file, or one PR-sized adapter: + +- **Add a skill** — drop a folder into [`skills/`](skills/) following the [`SKILL.md`][skill] convention. +- **Add a design system** — drop a `DESIGN.md` into [`design-systems//`](design-systems/) using the 9-section schema. +- **Wire up a new coding-agent CLI** — one entry in [`daemon/agents.js`](daemon/agents.js). + +Full walkthrough, bar-for-merging, code style, and what we don't accept → [`CONTRIBUTING.md`](CONTRIBUTING.md) ([简体中文](CONTRIBUTING.zh-CN.md)). ## License diff --git a/README.zh-CN.md b/README.zh-CN.md index 2cda340ff..763c2ca62 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,9 +1,9 @@ -# Open Claude Design +# Open Design -> **给设计的 Claude Code。** 一个本地优先、可部署到 Vercel 的开源 [Claude Design][cd] 复刻 —— 你机器上已经装好的 coding agent（Claude Code、Codex、Cursor Agent、Gemini CLI、OpenCode、Qwen）就是设计引擎，由可组合的 **Skills** 和 **71 套品牌级 Design System** 驱动。 +> **[Claude Design][cd] 的开源替代品。** 本地优先、可部署到 Vercel、每一层都 BYOK —— 你机器上已经装好的 coding agent（Claude Code、Codex、Cursor Agent、Gemini CLI、OpenCode、Qwen）就是设计引擎，由 **19 个可组合 Skills** 和 **71 套品牌级 Design System** 驱动。

- Open Claude Design banner + Open Design 封面：与本地 AI 智能体共同设计

@@ -20,15 +20,15 @@ ## 为什么要做这个 -Anthropic 的 [Claude Design][cd]（2026-04-17 发布，基于 Opus 4.7）让大家第一次看到：当一个 LLM 不再写废话、开始直接交付设计成品，会是什么样子。它瞬间出圈 —— 然后保持闭源、付费、只跑在云上、绑定 Anthropic 的模型和 Anthropic 的内部 skill。 +Anthropic 的 [Claude Design][cd]（2026-04-17 发布，基于 Opus 4.7）让大家第一次看到：当一个 LLM 不再写废话、开始直接交付设计成品，会是什么样子。它瞬间出圈 —— 然后保持**闭源**、付费、只跑在云上、绑定 Anthropic 的模型和 Anthropic 的内部 skill。没有 checkout，没有自托管，没有 Vercel 部署，也换不了自己的 agent。 -**Open Claude Design（OCD）是它的开源底座。** 我们不做 agent —— 你笔记本上最强的 coding agent 已经装好了。我们要做的，是把它接进一个 skill 驱动的设计工作流，跑在一个普通的 Web 应用里：本地 `pnpm dev`，云端 `vercel deploy`，每一层都 BYOK（自带 Key）。 +**Open Design（OD）就是它的开源替代品。** 同一套 loop、同一种「artifact-first」心智模型，但没有锁定。我们不做 agent —— 你笔记本上最强的 coding agent 已经装好了。我们要做的，是把它接进一个 skill 驱动的设计工作流，跑在一个普通的 Web 应用里：本地 `pnpm dev`，云端 `vercel deploy`，每一层都 BYOK（自带 Key）。 输入「帮我做一份杂志风的种子轮 pitch deck」。在模型挥洒第一个像素之前，**初始化问题表单**已经先跳出来。Agent 从 5 套精挑的视觉方向里选一个。一张活的 `TodoWrite` 计划卡片实时流入 UI。Daemon 在磁盘上构建出一个真实的项目目录，里面有 seed 模板、布局库、自检 checklist。Agent **强制 pre-flight** 读取它们，对自己的输出跑一轮**五维评审**，几秒后吐出一个 ``，渲染在沙盒 iframe 里。 -这不是「AI 试图做点设计」。这是一个被提示词栈训练得像高级设计师一样工作的 AI —— 有可用的文件系统、有确定性的色板库、有 checklist 文化。 +这不是「AI 试图做点设计」。这是一个被提示词栈训练得像高级设计师一样工作的 AI —— 有可用的文件系统、有确定性的色板库、有 checklist 文化 —— 也就是 Claude Design 立下的那条线，只是这次它开源、归你。 -OCD 站在四个开源项目的肩膀上： +OD 站在四个开源项目的肩膀上： - [**`alchaincyf/huashu-design`**（花叔的画术）](https://github.com/alchaincyf/huashu-design) —— 设计哲学的指南针。Junior-Designer 工作流、5 步品牌资产协议、anti-AI-slop checklist、五维自评审、以及方向选择器背后的「5 流派 × 20 种设计哲学」思路 —— 全部蒸馏进 [`src/prompts/discovery.ts`](src/prompts/discovery.ts)。 - [**`op7418/guizang-ppt-skill`**（歸藏的杂志风 PPT skill）](https://github.com/op7418/guizang-ppt-skill) —— Deck 模式。原样捆绑在 [`skills/guizang-ppt/`](skills/guizang-ppt/) 下，原 LICENSE 保留；杂志版式、WebGL hero、P0/P1/P2 checklist。 @@ -52,51 +52,130 @@ OCD 站在四个开源项目的肩膀上： ## 效果展示 -> 截图位为占位 —— 真实 UI 就是这些截图要拍的对象，请在 PR 里替换 `docs/screenshots/*.png`。 -
-入口页：选 skill + 选 design system + 写需求
+01 · 入口页
入口页 —— 选 skill、选 design system、写一行需求。同一个表面服务原型、deck、移动端、dashboard、editorial 页面所有 mode。 		-第一轮 discovery 表单
-初始化问题表单 —— 模型动笔之前，OCD 先把需求锁住：surface、受众、调性、品牌上下文、规模。30 秒勾选项秒杀 30 分钟来回返工。 +02 · 初始化问题表单
+初始化问题表单 —— 模型动笔之前，OD 先把需求锁住：surface、受众、调性、品牌上下文、规模。30 秒勾选项秒杀 30 分钟来回返工。
-5 套确定性视觉方向选择器
+03 · 方向选择器
方向选择器 —— 用户没有品牌上下文时，agent 自动跳第二个表单，5 套精选方向（Monocle / Modern Minimal / Tech Utility / Brutalist / Soft Warm）一个 radio 选完，色板 + 字体栈直接锁定，没有 freestyle 空间。 		-Live TodoWrite 进度卡片
+04 · 实时 todo 进度
实时 todo 进度 —— Agent 的计划以活卡片形式流入 UI。in_progress → completed 实时切换。用户能在中途以极低成本介入纠偏。
-沙盒 iframe 预览生成的 artifact
+05 · 沙盒预览
沙盒预览 —— 每个 <artifact> 都在干净的 srcdoc iframe 里渲染。可在文件工作区里就地编辑；可下载为 HTML / PDF / ZIP。 		-71 套 design system 库 + 调色板
+06 · 71 套 design system 库
71 套 design system 库 —— 每套产品系统都展示 4 色色卡。点进去看完整的 DESIGN.md、色板网格、live showcase。
-杂志风横向翻页 deck 输出
+07 · 杂志风 deck
Deck 模式（guizang-ppt） —— 内置的 guizang-ppt-skill 原样接入。杂志版式、WebGL hero 背景、单文件 HTML 输出、可导 PDF。 		-带 iPhone 15 Pro 外壳的移动端原型
+08 · 移动端原型
移动端原型 —— 像素级精确的 iPhone 15 Pro chrome（灵动岛、状态栏 SVG、Home Indicator）。多屏原型直接复用 /frames/ 共享资源，agent 永远不需要重新画一遍手机。
+## 内置 Skills + +19 个 skill，每个一个文件夹，都遵循 Claude Code 的 [`SKILL.md`][skill] 规范，并叠加 OD 的 `od:` frontmatter（`mode`、`platform`、`scenario`、`preview`、`design_system`）。 + +### 示例展示（Showcase examples） + +视觉表现最强、最适合上手第一跑的几条 skill。每条都附带可直接打开的 `example.html` —— 不用登录、不用配置，先看产出再下单。 + + + + + + + + + + + + + + + + + + +
+dating-web
+dating-web · prototype
消费级约会 / 婚恋仪表盘 —— 左侧栏、社区动态 ticker、头部 KPI、30 天双向匹配柱状图，editorial 字体，克制点缀色。 +		 +digital-eguide
+digital-eguide · template
两页数字 e-guide —— 封面（标题、作者、TOC 预告）+ 内文跨页（pull-quote + 步骤列表），创作者 / 生活方式风。 +
+email-marketing
+email-marketing · prototype
品牌新品发布邮件 —— 顶部 wordmark、hero 图、标题锁排、主 CTA、规格网格。居中单列 + 表格降级，邮件客户端安全。 +		 +gamified-app
+gamified-app · prototype
三屏游戏化移动 app 原型，黑色舞台 —— 封面 / 今日任务（XP 缎带 + 等级条）/ 任务详情。 +
+mobile-onboarding
+mobile-onboarding · prototype
三屏移动端引导流 —— splash、价值主张、登录。状态栏、滑动点、主 CTA。 +		 +motion-frames
+motion-frames · prototype
单帧 motion 设计 hero，CSS 循环动画 —— 旋转字环、地球、计时器。可直接交给 HyperFrames 等关键帧导出。 +
+social-carousel
+social-carousel · prototype
1080×1080 三连社媒轮播图 —— 三张电影感面板，标题前后呼应，品牌标识、loop 标记。 +		 +sprite-animation
+sprite-animation · prototype
像素 / 8-bit 动画解释器单帧 —— 米白通屏、像素吉祥物、动感日文标题、循环 CSS keyframes，可直接录屏成竖版视频。 +
+ +### 设计交付类 + +| Skill | Mode | 默认场景 | 产出 | +|---|---|---|---| +| [`web-prototype`](skills/web-prototype/) | prototype | 桌面 | 单页 HTML —— landing、营销、hero | +| [`saas-landing`](skills/saas-landing/) | prototype | 桌面 | hero / features / pricing / CTA 营销版式 | +| [`dashboard`](skills/dashboard/) | prototype | 桌面 | 带侧栏 + 数据密集型的后台 | +| [`pricing-page`](skills/pricing-page/) | prototype | 桌面 | 独立定价页 + 对比表 | +| [`docs-page`](skills/docs-page/) | prototype | 桌面 | 三栏文档版式 | +| [`blog-post`](skills/blog-post/) | prototype | 桌面 | 长文 editorial | +| [`mobile-app`](skills/mobile-app/) | prototype | 移动 | 带 iPhone 15 Pro / Pixel 外壳的 app 屏 | +| [`simple-deck`](skills/simple-deck/) | deck | 桌面 | 极简横滑 deck | +| [`guizang-ppt`](skills/guizang-ppt/) | deck | **deck 默认** | 杂志风网页 PPT —— 来自 [op7418/guizang-ppt-skill][guizang] | + +### 文档与办公产物类 + +| Skill | Mode | 产出 | +|---|---|---| +| [`pm-spec`](skills/pm-spec/) | template | PM 规范文档 + 目录 + 决策日志 | +| [`weekly-update`](skills/weekly-update/) | template | 团队周报：进度 / 阻塞 / 下一步 | +| [`meeting-notes`](skills/meeting-notes/) | template | 会议决策纪要 | +| [`eng-runbook`](skills/eng-runbook/) | template | 故障 runbook | +| [`finance-report`](skills/finance-report/) | template | 高管财务摘要 | +| [`hr-onboarding`](skills/hr-onboarding/) | template | 岗位入职计划 | +| [`invoice`](skills/invoice/) | template | 单页发票 | +| [`kanban-board`](skills/kanban-board/) | template | 看板快照 | +| [`team-okrs`](skills/team-okrs/) | template | OKR 计分表 | + +新增一个 skill 就是新增一个文件夹。读 [`docs/skills-protocol.md`](docs/skills-protocol.md) 了解扩展 frontmatter，fork 一个现有 skill，重启 daemon 即生效。 + ## 六个底层设计 ### 1 · 我们不带 agent，你的就够好 @@ -113,13 +192,13 @@ Daemon 启动时扫 `PATH`，找 [`claude`](https://docs.anthropic.com/en/docs/c ### 4 · 初始化问题表单干掉 80% 的来回返工 -OCD 的提示词栈把 `RULE 1` 写死了：每个新设计任务都从 `` 开始，**不是代码**。Surface · 受众 · 调性 · 品牌上下文 · 规模 · 约束。一段写得很长的需求里仍然有大量留白：视觉调性、色彩立场、规模 —— 而表单恰恰把这些用 30 秒勾选项锁死。错方向的代价是一轮对话，不是一份做完的 deck。 +OD 的提示词栈把 `RULE 1` 写死了：每个新设计任务都从 `` 开始，**不是代码**。Surface · 受众 · 调性 · 品牌上下文 · 规模 · 约束。一段写得很长的需求里仍然有大量留白：视觉调性、色彩立场、规模 —— 而表单恰恰把这些用 30 秒勾选项锁死。错方向的代价是一轮对话，不是一份做完的 deck。 这就是从 [`huashu-design`](https://github.com/alchaincyf/huashu-design) 蒸馏出来的 **Junior-Designer 模式**：开工前一次性批量问完，尽早 show 出一些可见的东西（哪怕只是灰色方块的 wireframe），让用户用最低成本介入纠偏。再叠加品牌资产协议（定位 · 下载 · `grep` hex · 写 `brand-spec.md` · 复述），这是输出从「AI freestyle」跳到「先看资料再画图的设计师」最关键的一步。 ### 5 · Daemon 让 agent 感觉自己就在你笔记本上 —— 因为它就是 -Daemon `spawn` CLI 时，`cwd` 设到该项目在 `.ocd/projects//` 下的 artifact 文件夹。Agent 拿到的 `Read` / `Write` / `Bash` / `WebFetch` 都是真工具，作用在真文件系统上。它能 `Read` skill 的 `assets/template.html`，能 `grep` 你的 CSS 拿 hex，能写一份 `brand-spec.md`，能落地生成的图片，能产出 `.pptx` / `.zip` / `.pdf` —— 这些文件在 turn 结束的时候作为下载 chip 出现在文件工作区里。Session、对话、消息、tab 都持久化在本地 SQLite 里 —— 明天再打开这个项目，agent 的 todo 卡片还在你昨天停下的地方。 +Daemon `spawn` CLI 时，`cwd` 设到该项目在 `.od/projects//` 下的 artifact 文件夹。Agent 拿到的 `Read` / `Write` / `Bash` / `WebFetch` 都是真工具，作用在真文件系统上。它能 `Read` skill 的 `assets/template.html`，能 `grep` 你的 CSS 拿 hex，能写一份 `brand-spec.md`，能落地生成的图片，能产出 `.pptx` / `.zip` / `.pdf` —— 这些文件在 turn 结束的时候作为下载 chip 出现在文件工作区里。Session、对话、消息、tab 都持久化在本地 SQLite 里 —— 明天再打开这个项目，agent 的 todo 卡片还在你昨天停下的地方。 ### 6 · 提示词栈本身就是产品 @@ -158,7 +237,7 @@ DISCOVERY 指令 （turn-1 表单、turn-2 品牌分支、TodoWrite、 │ /api/chat (SSE) │ │ │ └─────────┬────────────┘ - │ spawn(cli, [...], { cwd: .ocd/projects/ }) + │ spawn(cli, [...], { cwd: .od/projects/ }) ▼ ┌──────────────────────────────────────────────────────────┐ │ claude · codex · cursor-agent · gemini · opencode · qwen│ @@ -171,15 +250,15 @@ DISCOVERY 指令 （turn-1 表单、turn-2 品牌分支、TodoWrite、 | 前端 | Vite 5 + React 18 + TypeScript | | Daemon | Node 18+ · Express · SSE 流 · `better-sqlite3` 存项目/对话/消息/tab | | Agent 传输层 | `child_process.spawn`，Claude Code 走 `claude-stream-json` 解析器，其余走 line-buffered plain stdout | -| 存储 | 纯文件 `.ocd/projects//` + SQLite `.ocd/db.sqlite`（已 gitignore） | +| 存储 | 纯文件 `.od/projects//` + SQLite `.od/app.sqlite`（已 gitignore，daemon 启动自建） | | 预览 | 沙盒 iframe（`srcdoc`）+ 每个 skill 的 `` parser | | 导出 | HTML（内联资源）· PDF（浏览器打印）· PPTX（skill 自定义）· ZIP（archiver） | ## Quickstart ```bash -git clone https://github.com//open-claude-design.git -cd open-claude-design +git clone https://github.com/nexu-io/open-design.git +cd open-design pnpm install # 或 npm install pnpm dev:all # daemon (:7456) + Vite (:5173) 一起起 open http://localhost:5173 @@ -190,22 +269,40 @@ open http://localhost:5173 1. 检测你 `PATH` 上有哪些 agent CLI，自动选一个。 2. 加载 19 个 skill + 71 套 design system。 3. 弹欢迎对话框，让你贴 Anthropic key（仅 BYOK 兜底路径需要）。 +4. **自动创建 `./.od/`** —— 本地运行时目录，存放 SQLite 项目库、各项目工作区、保存下来的 artifact。**没有** `od init` 这一步，daemon 启动时会自己 `mkdir`。 输入需求，回车，看 question form 跳出来，填，看 todo 卡片流动，看 artifact 渲染。点 **Save to disk** 或导出整个项目 ZIP。 +### 第一次跑起来（`./.od/` 解释） + +Daemon 在仓库根下维护一个隐藏目录，里面所有内容都已 gitignore，纯本机数据，**不要** commit。 + +``` +.od/ +├── app.sqlite ← 项目 · 对话 · 消息 · 打开的 tab +├── artifacts/ ← Save to disk 一次性渲染（带时间戳） +└── projects// ← 每个项目的工作目录，也是 agent 的 cwd +``` + +| 想做什么 | 怎么做 | +|---|---| +| 看一眼里面有啥 | `ls -la .od && sqlite3 .od/app.sqlite '.tables'` | +| 完全清空，从零再来 | 先停 daemon，再 `rm -rf .od`，然后重新 `pnpm dev:all` | +| 换到别的位置 | 暂不支持 —— 路径是相对仓库根写死的 | + 完整文件地图、脚本、排错 → [`QUICKSTART.md`](QUICKSTART.md)。 ## 仓库结构 ``` -open-claude-design/ +open-design/ ├── README.md ← 英文 ├── README.zh-CN.md ← 本文件 ├── QUICKSTART.md ← 跑 / 构建 / 部署 -├── package.json ← 单 bin: ocd +├── package.json ← 单 bin: od │ ├── daemon/ ← Node + Express，唯一的服务端 -│ ├── cli.js ← `ocd` 二进制入口 +│ ├── cli.js ← `od` 二进制入口 │ ├── server.js ← /api/* 路由（projects、chat、files、exports） │ ├── agents.js ← PATH 扫描器 + 各 CLI 的 argv 拼装 │ ├── claude-stream.js ← Claude Code stdout 流式 JSON 解析 @@ -288,7 +385,7 @@ open-claude-design/ ├── docs/ │ ├── spec.md ← 产品定义、场景、差异化 │ ├── architecture.md ← 拓扑、数据流、组件 -│ ├── skills-protocol.md ← 扩展 SKILL.md 的 ocd: frontmatter +│ ├── skills-protocol.md ← 扩展 SKILL.md 的 od: frontmatter │ ├── agent-adapters.md ← 各 CLI 检测 + 派发 │ ├── modes.md ← prototype / deck / template / design-system │ ├── references.md ← 详尽的引用与师承 @@ -296,65 +393,16 @@ open-claude-design/ │ ├── schemas/ ← JSON schema │ └── examples/ ← 标准 artifact 样例 │ -└── .ocd/ ← 运行时数据，已 gitignore +└── .od/ ← 运行时数据，已 gitignore，daemon 启动自建 + ├── app.sqlite ← 项目 / 对话 / 消息 / tab ├── projects// ← 每个项目的工作目录（agent 的 cwd） - ├── artifacts/ ← 单次保存的 artifact - └── db.sqlite ← 项目 / 对话 / 消息 / tab + └── artifacts/ ← 单次保存的 artifact ``` -## 内置 Skills - -19 个 skill，每个一个文件夹，都遵循 Claude Code 的 [`SKILL.md`][skill] 规范，并叠加 OCD 的 `ocd:` frontmatter（`mode`、`platform`、`scenario`、`preview`、`design_system`）。 - -### 示例展示（Showcase examples） - -视觉表现最强、最适合上手第一跑的几条 skill。每条都附带可直接打开的 `example.html`，先看产出再下单。 - -| Skill | Mode | 产出 | -|---|---|---| -| [`dating-web`](skills/dating-web/) | prototype | 消费级约会 / 婚恋仪表盘 —— 左侧栏、社区动态 ticker、头部 KPI、30 天双向匹配柱状图，editorial 字体，克制点缀色 | -| [`digital-eguide`](skills/digital-eguide/) | template | 两页数字 e-guide —— 封面（标题、作者、TOC 预告）+ 内文跨页（pull-quote + 步骤列表），创作者 / 生活方式风 | -| [`email-marketing`](skills/email-marketing/) | prototype | 品牌新品发布邮件 —— 顶部 wordmark、hero 图、标题锁排、主 CTA、规格网格。居中单列 + 表格降级，邮件客户端安全 | -| [`gamified-app`](skills/gamified-app/) | prototype | 三屏游戏化移动 app 原型，黑色舞台 —— 封面 / 今日任务（XP 缎带 + 等级条）/ 任务详情 | -| [`mobile-onboarding`](skills/mobile-onboarding/) | prototype | 三屏移动端引导流 —— splash、价值主张、登录。状态栏、滑动点、主 CTA | -| [`motion-frames`](skills/motion-frames/) | prototype | 单帧 motion 设计 hero，CSS 循环动画 —— 旋转字环、地球、计时器。可直接交给 HyperFrames 等关键帧导出 | -| [`social-carousel`](skills/social-carousel/) | prototype | 1080×1080 三连社媒轮播图 —— 三张电影感面板，标题前后呼应，品牌标识、loop 标记 | -| [`sprite-animation`](skills/sprite-animation/) | prototype | 像素 / 8-bit 动画解释器单帧 —— 米白通屏、像素吉祥物、动感日文标题、循环 CSS keyframes，可直接录屏成竖版视频 | - -### 设计交付类 - -| Skill | Mode | 默认场景 | 产出 | -|---|---|---|---| -| [`web-prototype`](skills/web-prototype/) | prototype | 桌面 | 单页 HTML —— landing、营销、hero | -| [`saas-landing`](skills/saas-landing/) | prototype | 桌面 | hero / features / pricing / CTA 营销版式 | -| [`dashboard`](skills/dashboard/) | prototype | 桌面 | 带侧栏 + 数据密集型的后台 | -| [`pricing-page`](skills/pricing-page/) | prototype | 桌面 | 独立定价页 + 对比表 | -| [`docs-page`](skills/docs-page/) | prototype | 桌面 | 三栏文档版式 | -| [`blog-post`](skills/blog-post/) | prototype | 桌面 | 长文 editorial | -| [`mobile-app`](skills/mobile-app/) | prototype | 移动 | 带 iPhone 15 Pro / Pixel 外壳的 app 屏 | -| [`simple-deck`](skills/simple-deck/) | deck | 桌面 | 极简横滑 deck | -| [`guizang-ppt`](skills/guizang-ppt/) | deck | **deck 默认** | 杂志风网页 PPT —— 来自 [op7418/guizang-ppt-skill][guizang] | - -### 文档与办公产物类 - -| Skill | Mode | 产出 | -|---|---|---| -| [`pm-spec`](skills/pm-spec/) | template | PM 规范文档 + 目录 + 决策日志 | -| [`weekly-update`](skills/weekly-update/) | template | 团队周报：进度 / 阻塞 / 下一步 | -| [`meeting-notes`](skills/meeting-notes/) | template | 会议决策纪要 | -| [`eng-runbook`](skills/eng-runbook/) | template | 故障 runbook | -| [`finance-report`](skills/finance-report/) | template | 高管财务摘要 | -| [`hr-onboarding`](skills/hr-onboarding/) | template | 岗位入职计划 | -| [`invoice`](skills/invoice/) | template | 单页发票 | -| [`kanban-board`](skills/kanban-board/) | template | 看板快照 | -| [`team-okrs`](skills/team-okrs/) | template | OKR 计分表 | - -新增一个 skill 就是新增一个文件夹。读 [`docs/skills-protocol.md`](docs/skills-protocol.md) 了解扩展 frontmatter，fork 一个现有 skill，重启 daemon 即生效。 - ## Design System

- 71 套 design system 库 + 71 套 Design Systems 库 — 编辑版式双页

71 套开箱即用，每套一个 [`DESIGN.md`](design-systems/README.md)： @@ -386,7 +434,7 @@ open-claude-design/ ## 视觉方向 -当用户没有品牌资产时，agent 会跳第二个表单，5 套精选方向 —— 这是 [`huashu-design` 的「设计方向顾问 · 5 流派 × 20 种设计哲学」 fallback](https://github.com/alchaincyf/huashu-design#%E8%AE%BE%E8%AE%A1%E6%96%B9%E5%90%91%E9%A1%BE%E9%97%AE-fallback) 在 OCD 里的落地。每一套都是确定性 spec —— OKLch 色板、字体栈、版式姿态、参考列表 —— agent 直接把它**原样**绑进 seed 模板的 `:root`。一个 radio 选完，整套视觉系统全部锁定。零 freestyle，零 AI slop。 +当用户没有品牌资产时，agent 会跳第二个表单，5 套精选方向 —— 这是 [`huashu-design` 的「设计方向顾问 · 5 流派 × 20 种设计哲学」 fallback](https://github.com/alchaincyf/huashu-design#%E8%AE%BE%E8%AE%A1%E6%96%B9%E5%90%91%E9%A1%BE%E9%97%AE-fallback) 在 OD 里的落地。每一套都是确定性 spec —— OKLch 色板、字体栈、版式姿态、参考列表 —— agent 直接把它**原样**绑进 seed 模板的 `:root`。一个 radio 选完，整套视觉系统全部锁定。零 freestyle，零 AI slop。 | 方向 | 调性 | 参考 | |---|---|---| @@ -400,7 +448,7 @@ open-claude-design/ ## 反 AI Slop 机制 -下面整套机制都是 [`huashu-design`](https://github.com/alchaincyf/huashu-design) 的 playbook，被移植进 OCD 的提示词栈，并通过 skill 副文件 pre-flight 让每个 skill 都能落地执行。看 [`src/prompts/discovery.ts`](src/prompts/discovery.ts) 是真实文案： +下面整套机制都是 [`huashu-design`](https://github.com/alchaincyf/huashu-design) 的 playbook，被移植进 OD 的提示词栈，并通过 skill 副文件 pre-flight 让每个 skill 都能落地执行。看 [`src/prompts/discovery.ts`](src/prompts/discovery.ts) 是真实文案： - **先表单。** Turn 1 必须是 ``，**不准** thinking、不准 tools、不准旁白。用户用 radio 速度选默认。 - **品牌资产协议。** 用户贴截图或 URL 时，agent 走 5 步流程（定位 · 下载 · grep hex · 写 `brand-spec.md` · 复述）才能开始写 CSS。**绝不从记忆里猜品牌色**。 @@ -411,7 +459,7 @@ open-claude-design/ ## 横向对比 -| 维度 | [Claude Design][cd]（Anthropic） | [Open CoDesign][ocod] | **Open Claude Design** | +| 维度 | [Claude Design][cd]（Anthropic） | [Open CoDesign][ocod] | **Open Design** | |---|---|---|---| | License | 闭源 | MIT | **Apache-2.0** | | 形态 | Web (claude.ai) | 桌面 (Electron) | **Web 应用 + 本地 daemon** | @@ -432,7 +480,7 @@ open-claude-design/ | PPT skill 复用 | N/A | 内置 | **[`guizang-ppt-skill`][guizang] 直接接入** | | 计费门槛 | Pro / Max / Team | BYOK | **BYOK** | -[cd]: https://www.anthropic.com/news/claude-design +[cd]: https://x.com/claudeai/status/2045156267690213649 [ocod]: https://github.com/OpenCoworkAI/open-codesign [piai]: https://github.com/mariozechner/pi-ai [acd]: https://github.com/VoltAgent/awesome-claude-design @@ -461,7 +509,7 @@ Daemon 启动时从 `PATH` 自动检测，无需配置。 | 项目 | 在这里的角色 | |---|---| -| [`Claude Design`][cd] | 本仓库为它提供开源底座的闭源产品。 | +| [`Claude Design`][cd] | 本仓库为之提供开源替代的闭源产品。 | | [**`alchaincyf/huashu-design`**（花叔的画术）](https://github.com/alchaincyf/huashu-design) | 设计哲学的核心。Junior-Designer 工作流、5 步品牌资产协议、anti-AI-slop checklist、五维自评审、以及方向选择器背后的「5 流派 × 20 种设计哲学」库 —— 全部蒸馏进 [`src/prompts/discovery.ts`](src/prompts/discovery.ts) 与 [`src/prompts/directions.ts`](src/prompts/directions.ts)。 | | [**`op7418/guizang-ppt-skill`**（歸藏）][guizang] | Magazine-web-PPT skill 原样捆绑在 [`skills/guizang-ppt/`](skills/guizang-ppt/) 下，原 LICENSE 保留。Deck 模式默认。P0/P1/P2 checklist 文化也被借给了所有其他 skill。 | | [**`multica-ai/multica`**](https://github.com/multica-ai/multica) | Daemon + adapter 架构。PATH 扫描式 agent 检测、本地 daemon 作为唯一特权进程、agent-as-teammate 世界观。我们采纳模型，不 vendor 代码。 | @@ -481,8 +529,8 @@ Daemon 启动时从 `PATH` 自动检测，无需配置。 - [ ] 评论模式手术刀编辑（点元素 → 指令 → 局部 patch）—— 模式来自 [`open-codesign`][ocod] - [ ] AI 自吐 tweaks 面板（模型自己抛出值得调的参数）—— 模式来自 [`open-codesign`][ocod] - [ ] Vercel + 隧道部署食谱（Topology B） -- [ ] 一行 `npx ocd init` 脚手架带 `DESIGN.md` -- [ ] Skill 市场（`ocd skills install `） +- [ ] 一行 `npx od init` 脚手架带 `DESIGN.md` +- [ ] Skill 市场（`od skills install `） 分阶段交付计划在 [`docs/roadmap.md`](docs/roadmap.md)。 @@ -490,7 +538,15 @@ Daemon 启动时从 `PATH` 自动检测，无需配置。 这是一个早期实现 —— 闭环（检测 → 选 skill + design system → 对话 → 解析 `` → 预览 → 保存）已经端到端跑通。提示词栈和 skill 库是价值最重的部分，目前已稳定。组件级 UI 仍在每天迭代。 -欢迎 issue、PR、新 skill、新 design system。 +## 贡献 + +欢迎 issue、PR、新 skill、新 design system。收益最高的贡献往往就是一个文件夹、一份 Markdown，或者一个 PR 大小的 adapter： + +- **加一个 skill** —— 往 [`skills/`](skills/) 丢一个文件夹，遵循 [`SKILL.md`][skill] 规范。 +- **加一套 design system** —— 往 [`design-systems//`](design-systems/) 丢一份 `DESIGN.md`，用 9 段式 schema。 +- **接入一个新的 coding-agent CLI** —— 在 [`daemon/agents.js`](daemon/agents.js) 里加一项。 + +完整流程、合并硬线、代码风格、我们不接收的 PR 类型 → [`CONTRIBUTING.zh-CN.md`](CONTRIBUTING.zh-CN.md)（[English](CONTRIBUTING.md)）。 ## License diff --git a/assets/frames/README.md b/assets/frames/README.md index 84d87fdad..809bd2785 100644 --- a/assets/frames/README.md +++ b/assets/frames/README.md @@ -43,7 +43,7 @@ path inside its inner viewport: > \`\`\` -In an OCD-managed project, the recommended pattern is: +In an OD-managed project, the recommended pattern is: \`\`\` my-project/ diff --git a/daemon/cli.js b/daemon/cli.js index dd352eced..2cb1deb55 100644 --- a/daemon/cli.js +++ b/daemon/cli.js @@ -2,7 +2,7 @@ import { startServer } from './server.js'; const args = process.argv.slice(2); -let port = Number(process.env.OCD_PORT) || 7456; +let port = Number(process.env.OD_PORT) || 7456; let open = true; for (let i = 0; i < args.length; i++) { @@ -12,7 +12,7 @@ for (let i = 0; i < args.length; i++) { } else if (a === '--no-open') { open = false; } else if (a === '-h' || a === '--help') { - console.log(`Usage: ocd [--port ] [--no-open] + console.log(`Usage: od [--port ] [--no-open] Starts a local daemon that: * scans PATH for installed code-agent CLIs (claude, codex, gemini, opencode, cursor-agent, ...) @@ -24,7 +24,7 @@ Starts a local daemon that: } startServer({ port }).then(url => { - console.log(`[ocd] listening on ${url}`); + console.log(`[od] listening on ${url}`); if (open) { const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' diff --git a/daemon/db.js b/daemon/db.js index 2af15522d..4fbf4d370 100644 --- a/daemon/db.js +++ b/daemon/db.js @@ -1,6 +1,6 @@ // SQLite-backed persistence for projects, conversations, messages, and the // per-project set of open file tabs. The on-disk project folder under -// .ocd/projects// is still the single owner of the user's actual files +// .od/projects// is still the single owner of the user's actual files // (HTML artifacts, sketches, uploads); this database tracks the metadata // that used to live in localStorage. @@ -12,7 +12,7 @@ let dbInstance = null; export function openDatabase(projectRoot) { if (dbInstance) return dbInstance; - const dir = path.join(projectRoot, '.ocd'); + const dir = path.join(projectRoot, '.od'); fs.mkdirSync(dir, { recursive: true }); const file = path.join(dir, 'app.sqlite'); const db = new Database(file); diff --git a/daemon/lint-artifact.js b/daemon/lint-artifact.js index 294317264..c50110c55 100644 --- a/daemon/lint-artifact.js +++ b/daemon/lint-artifact.js @@ -143,7 +143,7 @@ export function lintArtifact(rawHtml) { severity: 'P0', id: 'left-accent-card', message: 'Rounded card with a coloured left border — the canonical AI-slop card pattern.', - fix: 'Drop either the border-radius (set 0px) or the border-left. Cards in the OCD seed use hairline borders all-round, no left accent.', + fix: 'Drop either the border-radius (set 0px) or the border-left. Cards in the OD seed use hairline borders all-round, no left accent.', snippet: clip(lam[0]), }); } @@ -262,19 +262,19 @@ export function lintArtifact(rawHtml) { } // ── P2-1: missing comment-mode anchor on
──────────────── - // Either `data-ocd-id` (web/mobile prototypes) or `data-screen-label` + // Either `data-od-id` (web/mobile prototypes) or `data-screen-label` // (decks) counts. Whichever the artifact uses, every
should // carry one so the chat layer can target it. const sections = html.match(/]*>/gi) ?? []; const tagged = sections.filter( - (s) => /data-ocd-id\s*=/.test(s) || /data-screen-label\s*=/.test(s), + (s) => /data-od-id\s*=/.test(s) || /data-screen-label\s*=/.test(s), ).length; if (sections.length > 0 && tagged < sections.length) { out.push({ severity: 'P2', id: 'missing-section-anchor', - message: `${sections.length - tagged} of ${sections.length}
s lack data-ocd-id (or data-screen-label).`, - fix: 'Add data-ocd-id="kebab-slug" (or data-screen-label="01 Cover" for slides) to every top-level
so comment mode can target it.', + message: `${sections.length - tagged} of ${sections.length}
s lack data-od-id (or data-screen-label).`, + fix: 'Add data-od-id="kebab-slug" (or data-screen-label="01 Cover" for slides) to every top-level
so comment mode can target it.', }); } diff --git a/daemon/projects.js b/daemon/projects.js index 70117042f..c1a94e544 100644 --- a/daemon/projects.js +++ b/daemon/projects.js @@ -1,5 +1,5 @@ // Project files registry. Each project is a folder under -// /.ocd/projects//. The frontend's project list +// /.od/projects//. The frontend's project list // (localStorage) carries metadata; this module is the single owner of the // on-disk content (HTML artifacts, sketches, uploaded images, pasted text). // diff --git a/daemon/server.js b/daemon/server.js index af6b60936..f3a624648 100644 --- a/daemon/server.js +++ b/daemon/server.js @@ -50,11 +50,11 @@ const PROJECT_ROOT = path.resolve(__dirname, '..'); const STATIC_DIR = path.join(PROJECT_ROOT, 'dist'); const SKILLS_DIR = path.join(PROJECT_ROOT, 'skills'); const DESIGN_SYSTEMS_DIR = path.join(PROJECT_ROOT, 'design-systems'); -const ARTIFACTS_DIR = path.join(PROJECT_ROOT, '.ocd', 'artifacts'); -const PROJECTS_DIR = path.join(PROJECT_ROOT, '.ocd', 'projects'); +const ARTIFACTS_DIR = path.join(PROJECT_ROOT, '.od', 'artifacts'); +const PROJECTS_DIR = path.join(PROJECT_ROOT, '.od', 'projects'); fs.mkdirSync(PROJECTS_DIR, { recursive: true }); -const UPLOAD_DIR = path.join(os.tmpdir(), 'ocd-uploads'); +const UPLOAD_DIR = path.join(os.tmpdir(), 'od-uploads'); fs.mkdirSync(UPLOAD_DIR, { recursive: true }); fs.mkdirSync(ARTIFACTS_DIR, { recursive: true }); @@ -580,7 +580,7 @@ export async function startServer({ port = 7456 } = {}) { // No mtime-based caching — frames are static and small. app.use('/frames', express.static(path.join(PROJECT_ROOT, 'assets', 'frames'))); - // Project files. Each project owns a flat folder under .ocd/projects// + // Project files. Each project owns a flat folder under .od/projects// // containing every file the user has uploaded, pasted, sketched, or that // the agent has generated. Names are sanitized; paths are confined to the // project's own folder (see daemon/projects.js). diff --git a/daemon/skills.js b/daemon/skills.js index da1a34b7c..04e6edb7d 100644 --- a/daemon/skills.js +++ b/daemon/skills.js @@ -24,20 +24,27 @@ export async function listSkills(skillsRoot) { const raw = await readFile(skillPath, 'utf8'); const { data, body } = parseFrontmatter(raw); const hasAttachments = await dirHasAttachments(dir); - const mode = data.ocd?.mode || inferMode(body, data.description); + const mode = data.od?.mode || inferMode(body, data.description); out.push({ id: data.name || entry.name, name: data.name || entry.name, description: data.description || '', triggers: Array.isArray(data.triggers) ? data.triggers : [], mode, - platform: normalizePlatform(data.ocd?.platform, mode, body, data.description), - scenario: normalizeScenario(data.ocd?.scenario, body, data.description), - previewType: data.ocd?.preview?.type || 'html', - designSystemRequired: data.ocd?.design_system?.requires ?? true, - defaultFor: normalizeDefaultFor(data.ocd?.default_for), - upstream: typeof data.ocd?.upstream === 'string' ? data.ocd.upstream : null, - featured: normalizeFeatured(data.ocd?.featured), + platform: normalizePlatform(data.od?.platform, mode, body, data.description), + scenario: normalizeScenario(data.od?.scenario, body, data.description), + previewType: data.od?.preview?.type || 'html', + designSystemRequired: data.od?.design_system?.requires ?? true, + defaultFor: normalizeDefaultFor(data.od?.default_for), + upstream: typeof data.od?.upstream === 'string' ? data.od.upstream : null, + featured: normalizeFeatured(data.od?.featured), + // Optional metadata hints used by 'Use this prompt' fast-create so + // the resulting project mirrors the shipped example.html. Each hint + // is only consumed when its kind matches the skill mode; missing + // hints fall back to the same defaults the new-project form uses. + fidelity: normalizeFidelity(data.od?.fidelity), + speakerNotes: normalizeBoolHint(data.od?.speaker_notes), + animations: normalizeBoolHint(data.od?.animations), examplePrompt: derivePrompt(data), body: hasAttachments ? withSkillRootPreamble(body, dir) : body, dir, @@ -85,7 +92,28 @@ function normalizeDefaultFor(value) { return [String(value)]; } -// Coerce `ocd.featured` into a numeric priority. Lower numbers float to the +// Optional `od.fidelity` hint for prototype skills. Only 'wireframe' and +// 'high-fidelity' are meaningful — anything else collapses to null so the +// caller falls back to the form default ('high-fidelity'). +function normalizeFidelity(value) { + if (value === 'wireframe' || value === 'high-fidelity') return value; + return null; +} + +// Coerce truthy / falsy strings ("true", "yes", "false", "no") and booleans +// to a real boolean. Returns null for anything we can't interpret so the +// caller knows to fall back to the form default. +function normalizeBoolHint(value) { + if (typeof value === 'boolean') return value; + if (typeof value === 'string') { + const v = value.trim().toLowerCase(); + if (v === 'true' || v === 'yes' || v === '1') return true; + if (v === 'false' || v === 'no' || v === '0') return false; + } + return null; +} + +// Coerce `od.featured` into a numeric priority. Lower numbers float to the // top of the Examples gallery; `true` is treated as priority 1; anything // missing/unrecognised becomes null so non-featured skills keep their // natural alphabetical order. @@ -99,12 +127,12 @@ function normalizeFeatured(value) { return null; } -// Prefer an explicitly authored `ocd.example_prompt`. Fall back to the +// Prefer an explicitly authored `od.example_prompt`. Fall back to the // skill description's first sentence — it's already written in actionable // language ("Admin / analytics dashboard in a single HTML file…") so it // serves as a passable starter prompt. function derivePrompt(data) { - const explicit = data.ocd?.example_prompt; + const explicit = data.od?.example_prompt; if (typeof explicit === 'string' && explicit.trim()) return explicit.trim(); const desc = typeof data.description === 'string' ? data.description.trim() : ''; if (!desc) return ''; diff --git a/design-systems/README.md b/design-systems/README.md index 7335e1dcc..85265fec2 100644 --- a/design-systems/README.md +++ b/design-systems/README.md @@ -6,7 +6,7 @@ will read it as part of its system prompt. ## What's bundled -- **`default/`** — Neutral Modern. Hand-authored starter for the OCD spec. +- **`default/`** — Neutral Modern. Hand-authored starter for the OD spec. - **`warm-editorial/`** — Warm Editorial. Hand-authored serif starter. - **69 product systems**, imported from [`VoltAgent/awesome-design-md`](https://github.com/VoltAgent/awesome-design-md) diff --git a/docs/agent-adapters.md b/docs/agent-adapters.md index 1759b74eb..aa14bad2f 100644 --- a/docs/agent-adapters.md +++ b/docs/agent-adapters.md @@ -2,7 +2,7 @@ **Parent:** [`spec.md`](spec.md) · **Siblings:** [`architecture.md`](architecture.md) · [`skills-protocol.md`](skills-protocol.md) · [`modes.md`](modes.md) -The adapter layer is OCD's most load-bearing design decision. We delegate the **entire agent loop** — model calls, tool use, context management, permission handling, resume, cancel — to the user's existing code agent CLI. OCD's job is to detect it, feed it a skill + prompt + working directory, and stream its output back to the web UI. +The adapter layer is OD's most load-bearing design decision. We delegate the **entire agent loop** — model calls, tool use, context management, permission handling, resume, cancel — to the user's existing code agent CLI. OD's job is to detect it, feed it a skill + prompt + working directory, and stream its output back to the web UI. > **Thesis:** The code agent space has already converged on a few strong implementations (Claude Code, Codex, Cursor Agent, Gemini CLI, OpenCode, OpenClaw). Reimplementing a 7th is worse than just talking to all of them. > @@ -70,7 +70,7 @@ type AgentEvent = ## 2. Detection strategy -Run all adapters' `detect()` in parallel on daemon start, then cache results in `~/.open-claude-design/agents.json` with a 24h TTL. Re-detect on daemon `SIGHUP`. +Run all adapters' `detect()` in parallel on daemon start, then cache results in `~/.open-design/agents.json` with a 24h TTL. Re-detect on daemon `SIGHUP`. Each adapter uses **two signals**: @@ -98,7 +98,7 @@ If both signals agree, detection is confident. If only one signal fires, we mark Skills travel into each agent via one of three strategies, in order of preference: ### 4.1 Native skill loading (preferred) -Agent scans its own `~/./skills/` on launch. We symlink OCD's skill into that dir (see [`skills-protocol.md`](skills-protocol.md) §3) and let the agent pick it up natively. Zero prompt overhead. +Agent scans its own `~/./skills/` on launch. We symlink OD's skill into that dir (see [`skills-protocol.md`](skills-protocol.md) §3) and let the agent pick it up natively. Zero prompt overhead. - **Works for:** Claude Code. Codex (version-dependent). OpenCode. @@ -131,10 +131,10 @@ The adapter declares which strategy to use via `capabilities().nativeSkillLoadin - Invocation: direct Anthropic Messages API with `stream: true`. - Skill loading: prompt injection only — read the skill dir, inline everything. -- Tool use: we register `Read/Write/Edit` as tools, implement them in the daemon against the artifact cwd, and run the loop ourselves. This is the one place OCD does own the loop — because the user has no agent at all. Keep it as dumb as possible. +- Tool use: we register `Read/Write/Edit` as tools, implement them in the daemon against the artifact cwd, and run the loop ourselves. This is the one place OD does own the loop — because the user has no agent at all. Keep it as dumb as possible. - Surgical edits: approximated by regenerating the whole target file with "only change X" in the prompt. - Model: Claude Sonnet 4.6 default; Opus 4.7 behind a flag. -- **Why ship this at all?** Topology C requires it (no daemon available in a pure-Vercel deploy). Also, users trying OCD for the first time without a CLI installed still get a working experience. +- **Why ship this at all?** Topology C requires it (no daemon available in a pure-Vercel deploy). Also, users trying OD for the first time without a CLI installed still get a working experience. ### 5.3 Codex @@ -173,7 +173,7 @@ The web UI reads `agents.capabilities()` and disables features that the active a | Comment mode (click to refine) | `surgicalEdit: true` | Hidden; show tooltip explaining why | | Streaming tool-call feed | `streaming: true` | Show a spinner only | | Resume interrupted run | `resume: true` | "Cancel + restart" only | -| Skill picker shows skill with `ocd.capabilities_required` | all listed caps | Skill greyed out with reason | +| Skill picker shows skill with `od.capabilities_required` | all listed caps | Skill greyed out with reason | This is how we avoid "works on my Claude Code, breaks on your Gemini" — we detect, degrade, and document. @@ -192,7 +192,7 @@ Switching mid-run is not allowed (cancel first). The artifact is agent-agnostic; ## 8. Fallback chain -If the user's preferred agent fails (crash, auth, timeout), OCD offers a one-click fallback in this order: +If the user's preferred agent fails (crash, auth, timeout), OD offers a one-click fallback in this order: 1. User's preferred agent (e.g. Cursor Agent) 2. Any other detected agent (Claude Code, if installed) @@ -206,14 +206,14 @@ First run: ``` $ pnpm dev -[ocd] daemon starting on :7431 -[ocd] detecting agents… -[ocd] ✓ claude-code v0.6.3 (auth: ok, skills dir linked) -[ocd] ✓ codex v0.8.1 (auth: ok) -[ocd] ✗ cursor-agent (not installed) -[ocd] ✗ gemini-cli (installed but not authenticated; run `gemini auth login`) -[ocd] ✓ api-fallback (ANTHROPIC_API_KEY found) -[ocd] daemon ready; 3 agents available +[od] daemon starting on :7431 +[od] detecting agents… +[od] ✓ claude-code v0.6.3 (auth: ok, skills dir linked) +[od] ✓ codex v0.8.1 (auth: ok) +[od] ✗ cursor-agent (not installed) +[od] ✗ gemini-cli (installed but not authenticated; run `gemini auth login`) +[od] ✓ api-fallback (ANTHROPIC_API_KEY found) +[od] daemon ready; 3 agents available ``` Web UI mirrors this in an agent-selector dropdown, with unauthenticated agents shown greyed out with a fix-it tooltip. @@ -222,8 +222,8 @@ Web UI mirrors this in an agent-selector dropdown, with unauthenticated agents s We inherit the underlying agent's permission model rather than building our own. This means: -- **Claude Code** respects its own `--allowed-tools` and `--permission-mode` flags. OCD passes through user preferences. -- **Codex / Cursor** sandbox by workspace; OCD always sets cwd to the artifact dir so nothing outside is visible by default. +- **Claude Code** respects its own `--allowed-tools` and `--permission-mode` flags. OD passes through user preferences. +- **Codex / Cursor** sandbox by workspace; OD always sets cwd to the artifact dir so nothing outside is visible by default. - **API fallback** is the one case we own. We implement a whitelist: only `Read`, `Write`, `Edit` tools, all rooted at the artifact cwd. Network access is off. The daemon never grants more authority to an agent than it had on its own. We don't run the agent in a privileged mode "for convenience." @@ -253,6 +253,6 @@ Each adapter is a separate module so community contributions can add new ones wi ## 12. Open questions - **Nested agents.** What if Claude Code's agent itself spawns a subagent? We receive events from the outer process only. v1 policy: surface only top-level events; summarize subagent activity as "sub-task" placeholder. -- **Billing awareness.** Some agents bill per message, some per token. OCD doesn't track cost in MVP; v1 adds an optional "usage" event from adapters that expose it. +- **Billing awareness.** Some agents bill per message, some per token. OD doesn't track cost in MVP; v1 adds an optional "usage" event from adapters that expose it. - **Windows support.** PATH scanning and `spawn` semantics differ on Windows. v1 targets macOS and Linux; Windows is best-effort. - **Docker-contained agents.** Some users run Claude Code in a container. Adapter needs a "remote" mode — probably same interface but talks over SSH. Phase 2+. diff --git a/docs/architecture.md b/docs/architecture.md index 5fbea6379..ac3389695 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -13,7 +13,7 @@ This doc describes the system topology, runtime modes, data flow, and file layou ## 1. Three deployment topologies -OCD is a web app plus a local daemon. The split means the same UI can run in three shapes: +OD is a web app plus a local daemon. The split means the same UI can run in three shapes: ### Topology A — Fully local (the default) @@ -24,7 +24,7 @@ OCD is a web app plus a local daemon. The split means the same UI can run in thr │ │ │ │ │ ws://localhost:7431 │ │ ▼ │ -│ ocd daemon (Node, long-running) │ +│ od daemon (Node, long-running) │ │ │ │ │ ▼ │ │ spawns: claude / codex / cursor / … │ @@ -36,22 +36,22 @@ One `pnpm dev` starts both the Next.js app and the daemon (via a predev script). ### Topology B — Web on Vercel + daemon on user's machine ``` -browser ──► ocd.yourdomain.com (Vercel) +browser ──► od.yourdomain.com (Vercel) │ │ ws(s):// user-provided URL (e.g. cloudflared tunnel) ▼ - ocd daemon on user's laptop + od daemon on user's laptop │ ▼ spawns: claude / codex / … ``` -The user runs `ocd daemon --expose` which prints a tunnel URL; they paste the URL into the deployed web app's "Connect daemon" screen. Daemon holds secrets; Vercel holds nothing sensitive. +The user runs `od daemon --expose` which prints a tunnel URL; they paste the URL into the deployed web app's "Connect daemon" screen. Daemon holds secrets; Vercel holds nothing sensitive. ### Topology C — Web on Vercel + direct API (no daemon) ``` -browser ──► ocd.yourdomain.com (Vercel serverless) +browser ──► od.yourdomain.com (Vercel serverless) │ ▼ Anthropic Messages API (BYOK stored in browser) @@ -91,8 +91,8 @@ The three topologies share the same web bundle; the difference is which transpor │ │ ▼ ▼ ┌─ agent CLIs ─┐ ┌─ filesystem ─┐ -│ claude │ │ ./.ocd/ │ -│ codex │ │ ~/.ocd/ │ +│ claude │ │ ./.od/ │ +│ codex │ │ ~/.od/ │ │ cursor-agent │ │ skills/ │ │ gemini │ │ DESIGN.md │ │ opencode │ └──────────────┘ @@ -107,10 +107,10 @@ The three topologies share the same web bundle; the difference is which transpor - **Why Next.js, not Vite SPA?** We want SSR for the marketing landing page + serverless routes for Topology C's direct-API path + Vercel deployment as a first-class citizen. An SPA would need a separate server for any of that. - **State:** Zustand for session/artifact stores. Browser-side only; hydrated from daemon on connect. - **Iframe preview:** Vendored React 18 + Babel standalone for JSX artifacts, following [Open CoDesign][ocod]'s approach. HTML artifacts load raw. See [§5](#5-preview-renderer). -- **Comment mode:** Click captures `[data-ocd-id]` on preview DOM, opens a popover, sends `{artifact_id, element_id, note}` to daemon → agent gets a surgical edit instruction. +- **Comment mode:** Click captures `[data-od-id]` on preview DOM, opens a popover, sends `{artifact_id, element_id, note}` to daemon → agent gets a surgical edit instruction. - **Slider UI:** When an agent emits a "tweak parameter" tool call (see [`skills-protocol.md`](skills-protocol.md) §4.2), the web app renders a live-update control that re-sends parameterized prompts without round-tripping the chat. -### 3.2 Local daemon (`ocd daemon`) +### 3.2 Local daemon (`od daemon`) Single binary via `pkg` or a thin Node script distributed over npm. Responsibilities: @@ -155,7 +155,7 @@ Conflicts resolve by priority (higher wins). Each skill parsed once; watched for Plain files on disk. Conventional layout per project: ``` -./.ocd/ +./.od/ ├── config.json # project-level daemon config ├── artifacts/ │ ├── 2026-04-24T10-03-12-landing/ @@ -169,8 +169,8 @@ Plain files on disk. Conventional layout per project: ``` Rationale: -- **Plain files** → users can `git add ./.ocd/artifacts/` and review designs in PRs. -- **`artifact.json` metadata** → OCD can reconstruct the artifact tree without a DB. +- **Plain files** → users can `git add ./.od/artifacts/` and review designs in PRs. +- **`artifact.json` metadata** → OD can reconstruct the artifact tree without a DB. - **`history.jsonl` not SQLite** → append-only, git-friendly, greppable. [Open CoDesign][ocod] uses SQLite; we deliberately don't. - **Sessions separate from artifacts** → sessions are ephemeral UI state; artifacts are durable. @@ -195,7 +195,7 @@ Rationale: 3. Daemon: a. picks active skill (prototype-skill) b. loads design-system (DESIGN.md) - c. materializes a new artifact dir under ./.ocd/artifacts// + c. materializes a new artifact dir under ./.od/artifacts// d. invokes agent adapter with: - system: skill's SKILL.md contents + DESIGN.md - user: original prompt @@ -242,9 +242,9 @@ Rationale: | File | Purpose | |---|---| -| `~/.open-claude-design/config.toml` | daemon-global: default agent preference, keys (optional, BYOK), telemetry opt-in (default off) | -| `~/.open-claude-design/agents.json` | cached agent detection results | -| `./.ocd/config.json` | project-local: active design system, preferred skills, preferred mode | +| `~/.open-design/config.toml` | daemon-global: default agent preference, keys (optional, BYOK), telemetry opt-in (default off) | +| `~/.open-design/agents.json` | cached agent detection results | +| `./.od/config.json` | project-local: active design system, preferred skills, preferred mode | | `./skills//SKILL.md` | skill manifest (standard Claude Code format) | | `./DESIGN.md` | active design system ([awesome-claude-design][acd] format) | @@ -288,35 +288,35 @@ pnpm dev # starts daemon on :7431, next on :3000 services: daemon: image: openclaudedesign/daemon - volumes: [ "~/.open-claude-design:/root/.open-claude-design", "./:/workspace" ] + volumes: [ "~/.open-design:/root/.open-design", "./:/workspace" ] ports: ["7431:7431"] web: image: openclaudedesign/web ports: ["3000:3000"] - environment: [ "OCD_DAEMON_URL=ws://daemon:7431" ] + environment: [ "OD_DAEMON_URL=ws://daemon:7431" ] ``` ### Vercel + local daemon (Topology B) ```sh vercel deploy # web only -ocd daemon --expose # user runs locally; prints tunnel URL +od daemon --expose # user runs locally; prints tunnel URL # user pastes URL into /connect UI ``` ### Vercel direct (Topology C) ```sh vercel deploy # same bundle -# flip VERCEL env flag OCD_MODE=direct to hide daemon-connect UI +# flip VERCEL env flag OD_MODE=direct to hide daemon-connect UI ``` ## 9. Security model | Surface | Threat | Mitigation | |---|---|---| -| Daemon WebSocket | Arbitrary local process talks to daemon | Token handshake; token printed on `ocd daemon` start, required in WS URL | +| Daemon WebSocket | Arbitrary local process talks to daemon | Token handshake; token printed on `od daemon` start, required in WS URL | | Artifact code in preview | XSS/cookie theft from host | `