diff --git a/docs/login-widget-guide.md b/docs/login-widget-guide.md
new file mode 100644
index 0000000..a700761
--- /dev/null
+++ b/docs/login-widget-guide.md
@@ -0,0 +1,232 @@
+# 登录 Widget 使用指南
+
+## 概述
+
+登录 Widget 是一个可嵌入到任何网页的登录表单组件。通过一行 `
+```
+
+### 2. 创建容器
+
+在页面中放置一个 DOM 元素作为 Widget 的挂载点:
+
+```html
+
+```
+
+### 3. 初始化 Widget
+
+在脚本加载后调用 `NewApiLoginWidget.init()`:
+
+```html
+
+```
+
+### 完整示例
+
+```html
+
+
+
+
+ 我的网站
+
+
+ 欢迎
+
+
+
+
+
+
+
+
+
+
+
+```
+
+---
+
+## API 参考
+
+### `NewApiLoginWidget.init(options)`
+
+初始化并渲染登录表单。
+
+#### 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `container` | `string` 或 `Element` | 是 | 挂载点,支持 CSS 选择器字符串或 DOM 元素 |
+| `apiUrl` | `string` | 是 | New API 服务地址,如 `https://api.example.com` |
+| `onSuccess` | `function` | 否 | 登录成功回调,参数为用户数据对象 |
+| `onError` | `function` | 否 | 登录失败回调,参数为 `{ message: string }` |
+| `theme` | `string` | 否 | 主题,可选 `'light'`(默认)或 `'dark'` |
+
+#### 返回值
+
+返回一个对象,包含以下方法:
+
+| 方法 | 说明 |
+|------|------|
+| `destroy()` | 卸载 Widget,清除 DOM |
+
+#### onSuccess 回调数据
+
+```json
+{
+ "id": 1,
+ "username": "user",
+ "display_name": "用户",
+ "role": 1,
+ "status": 1,
+ "group": "default"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | number | 用户 ID |
+| `username` | string | 用户名 |
+| `display_name` | string | 显示名称 |
+| `role` | number | 角色(1=普通用户,10+=管理员,100+=超级管理员) |
+| `status` | number | 状态 |
+| `group` | string | 用户组 |
+
+---
+
+## 主题
+
+### Light(默认)
+
+```js
+NewApiLoginWidget.init({
+ container: '#login',
+ apiUrl: 'https://your-domain.com',
+ // theme: 'light' // 默认就是 light,可省略
+});
+```
+
+### Dark
+
+```js
+NewApiLoginWidget.init({
+ container: '#login',
+ apiUrl: 'https://your-domain.com',
+ theme: 'dark'
+});
+```
+
+---
+
+## 销毁 Widget
+
+当不再需要登录表单时(如登录成功后),调用 `destroy()` 移除:
+
+```js
+var widget = NewApiLoginWidget.init({ ... });
+
+// 登录成功后销毁
+widget.destroy();
+```
+
+---
+
+## 同一页面多个实例
+
+支持在同一页面创建多个 Widget 实例(如同时显示 Light 和 Dark 主题):
+
+```html
+
+
+
+
+
+```
+
+---
+
+## 注意事项
+
+1. **跨域支持**:Widget 支持跨域嵌入。你的 New API 服务已配置 CORS,允许任意域名调用登录接口。
+2. **HTTPS**:生产环境建议 New API 服务使用 HTTPS,否则部分浏览器功能可能受限。
+3. **不管理会话**:Widget 只负责登录验证并返回用户数据,不会自动管理嵌入方的登录状态。你需要在 `onSuccess` 回调中自行处理用户会话。
+4. **两步验证(2FA)**:当前版本不支持 2FA。如果用户启用了两步验证,`onError` 会收到提示信息。
+5. **文件大小**:Widget JS 约 146KB(含 React 运行时),gzip 后约 48KB。
+
+---
+
+## 常见问题
+
+### Q: 引入脚本后页面报错 `NewApiLoginWidget is not defined`
+
+确保 `