Saltar al contingut principal
Recepta número 40

Receptari · Capítol 10 · Sortida i integració

Fonts de marca a la composició, al PDF i al paquet

El manual d'identitat d'un metro fictici amb els fitxers de font de la marca, baixats un sol cop per a la composició, el PDF i un paquet .postext.

En aquesta pàgina
  • Mostra en anglès: encara no hi ha edició en català
  • Format 210 × 280 mm
  • 2 columnes, espai entre columnes de 8 mm
  • Public Sans 9,8/14
  • Big Shoulders Display
  • Spline Sans Mono
  • 4 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 76 ms
  • 246 línies de codi

En poques paraules

Un manual d'identitat d'un metro inventat. Ensenya a baixar una sola vegada les fonts pròpies d'una marca i a fer-les servir a la previsualització, al PDF i al fitxer desat.

Què compondràs

Quatre pàgines, en anglès, del manual d'identitat del Metro de Alba, una xarxa fictícia de cinc línies. A la coberta, les cinc línies surten juntes de l'angle inferior esquerre i se separen cap a la dreta després de travessar un riu gris, sota el nom en Big Shoulders Display. Cada secció s'obre sota una franja negra, amb un número de dues xifres en el color d'una línia. A 01 Colour, la primera columna de la taula és el color mateix; 02 Type reuneix línies de mostra i un rètol d'andana, i 03 Usage tanca amb dos plànols emmarcats, un dibuixat segons les regles (Do) i un altre que se les salta (Don't). Tot el text surt de sis fitxers de font que el codi baixa abans de compondre. El PDF es dibuixa amb aquests sis fitxers i el .postext en porta cinc, perquè la font de rètols està marcada com a no redistribuïble.

Aquesta recepta respon a

  • Com faig servir les meves fonts corporatives o amb llicència en la composició i les incrusto al PDF?
  • Com exporto un PDF de debò al navegador, amb les fonts incrustades?
  • Com evito que els títols, les negretes i les vinyetes surtin en blau?
  • Com afegeixo mostres de color com a llegenda en el text, els peus o les notes de taula?
  • Com creo un paquet .postext des del codi per passar un document al Sandbox o a un altre programa?

La resposta curta

script.js · línies 16–53al codi complet
// 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' })),
}));

Ingredients

Tipografia
Public Sans, Big Shoulders Display, Spline Sans Mono (SIL OFL 1.1)
Recursos
  • The network drawing on the cover and the two map examples, drawn in code (Ignacio Ferro, CC BY 4.0)

Elaboració

#1 · Registra les fonts de la marca, compon i dona al PDF els mateixos bytes

script.js · línies 448–453al codi complet
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

La composició mesura cada paraula amb les fonts de document.fonts, així que loadBrandFonts(), a la resposta curta, baixa cada fitxer una sola vegada, en desa els bytes i hi registra un FontFace abans de cridar buildDocument. El kitFonts del kit només baixa de Fontsource, i una marca serveix els seus fitxers des del seu propi servidor. renderToPdf demana les variants que pinten les pàgines, i brandFontProvider respon cada petició amb els bytes ja baixats; a un gruix o una cursiva que la marca no tingui li donaria el fitxer més proper de la mateixa família (Per què un proveïdor de fonts?). El PDF incrusta els sis fitxers que va mesurar el canvas, una vegada cadascun.

#2 · El sistema de color és una sola llista

script.js · línies 59–84al codi complet
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 }))),
  ] });

Com que la paleta i la taula 1.1 es construeixen amb les mateixes nou files, la taula no pot donar un valor que les pàgines no facin servir. setCellBackground omple la primera cel·la de cada fila, que va buida, amb el color d'aquella fila enllaçat a la paleta. Dins el text, :swatch{color="line-2"} rep l'identificador d'una entrada de la paleta i dibuixa un quadrat perfilat amb el color del text. main-color pren l'hex d'Ink, de manera que els títols, les negretes i les cursives, que hi estan enllaçats per defecte, surten en Ink i no en el blau del motor. bodyText.referenceColor: col('ink') assigna Ink també a les remissions (Paleta de colors).

#3 · Una obertura, tres colors de línia

script.js · línies 93–110al codi complet
// 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}' escriu el comptador amb dues xifres, i {number} imprimeix 01, 02 i 03 a l'obertura; el títol de la coberta porta numbered: false i es queda sense número. Els tres estils de secció només es diferencien en l'entrada section de la paleta, a la qual cadascun dona el color de la seva línia. El número i el quadrat de la franja estan enllaçats a section, de manera que un únic disseny d'obertura serveix per a les tres seccions. minHeight reserva per a l'obertura deu línies de la retícula de base de 14 pt, i el text de cada secció comença a la mateixa línia de la seva pàgina.

