masterconcept.ai — how this site is actually built

01What this site is

The five-minute mental model. If you only remember one thing, make it the last paragraph.

masterconcept.ai is Master Concept's public marketing site: a WordPress install on SiteGround, fronted by Cloudflare, running the Hello Elementor theme with Elementor Pro and ElementsKit on top, translated into four languages by WPML.

Counts taken from the REST API, Nov 2026. Note how thin zh-hk and zh-cn are — that imbalance drives a lot of section 6.

Three kinds of page live here

02Access you need

Ask Tommy for these on day one. They're granted individually, so say what you need and why.

• WordPress login (wp-admin)Your own account — never a shared one. The login URL is not /wp-login.php; the site hides it. Ask for the real URL.
• Application PasswordGenerated inside your WP profile. Needed for any script or tool that talks to the REST API as you.
• GitHub — mcailab/wpbuddyPushing to main deploys the plugin to the live site, so this is a production credential.
• FigmaDesigns come from Figma; page builds read measurements straight out of the file.
• Claude — via Magic LoginThe shared mc-marketing account. Section 10 has the full flow.
• A password manager of your ownFor your credentials — WP login, application password, GitHub. See the box below.

Where passwords go

Two different things, and it's worth keeping them straight:

Bookmark these

wp-admin links need you signed in — and the sign-in URL isn't /wp-login.php, so get that from Tommy first.

03The stack

39 plugins are active. These are the dozen that will actually affect your work.

04Where each thing lives

The most useful table on this page. Before you change anything, find its row — editing in the wrong place is the most common way to lose work here.

The WP Buddy repo — github.com/mcailab/wpbuddy

wp-buddy/
├── plugin/                 ← this is what deploys
│   ├── wp-buddy.php         ← main file, version + include list + changelog
│   ├── includes/            ← one file per feature
│   └── assets/              ← enqueued CSS/JS
├── docs/                    ← design + implementation notes (read these)
├── .github/workflows/       ← auto-deploy to the live site
└── README.md

No build step — plain PHP, vanilla JS and CSS. Nothing to compile, nothing to install.

Shortcodes it provides

[wpb_post_list] · [wpb_authors] · [wpb_hs_form] · [wpb_zoom] · [wpbuddy_nav] · [wpbuddy_menu]

House rule: reusable dynamic content goes through a shortcode, never hardcoded markup. If you find yourself pasting the same list of links into four language versions of a page, stop — that's a shortcode.

Its admin screens

wp-admin → WP Buddy: Tools · Analytics Dashboard · Tags Management · Content Tree · AI Builder (Beta) · Brand Kit · Shortcode · PageSpeed · Toolkit.

05Sitemap

The shape of the site at a glance. English structure shown — the other three languages mirror it, minus what hasn't been translated.

Pages — top level (English)

Posts — by category

Posts are organised by category, not by parent. The category decides where a post appears in a listing, and getting it wrong makes a post vanish from a page while looking perfectly fine in wp-admin.

06Languages & WPML

Four languages, uneven content, and a translation layer with sharp edges. This section exists because each of these cost us a day.

POST /wp-json/wpbuddy/v1/set-term-language
{ "term_id": 1091, "taxonomy": "nav_menu", "language": "zh-hant" }

Content gaps you'll run into

So zh-hk and zh-cn menus are mostly showing fallback links today. That is known, not a bug you need to fix on sight — but it's why those languages look thin.

Rules of thumb

• Always know which language you're editing. The URL prefix tells you.
• A page is not "translated" until WPML links it to its original — a standalone page in another language is invisible to the switcher.
• English copy runs ~30–40% longer than Chinese for the same meaning. Type sizes are tuned down for EN. Check both.
• If a language renders empty where another renders fine, suspect the cache first (section 11), then WPML.

07Menus & navigation

The header is a WordPress menu wearing an ElementsKit costume. Once that clicks, the mega menu stops being mysterious.

How the mega menu is actually built

The header is a normal WP menu. ElementsKit marks a top-level item as a mega-menu parent and attaches a separate Elementor document to it, which renders as the dropdown panel:

<li class="… elementskit-megamenu-has">
  <a>Solutions</a>
  <div class="elementskit-megamenu-panel" id="ekit-megamenu-panel-{itemID}">
      ← a whole Elementor post (type: elementskit_content)
  </div>
</li>

So "edit the mega menu" means two different jobs: the item is in Appearance → Menus, the panel is an Elementor template.

The newer, menu-driven approach

Hardcoding 24 links into a panel × 4 languages doesn't scale. New preview pages render navigation from a real WP menu with one shortcode:

[wpbuddy_nav menu="mega-solutions"   depth="2" icons="label"]
[wpbuddy_nav menu="footer-resources" depth="1"]
[wpbuddy_nav menu="footer-social"    depth="1" icons="1"]

