En pocas palabras
Una guía de reciclaje de cuatro páginas de un ayuntamiento. Enseña a crear un PDF que los lectores de pantalla pueden seguir, con descripciones de las imágenes y tablas que pueden leer en voz alta.
Lo que vas a componer
Reciclar en el barrio es la guía de reciclaje de un ayuntamiento inventado: cuatro páginas A4 para leer en pantalla o imprimir en casa. La cubierta, azul marino, lleva los cinco contenedores sobre un bordillo amarillo. La página 2 reúne el índice, tres recuadros y la carta de la concejala; la 3 y la 4, las dos secciones, a dos columnas en bandera. El PDF etiquetado que exporta el código supera las comprobaciones PDF/UA-1 de veraPDF, con títulos, listas, recuadros y tablas en orden de lectura, texto alternativo en la figura y celdas de cabecera en las tablas. El archivo declara título e idioma (es), y los marcadores y las filas del índice son enlaces. Como las etiquetas no se imprimen, el código las dibuja solo en la vista previa de la página 3, la que ves aquí, con un recuadro numerado por bloque y el nombre de su etiqueta.
Esta receta responde a
- ¿Cómo genero un PDF accesible (etiquetado, PDF/UA) con texto alternativo e idioma del documento?
- ¿Cómo consigo las etiquetas «Figura» y «Tabla» en el idioma de mi documento?
- ¿Cómo añado un índice que se actualice solo (líneas de puntos, números de página, autores, filas de parte)?
- ¿Cómo exporto un PDF de verdad en el navegador, con las fuentes incrustadas?
La respuesta corta
// renderToPdf writes a tagged PDF by default: the tag tree follows the headings, paragraphs,
// lists and boxes of the Markdown. Pictures and tables carry their own accessible text here.
const table = (id, tsv, columnWidths, caption, altText) => ({ id, typeId: 'table', kind: 'table',
caption, altText, createdAt: 0, updatedAt: 0, // altText → the Table's /Summary
placement: { position: 'here' }, // set under the sentence that cites it
table: { model: { headerRowCount: 1, columnWidths, // row 0: TH cells, scope Column
rows: parseTSV(tsv).rows.map((row) => row.map(({ content }, c) => ({ content: cell(content),
...(c === 0 && { isHeader: true }) }))) } } }); // column 0: TH cells, scope Row
const resources = () => [
{ id: 'contenedores', typeId: 'figure', kind: 'svg', placement: { position: 'here' },
svg: { fileId: 'contenedores.svg', width: FIGURE[0] * PX, height: FIGURE[1] * PX },
caption: 'Una isla del barrio: de izquierda a derecha, amarillo, azul, verde, marrón y gris.',
altText: 'Cinco contenedores en fila: amarillo con una botella de plástico, azul con una caja '
+ 'de cartón, verde con una botella de vidrio, marrón con un corazón de manzana y gris con '
+ 'una bolsa de basura cerrada.', createdAt: 0, updatedAt: 0 }, // → the Figure's /Alt
table('dudas', dudas, [3, 2], 'Los residuos que más dudas dan.',
'Once residuos y el contenedor de cada uno.'),
table('horarios', horarios, [2.2, 4, 1.4], 'Días y horas de recogida.',
'Qué días y desde qué hora se vacía cada contenedor.'),
{ id: 'calle', typeId: 'figure', kind: 'svg', createdAt: 0, updatedAt: 0, // the cover's row:
svg: { fileId: 'calle.svg', width: STREET[0] * PX, height: STREET[1] * PX } }, // an artifact
];
const exportPdf = (doc) => renderToPdf(doc, { fontProvider: fontsourceProvider,
resourceBytes: imageBytes }); // accessible and outlines default to true
Ingredientes
- Funciones
- PDF accesible etiquetadoÍndice generalExportación a PDFMarcadores del PDFFigura y Tabla en tu idiomaTablas a partir de datosFiguras justo aquíMuestras de colorCitas que colocan las figurasMetadatos del documentoEstilos de títuloCapítulos sin númeroAperturas diseñadasBanda de capítulo a todo el anchoCubiertas, portadas y colofonesImágenes en los diseños de páginaRecuadrosFuentes antes de componerPáginas en un canvas
- También usa
- Atributos de títuloTítulos numeradosSalir de la rejilla a propósitoSaltos de página y de columnaEstilos de párrafoFuentes incrustadas en el PDFFiguras y tablas como recursosGeometría por secciónCabeceras por secciónSaltos de línea en los títulos
- Tipografía
- Atkinson Hyperlegible Next, Atkinson Hyperlegible Mono, Public Sans (SIL OFL 1.1)
- Recursos
- Ninguno: todas las imágenes se dibujan en código
Elaboración
#1 · El idioma y el título del documento
locale: LANG, // → /Lang es, and "Figura", "Tabla" in the captions and the citations
// /Title and /Author come from the frontmatter's title and author
postext-pdf escribe el idioma de las etiquetas a partir de locale, aquí /Lang es, para que un lector de pantalla lea la guía con pronunciación española; si falta, el archivo declara en-US. El title y el author del frontmatter de content.es.md dan el título y el autor del PDF, y el archivo pide a los visores que muestren ese título en la barra de la ventana en lugar del nombre de archivo. El mismo locale da a los pies y a las citas sus nombres en español: «Figura 1.1», «tabla 1.1». El texto accesible de la figura y de las tablas está en la respuesta corta: el altText da la descripción alternativa de la figura (/Alt) y el resumen de cada tabla (/Summary), y la primera fila y la primera columna de las dos tablas se etiquetan como celdas de cabecera.
#2 · Un solo esquema, y una banda de cubierta con el título y nada más
const [BAND, COVER] = [54, 176]; // mm from the trim top to the foot of each band
const band = (height) => ({ kind: 'box', id: 'band', style: { backgroundColor: col('navy') },
placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(height) } } });
const display = (size, hue) => face('Public Sans', 800, size, { lineHeight: 1, color: col(hue) });
const section = { enabled: true, slot: { elements: [band(BAND),
text('number', '{number}', display(64, 'signal'), at('container', 'top-left', 0, 4)),
text('title', '{titleText}', display(28, 'paper'),
{ ...at('#number', 'right-of', 6, 3.5), size: { width: mm(130) } })] } };
// A heading design's text is tagged as the heading, so the cover's band holds only the title.
const cover = { enabled: true, minHeight: mm(COVER - TOP + 24), slot: { elements: [band(COVER),
{ kind: 'box', id: 'kerb', style: { backgroundColor: col('signal') },
placement: { ...at('bleed', 'top-left', 0, COVER), size: { width: 'fill', height: mm(3) } } },
{ kind: 'image', id: 'bins', resourceId: 'calle', // the wheels stand on the kerb
placement: { ...at('#kerb', 'align-bottom', SIDE), size: { width: mm(STREET[0]) } } },
text('title', '{titleText}', display(66, 'paper'),
{ ...at('container', 'top-left', 0, 26), size: { width: mm(STREET[0]) } })] } };
const plain = (id, more) => ({ id, numbered: false, span: 'column', ...more,
advancedDesign: { enabled: false }, fontSize: pt(26), lineHeight: pt(2 * LEAD) });
const headingStyles = [
{ id: 'portada', numbered: false, toc: false, span: 'page', advancedDesign: cover,
layout: { layoutType: 'single' }, footer: { elements: [] } },
plain('indice', { toc: false }), // the contents leave their own heading out
plain('presentacion', { breakBefore: { enabled: false } }), // gotcha: style-inherits-break
];
const headings = { fontFamily: 'Public Sans', fontWeight: 800, color: col('ink'),
levels: [ // parity 'any': a section opens the next page, whichever side it falls on
{ level: 1, numberingTemplate: '{1}', breakBefore: { enabled: true, parity: 'any' },
span: 'page', advancedDesign: section, marginBottom: pt(LEAD) }, // 9.7 mm under the band
{ level: 2, fontWeight: 700, fontSize: pt(13.5), lineHeight: pt(LEAD), marginTop: pt(0),
marginBottom: pt(0) }, // the line above an H2 is the paragraph's, or the resource's, gap
] };
El árbol de etiquetas toma sus elementos H1 y H2 de los encabezados del Markdown, y los marcadores del PDF salen de la misma lista, así que la cubierta, el índice, la carta y las dos secciones son de nivel 1, y los ladillos, de nivel 2. postext-pdf etiqueta cada texto del diseño de un título dentro de ese título. Por eso la banda de la cubierta lleva solo el título, y la entradilla y el nombre del ayuntamiento van debajo, como párrafos. Las bandas azul marino, el bordillo y la fila de contenedores son elementos de diseño, y el PDF marca las cajas y las imágenes de diseño como artefactos, así que no necesitan texto alternativo y el lector de pantalla se las salta.
#3 · Un índice con enlaces
const [NUMBER, GAP] = [6, 2.5]; // mm: the number column and the gap before a title
const toc = { levels: [{ level: 1, ...face('Public Sans', 700, 12), numberWidth: mm(NUMBER),
numberGap: mm(GAP), marginTop: pt(LEAD / 2) }, { level: 2, indent: mm(NUMBER + GAP) }],
unnumbered: { indent: mm(NUMBER + GAP) }, leader: { gap: mm(1.5) }, // Presentación: no number
// The page numbers, and the leaders with them, in the text face
pageNumber: { fontFamily: 'Atkinson Hyperlegible Next', fontWeight: 700, width: mm(8) } };
:::toc recoge los H1 y los H2 con el número de página que imprimen, y en el PDF cada una de sus once filas enlaza con el principio de su página. Las citas :ref de la página 3, «figura 1.1» y «tabla 1.1», y la de la página 4, «tabla 2.1», llevan a la figura y a las tablas. Los números de página van en la letra del texto, Atkinson Hyperlegible Next Bold, y las líneas de puntos toman la letra de los números, no la Public Sans de las entradas.
#4 · El orden de lectura, dibujado en la página
// An opener band's title, then each column from top to bottom; a float is read after the text
// that cites it, wherever it is painted. A paragraph continued in the next column stays one
// element, so its second part keeps its number.
const tagOf = (b) => ({ heading: `H${b.headingLevel ?? 1}`, callout: 'Div', listItem: 'LI',
resource: b.resourceBlock?.kind === 'table' ? 'Table' : 'Figure' })[b.type] ?? 'P';
function readingOrder(page) {
const ids = new Map(); // element → its number
const add = (block, box) => {
const key = block.id.replace(/-cont-\d+$/, ''); // fragments share their block's id
if (!ids.has(key)) ids.set(key, ids.size + 1);
return { n: ids.get(key), tag: tagOf(block), box, cont: key !== block.id };
};
const blocks = page.columns.flatMap((c) => c.blocks);
const title = blocks.find((b) => b.hidden && b.type === 'heading'); // drawn by the band
const flow = blocks.filter((b) => !b.hidden);
for (const float of page.floats ?? []) { // after the last block up to its place in the source
flow.splice(flow.findLastIndex((b) => b.contentIndex <= float.contentIndex) + 1, 0, float);
}
return [...(page.openerBand && title ? [add(title, union(page.openerBand.blocks
.filter((b) => b.kind === 'text')))] : []), ...flow.map((b) => add(b, b.bbox))];
}
Un lector de pantalla sigue las etiquetas. renderToPdf etiqueta primero el título de la banda y después cada columna de arriba abajo, y lee un flotante justo después del párrafo que lo cita, se pinte donde se pinte. Esta función repite ese orden para numerar los recuadros de la página 3, y el árbol de estructura del PDF da los mismos catorce elementos en el mismo orden. La figura y las dos tablas van en el flujo, con placement: { position: 'here' } y una línea ::resource, para que quien lee con la vista también las encuentre bajo la frase que las cita. El párrafo del vidrio que sigue en la segunda columna conserva un solo número, el 9, porque el PDF etiqueta las dos partes como un único párrafo.
#5 · Colores elegidos por su contraste
const palette = {
ink: '#14243a', // text: 15.6:1 on white
navy: '#173556', // bands: white type on it 12.5:1
signal: '#f2b705', // yellow: only on navy (6.9:1) or as a fill, never as text on white
tint: '#e8eef5', // header cells and boxes: ink on it 13.4:1
rule: '#aebccb', // table rules
muted: '#4a5a6e', // footer and colophon: 7.0:1 on white
paper: '#ffffff',
};
// every colour is linked to its palette entry by id
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// 'main-color' is the id the engine's default styles link to: any default left in them is navy
const colorPalette = [...Object.entries(palette), ['main-color', palette.navy]]
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const BIN = { amarillo: '#f2b705', azul: '#1f6fc5', verde: '#2e8b4a', marron: '#8a5a2f',
gris: '#6b7480' }; // the street bins' colours, for the pictograms and the swatches
const NAME = { amarillo: 'Amarillo', azul: 'Azul', verde: 'Verde', marron: 'Marrón', gris: 'Gris',
punto: 'Punto limpio' }; // a table cell never shows a colour alone: its name goes beside it
const cell = (text) => (text in NAME // an unknown colour ('none') draws an empty square
? `:swatch{color="${BIN[text] ?? 'none'}"} ${NAME[text]}` : text);
PDF/UA-1 no comprueba el color, pero WCAG 2.2 pide 4,5:1 entre el texto y su fondo. La tinta da 15,6:1 sobre blanco; la letra blanca, 12,5:1 sobre las bandas azul marino, y el gris del pie de página, 7,0:1. El amarillo da 1,8:1 sobre blanco, así que solo aparece sobre azul marino (6,9:1) y como relleno. Los pictogramas siguen el 3:1 que WCAG pide a los gráficos: blanco cuando llega a esa proporción sobre su contenedor y tinta sobre el amarillo. cell() escribe el nombre de cada contenedor junto a su muestra de color, y da al punto limpio un cuadrado vacío, así que ninguna indicación depende de distinguir colores.
La receta completa
// ═══ Postext Cookbook · Nº 039 · Accessible tagged PDF (PDF/UA) ═════════════════════
// https://postext.dev/en/cookbook/accessible-tagged-pdf
// Code: MIT · Text: original (CC BY 4.0) · Pictograms: generated in code (CC BY 4.0)
// Fonts: Atkinson Hyperlegible Next and Mono, Public Sans (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
buildDocumentWithFonts, renderPageToCanvas, registerResourceImage, parseTSV,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
const LANG = 'es'; // @lang: the language of the sample document (this recipe is Spanish only)
const RECIPE = 'accessible-tagged-pdf';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: text colours chosen for their contrast, and never a colour without its name
const palette = {
ink: '#14243a', // text: 15.6:1 on white
navy: '#173556', // bands: white type on it 12.5:1
signal: '#f2b705', // yellow: only on navy (6.9:1) or as a fill, never as text on white
tint: '#e8eef5', // header cells and boxes: ink on it 13.4:1
rule: '#aebccb', // table rules
muted: '#4a5a6e', // footer and colophon: 7.0:1 on white
paper: '#ffffff',
};
// every colour is linked to its palette entry by id
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// 'main-color' is the id the engine's default styles link to: any default left in them is navy
const colorPalette = [...Object.entries(palette), ['main-color', palette.navy]]
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const BIN = { amarillo: '#f2b705', azul: '#1f6fc5', verde: '#2e8b4a', marron: '#8a5a2f',
gris: '#6b7480' }; // the street bins' colours, for the pictograms and the swatches
const NAME = { amarillo: 'Amarillo', azul: 'Azul', verde: 'Verde', marron: 'Marrón', gris: 'Gris',
punto: 'Punto limpio' }; // a table cell never shows a colour alone: its name goes beside it
const cell = (text) => (text in NAME // an unknown colour ('none') draws an empty square
? `:swatch{color="${BIN[text] ?? 'none'}"} ${NAME[text]}` : text);
// #endregion
const TRIM = [210, 297]; // A4, the size residents print at home
const [TOP, FOOT, SIDE, LEAD] = [20, 22, 18, 15.5]; // margins in mm, not mirrored; leading in pt
const [PX, FIGURE, STREET] = [12, [83, 30], [174, 44]]; // drawings: px per mm, sizes in mm
const face = (fontFamily, fontWeight, size, more) => ({ fontFamily, fontWeight, fontSize: pt(size),
...more });
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });
const text = (id, content, style, placement) => ({ kind: 'text', id, content, align: 'left',
...style, placement }); // a heading's design wraps its text; the footer clips its own
// #region answer: the alt text and header cells the tags take from the resources
// renderToPdf writes a tagged PDF by default: the tag tree follows the headings, paragraphs,
// lists and boxes of the Markdown. Pictures and tables carry their own accessible text here.
El script.js compuesto funciona tal cual: pégalo como script de módulo en cualquier página o abre la receta en CodePen. Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)
Variantes
#Deja flotar la figura
Quita la colocación y la figura 1.1 flota al pie de la primera columna de la página 3. El PDF la sigue leyendo después del párrafo que la cita, así que el dibujo le mantiene el número 3 y el orden de las etiquetas no cambia.
- { id: 'contenedores', typeId: 'figure', kind: 'svg', placement: { position: 'here' },
+ { id: 'contenedores', typeId: 'figure', kind: 'svg',Errores frecuentes
Error frecuente
Un estilo de título hereda el salto de página de su nivel
Una entrada de headingStyles toma de su nivel de título todo lo que no fija, también breakBefore. Un índice o un colofón con estilo sobre un H1 tras un :::pagebreak hereda la paridad 'odd' y cae detrás de una página en blanco. Dale a ese estilo breakBefore: { enabled: false }. Estilos de título →
Error frecuente
Los archivos de Fontsource cubren letras, no símbolos
El kit incrusta el archivo latin de Fontsource de cada fuente y, cuando el texto los usa, su archivo latin-ext para č, ł, † y su archivo greek para α, χ (en una familia que lo tenga: Lora y Gelasio no), en pantalla y en el PDF. Símbolos como →, ≈, ✓ y ★ no están en ninguno de esos archivos y faltan en el PDF: dibújalos, escríbelos como matemáticas o elige una fuente cuyos archivos los tengan. Fuentes incrustadas en el PDF →
El código no puede validar su propio PDF, porque veraPDF funciona fuera del navegador. Descarga el archivo y ejecuta verapdf -f ua1 accessible-tagged-pdf.pdf; el PDF capturado para esta página pasa la validación. El validador no sabe si un texto alternativo describe su imagen, así que escucha también la guía con un lector de pantalla.
El colofón imprime la dirección web completa porque la guía se escribió para postext 1.4.1, en el que un enlace de Markdown imprimía sus palabras sin añadir ningún enlace al PDF. Desde postext 1.10 un enlace [texto](url) funciona en el PDF y se etiqueta como un elemento Link cuyo texto son las palabras enlazadas.
Créditos
- Receta
- Ignacio Ferro
- Texto
- Texto original, CC BY 4.0
- Fuentes
- Atkinson Hyperlegible Next (SIL OFL 1.1) · Atkinson Hyperlegible Mono (SIL OFL 1.1) · Public Sans (SIL OFL 1.1)
- Código
- MIT, como Postext
Editar este texto ↗ (se abre en una nueva pestaña)Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)


