# SW Simple Hero — AI Agent Documentation

**Module path:** `smithworks-2025/sw-modules/SW Simple Hero.module` (smithworks portal)  
**Reference:** MODULE-SETTINGS-BACKGROUND-STANDARD.md, MODULE-SETTINGS-BACKGROUND-REFERENCE.md, MODULE-FIELD-LABELING-STANDARD.md, ALIAS-MAPPING-STANDARD.md  
**Last updated:** 2026.02.16

---

## 1. Overview

SW Simple Hero is a hero section with headings (repeater), rich text content, optional background (image, color, gradient, video), and up to two CTA buttons. It uses the standard **Module Settings** (Style tab, first group), **Module Background Settings** (Style tab, second group), and **Module Background Video** (Content tab, last group). Only **smithworks-2025** is the primary edited theme; other themes may adopt the module from there.

---

## 2. Content tab (order)

1. Custom ID, Custom Classes  
2. Headings (repeater: heading_text, size, display size, color, align, padding override, text shadow, MD/SM display overrides)  
3. Content Area (richtext), Content style, Text Color  
4. **Module Background Video** (last group) — visible only when Style → Module Background Settings → Background Option = **Video**. Video Type (HubSpot Video, Video from files, External Embed), source fields, Poster image. Overlay and base color for video are in the Style tab when Video is selected.  
5. CTA Buttons (alignment, button 1/2: add, text, link, style, icon)

---

## 3. Style tab (order)

1. **Module Settings** (first group)  
   - Spacing (margin/padding)  
   - Max Module Width (Default, Small, Large, Full Width, Custom); Max Module Width (px) when Custom  
   - XL Module Height: Minimum Height (Default, Custom Height, Full Screen), Height (px) when Custom, Vertical Alignment  
   - Override Desktop Height, Override Tablet Height, Override Mobile Height (toggle, then Minimum Height, Height (px), Vertical Alignment for each)

2. **Module Background Settings** (second group)  
   - **Background Option:** Theme Color, Custom Color, Gradient, Image, Video  
   - When **Theme Color** or **Custom Color:** theme color picker or custom hex + opacity  
   - When **Gradient:** gradient field  
   - When **Image:** XL Background Image group (overlay, base color, image, position, repeat, **background size**), then Override Desktop / Tablet / Mobile Background Image groups (override toggle, then image, position, size, etc.)  
   - When **Video:** Overlay, base color, and playback toggles (Autoplay, Loop, Muted, Plays Inline) appear here; video source and poster are in Content → Module Background Video

3. Text Box Settings (max width, column widths, padding, alignment, background color)

---

## 4. Background image: size, position, repeat (important for AI and users)

When **Background Option = Image**, each responsive image group (XL and, when overridden, Desktop/Tablet/Mobile) includes **Background Size**, **Background Position**, and **Background Repeat**. These map directly to standard CSS. An AI agent is expected to understand standard CSS `background-size`, `background-position`, and `background-repeat`; below is what the module exposes and how it maps.

### 4.1 Background Size

**Field label:** Background Size (XL); per-breakpoint when override is enabled.

**Choices in the module:**

| Choice (label)   | Value (stored) | CSS equivalent | When to use |
|------------------|----------------|----------------|-------------|
| **Cover**        | `cover`        | `background-size: cover` | Image scales to cover the whole area; may crop. No letterboxing. Default for XL. |
| **Contain**      | `contain`      | `background-size: contain` | Image scales to fit inside the area; may show letterboxing (empty bands). |
| **Stretch to Fill** | `100% 100%` | `background-size: 100% 100%` | Image stretched to exact width and height of area; can distort aspect ratio. |
| **Natural Size** | `auto`         | `background-size: auto` | Image at intrinsic size; may tile or show once depending on Background Repeat. |

