Руководство по дизайну 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>
);
}При подключении выбирайте возможности в следующем порядке:
- Выберите базовые компоненты, такие как Button, Card, Dialog и другие, из
@qokit/components/ui; - Выберите стабильные продуктовые комбинации из
@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 компонента, а документация исправляется в той же версии.
