# SW Text Headings — AI Agent Reference

**Module name:** SW Text Headings  
**Use this document when:** A user asks how to configure the SW Text Headings module (single/multi heading hero) — headings, display sizes, alignment, colors, spacing, module height, or background (theme color, gradient, image, video).

---

## Instructions for the AI Agent

- You do **not** have HubSpot access unless explicitly given. Answer only from this document (and other docs supplied by the user).  
- When the user wants to change something, direct them to the exact **tab → group → field** names listed in the Configuration Reference.  
- Some settings (Module Settings, Module Background Settings, Module Background Video) are **standard across all modules**. Rather than restating everything, this doc references **`docs/MODULE-SETTINGS-BACKGROUND-STANDARD.md`**. Follow that doc for in-depth details and troubleshooting.  
- If a user request cannot be satisfied by module fields, explain that clearly and direct them to add CSS in their theme’s `custom-styles.css` (or equivalent).  
- Support / bug issues: point to **https://smithworks.marketing/contact**.

---

## Support and Bug Reports

For support or bug reports related to SW Text Headings (or other Smithworks modules):
- **Contact:** [smithworks.marketing/contact](https://smithworks.marketing/contact)

---

## 1. Purpose and When to Use

Use **SW Text Headings** when you need:
- A hero or banner that displays **one or more headings** (repeater) with independent display sizes, colors, alignment, and responsive overrides.
- A **full-width background**: theme color, custom color, gradient, image (with per-breakpoint overrides), or **video background** (HubSpot Video, video file, external embed) with poster, overlay, and base color.
- Built‑in **module spacing**, max width options, and **minimum height** controls (including full viewport height) using the shared Module Settings standard.

Common use cases: simple hero banners, section separators with background imagery/video, callout rows with stacked headings, headings-only landing page intros.

---

## 2. Module Structure (Rendered Layout)

1. **Wrapper (`.sw-text-headings`)** — Full-width container; optional max width via Module Settings.
2. **Video/Image Background (optional)** —  
   - Image: set in Module Background Settings (Style tab).  
   - Video: enable background option = Video (Style tab), then configure Module Background Video group (Content tab; always last group).  
3. **Headings container** — Repeater outputs each heading in order, with optional custom class, color, alignment, padding overrides, and responsive display overrides.

No buttons, lists, or CTAs — this module is purely headings + background.

---

## 3. Configuration Reference

Tabs: **Content** and **Style**. Field names below match the HubSpot inspector.

### 3.1 Content Tab

| Group / Field | Purpose |
|---------------|---------|
| **Custom ID** | Optional override for the HTML `id` on the module wrapper. |
| **Custom Classes** | Space-separated classes appended to the wrapper. |
| **Headings** (repeater) | Each item includes: **Heading** (text/HTML), **Size** (semantic h1–h6/p), **Display Size** (visual scale), **Color** (theme/custom), **Custom Color** (when Color = Custom), **Align**, **Override Padding** (Top/Bottom px), **CSS Class**, **Override Text Alignment (Tablet)**, **Text Alignment (Tablet)**, **Override Text Alignment (Mobile)**, **Text Alignment (Mobile)**; **Override Tablet Display Size**, **Tablet Display Size**, **Override Mobile Display Size**, **Mobile Display Size**. Default Align: Center. Defaults render a single display‑4, centered heading reading “Add your heading here.” |
| **Module Background Video** | *Always the last Content-tab group.* Only visible when Style → Module Background Settings → Background Option = **Video**. Content tab: **Video Type** (HubSpot Video, Video from files, External Embed), **HubSpot Video**, **Video File**, **External Embed**, **Poster image**. Overlay, base color, and playback toggles (Autoplay, Loop, Muted, Plays Inline) are in **Style** tab when Video. Follow `docs/MODULE-SETTINGS-BACKGROUND-STANDARD.md` §10 for exact behavior. |

### 3.2 Style Tab

This module uses the shared standards for both Module Settings and Module Background Settings. Rather than duplicating the entire field list, reference the standard:

1. **Module Settings** (first Style group) — Spacing, Max Module Width, module height controls (XL + breakpoint overrides) with vertical alignment. These are exactly the “standard” fields defined in `docs/MODULE-SETTINGS-BACKGROUND-STANDARD.md` §10 (Module Settings table). There are **no module-specific extras** in this group.
2. **Module Background Settings** (second Style group) — Background Option (Theme Color, Custom Color, Gradient, Image, Video) plus all per-breakpoint image/position/repeat/overlay/base color controls. Exact list is in §10 of the standard. When Background Option = Video, overlay, base color, and playback toggles (Autoplay, Loop, Muted, Plays Inline) are here; configure the source and poster in the Content tab (Module Background Video group).

**Reminder:** When creating or editing this module’s fields, ensure the order matches the standard (Module Settings first, Module Background Settings second, Module Background Video last). See §9 of the standard for verification steps.

---

## 4. Common Tasks (“How Do I…?”)

| Task | Steps |
|------|-------|
| Change heading text | **Content** tab → **Headings** repeater → edit **Heading** field. |
| Adjust heading size/visual scale | Same repeater item → **Size** (semantic) and **Display Size** (visual). Use Display override fields for tablet/mobile. |
| Change heading color | **Color** (theme palette) or **Custom Color** (hex with opacity) in the repeater item. |
| Align or center headings | **Align** in each heading item (Left, Center, Right, Auto). Default: Center. |
| Change heading alignment on tablet/mobile | **Content** tab → **Headings** → **Override Text Alignment (Tablet/Mobile)** ON → **Text Alignment (Tablet/Mobile)**. |
| Add extra spacing above/below a heading | **Override Padding** toggle → set **Padding Top** / **Padding Bottom** (px). |
| Restrict max width of headings block | **Style** tab → **Module Settings** → **Max Module Width** (Default/Small/Large/Full/Custom). When Custom, set pixels. |
| Make hero full screen | **Style** tab → **Module Settings** → **XL Module Height** → **Minimum Height** = Full Screen (or set custom px). Use overrides for smaller breakpoints if needed. |
| Adjust vertical alignment | **Style** tab → **Module Settings** → **Vertical Alignment** per breakpoint (Top/Middle/Bottom). |
| Change spacing around module | **Style** tab → **Module Settings** → **Spacing** (margin/padding). |
| Set solid/gradient background | **Style** tab → **Module Background Settings** → **Background Option** = Theme Color / Custom Color / Gradient and configure associated fields. |
| Set image background | **Style** tab → **Module Background Settings** → **Background Option** = Image. Upload XL image, enable overrides for Desktop/Tablet/Mobile as needed. |
| Add video background | **Style** tab → **Module Background Settings** → **Background Option** = Video (overlay, base, playback toggles here). Then **Content** tab → **Module Background Video** (bottom) → choose Video Type and fill source; set Poster. |
| Ensure video covers area | Module handles this automatically (iframe cover sizing + HTML5 video `object-fit`). If you still see gaps, confirm Module Settings spacing/top padding and refer to FAQ item about video letterboxing. |
| Add custom CSS hook | **Content** tab → **Custom Classes** (applies to wrapper); or **Custom ID** for unique selectors. |

---

## 5. FAQ

**Q: My video background shows a bar or letterboxing. What should I check?**  
A: Confirm Style → Module Background Settings → Background Option = Video, and Content → Module Background Video is configured (Video Type and source). The module forces `padding-top: 0` and uses cover-style sizing for YouTube/Vimeo embeds and HTML5 video. If you still see a bar, verify the **section/row** wrapping the module has no padding/margin, or apply custom CSS to remove it.  

**Q: Video from files isn’t rendering.**  
A: The file field accepts array formats returned by HubSpot. Make sure you selected the video via the file picker (Content → Module Background Video → Video Type = Video from files → **Video from files**). After uploading or selecting, click “Insert.” The module resolves URL from `.url`, `.src`, `.href`, or string array entries. If the field is still empty, re-select the file.  

**Q: Where do I configure overlay/base colors for video backgrounds?**  
A: In **Content** tab → **Module Background Video** → **Background Color Overlay** and **Background Base Color**. These map to the module’s `::before` overlay (contrast) and fallback base color.  

**Q: Can I add body text or buttons?**  
A: No — SW Text Headings is headings-only. Use another module (e.g., SW Pillar Section, SW Simple Hero) if you need text, buttons, or media beyond the heading repeater.  

**Q: How do I remove top spacing entirely?**  
A: **Style** tab → **Module Settings** → **Spacing**. Set top/bottom padding and margins to zero. Module automatically removes top padding when Background Option = Video, but Section/Row padding in the page editor may still add space.  

**Q: Can headings include HTML (e.g., `<span>` for colored words)?**  
A: Yes. The field allows raw HTML (documented in the repeater help text). Use `<strong>`, `<em>`, `<span>` etc. Keep markup valid; script tags are not recommended.  

**Q: How do I make the module full-width but limit heading width?**  
A: Use **Module Background Settings** for full-width background. Then in **Module Settings** → **Max Module Width**, choose Small/Large/Custom to limit the inner heading container.  

---

## 6. When to Use Custom CSS

Use custom CSS when a request is not covered by module fields (e.g., special typography, drop shadows, responsive behavior beyond provided options).  
- Add CSS to your theme’s **`custom-styles.css`** (or theme-specific overrides file).  
- Target elements using the selectors in the appendix.  
- Prefer Custom ID / Custom Classes fields when you need one-off overrides.

---

## 7. Appendix: Key CSS Classes and Selectors

| Element | Selector(s) | Notes |
|---------|-------------|-------|
| Module wrapper | `.sw-text-headings` | Also gets `smithworks-module` and any Custom Classes; `id` = Custom ID if provided. |
| Inner container | `.sw-text-headings__inner` | Max width and alignment set here. |
| Headings container | `.sw-text-headings__headings` | Wraps heading repeater. |
| Individual heading | `.sw-text-headings__heading` | Includes semantic class `heading`; alignment classes added per field. |
| Video wrapper | `.sw-text-headings__video-wrap` | Absolutely positioned behind content when background option = video. |
| Embed wrapper | `.sw-text-headings__embed`, `.oembed_container`, `.embed_container`, `.iframe_wrapper` | Fill area (module enforces `padding: 0` and cover sizing). |
| HTML5 video | `.sw-text-headings__video-file` | Autoplay/muted/loop/playsinline. |
| Background modifiers | `.sw-text-headings--has-bg-image`, `.sw-text-headings--has-bg-video` | Applied when image or video background is active. |

Data attributes: The wrapper includes `data-instance="{{ name }}"` for targeting specific module instances if needed.

---

## 8. Document Version

- **Module reference:** SW Text Headings (smithworks-2025).  
- **Doc last updated:** 2026-02-02.  
- **2026-02-02:** Initial documentation reflecting video background support, shared Module Settings & Background standard, and video file/embed fixes.  
- Future updates: Whenever the module changes (fields, template behavior, CSS/JS), update this document and sync via `docs/PROCESS-MODULE-DOCUMENTATION-SYNC.md`.

**Developer Note:** When updating this file, sync to `SW AI Documentation.html`. See `docs/PROCESS-MODULE-DOCUMENTATION-SYNC.md`.