> ## 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.

# Document Template UX & Implementation Recommendations

> This document summarizes recommendations to improve the document template creation flow, based on a hands-on run-through and code review.

**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)

| Priority | Item                                 | Effort | Impact |
| -------- | ------------------------------------ | ------ | ------ |
| Medium   | SectionEditor keyboard accessibility | Medium | Medium |
| Lower    | Type-specific default sections       | Medium | Low    |

***

## 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`