0
# Accessibility Features
1

2
Tagged PDF support, structure elements, and accessibility features for creating inclusive documents that comply with PDF/UA and accessibility standards.
3

4
## Capabilities
5

6
### Structure Elements
7

8
Create structured content with semantic meaning for screen readers and assistive technology.
9

10
```javascript { .api }
11
/**
12
 * Create structure element
13
 * @param type - Structure type
14
 * @param options - Structure options
15
 * @param children - Child structure elements
16
 * @returns Structure element
17
 */
18
struct(type: StructureType, options?: StructureOptions, children?: StructureElement[]): StructureElement;
19

20
/**
21
 * Add structure element to document
22
 * @param structElem - Structure element to add
23
 * @returns Document instance for chaining
24
 */
25
addStructure(structElem: StructureElement): PDFDocument;
26

27
type StructureType = 
28
  // Root elements
29
  | 'Document' | 'Part' | 'Art' | 'Sect' | 'Div'
30
  // Headings
31
  | 'H' | 'H1' | 'H2' | 'H3' | 'H4' | 'H5' | 'H6'
32
  // Paragraphs and text
33
  | 'P' | 'Span'
34
  // Lists
35
  | 'L' | 'LI' | 'Lbl' | 'LBody'
36
  // Tables
37
  | 'Table' | 'TR' | 'TH' | 'TD' | 'THead' | 'TBody' | 'TFoot'
38
  // Links and references
39
  | 'Link' | 'Annot' | 'Ruby' | 'RB' | 'RT' | 'RP'
40
  // Figures and media
41
  | 'Figure' | 'Formula' | 'Form'
42
  // Quotes and citations
43
  | 'Quote' | 'Note' | 'Reference' | 'BibEntry'
44
  // Code
45
  | 'Code'
46
  // Inline elements
47
  | 'Em' | 'Strong';
48

49
interface StructureOptions {
50
  /** Alternative text description */
51
  Alt?: string;
52
  /** Actual text content */
53
  ActualText?: string;
54
  /** Language specification */
55
  Lang?: string;
56
  /** Expansion of abbreviation */
57
  E?: string;
58
  /** Structure title */
59
  T?: string;
60
  /** Structure ID */
61
  ID?: string;
62
  /** Bounding box */
63
  BBox?: [number, number, number, number];
64
}
65
```
66

67
**Usage Examples:**
68

69
```javascript
70
// Enable tagged PDF
71
const doc = new PDFDocument({ tagged: true });
72

73
// Document structure
74
const docStruct = doc.struct('Document');
75

76
// Heading structure
77
const heading = doc.struct('H1', {
78
  Alt: 'Main document title',
79
  T: 'Introduction'
80
});
81

82
// Paragraph structure
83
const paragraph = doc.struct('P', {
84
  Lang: 'en-US'
85
});
86

87
// Add structures to document
88
doc.addStructure(docStruct);
89
docStruct.add(heading);
90
docStruct.add(paragraph);
91
```
92

93
### Marked Content
94

95
Mark content sections with semantic tags for accessibility.
96

97
```javascript { .api }
98
/**
99
 * Begin marked content sequence
100
 * @param tag - Content tag
101
 * @param options - Marking options
102
 * @returns Document instance for chaining
103
 */
104
markContent(tag: string, options?: MarkingOptions): PDFDocument;
105

106
/**
107
 * Mark structure content
108
 * @param tag - Structure tag
109
 * @param options - Structure options
110
 * @returns Document instance for chaining
111
 */
112
markStructureContent(tag: StructureType, options?: StructureMarkingOptions): PDFDocument;
113

114
/**
115
 * End marked content sequence
116
 * @returns Document instance for chaining
117
 */
118
endMarkedContent(): PDFDocument;
119

120
interface MarkingOptions {
121
  /** Properties dictionary */
122
  properties?: any;
123
  /** MCID (Marked Content ID) */
124
  MCID?: number;
125
}
126

127
interface StructureMarkingOptions extends MarkingOptions {
128
  /** Structure element reference */
129
  structElem?: StructureElement;
130
  /** Alternative text */
131
  Alt?: string;
132
  /** Actual text */
133
  ActualText?: string;
134
  /** Language */
135
  Lang?: string;
136
}
137
```
138

139
**Usage Examples:**
140

