BSP Figma — Codebase Documentation

0. Apr 27 changelog — doc shipped

This doc was created Apr 27 2026 as Layer 5 of the Apr 27 structural fix after the smoke-gate caught drift between dispatcher_safety.py's M2 sanitizer-chain assertion and the live endpoint. Same drift risk exists for Figma work: multiple walker iterations (v1/v2/v3), undocumented API endpoint usage, asset upload failure modes, brand token drift between Figma and Bricks. Without a TIER 0 codebase doc, every future Figma task re-investigates from scratch — and that's the loop the Bricks doc was created to break.

Sources consolidated into this doc

• Walker source: /opt/nexus/nexus/scripts/figma_to_bricks_walker.py (v1, 400 LOC) · figma_to_bricks_walker_v2.py (v2, 366 LOC) · figma_to_bricks_walker_v3.py (v3, 502 LOC)
• Walker spec: /opt/nexus/nexus/scripts/walker_v3_spec.md (248 lines, evidence-classed schema)
• MH sections: bsp-apr14-figma-audrey-design-pulled, bsp-apr14-walker-v3-deployed, bsp-apr14-footer-figma-api-violation-rebuild, bsp-apr15-figma-source-verified-wave-is-rectangle, bsp-apr15-figma-to-bricks-v3-generator-SHIPPED-187-elements, bsp-apr15-figma-v3-paste-import-ready-auth-fixed, bsp-apr15-real-figma-wave-png-live, bsp-apr15-audrey-autolayout-reframe-VERIFIED-match-spec, bsp-apr16-bricks-23-of-23-checks-pass-wave-faq-spam-fixed, bsp-apr17-trust-bar-figma-icons, bsp-apr20-memory-backfill-figma-api-first.
• Memory rule: memory/feedback_figma_api_first.md — "Figma API first for any Audrey design task"
• Companion: BSP_Bricks_Codebase_Documentation.html (the other half of the stack)

🧭1. Intent — why this codebase doc exists

The design half of BSP's web stack is Figma. Audrey designs at figma.com, exports via the Figma REST API, the BSP walkers translate her autolayout trees into Bricks element JSON, the JSON is pasted into the Bricks editor (or POSTed to /bsp/v2/bricks/native-save), and the result renders at bricks.callbrightside.com. Every link in that chain has a known sharp edge.

This doc enforces three things:

1. Figma API first — never rebuild from a screenshot, transcript, or memory when the file key + token are sitting in .env. The Apr 14 footer-figma-API-violation cost 5 hours and an embarrassing "you have figma api access fucker" correction from Robert.
2. Walker is the producer, not the verifier — Bricks rendering reality is the verifier. Walker JSON that "looks right" is irrelevant; only what the live page renders counts.
3. Tokens live ONE place: Figma — Audrey's file is the source of truth for color/typography/spacing/copy. Brand drift events (e.g. Apr 15 wave-is-rectangle, Apr 17 trust-bar emoji vs custom icons) all came from substituting interpretation for the file.

🛡️2. Anti-slop principles (Audrey/Robert/Mario lessons applied to Figma)

The 5 anti-patterns that have burned us

The Audrey reframe lesson (Apr 15-16)

Producer-as-Verifier callouts specific to Figma

• Walker says 187 elements emitted → curl /bsp/v2/db/meta-full?post_id=8 after paste-import. Apr 14: walker emitted 122, sanitizer accepted, page rendered. Apr 16: walker emitted 187 via /bsp/v1/bricks/apply-v2 (200 OK, verify_count=187), but immediate read returned 0 — sanitizer rejected schema. Two different outcomes from indistinguishable producer signals.
• Image element renders → Playwright screenshot, not grep "image" in HTML. Bricks renders <img> tags even when image.url 404s.
• Wave aligns visually → pixel-sample at the overlap row, not visual inspection. Apr 15 80px overlap was confirmed via RGB(190,230,245) sampling at y=2479,2519 — not by "looks right".

🏗️3. Architecture overview — Figma → walker → Bricks

