Habilidades para criar temas e blocos

[manuel (Manuel Kostka)]

Um repositório de habilidades do Claude Code para criar temas e componentes de blocos do Discourse:

GitHub - discourse/discourse-theme-skills: Claude Code skills for Discourse theme development

O que está incluído

Habilidade de Criação de Temas — abrange um escopo completo para construir um tema do Discourse: scaffolding com o CLI discourse_theme, arquitetura SCSS, biblioteca de viewport, internacionalização, configurações, modificadores, transformadores de valor, ícones e variáveis CSS. Arquivos de referência detalhados para ícones, variáveis e transformadores estão incluídos separadamente e podem ser carregados sob demanda. SKILL.md

Habilidade de Criação de Blocos — abrange o lado do tema da API de Blocos: escrever componentes de bloco com o decorador @block, definir esquemas de argumentos, renderizar blocos nas saídas principais disponíveis, condições, blocos de contêiner e agrupamento de layout, e integrar traduções e configurações do tema aos argumentos do bloco. SKILL.md

Tema de Exemplo — um tema funcional com uma página inicial personalizada construída com blocos, demonstrando padrões reais para saídas, condições e composição de layout.

---

Sobre a API de Blocos

A API de Blocos é o novo framework do Discourse para criar componentes de UI modulares e compostáveis em temas e plugins. Os blocos são componentes Glimmer registrados em saídas nomeadas — como homepage-blocks, hero-blocks ou sidebar-discovery — e podem ser exibidos condicionalmente com base na rota, usuário, viewport, configurações do site ou disponibilidade de plugins.

Uma força chave do sistema é que os blocos têm escopo pequeno e focado e padrões consistentes. Isso os torna bem adequados para desenvolvimento assistido por IA: um modelo com a habilidade de bloco pode criar um componente de bloco funcional, registrá-lo em uma saída e configurar as condições em uma única passada.

O tema de exemplo neste repositório demonstra uma página inicial que se adapta com base nos plugins e conteúdos disponíveis. Veja como a página inicial básica se parece, com um bloco de destaque e uma lista de tópicos em destaque:

Quando condições adicionais são atendidas (uma tag em destaque está configurada, o plugin Discourse Events está ativo e o plugin Discourse Leaderboard está disponível), blocos adicionais são renderizados condicionalmente no layout:

Os blocos não se limitam à página inicial. O tema de exemplo também usa a saída sidebar-blocks para adicionar um link Início, a saída sidebar-discovery para adicionar conteúdo específico da categoria na barra lateral e um bloco category-banner no topo das páginas de categoria:

O inspetor de blocos nas Ferramentas de Desenvolvedor mostra os rótulos das saídas e os identificadores dos blocos sobrepostos na página. Isso facilita entender a estrutura do layout e depurar o que está sendo renderizado onde:

---

Usando com um MCP de plataforma de design

As habilidades funcionam bem com MCPs de plataformas de design (como o Penpot ou o Figma MCP). Com um conectado, o Claude pode ler especificações de componentes e tokens de design diretamente dos seus arquivos de design e implementá-los usando as convenções da habilidade. É um ciclo mais fechado entre design e código, especialmente ao trabalhar com um sistema de design estruturado.

---

Faça um fork e ajuste

Algumas convenções nas habilidades são mais preferenciais do que convencionais, como a arquitetura de pastas SCSS. Você pode fazer um fork do repositório e ajustar as habilidades para corresponder ao seu próprio fluxo de trabalho e convenções.

---

Compartilhe o que você constrói

Experimente e nos conte como foi! Adoraríamos saber como você está usando as habilidades, o que construiu com elas e onde elas falham. Comentários, correções e forks são todos bem-vindos.

[NateDhaliwal]

Haverá um tópico dedicado a Blocks ou é este?

Se for o último, talvez alguns trechos de código possam ajudar? Ou o que está no arquivo plugin-api.gjs são as documentações atuais?

Obrigado.

[manuel (Manuel Kostka)]

@NateDhaliwal

Haverá um tópico dedicado ao Blocks ou é este?

Ainda haverá documentação que cobre toda a API do Blocks, incluindo a implementação no núcleo e em plugins. Para temas com Blocks, o SKILL.md já deve abordar todos os aspectos relevantes. É compacto e muito legível.

@NateDhaliwal