#4 · Do i Don't són tipus de figura

script.js · línies 159–164al codi complet
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

Un tipus de recurs admet un captionStyle parcial, i aquests dos només canvien el color de l'etiqueta: Signal green a Do i Signal red a Don't (Tipus de recurs). Els dos colors de senyal arriben a 5,1:1 i 5,5:1 sobre blanc, mentre que les línies 1, 2, 3 i 5 es queden per sota del 4,5:1 que demana el text petit. Els dos dibuixos floten amb position: 'bottom' i se citen al mateix paràgraf, el primer de Drawing the map, així que comparteixen el peu de la pàgina 4, Do a la columna esquerra i Don't a la dreta.

#5 · El paquet porta les fonts que pot compartir

script.js · línies 457–471al codi complet
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 llegeix config.customFonts, busca a files els bytes de cada variant pel seu fileId i els desa a fonts/, amb una entrada fonts al manifest. La família de rètols porta redistributable: false, que aquí simula una llicència que no deixa repartir els fitxers (la de Big Shoulders Display, l'OFL, sí que ho permet). El seu fitxer es queda fora i warnings anomena la família. El fitxer de 81 KB conté el capítol, la configuració, els tres dibuixos i cinc fitxers de font. La composició no llegeix mai customFonts, i sense ell les pàgines surten iguals (Crear un paquet).

La recepta completa

Sandbox
// ═══ 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).

L'script.js compost funciona tal com és: enganxa'l com a script de mòdul en qualsevol pàgina o obre la recepta a CodePen. Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)

Variants

#Inclou també la font de rètols

Si la llicència et permet repartir els fitxers, treu redistributable i el paquet portarà les tres famílies en 96 KB.

-  name, redistributable: name !== DISPLAY, // the display face reaches suppliers another way
+  name,

#Fes servir una negreta de debò

Com que la marca no té negreta, boldFontWeight: 600 compon en seminegreta les negretes, les capçaleres de taula i les etiquetes dels peus; si la teva família en té, afegeix-ne els fitxers a FONTS, treu el paràmetre i canvia la línia de mostra del text d'exemple i el seu «There is no Bold», que deixarien de ser certs.

-    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'],

Errors freqüents

Error freqüent

customFonts no carrega cap font

config.customFonts només anomena fitxers de font pel seu fileId: buildDocument i els renderitzadors de canvas, HTML i PDF no el llegeixen mai, així que una família que hi figura i no s'ha registrat es mesura i es pinta amb una font de reserva. Registra tu mateix cada estil (un FontFace amb els seus bytes) abans de la primera composició i passa aquests mateixos bytes al proveïdor de fonts del PDF. createBundle llegeix la llista per ficar els fitxers en un .postext, i el Sandbox, per registrar les fonts. Les teves pròpies fonts →

Error freqüent

La negreta o la cursiva que la família no porta se simula a la pantalla, no al PDF

Quan un text demana un pes o un estil que la seva família no porta (una capçalera de taula en negreta amb una font de retolació d'un sol estil, cursiva en una sans sense cursives), el navegador el sintetitza al canvas i a l'HTML: engruixeix o inclina la rodona amb les mateixes amplades. Un PDF només incrusta fonts reals, així que allà s'imprimeix la font més propera que doni el proveïdor, sense engruixir ni inclinar. Posa a la llista de fonts només les que la família porta i ajusta cada estil a aquestes, per exemple amb tableStyle.headerBold: false. Fonts incrustades al PDF →

Error freqüent

Els fitxers de Fontsource cobreixen lletres, no símbols

El kit incrusta el fitxer latin de Fontsource de cada font i, quan el text els fa servir, el seu fitxer latin-ext per a č, ł, † i el seu fitxer greek per a α, χ (en una família que en tingui: Lora i Gelasio no), a la pantalla i al PDF. Símbols com →, ≈, ✓ i ★ no són a cap d'aquests fitxers i falten al PDF: dibuixa'ls, escriu-los com a matemàtiques o tria una font els fitxers de la qual els tinguin. Fonts incrustades al PDF →

Passa a createBundle els bytes de cada font amb el fileId que els dona customFonts. Una variant sense bytes es queda fora amb l'avís «missing file, skipped», i la família que es queda sense variants desapareix del manifest.

Crèdits

Text
  • The Metro de Alba identity manual, a fictional network · Ignacio Ferro · CC BY 4.0
Imatges
  • The network drawing on the cover and the two map examples, drawn in code · Ignacio Ferro · CC BY 4.0
Fonts
Public Sans (SIL OFL 1.1) · Big Shoulders Display (SIL OFL 1.1) · Spline Sans Mono (SIL OFL 1.1)
SandboxPDF