141
```javascript
142
// Mark heading content
143
doc.markStructureContent('H1', {
144
  Alt: 'Document title',
145
  Lang: 'en'
146
});
147
doc.fontSize(24)
148
   .text('Welcome to Our Guide', 100, 100);
149
doc.endMarkedContent();
150

151
// Mark paragraph content
152
doc.markStructureContent('P');
153
doc.fontSize(12)
154
   .text('This paragraph contains important information about accessibility.', 100, 150, {
155
     width: 400
156
   });
157
doc.endMarkedContent();
158

159
// Mark artifacts (decorative content)
160
doc.markContent('Artifact', {
161
  properties: { Type: 'Layout' }
162
});
163
doc.rect(50, 50, 500, 2)
164
   .fill('gray');  // Decorative line
165
doc.endMarkedContent();
166
```
167

168
### Document Metadata for Accessibility
169

170
Set document properties that enhance accessibility.
171

172
```javascript { .api }
173
// Document with accessibility metadata
174
const doc = new PDFDocument({
175
  tagged: true,
176
  lang: 'en-US',
177
  displayTitle: true,
178
  info: {
179
    Title: 'Accessible Document Example',
180
    Author: 'John Doe',
181
    Subject: 'Demonstrating PDF accessibility features',
182
    Keywords: 'accessibility, PDF/UA, tagged PDF'
183
  }
184
});
185
```
186

187
### Alternative Text for Images
188

189
Provide alternative text descriptions for images.
190

191
```javascript { .api }
192
// Image with alternative text
193
doc.markStructureContent('Figure', {
194
  Alt: 'A bar chart showing quarterly sales data with Q1 at $100k, Q2 at $150k, Q3 at $200k, and Q4 at $180k',
195
  ActualText: 'Sales Chart Q1-Q4'
196
});
197
doc.image('sales-chart.png', 100, 200, {
198
  width: 300,
199
  height: 200
200
});
201
doc.endMarkedContent();
202
```
203

204
### Accessible Tables
205

206
Create structured tables that are accessible to screen readers.
207

208
```javascript { .api }
209
// Table structure
210
doc.markStructureContent('Table');
211

212
// Table header
213
doc.markStructureContent('THead');
214
doc.markStructureContent('TR');
215

216
doc.markStructureContent('TH', {
217
  Alt: 'Product name column header'
218
});
219
doc.text('Product', 100, 300);
220
doc.endMarkedContent();
221

222
doc.markStructureContent('TH', {
223
  Alt: 'Price column header'
224
});
225
doc.text('Price', 200, 300);
226
doc.endMarkedContent();
227

228
doc.endMarkedContent(); // End TR
229
doc.endMarkedContent(); // End THead
230

231
// Table body
232
doc.markStructureContent('TBody');
233
doc.markStructureContent('TR');
234

235
doc.markStructureContent('TD');
236
doc.text('Widget A', 100, 320);
237
doc.endMarkedContent();
238

239
doc.markStructureContent('TD');
240
doc.text('$19.99', 200, 320);
241
doc.endMarkedContent();
242

243
doc.endMarkedContent(); // End TR
244
doc.endMarkedContent(); // End TBody
245
doc.endMarkedContent(); // End Table
246
```
247

248
### Accessible Lists
249

250
Create properly structured lists with semantic markup.
251

252
```javascript { .api }
253
// Ordered list structure
254
doc.markStructureContent('L');
255

256
// First list item
257
doc.markStructureContent('LI');
258
doc.markStructureContent('Lbl');
259
doc.text('1.', 100, 100);
260
doc.endMarkedContent();
261
doc.markStructureContent('LBody');
262
doc.text('First item in the list', 120, 100);
263
doc.endMarkedContent();
264
doc.endMarkedContent();
265

266
// Second list item
267
doc.markStructureContent('LI');
268
doc.markStructureContent('Lbl');
269
doc.text('2.', 100, 120);
270
doc.endMarkedContent();
271
doc.markStructureContent('LBody');
272
doc.text('Second item in the list', 120, 120);
273
doc.endMarkedContent();
274
doc.endMarkedContent();
275

276
doc.endMarkedContent(); // End L
277
```
278

279
### Accessible Links
280

281
Create links with proper structure and alternative text.
282

