allianz/ng-aquila/a1-migration

A1 Design System Migration

When to Use

• Migrating an Angular app from NDBX/old design system to One Allianz (A1) Design System
• Applying One Allianz theme (spacious, compact, or dense)
• Replacing nx-circle-toggle / nx-circle-toggle-group with nx-tile / nx-tile-group
• Replacing info buttons with popovers to use the new NxInfoIconComponent
• Updating layout from center-aligned to left-aligned (A1 standard)
• Adjusting nx-small-stage components, eyebrows and accent-color headlines

How to Apply Changes

• if css is required, add to the component's CSS file. If the component is standalone, add the CSS to the component's styles array in the @Component decorator.
• write style definitions into components style file. Do not use inline styles in the HTML template.

IMPORTANT: Before starting, tell the user the skill version "0.1.5" and that it's in beta phase. This is important for tracking and future updates.

Step 1: Apply A1 Theme

Important: check if package @allianz/ngx-brand-kit is installed.

• if not installed, do not try to install, do not ask the user to install and skip this step and continue with Step 2.
• if installed, continue with the Procedure as described below.

Procedure

1. If theme is not specified, ask the user which theme they want: spacious, compact, or dense.

• spacious for end customer-facing apps with more white space and larger touch targets
• compact for internal tools and dashboards where more information density is needed
• dense for data-heavy applications where maximum information density is required (e.g. tables, analytics)

1. Run the schematic from the project root (where angular.json lives):

``bash ng g @allianz/ngx-brand-kit:apply-a1-theme --type=<THEME> ``

Step 2: Migrate Circle Toggles → Tiles

Stack: Angular standalone components, TypeScript, @allianz/ng-aquila

Imports

import { NxTileComponent, NxTileGroupComponent } from '@allianz/ng-aquila/tile';

If used in a Standalone Component, add the NxTileComponent, NxTileGroupComponent to the components imports array.

Decision Rules

Selection / Forms Pattern

Before (checked-based):

<nx-circle-toggle-group>
  <nx-circle-toggle
    [checked]="sel==='a'"
    value="a"
    label="Label A"
    icon="icon-name"
  ></nx-circle-toggle>
  <nx-circle-toggle
    [checked]="sel==='b'"
    value="b"
    label="Label B"
    icon="icon-name"
  ></nx-circle-toggle>
</nx-circle-toggle-group>

After (value-based on group):

<nx-tile-group [value]="sel">
  <nx-tile value="a" label="Label A" icon="icon-name"></nx-tile>
  <nx-tile value="b" label="Label B" icon="icon-name"></nx-tile>
</nx-tile-group>

IMPORTANT: Do NOT put content inside <nx-tile>. Use only label, value, and icon attributes.

Layout Rules

For each occurrence found, output a short decision log: what was there, what you chose and why.

Step 3: Migrate Info Popups → new Info Icon Component

1. Identify info buttons with popups: look for buttons (e.g. buttons with directive nxPopoverTrigger) that trigger popovers and just have an info icon inside.
2. Replace with `NxInfoIconComponent`: use the new component for consistent styling and behavior.
3. Example:

<nx-info-icon
  nxFormfieldAppendix
  buttonAriaLabel="Additional information"
  popoverDirection="bottom"
  popoverWidth="300px"
>
  <span>
    This is an info icon with a popover. Click the icon to see additional information. Sadipscing
    elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
    voluptua.
  </span>
</nx-info-icon>

And the corresponding import:

import { NxInfoIconComponent } from '@allianz/ng-aquila/info-icon';

If used in a Standalone Component, add the NxInfoIconComponent to the components imports array.

1. Important: For info buttons inside a Formfield (<nx-formfield>), do NOT use this standalone

<nx-info-icon> replacement — migrate them with Step 3.1 below instead. This step (Step 3) only covers standalone info buttons that trigger popovers outside of a formfield.

Step 3.1: Formfield info icons → nxLabelInfo projection slot

Formfields expose a content-projection slot for the label info icon: project an info-icon component into the formfield and mark it with the nxLabelInfo directive. It renders next to the label (in A1, where the label is permanently floated). Migrate the old workaround — an info-icon/popover manually placed in the formfield's nxFormfieldAppendix slot — to this slot.

1. Identify: an <nx-formfield> that contains, in its nxFormfieldAppendix slot, either

• an existing <nx-info-icon nxFormfieldAppendix>…</nx-info-icon>, or
• a button with nxPopoverTrigger (or [nxPopoverTriggerFor]) holding an info icon (e.g.

<nx-icon name="info-circle-o">) whose popover just explains the field.

1. Replace: put an <nx-info-icon nxLabelInfo>…</nx-info-icon> inside the formfield with the help

content projected directly (plain text or structured markup). Remove the old appendix button/popover markup. Because the info icon is now a projected component, you keep full control over its API (popoverDirection, popoverWidth, popoverModal, buttonAriaLabel, …) directly on the element — and you can project a custom/entity-specific info-icon implementation into the same slot.