Se for o último, talvez alguns trechos de código possam ajudar? Ou o que está no arquivo plugin-api.gjs são as documentações atuais?

O tema de exemplo inclui tanto arquivos de inicializador quanto blocos. Os arquivos de inicializador decloram o layout por BlockOutlet: discourse-theme-skills/javascripts/discourse/api-initializers at main · discourse/discourse-theme-skills · GitHub.

[manuel (Manuel Kostka)]

Estou me divertindo de verdade com isso … Como outras ferramentas de design com IA, é realmente eficiente para prototipar rapidamente ideias que seriam muito caras para esboçar manualmente.

Peça uma página inicial editorial em estilo brutalista, com conteúdo altamente incomum destacado da comunidade. Obtive este layout, que de fato tem algumas ideias bem interessantes para blocos em destaque. O mais engraçado é que ele batizou o tema de Jornal do Inferno

Depois, pedi algo que sempre quis explorar: uma página inicial de portal no estilo japonês, com blocos densos, cores pastéis e muitas animações pequenas… Adorei essa primeira versão:

Na verdade, seria legal ter um screencast, porque todas aquelas pequenas animações tornam tudo muito mais legal:

[Canapin (Coin-coin le Canapin)]

@manuel

E mais divertido quando tudo está se movendo Criador de Temas

[jrgong]

Finalmente!!! Vou tentar o mais breve possível para atualizar meus componentes de tema experimentais

[BrianC (Brian)]

Este é um ótimo trabalho e muito criativo. Se fizermos um fork e desenvolvermos com base neste tema, há alguma consideração sobre o tema pai não permanecer atualizado com o Discourse ao longo do tempo? Estou tentando pensar como isso deve ser abordado.

Obrigado pelos recursos!

[manuel (Manuel Kostka)]

Obrigado, @BrianC!

Sobre a atualização do tema principal: o track de habilidades acompanha as APIs de tema e Blocos do Discourse, então, desde que as usemos ativamente, elas serão mantidas sincronizadas conforme as APIs evoluem. O tema de exemplo é mais um instantâneo para demonstrar padrões. Se você fizer um fork dele, será o dono do seu fork. Mas você pode consultar o track de habilidades ou novos exemplos ao atualizar seu tema.

Um objetivo central da própria API de Blocos é ter uma área de superfície pequena e estável, que ajude a manter as personalizações resilientes nas atualizações do Discourse. Então, se você principalmente adiciona blocos personalizados (como o tema de exemplo faz), já deve operar em um ambiente estável. A principal coisa a observar seriam mudanças nos nomes das saídas (outlets) ou nas assinaturas da API de blocos. Atualmente, a API ainda é considerada experimental, então pode haver alterações em nomes etc.

Eu resumiria a abordagem recomendada assim: faça um fork do tema livremente e use a documentação do track de habilidades como referência viva de como as coisas devem ser feitas daqui para frente.

[nathank (Nathan Kershaw)]

Estou apenas começando a brincar com isso (sem codificação agêntica).

Tenho a impressão de que não seria preciso muito esforço para converter isso em um Componente de Tema que controle apenas a Página Inicial de um site — por exemplo, um que já utilize o Tema Horizon. Isso seria uma ideia ruim?

Além disso, notei alguns problemas:

O Bloco de Eventos Futuros não ordena os tópicos

Ele simplesmente lista os tópicos de eventos por data de criação; isso é extremamente inútil!!

O ask.discourse.com sugere esse tipo de alteração para corrigir o problema, o que posso confirmar que funciona (perdoem minha falta de pensamento crítico humano):

@bind
async fetchEvents() {
  const count = this.args.count || 5;
  const results = await ajax("discourse-post-event/events");

  if (!results.events?.length) {
    return null;
  }

  const now = new Date();

  // Separa eventos passados e futuros, depois ordena em ordem crescente pela data de início
  const upcoming = results.events
    .filter((e) => new Date(e.starts_at) >= now)
    .sort((a, b) => new Date(a.starts_at) - new Date(b.starts_at));

  return upcoming.slice(0, count);
}

O Bloco de Banners de Categoria não respeita as configurações

Ele é exibido em todas as categorias (não apenas nas especificadas) e parece não atualizar durante a navegação (somente ao recarregar a página).

[manuel (Manuel Kostka)]

