Implementation Spec — faddom.com AI/UX Audit Remediation (WordPress + Elementor)

Stack Context

• CMS: WordPress 6.9.4 (high confidence)
• Page builder: Elementor (medium confidence), with Elementor widget/class patterns in DOM:
  • span.elementor-button-content-wrapper
  • span.elementor-button-text
  • div.elementor-element.elementor-element-b2dc2f1 (custom clickable icon/close control)
• Infra hints: Cloudflare + Kinsta
• Observed characteristics:
  • Home HTML size: 1,256,502 bytes
  • DOM nodes: 3,296
  • Load time: 3,792ms
• Primary issues from audit:
  • Accessibility semantics + ARIA (163 non-semantic clickables missing role/tabindex)
  • Form labeling (3 unlabeled controls out of 8)
  • Tap target size (21 too small out of 78)
  • AI discovery endpoints and machine-readable policy/docs largely absent

Assume a standard WordPress theme + Elementor + likely caching/minification layers. Fixes should be done in theme/plugin custom code, not Elementor core/plugin edits.

---

Codebase Orientation

Inspect in this order before writing code:

1. Theme entry points
   • wp-content/themes/<active-theme>/functions.php
   • wp-content/themes/<active-theme>/header.php
   • wp-content/themes/<active-theme>/footer.php
   • wp-content/themes/<active-theme>/assets/css/ (or equivalent)
2. Must-use or custom plugins
   • wp-content/mu-plugins/
   • wp-content/plugins/<custom-site-plugin>/
   • Look for existing hooks on wp_head, template_redirect, init, send_headers, robots_txt.
3. Elementor customizations
   • Search for elementor/frontend/ hooks, custom widgets, JS click handlers on <div>/<span>.
   • Search for classes in audit:
     • .elementor-button-content-wrapper
     • .elementor-button-text
     • .close-bar
     • .e-n-menu-dropdown-icon
     • .ea11y-skip-to-content-link
4. Robots and well-known routing
   • Check if physical files exist in docroot (robots.txt, llms.txt)
   • Check any rewrite/virtual endpoint logic in theme/plugin
5. Forms
   • Identify Elementor forms containing:
     • #form-field-first_name
     • #form-field-email
     • #form-field-description
   • Prefer Elementor form settings first; fallback to server-side DOM filter if needed.

---

Tasks

T1 — Fix non-semantic clickable elements and ARIA gaps

Priority: P0

Affected files (best guess):

• wp-content/themes/<active-theme>/functions.php
• wp-content/themes/<active-theme>/assets/js/accessibility.js
• wp-content/themes/<active-theme>/assets/css/accessibility.css
• Possibly Elementor template JSON/content where specific widgets are configured

Acceptance criteria:

• Reduce nonSemanticWithoutAria from 163 to < 20 (or best possible without breaking Elementor internals).
• For any retained non-semantic clickables, ensure:
  • role="button" (or correct semantic role)
  • tabindex="0"
  • keyboard activation on Enter/Space
• Specific selector from audit addressed:
  • div.elementor-element.elementor-element-b2dc2f1.close-bar... becomes keyboard-operable and announceable.
• No regression in click behavior for menus, close actions, CTA triggers.

Implementation notes:

• Prefer true semantic conversion where feasible in Elementor editor:
  • Use <a>/<button> based widgets instead of clickable icon wrappers.
• For unavoidable Elementor-rendered wrappers, apply progressive enhancement JS:
  • Target known clickable non-semantic elements only (avoid global blanket on all spans/divs).
  • Add role/tabindex and keydown handler.
• Do not add ARIA to purely decorative spans like .elementor-button-content-wrapper unless they actually receive click listeners.
• Add robust guard:
  • If element already has native semantics (a, button, input types), skip.
  • If has aria-hidden="true", skip.

Test scenarios:

• Manual keyboard test:
  • Tab through header/nav/hero CTAs/close controls
  • Enter/Space activates same behavior as click
• Playwright smoke:

await page.goto('https://faddom.com/');
await page.keyboard.press('Tab');
// iterate and assert focus reaches close/menu controls and CTA actions fire on Enter

---

T2 — Add explicit labels for Elementor form inputs

Priority: P0

Affected files:

• Elementor form config/template for homepage form block
• Optional fallback: functions.php with frontend render filter for form markup

Acceptance criteria:

