1. Treat field groups as versioned code
Store ACF definitions in JSON sync or PHP registration in the repo—not only in the database. Deployments should not “surprise” production with a new layout nobody tested. Tag releases with migration notes when you rename layouts or change sub-field keys; old post meta does not rewrite itself.
2. Permissions and editorial roles
Not every role should see every layout. Use capabilities, custom role plugins, or ACF location and field filters to hide destructive options (e.g. homepage hero) from contributors. Pair with workflow plugins or editorial states if legal must sign off before publish.
3. Validation, not just labels
Use acf/validate_value (and required flags) for business rules: min/max items, mutually exclusive toggles, URLs that must be internal, or image dimensions for hero slots. Catching errors in the editor beats broken front pages after publish.
4. Previews, revisions, and scheduled content
Meta-driven layouts interact oddly with expectations if teams assume “revision = full snapshot.” Document how preview works for your theme (classic vs block theme, any caching). For scheduled posts, ensure cron and object cache do not serve stale fragments when content goes live.
5. Multilingual and multi-market
Translation plugins and deep repeaters need a documented mapping: which flex layouts are translatable, which are shared globals, and how related posts resolve per locale. Test duplication and sync features on a clone—flex trees are where translation tools usually show their sharp edges.
6. Headless and API consumers
If a React or mobile client reads posts via REST or GraphQL, expose flex data as a stable, typed shape (normalized layout name + fields). Avoid leaking raw ACF keys that rename on a whim. Consider a thin serialization layer in PHP so the API contract survives field group refactors.
7. Editor enablement
Ship a short layout cookbook (screenshots + when to use each block of fields) and keep it next to the style guide. Advanced CM is as much training and naming as it is PHP.
Flex fields scale as a CMS primitive when you manage them like product surface area: versioned schema, explicit roles, validated data, and contracts for every consumer—classic theme, decoupled app, or translation pipeline.