Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Context: PF-64 Document Templates — create/edit flow at Settings → Template Settings → Documents.
Last updated: 2026-02-17 This document summarizes recommendations to improve the document template creation flow, based on a hands-on run-through and code review.

​
What Works Well

  • Clear navigation: Settings → Template Settings → Documents tab → Create Template is easy to find.
  • Breadcrumbs: Template Settings → Documents → New Document Template (and back) are correct.
  • Skeleton loading: Editor uses <Skeleton /> while loading existing template (no return null).
  • Submit feedback: Create Template button shows loading state (isSubmitting); success toast and redirect to list.
  • Sections: Default policy sections (Purpose, Scope, Definitions, etc.) and drag-and-drop reorder (SectionEditor) are useful.
  • Contextual help: TemplatesSettingsPage explains the difference between document templates, forms, and workflow templates with links.

​
Recommendations for Improvement

​
1. ✅ Help content — IMPLEMENTED

Tooltips and FormFieldWithHelp have been added to DocumentTemplateEditor.tsx for Template Type, Status, Section Numbering, and Page Orientation. A QuickTip at the top of the editor guides first-time users.

​
2. ✅ Error handling — IMPLEMENTED

sanitizeErrorMessage(error) is used in the onSubmit catch block of DocumentTemplateEditor.tsx so user-facing errors are actionable without exposing internals.

​
3. ✅ Letterhead empty state — IMPLEMENTED

When no organization letterheads exist, a FormDescription with a link to /settings/templates?tab=letterheads guides users to create one.

​
4. ✅ Sections hint — IMPLEMENTED

A QuickTip at the top of the Create/Edit page tells users to add sections and that they can reorder by dragging.

​
5. ✅ Save / Create button visibility — IMPLEMENTED

A sticky action bar keeps Cancel and Create Template buttons visible on scroll in DocumentTemplateEditor.tsx.

​
6. ✅ Preview before save — IMPLEMENTED

A “Preview” action is available via useGenerateTemplatedPdf so users can preview how the template renders before saving.

​
7. Accessibility — REMAINING

Current: Back button has aria-label="Go back". Form fields use semantic labels. Section editor uses drag-and-drop (consider keyboard reorder). Remaining work:
  • Ensure SectionEditor drag-and-drop has full keyboard support (e.g. focus management, arrow keys to move, Enter to reorder) per @dnd-kit best practices so the template is usable without a mouse.
  • Confirm all comboboxes (Template Type, Status, Letterhead, Section Numbering, Page Orientation) have correct aria-describedby when help text or tooltips are added.

​
8. Default sections for “Policy” — REMAINING

Current: The editor prefills a set of sections (Purpose, Scope, Definitions, etc.) for new templates. That’s helpful. Remaining work:
  • Document or make explicit that these defaults apply when Template Type is “Policy.” If other types (Letter, Procedure) get different default sections in the future, consider type-specific defaults and a short note in the UI (e.g. “Default sections for Policy templates”).

​
Implementation priority (remaining items only)

PriorityItemEffortImpact
MediumSectionEditor keyboard accessibilityMediumMedium
LowerType-specific default sectionsMediumLow

​
References

  • PF-64: Organization Document Templates spec
  • AGENTS.md: Help Content Requirements, Error Handling Patterns
  • Quick Reference: sanitizeErrorMessage(error), FormFieldWithHelp, InfoTooltip, QuickTip
  • Templates UI: src/platform/templates/pages/DocumentTemplateEditor.tsx, TemplatesSettingsPage.tsx, SectionEditor.tsx