magicpath

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MagicPath

A platform for building, sharing, and installing UI components via AI. Components are added as source code to the user's project via the

magicpath-ai

CLI.

Terminology: Users often refer to MagicPath components as "designs" — the two terms are interchangeable. When a user says "design," "my designs," or "that design," treat it as meaning a MagicPath component. Search, inspect, and install accordingly.
Users also refer to MagicPath design systems as "themes." When a user says "theme," "my themes," or "use the X theme," they mean a MagicPath design system — a set of CSS variables, fonts, and styling instructions. Use
list-themes
and
get-theme
to work with them.

一个通过AI构建、共享和安装UI组件的平台。组件通过

magicpath-ai

CLI以源代码形式添加到用户项目中。

术语说明： 用户常将MagicPath组件称为“设计”——这两个术语可以互换。当用户提到“设计”、“我的设计”或“那个设计”时，均指MagicPath组件。请相应地进行搜索、检查和安装操作。
用户也将MagicPath设计系统称为“主题”。当用户提到“主题”、“我的主题”或“使用X主题”时，指的是MagicPath设计系统——一套包含CSS变量、字体和样式说明的集合。使用
list-themes
和
get-theme
命令来操作主题。

First Step

第一步

Run

magicpath-ai info -o json

to check auth status, project context, and CLI availability.

If the CLI is missing, invoke it with
```
npx magicpath-ai
```
.
If
```
auth.authenticated
```
is false, run
```
magicpath-ai login
```
, wait for browser auth to finish, then verify with
```
magicpath-ai whoami -o json
```
.

运行

magicpath-ai info -o json

检查认证状态、项目上下文和CLI可用性。

如果缺少CLI，使用
```
npx magicpath-ai
```
调用它。
如果
```
auth.authenticated
```
为false，运行
```
magicpath-ai login
```
，等待浏览器认证完成，然后使用
```
magicpath-ai whoami -o json
```
验证。

Workflow

工作流程

Always use
-o json
for all data-returning commands (
search
,
list-projects
,
list-components
,
list-themes
,
get-theme
,
info
,
add
,
inspect
). This gives you structured output to work with instead of human-readable tables.

所有返回数据的命令必须使用
-o json
（包括
search
、
list-projects
、
list-components
、
list-themes
、
get-theme
、
info
、
add
、
inspect
）。这样可以获得结构化输出，而非人类可读的表格。

Phase 1: Discover

阶段1：发现

Check auth — run
```
magicpath-ai whoami -o json
```
to verify authentication.

Find components — use

magicpath-ai search <query> -o json

to search across all projects, or

list-projects -o json

then

list-components <projectId> -o json

to browse.

Understand components visually —
```
search
```
and
```
list-components
```
results include a
```
previewImageUrl
```
field. Download and analyze these images to understand what each component looks like before recommending it. Preview images are for your own understanding — use the
```
view
```
command when the user needs to see a component.
Confirm with the user (STOP and wait) — unless the user specified an exact generatedName, tell the user what you found (name, generatedName, project), open a browser preview with
```
magicpath-ai view <generatedName>
```
, and ask if it's the right component. If multiple matches, list them all and ask which one. This is a STOP point — end your response here and wait for the user to reply. Do NOT proceed until the user explicitly confirms. Do not run
```
add
```
or
```
inspect
```
yet.

检查认证——运行
```
magicpath-ai whoami -o json
```
验证认证状态。

查找组件——使用

magicpath-ai search <query> -o json

跨所有项目搜索，或者先运行

list-projects -o json

再运行

list-components <projectId> -o json

进行浏览。

可视化理解组件——
```
search
```
和
```
list-components
```
的结果包含
```
previewImageUrl
```
字段。下载并分析这些图片，在推荐组件前了解每个组件的外观。预览图片仅供你自己参考——当用户需要查看组件时，使用
```
view
```
命令。
与用户确认（停止并等待）——除非用户指定了确切的generatedName，否则告知用户你找到的内容（名称、generatedName、项目），使用
```
magicpath-ai view <generatedName>
```
打开浏览器预览，并询问是否是所需组件。如果有多个匹配项，列出所有选项并询问用户选择哪一个。**这是一个停止点——在此结束回复并等待用户回复。在用户明确确认前，请勿继续操作。**暂时不要运行
```
add
```
或
```
inspect
```
命令。

