Document components
Use a document component when a person needs to compose a formatted document within a service, rather than answer a short text question. It provides an editor with configurable writing and formatting tools.
This is a specialised component. For ordinary explanations or short answers, use information or text components instead. A document component needs careful decisions about storage, allowed editor features, content limits and review.
Design the document task first
State what the person is writing, why it is needed, and what a satisfactory document includes. Provide a template or structured prompts where possible; a blank rich-text editor can be difficult to use.
flowchart LR
A[Define the document purpose] --> B[Choose storage method]
B --> C[Expose only necessary editor tools]
C --> D[Set clear content limits]
D --> E[Test writing, review and downstream use]Use headings and prompts outside the editor for the essential structure. Do not rely on formatting choices alone to guide a person through a complex document.
Choose a storage method
A document can be stored as service data or as an uploaded HTML file. Storing as service data is appropriate for text-only documents within the relevant size limit. File storage supports larger documents and, where enabled, embedded images.
Choose file storage only when it is necessary. Embedded images increase privacy, accessibility, size and downstream-processing considerations. Set a realistic size limit and test it against every storage, export and integration destination.
Limit the editor to what is needed
The editor toolbar can expose many formatting features. Provide only the tools that help the person create the required document. A focused set—headings, basic emphasis, lists and links—is easier to learn and creates more consistent content than every available formatting option.
Avoid typography, colour and layout controls unless the document’s purpose needs them. Do not let visual styling become the only way meaning is communicated.
Set content limits and validation
Use character or word limits where the receiving process has a real constraint. Explain the limit before the person begins and distinguish a suggested writing length from a hard maximum.
If the document is required only for a particular route, use conditional validation or a page condition as appropriate. Give error messages that describe what needs to be added, not just that the document is invalid.
Review, privacy and downstream use
Review pages should make it clear that the document exists and provide an appropriate way to view it. Do not render confidential document content in summaries, notifications or logs unless that is intentionally designed and protected.
Test a realistic document with headings, lists, links, long text, empty content, and any enabled image upload. Check accessibility of the rendered document and that downstream actions preserve the content you expect.