vishwakarma

<div align="center"> <a href="#-why-this-exists"> <img src="assets/banner.png" alt="Vishwakarma — 设计智能，用于 AI 编程代理" width="100%" /> </a> <h1></h1> [](LICENSE) [](#-the-packages) [](#-the-skill-catalog) [](#-the-skill-catalog) [](#) **教任何编码代理构建看起来像是**设计**过的界面，而不是**生成**的界面，并给它工具来证明这一点。** 适用于 **Claude Code · Cursor · Windsurf · Cline · Roo Code · Codex · Gemini CLI · Copilot · Continue · Zed · Aider** — 以及任何 MCP 客户端。 ```text 从 https://github.com/yogvidwankhede/vishwakarma 安装技能 ``` _{开源 · Apache-2.0 · TypeScript · 零遥测} </div> --- ## 💡 为什么存在 询问任何有能力的模型来构建一个着陆页，你每次都会得到**相同的页面**： > 中央标题在三个等分特征卡上方。`<h1>`上从紫色到蓝色的渐变。一个边框半径和一个投影应用于所有内容。灰色在白色背景上的正文文本静默地未能通过对比度检查。没有空状态，没有加载状态，并且在真正的产品名称比“Acme”更长时布局会破坏。 页面并不**丑陋**。丑陋会很有趣。它是**无特色的** —— 每个元素都具有相同的权重，所以眼睛无处可去，结果读起来很称职但容易被遗忘。 这不是一个能力差距。**模型知道什么是好的设计。** 问题在于“使其看起来更高级”不是任何东西可以执行的指令 —— 模型已经相信它已经产生了这样的效果。 > ###形容词在与语言模型的接触中存活不了。 > **所以 Vishwakarma 不使用形容词。** --- ## ✨ 它做了什么 <table> <tr> <td width="50%" valign="top"> ### 🎯 命名确切的失败 不是“改善层次结构”，而是“标题与上方和下方具有相等空间的内容绑定在一起 - 使用48px在上方，12px在下方。” </td> <td width="50%" valign="top"> ### 🔬 解释机制，而不是规则 每个规则都带有其背后的推理 —— 以便代理可以**正确地覆盖它**，当推理不适用时。 </td> </tr> <tr> <td width="50%" valign="top"> ### 🧮 计算而不是猜测 颜色对比度是算术。感知坡度是算术。Vishwakarma 进行数学运算并返回答案。 </td> <td width="50%" valign="top"> ### ✅ 使设计可检查 **设计合同** 将“这可能更好”转化为一个通过或失败的测试，并附有确切的修复方法。 </td> </tr> </table> --- ## 🚀 快速开始 ### 粘贴网址 - Claude 安装它 最快的路径。在任何 Claude Code 会话中，只需告诉它在哪里查找： ```text 从 https://github.com/yogvidwankhede/vishwakarma 安装技能 ``` Claude 从存储库中的 `.claude/skills/` 获取编译后的目录，并将所有 23 个技能复制到您的项目中。无需命令，无需构建，无需 npm。 ### Claude Code 插件 - 两个命令 存储库还作为 **Claude Code 插件市场** 提供，它为您提供适当的版本管理： ```text /plugin marketplace add yogvidwankhede/vishwakarma /plugin install vishwakarma@vishwakarma ``` 所有 23 个技能都加载并具有渐进式披露 - 描述始终可见，完整指导和引用仅在相关时可见。 ### 其他所有代理 - CLI CLI 将技能原生安装到 **13 种代理格式**。这些软件包尚不在 npm 上（它在 [路线图](ROADMAP.md) 上），因此请从检查点运行： ```bash git clone https://github.com/yogvidwankhede/vishwakarma.git cd vishwakarma pnpm install && pnpm build ``` 然后，从您自己的项目目录中： ```bash # 检测您的代理，安装一组启动技能，并生成设计令牌 node /path/to/vishwakarma/packages/cli/dist/index.js init # 浏览提供的一切 node /path/to/vishwakarma/packages/cli/dist/index.js list # 将特定技能安装到特定代理中 node /path/to/vishwakarma/packages/cli/dist/index.js add design-judgment motion-design --target claude-code cursor # 注册 MCP 服务器 - 实时工具，零静态上下文成本 node /path/to/vishwakarma/packages/cli/dist/index.js add --target mcp ``` > **提示：** 在检出中，`pnpm vk <command>` 是同一 CLI 的简写。一旦软件包发布，每个命令都变为 `npx vishwakarma <command>`。 `init` **读取您的仓库** 以确定您使用哪些代理和框架 - 因此第一次交互是**确认**，而不是问卷。 每个编写命令都有一个 `--dry-run`，而写入您自己编写的文件（例如 `AGENTS.md`）的内容则位于一个分隔部分 - 因此重新同步**永远不会**破坏您自己的指令。 --- ## 🧠 魔法：从简介到已验证的界面 当一个安装了 Vishwakarma 的代理被要求“**构建一个定价页面**”时，它现在会： ``` 1. 🎲 选择设计方向 - 确定性，以便它不会崩溃为默认值 2. 📊 排名内容 - 在样式化任何内容之前 3. 📐 构建布局 - 使用真实内容，长度现实 4. 🎨 解析每个值 - 到设计令牌，而不是神奇数字 5. ♿ 可访问性合成 - 原生元素优先，所有状态均设计 6. 🎬 编排动作 - 仅在有意义的地方，减少动作感知 7. 🧪 应激测试 - 长字符串，空列表，每个视口，键盘 8. 🔍 自我批评 - 七次协议，并修复发现的问题 9. 📝 报告 - 它假设的内容，需要人类处理的内容 ``` 并且可以**验证自己的工作** 而不是依赖其眼睛： ``` check_contrast(foreground: "#8a8a8a", background: "#ffffff") → wcagRatio: 3.45 · passesAA: false suggestedForeground: "#777777" "相同的色调和色度，亮度调整到最近的值以通过 — 所以它仍然读取为相同的颜色。" ``` > **修复** 比判决更重要。仅被告知“**失败**”的代理将猜测一个替换方案 - 通常会猜错。 --- ## 📚 技能目录 **23 个技能**，带有 **406 条规则**（每条规则都说明了其机制），**143 个自我检查** 和 **42 个深度引用** 仅在需要时加载。 | | | | |---|---|---| | 🎯 **设计判断** | 🏗️ **UI 生成工作流** | 🔍 **设计审查** | | ✍️ **印刷系统** | 🎨 **颜色系统** | 🧱 **布局和组成** | | 🌗 **表面和深度** | 📱 **响应式架构** | 👆 **交互设计** | | 🔄 **界面状态** | ♿ **可访问组件** | 💬 **界面复制** | | 🗺️ **信息架构** | 🎬 **动作设计** | 📜 **滚动体验** | | ✨ **微交互** | 🧩 **组件架构** | 🎟️ **设计令牌** | | 🌓 **主题系统** | ⚡ **渲染性能** | 🔎 **SEO 和元数据** | | 🎮 **多人游戏发布** | 🧊 **3D 游戏资产** | | ```bash vishwakarma show motion-design # 以完整的方式阅读任何技能 ``` --- ## 📦 软件包 **18 个软件包**，全部构建，全部类型检查，全部测试。一个干净的五层堆栈： ### 🧱 基础 - *纯计算，零依赖* | 软件包 | 它做什么 | |---|---| | [`@vishwakarma/core`](packages/core) | 感知颜色（OKLCh），缩放，动作语法，设计合同，变异引擎 | | [`@vishwakarma/tokens`](packages/tokens) | 三层令牌系统 → CSS，Tailwind v4，TypeScript，JSON，Markdown 从一个源 | ### 🎨 实现 - *工作代码，已经体现了指导* | 软件包 | 它做什么 | |---|---| | [`@vishwakarma/primitives`](packages/primitives) | 无头，ARIA 模式可访问 - 对话框，选项卡，菜单，披露 - 具有完整键盘合同 | | [`@vishwakarma/ui`](packages/ui) | 20 个样式化的 React 19 组件在一个键入的变体系统上 | | [`@vishwakarma/layout`](packages/layout) | 固有布局基元 - 堆栈，网格，Bento，覆盖，完整出血等 | | [`@vishwakarma/motion`](packages/motion) | 具有内置减少运动的动作基元，并且揭示 *不能隐藏你的内容* | | [`@vishwakarma/scroll`](packages/scroll) | 滚动驱动的动画优先，观察者其次，从不测量滚动处理程序 | | [`@vishwakarma/three`](packages/three) | React Three Fiber 助手，在加载单个字节的 WebGL 之前探测设备能力 | | [`@vishwakarma/theme`](packages/theme) | 闪存免费的主题切换，三状态首选项，密度和强制颜色模式 | | [`@vishwakarma/tailwind`](packages/tailwind) | Tailwind v4 预设，自定义实用程序，变体和覆盖警告 | ### 🛡️ 强制执行 - *证明指导被遵循* | 软件包 | 它做什么 | |---|---| | [`@vishwakarma/audit`](packages/audit) | 从源代码中提取实际测量值，并与合同进行检查 | | [`@vishwakarma/lint`](packages/lint) | 设计规则的 lint 规则，这些规则 *真正* 是机械的 | | [`@vishwakarma/testing`](packages/testing) | 匹配者的失败消息会告诉你确切的修复方法 | ### 🚚 分发 - *将智能放入任何代理* | 软件包 | 它做什么 | |---|---| | [`@vishwakarma/skills`](packages/skills) | 技能格式，验证器和 23 个技能目录 | | [`@vishwakarma/adapters`](packages/adapters) | 将一个技能编译为 **13 种代理格式**，带有安装锁定文件 | | [`@vishwakarma/mcp`](packages/mcp) | MCP 服务器 - 14 个工具，2 个提示，2 个资源 | | [`@vishwakarma/registry`](packages/registry) | 复制组件分发，具有依赖项解析 | | [`@vishwakarma/cli`](packages/cli) | 安装程序，分析器和审计员的前端 | --- ## 🆕 九个你不会在其他地方找到的想法 <details open> <summary><b>1. 设计合同</b> - 设计作为一种类型系统</summary> <br>将设计系统表达为 **机器可检查的约束** 而不是没人会读的文档。它说的是输出的语法是什么 - 就像类型系统说什么一样，而不是你的函数计算什么。它把设计审查从意见变成测试。 </details> <details open> <summary><b>2. 动作语法</b> - 从意义中导出的时间</summary> <br>封闭的动作词汇 - `enter`，`exit`，`transform`，`respond`，`attract`，`occupy`，`affirm`，`reject` - 从中导出 **持续时间和缓动**。你不是选择持续时间；你选择这是何种事件。 *"此出口使用进入的缓动"* 成为一个事实主张。 </details> <details> <summary><b>3. 编译一次，随处运行的技能</b></summary> <br>技能格式是 **最受约束的代理** 的刻意 **超集**，因此每个适配器的任务是减法，而不是发明。一个真实的源 → 13 个原生输出 → 零漂移。 </details> <details> <summary><b>4. 带有证据的规则</b></summary> <br>每个规则都说明其机制、来源和置信度 - 以便代理可以 **推理** 规则而不是盲目服从，并且在机制不适用时正确覆盖它。 </details> <details> <summary><b>5. 声明的上下文预算</b></summary> <br>技能声明其令牌成本，CLI **告诉你每个请求花费了多少**。一个工具包悄悄地烧掉了请求窗口的五分之一，向代理解释动画，而编写数据库迁移的代理使其 **更糟糕**。 </details> <details> <summary><b>6. 非破坏性安装</b></summary> <br>您手写的指令位于一个有限部分。重新同步仅重写 **我们的** 区域。卸载后删除它，并留下其他内容 - 删除文件仅当不再剩余任何内容时。 </details> <details> <summary><b>7. 确定性变化</b> - 消除相同的问题 🎲</summary> <br>要求一个着陆页，模型每次都会返回其 **模态答案** - 而这种相同的行为正是生成的作品看起来像生成的确切原因。告诉它“富有创意”失败（一个形容词）；提高温度会将相同的问题替换为不一致性。所以选择 **移出采样器到输入**：一个预先审查的选项集，通过哈希简报选择。每个结果都是有道理的，相同的简报始终以相同的方式解决（可复制，可审查），不同的简报会有所不同。 **720 种组合，5 轴。</details> <details> <summary><b>8. 安装锁文件知道你编辑了什么</b></summary> <br>它将四种情况分为一类：*不变*、*更新*、*漂移*（您编辑了它）和*冲突*（两者都移动）。只有后两者会中断 - 因为一个工具询问每个文件都会训练人们点击“是”而不阅读。 </details> <details> <summary><b>9. 项目配置文件</b></summary> <br>`vishwakarma profile` 记录您已经定义的令牌，您已经拥有的组件以及您的暗主题如何作用于它 - 然后编写一个代理在编写一行代码之前读取 *它*。确定且安全提交，以便团队成员的代理从与您相同的理解开始。</details> --- ## 🔌 与您的代理一起工作 <div align="center"> | 代理 | 它安装在哪里 | |---|---| | **Claude Code** | `.claude/skills/` | | **Cursor** | `.cursor/rules/` | | **Windsurf** | `.windsurf/rules/` | | **Cline / Roo / Continue** | `.clinerules/` · `.roo/rules/` · `.continue/rules/` | | **Codex / Gemini / Copilot** | `AGENTS.md` · `GEMINI.md` · `.github/copilot-instructions.md` | | **Zed / Aider** | `.rules` · `CONVENTIONS.md` | | **任何MCP ` | **Any MCP client** | `.mcp.json` — *nothing loads until the agent asks* | </div> ```bash pnpm vk targets # from the checkout — see every supported agent and where it lands ``` --- ## 🛠️ 直接使用软件包 技能 **教授**；软件包 **实现**。两者皆可使用。 ```tsx import { Reveal, RevealStyles } from '@vishwakarma/motion' import { Stack, Container, Bento } from '@vishwakarma/layout' import { Button, Card, EmptyState } from '@vishwakarma/ui' export function Features({ items }) { return ( <Container> <Stack gap="loose"> {items.map((item) => ( <Reveal key={item.id} from="below" distance="short"> <Card>{item.title}</Card> </Reveal> ))} </Stack> </Container> ) } ``` > `RevealStyles` 发出一个微小的阻塞脚本来 **启用** 揭示。如果没有它，什么都不会损坏 - 元素只是像未动画一样出现。那是正确的失败模式，这就是为什么机制以这种方式工作。 --- ## 🧪 在 CI 中强制执行 `@vishwakarma/audit` 检查源代码是否符合设计合同，并原生支持 GitHub 的注释格式： ```js // scripts/design-audit.mjs import { auditProject, formatReport } from '@vishwakarma/audit' import { DEFAULT_CONTRACT } from '@vishwakarma/core' const report = await auditProject(['src/**/*.{tsx,jsx,css}'], DEFAULT_CONTRACT) console.log(formatReport(report, { format: 'github' })) if (report.summary.errors > > ```yaml - run: node scripts/design-audit.mjs ``` 检查结果会作为 **行内注释** 显示在拉取请求上。错误会导致构建失败；警告不会。 *(并且它对不解析的计算类名持诚实态度，报告会说明这一点。)* --- ## 📖 文档 | | | |---|---| | 🚀 [开始使用](docs/getting-started.md) | 安装，连接令牌，日常命令 | | 🏛️ [架构](docs/architecture.md) | 它如何组合在一起，为什么 | | 🔌 [代理集成](docs/agents.md) | 每个代理的文件位置和权衡 | | ✍️ [编写技能](docs/authoring-skills.md) | 编写您自己的 | | 🗺️ [路线图](ROADMAP.md) | 计划中的内容 - 和不计划的内容 | | ⚖️ [原创政策](ORIGINALITY.md) | 我们如何保持“原创作品”的承诺 | | 🤝 [贡献](CONTRIBUTING.md) | 欢迎讨论 | | | | --- ## ⚖️ 许可证，所有权和原创作品 Vishwakarma 在 **Apache License 2.0** 下是 **开源的** - 使用它，建立在它之上，商业化它。所有要求是您保留版权和许可证通知，并记录您所做的任何更改。Apache-2.0 还为你提供了明确的专利许可，而纯 MIT 不提供。 这里的每一行代码，每个技能，每个令牌都是 **从头开始编写** 的，用于这个项目 - 通过研究现有成果，然后设计我们自己的解决方案。一个原则不是受版权保护的；它的表达方式是。 我们拿到了前者并自己编写了后者。每个源文件都带有版权 + `SPDX` 头，因此即使在上下文中被提取，每个文件仍然可以识别。 > **“Vishwakarma” 是项目所有者的商标。** 代码是您的，但 **名称** 不是。这是标准的分割 - Apache 保护代码，商标保护身份。参见 [ORIGINALITY.md](ORIGINALITY.md) 以获取完整政策。 CI 强制执行原创性：非许可许可证的依赖项会构建失败，带有外来版权标头的源文件会构建失败。 **零遥测。零网络调用在运行时。没有付费层级的已发布功能。** --- ## 🙏 名字 **Vishwakarma** 是印度传统中的神圣建筑师和工匠 - 形态的创造者，建筑师的守护神。名字被选中是因为它的含义：**设计，制造，工艺**。该项目是世俗的，不做任何宗教声明。 --- <div align="center"> ### 构建一个想法，让一个想法成真： **好的设计是一套决策 - 决策可以被检查。** ⭐ 如果您相信生成的 UI 可以比普通的更好，请 **给这个仓库点赞**。 [开始使用](docs/getting-started.md) · [浏览技能](#-the-skill-catalog) · [阅读架构](docs/architecture.md) · [贡献](CONTRIBUTING.md) **Apache-2.0 许可** · 由关心事物外观和功能的人精心制作。 </div>