Qokit 设计指南
面向平台集成、扩展开发与组件使用的公开设计契约。
Qokit 设计指南
Qokit 设计指南面向未来的平台集成方、扩展开发者和前端团队,公开说明可以长期依赖的品牌基础、组件接口、视觉层级、响应式要求与兼容策略。
这里描述的是“开发者可以依赖什么”,不包含内部产品路线、AI 提示、仓库决策过程或未公开实现方案。
快速接入
import { Button, Card } from '@qokit/components/ui';
import { platformButtonSkin, platformCardSkin } from '@qokit/components/skins/platform';
export function IntegrationAction() {
return (
<Card layer="shell" skin={platformCardSkin}>
<Button skin={platformButtonSkin} type="button" variant="primary">
连接 Qokit
</Button>
</Card>
);
}接入时按以下顺序选择能力:
- 从
@qokit/components/ui选择 Button、Card、Dialog 等基础组件; - 从
@qokit/components/patterns选择稳定的产品组合; - 使用
@qokit/components/skins/platform、site或admin适配目标界面; - 使用共享 CSS Token,不复制组件基础样式;
- 验证桌面、移动端、键盘和长文案状态。
指南地图
| 需要了解的内容 | 文档 |
|---|---|
| 品牌颜色、字体、间距和 Token | foundations.md |
| 响应式、键盘与无障碍 | accessibility.md |
| 组件导入、Skeleton/Skin 公共契约与升级方式 | component-integration.md |
| Button 与 IconButton | button-component-rules.md |
| Card、Shell、浮层与材质 | card-surface-materials.md |
| 生成站点的公开质量标准 | generated-site-quality.md |
| 契约变化与升级记录 | changelog.md |
公开契约
- 组件结构、属性和可访问性行为由共享组件维护;
- Skin 只改变 class 槽和 CSS 变量,不改变业务行为;
- 语义 Token 在浅色、深色和生成站点主题中保持同一职责;
- 破坏性变更必须记录在 Changelog,并提供迁移说明;
- 文档与代码存在差异时,以已发布组件 API 为准,并在同一版本修正文档。