Phase 2: Understand the Target Context

阶段2：理解目标上下文

This phase is critical. Before installing anything, you MUST understand where the component is going and what it needs to do there. Skipping this leads to components that look right but behave wrong.

Inspect the MagicPath component source — use
```
magicpath-ai inspect <generatedName> -o json
```
to read the source code. Identify what it renders, what props it expects, and what assumptions it makes about layout (fixed widths, absolute positioning, etc.).
Read the target codebase context — before installing, read the file(s) where the component will live. Understand:
- Existing functionality: If replacing a component, what does the current one do? What callbacks, state, API calls, navigation, validation, or side effects does it handle? Every piece of existing behavior must be preserved or consciously addressed.
- Layout context: What is the parent layout? Is it a flex/grid container? What are the responsive breakpoints? How does spacing work? A component that looks perfect in isolation can break a layout if its sizing assumptions don't match.
- Data flow: What props, context, or state does the surrounding code provide? What does it expect back (callbacks, form data, events)?
- Design system: What styling patterns does the project use (Tailwind, CSS modules, theme tokens)? The MagicPath component's styles need to harmonize, not clash.

此阶段至关重要。 在安装任何组件之前，你必须了解组件将部署到何处以及需要实现什么功能。跳过此步骤会导致组件外观正确但行为异常。

检查MagicPath组件源代码——使用
```
magicpath-ai inspect <generatedName> -o json
```
读取源代码。确定组件渲染内容、所需props以及对布局的假设（固定宽度、绝对定位等）。
读取目标代码库上下文——安装前，读取组件将存放的文件。了解：
- 现有功能：如果替换组件，当前组件的功能是什么？它处理哪些回调、状态、API调用、导航、验证或副作用？所有现有行为必须得到保留或有意识地处理。
- 布局上下文：父级布局是什么？是flex/grid容器吗？响应式断点是什么？间距如何工作？一个在孤立环境中看起来完美的组件，如果其尺寸假设与布局不匹配，可能会破坏布局。
- 数据流：周围代码提供哪些props、上下文或状态？它期望返回什么（回调、表单数据、事件）？
- 设计系统：项目使用什么样式模式（Tailwind、CSS模块、主题令牌）？MagicPath组件的样式需要与之协调，而非冲突。

Applying a Theme (if applicable)

应用主题（如适用）

If the user has a theme they want applied, or references a brand/design system by name:

List available themes — run
```
magicpath-ai list-themes -o json
```
to see all themes.
Get the theme definition — run
```
magicpath-ai get-theme <id-or-name> -o json
```
to fetch the full definition.
Read the
prompt
field — if present, this contains natural-language styling instructions from the designer (e.g., "use rounded corners, prefer shadows over borders, use the brand blue for CTAs"). Follow these instructions when adapting components.
Apply CSS variables — the theme's
```
light
```
and
```
dark
```
objects map CSS variable names to values (e.g.,
```
--background: #ffffff
```
,
```
--primary: #3b82f6
```
). When adapting MagicPath components, use these CSS variables instead of hardcoded colors:
```
bg-[var(--background)]
```
,
```
text-[var(--primary)]
```
, etc. Ensure the component respects
```
defaultTheme
```
(light or dark).
Handle fonts — if the theme includes
```
fonts
```
, ensure the project loads these fonts (Google Fonts link or
```
@font-face
```
declarations for custom fonts) and that components reference them via the theme's font CSS variables (e.g.,
```
font-family: var(--font-body)
```
).
Non-React/JS projects — theme data is a reference, not a stylesheet. Translate CSS variables into the target platform's equivalent: SwiftUI
```
Color
```
assets, Android theme XML, Python template context, etc. The
```
prompt
```
field and color/font values express platform-agnostic design intent — map them to native patterns rather than using CSS directly.

如果用户想要应用某个主题，或提及品牌/设计系统名称：