You give it the base slug; it appends the language suffix automatically — -zh, -hk, -cn — so one page template serves all four languages. If a language has no menu it renders nothing, on purpose: an empty column is an honest signal that a menu still needs building, whereas a silent English fallback is how zh-hk once shipped an English header.

Icons come from the menu item

In Appearance → Menus, switch on CSS Classes under Screen Options, then put one of these on the item:

Current menus

Edit any of them at /wp-admin/nav-menus.php?action=edit&menu=<ID>.

Preview pages

Redesigns live as real pages before they replace anything. These are the current ones:

None of these are linked from the site. They are not live navigation — the production header still runs on the ElementsKit menus above.

08Building a page

The native-HTML route, where most of your frontend work will happen. These patterns are battle-tested — use them before inventing your own.

Full-bleed layout — the #1 recurring issue

With Elementor off, the page renders through Hello Elementor, whose main.site-main boxes content to 1140px and adds a top gap. Elementor sections used to break out of that; raw HTML doesn't, so you get grey strips down both sides.

Every native page carries a page-specific, unscoped override. Inline <style> only loads on that page, so it's safe:

main.site-main{max-width:none!important;margin:0!important;padding:0!important;width:100%!important}
main.site-main>.page-content{max-width:none!important;margin:0!important;padding:0!important}
.page-content>p:empty{display:none!important;margin:0!important;height:0!important}

That last rule kills the empty paragraph wpautop inserts at the top. Also strip the content and collapse whitespace between tags before pushing, so wpautop has nothing to chew on.

Centring a button

Use a text-align:center wrapper. The theme overrides both align-self:center and auto-margins on flex children — both failed silently in production.

<div class="cta"><a class="btn">了解更多</a></div>

.cta{text-align:center;margin-top:auto}  /* centre + pin to bottom of flex column */
.btn{display:inline-block}               /* stays inline-block so text-align works */

That margin-top:auto also gives you Elementor-style equal-height cards: image at the top, button pinned to the bottom, regardless of how long the copy is.

Figma-exported pages

Some pages come straight out of Figma as a fixed 1440px canvas with every element absolutely positioned. They scale down with a --hp-scale variable.

And a judgement call worth internalising: a Figma design with 20 fixed slots cannot hold 24 real items. When real content outgrows a fixed layout, convert it to a flowing one (grid + shortcode) rather than squeezing or dropping items. We did exactly that to the Solutions panel.

Images and assets

• Deduplicate Figma images by fills[].imageRef, not by layer name — designers reuse names while each fill is a distinct image.
• Upload to the media library with curl. Python's urllib gets 403'd by the WAF unless you send a browser/curl User-Agent.
• A reused filename gets a -1 suffix — check the URL you got back, don't assume.

09Design system

Navy and orange. The contrast rules below are computed, not opinions — please don't quietly break them.

Type

Raleway across the site, Arial fallback. Hero H1 50px desktop / 32px mobile at weight 900; H2 36/24 at 800; body 16–18px. Sizes come from clamp-based tokens in :root — --fs-h1, --fs-h2, --fs-lead, --fs-body — so set the token, don't hardcode a px value in a rule.

Cards

Floating white cards, not flat-bordered: 12px radius, 24–32px padding, soft shadow (0 6px 24px rgba(16,40,80,.10)) that deepens and lifts 4px on hover. The image sits inset on a light-blue panel with its own 10px radius — not bleeding to the card edge. Title centred and brand-blue, body left-aligned and grey.

Layout

• Container max-width:1140px, padding:0 20px
• Section padding 80px desktop / 60px mobile
• Fixed transparent header, 90px desktop / ~70px mobile — every hero needs a dark background or overlay, or the white header text vanishes

The live tokens also sit in wp-admin under WP Buddy → Brand Kit.

Accessibility we hold ourselves to

• Never encode meaning by colour alone — add a shape, a glyph, or a label. Roughly one man in twelve has a red–green deficiency.
• Anything clickable shows a pointer cursor, including the little arrow glyphs beside menu text. They're separate elements and are easy to miss.
• Check desktop and mobile on every change. Not optional.

10Figma & Claude → WordPress

A lot of pages here are built with Claude rather than by hand. This is how you get in, and which of the two routes you're on.

Signing in to Claude

We use a shared mc-marketing Claude account for this work — not a personal one, so that projects, skills and history stay with the team.

1. Go to magic.mcai.dev and sign in with your Master Concept Google account.
2. Find the mc-marketing tile and use it to sign in to Claude. Magic Login holds the password and the one-time code.
3. That's it — no password ever gets copied into a file, a note, or a chat.

Route A — Figma → WordPress yours

This is the technical route, and the one you'll live in. The figma-to-wp skill drives it:

• Pulls the frame's render, its copy verbatim, its colour and type tokens, its box geometry and its images out of Figma.
• You then write the HTML against those real numbers, one section at a time — the skill does not generate the page for you.
• verify confirms every string survived and the site's hard rules hold · audit names which element is wrong and by how much · diff screenshots the result and scores each section against the Figma render · mobile runs the phone checks the frame can't answer.
• Then it uploads the media and creates the page as a draft, with the right slug and Permalink Manager URI.
• pull goes the other way — start from a page that already exists in WordPress.

Figma is read through its API with a read-only token — ask Tommy to set it up for you rather than minting your own. Nothing publishes itself; a draft is always the end state until someone says otherwise.

Route B — Claude Design → WordPress colleagues

Non-technical colleagues build a page in Claude Design and hand over a link; Claude publishes it. You should know this route exists because you will be the one who fixes it when the result needs a human.

It's one page covering what they send, page vs post, which language, category and region, cover image and SEO, the web address, and where it sits in the menu. Worth ten minutes — it's the shared vocabulary everyone here uses when they ask for a page.

11Deploy & verify

Two different pipelines depending on what you changed — and one cache that will lie to you.

Plugin code → git

1. Edit under plugin/
2. php -l <file> — CI doesn't lint yet
3. Bump WPBUDDY_VERSION and add a changelog line in wp-buddy.php for anything user-facing
4. Commit → push to main
5. GitHub Actions syncs plugin/ → wp-content/plugins/wp-buddy/ on the live site

Watch it land: gh run list --repo mcailab/wpbuddy — or the Actions tab. No FTP, no server login; the push is the deploy.

Page content → REST

Pages are pushed as raw HTML via the REST API using a dedicated user that holds unfiltered_html. The plugin exposes named abilities for the fiddly parts:

Preferred workflow

Edit local → review local → push to prod → verify via DOM. Reviewing locally first avoids the entire cache problem, which is why we do it that way round.

12Gotchas

Every one of these has already cost someone here real time. Skim now; come back when something behaves impossibly.

13House rules

Short list. Mostly about not surprising the next person.

Code

• Match the surrounding code — its naming, its comment density, its idiom. Don't import a different house style into one file.
• Names are canonical and domain-free: no leaking one customer's or one page's vocabulary into shared code.
• Reusable dynamic content → a shortcode. Never four hardcoded copies, one per language.
• php -l before you commit.
• Bump the version and write the changelog line for anything user-facing.

Working on production

• Back up the current HTML of any page before you overwrite it.
• Review locally first.
• Verify by DOM after pushing.
• If you changed something and can't see it, suspect cache before you suspect your code — then suspect your code.

Asking

Ask early about: anything touching the live header or footer, anything that changes a URL, anything multilingual you're unsure about, and anything that needs a credential. None of those are things to figure out quietly on production.

14Your work & how it reaches you

Three places, and they're in transition. Start with the sheet; learn the other two in your first fortnight.

1 · Your task list start here

The sheet is the live list — work from it, tick things off there, and ask Tommy if a row isn't clear. Everything you need in order to do those tasks is somewhere on this page; the sections above are in roughly the order you'll need them.

2 · Asana — the team board today

Where the wider team's work is tracked today. Requests from the business arrive through Asana Forms rather than as ad-hoc messages — someone fills in the form, it lands on the board as a card with the details already structured. If a colleague asks you for something in chat, the right answer is usually "put it through the form", so it's tracked and nobody loses it.

3 · Wilco → Plane — where we're heading the goal

This is the workflow automation we're building toward, and it's already running on this site. It removes the retyping step entirely:

1. Someone spots a problem on a live page and pins feedback directly on it — on the page itself, not in a ticket describing the page.
2. Wilco captures the pin with its page, its position, the device, the author and any screenshot.
3. One action turns it into a work item in Plane — MC-1, MC-4, MC-5 and so on — tracked, assignable, closable.
4. Any pin reopens the real page with the pin in place via ?fb=<id>, so you see exactly what they saw.

Four projects are wired up: Master Concept Website, ATS (careers), EIP and Aptitude Test. The website currently has 3 open pins, all already linked to Plane items.

Known open work on the site

Independent of the sheet, these are live and unfinished today:

• Header preview exists in 繁中 only — the other three need their top-bar labels translated.
• Mobile design for the header: hamburger + tap-to-expand accordion, deliberately different from the desktop hover mega menu.
• Partners mega menu — ~40 items, needs the brand logos uploaded first.
• The 24 solution pages don't exist in zh-hk at all, and only 4 of 24 exist in 简中.
• Swap the live ElementsKit Solutions panels over to render from the mega-solutions menu.
• 12 unused footer menus (Footer Solutions / Company / Customers × 4) left over from a dropped layout — pending a decision to delete.

15Glossary & contacts

Terms that get used around here as if everyone already knows them.

Where to look things up