1. Works with a custom label too: the slot renders the icon regardless of whether the label comes

from the label string input or a projected <nx-formfield-label>. Do not move the info content into <nx-formfield-label>.

Before (appendix workaround — button + popover):

<nx-formfield label="Email">
  <input nxInput [(ngModel)]="email" />
  <button
    nxFormfieldAppendix
    nxIconButton="tertiary small"
    [nxPopoverTriggerFor]="emailInfo"
    nxPopoverTrigger="click"
    type="button"
    aria-label="More information"
  >
    <nx-icon name="info-circle-o" size="s" aria-hidden="true"></nx-icon>
  </button>
</nx-formfield>
 
<nx-popover #emailInfo>
  <div style="max-width: 300px">We only use your email to send policy documents.</div>
</nx-popover>

After (string content):

<nx-formfield label="Email">
  <input nxInput [(ngModel)]="email" />
  <nx-info-icon nxLabelInfo>We only use your email to send policy documents.</nx-info-icon>
</nx-formfield>

After (structured content, projected directly — no `ng-template` needed):

<nx-formfield label="Email">
  <input nxInput [(ngModel)]="email" />
  <nx-info-icon nxLabelInfo>
    <p nxCopytext>We only use your email to send policy documents.</p>
    <a nxLink href="/privacy">Privacy policy</a>
  </nx-info-icon>
</nx-formfield>

Add the info-icon import (and, in a standalone component, add it to imports). The nxLabelInfo directive ships with the label/formfield modules:

import { NxInfoIconComponent } from '@allianz/ng-aquila/info-icon';

Note: the manual nxFormfieldAppendix slot still works and is not removed from the framework — but prefer the nxLabelInfo slot for field-level help so the icon aligns with the label consistently in A1.

Convention: content projection over pass-through inputs

When wrapping one component inside another, prefer content projection over adding pass-through inputs. Do not mirror a child component's inputs onto its wrapper (e.g. there is deliberately no infoIconContent input on the formfield) — project the child (<nx-info-icon nxLabelInfo>) and let it own its own API. This keeps a single authoring model, avoids the wrapper drifting out of sync with the child, and lets consumers swap in their own implementation. Reserve @Input() for scalar configuration the component itself owns with a closed set of options (size, disabled, label).

Step 4: Update Layout — Left Alignment

A1 uses left-alignment throughout for accessibility and consistency.

Checklist

1. Remove centering on rows: Change or remove rowJustify="center" → use rowJustify="start" or remove entirely.
2. Remove text centering: Remove class="text-center", style="text-align: center", and similar on headings and paragraphs.
3. Bottom navigation buttons (Back / Next):

• Must be right-aligned (rowJustify="end")
• Must be side-by-side (same nxRow, not stacked in separate rows)
• Must use sentence case ("Back", "Next") not ALL CAPS
• nxCol only accepts numbers — warning nxCol="auto" will break; use nxCol="12", nxCol="12,12,6" or similar
• info on nxCol: breakpoints are defined as nxCol="<tiny>, <small>, <medium>, <large>, <xlarge>, <2xlarge>, <3xlarge>"
• must be vertically centered within the row — if nxRow is used, add rowAlignItems="center".

1. Margins / padding: Remove margin: auto, horizontal centering, and ensure content aligns to the left edge.

Vertical Spacing Adjustments

• Important: Skip this step if the ngx-brand-kit is not installed and continue with Headline Sizes below. The spacing values below rely on CSS variables from the A1 brand kit, so if it's not installed, leave spacing as-is.
• Find Dividers (<hr>, nx-divider, nxCol="12" class="section-divider" or similar) divider lines that span the full width of the page and add vertical spacing above and below them. Use var(--semantic-gap-all-static-1600) for this spacing to ensure consistency with A1 design standards.
• Headlines that are used standalone (outside of other components) should have a spacing below them. Use the mapping below
• nxHeadline size="3xl" → var(--semantic-gap-all-static-1200)
• nxHeadline size="2xl" → var(--semantic-gap-all-static-1000)
• nxHeadline size="xl" → var(--semantic-gap-all-static-800)
• If the element underneath the headline has a top spacing (e.g. margin-top or padding-top), remove it to avoid double spacing or subtract the headline spacing from it.

Headline Sizes

Hierarchy rule — applies after the mapping table and overrides it where needed: The mapping table below is a starting point, not a final answer. After applying it, verify that the resulting sizes form a clear visual hierarchy on the page. If a primary section heading (e.g. an <h2> that is the main title of a page section) maps to a small size like s or m, override the mapped value to restore the hierarchy. A page with an h1 at size="3xl" should use size="2xl" for its primary h2 sections, size="xl" for sub-sections, and so on — regardless of what the old assignment was.

• if you find nxHeadline with type assignments (e.g. <h1 nxHeadline="page"> ), translate to size attribute. For example, <h1 nxHeadline="page"> becomes <h1 nxHeadline size="3xl">. Ensure the main headline in nx-small-stage uses size="3xl" for A1 consistency.