SW Simple Header — AI Agent Reference

Module name: SW Simple Header
Module path: smithworks-2025/sw-modules/SW Simple Header.module (smithworks portal); also in master sw-theme-elements
Reference: MODULE-FIELD-LABELING-STANDARD.md, MODULE-SETTINGS-BACKGROUND-STANDARD.md, ALIAS-MAPPING-STANDARD.md
Last updated: 2026.02.27

Use this document when: The user asks about the SW Simple Header HubSpot module—what it does, how to configure logo, navigation, buttons, mobile menu, announcement bar, top bar, Simple Link style, Menu position (In header vs Below header), spacing when the menu is in the header, or what to do when the menu is too large to fit; how to link text in the top bar; how to change top bar icon color (including when Simple Link Font color doesn't work); how to change the menu dropdown arrow icon; or gradient buttons.

================================================================================
1. OVERVIEW
================================================================================

SW Simple Header is a global header module with logo, navigation menu, optional CTA buttons, and a mobile hamburger drawer. It includes an announcement bar (optional, slides down from top) and top bar (optional, one or two columns for buttons, text, or rich text) above the main header content. It supports Menu position: In header (menu in the same row as logo and buttons) or Below header (menu in a full-width row under the header). It uses standard Module Settings (Style tab) for wrapper spacing and max width, Module Background Settings for background (color, custom, gradient, image, video), and Module Background Video (Content tab) when Background Option = Video.

================================================================================
2. CONTENT TAB (order)
================================================================================

1. Custom ID, Custom Classes
2. Logo — Logo Link, Logo Image (override), Alt Text. Uses brand kit logo by default.
3. Navigation — Menu (HubSpot menu), Max Dropdown Levels (1–4)
4. Buttons (repeater) — Button Text, Button Link, Button Style (Primary, Secondary, Simple Link, etc.), Button Size (hidden when Button Style = Simple Link), Add Icon, Show in header on mobile, Show in mobile menu, Icon (when Add Icon on). Root-level repeater; alias from legacy buttons_group.cta_button_items.
5. Announcement Bar — Enable toggle; Rich text content; Delay (seconds); Hide Duration (hours, minutes). When enabled, bar slides down from top after delay; close button hides site-wide for duration (localStorage).
6. Top Bar — Top Bar Layout (None | One Column | Two Columns). When One or Two: Primary Column (Content Type: Buttons, Text Repeater, or Rich Text; Alignment; Show on mobile; column width when two columns); Secondary Column (when Two Columns). Buttons use repeater; Text Repeater uses text items; Rich Text uses rich text field. Button Style = Simple Link uses shared Simple Link Font from Style tab (Top Bar Style).
7. Mobile Menu Icon — Icon (override), Icon width (px). Defaults to brand favicon; used in drawer header.
8. Module Background Video — Visible when Style → Module Background Settings → Background Option = Video. Video Type, source fields, Poster Image. Overlay and base color in Style tab when Video.

================================================================================
3. STYLE TAB (order)
================================================================================

1. Module Settings — Spacing (margin/padding on module wrapper; default 25px padding), Max Module Width (Default/Small/Large/Full Width/Custom), Max Module Width (px) when Custom.
2. Module Background Settings — Background Option (Theme Color, Custom Color, Gradient, Image, Video).
3. Header Behavior — Header Position (Sticky | Static); Use mobile menu at XL, at Desktop (LG), at Tablet (MD).
4. Menu Colors — Main menu color/hover, Hamburger icon color/hover, Submenu background/color/hover. Use Menu Colors for link colors (including hover). The font fields (Menu Fonts, Simple Link Font) include a color picker, but that does not control hover state—only Menu Colors does.
5. Menu Fonts — XL + Override Desktop/Tablet/Mobile. Font (main level), Font (sub levels) per breakpoint. Font object includes size. Because these are link fonts, set link colors (including hover) in Menu Colors, not in the font fields.
6. Menu Layout — Menu Alignment (left/center/right), Menu Position (In header | Below header), Menu Section Spacing (when Below header), Menu section & mobile background.
7. Announcement Bar Style — Visible when Top Bar Layout ≠ None or Announcement Bar enabled. Background Option (Theme Color, Custom Color, Gradient); Theme Color (default: Light); Override Border Radius; Height (px) 40–300; Padding (px); Max Width (Full | Custom). Bar has 10px margin bottom; 10px spacing from left/right edges (width calc(100% - 20px), margin auto). When closed, negative margin = height + 10px so bar and gap are hidden.
8. Top Bar Style — Visible when Top Bar Layout = One or Two Columns. Background Option (Theme Color, Custom Color, Gradient); Theme Color (default: Dark); Font Color (default: #FFFFFF); Spacing (margins 0, padding 10px 25px default); Simple Link Font — Font (XL + Override Desktop/Tablet/Mobile). Font object includes size and color picker; the font color does not control hover. Top bar links inherit from the top bar's font color. Applies to all Simple Link buttons in the top bar. Only affects buttons when Button Style = Simple Link.

================================================================================
4. SIMPLE LINK BUTTONS AND TEXT REPEATERS (top bar)
================================================================================

Linking text in the top bar: You cannot link plain text directly. Use either:
- Simple Link buttons (Content type = Buttons, Button style = Simple Link) — recommended for individual links.
- Rich text (Content type = Rich text) — add links via the rich text editor's link tool for inline links in paragraphs.
Text Repeater items are plain text only; they are not clickable.

Simple Link style: When Button Style = Simple Link, Button Size is hidden. Font and size come from Style → Top Bar Style → Simple Link Font (shared for all Simple Link buttons in both columns). Link color inherits from the top bar; the font field's color picker does not control hover—use Menu Colors for link colors if needed.

Margins (consistent spacing between items):
- Right alignment: margin-left 20px on all items except first
- Left alignment: margin-right 20px on all items except last
- Center alignment: margin-left and margin-right 10px on all items
- Mobile (≤767px): margin-left and margin-right 10px on all items

Same margin logic applies to Text Repeater items in the top bar.

4a. TOP BAR ICON COLOR — WHEN SIMPLE LINK FONT COLOR DOESN'T WORK

Simple Link Font (Style → Top Bar Style) sets color for both text and icons when Button Style = Simple Link. If the icon does not turn white (or the desired color):

- If the icon is an UPLOADED IMAGE (SVG/PNG): The module cannot recolor it. Upload a white (or desired color) version of the icon and select it in the button's Icon picker.

- If the icon is a BUILT-IN ICON (Font Awesome from the icon picker): Add custom CSS to force the color. Example (Site header HTML or theme CSS override):

  .sw-site-topper__top-bar .sw-site-topper__btn--simple-link i,
  .sw-site-topper__top-bar .sw-site-topper__btn--simple-link svg {
    color: #ffffff !important;
    fill: #ffffff !important;
  }

Replace #ffffff with the desired color. Publish the theme/settings and hard-refresh the page.

================================================================================
5. SPACING CONSTRAINTS WHEN MENU IS IN THE HEADER (important for AI and users)
================================================================================

When Menu position is In header, the navigation menu sits in the SAME SINGLE ROW as the logo (left) and the buttons (right). That row has fixed horizontal space: it is constrained by Module Settings → Spacing (padding on the module wrapper), Max Module Width, and the fact that logo + menu + buttons must all fit in one line. There is NO separate spacing field for the menu area when the menu is in the header—only the overall module spacing applies to the whole header block.

Implications:
- Logo has a max width (e.g. 50% of its container) and the menu lives in the middle. If the menu has many items or long labels, it can overflow or wrap. The module does not provide a dedicated "menu row padding" or "menu max width" when In header.
- Reducing wrapper padding (Style → Module Settings → Spacing) can free a little space for the menu row but also makes the whole header tighter.
- Max Module Width constrains the total width of the header; a narrower max width makes the menu area smaller.

When the user says the menu doesn't fit, looks cramped, or wraps badly with Menu position = In header, use the options in section 6 below.

================================================================================
6. WHAT TO DO WHEN THE MENU IS TOO LARGE TO FIT IN THE HEADER
================================================================================

If the menu has too many items or long labels to fit comfortably in the header row (Menu position = In header), there are two main options. Do NOT tell users there is a "menu-only" spacing control when the menu is in the header; there is not.

OPTION A: Move the menu below the header
- Style → Menu Layout → Menu Position = Below header.
- The menu moves to a full-width row below the logo/buttons row. That row has:
  - Menu Section Spacing (margin and padding for the menu row only), visible when Menu position = Below header.
  - Menu section & mobile background (Same as header, Theme Color, or Custom Color) for the menu row and mobile drawer.
- The desktop menu can then use the full width, wrap naturally, and align left/center/right via Menu Alignment.

Use this when: The user wants to keep all nav items visible on desktop in a horizontal bar and is okay with a two-row header.

OPTION B: Use the mobile menu at larger breakpoints
- Style → Header Behavior:
  - Use mobile menu at XL (1200px+)
  - Use mobile menu at Desktop (LG) (992–1199px)
  - Use mobile menu at Tablet (MD) (768–991px)
- When one of these is ON, at that breakpoint the horizontal nav is hidden and the hamburger menu (drawer) is shown instead. The menu items then appear in the drawer, not in the header row.
- The user can leave Menu position = In header but effectively "free" the header row from the menu at XL, or at Desktop, or at Tablet.

Use this when: The user wants to keep a single-row header (or below-header menu row) but is okay with the hamburger/drawer at 1200px+, or 992px+, or 768px+, so the menu doesn't have to fit in the constrained space at those sizes.

Summary for AI:
- "Menu doesn't fit in the header" / "Menu is cramped" → Offer Option A (Menu position = Below header) and/or Option B (Use mobile menu at XL/Desktop/Tablet). Explain there is no menu-only spacing when In header.
- "I want the menu in a full-width row" → Menu Position = Below header. Then set Menu Section Spacing and Menu section & mobile background as needed.
- "I want hamburger on desktop so the top row isn't crowded" → Header Behavior → Use mobile menu at XL (or at Desktop/LG, or at Tablet/MD) = ON.

================================================================================
7. FIELD PATHS (canonical)
================================================================================

- Module Settings: module.styles.module_settings — spacing, max_module_width, max_module_width_custom.
- Header Behavior: module.styles.header_behavior — header_position, mobile_menu_at_xl, mobile_menu_at_lg, mobile_menu_at_md.
- Menu Layout: module.styles.menu_layout — menu_alignment, menu_position, menu_section_spacing (when menu_position = below_header), menu_section_background_option, menu_section_background_theme_color, menu_section_background_custom.
- Menu Colors: module.styles.menu_color_settings (use for link colors including hover). Menu Fonts: module.styles.menu_font_settings (xl_menu_fonts_group, override_desktop/tablet/mobile_group; font object includes size).
- Buttons: module.cta_button_items (root); alias from module.buttons_group.cta_button_items. Template uses root first, then legacy.
- Announcement Bar: module.announcement_bar — announcement_enabled, announcement_content, announcement_delay_seconds, announcement_hide_duration_hours, announcement_hide_duration_minutes.
- Top Bar: module.top_bar — top_bar_layout, primary_column (primary_content_type, primary_column_alignment, primary_buttons, primary_text_items, primary_rich_text), second_column (when two columns).
- Announcement Bar Style: module.styles.announcement_bar_style — announcement_background_option, announcement_background_color, announcement_height, announcement_padding, announcement_max_width, etc.
- Top Bar Style: module.styles.top_bar_style — top_bar_background_option, top_bar_background_color, top_bar_font_color, top_bar_spacing, top_bar_simple_link_font (xl_font_group.font, override groups; no Link Colors field—links inherit from top bar).
- Module Background Settings / Module Background Video: Same pattern as other SW modules.

================================================================================
8. TEMPLATE AND CSS NOTES
================================================================================

- Gradient buttons: Individual CTA buttons (header or top bar) cannot be styled with gradients via module fields. Gradients are only available for Module Background Settings (section backgrounds). For a gradient button, use custom CSS with a unique Custom Class on the module.

- Module Settings spacing applies to the module wrapper (.sw-simple-header). When Menu position = Below header, Menu Section Spacing applies only to the menu row (.sw-simple-header__menu-section).
- Announcement bar: .sw-site-topper__announcement-wrapper, .sw-site-topper__announcement-wrapper--closed, .sw-site-topper__announcement. CSS variable --sw-site-topper-announcement-height for slide animation. Margin-bottom 10px; when closed, margin-top calc(-height - 10px).
- Top bar: .sw-site-topper__top-bar, .sw-site-topper__top-bar-row, .sw-site-topper__top-bar-col, .sw-site-topper__buttons, .sw-site-topper__btn--simple-link, .sw-site-topper__text-items, .sw-site-topper__text-item. Alignment modifiers: --align-left, --align-center, --align-right.
- Data attributes: data-menu-position (in_header | below_header), data-menu-alignment, data-mobile-menu-at-xl, data-mobile-menu-at-lg, data-mobile-menu-at-md, data-position (sticky | static).
- Modifiers: .sw-simple-header--sticky, .sw-simple-header--menu-below (when Menu position = Below header). Nav wrap alignment: .sw-simple-header__nav-wrap--left, --center, --right.
- Mobile drawer uses the same padding as the header (from Module Settings) so the drawer icon and close button align with the header row when closed.

================================================================================
9. MENU DROPDOWN ARROW (not configurable via module)
================================================================================

The arrow/caret next to menu items that have submenus is NOT a module field. It is hardcoded in the template as a Unicode character (▾) inside .sw-simple-header__menu-caret.

To change it:
1. The HTML is in the module template (module.html); the character or element can be edited in a theme override/fork.
2. Or use CSS to replace/hide it:
   - Hide the default: .sw-simple-header__menu-caret { display: none; }
   - Add a custom icon via ::after on the parent: .sw-simple-header__menu-link--toggle::after { content: "▼"; font-size: 0.6em; opacity: 0.8; } (after hiding the default caret)
   - Or use background-image with an SVG for a custom icon.

Selector: .sw-simple-header__menu-caret (inside .sw-simple-header__menu-link--toggle, within .sw-simple-header__menu-item--has-submenu).

================================================================================
10. REFERENCES
================================================================================

MODULE-FIELD-LABELING-STANDARD.md, MODULE-SETTINGS-BACKGROUND-STANDARD.md, MODULE-SAMPLE-CONTENT-STANDARD.md (§6 CTA default URL), ALIAS-MAPPING-STANDARD.md, SW Button (reference for Buttons repeater and CTA default URL).

Changelog (AI doc): 2026.02.10 — Initial AI documentation. 2026.02.10 — Announcement Bar; Top Bar; Simple Link Font. 2026.02.24 — Top bar linking text; top bar icon color workarounds; menu dropdown arrow; gradient buttons. 2026.02.27 — Font fields include color but do not control hover; use Menu Colors for link colors (menu and top bar). Removed Link Colors from Simple Link Font (links inherit from top bar).