A developer's guide to moving AEM Classic UI to Touch UI

Migrating from AEM Classic UI to Touch UI is more than replacing an authoring skin. It changes how components are configured, how JavaScript and styles are delivered, and how authors interact with structured content. Touch UI relies on a modern component model, so teams must modernise the underlying code as well as the screens. The safest path treats UI migration, content remediation and delivery validation as one programme.

Australian projects often spread across Sydney, Melbourne, Brisbane and Canberra, with agency teams supporting clients in another state. Time zones matter immediately: Brisbane usually stays on AEST, Sydney and Melbourne move between AEST and AEDT, and a follow-the-sun support roster can cross Perth's AWST window. Plan release approvals, publishing windows and incident handovers around those local schedules rather than copying a US timetable.

Australian workplace discussions tend to be direct and practical. A lead may ask, “Can you roll it back?” and expect a clear answer, while a content owner may call a missing field a “blocker” without softening it. That plainness helps a migration: record decisions, owners and acceptance criteria in writing. Budgets also tend to run in Australian dollars, so make licence, hosting, training and contingency costs visible at approval stage.

CIRCUIT, the two-day Adobe developer conference in Chicago, brought Java developers, AEM architects, front-end developers and systems engineers together for hands-on sessions. Its programme covered integrations, Sightly, mobile development, microservices, IoT, open source and analytics. The archive of agendas, speaker details, pricing history and recordings from 2015 and 2016 offers useful context for the engineering decisions behind a Touch UI programme.

Why Touch UI changes the system

Classic UI let many projects accumulate side-by-side JavaScript under /etc.clientlibs, JSP-based rendering and tightly coupled dialogs. Touch UI expects components under /apps, modern client libraries, Granite UI dialog elements and data supplied through Sling Models or another supported rendering pattern. Existing content can survive, but the old assumptions cannot simply be copied into the new console.

The component boundary is the key architectural checkpoint. A dialog should configure a clear content model, a Sling Model should expose that data, and the HTL template should render it without business logic embedded in the view. This reduces brittle JavaScript and gives authors a consistent editing experience. It also makes later upgrades safer because responsibilities are separated instead of hidden in a large client-side bundle.

First decide whether the target is AEM 6.5, AEM as a Cloud Service or a later managed platform, because the deployment and repository rules differ. Classic UI is unavailable in AEM as a Cloud Service, and a cloud move carries additional concerns such as customisation limits and managed dependencies. Teams coming from another component-based CMS can find the discipline useful; the Drupal 8 Day programme illustrates how structured content models work beyond AEM.

Build a reliable migration baseline

Start with a content and code inventory, not a folder-by-folder rewrite. Map each page template to its components, dialogs, client libraries, include paths, dynamic media, tagged references and personalised variants. Record whether a component is still used, whether its configuration is reused elsewhere and which business team owns it. This exposes the smallest useful migration set.

Use repository and package analysis to find references between /content, /apps and /libs. Look for scripts calling deprecated Classic APIs, hard-coded console paths, inline CSS assumptions and permissions attached to the old authoring workflow. Run compatibility checks against the target AEM version and save the results beside the component inventory. They become a repeatable baseline after each refactoring batch.

Java issues need direct investigation rather than guesswork. For Sling Model failures, request injection problems or unexpected dispatcher behaviour, the archived Eclipse debugging tips provide a useful companion to local logging. Pair those findings with representative content, because a component that works with one page may still break when an inherited property or null value appears elsewhere.

Refactor components without breaking delivery

Rebuild one representative template at a time using Granite UI fields, meaningful field names, validation and accessible help text. Move reusable configuration into Sling Models, keep rendering logic in HTL or a model exporter, and place browser behaviour in versioned client libraries under the application. Give each component a clear owner and publish a short contract describing its fields and output.

Do not change the content model and front-end contract in the same uncontrolled step. If a field must be renamed, add a migration or compatibility layer and test existing content against it. Review selectors, CSS namespaces, JavaScript events and response modes because Touch UI components are also used for rendering authored pages. Any change to a component can affect cached output, analytics dimensions and downstream APIs.

Move the cleaned component into a controlled branch, run automated package validation and review it with an author, developer and release engineer. For a large content estate, migrate in waves by template or business area rather than by JCR path. Keep a content freeze for the affected wave, obtain editorial approval, then promote the same tested package through release. This reduces duplicated work and makes rollback practical.

Validate author workflows and published pages

Testing must cover both sides of the platform. Authors need to open inherited pages, edit required fields, use assets, manage tags, preview variants and complete approval tasks without relying on Classic UI habits. Administrators need to confirm groups, permissions and workflow assignments. Published pages, headless endpoints and mobile delivery should retain their expected structure and behaviour after the component refactor.

Baseline to capture before refactoring

A component-to-template inventory, including unused and inherited content.
Screenshots of critical authoring screens and published-page journeys.
Current accessibility, performance, analytics and search baselines.
Named content owners and approval paths for each business area.

Go-live checks

Every migrated dialog opens, saves and publishes through supported roles.
Critical journeys match approved content and visual baselines.
No critical accessibility, security or performance regressions remain.
A tested rollback, support roster and communication plan are ready.

After these gates pass, test in every browser supported by the target AEM release and include keyboard-only journeys. Check that error messages appear beside the relevant field, focus order is logical, labels survive localisation and colour contrast remains compliant. Compare page weight and Core Web Vitals with the baseline, since a modernised component can still introduce an oversized bundle or an inefficient image.

Roll out the change and support the authors

A migration succeeds when authors can work faster, not when they can merely complete a training course. Run short, role-based clinics using real templates and realistic content. Demonstrate required fields, asset selection, preview, approval and recovery from validation errors. Give each business area a named super user who can triage issues and feed recurring requests into the product backlog.

Coordinate release communications with the Australian operating day. Publish the window in local time, state whether editors should publish or only prepare content, and include the support channel in the same message. During the first business days, watch authoring errors, failed publish jobs, broken references and unusual time on task. A live dashboard is more useful than a launch announcement because it shows whether the new workflow is changing author behaviour.

CIRCUIT's session recordings can support internal reviews of architecture, integration and debugging decisions. Review the conference FAQ for event information, then select the recordings that match your migration risks and share them with developers, architects and content owners. Make the next step concrete: assign a component inventory owner, schedule the first template refactor and rehearse the rollback before the next release window.