┌──────────────────────────┐    ┌──────────────────────────┐    ┌──────────────────────────┐
│   FIGMA                  │    │   BSP VM (Nexus)         │    │   WORDPRESS / BRICKS     │
│                          │    │                          │    │                          │
│  Audrey designs          │    │  figma_to_bricks_        │    │  bricks.callbrightside   │
│  autolayout frames       │──→ │  walker_v2.py / v3.py    │──→ │  .com  (page 8 + tpl)    │
│                          │    │                          │    │                          │
│  files/{file_key}        │    │  Walker reads:           │    │  POST /bsp/v2/bricks/    │
│  GViYd2jKWUEpLbz1lWghby  │    │   /tmp/figma_audrey.json │    │       native-save         │
│  6Hs3YviSaG5uCzc90XKU7Q  │    │   /tmp/bricks_uploaded_  │    │  POST /bsp/v1/bricks/    │
│  (...)                   │    │      assets.json         │    │       template-create     │
│                          │    │  Walker writes:          │    │  POST /wp/v2/media        │
│  /v1/files/{key}         │←── │   /tmp/bricks_import_    │    │                          │
│  /v1/files/{key}/nodes   │    │      v3.json (187 elems) │    │  Bricks sanitizer chain   │
│  /v1/images/{key}        │    │                          │    │  may reject + return 200  │
│                          │    │  Auth: X-Figma-Token     │    │  → READ-AFTER-WRITE       │
└──────────────────────────┘    └──────────────────────────┘    └──────────────────────────┘
        ↑                                  ↓                                ↓
        │                          drafts / .env / logs              functions.php CSS
        │                                                            mirrors Figma tokens
        └──────────── if walk fails, request autolayout reframe ──────────────┘
  

Pipeline phases (Apr 14-17 canonical flow)

1. Pull — curl -H "X-Figma-Token: $FIGMA_TOKEN" https://api.figma.com/v1/files/{key} > /tmp/figma_audrey_full.json
2. Render reference PNG — /v1/images/{key}?ids=708:216&format=png&scale=2 → upload to morpheus for visual diff
3. Export image fills — /v1/images/{key}?ids=...&format=png&scale=2 for every RECTANGLE with fills[].type==IMAGE
4. Upload to WP media — POST /wp/v2/media with claude-api app password (see Auth section); save {id, url, slug, hash12} to /tmp/bricks_uploaded_assets.json
5. Walk — python3 figma_to_bricks_walker_v2.py /tmp/elements.json <frame_names...>
6. Apply — paste-import via Bricks editor UI (preferred) OR POST /bsp/v2/bricks/native-save (REST path)
7. Read-after-write — GET /bsp/v2/db/meta-full?post_id=N · sanitizer wipes silently on schema mismatch
8. Verify visually — Playwright screenshot, pixel-sample at decoration boundaries, side-by-side vs Figma /v1/images render
9. Purge — LiteSpeed admin + Cloudflare API (NEVER skip — Apr 16 lie-loop documented)

🌐4. Figma REST API — endpoints BSP uses, annotated

Authentication

HEADER:
  X-Figma-Token: <Personal Access Token>

WHERE:
  /opt/nexus/nexus/config/.env  →  FIGMA_TOKEN=...   (perm 600, owned dovew)

OWNER OF TOKEN:
  audrey.grant@callbrightside.com  (handle: audfish, role: owner on her files)
  Whoami probe: GET https://api.figma.com/v1/me  →  email + handle echoed back

Endpoint inventory (verified BSP-usage)

Canonical curl examples (used Apr 14-17, copy-paste ready)

FIGMA_TOKEN=$(grep ^FIGMA_TOKEN /opt/nexus/nexus/config/.env | cut -d= -f2)
KEY=GViYd2jKWUEpLbz1lWghby

# 1) Whoami (auth probe)
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" https://api.figma.com/v1/me

# 2) Full file (depth=3 index)
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/files/$KEY?depth=3" > /tmp/figma_index.json

