AEM Author Guide

Creator

Users with this role can read, modify, and create pages in AEM. If you require Creator permissions, please reach out to Isabelle Louie or Priscilla Lee.

Publisher

Users with this role can read, modify, create, delete, and publish pages in AEM. If you need to publish a change, please reach out to Isabelle Louie.

To create or edit pages in AEM, you'll need to save the following links:

• AEM Directory: Data & Analytics Design – Main authoring environment for creating and editing documentation.
• AEM Assets (Images) – Upload and manage images used in guidelines and visual specifications.
• AEM Side Navigation Admin – Edit side navigation links and structure.
• Data & Analytics Design System Portal – Review published content and verify changes on the live site.

To prepare images for export:

1. Make a copy of each image, outside of the documentation container. Give it a clear, descriptive name and remove any unnecessary surrounding frames or content.
2. Set the image background color to Application/sapBackgroundColor.
3. Set the corner radius to --sapElement-BorderCornerRadius and enable "Clip content".
4. Export the image as a PNG at 2× for optimal quality.

Need a visual reference?

View Figma example

1. Go to AEM Assets and navigate to the dna-design folder (All Assets > SAP COM > design-system > dna-design).
2. Locate the existing component folder (or create a new folder) and upload the prepared images. In the file upload dialog, leave “Publish to AEM” unchecked.
3. Ensure images have a clear, descriptive name so they can be easily located.

If an uploaded image shares a name with an existing file in the folder, it will not be overwritten automatically.

1. Open the “Duplicate assets” info panel via the button in the top right corner.
2. Under the overflow ("...") button, select “Replace Duplicates”. If it fails, select “Save Duplicates as Version” instead.
3. If the image is already referenced in AEM, all instances will update to the new version.

New page – guidelines only:

1. In the AEM Directory, navigate to template-simple. Select its checkbox, then select "Copy" in the top toolbar.
2. Go up one level to ui-elements. Ensure the checkbox is not selected, then select "Paste" in the top toolbar.
3. In the "Paste Page" dialog, enter a new URL slug, using lowercase text and hyphens to separate words. Leave "Paste Without Children" unchecked, then select "Paste" in the dialog footer.

New page – with multiple page tabs:

1. If the documentation includes multiple page tabs (e.g., visual specifications, accessibility annotations, decision log), use template-multi-tab and follow the steps above.
2. Once the copy has been created, remove any unnecessary child pages by selecting its checkbox and selecting "Delete" in the top toolbar. The "Delete" option may be inside the overflow menu.

Note: Creating pages from an existing template is the recommended approach.

To create a page from scratch:

1. Navigate to ui-elements and ensure the checkbox is not selected.
2. Select "Create" in the top toolbar, then select "Page" from the dropdown.
3. In the "Create Page" step, select "Design System Page", then "Next" in the top toolbar.
4. Complete the Title and Description fields.
5. In the newly created page, open the Content Tree view in the right panel and select "Page".
6. With "Page" selected, open the Properties view in the right panel. Scroll down to the Visibility field and select "Internal" – this prevents the page from appearing in external search results on sap.com.

With the page created, update its properties:

1. Select the newly created page, ensuring its checkbox is selected, and select “Properties” in the top toolbar.
2. Update the Title field using title case.
3. In the Description field, enter the text from the "Intro" section of the guidelines.
4. Select "Save and Close" in the top toolbar.

Single page –guidelines only:

1. Select the page and its checkbox, then select "Edit" in the top toolbar.

Page with multiple tabs:

Let's use Shell Bar as an example. The Shell Bar page has two page tabs: Guidelines and Visual Specifications.

1. With the component page (Shell Bar) selected, select "Edit" in the top toolbar. From this level, only the Header element (page title and breadcrumb) and which Page Tabs are displayed can be edited.
2. To edit content within a specific tab, navigate one level deeper (e.g., to the Guidelines page), select its checkbox, then select "Edit" in the top toolbar.

Adding a new section:

1. In the Content Tree view within the right panel, select the “Main” level, then select the “Add” icon button.

Adding elements inside a section:

1. In the Content Tree view, select the “Section” level, then select the “Add” icon button.
2. Select an element from the list in the dialog.

Removing elements:

1. In the Content Tree view, right-click the element and select "Delete".

Editing content within an element:

1. Newly added elements appear empty by default.
2. With an element selected in the Content Tree view, navigate to the Properties view in the right panel to edit its content.
3. Links may not paste correctly – verify all links are working and up to date.
4. In the Content Tree view, right-click an element to duplicate, delete, or copy it.

Adding an Image element to a section:

1. In the Content Tree view, select the “Section” level, then select the “Add” icon button.
2. Select "Image" from the list in the dialog.
3. In the Content Tree view, select the Image element and navigate to the Properties view. Select the "Add" button – this will open the Content Advisor dialog.

Locating previously uploaded images:

1. In the "Repository" dropdown in the top right of the dialog, ensure "WCMS ... prod author" is selected.
2. In the left panel, navigate to the dna-design folder to locate the assets.
3. Select the image and confirm with the "Select" button in the top right of the dialog.
4. If needed, images can also be uploaded at this stage.

Adding a caption:

1. Add a new Text element below the image. Enter a short caption, setting the text style to "Paragraph" and applying italics.

The AEM Table editor is limited and requires HTML input.

The simplest approach is to copy the table as a PNG from Figma (Cmd + Shift + C), then use Claude to convert it into HTML.

Previewing content:

1. All edits are auto-saved within AEM.
2. The fastest way to preview a page is to select the "Open Page" icon button, directly to the right of the "Publish" button. It provides a relatively accurate view of the content, but certain page elements (e.g., side navigation, quick links) may not appear or work as intended.
3. To create a shareable preview link for stakeholders without AEM access, contact Isabelle Louie.

Publishing content:

1. To publish a change to the live site, contact Isabelle Louie.
2. After publication, changes may not appear immediately – a hard refresh (Cmd + Shift + R) may be required.

An in-depth guide to the Side Navigation Admin Tool can be found below:

Side Navigation Admin Tool: User Guide