Sistema de Temas — Honne

Motor de temas LiquidJS para páginas públicas de usuários. Temas são compostos por templates Liquid, seções, snippets, assets (CSS/JS) e um arquivo de configuração (schema.json) que define as settings editáveis pelo usuário no editor visual.

⬇ Download do Tema Base

O ZIP contém a estrutura completa do tema base com todos os arquivos Liquid, CSS, JS e configuração. Use como ponto de partida para criar temas customizados.

Índice

• Arquitetura
• Estrutura de Diretórios
• Fluxo de Render
• Variáveis do Contexto Liquid
  • Objeto user
  • Objeto settings
  • Objeto theme
  • Objeto player / featured_video
  • Objeto links
  • Objeto socials
  • Objeto translation / locales / locale
• Filtros Custom
• Tags Custom
  • Tag {% render %}
  • Named Arguments
  • Escopo de Variáveis
• Sistema de Settings
  • Tipos de Setting
  • Grupos (Tabs no Editor)
  • Merge Base + Usuário
• Templates
  • profile.liquid
  • portfolio.liquid
  • business.liquid
• Sections
  • header.liquid / portfolio-header.liquid / business-header.liquid
  • links.liquid
  • social.liquid
  • player.liquid
  • featured-video.liquid
  • countdown.liquid
  • footer.liquid
  • Business Sections
  • Portfolio Sections
  • language-selector.liquid
• Snippets
  • link-button.liquid
    • Tipos de Link
• Embeds (Vídeo / Música)
• ícones Sociais (simple-icons)
• Assets do Tema
• Campos do Link (formato do banco)
• Editor Visual (Admin)
• Cache
• Criar um Tema Novo

Arquitetura

honne/
└── themes/
    └── base/                     ← Tema padrão (fallback)
        ├── layout/
        │   └── theme.liquid      ← HTML shell (head, CSS, footer)
        ├── templates/
        │   ├── profile.liquid    ← Padrão (links + social + player)
        │   ├── portfolio.liquid  ← Currículo/portfólio
        │   └── business.liquid   ← Perfil empresarial
        ├── sections/             ← Componentes reutilizáveis
        │   ├── header.liquid
        │   ├── links.liquid
        │   ├── social.liquid
        │   ├── player.liquid
        │   ├── featured-video.liquid
        │   ├── countdown.liquid
        │   ├── footer.liquid
        │   ├── language-selector.liquid
        │   ├── business-header.liquid
        │   ├── business-hours.liquid
        │   ├── business-location.liquid
        │   ├── business-testimonials.liquid
        │   ├── business-contact.liquid
        │   ├── portfolio-header.liquid
        │   ├── portfolio-skills.liquid
        │   ├── portfolio-projects.liquid
        │   └── portfolio-hire.liquid
        ├── snippets/             ← Partials pequenos
        │   └── link-button.liquid
        ├── assets/               ← Estáticos públicos
        │   ├── theme.css
        │   └── theme.js
        └── config/
            ├── schema.json       ← Define settings + grupos (UI do editor)
            └── settings.json     ← Valores padrão de todas as settings

Estrutura de Diretórios

