Guia de Design Qokit
Contrato de design público voltado para integração de plataforma, desenvolvimento de extensões e uso de componentes.
Guia de Design do Qokit
O Guia de Design do Qokit destina-se a futuros integradores da plataforma, desenvolvedores de extensões e equipes front-end, explicando publicamente o que pode ser confiável a longo prazo: fundamentos da marca, interfaces de componentes, hierarquia visual, requisitos de responsividade e estratégias de compatibilidade.
Aqui descrevemos "no que os desenvolvedores podem confiar", sem incluir rotas internas de produto, prompts de IA, processos de decisão do repositório ou soluções de implementação não públicas.
Integração Rápida
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>
);
}Ao integrar, selecione as capacidades na seguinte ordem:
- Selecione componentes básicos como Button, Card e Dialog em
@qokit/components/ui; - Selecione combinações de produtos estáveis em
@qokit/components/patterns; - Utilize
@qokit/components/skins/platform,siteouadminpara adaptar à interface alvo; - Use Tokens CSS compartilhados, não copie estilos base dos componentes;
- Valide nos estados desktop, mobile, teclado e textos longos.
Mapa do Guia
| O que precisa saber | Documento |
|---|---|
| Cores da marca, fontes, espaçamentos e Tokens | foundations.md |
| Responsividade, teclado e acessibilidade | accessibility.md |
| Importação de componentes, contrato público Skeleton/Skin e métodos de atualização | component-integration.md |
| Button e IconButton | button-component-rules.md |
| Card, Shell, sobreposições e materiais | card-surface-materials.md |
| Padrões de qualidade públicos para sites gerados | generated-site-quality.md |
| Mudanças no contrato e registro de atualizações | changelog.md |
Contrato Público
- A estrutura do componente, atributos e comportamento de acessibilidade são mantidos pelo componente compartilhado;
- Skin altera apenas slots de class e variáveis CSS, não altera o comportamento de negócios;
- Tokens semânticos mantêm a mesma responsabilidade em temas claros, escuros e de sites gerados;
- Alterações breaking devem ser registradas no Changelog, com instruções de migração fornecidas;
- Quando houver divergência entre documentação e código, prevalece a API do componente publicado, e a documentação deve ser corrigida na mesma versão.