列出可用主题——运行
```
magicpath-ai list-themes -o json
```
查看所有主题。
获取主题定义——运行
```
magicpath-ai get-theme <id-or-name> -o json
```
获取完整定义。
读取
prompt
字段——如果存在，此字段包含设计师的自然语言样式说明（例如：“使用圆角，优先使用阴影而非边框，品牌蓝色用于CTA按钮”）。适配组件时请遵循这些说明。
应用CSS变量——主题的
```
light
```
和
```
dark
```
对象将CSS变量名称映射到值（例如：
```
--background: #ffffff
```
，
```
--primary: #3b82f6
```
）。适配MagicPath组件时，使用这些CSS变量而非硬编码颜色：
```
bg-[var(--background)]
```
、
```
text-[var(--primary)]
```
等。确保组件遵循
```
defaultTheme
```
（浅色或深色）。
处理字体——如果主题包含
```
fonts
```
，确保项目加载这些字体（Google Fonts链接或自定义字体的
```
@font-face
```
声明），并且组件通过主题的字体CSS变量引用它们（例如：
```
font-family: var(--font-body)
```
）。
非React/JS项目——主题数据是参考，而非样式表。将CSS变量转换为目标平台的等效形式：SwiftUI的
```
Color
```
资源、Android主题XML、Python模板上下文等。
```
prompt
```
字段和颜色/字体值表达了与平台无关的设计意图——将它们映射到原生模式，而非直接使用CSS。

Phase 3: Install and Adapt

阶段3：安装与适配

Add to project — use
```
magicpath-ai add <generatedName> -y
```
to install component files. Always pass
```
-y
```
in non-interactive contexts. If this is a non-React project (Swift, Python, etc.), do not run
add
— use
```
magicpath-ai inspect <generatedName> -o json
```
to read the source as a reference, then recreate the component in the target language and framework.
Adapt the component for production use — MagicPath components are design artifacts: they capture visual intent and structure, but they are often not production-ready out of the box. After adding, you MUST edit the component files to:
- Make it responsive: Replace any hardcoded widths/heights (e.g.,
```
w-[300px]
```
  ) with responsive utilities (
```
w-full max-w-sm
```
  , responsive breakpoints like
```
md:w-64 lg:w-80
```
  ). A design may show a single viewport — your job is to make it work across all viewports.
- Add real interactivity: Replace static/placeholder content with actual props, state, and event handlers. A MagicPath button that says "Submit" needs an
```
onClick
```
  prop and loading state. A form needs validation and
```
onSubmit
```
  .
- Wire up data flow: Connect the component to the app's actual data — props from parents, context providers, API calls, router state. Don't leave mock data in place.
- Preserve existing functionality: When replacing an existing component, audit every feature the old one provided (form submission, error handling, loading states, accessibility, keyboard navigation, analytics events) and ensure the new component handles all of them.
- Match the project's patterns: Use the same state management, error handling, and styling approaches as the rest of the codebase.

添加到项目——使用
```
magicpath-ai add <generatedName> -y
```
安装组件文件。在非交互式环境中始终传递
```
-y
```
参数。如果是非React项目（Swift、Python等），请勿运行
add
——使用
```
magicpath-ai inspect <generatedName> -o json
```
读取源代码作为参考，然后在目标语言和框架中重新创建组件。
适配组件以用于生产环境——MagicPath组件是设计工件：它们捕获视觉意图和结构，但通常无法直接用于生产环境。添加后，你必须编辑组件文件以：
- 实现响应式：替换任何硬编码的宽度/高度（例如：
```
w-[300px]
```
  ）为响应式工具类（
```
w-full max-w-sm
```
  ，响应式断点如
```
md:w-64 lg:w-80
```
  ）。设计可能只展示单一视口——你的任务是使其在所有视口中正常工作。
- 添加真实交互性：将静态/占位符内容替换为实际的props、状态和事件处理程序。一个显示“Submit”的MagicPath按钮需要
```
onClick
```
  prop和加载状态。表单需要验证和
```
onSubmit
```
  。