meu-tema/
├── layout/
│   └── theme.liquid        ← Obrigatório. HTML shell com {{ content }}
├── templates/
│   ├── profile.liquid      ← Obrigatório. Template principal
│   ├── portfolio.liquid    ← Opcional. fallback: profile.liquid
│   └── business.liquid     ← Opcional. fallback: profile.liquid
├── sections/               ← Opcional. Componentes usados via {% render %}
│   └── *.liquid
├── snippets/               ← Opcional. Partials usados via {% render %}
│   └── *.liquid
├── assets/                 ← Opcional. Servidos em /theme-assets/base/*
│   ├── theme.css
│   └── theme.js
└── config/
    ├── schema.json          ← Opcional. Define settings editáveis
    └── settings.json        ← Opcional. Valores padrão

Fluxo de Render

Request /:username
  ↓
Profile Controller (apps/web/src/controllers/profile.ts)
  ├── Busca user no DB (username)
  ├── Busca links ativos (linkQueries.listLinks)
  ├── Carrega settings padrão (themes/base/config/settings.json)
  ├── Merge com user.theme (JSONB da tabela users)
  │   { ...baseSettings, ...userTheme }
  └── Chama renderUserPage(rawUser, mergedSettings)
        ↓
Theme Engine (packages/theme-engine/src/index.ts)
  ├── normalizeUser(rawUser)
  │   ├── Filtra links (enabled, scheduled_at, expires_at)
  │   ├── Ordena links por position
  │   ├── Enriquece socials com _icon_slug (mapeia twitter→x)
  │   └── Retorna NormalizedUser
  ├── parseEmbedUrl(player_url) → player (ou null)
  ├── parseEmbedUrl(featured_video_url) → featured_video (ou null)
  ├── Se featured_video_autoplay → adiciona ?autoplay=1 na embedUrl
  ├── Monta contexto Liquid:
  │   { user, links, player, featured_video, theme, settings, socials }
  ├── Renderiza template conforme profile_mode:
  │   "profile"   → templates/profile.liquid
  │   "portfolio" → templates/portfolio.liquid
  │   "business"  → templates/business.liquid
  ├── Render interno: {{ content }} dentro de layout/theme.liquid
  │   ↓
  │   layout/theme.liquid
  │     ├── Meta tags (OG, theme-color, viewport)
  │     ├── Google Fonts (font_family da setting)
  │     ├── Tailwind CDN (config dinâmica com cores do tema)
  │     ├── CSS inline com variáveis CSS (:root { --bg, --text, ... })
  │     ├── CSS custom ({{ settings.custom_css }})
  │     ├── <link rel="stylesheet" href="{{ 'theme.css' | asset_url }}">
  │     ├── {{ content }} → template renderizado
  │     └── <script src="{{ 'theme.js' | asset_url }}"></script>
  ├── Cache LRU (template parsed + HTML output)
  └── Retorna HTML final

Variáveis do Contexto Liquid

Todas as variáveis abaixo estão disponíveis em qualquer template, section ou snippet do tema.

Objeto user

Objeto settings

Contém o merge de settings.json + user.theme (JSONB do banco). Valores do usuário sobrescrevem os defaults.

Objeto theme

Alias para settings — contém os mesmos valores. Útil para diferenciar settings de tema de outras settings.

{{ theme.primary_color }}   → mesmo que {{ settings.primary_color }}
{{ theme.show_player }}     → mesmo que {{ settings.show_player }}

Objeto player / featured_video

Presentes apenas quando a URL correspondente está preenchida no settings.

Se a URL não estiver preenchida, a variável é null/false — pode ser usada em condicionais:

{% if player %}
  <iframe src="{{ player.embedUrl }}"></iframe>
{% endif %}

Objeto links

Array de links do usuário, já filtrados (apenas enabled + dentro do agendamento) e ordenados por position.

Cada link tem os campos:

Objeto socials

Array de redes sociais do usuário.

Objeto translation / locales / locale

(Funcionalidade futura de internacionalização)

• {{ translation.title }} — Título traduzido
• {{ translation.subtitle }} — Subtítulo traduzido
• {{ translation.bio }} — Bio traduzida
• {{ locales }} — Array de idiomas disponíveis
• {{ locale }} — Código do idioma ativo ("pt", "en", etc.)

Filtros Custom

Filtro asset_url

Segurança: sanitiza o path (remove caracteres especiais, bloqueia ..).

<link rel="stylesheet" href="{{ 'theme.css' | asset_url }}">
<script src="{{ 'theme.js' | asset_url }}"></script>
<img src="{{ 'images/logo.svg' | asset_url }}" alt="Logo">

Tags Custom

Tag {% render %}

Carrega uma section ou snippet do tema.

{% render 'header' %}              ← sections/header.liquid
{% render 'link-button',           ← snippets/link-button.liquid
  title: link.title,
  url: link.url,
  type: link.type %}

A tag procura primeiro em sections/, depois em snippets/.

Named Arguments

Você pode passar variáveis nomeadas para a section/snippet:

{% render 'card',
  title: project.name,
  description: project.bio,
  image: project.thumbnail %}

Escopo de Variáveis

Dentro de uma section/snippet renderizada, as seguintes variáveis estão automaticamente disponíveis sem precisar passar como argumento:

Além disso, qualquer argumento nomeado passado no {% render %} está disponível como variável local.

{% render 'meu-componente', cor: 'azul', tamanho: 'grande' %}

Dentro de meu-componente.liquid:

{{ cor }}      → "azul"
{{ tamanho }}  → "grande"

Sistema de Settings

Definição (schema.json)

O arquivo config/schema.json define todas as settings que o usuário pode editar no editor visual.

Estrutura:

{
  "groups": [
    { "id": "hero", "label": "Hero", "icon": "person", "fields": ["logo_image", "hero_title", "hero_subtitle"] }
  ],
  "settings": [
    { "id": "hero_title", "label": "Título", "type": "text", "default": "", "placeholder": "Ex: Criador de Conteúdo", "info": "Texto principal acima dos links" }
  ]
}

Tipos de Setting

Grupos (Tabs no Editor)

Cada grupo define uma seção colapsável no editor visual.

Grupos do tema base:

Merge Base + Usuário

1. Base: themes/base/config/settings.json (valores padrão do tema)
2. Usuário: users.theme (coluna JSONB no PostgreSQL)
3. Resultado: { ...baseSettings, ...userTheme }

O usuário pode sobrescrever qualquer setting. Valores não definidos pelo usuário mantêm o default.

Templates

profile.liquid

Template padrão. Fluxo de render:

social (top)     ← se social_position == 'top'
header           ← avatar + nome + bio
player (top)     ← se player_position == 'top'
featured-video (top)  ← se featured_video_position == 'top'
countdown        ← se show_countdown e countdown_date
player (before_links) ← se player_position == 'before_links'
featured-video (before_links)
links            ← lista de links do usuário
player (after_links)  ← se player_position == 'after_links'
featured-video (after_links)
social (!top)    ← se social_position != 'top'
player (bottom)  ← se player_position == 'bottom'
featured-video (bottom)
footer

portfolio.liquid

social (top)
portfolio-header   ← título + avatar + cargo
portfolio-skills   ← lista de habilidades
portfolio-projects ← links do tipo 'case'
portfolio-hire     ← botão "Contrate-me"
social (!top)
footer

business.liquid

social (top)
business-header    ← nome da empresa + avatar
player/video (top)
business-hours     ← horários
business-location  ← endereço + Google Maps
countdown
player/video (before_links)
links
player/video (after_links)
business-testimonials ← depoimentos
business-contact   ← WhatsApp + telefone
social (!top)
player/video (bottom)
footer

Sections

header.liquid / portfolio-header.liquid / business-header.liquid

Renderizam o topo da página:

{% if settings.logo_image %}
  <img src="{{ settings.logo_image }}">
{% elsif user.avatarUrl %}
  <img src="{{ user.avatarUrl }}">
{% endif %}

<h1>{{ hero_title }}</h1>  ← translation.title > settings.hero_title > user.name
<p>{{ settings.hero_subtitle }}</p>
<p>{{ user.bio }}</p>

links.liquid

Itera sobre {{ links }} e renderiza cada um com o snippet link-button:

{% for link in links %}
  {% render 'link-button',
    title: link.title,
    url: link.url,
    type: link.type,
    click_id: link.id,
    username: user.username,
    cta_text: link.cta_text,
    cta_color: link.cta_color,
    thumbnail: link.thumbnail,
    embed_url: link.embed_url,
    embed_provider: link.embed_provider,
    embed_id: link.embed_id %}
{% endfor %}

social.liquid

Renderiza ícones de redes sociais. Usa simple-icons CDN para os ícones (com fallback inline SVG para LinkedIn).

Comportamento conforme settings.social_style:

<img src="https://cdn.simpleicons.org/{{ social._icon_slug }}/a1a1aa">

Para LinkedIn (não disponível no simple-icons), renderiza SVG inline.

player.liquid

Renderiza iframe do player de música (Spotify ou SoundCloud).

{% if settings.show_player and player %}
  <iframe src="{{ player.embedUrl }}"
    height="{% if player.provider == 'spotify' and player.type == 'track' %}80{% else %}166{% endif %}">
  </iframe>
{% endif %}

featured-video.liquid

Renderiza iframe do vídeo em destaque (YouTube, Vimeo, Twitch).

{% if settings.show_featured_video and featured_video %}
  <div style="padding-bottom: 56.25%;">
    <iframe src="{{ featured_video.embedUrl }}" allowfullscreen></iframe>
  </div>
{% endif %}

countdown.liquid

Renderiza contador regressivo com data dinâmica via JavaScript.

<section data-countdown="{{ settings.countdown_date }}"
         data-message="{{ settings.countdown_message }}"
         data-expired="{{ settings.countdown_expired_message }}">
  <div class="countdown-timer"></div>
</section>

O CSS e JS do contador estão em assets/theme.css e assets/theme.js.

footer.liquid

{% if settings.show_footer %}
  <footer>Powered by <strong>Honne</strong></footer>
{% endif %}

Business Sections

Portfolio Sections

language-selector.liquid

Seletor de idioma (futuro). Exibido apenas se locales.size > 1.

<select onchange="switchLanguage(this.value)">
  {% for l in locales %}
    <option value="{{ l.code }}">{{ l.code | upcase }}</option>
  {% endfor %}
</select>

Snippets

link-button.liquid

Snippet principal que renderiza cada tipo de link. Recebe os seguintes argumentos:

Tipos de Link

Tracking de cliques: Quando click_id e username estão presentes, o link aponta para /click/:username/:id que registra o clique e redireciona.

CTA customizado:

• Se cta_color está presente: fundo = cor do CTA, texto = branco
• Se não: fundo = var(--card), texto = var(--text)
• Se cta_text está presente: mostra o texto do CTA em vez do título
• Se settings.button_shadow: adiciona box-shadow

Embeds (Vídeo / Música)

O sistema detecta automaticamente URLs de serviços de streaming e gera iframes embed.

Providers Suportados

Como Funciona

1. No backend (packages/core/src/embed.ts): parseEmbedUrl(url) analisa a URL e retorna { provider, id, embedUrl, type } ou null se não for reconhecida.

2. No engine (packages/theme-engine/src/index.ts): Para cada link, se a URL for reconhecida como embed, os campos embed_url, embed_provider, embed_id, embed_type são adicionados ao objeto do link.

3. No template (link-button.liquid): Se embed_url existe e o tipo é video ou music, renderiza o iframe embed em vez do botão padrão.

Exemplo

{% if link.type == 'video' and link.embed_url %}
  <iframe src="{{ link.embed_url }}"></iframe>
{% endif %}

Ícones Sociais (simple-icons)

As redes sociais usam o simple-icons CDN para renderizar os ícones.

URL padrão:

https://cdn.simpleicons.org/{slug}/a1a1aa

Onde {slug} é o slug da plataforma no simple-icons e a1a1aa é a cor do ícone (hex sem #).

Mapeamento de Nomes

LinkedIn

LinkedIn não tem ícone no simple-icons. O tema base inclui um SVG inline do logo do LinkedIn no social.liquid.

Custom Platform

O editor de redes sociais tem uma opção "Outra…" onde o usuário pode digitar qualquer slug do simple-icons (ex: patreon, onlyfans, nintendoswitch, medium, devto).

Assets do Tema

Arquivos em assets/ são servidos estaticamente via:

GET /theme-assets/base/:file

Arquivos do tema base:

• theme.css — Animações (fade-in, scale), estilos do countdown, lightbox
• theme.js — Countdown timer, link tracking client-side

Uso nos templates:

<link rel="stylesheet" href="{{ 'theme.css' | asset_url }}">
<script src="{{ 'theme.js' | asset_url }}"></script>

MIME types suportados: .css, .js, .png, .jpg, .svg, .woff2

Campos do Link (formato do banco)

Cada link armazenado no banco tem a seguinte estrutura:

{
  id: string;              // UUID
  userId: string;          // FK do usuário
  title: string;           // Título
  url: string;             // URL de destino
  type: string;            // "link" | "button" | "video" | "music" | "image" | "text" | "divider" | "case"
  position: number;        // Ordenação (0-based)
  enabled: boolean;        // Ativo?
  ctaText: string | null;  // Texto do CTA
  ctaColor: string | null; // Cor do CTA (hex)
  thumbnail: string | null;// URL da thumbnail
  content: object | null;  // Dados específicos do tipo:
                            //   case: { description, tags: string[] }
  scheduledAt: Date | null;// Agendamento (início)
  expiresAt: Date | null;  // Agendamento (fim)
  createdAt: Date;
  updatedAt: Date;
}

Editor Visual (Admin)

O editor de temas (GET /admin/theme) permite:

1. Settings visuais — Formulário gerado dinamicamente do schema.json, agrupado por groups
2. Preview ao vivo — Iframe com mockup iPhone (375x650) ou desktop, sandboxed
3. Drag & drop dos grupos para reordenar
4. Auto-save — Salva automaticamente 2s após a última alteração
5. Atalho: Ctrl+S para salvar

Edição de Arquivos

Editam o tema base em disco (themes/base/), compartilhado por todo usuário sem tema instalado — só platform admin, não é ação por conta.

Preview

O preview é carregado em um iframe com sandbox="allow-scripts allow-same-origin allow-popups allow-forms". Atualiza automaticamente ao salvar settings.

Cache

3 camadas de cache LRU:

Clear cache em:

• Publicar tema
• Salvar settings
• Upload de novo tema
• Restaurar tema padrão

Criar um Tema Novo

1. Baixe o tema base como ponto de partida (botão no topo desta página)
2. Estrutura mínima:

   meu-tema/
   ├── layout/theme.liquid    ← HTML shell
   ├── templates/profile.liquid ← Template principal
   └── config/
       ├── schema.json        ← Settings editáveis
       └── settings.json      ← Valores padrão
   

3. Customize os templates usando as variáveis Liquid documetandas acima
4. Adicione sections em sections/ e use {% render 'nome' %}
5. Adicione assets em assets/ e use {{ 'arquivo' | asset_url }}
6. Defina as settings no schema.json com groups e settings
7. Teste localmente fazendo upload do ZIP no editor de temas (/admin/theme/upload)

Regras do Sandbox

• LiquidJS sem acesso a fs, require, process, rede
• ownPropertyOnly: true — não acessa prototype chain
• Path traversal sanitization em todos os file paths
• Rate limit de render: 100 renders/min por usuário

Boas Práticas

• Use variáveis CSS (var(--bg), var(--text), var(--primary), var(--card), var(--muted), var(--radius)) em vez de valores fixos — elas são definidas no layout/theme.liquid conforme as settings do usuário
• Adapte o design para mobile-first (largura máxima de 640px)
• Use loading="lazy" em imagens
• Teste todos os tipos de link (link, button, video, music, image, text, divider, case)
• Mantenha compatibilidade com o sistema de tracking (/click/:username/:id)
• Para animações, use as classes CSS do assets/theme.css (.animate-fade-in)
• O tema base usa Tailwind CSS via CDN — você pode usar classes utilitárias nos seus templates