Allow editors to add or remove subsection callout styling

[mikec-ai]

Summary

• allow editors to add or remove callout-box styling from a subsection
• explain the existing Step 1 portrait placement behavior for recognized callouts
• clarify that reimport uses styling from the source document
• add regression coverage for editing, rendering, navigation, Word export, and reimport

Why

Subsections already stored callout state and Builder already rendered both callout and regular subsections, but the edit screen submitted the existing value through a hidden field. Editors therefore could not correct callout styling without changing and reimporting the source document or requesting engineering support.

This exposes the existing state as an intentional editing choice without redesigning callout recognition or rendering.

Closes #772.

User impact

Editors can now apply or remove callout styling while preserving the subsection's name, heading level, content, order, anchor, page-break setting, and table-of-contents behavior.

Recognized Step 1 callouts retain their existing portrait right-margin placement. Reimport remains source-authoritative, and the previous manual state remains available in the archived revision.

Validation

• 1,577 tests passed before final rebase
• 27 focused subsection-edit and reimport tests passed after rebasing onto the latest main
• Django system checks passed
• Black and isort checks passed
• git diff --check passed
• independent code review found no actionable issues

Visual evidence

Before, the subsection edit screen did not expose the stored callout state.

After this change, it presents a USWDS tile checkbox with placement and reimport guidance.

[mikec-ai]

@benbrasso maybe we can use this one as the test case for Jana and Yasmine to review in dev?

[benbrasso]

@mikec-ai, yes, agreed.

Separately, review the following guidance in the Builder Wiki on when to use callout boxes and determine if wording adjustments are needed in the new component in NOFO Builder:

---

When should I use a callout box (or callout component)?

Callout boxes are best for short, high-priority content that applicants need to notice quickly. Common uses include:

• Contact and support information
• Reminders and post-award requirements
• Action-oriented information that stands on its own

Avoid using callout boxes for long narrative content or detailed policy explanations — those belong in the body of the NOFO. The goal is to surface information that applicants might otherwise miss, not to highlight everything.

Adding a callout box in NOFO Builder

Select Configure section on the relevant section, then select Add subsection where you want the callout box to appear. Check the Is callout box checkbox and enter your content.

Importing a callout box from Word

NOFO Builder automatically recognizes 1x1 tables in your Word document as callout boxes on import. Make sure any content you want displayed as a callout box is inside a 1x1 table in Word before importing.

[benbrasso]

@mikec-ai I'd also consider positioning it immediately before the page break component. I.e., semantically, it probably makes sense to identify the subsection, then decide on decorative options.

Also, take a look in prod now, where is the current callout box positioned on the edit subsection page. Ideally, we'd be consistent with its position on the edit pages.

[benbrasso]

Ooooh, now I see why you selected that position for the checkbox

---

[benbrasso]

Well, here's the edit page when "adding a new subsection"

---

[mikec-ai]

Addressed the callout guidance and placement feedback in 428bd932:

• moved the callout control after the subsection name and heading level, immediately before the page-break option
• added the Wiki guidance that callouts are for short, high-priority content and should not be used for long narrative or detailed policy content
• retained the Step 1 placement and reimport behavior notes

Validation: 1,584 full-suite tests and 27 focused edit/reimport tests passed.

Updated screenshot:

[mikec-ai]

@benbrasso see the last comment about the update made

[benbrasso]

@mikec-ai any reason we don't want to use the same component and content that we already have built? I think the help text isn't needed. A lot of information creates unnecessary noise and cognitive load.

---

[mikec-ai]

@benbrasso reused the same component and content now

[benbrasso]

approved to merge