• Inputs currently flagged unlabeled gain accessible names:
  • input#form-field-first_name
  • input#form-field-email
  • textarea#form-field-description
• Each has one of:
  • <label for="...">...
  • aria-label="..."
  • aria-labelledby="..."
• Placeholder remains optional, not sole accessible name.
• Audit label-input moves from 5/8 labeled to 8/8 labeled.

Implementation notes:

• Preferred: configure Elementor Form widget field labels as visible or hidden-but-rendered labels.
• If Elementor strips labels in this layout, inject aria-label server-side via filter on rendered form HTML for IDs above.
• Keep strings aligned with existing placeholder copy:
  • Full Name *
  • Business Email *
  • Tell us about your needs

Test scenarios:

• Inspect DOM for each field accessible name in DevTools Accessibility panel.
• Screen reader quick check: field announced with proper label.

---

T3 — Enforce minimum tap target sizes

Priority: P1

Affected files:

• wp-content/themes/<active-theme>/assets/css/accessibility.css
• Possibly Elementor global site settings / custom CSS panel

Acceptance criteria:

• Improve tap target pass count from 57/78 to at least 72/78.
• Problem selectors addressed:
  • button#e-n-menu-dropdown-icon-1631 (13×26) → min width >=24
  • button#e-n-menu-dropdown-icon-1632 (13×26) → min width >=24
  • a.ea11y-skip-to-content-link must be practically reachable and not 2×2 when visible/focused
• Keep visual design impact minimal on desktop; prioritize mobile/touch usability.

Implementation notes:

• Add scoped CSS:
  • min-width: 24px; min-height: 24px;
  • Prefer 44x44 for primary nav toggles and major CTAs.
• For skip link:
  • Hidden offscreen by default is okay, but on :focus make it fully visible/clickable with sufficient size.
  • Remove/avoid conflicting onclick="return false" behavior if suppressing interaction.
• Validate no layout shift in nav after padding/size adjustments.

Test scenarios:

• Mobile emulation (iPhone/Android viewport) verify menu toggles easily tappable.
• Keyboard focus on skip link displays usable target.

---

T4 — Fix skip-link obstruction and interaction behavior

Priority: P1

Affected files:

• Theme header template and CSS
• Potentially Elementor header section with div.elementor-element.elementor-element-f9d2ea5

Acceptance criteria:

• a.ea11y-skip-to-content-link is not blocked at center point by overlay when focused.
• Skip link activates reliably and jumps to #content.
• Remove anti-patterns preventing native behavior (onclick="return false"), unless replaced with equivalent accessible script.

Implementation notes:

• Ensure z-index and positioning on focus state exceeds header overlay layers.
• Confirm #content anchor exists and is unique.
• If JS used for smooth scrolling, do not block default anchor semantics for keyboard users.

Test scenarios:

• Keyboard: first Tab should reveal skip link, Enter moves focus/scroll to main content.
• Hit testing in DevTools confirms no overlay intercept.

---

T5 — Expand robots.txt with explicit AI crawler rules

Priority: P0

Affected files:

• If physical: /robots.txt in site root
• If WP-generated: hook via robots_txt filter in functions.php or custom plugin

Acceptance criteria:

• Add explicit directives for missing bots listed by audit:
  • GPTBot
  • ClaudeBot
  • anthropic-ai
  • Google-Extended
  • CCBot
• Maintain existing directives for:
  • ChatGPT-User
  • PerplexityBot
• https://faddom.com/robots.txt remains HTTP 200 plain text and parseable.

Implementation notes:

• Choose intentional policy (Allow or Disallow) per business/legal direction; do not leave implicit.
• Keep syntax strict:

User-agent: GPTBot
Allow: /

(or Disallow: /).

• Preserve existing sitemap declaration(s).

Test scenarios:

• curl https://faddom.com/robots.txt
• Validate each UA block appears exactly once and with expected directive.

---

T6 — Rebuild llms.txt to valid canonical structure

Priority: P0

Affected files:

• /llms.txt (root static file or generated endpoint)

Acceptance criteria:

• Keep HTTP 200.
• Add required structure:
  • H1 title present
  • Blockquote summary immediately after H1 (currently missing)
  • At least one H2 section
  • At least one markdown link
• Reduce bloat; current file appears huge (135,191 bytes) with no detectable sections/links.