# 3) Specific node tree (autolayout walk)
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/files/$KEY/nodes?ids=708:216,606:9&depth=10" \
  > /tmp/figma_audrey_full.json

# 4) Reference PNG render (visual diff source)
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/images/$KEY?ids=708:216&format=png&scale=2" \
  | jq -r '.images["708:216"]' \
  | xargs -I{} curl -s -o /tmp/figma_desktop.png "{}"

# 5) Trust-bar icon export (Apr 17)
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/images/$KEY?ids=734:26,734:29,734:19,734:8&format=png&scale=3"

🧩5. Figma plugins — community + custom

Community plugin Robert flagged Apr 27

URL: https://www.figma.com/community/plugin/991866272578143756

Plugins/integrations BSP currently uses (verified)

🚶6. Walker v1 → v2 → v3 — annotated source

Version timeline

v2 — what it does

Source: /opt/nexus/nexus/scripts/figma_to_bricks_walker_v2.py

Module docstring (verbatim):

"""figma_to_bricks_walker_v2.py
Layout-faithful Figma -> Bricks walker.
Fixes from v1:
  - Indexes ONLY Desktop - 1 (not iPhone)
  - Multi-line TEXT in nav columns -> split into separate text-basic rows
  - Header section gets tagName:header, nav containers get tagName:nav
  - Footer section gets tagName:footer
  - Width propagation via percent (child width / parent width) for proper row layout
  - VECTOR with wide/thin aspect -> divider element
  - Big background VECTORs (wave_element, Footer shape) at Desktop root are skipped
    (they're absolutely-positioned decoration, not flow content)
  - Button frames use tel:+19139631029 and button element with proper bg + text
  - Line-height, letter-spacing carried through typography
"""

v2 element-type mapping (annotated)

v2 known unsupported types (logged but skipped)

• BOOLEAN_OPERATION (compound shapes — export PNG)
• STAR, POLYGON, ELLIPSE non-button (export PNG)
• SLICE, STICKY, WIDGET (designer-only artifacts)

v3 — what it does

Source: /opt/nexus/nexus/scripts/figma_to_bricks_walker_v3.py

Module docstring (verbatim):

"""figma_to_bricks_walker_v3.py

Builds Bricks HEADER + FOOTER templates from Figma (Audrey) + reuses Walker v2
body for page content. Schema-locked per /opt/nexus/nexus/scripts/walker_v3_spec.md.

Key deltas vs v2:
  - Emits bare-string widths/paddings ("220", "16") instead of {unit,value} dicts
    (matches real Bricks exports on disk: form_pwlost.json)
  - Image elements carry full 5-key shape (id, filename, size, full, url)
  - Header uses flex row + logo/nav/cta horizontal layout (NOT stacked)
  - Nav uses text-basic links in a flex container (avoids WP nav menu term dep)
  - Footer uses 3-column nav row + BBB row + copyright row
  - Both templates emit tag=header / tag=footer on root section
  - No sticky / no shape divider (flagged in spec as known gaps)

Outputs JSON payload ready to POST to /wp-json/bsp/v1/bricks/template-create.
"""

v3 schema deltas (canonical, from walker_v3_spec.md)

v3 brand constants (hardcoded in source)

BRAND_NAVY   = "#1D1760"
BRAND_BLUE   = "#30C5FF"
BRAND_YELLOW = "#FFEA00"
PHONE_DISPLAY = "(913) 963-1029"
PHONE_TEL     = "tel:+19139631029"

NAV_LABELS = ["Services", "Service Areas", "Blog", "About Us"]
NAV_URLS   = ["/services/", "/service-areas/", "/blog/", "/about/"]   # placeholders

FOOTER_SERVICES = ["Sewer Camera Inspection","Drain Cleaning","Water Heaters",
                   "Sump Pumps","Leak Detection"]
FOOTER_AREAS    = ["Overland Park","Leawood","Olathe","Lenexa","Kansas City"]
FOOTER_CONTACT_LINES = ["Bright Side Plumbing",
                        "12022 Blue Valley Pkwy",
                        "Overland Park, KS 66213",
                        PHONE_DISPLAY]

