Developer Guide

This guide answers one question: I need to work on this codebase — what do I need to know?

It covers the navigation system, CSS architecture, and implementation rules for the UX Design Warrior site. It does not cover design system rationale, brand guidelines, or typography specimens — those live in the UXDW Style Guide.

Before modifying any CSS, confirm you are working in the correct environment. The wrong location will either have no effect or break existing styles.

Where CSS lives — exact paths:

The UXDW site uses a menu-only global header. This was a deliberate architectural decision — not a Divi default. Most pages use custom full-width layouts without a global header. Rather than duplicating the menu across every page, the menu module was made the sole global element. This eliminated z-index conflicts and created a single source of truth for navigation.

For the full investigation behind this decision, see the Debugging an AI Loop case study ↗

These five rules were established through direct testing in the UXDW Divi environment by Ryan (ChatGPT). They protect the navigation system from structural failures.

• 01

  Always scope to the header

  Always use .et-l--header .et_pb_menu as the outermost parent scope. This prevents CSS from bleeding into mobile drawers or footer menu instances.

• 02

  Layer CSS in order

  Write rules in this sequence: container → main links → dropdown panel → dropdown links → mobile. Writing out of order causes cascade conflicts.

• 03

  Avoid bare element selectors

  Never write bare ul, li, or a selectors. Always qualify with the menu parent. Bare selectors bleed into every list on the page.

• 04

  Override presentation, not structure

  Never add flex or float to Divi menu structure. Divi manages its own layout. Override color, font, and spacing only.

• 05

  Use !important surgically

  Only use !important where Divi injects inline styles that cannot otherwise be overridden. Document every instance with a comment.

Confirmed working in the UXDW Divi Theme Builder environment. All selectors target the Theme Builder context. Do not substitute legacy #top-menu selectors — they are unreliable in Theme Builder.

Complete current CSS for the UXDW header navigation. Paste the entire block into the Header Template's Advanced CSS field.

/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━
   HEADER BACKGROUND
━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
#main-header,
#main-header.et-fixed-header {
  background-color: #190f0a !important;
}

/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━
   MAIN NAV LINKS
━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
.et-l--header .et_pb_menu .et-menu > li > a {
  color: #F4E8D8 !important;
  font-family: 'Source Sans 3', sans-serif !important;
  font-size: 16px !important;
  font-weight: 500 !important;
  letter-spacing: 0.02em;
  opacity: 1 !important;
}
.et-l--header .et_pb_menu .et-menu > li > a:hover {
  color: #ffffff !important;
  opacity: 1 !important;
}

/* Current / active page */
.et-l--header .et_pb_menu .et-menu li.current-menu-item > a,
.et-l--header .et_pb_menu .et-menu li.current-menu-ancestor > a {
  color: #ffffff !important;
  font-weight: 600 !important;
  border-bottom: 2px solid #c85a1e;
  box-shadow: none;
}

/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━
   DROPDOWN PANEL
━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
.et-l--header .et_pb_menu .sub-menu {
  background-color: #3d1a00 !important;
  border-top: 2px solid #c85a1e !important;
  padding: 8px 0 !important;
}
.et-l--header .et_pb_menu .sub-menu a {
  color: #F4E8D8 !important;
  font-family: 'Source Sans 3', sans-serif !important;
  font-size: 16px !important;
  font-weight: 400 !important;
  padding: 10px 24px !important;
  opacity: 1 !important;
}
.et-l--header .et_pb_menu .sub-menu a:hover {
  color: #ffffff !important;
  background-color: #5a2800 !important;
}

/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━
   MOBILE HAMBURGER
━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
.mobile_menu_bar {
  min-width: 52px !important;
  min-height: 52px !important;
  background: #c85a1e !important;
  border-radius: 6px !important;
  display: flex !important;
  align-items: center !important;
  justify-content: center !important;
}
.mobile_menu_bar::before {
  color: #ffffff !important;
  font-size: 22px !important;
}

/* Mobile drawer */
.et_mobile_menu {
  background: #3d1a00 !important;
  z-index: 9999;
}
.et_mobile_menu a {
  color: #F4E8D8 !important;
  font-family: 'Source Sans 3', sans-serif !important;
  font-size: 16px !important;
  font-weight: 500 !important;
}
.et_mobile_menu a:hover {
  color: #ffffff !important;
  background: #5a2800 !important;
}
      

Platform-level Divi behaviors that have caused failures on this site. Each was identified during the debugging investigation.

• ⚠️ Divi injects inline styles that override CSS rules

  Divi's divi-dynamic stylesheet injects opacity: 0.7 on dropdown hover states at runtime. This overrides external CSS. It was the root cause of the persistent hover failure on this site.

  Fix: Use opacity: 1 !important on hover states. Document every !important usage.
• ⚠️ overflow:hidden clips dropdown menus

  Any parent container with overflow: hidden will clip dropdown menus. This affects both custom HTML and native Divi menus inside certain section types.

  Fix: Remove overflow: hidden from any container wrapping the menu module.
• ⚠️ Theme Builder templates can duplicate navigation

  Overlapping template scopes can cause the menu to render twice. This occurred on the About page during this investigation.

  Fix: Audit Theme Builder template scopes. Ensure no conflicting secondary template scopes exist.
• ⚠️ Auto-generated class names are fragile

  Classes like .et_pb_menu_0_tb_header auto-generated by Divi can change between versions or when templates are re-saved. CSS targeting them will break silently.

  Fix: Always use stable structural selectors like .et-l--header .et_pb_menu.

When CSS is not applying as expected, follow this sequence before writing new code:

• Hard reload in a second browser — eliminates cache as a variable entirely
• Inspect the element — confirm whether Divi is injecting an inline style override
• Verify selector location — confirm CSS is in the Header Template, not Theme Options
• Check for overflow: hidden on parent containers
• Confirm the selector matches exactly — copy from the verified selector table above
• Test one property at a time — add, confirm, then add the next
• Document what failed and why before trying something new

Rules for anyone modifying the UXDW codebase. These protect the system from unintended regressions.

• —

  Never introduce unscoped selectors

  All CSS must be scoped to a page prefix wrapper or .et-l--header .et_pb_menu. Bare selectors break the entire site.

• —

  Avoid modifying Divi module structure

  Do not alter the HTML structure Divi generates for the menu module. Override presentation through CSS only.

• —

  Avoid using PHP in Code Modules

  Divi Code Modules do not execute PHP. Hardcode all links and values directly in HTML.

• —

  Document all navigation overrides

  If you add or change navigation CSS, note what changed and why. Every !important must be justified in a comment.

• —

  Use the page prefix system

  All page-level CSS wraps content in a .prefix-page wrapper. See the prefix registry below.

Page Prefix Registry

Navigation-relevant color tokens only. For the full design system — typography, contrast ratios, brand guidelines — see the UXDW Style Guide.