- 连接数据流：将组件连接到应用的实际数据——父组件的props、上下文提供者、API调用、路由状态。不要保留模拟数据。
- 保留现有功能：替换现有组件时，审核旧组件提供的每一项功能（表单提交、错误处理、加载状态、可访问性、键盘导航、分析事件），确保新组件能处理所有这些功能。
- 匹配项目模式：使用与代码库其余部分相同的状态管理、错误处理和样式方法。

Phase 4: Integrate into the Page

阶段4：集成到页面

Import and render — import the component using the
```
importStatement
```
from the add output. Pass the props you've defined.
Verify layout fit — after placing the component, review the parent layout to ensure it integrates cleanly. Check that the component doesn't overflow, create unexpected gaps, or break the responsive flow of the page.

导入并渲染——使用
```
add
```
输出中的
```
importStatement
```
导入组件。传递你定义的props。
验证布局适配——放置组件后，检查父级布局以确保其完美集成。确认组件不会溢出、产生意外间隙或破坏页面的响应式流程。

Design-to-Production Mindset

设计到生产的思维

MagicPath is a design tool. Components from MagicPath represent what something should look like and how it should be structured — they are the design spec expressed as code. But a design comp and a production component are different things:

Design artifact	Your job as the agent
Fixed width `w-[400px]`	Make it responsive: `w-full max-w-md` or breakpoint-based
Static text "John Doe"	Replace with dynamic prop: `{user.name}`
Placeholder `onClick={() => {}}`	Wire to real handler: `onClick={handleSubmit}`
Hardcoded list of 3 items	Map over real data: `{items.map(…)}`
No error/loading states	Add loading spinners, error boundaries, empty states
No accessibility attributes	Add `aria-label` , `role` , keyboard handlers, focus management
Desktop-only layout	Add responsive breakpoints, mobile navigation patterns
Decorative images with `src="/photo.jpg"`	Use real assets or proper placeholders from the project

The golden rule: a MagicPath component tells you WHAT to build. Your job is to make it WORK — responsively, accessibly, and fully wired into the application.

MagicPath是一个设计工具。 来自MagicPath的组件代表了事物的外观和结构——它们是用代码表达的设计规范。但设计稿和生产组件是不同的：

设计工件	你的任务
固定宽度 `w-[400px]`	实现响应式： `w-full max-w-md` 或基于断点的设置
静态文本“John Doe”	替换为动态prop： `{user.name}`
占位符 `onClick={() => {}}`	连接到真实处理程序： `onClick={handleSubmit}`
硬编码的3项列表	映射真实数据： `{items.map(…)}`
无错误/加载状态	添加加载 spinner、错误边界、空状态
无可访问性属性	添加 `aria-label` 、 `role` 、键盘处理程序、焦点管理
仅桌面端布局	添加响应式断点、移动端导航模式
装饰图片 `src="/photo.jpg"`	使用项目中的真实资源或合适的占位符

黄金法则：MagicPath组件告诉你要构建什么。你的工作是让它正常工作——响应式、可访问，并完全集成到应用中。

Common Scenarios

常见场景

Replacing an existing component (e.g., swapping an old login form for a MagicPath design):

Read the old component thoroughly — list every prop, callback, validation rule, and side effect

Inspect the MagicPath component source with

magicpath-ai inspect <generatedName> -o json

Install the MagicPath component with
```
magicpath-ai add <generatedName> -y
```
Edit the MagicPath component to accept all the same props/callbacks
Ensure every feature from the old component exists in the new one
Swap the import in the parent — the parent code should barely change

Building a new page from a MagicPath design library:

Browse the project's components with
```
list-components
```
Plan the page layout first — identify which MagicPath components map to which sections
Install needed components one at a time with
```
magicpath-ai add <generatedName> -y
```
Build the page layout, importing each component
Adapt each component: responsive sizing, real data, proper routing, state management
Ensure consistent spacing, typography, and color usage across all components

Using a single MagicPath component as inspiration:

Inspect the source with

magicpath-ai inspect <generatedName> -o json

Understand the design intent — colors, spacing, layout structure, typography
Install and adapt it, or use it as a reference to build something custom that follows the same design language

替换现有组件（例如：用MagicPath设计替换旧登录表单）：

彻底阅读旧组件——列出所有props、回调、验证规则和副作用

使用