How to invoke (CLI)

# Walker v2 — body content
python3 /opt/nexus/nexus/scripts/figma_to_bricks_walker_v2.py \
  /tmp/page8_elements.json \
  01_Hero 02_CTA_TrustBar 03_Reveals 04_Process_Steps \
  05_Services 06_kc_homeowners_say 07_Commercial 08_FAQs 09_Final_CTA

# Walker v3 — header + footer templates
python3 /opt/nexus/nexus/scripts/figma_to_bricks_walker_v3.py \
  --emit both
# emits /tmp/header_v3_payload.json + /tmp/footer_v3_payload.json
# POST each to /wp-json/bsp/v1/bricks/template-create

📁7. BSP Figma file inventory

🖼️8. Asset pipeline — Figma export → WP media → Bricks image src

[1] Figma node with fill IMAGE
       │
       │  imageRef = "abc123def4567890..."     (full hash)
       │
       ▼
[2] /v1/images/{key}?ids=NODE&format=png&scale=2
       │
       │  → signed S3 URL (expires ~30 min)
       │
       ▼
[3] curl -o /tmp/audrey_assets/{slug}.png <signed URL>     # download immediately
       │
       ▼
[4] POST /wp-json/wp/v2/media     (auth: claude-api app password GaW1...LHBP)
       │
       │  → returns {id, source_url, slug, ...}
       │
       ▼
[5] Append to /tmp/bricks_uploaded_assets.json:
       │
       │  { "fill_abc123def456": { "id": 153,
       │                           "url": "https://bricks.callbrightside.com/wp-content/uploads/...",
       │                           "slug": "bsp-trust-licensed",
       │                           "hash12": "abc123def456" } }
       │
       ▼
[6] Walker v2 reads assets, keys hash_map by hash12 → resolves to {id, url, size}
       │
       ▼
[7] Bricks image element renders <img src="..."> on live page
       │
       ▼
[8] Visual verify: Playwright screenshot · pixel-sample @ image bounding box

Auth for WP media upload

USER:  claude-api          (NOT morpheus — that one is DAOT...)
PASS:  GaW1 p28e 2JLq xrwv yIf0 LHBP   (Apr 16 verified working)
ENV:   /opt/nexus/nexus/config/.env  →  WP_APP_PASSWORD_CLAUDE=GaW1...LHBP

curl -u 'claude-api:GaW1 p28e 2JLq xrwv yIf0 LHBP' \
  -F 'file=@/tmp/audrey_assets/bsp-trust-licensed.png' \
  -F 'title=BSP Trust Licensed' \
  -F 'slug=bsp-trust-licensed' \
  https://bricks.callbrightside.com/wp-json/wp/v2/media

Inventory: assets shipped via this pipeline (Apr 14-17)

🎨9. Brand tokens — Audrey's design system

Colors (verified from Figma file GViYd2jKWUEpLbz1lWghby, Apr 14 spec extract)

Typography

Spacing (autolayout itemSpacing — Audrey reframe verified Apr 16)

Decorative assets (NOT walker-emitted — handled via CSS / pseudo-elements)

