Front-end Django com templates renderizados no servidor. Use ao criar ou alterar templates .html de um projeto Django, componentizar uma tela, criar include ou partial, montar formulário no template, começar o front de um projeto ou app Django, ou usar Tailwind, HTMX ou Alpine em Django.
El texto de las convenciones está escrito en portugués y se muestra aquí tal como está en el repositorio.
Django templates — front renderizado no servidor
Projeto que já existe? Estas convenções valem para código novo e para remodelação. Em sistema legado, de cliente ou de outra equipe, a arquitetura do projeto manda: antes da primeira mudança, siga
veritas:projeto-existente.Dado pessoal? Código que toca CPF, contato, saúde, dado financeiro ou credencial, e todo log, exportação ou integração, segue também a
veritas:lgpd, em qualquer modo.
A casa ainda não tem um projeto de referência para o front Django. Por isso esta skill não impõe arquitetura: ela lê o que o projeto já decidiu, e pergunta quando nada foi decidido. As regras da seção "Sempre" valem em qualquer caso.
Backend (view, service, model) continua na veritas:django. Onde cada nível
de componente mora está na veritas:atomic-design, arquivo django.md.
1. Leia antes de perguntar
Procure, nesta ordem:
- O
CLAUDE.mddo projeto: uma seção de front decidida vale mais que esta skill. templates/components/e obase.htmloulayouts/: como o projeto já quebra as telas.static/css/: CSS por componente (components/atoms/...) ou utilities direto no HTML.pyproject.tomlepackage.json:tailwindcss,django-widget-tweaks,django-crispy-forms,htmx,alpinejs.
Achou padrão: siga o padrão, e não pergunte o que o código já responde. Divergir do padrão do projeto só com pedido explícito.
2. Pergunte quando nada foi decidido
Em modo conservar (veritas:projeto-existente), estas perguntas não se
fazem: siga a tela mais parecida que já existe, mesmo que o projeto misture
padrões. Elas servem a projeto novo, front novo num projeto da casa, ou
remodelação.
Faça as perguntas quando:
- o projeto, ou a área da tela, ainda não tem front;
- a pessoa pediu para "componentizar" ou "criar do zero";
- o que existe se contradiz (ex.:
components/ev2/com padrões diferentes).
As três de uma vez, numa mensagem só, antes de escrever markup:
- Componentizar?
- Atomic design: pastas
atoms/,molecules/eorganisms/, no template e no CSS. Vejaveritas:atomic-design→django.md. - Pasta única:
templates/components/_nome.html, sem níveis. - Sem componente: tela simples ou descartável, tudo na própria página.
- Atomic design: pastas
- CSS:
- Classes de componente: um arquivo CSS por componente (
.btn,.card), e utilities do Tailwind só para posicionamento. - Utilities direto no HTML: sem arquivo por componente.
- Classes de componente: um arquivo CSS por componente (
- Interatividade:
- HTMX: trocar pedaço da tela com resposta do servidor.
- Alpine: estado só no navegador (modal, aba, toggle).
- Os dois.
- Nenhum: página recarrega, formulário com PRG.
Ofereça como padrão atomic design, classes de componente e HTMX com Alpine. É a combinação mais testada na casa (jcmotors), mas a escolha é da pessoa.
Registre a resposta no CLAUDE.md do projeto, numa seção "Front". É o que
faz a próxima tarefa cair no passo 1 e não perguntar de novo.
Escolheu HTMX ou Alpine: leia interatividade.md antes
de escrever o primeiro atributo hx- ou x-.
3. Sempre
Valem com qualquer resposta às perguntas.
Componente tem contrato.
- Todo
{% include %}de componente usawith ... only. Sem oonly, o componente passa a depender do contexto da página por acidente. - O topo do arquivo diz, num
{% comment %}, o que ele recebe, quais parâmetros são obrigatórios e um exemplo de uso.
CSRF em componente com formulário. Com only, o csrf_token não vai
junto: passe csrf_token=csrf_token explicitamente. Sem isso, o
{% csrf_token %} sai vazio e todo envio volta 403. O Django só avisa no
console, e o test client não confere CSRF, então o teste não pega.
Lógica fora do template. No template fica só lógica de exibição: {% if %}
para mostrar ou esconder, {% for %} sobre lista pronta, filtro para
formatar. Calcular, decidir estado, agregar ou filtrar queryset vai para o
model (@property, is_*()), um presenter, o form ou o contexto da view.
Template tag que consulta o banco é query escondida: a view entrega o dado.
Fragmento de um arquivo só usa partial nativo. No Django 6:
{% partialdef nome %} e {% partial nome %}. Ele também serve de resposta
de HTMX: render(request, "app/tela.html#nome", ctx). Vira arquivo próprio em
components/ quando o segundo template precisar dele.
Formulário.
- Rótulo e
help_textficam no model; rótulo específico de uma tela, emMeta.labelsdo form. placeholder,autofocuse classe CSS ficam no template, nunca emattrs=noforms.py. Atributo de comportamento (step,min,inputmode,maxlength) pode ficar no form.{{ form.non_field_errors }}aparece na tela: erro de restrição com mais de um campo não cai em campo nenhum.- Com
django-widget-tweaks: campo a campo, com{% render_field %}ou o componente de campo do projeto, nunca{{ form }}ouas_p. Atributo com:(x-on:change,:class,@click) não passa pelorender_field: sai renderizado errado e sem erro. Ponha o handler num elemento escrito à mão.
Link sem destino renderiza inerte. Item de menu ou botão cuja tela ainda
não existe ganha estado desabilitado visível, nunca href="#".
Acessibilidade. Todo campo tem <label for>. O erro do campo fica em
id="{{ field.auto_id }}_error", que é para onde o aria-describedby do
Django aponta. Ícone sozinho num botão pede aria-label.
Skills de fora
Se estiverem instaladas, carregue sem esperar pedido:
- Página pública (landing, site, portfolio) →
design-taste-frontend - Site existente com cara genérica →
redesign-existing-projects - Revisar UI ou acessibilidade →
web-design-guidelines
Elas decidem visual; as respostas do passo 2 e as regras de "Sempre" são desta skill. Em conflito, esta vence. O que nunca entra sozinho: skills-de-fora.md.
Origem
Banco de skills do Veritas, skill django-templates. Criada
em 2026-09-23. As regras de "Sempre" foram tiradas do CLAUDE.md do jcmotors,
onde cada uma veio de um defeito real (o CSRF vazio no partial de pagamento, o
atributo x-on: mutilado pelo widget-tweaks). A escolha de arquitetura ficou
como pergunta porque a casa ainda não tem projeto de referência. Partials
nativos conferidos nas notas de versão do Django 6.0.
Correções vão por PR no repositório, não editando a cópia local.