magicpath-ai inspect <generatedName> -o json

检查MagicPath组件源代码

使用
```
magicpath-ai add <generatedName> -y
```
安装MagicPath组件
编辑MagicPath组件以接受所有相同的props/回调
确保旧组件的所有功能在新组件中都存在
在父组件中替换导入——父组件代码应几乎无需修改

从MagicPath设计库构建新页面：

使用
```
list-components
```
浏览项目组件
先规划页面布局——确定哪些MagicPath组件对应哪些部分
使用
```
magicpath-ai add <generatedName> -y
```
逐个安装所需组件
构建页面布局，导入每个组件
适配每个组件：响应式尺寸、真实数据、正确路由、状态管理
确保所有组件之间的间距、排版和颜色使用一致

将单个MagicPath组件作为灵感来源：

使用

magicpath-ai inspect <generatedName> -o json

检查源代码

理解设计意图——颜色、间距、布局结构、排版
安装并适配它，或以此为参考构建符合相同设计语言的自定义组件

Critical Rules

关键规则

add
means install-to-use. Only run
```
add
```
when you intend to import and render the installed component. If you just want to read the source code, use
```
inspect
```
instead.
After
add
, always import the component. The whole point of
```
add
```
is to get source files you then import. Never add a component and then copy its styles/markup into another file — import and render the component directly.
MagicPath components are source code you own. After
```
add
```
, the component files live in your project at
```
src/components/magicpath/<name>/
```
. You can and should edit them directly to add props, change behavior, adjust styles, or integrate with your app's state.
When a component needs integration: (1)
```
add
```
the component, (2) edit the component file to accept the props you need (e.g.,
```
onSubmit
```
,
```
placeholder
```
,
```
className
```
), (3) import it from the parent and pass those props. Do NOT copy the component's JSX/styles into the parent file.
Never just drop a component in. Always read the surrounding code, understand the layout constraints, and adapt the component to fit. A MagicPath component placed without adaptation is a bug, not a feature.
inspect
is read-only. Shows full source code without writing any files. Use this when deciding whether a component fits your needs before committing to install.
add
is for React/TypeScript projects only. The
```
add
```
command writes
```
.tsx
```
files to
```
src/components/magicpath/
```
and installs npm dependencies. Only use
```
add
```
in JavaScript/TypeScript projects. For non-JS projects (Swift, Python, etc.), use
```
inspect
```
to read the component source, then translate the design and behavior into the project's language and framework.
Never run
view
commands in parallel. The
```
view
```
command opens a browser window for the user. Only open one preview at a time.

add
意味着安装后使用。仅当你打算导入并渲染安装的组件时才运行
```
add
```
。如果只是想读取源代码，使用
```
inspect
```
。
add
后务必导入组件。
```
add
```
的全部意义在于获取可导入的源文件。切勿添加组件后将其样式/标记复制到另一个文件——直接导入并渲染组件。
MagicPath组件是你拥有的源代码。
```
add
```
后，组件文件存放在项目的
```
src/components/magicpath/<name>/
```
目录下。你可以且应该直接编辑这些文件以添加props、更改行为、调整样式或与应用状态集成。
当组件需要集成时： (1)
```
add
```
组件，(2) 编辑组件文件以接受所需的props（例如：
```
onSubmit
```
、
```
placeholder
```
、
```
className
```
），(3) 从父组件导入并传递这些props。切勿将组件的JSX/样式复制到父文件中。
切勿直接放置组件。 务必阅读周围代码，了解布局约束，并适配组件以使其符合要求。未经适配的MagicPath组件是bug，而非功能。
inspect
是只读的。显示完整源代码但不写入任何文件。在决定是否安装组件前，使用此命令判断组件是否符合需求。
add
仅适用于React/TypeScript项目。
```
add
```
命令将
```
.tsx
```
文件写入
```
src/components/magicpath/
```
并安装npm依赖。仅在JavaScript/TypeScript项目中使用
```
add
```
。对于非JS项目（Swift、Python等），使用
```
inspect
```
读取组件源代码，然后将设计和行为转换为项目的语言和框架。
切勿并行运行
view
命令。
```
view
```
命令会为用户打开浏览器窗口。一次仅打开一个预览窗口。