**Reference:** For full CSS behavior (e.g. two-value form, keywords), see [MDN: background-size](https://developer.mozilla.org/en-US/docs/Web/CSS/background-size).

### 4.2 Background Position

**Field label:** Background Position (XL); Desktop/Tablet/Mobile Background Position when override is enabled.

**Named choices (one value stored, maps to CSS keyword pair):**  
Top Left (`left top`), Top Center (`center top`), Top Right (`right top`), Middle Left (`left center`), Middle Center (`center center`), Middle Right (`right center`), Bottom Left (`left bottom`), Bottom Center (`center bottom`), Bottom Right (`right bottom`).

**Custom (from edge):** When user selects **Custom (from edge)**, additional fields appear: Custom Horizontal Edge (Left/Right), Horiz Offset, Horiz Unit (px/%); Custom Vertical Edge (Top/Bottom), Vert Offset, Vert Unit (px/%). These build a CSS position from one edge (e.g. `left 20px top 10%`).

**Reference:** For full CSS syntax (lengths, percentages, multiple backgrounds), see [MDN: background-position](https://developer.mozilla.org/en-US/docs/Web/CSS/background-position).

### 4.3 Background Repeat

**Field label:** Background Repeat (in each image group).

**Choices:**

| Label                  | Value       | CSS equivalent |
|------------------------|------------|----------------|
| No Repeat             | `no-repeat`| `background-repeat: no-repeat` |
| Tile                  | `repeat`   | `background-repeat: repeat` |
| Repeat Horizontally   | `repeat-x` | `background-repeat: repeat-x` |
| Repeat Vertically     | `repeat-y` | `background-repeat: repeat-y` |

**Reference:** [MDN: background-repeat](https://developer.mozilla.org/en-US/docs/Web/CSS/background-repeat).

### 4.4 Directing users

- **“How do I make the background image cover the whole hero?”** → Style → Module Background Settings → Background Option = Image → XL Background Image (or the override group for that breakpoint) → **Background Size** = **Cover**.
- **“How do I avoid cropping and show the whole image?”** → **Background Size** = **Contain** (may add letterboxing).
- **“How do I move the focal point of the image?”** → **Background Position** (named or Custom from edge).
- **“How do I tile the image?”** → **Background Repeat** = **Tile**.

---

## 5. Field paths (canonical)

- **Module Settings:** `module.styles.module_settings`  
  - `spacing`, `max_module_width`, `max_module_width_custom`, `module_height_xl_group` (mode, height, vertical_align), `module_height_lg_group`, `module_height_md_group`, `module_height_sm_group`.
- **Module Background Settings:** `module.styles.module_background_settings`  
  - `background_option`; when Image: `background_image_xl_group` (and `background_image_lg_group`, etc.) with `background_image_xl`, `background_position_xl`, `background_repeat_xl`, `hero_background_size`, overlay, base color; custom position fields when position = custom.
- **Module Background Video:** `module.background_video_settings` (Content)  
  - `video_source_type`, `hubspot_video`, `video_file`, `embed_field`, `poster_image`. Visible when `module.styles.module_background_settings.background_option` = video.
- **When Video (in Module Background Settings):** `background_color_overlay_video`, `background_base_color_video`, `video_autoplay`, `video_loop`, `video_muted`, `video_plays_inline`.
- **Alias mapping:** Old path `style.general_banner_settings` (e.g. hero height) is aliased to `module_settings`. Old image/position/size paths under `style.background_image` are aliased to the new `module_background_settings.background_image_*_group` paths. Template supports fallback when aliases are missing.

---

## 6. Template and CSS notes

- **Module Settings spacing:** Applied to the **module wrapper** (`.sw-hero`). Margin and padding from Module Settings > Spacing output on `.sw-hero`.
- **Text Box Settings spacing:** Applied to the **text box** only (`.content-wrapper`). Text Box Settings > Text Box Padding controls margin and padding on the content wrapper. Defaults: 0 margin, 20px padding.
- **Height modes:** `default` (no minimum), `custom` (use height px), `full` (100vh minus header). Full uses CSS variable `--sw-hero-header-height`.
- **Cascade:** When Override Desktop/Tablet/Mobile is **off**, that breakpoint inherits height (and mode) from the next larger breakpoint.

---

## 7. Background width vs. content width (important for AI and users)

- **Background:** The hero background (image, color, gradient, video) is **full-bleed** — it fills the width of the **section** that wraps the module. There is no module setting to make the background “stay inside” the module’s Max Module Width.
- **Content:** The hero **content** (text column + image column) is constrained by **Module Settings → Max Module Width** and centered. So on a full-width section, the content can be e.g. 1000px centered while the background spans the whole viewport.
- **To contain the background:** If the user wants the background (e.g. the hero image) contained within a certain width (e.g. 1800px), they must **set a width on the outer section** that wraps the SW Simple Hero module — for example, in the page template or section/section group settings, set the section’s max-width (and margin auto to center). The module then sits inside that section; the background will be contained within the section’s width. Do not tell users there is a module-level option for this; the solution is section-level.

---

## 8. References

- MODULE-SETTINGS-BACKGROUND-STANDARD.md  
- MODULE-SETTINGS-BACKGROUND-REFERENCE.md  
- MODULE-FIELD-LABELING-STANDARD.md  
- ALIAS-MAPPING-STANDARD.md  
- SW Text Headings (reference implementation for Module Settings / Module Background Settings / Module Background Video)

---

**Changelog (AI doc):**  
- 2026.02.04: Fixed §6 spacing: Module Settings spacing on module wrapper (.sw-hero); Text Box Settings spacing on content wrapper (.content-wrapper). Added video playback toggles (Autoplay, Loop, Muted, Plays Inline) to §3 and §5.
- 2026.02.03: Full AI doc update. Added §4 Background image: size, position, repeat (Cover, Contain, Stretch to Fill, Natural Size; position named + custom; repeat options); pointed to MDN for standard CSS. Updated Content/Style order to current (Module Background Video last; Module Background Settings second). Removed Phase 1/2 wording; doc now reflects current module structure. §7 Background width vs. content width retained.