Obrigado por testar, @nathank! Ainda é considerado experimental e faremos alterações na API, então não recomendo criar um componente de tema do tipo construtor de páginas principais com base nisso por enquanto.

Os blocos de demonstração são apenas exemplos básicos. Também temos algumas mudanças na API por vir que melhorarão a forma como carregamos dados. Vou aplicar as alterações em todos os blocos do tema de demonstração assim que isso estiver disponível.

O bloco de banners de categorias deve aparecer em todas as categorias. Acho que o seletor de categorias que você mencionou é para o bloco de categorias em destaque na página inicial.

[satonotdead]

Finalmente dei o passo e comecei a brincar um pouco com isso. Muito obrigado por compartilhar.

Estou me perguntando o quão possível seria gerar um bloco personalizado que exiba o avatar e o nome do usuário (o que já consegui fazer), juntamente com a contagem de tópicos e posts, curtidas, pontos de “cheer” e algo semelhante a See TL3 Progress, mas em relação a badges específicas (nível de confiança personalizado construído sobre elas)?

Inspirado em jogos de interpretação de papéis, onde se pode ver em um cartão a EXP do próprio personagem, informações básicas e suas principais habilidades.

[NateDhaliwal]

Se você quiser adicionar um bloco, acho que será necessário enviar um PR para o core.

[nickdb (Nick)]

Venho me informando sobre a API de blocos e o ask.discourse tem sido bastante útil.

Gostaria de tentar imitar (plagiar) o banner da categoria meta com os ícones, entre outras ideias.

A maioria dos materiais que li parece se concentrar em sites auto-hospedados, e não em sites hospedados.

Existem alguma limitação para sites hospedados?

[manuel (Manuel Kostka)]

@satonotdead

Eu me pergunto o quão possível seria gerar um bloco personalizado que exibe o avatar e o nome do usuário (o que eu já consegui fazer), junto com a contagem de tópicos e posts, curtidas, pontos de entusiasmo e algo semelhante a See TL3 Progress, mas em relação a badges específicas (nível de confiança personalizado baseado neles)?

Isso deveria ser totalmente possível e um agente usando as habilidades e os blocos de exemplo do tema compartilhado deveria ser totalmente capaz de codificar isso.

Na verdade, eu fiz um bloco semelhante há algum tempo. Ele ainda não está usando a nova API de Blocos, mas você ainda pode olhar para a abordagem em Manuel Kostka / Discourse / Blocks / User Profile · GitLab. Parece com isso, por exemplo, no tema Canvas Central:

@NateDhaliwal

Se você quiser adicionar um bloco, acho que você precisará enviar um PR para o core.

Nós não temos blocos no core (ainda). Todos os blocos são adicionados apenas usando temas ou componentes de tema.

@nickdb

Há alguma limitação para sites hospedados?

Você pode adicionar blocos a BlockOutlets existentes usando temas e componentes de tema, e acho que você precisa estar em um plano Pro ou superior para adicionar temas personalizados. Caso contrário, não deve haver limitações.

[nickdb (Nick)]

Estou ocupado discutindo com o bot de IA do seu ask, que insiste em me dizer para não usá-lo porque é muito experimental e está sendo “dogfoodado” na Meta. Estou prestes a desistir e esperar que ele fique mais maduro.

[manuel (Manuel Kostka)]

É provável que o bot esteja obtendo sua direção a partir do anúncio oficial: Creating a 'Blocks' API for injecting content

Mas concordo, você não deve usá-lo em produção por enquanto, pois provavelmente haverá mudanças incompatíveis que não serão anunciadas com antecedência.

[nickdb (Nick)]

Estou apenas testando em um site de staging, não mexeria na produção.

[manuel (Manuel Kostka)]

Isso deve estar tudo bem. A ressalva não é que ainda não seja abrangente, mas sim de que não faremos hedge contra mudanças incompatíveis, como fazemos com outras APIs ou interfaces estáveis.

[NateDhaliwal]

@manuel

Não temos blocos no núcleo (ainda). Todos os blocos são adicionados apenas usando temas ou componentes de tema.

Ah, claro. Eu, besta. Pensei que estivesse se referindo à adição de localizações de blocos.

[manuel (Manuel Kostka)]

@NateDhaliwal

Eu achei que estivesse se referindo à adição de localizações de blocos.

Sim, os BlockOutlets estão no núcleo. Embora você também possa adicioná-los com um plugin.