Quick Reference

快速参考

bash

undefined

bash

undefined

Auth

认证

magicpath-ai login # one-click browser login magicpath-ai whoami -o json # check auth status magicpath-ai info -o json # full project context

magicpath-ai login # 一键浏览器登录 magicpath-ai whoami -o json # 检查认证状态 magicpath-ai info -o json # 完整项目上下文

Find components (always use -o json)

查找组件（始终使用-o json）

magicpath-ai search "input box" -o json # search across all projects magicpath-ai list-projects -o json # list all projects magicpath-ai list-components <id> -o json # list components in a project

magicpath-ai search "input box" -o json # 跨所有项目搜索 magicpath-ai list-projects -o json # 列出所有项目 magicpath-ai list-components <id> -o json # 列出项目中的组件

Inspect components

检查组件

magicpath-ai view <generatedName> # preview in browser magicpath-ai inspect <generatedName> -o json # show source code (no install) magicpath-ai add <generatedName> --dry-run # show what would be installed

magicpath-ai view <generatedName> # 在浏览器中预览 magicpath-ai inspect <generatedName> -o json # 显示源代码（无需安装） magicpath-ai add <generatedName> --dry-run # 显示将安装的内容

Install and use components

安装并使用组件

magicpath-ai add <generatedName> -y # add to project (no prompts)

magicpath-ai add <generatedName> -y # 添加到项目（无提示）

Themes (design systems)

主题（设计系统）

magicpath-ai list-themes -o json # list all themes magicpath-ai get-theme <id-or-name> -o json # get theme CSS vars, fonts, prompt

undefined

magicpath-ai list-themes -o json # 列出所有主题 magicpath-ai get-theme <id-or-name> -o json # 获取主题CSS变量、字体、提示信息

undefined

Key Concepts

核心概念

Each component has a generatedName (e.g.,
```
wispy-river-5234
```
) — this is the identifier for all operations
Components are added as source code to
```
src/components/magicpath/<name>/
```
The
```
add
```
command returns
```
importStatement
```
and
```
usage
```
— use these in code
Use
```
inspect
```
to inspect source code without installing — don't use
```
add
```
just to read code
MagicPath components are React/TypeScript source code — use
```
add
```
in JS/TS projects, use
```
inspect
```
+ translate for other languages
Themes (design systems) contain CSS variables (
```
light
```
/
```
dark
```
maps), optional
```
fonts
```
, and an optional
```
prompt
```
with styling instructions for agents. "Theme" and "design system" are interchangeable. Use
```
list-themes
```
to browse,
```
get-theme
```
to fetch the full definition

每个组件都有一个generatedName（例如：
```
wispy-river-5234
```
）——这是所有操作的标识符
组件以源代码形式添加到
```
src/components/magicpath/<name>/
```
目录
```
add
```
命令返回
```
importStatement
```
和
```
usage
```
——在代码中使用这些内容
使用
```
inspect
```
检查源代码而无需安装——不要仅为了读取代码而使用
```
add
```
MagicPath组件是React/TypeScript源代码——在JS/TS项目中使用
```
add
```
，在其他语言中使用
```
inspect
```
+转换
主题（设计系统）包含CSS变量（
```
light
```
/
```
dark
```
映射）、可选的
```
fonts
```
以及可选的
```
prompt
```
（供AI使用的样式说明）。“主题”和“设计系统”可以互换。使用
```
list-themes
```
浏览，
```
get-theme
```
获取完整定义

Current Project Context

当前项目上下文

json

!`magicpath-ai info --json 2>/dev/null || echo '{"error": "magicpath-ai not found. Install with: npm install -g magicpath-ai"}'`

The JSON above contains auth status, projects, and CLI version. If auth.authenticated is false, the user needs to log in before any other operations.

json

!`magicpath-ai info --json 2>/dev/null || echo '{"error": "magicpath-ai not found. Install with: npm install -g magicpath-ai"}'`

上述JSON包含认证状态、项目和CLI版本。如果auth.authenticated为false，用户需要先登录才能进行其他操作。

References

参考资料

CLI Reference

CLI参考文档