Implementation notes:

• Follow llmstxt.org style:

# Faddom

> Concise summary of product, audience, and key docs.

## Product
- [Overview](https://faddom.com/...)
- [Features](https://faddom.com/...)

## Docs
- [Knowledge Base](...)

• Keep concise and curated, not full corpus dump.

Test scenarios:

• Fetch and verify markdown parser detects headings, blockquote, links.
• Re-audit should move llms-txt from 60 toward 100.

---

T7 — Publish llms-full.txt aggregate

Priority: P2 (high-value optional)

Affected files:

• /llms-full.txt static artifact or generated endpoint
• Build/deploy script if auto-generated

Acceptance criteria:

• https://faddom.com/llms-full.txt returns HTTP 200 text/plain or markdown-compatible content.
• Contains substantial body corpus in markdown/plain text (not HTML error template).
• Linked/referenced from llms.txt optionally.

Implementation notes:

• Start with key high-intent pages (product, pricing, docs, integrations, security).
• If automation unavailable, publish manually curated v1; automate later.

Test scenarios:

• curl -I https://faddom.com/llms-full.txt → 200
• Spot-check content quality and readability.

---

T8 — Add .well-known machine-readable discovery manifests

Priority: P1 (for discovery score uplift)

Affected files:

• /.well-known/mcp.json
• /.well-known/agent-skills.json
• Optional:
  • /.well-known/oauth-authorization-server
  • /.well-known/api-catalog

Acceptance criteria:

• Endpoints return HTTP 200 with valid JSON and correct content-type.
• mcp.json includes required fields and non-empty tools list if applicable.
• agent-skills.json contains at least 1–2 real capabilities if product exposes callable flows.

Implementation notes:

• If no public tool invocation exists yet, still publish minimal truthful manifests (do not invent unsupported actions).
• Host as static JSON in webroot or route via WP rewrite + template output.
• Keep schemas aligned with current public drafts/specs used by audit tool.

Test scenarios:

• curl https://faddom.com/.well-known/mcp.json
• JSON lint + schema spot-check.

---

T9 — Optional content negotiation for markdown

Priority: P2

Affected files:

• Nginx/Apache config (likely Kinsta-level config constraints)
• WordPress routing/plugin if app-level fallback

Acceptance criteria:

• For selected routes, Accept: text/markdown can return markdown representation (or negotiated redirect to canonical md endpoint).
• Avoid breaking normal HTML delivery.

Implementation notes:

• On managed hosting, true header negotiation may be constrained.
• Practical alternative: expose parallel .md endpoints and document in llms.txt.
• If full negotiation infeasible, deprioritize in favor of llms manifests.

Test scenarios:

curl -H "Accept: text/markdown" -I https://faddom.com/

• Verify behavior matches implemented policy.

---

Stack-Specific Cautions

• Do not edit Elementor plugin core files (wp-content/plugins/elementor/...); updates will overwrite.
• Do not patch generated/minified cache artifacts directly (Cloudflare/Kinsta cache layers); change source theme/plugin files.
• Avoid global JS that sets role="button" on every div/span; this will create false positives and accessibility noise.
• Do not remove native anchor/button semantics by attaching JS-only click handlers.
• Preserve existing SEO/crawl directives in robots; append AI-agent blocks carefully.
• For .well-known files, ensure they bypass WP 404/caching quirks and return raw JSON.

---

Verification

After implementation:

1. Clear WP/plugin cache + Kinsta cache + Cloudflare cache.
2. Re-run audit on https://faddom.com/.
3. Validate key metric deltas:
   • aria-roles: from 10 → target 80+
   • semantic-elements: from 74 → target 90+
   • label-input: from 63 → target 100
   • tap-target-size: from 73 → target 90+
   • robots-ai-bots: from 29 → target 100
   • llms-txt: from 60 → target 95+
   • llms-full-txt: from 0 → target 100 (if T7 done)
   • mcp-server-card / agent-skills: from 0 → target 100 (if T8 done)

Expected score improvement (realistic):

• Overall: 52 → ~74–82 (depending on optional discovery tasks completed)
• Discovery: 34 → ~68–88
• UX: 64 → ~82–92

If constrained by platform for negotiation/OAuth/API catalog/WebMCP, still ship P0/P1 tasks first; they deliver the largest weighted gains with lowest risk.