Em poucas palavras
Um manual de identidade visual de um metrô inventado. Mostra como baixar uma única vez as fontes próprias de uma marca e usá-las na visualização da página, no PDF e no arquivo salvo.
O que você vai compor
Quatro páginas do manual de identidade do Metro de Alba, um metrô fictício de cinco linhas. Na capa, as cinco linhas saem juntas do canto inferior esquerdo num trilho comum e se separam para a direita depois de cruzar um rio cinza, sob o nome em Big Shoulders Display. Cada seção abre sob uma faixa preta, com um número grande de dois algarismos na cor de uma das linhas. Em 01 Colour, a primeira coluna da tabela é a própria cor; 02 Type traz linhas de amostra e uma placa de plataforma, e 03 Usage fecha com dois desenhos de mapa emoldurados, um feito segundo as regras (Do) e outro contra elas (Don't). Todo o texto é composto em seis arquivos de fonte que o script baixa antes da primeira diagramação. O PDF é desenhado com os mesmos seis arquivos, e o arquivo .postext leva cinco, porque a fonte de títulos está marcada como não redistribuível.
Esta receita responde a
- Como uso as fontes da minha marca ou fontes licenciadas na composição e as incorporo ao PDF?
- Como faço para exportar um PDF de verdade no navegador, com as fontes incorporadas?
- Como evito que títulos, negritos e marcadores de lista saiam em azul?
- Como acrescento amostras de cor, como chave de cores, ao texto, às legendas ou às notas de tabela?
- Como crio um pacote .postext a partir do código, para passar um documento ao Sandbox ou a outro programa?
A resposta curta
// Your licensed files, one per face in FONTS. Fontsource's copies stand in for them here:
// point FONT_URL at your own server (same origin, or one that lets this page in by CORS).
const slug = (family) => family.toLowerCase().replaceAll(' ', '-');
const FONT_URL = ({ family, weight, style }) => `https://cdn.jsdelivr.net/npm/@fontsource/`
+ `${slug(family)}@5/files/${slug(family)}-latin-${weight}-${style}.woff2`;
const brandFaces = () => Object.entries(FONTS).flatMap(([family, specs]) => specs.map((spec) => {
const weight = parseInt(spec, 10), style = spec.endsWith('i') ? 'italic' : 'normal';
return { family, weight, style, fileId: `${slug(family)}-${weight}-${style}.woff2` };
}));
const fontFiles = new Map(); // fileId → the WOFF2 bytes, fetched once
// 1 · Layout measures with document.fonts: register every face before the first build.
async function loadBrandFonts() {
await Promise.all(brandFaces().map(async ({ family, weight, style, fileId }) => {
const res = await fetch(FONT_URL({ family, weight, style }));
if (!res.ok) throw new Error(`No file for ${family} ${weight} ${style}`);
fontFiles.set(fileId, new Uint8Array(await res.arrayBuffer()));
const face = new FontFace(family, fontFiles.get(fileId), { weight: `${weight}`, style });
document.fonts.add(await face.load());
}));
}
// 2 · The PDF embeds the same bytes as TrueType. renderToPdf asks for the faces the pages
// paint; a weight or slant the brand lacks gets the family's closest file, embedded once.
async function brandFontProvider(family, weight, style) {
const cost = (f) => (f.style === style ? 0 : 1000) + Math.abs(f.weight - weight);
const own = brandFaces().filter((f) => f.family === family);
if (!own.length) throw new Error(`${family} is not one of the brand's fonts`);
return decompressWoff2(fontFiles.get(own.reduce((a, b) => (cost(b) < cost(a) ? b : a)).fileId));
}
// 3 · The bundle: customFonts names each face's file by its fileId; createBundle packs the bytes
// of every family it may hand on. Layout never reads it (gotcha: custom-fonts-declarative).
const customFonts = () => Object.keys(FONTS).map((name) => ({
name, redistributable: name !== DISPLAY, // the display face reaches suppliers another way
variants: brandFaces().filter((f) => f.family === name)
.map(({ weight, style, fileId }) => ({ weight, style, fileId, format: 'woff2' })),
}));
Ingredientes
- Funcionalidades
- Suas próprias fontesPaleta de cores semânticaPreenchimento de célulasAmostras de corAberturas desenhadasTítulos numeradosFaixa de capítulo em largura totalEstilos de tabela com nomeEstilos de parágrafoTipos de recurso personalizadosEstilo de legendaPosicionamento de figurasTextos, fios e caixas nos designs de páginaTipografia do textoUma ou duas colunasFontes antes da diagramaçãoExportação para PDFPacotes .postextPáginas em um canvasFiguras e tabelas como recursos
- Também usa
- BoxesCitações que posicionam as figurasAtributos de títuloEstilos de títuloFigura e Tabela no seu idiomaCores por parteFontes incorporadas ao PDFCabeços por seçãoCapítulos sem número
- Tipografia
- Public Sans, Big Shoulders Display, Spline Sans Mono (SIL OFL 1.1)
- Materiais
- The network drawing on the cover and the two map examples, drawn in code (Ignacio Ferro, CC BY 4.0)
Preparo
#1 · Registrar as fontes da marca, compor e dar ao PDF os mesmos bytes
await loadBrandFonts(); // the answer, step 1
for (const [fileId, markup] of Object.entries(ART)) await loadSvg(fileId, markup);
const doc = buildDocument({ markdown, resources }, config());
showPages(doc, { title: 'Metro de Alba · Identity manual' });
offerPdf(() => renderToPdf(doc, { fontProvider: brandFontProvider, resourceBytes: imageBytes }),
`${RECIPE}.pdf`); // step 2: the provider hands renderToPdf the same files
A diagramação mede cada palavra com as fontes de document.fonts, por isso loadBrandFonts(), na resposta curta, baixa cada arquivo uma vez, guarda os bytes e registra com eles um FontFace antes de buildDocument rodar. O kitFonts do kit só baixa da Fontsource, e uma marca serve os arquivos do próprio servidor. renderToPdf pede as variantes que as páginas pintam, e brandFontProvider responde a cada pedido com os bytes já baixados; um peso ou um itálico que a marca não tenha receberia o arquivo mais próximo da mesma família (Por que um provedor de fontes?). O PDF incorpora os seis arquivos que o canvas mediu, uma vez cada.
#2 · O sistema de cores é uma lista só
const COLOURS = [ // id, name, screen, print (coated stock)
['line-1', 'Line 1 · Tile red', '#e4572e', '0 75 85 0'],
['line-2', 'Line 2 · Harbour teal', '#17bebb', '75 0 32 0'],
['line-3', 'Line 3 · Broom yellow', '#ffc914', '0 22 95 0'],
['line-4', 'Line 4 · Heather', '#6c4f9e', '65 75 0 0'],
['line-5', 'Line 5 · Pine', '#3f9b4a', '76 12 90 2'],
['signal-red', 'Signal red', '#c0391b', '10 88 100 2'],
['signal-green', 'Signal green', '#2b7d3c', '84 25 95 10'],
['ink', 'Ink', '#1f2124', '72 62 55 78'],
['rule', 'Rule grey', '#d9d9d4', '14 10 14 0'],
];
const palette = { ...Object.fromEntries(COLOURS.map(([id, , hex]) => [id, hex])),
paper: '#ffffff', section: '#e4572e' }; // section: the line colour of the current section
// col(): a colour linked to its palette entry, with the entry's hex beside the link.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [...Object.entries(palette), ['main-color', palette.ink]]
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16)).join(' ');
const swatchTable = () => COLOURS.reduce( // an empty first cell, filled with the colour itself
(model, [id], i) => setCellBackground(model, { row: i + 1, col: 0 }, col(id)),
{ headerRowCount: 1, columnWidths: [22, 34, 14, 15, 15], rows: [
['COLOUR', 'NAME', 'HEX', 'RGB', 'CMYK'].map((content) => ({ content, isHeader: true })),
...COLOURS.map(([, name, hex, cmyk]) =>
['', name, hex.toUpperCase(), rgb(hex), cmyk].map((content) => ({ content }))),
] });
Como a paleta e a Tabela 1.1 são montadas com as mesmas nove linhas, a tabela não tem como listar um valor que as páginas não usam. setCellBackground preenche a primeira célula vazia de cada linha com a cor daquela linha, vinculada à paleta. No texto, :swatch{color="line-2"} recebe o id de uma cor da paleta e desenha um quadrado contornado na cor do texto. main-color tem o hex de Ink, de modo que os títulos e os trechos em negrito e itálico, vinculados a ela por padrão, saem em Ink e não no azul do motor. bodyText.referenceColor: col('ink') indica Ink também para as referências (Paleta de cores).
#3 · Uma abertura, três cores de linha
// The body starts ten grid lines down, in both columns.
const opener = { enabled: true, minHeight: pt(10 * LEAD), slot: { elements: [
{ kind: 'text', id: 'number', content: '{number}', fontFamily: DISPLAY, fontWeight: 800,
fontSize: pt(130), lineHeight: 1, color: col('section'), align: 'left', overflow: 'wrap',
// Nudged by eye on the capture: the cap tops of number and title on one line.
placement: { anchor: { to: 'container', edge: 'top-left' },
offset: { x: mm(-1.5), y: mm(1.3) } } },
{ kind: 'text', id: 'title', content: '{titleText}', fontFamily: DISPLAY, fontWeight: 800,
fontSize: pt(34), lineHeight: 1, color: col('ink'), align: 'left', overflow: 'wrap',
placement: { anchor: { to: 'container', edge: 'top-left' },
offset: { x: mm(COL + GUTTER), y: mm(1) }, size: { width: mm(COL) } } },
{ kind: 'text', id: 'lead', content: '{attr.lead}', fontFamily: TEXT, fontSize: pt(12.5),
lineHeight: 1.36, color: col('ink'), align: 'left', overflow: 'wrap',
placement: { anchor: { to: '#title', edge: 'below' }, offset: { y: mm(3) },
size: { width: mm(COL) } } },
] } };
// Each section sets `section` to its line's colour; the number and the head square use it.
const section = (id) => ({ id, palette: { section: palette[id] } });
numberingTemplate: '{1:01}' escreve o contador com dois algarismos, e {number} imprime 01, 02 e 03 na abertura; o título da capa é numbered: false e fica sem número. Os três estilos de seção só diferem na entrada section da paleta, à qual cada um dá a cor da linha. O número e o quadrado da faixa estão vinculados a section, de modo que um único design de abertura serve às três seções. minHeight reserva dez linhas da grade de 14 pt para a abertura, e o texto de cada seção começa na mesma linha da grade na página.
#4 · Do e Don't são tipos de figura
const example = (id, name, colour) => ({ id, name, shortLabel: name, captionPrefix: name,
numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal',
captionStyle: { labelColor: col(colour) } });
const resourceTypes = [...defaultResourceTypes(LANG),
example('do', 'Do', 'signal-green'), example('dont', 'Don’t', 'signal-red')];
const FOOT = { position: 'bottom' }; // cited in one paragraph: its page's foot, one per column
Um tipo de recurso pode ter um captionStyle parcial, e estes dois definem só a cor do rótulo, Signal green para Do e Signal red para Don't (Tipos de recurso). As cores de sinalização chegam a 5,1:1 e 5,5:1 sobre branco, enquanto as linhas 1, 2, 3 e 5 ficam abaixo dos 4,5:1 que o texto pequeno exige. Os dois desenhos flutuam com position: 'bottom' e são citados no mesmo parágrafo, o primeiro sob Drawing the map, por isso dividem o pé da página 4, Do na coluna da esquerda e Don't na da direita.
#5 · O pacote leva as fontes que pode compartilhar
const pack = Object.assign(document.createElement('button'), { type: 'button',
textContent: 'Build the .postext' });
pack.addEventListener('click', async () => {
const { bytes, manifest, warnings } = await createBundle({
name: 'Metro de Alba identity manual', locale: LANG, markdown, config: config(), resources,
files: new Map([...Object.entries(ART), ...fontFiles]), // fileId → SVG markup or font bytes
});
const size = `${Math.round(bytes.length / 1024)} KB`;
const packed = `fonts inside: ${manifest.fonts.map((font) => font.name).join(', ')}`;
kitStatus(['.postext', size, packed, ...warnings].join(' · ')); // warnings: what stayed out
pack.replaceWith(Object.assign(document.createElement('a'), { download: `${RECIPE}.postext`,
href: URL.createObjectURL(new Blob([bytes], { type: 'application/zip' })),
textContent: `Download ${RECIPE}.postext · ${size}` }));
});
document.getElementById('pt-actions').append(pack);
createBundle lê config.customFonts, procura em files os bytes de cada variante pelo fileId dela e os grava em fonts/, com uma entrada fonts no manifesto. A família de títulos tem redistributable: false, fazendo as vezes de uma licença que proíbe repassar os arquivos (a Big Shoulders Display em si está sob a OFL). O arquivo dela fica de fora, e warnings indica a família. O arquivo de 81 KB contém o capítulo, a configuração, os três desenhos e cinco arquivos de fonte. A diagramação nunca lê customFonts; sem ele as páginas saem iguais (Criar um pacote).
A receita completa
// ═══ Postext Cookbook · Nº 040 · Brand fonts in layout, PDF and bundle ════════════
// https://postext.dev/en/cookbook/brand-fonts-identity-manual
// Code: MIT · Text and drawings: original (CC BY 4.0) · Metro de Alba is a fictional network
// Fonts: Public Sans, Big Shoulders Display, Spline Sans Mono (OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocument, renderPageToCanvas, registerResourceImage, defaultResourceTypes, setCellBackground,
createBundle,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'brand-fonts-identity-manual';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region answer: the brand's font files, fetched once for the layout, the PDF and the bundle
// Your licensed files, one per face in FONTS. Fontsource's copies stand in for them here:
// point FONT_URL at your own server (same origin, or one that lets this page in by CORS).
const slug = (family) => family.toLowerCase().replaceAll(' ', '-');
const FONT_URL = ({ family, weight, style }) => `https://cdn.jsdelivr.net/npm/@fontsource/`
+ `${slug(family)}@5/files/${slug(family)}-latin-${weight}-${style}.woff2`;
const brandFaces = () => Object.entries(FONTS).flatMap(([family, specs]) => specs.map((spec) => {
const weight = parseInt(spec, 10), style = spec.endsWith('i') ? 'italic' : 'normal';
return { family, weight, style, fileId: `${slug(family)}-${weight}-${style}.woff2` };
}));
const fontFiles = new Map(); // fileId → the WOFF2 bytes, fetched once
// 1 · Layout measures with document.fonts: register every face before the first build.
async function loadBrandFonts() {
await Promise.all(brandFaces().map(async ({ family, weight, style, fileId }) => {
const res = await fetch(FONT_URL({ family, weight, style }));
if (!res.ok) throw new Error(`No file for ${family} ${weight} ${style}`);
fontFiles.set(fileId, new Uint8Array(await res.arrayBuffer()));
const face = new FontFace(family, fontFiles.get(fileId), { weight: `${weight}`, style });
document.fonts.add(await face.load());
}));
}
// 2 · The PDF embeds the same bytes as TrueType. renderToPdf asks for the faces the pages
// paint; a weight or slant the brand lacks gets the family's closest file, embedded once.
async function brandFontProvider(family, weight, style) {
const cost = (f) => (f.style === style ? 0 : 1000) + Math.abs(f.weight - weight);
const own = brandFaces().filter((f) => f.family === family);
if (!own.length) throw new Error(`${family} is not one of the brand's fonts`);
return decompressWoff2(fontFiles.get(own.reduce((a, b) => (cost(b) < cost(a) ? b : a)).fileId));
}
// 3 · The bundle: customFonts names each face's file by its fileId; createBundle packs the bytes
// of every family it may hand on. Layout never reads it (gotcha: custom-fonts-declarative).
O script.js montado funciona como está: cole-o como script de módulo em qualquer página ou abra a receita no CodePen. Pasta da receita no GitHub ↗ (abre em uma nova aba)
Variações
#Incluir também a fonte de títulos
Se a licença permite repassar os arquivos, tire o sinalizador, e o pacote leva as três famílias em 96 KB.
- name, redistributable: name !== DISPLAY, // the display face reaches suppliers another way
+ name,#Usar um negrito de verdade
boldFontWeight: 600 compõe os trechos em negrito, os cabeçalhos de tabela e os rótulos de legenda no seminegrito, porque a marca não tem negrito; se sua família tiver, acrescente os arquivos dele a FONTS, apague a configuração e reescreva a linha de amostra do texto de exemplo e o “There is no Bold” dela, que deixaria de ser verdade.
- boldFontWeight: 600, // the brand has no Bold: its SemiBold sets **emphasis**
- 'Public Sans': ['400', '400i', '600', '600i'],
+ 'Public Sans': ['400', '400i', '600', '600i', '700', '700i'],Erros comuns
Erro comum
customFonts não carrega nenhuma fonte
config.customFonts só nomeia arquivos de fonte pelo fileId: buildDocument e os renderizadores de canvas, HTML e PDF nunca o leem, então uma família listada ali e não registrada é medida e pintada com uma fonte substituta. Registre você mesmo cada estilo (um FontFace a partir dos bytes) antes da primeira composição e passe esses mesmos bytes ao provedor de fontes do PDF. createBundle lê a lista para empacotar os arquivos num .postext, e o Sandbox a lê para registrar as fontes. Suas próprias fontes →
Erro comum
O negrito ou itálico que falta na família é simulado na tela, não no PDF
Quando um texto pede um peso ou estilo que a família não traz (um cabeçalho de tabela em negrito numa fonte de títulos de um estilo só, itálico numa sem serifa sem itálicos), o navegador o sintetiza no canvas e no HTML, engrossando ou inclinando o redondo com as mesmas larguras. Um PDF só incorpora fontes reais, então nele sai a fonte mais próxima que o provedor entregar, sem engrossar nem inclinar. Ponha na sua lista de fontes só as que a família traz e ajuste cada estilo a elas, por exemplo com tableStyle.headerBold: false. Fontes incorporadas ao PDF →
Erro comum
Os arquivos do Fontsource cobrem letras, não símbolos
O kit incorpora o arquivo latin do Fontsource de cada fonte e, quando o texto usa esses caracteres, o arquivo latin-ext para č, ł, † e o arquivo greek para α, χ (em uma família que o tenha: Lora e Gelasio não têm), na tela e no PDF. Símbolos como →, ≈, ✓ e ★ não estão em nenhum desses arquivos e somem no PDF: desenhe-os, componha-os como matemática ou escolha uma fonte cujos arquivos os tenham. Fontes incorporadas ao PDF →
Passe a createBundle os bytes de cada fonte sob o fileId que customFonts dá a ela. Uma variante sem bytes fica de fora com o aviso “missing file, skipped”, e uma família que perde todas as variantes sai do manifesto.
Créditos
- Receita
- Ignacio Ferro
- Texto
- The Metro de Alba identity manual, a fictional network · Ignacio Ferro · CC BY 4.0
- Imagens
- The network drawing on the cover and the two map examples, drawn in code · Ignacio Ferro · CC BY 4.0
- Fontes
- Public Sans (SIL OFL 1.1) · Big Shoulders Display (SIL OFL 1.1) · Spline Sans Mono (SIL OFL 1.1)
- Código
- MIT, como o Postext
Editar este texto ↗ (abre em uma nova aba)Pasta da receita no GitHub ↗ (abre em uma nova aba)


