Guias de Design do Qokit
Contrato de design público 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 equipas front-end, explicando publicamente o que pode ser considerado uma base de marca, interfaces de componentes, hierarquia visual, requisitos responsivos e estratégias de compatibilidade de longo prazo.
Aqui descreve-se "no que os desenvolvedores podem confiar", não incluindo 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 pela 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; - Utilize Tokens CSS partilhados, sem copiar estilos base dos componentes;
- Valide nos estados de desktop, mobile, teclado e texto longo.
Mapa do Guia
| O que precisa de saber | Documento |
|---|---|
| Cores da marca, tipografia, espaçamentos e Tokens | foundations.md |
| Responsividade, teclado e acessibilidade | accessibility.md |
| Importação de componentes, contrato público Skeleton/Skin e formas 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 |
| Alterações no contrato e registo de atualizações | changelog.md |
Contrato Público
- A estrutura dos componentes, atributos e comportamento de acessibilidade são mantidos por componentes partilhados;
- A Skin altera apenas os slots de class e variáveis CSS, sem alterar o comportamento do negócio;
- Os Tokens semânticos mantêm a mesma responsabilidade nos temas claro, escuro e de sites gerados;
- Alterações disruptivas devem ser registadas no Changelog, com instruções de migração fornecidas;
- Em caso de divergência entre documentação e código, prevalece a API do componente publicada, corrigindo a documentação na mesma versão.
