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 為準,並在同一版本修正文件。
