Khatt: caligrafia árabe animada
O Khatt formata o texto com HarfBuzz (letras conectadas, da direita para a esquerda, marcas no lugar), organiza e anima com CSS puro dentro de um único arquivo SVG. Sem rede, sem instalação: o script, as fontes e o motor de formatação estão todos nesta pasta.
Fazer um desenho
node scripts/khatt.mjs "النص" --style ruqaa --layout line --effect ink -o out.svg
Execute a partir da pasta desta skill, ou use o caminho completo para scripts/khatt.mjs.
Salve a saída onde o usuário desejar (pasta do projeto, Área de Trabalho, ...).
| Opção | Valores |
|---|---|
--style | ruqaa (diário, inclinado), naskh (manuscrito clássico), kufi (angular), nastaliq (persa pendurado), kano (caneta de junco grossa), blaka (geométrico ousado) |
--layout | line, arc, circle (um anel com uma estrela no meio), mirror (o clássico musanna espelhado) |
--effect | ink, gold, bleed, mosaic, sand, neon, stars, lantern, rise, stamp, reveal, wave, ou um caminho para um efeito .mjs |
--palette | paper, night, neon, zellige, desert, clear (transparente) |
--ink, --accent, --bg | substitui cores, ex.: --ink "#0b3d2e" --bg none |
--still | congela no desenho final (bom para logotipos e impressão) |
-o | .svg para o arquivo em si, .html para uma página que repete ao clicar |
Execute node scripts/khatt.mjs --list para ver tudo com descrições curtas.
Use \n dentro do texto para uma segunda linha (até quatro linhas).
Escolhendo bem
- Nomes e palavras em inglês: O Khatt desenha apenas escrita árabe. Translitere primeiro (Sara → سارة, Kamangir → كمنجير) e, quando a grafia puder ter várias opções, mostre ao usuário sua grafia antes de renderizar.
- Ramadã ou Eid:
lanternougoldcomnight, estilonaskhouruqaa. - Casamentos e cartões formais:
gold,riseouink; tente--layout mirror. - Logotipos:
--still, estilokufioublaka,--palette clear. - Postagens em redes sociais: um
.svganimado funciona em qualquer navegador. Para um vídeo, aponte o usuário para o estúdio (https://m-alkassem.github.io/khatt/), que exporta MP4. - Texto curto fica melhor. Frases longas: layout
line, duas ou três linhas.
Abra o resultado para o usuário quando possível (ex.: open out.html no macOS).
Fazer um novo efeito
Quando nenhum dos doze efeitos servir ("faça as letras queimarem", "uma lanterna de Ramadã
que balança"), escreva um novo. Comece a partir de examples/ripple.mjs. Um efeito é um
objeto simples sem imports:
export default {
id: "my-effect", name: "My effect", nameAr: "…", blurb: "…",
palette: "night", // id da paleta padrão
loop: false, // true se continuar se movendo
render(ctx) {
// retorna { css, defs?, body, duration, poster? }
},
};
render(ctx) recebe:
ctx.pieces: uma entrada por glifo:d(caminho SVG),order(ordem de leitura, 0 = primeira letra),box{x0,y0,x1,y1},cx,cy. Cópias espelhadas compartilham uma ordem.ctx.steps,ctx.box(caixa de texto),ctx.view(tela inteira),ctx.em(tamanho da fonte, 100),ctx.palette(bg,ink,accent),ctx.rng()(aleatório com semente).ctx.stagger(order, spread?): atraso para uma letra, distribuído porspreadsegundos.ctx.sample(piece, count): pontos aleatórios dentro de uma letra, para partículas.ctx.inside(piece, x, y),ctx.area(piece).ctx.anim(name, seconds, { ease, loop, alternate }): CSS de animação para uma classe.ctx.at(seconds, extraStyle?): o estilo inline que define o atraso de um elemento.ctx.n(number): arredonda números para saída compacta.ctx.p: um prefixo único. Use-o para toda classe, id e nome de keyframe.
Regras que mantêm o desenho pausável em qualquer quadro (paradas e exportação de vídeo dependem disso):
- Todo elemento animado recebe
class="${p}-a ..."estyle="${at(seconds)}". - Use
ctx.anim(...)em suas regras de classe. Nunca escreva a abreviaçãoanimation:ou definaanimation-delayvocê mesmo. - Nomeie keyframes
${p}-something. Adicione${p}-ba um elemento para escaloná-lo ou girá-lo em torno de seu próprio centro. - Anime apenas propriedades CSS (
opacity,transform,stroke-dashoffset,fill-opacity, …). SMIL<animate>e scripts não congelarão corretamente. - Mantenha leve: no máximo alguns milhares de elementos.
Depois execute:
node scripts/khatt.mjs "نار" --effect ./my-effect.mjs -o fire.html
Se o usuário gostar, sugira que compartilhe como um pull request em
https://github.com/M-Alkassem/khatt (os efeitos ficam em src/effects/).