• Mid wave — wave-bg-mid-light-scaled.png attached to #brxe-a9bd17::before (Process Steps section), aspect-ratio padding-bottom 85.8% so height scales proportionally with width. 4 responsive breakpoints: 1024 / 767 / 480 / 478 px (mobile wave removal).
• Footer wave — inline SVG, path M0,80 C240,20 480,0 720,20 C960,40 1200,60 1440,20 L1440,80 Z fill #BEE6F5.
• Doodles / sketched underlines — exported as PNG, placed as image elements (e.g. asset for "What KC Homeowners Say" underline = #brxe-89053d).

💀10. Failure modes encountered + workarounds

📋11. Canonical Build SOP — Figma-driven page work

Mirrors §13 of the Bricks doc. Follow this order for any page or section that originates from a Figma file. Pre-flight (Rule 0 web check) is REQUIRED before step 1.

Pre-flight (BSP CLAUDE.md Rule 0 — 4 checks)

# 1. Intent prepare
curl 'http://localhost:5544/api/context/prepare?intent=figma_page_build'

# 2. Zeus RAG search prior context
curl 'http://localhost:5544/api/zeus/search?q=figma+walker+page8'

# 3. MH grep — has this been done before?
ssh dovew@34.55.179.122 \
  "grep -i 'figma.*<page-slug>' /opt/nexus/nexus/scripts/output/playbooks/BSP_Master_Session_History.html | tail -5"

# 4. Financial validator (only if any $ involved — usually N/A for Figma work)
python3 /opt/nexus/nexus/scripts/financial_validator.py

Build steps

1. Confirm autolayout — pull /v1/files/{key}/nodes?ids=<target>&depth=2; check root has layoutMode: VERTICAL and per-section autolayout. If absent → Slack Audrey using drafts/slack_audrey_autolayout_request_apr15.txt template. Stop here until reframed.
2. Pull full file tree — /v1/files/{key}?depth=10 → /tmp/figma_audrey_full.json. Verify size > 100 KB (Apr 14 baseline 627 KB for sewer-camera).
3. Render reference PNG — /v1/images/{key}?ids=<desktop-node>&format=png&scale=2 → upload to morpheus.callbrightside.com/documents/figma_<page>_desktop.png for visual diff later.
4. Export image fills — for every RECTANGLE with fills[].type=IMAGE, hit /v1/images, download, upload to WP via POST /wp/v2/media, append to /tmp/bricks_uploaded_assets.json.
5. Walk — python3 figma_to_bricks_walker_v2.py /tmp/elements.json <frame_names>. Inspect stdout: element count, asset count, self.unsupported list. If unsupported > 5, stop and triage.
6. Apply — paste-import via Bricks editor (preferred) OR POST /bsp/v2/bricks/native-save. Read-after-write: GET /bsp/v2/db/meta-full?post_id=N, count elements. If sanitizer wiped, fall back to paste-import.
7. Patch ID-dependent CSS — re-extract live ID map (bricks_page8_id_map.json), sed-replace old IDs in functions.php if rebuilding. Deploy via POST /bsp/v2/theme/install-child.
8. Purge — LiteSpeed admin + Cloudflare API. Wait 5 sec.
9. Verify visually — Playwright screenshot at 1440 + 768 + 390 viewports. Side-by-side vs the Figma reference PNG from step 3. Pixel-sample at decoration boundaries (waves, doodles, image overlaps).
10. Log to MH — nexus_html_logger.py with section ID bsp-aprNN-<page-slug>-figma-shipped, severity success, content includes element count, asset IDs, sha + bytes of functions.php, MH cross-links.

🧵12. Cross-cutting threads

Walker evolution

v1 (Apr 14 14:51, 400 LOC)
  ├── indexed BOTH iPhone and Desktop frames → confused output
  ├── multi-line TEXT in nav columns shipped as one element
  ├── no nav-column expansion
  └── superseded 48 min later by v2

v2 (Apr 14 15:39, 366 LOC)  ★ active body walker
  ├── Desktop-1 only
  ├── nav column expansion (Services/Pages headers + per-line text-basic)
  ├── tagName: header / nav / footer
  ├── width propagation via percent (child / parent)
  ├── VECTOR wide+thin → divider element
  ├── SKIP_DESKTOP_ROOT_NAMES = {"wave element 2", "Footer", "wave_background_elements"}
  ├── button frames → tel:+19139631029 button element
  └── used in Apr 14 paste-import that shipped 122 elements rendering

v3 (Apr 14 16:05, 502 LOC)  ★ active header/footer template builder
  ├── schema-locked per walker_v3_spec.md (248 lines, evidence-classed)
  ├── bare-string widths/paddings ("16" not {unit,value})
  ├── 5-key image shape (id, filename, size, full, url)
  ├── horizontal header layout (logo / nav row / cta) NOT stacked
  ├── 4-col footer (logo+social / Services / Pages / Contact+Hours+BBB)
  ├── tag=header / tag=footer on root section
  ├── BRAND_NAVY/BLUE/YELLOW + PHONE_TEL hardcoded
  ├── outputs to /tmp/header_v3_payload.json + /tmp/footer_v3_payload.json
  └── POST to /wp-json/bsp/v1/bricks/template-create

Asset upload events (Apr 14-17)

• Apr 14: hero photo, 6 service-card photos, commercial photo, footer logo (asset 149 horizontal-rgb)
• Apr 15: wave-bg-mid-light-scaled.png (Figma node 612:15 PNG, 2560×2196)
• Apr 17: 5 new assets — 150 vertical footer logo, 151-154 trust-bar icons (star/5gen/licensed/ontime) at scale=3 from Figma frame 734:30

Brand drift events (color/spec corrections)

• Apr 14: footer color #D4E9FF (invented) → #D5EAFF (Figma source)
• Apr 15: wave shape misread as rectangle vs "curve" — verified via fresh /v1/images, IS 90% rectangle by design
• Apr 17: trust bar emoji-prefix → 4 custom Figma SVG icons
• Apr 17: reviewer name 15px → 20px w700 (Robert feedback)
• Apr 17: office hours 7am→8am Mon-Fri (Audrey delivery, time changed)

🧹13. Cleanup candidates

🔗14. References

Public Figma docs

• figma.com/developers/api — REST API reference (canonical for endpoints in §4)
• developers.figma.com/docs/rest-api — newer dev portal, same content
• figma.com/community/plugin/991866272578143756 — community plugin Robert flagged Apr 27 (research pending, see §5)

BSP scripts (cite verbatim before reinventing)

• /opt/nexus/nexus/scripts/figma_to_bricks_walker_v2.py — body walker (366 LOC)
• /opt/nexus/nexus/scripts/figma_to_bricks_walker_v3.py — header/footer template builder (502 LOC)
• /opt/nexus/nexus/scripts/walker_v3_spec.md — schema spec (248 lines, evidence-classed)
• /opt/nexus/nexus/scripts/audrey_asset_batch_upload.py — asset upload helper
• /opt/nexus/nexus/scripts/bsp_audrey_photo_workflow.py — photo intake workflow
• /opt/nexus/nexus/config/.env — FIGMA_TOKEN (perm 600)

MH sections (canonical Figma history)

• bsp-apr14-figma-audrey-design-pulled — first auth + 627 KB pull
• bsp-apr14-walker-v3-deployed — header/footer template ship + render gap flagged
• bsp-apr14-footer-figma-api-violation-rebuild — the "you have figma api access fucker" correction
• bsp-apr15-figma-source-verified-wave-is-rectangle — wave PNG is 90% rectangle, by design
• bsp-apr15-figma-to-bricks-v3-generator-SHIPPED-187-elements — generator built, deployment blocked on auth
• bsp-apr15-figma-v3-paste-import-ready-auth-fixed — auth fix (GaW1 not DAOT) + sanitizer documented
• bsp-apr15-real-figma-wave-png-live — removed fake bg rectangle covering real wave
• bsp-apr15-audrey-autolayout-reframe-VERIFIED-match-spec — autolayout matches spec exactly
• bsp-apr16-bricks-23-of-23-checks-pass-wave-faq-spam-fixed — element ID drift lesson
• bsp-apr16-bricks-fuckup-nothing-changed-visually — LiteSpeed cache miss + producer-as-verifier collapse
• bsp-apr17-trust-bar-figma-icons — 4 custom icons pulled, emoji-prefix text removed
• bsp-apr20-memory-backfill-figma-api-first — canonical "Figma API first" rule

Companion playbooks

• BSP_Bricks_Codebase_Documentation.html — Bricks half of the stack
• data_weapons_plan_v2.html — Sacred v2 operations dashboard
• BSP_Master_Session_History.html — full session log
• BSP_Location_Pages_Playbook.html — Audrey-first location page brief
• BSP_Homepage_Redesign_Playbook.html — homepage parent playbook