283
```javascript { .api }
284
// Link with structure
285
doc.markStructureContent('Link', {
286
  Alt: 'External link to company website'
287
});
288
doc.fillColor('blue')
289
   .text('Visit our website', 100, 150, {
290
     link: 'https://example.com',
291
     underline: true
292
   });
293
doc.endMarkedContent();
294

295
// Internal link
296
doc.markStructureContent('Link', {
297
  Alt: 'Link to appendix section'
298
});
299
doc.fillColor('blue')
300
   .text('See Appendix A', 100, 180, {
301
     goTo: 'appendixA',
302
     underline: true
303
   });
304
doc.endMarkedContent();
305
```
306

307
### Language Specification
308

309
Specify language for text content to assist screen readers.
310

311
```javascript { .api }
312
// Document-level language (in constructor)
313
const doc = new PDFDocument({
314
  tagged: true,
315
  lang: 'en-US'
316
});
317

318
// Paragraph with different language
319
doc.markStructureContent('P', {
320
  Lang: 'es-ES'
321
});
322
doc.text('Hola, mundo!', 100, 100);
323
doc.endMarkedContent();
324

325
// Back to English
326
doc.markStructureContent('P', {
327
  Lang: 'en-US'
328
});
329
doc.text('Hello, world!', 100, 120);
330
doc.endMarkedContent();
331
```
332

333
### Reading Order
334

335
Control the reading order of content for screen readers.
336

337
```javascript { .api }
338
// Create structure tree to define reading order
339
const docStruct = doc.struct('Document');
340

341
// Add content in logical reading order
342
const title = doc.struct('H1');
343
const intro = doc.struct('P');
344
const section1 = doc.struct('Sect');
345
const section1Title = doc.struct('H2');
346
const section1Text = doc.struct('P');
347

348
// Build hierarchy
349
docStruct.add(title);
350
docStruct.add(intro);
351
docStruct.add(section1);
352
section1.add(section1Title);
353
section1.add(section1Text);
354

355
doc.addStructure(docStruct);
356
```
357

358
## PDF/UA Compliance
359

360
Features for PDF/UA (Universal Accessibility) compliance.
361

362
```javascript { .api }
363
// PDF/UA compliant document
364
const doc = new PDFDocument({
365
  tagged: true,
366
  subset: 'PDF/UA',
367
  lang: 'en-US',
368
  displayTitle: true,
369
  info: {
370
    Title: 'Accessible Document'
371
  }
372
});
373
```
374

375
### Required Elements for PDF/UA
376

377
1. **Tagged structure**: Enable `tagged: true`
378
2. **Document title**: Set in `info.Title` and `displayTitle: true`
379
3. **Document language**: Set `lang` property
380
4. **Alternative text**: For all non-text content
381
5. **Logical structure**: Proper heading hierarchy
382
6. **Reading order**: Structured content tree
383

384
### Accessibility Validation
385

386
```javascript { .api }
387
// Check document compliance
388
doc.on('end', () => {
389
  console.log('Document structure:', doc.structureTree);
390
  console.log('Tagged content count:', doc.taggedContentCount);
391
});
392
```
393

394
## Best Practices
395

396
### Content Structure
397
- Use proper heading hierarchy (H1 → H2 → H3)
398
- Mark all content with appropriate structure types
399
- Provide alternative text for images and graphics
400
- Use semantic markup for lists, tables, and links
401

402
### Language and Text
403
- Specify document language
404
- Mark language changes within content
405
- Provide actual text for symbols or abbreviations
406
- Use descriptive link text
407

408
### Visual Design
409
- Ensure sufficient color contrast
410
- Don't rely solely on color to convey information
411
- Use proper heading styles
412
- Maintain logical reading order
413

414
### Testing
415
- Validate with accessibility checking tools
416
- Test with screen readers
417
- Verify tab order for form fields
418
- Check that all content is reachable
419

420
## Accessibility Standards
421

422
PDFKit supports compliance with:
423
- **PDF/UA-1**: Universal Accessibility standard
424
- **WCAG 2.1**: Web Content Accessibility Guidelines
425
- **Section 508**: U.S. federal accessibility requirements
426
- **EN 301 549**: European accessibility standard
427

428
These features ensure that PDFs created with PDFKit can be used effectively by people with disabilities and assistive technologies.