a1-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

A1 Design System Migration

A1设计系统迁移

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 attention-color headlines

将Angular应用从NDBX/旧设计系统迁移至One Allianz (A1)设计系统
应用One Allianz主题（
```
spacious
```
、
```
compact
```
或
```
dense
```
）

将

nx-circle-toggle

nx-circle-toggle-group

替换为

nx-tile

nx-tile-group

将信息按钮替换为弹出框，使用新的
```
NxInfoIconComponent
```
将布局从居中对齐更新为左对齐（A1标准）
调整
```
nx-small-stage
```
组件、眉栏和醒目颜色标题

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.3" and that it's in beta phase. This is important for tracking and future updates.

如果需要CSS，添加到组件的CSS文件中。如果是独立组件，将CSS添加到
```
@Component
```
装饰器的
```
styles
```
数组中。
将样式定义写入组件样式文件。不要在HTML模板中使用内联样式。

重要提示： 开始前，请告知用户该技能版本为"0.1.3"且处于测试阶段。这对追踪和后续更新至关重要。

Step 1: Apply A1 Theme

步骤1：应用A1主题

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.

重要： 检查是否已安装

@allianz/ngx-brand-kit

包。

如果未安装，请勿尝试安装，也不要要求用户安装，跳过此步骤直接进入步骤2。
如果已安装，请按照以下步骤操作。

Procedure

操作流程

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)

Run the schematic from the project root (where

angular.json

lives):

bash

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

如果未指定主题，请询问用户想要哪种主题：
```
spacious
```
、
```
compact
```
或
```
dense
```
。

spacious适用于面向终端客户的应用，具有更多留白和更大的触控目标
compact适用于内部工具和仪表板，需要更高的信息密度
dense适用于数据密集型应用，需要最大化信息密度（如表格、分析类应用）

从项目根目录（

angular.json

所在位置）运行原理图：

bash

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

Step 2: Migrate Circle Toggles → Tiles

步骤2：将圆形切换组件迁移为卡片组件

Stack: Angular standalone components, TypeScript,

@allianz/ng-aquila

技术栈：Angular独立组件、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.

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

如果在独立组件中使用，需将

NxTileComponent, NxTileGroupComponent

添加到组件的

imports

数组中。

Decision Rules

决策规则

Scenario Action

Scenario	Action
`nx-circle-toggle` not in a group	Multi-select → use `nx-tile-group [value]="arrayOfValues"`
`nx-circle-toggle` inside `nx-circle-toggle-group`	Single-select → use `nx-tile-group [value]="selectedValue"`
`circleText` attribute present	Remove it; add `<!-- TODO: revisit once toggle-button component is available -->`

nx-circle-toggle

not in a group

Multi-select → use

nx-tile-group [value]="arrayOfValues"

nx-circle-toggle

inside

nx-circle-toggle-group

Single-select → use

nx-tile-group [value]="selectedValue"

circleText

attribute present

Remove it; add

<!-- TODO: revisit once toggle-button component is available -->

场景操作

场景	操作
`nx-circle-toggle` 不在组内	多选场景 → 使用 `nx-tile-group [value]="arrayOfValues"`
`nx-circle-toggle` 在 `nx-circle-toggle-group` 内	单选场景 → 使用 `nx-tile-group [value]="selectedValue"`
存在 `circleText` 属性	删除该属性；添加 `<!-- TODO: revisit once toggle-button component is available -->`

nx-circle-toggle

不在组内

多选场景 → 使用

nx-tile-group [value]="arrayOfValues"

nx-circle-toggle

在

nx-circle-toggle-group

内

单选场景 → 使用

nx-tile-group [value]="selectedValue"

存在

circleText

属性

删除该属性；添加

<!-- TODO: revisit once toggle-button component is available -->

Selection / Forms Pattern

选择/表单模式

Before (checked-based):

html

<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):

html

<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.

迁移前（基于选中状态）：

html

<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>

迁移后（基于组的数值）：

html

<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>

重要提示： 不要在
<nx-tile>
内部添加内容。仅使用
label
、
value
和
icon
属性。

Layout Rules

布局规则

Layout found	What to do
No wrapper, no layout CSS	Replace group directly; no extra layout needed
`nxLayout` / `nxRow` / `nxCol` grid	Derive `maxColumns` from lowest `nxCol` number: `12 ÷ lowest = maxColumns` . Remove grid wrapper.
Custom CSS	Translate to `[maxColumns]` on `nx-tile-group` ; copy CSS only if auto-grid is insufficient
2–3 tiles total	Wrap `nx-tile-group` in `nxCol="12,12,6"` (half-width)

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

现有布局	操作
无包装器，无布局CSS	直接替换组；无需额外布局
`nxLayout` / `nxRow` / `nxCol` 网格	从最小的 `nxCol` 数值推导 `maxColumns` ： `12 ÷ 最小数值 = maxColumns` 。移除网格包装器。
自定义CSS	转换为 `nx-tile-group` 上的 `[maxColumns]` ；仅当自动网格不足时才复制CSS
总计2–3个卡片	将 `nx-tile-group` 包裹在 `nxCol="12,12,6"` （半宽）中

对于每个发现的实例，输出简短的决策日志：原有内容、选择的方案及原因。

Step 3: Migrate Info Popups → new Info Icon Component

步骤3：将信息弹出框迁移为新的信息图标组件

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

html

<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.

Important: Do not change buttons inside Formfields (
```
<nx-formfield>
```
). Only replace standalone info buttons that trigger popovers.

识别带弹出框的信息按钮：查找带有弹出框触发指令（如
```
nxPopoverTrigger
```
）且内部仅包含信息图标的按钮。
替换为
NxInfoIconComponent
：使用新组件以确保样式和行为的一致性。
示例：

html

<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>

对应的导入语句：

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

如果在独立组件中使用，需将

NxInfoIconComponent

添加到组件的

imports

数组中。

重要提示： 不要更改
```
<nx-formfield>
```
内部的按钮。仅替换触发弹出框的独立信息按钮。

Step 4: Update Layout — Left Alignment

步骤4：更新布局——左对齐

A1 uses left-alignment throughout for accessibility and consistency.

A1设计系统全程使用左对齐，以提升可访问性和一致性。

Checklist

检查清单

Remove centering on rows: Change or remove
```
rowJustify="center"
```
→ use
```
rowJustify="start"
```
or remove entirely.
Remove text centering: Remove
```
class="text-center"
```
,
```
style="text-align: center"
```
, and similar on headings and paragraphs.
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"
```
  .
Margins / padding: Remove
```
margin: auto
```
, horizontal centering, and ensure content aligns to the left edge.

移除行的居中设置：修改或移除
```
rowJustify="center"
```
→ 使用
```
rowJustify="start"
```
或直接移除。
移除文本居中：移除标题和段落上的
```
class="text-center"
```
、
```
style="text-align: center"
```
及类似设置。
底部导航按钮（返回/下一步）：
- 必须右对齐（
```
rowJustify="end"
```
  ）
- 必须并排显示（在同一个
```
nxRow
```
  中，不要分开展示在不同行）
- 必须使用句首大写（"Back"、"Next"）而非全大写
- ```
nxCol
```
  仅接受数字 — 注意
```
nxCol="auto"
```
  会导致问题；使用
```
nxCol="12"
```
  、
```
nxCol="12,12,6"
```
  或类似值
- 关于
```
nxCol
```
  的说明：断点定义为
```
nxCol="<tiny>, <small>, <medium>, <large>, <xlarge>, <2xlarge>, <3xlarge>"
```
- 必须在行内垂直居中 — 如果使用
```
nxRow
```
  ，添加
```
rowAlignItems="center"
```
  。
边距/内边距：移除
```
margin: auto
```
、水平居中设置，确保内容与左边缘对齐。

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.

重要提示： 如果未安装
```
ngx-brand-kit
```
，跳过此步骤直接进入下方的「标题尺寸」部分。以下间距值依赖于A1品牌工具包中的CSS变量，因此如果未安装该工具包，请保持原有间距不变。
查找跨页面全宽的分隔线（
```
<hr>
```
、
```
nx-divider
```
、
```
nxCol="12" class="section-divider"
```
或类似元素），并在其上下添加垂直间距。使用
```
var(--semantic-gap-all-static-1600)
```
作为间距值，以确保符合A1设计标准。

独立使用的标题（不在其他组件内部）下方应添加间距。使用以下映射关系：

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)

如果标题下方的元素有顶部间距（如
```
margin-top
```
或
```
padding-top
```
），请移除该间距，或从其中减去标题的间距以避免双重间距。

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

, override the mapped value to restore the hierarchy. A page with an

h1

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.

old assignment	size attribute	use for
nxHeadline="page-bold-caps"	nxHeadline size="4xl"	huge page headlines, only for marketing pages, not for product UIs
nxHeadline="page"	nxHeadline size="3xl"	main page headlines
nxHeadline="section"	nxHeadline size="2xl"	section headlines
nxHeadline="subsection-large"	nxHeadline size="xl"	large subsection headlines
nxHeadline="subsection-medium"	nxHeadline size="l"	medium subsection headlines
nxHeadline="subsection-small"	nxHeadline size="m"	small subsection headlines
nxHeadline="subsection-xsmall"	nxHeadline size="s"	extra small subsection headlines

After applying the table, check: does the result make sense in context? A primary

<h2>

section heading should never end up at

size="s"

just because the old code used

subsection-xsmall

. Promote it to the correct level in the page hierarchy.

层级规则——适用于映射表之后，必要时覆盖映射表结果： 以下映射表为起点，而非最终结果。应用映射后，请验证最终尺寸在页面上形成清晰的视觉层级。如果主章节标题（如作为页面章节主标题的

<h2>

）映射到

或

等小尺寸，请覆盖映射值以恢复层级。例如，页面主标题

<h1>

使用

size="3xl"

时，其主

<h2>

章节应使用

size="2xl"

，子章节使用

size="xl"

，依此类推——无论旧代码中的设置是什么。

如果发现带有类型赋值的
```
nxHeadline
```
（例如
```
<h1 nxHeadline="page">
```
），请转换为
```
size
```
属性。例如，
```
<h1 nxHeadline="page">
```
变为
```
<h1 nxHeadline size="3xl">
```
。确保
```
nx-small-stage
```
中的主标题使用
```
size="3xl"
```
以符合A1设计一致性要求。

旧赋值	size属性	适用场景
nxHeadline="page-bold-caps"	nxHeadline size="4xl"	超大页面标题，仅用于营销页面，不用于产品UI
nxHeadline="page"	nxHeadline size="3xl"	主页面标题
nxHeadline="section"	nxHeadline size="2xl"	章节标题
nxHeadline="subsection-large"	nxHeadline size="xl"	大型子章节标题
nxHeadline="subsection-medium"	nxHeadline size="l"	中型子章节标题
nxHeadline="subsection-small"	nxHeadline size="m"	小型子章节标题
nxHeadline="subsection-xsmall"	nxHeadline size="s"	超小型子章节标题

应用映射表后，请检查：结果在上下文环境中是否合理？主

<h2>

章节标题绝不应因为旧代码使用

subsection-xsmall

而最终设置为

size="s"

。请将其提升至页面层级中的正确级别。

Step 5: Adjust Small Stages

步骤5：调整小型阶段组件

5.1 Subline → Eyebrow

5.1 副标题 → 眉栏

Move any

<p nxCopytext="large">Subline</p>

inside

nx-small-stage

to an eyebrow above the

<h1>

html

<nx-eyebrow size="s">Subline Text</nx-eyebrow>
<h1 nxHeadline size="3xl">...</h1>

Use the

size="s"

eyebrow size for nxHeadline size 3xl and smaller. If the user wants a nxHeadline larger than 3xl, use

size="m"

for the eyebrow.

import { NxEyebrowComponent } from '@allianz/ng-aquila/eyebrow';

If used in a Standalone Component, add the

NxEyebrowComponent

to the components

imports

array.

将

nx-small-stage

内部的任何

<p nxCopytext="large">Subline</p>

移动到

<h1>

上方的眉栏中：

html

<nx-eyebrow size="s">Subline Text</nx-eyebrow>
<h1 nxHeadline size="3xl">...</h1>

对于

nxHeadline size="3xl"

及更小的标题，使用

size="s"

的眉栏尺寸。如果用户需要大于

3xl

的

nxHeadline

，则使用

size="m"

的眉栏。

import { NxEyebrowComponent } from '@allianz/ng-aquila/eyebrow';

如果在独立组件中使用，需将

NxEyebrowComponent

添加到组件的

imports

数组中。

5.2 Partial Headline Coloring (required)

5.2 标题部分着色（必填）

Always wrap the most meaningful word or short phrase in the

<h1>

with an attention-color span. This is a required A1 design standard for

nx-small-stage

headlines — do not skip it. Choose the word or phrase that carries the most semantic weight (the product, the action, or the subject — not filler words like "your" or "and").

html

<h1 nxHeadline size="3xl">Enter your <span [nx-attention-color]="'aqua'">property details</span></h1>

import { NxAttentionColorComponent } from '@allianz/ng-aquila/text';

If used in a Standalone Component, add the

NxAttentionColorComponent

to the components

imports

array.

务必将

<h1>

中最具意义的单词或短语用醒目颜色的span包裹。这是

nx-small-stage

标题的A1设计强制标准——请勿跳过。选择承载最多语义权重的单词或短语（产品、操作或主题——而非诸如"your"或"and"之类的填充词）。

html

<h1 nxHeadline size="3xl">Enter your <span [nx-attention-color]="'aqua'">property details</span></h1>

import { NxAttentionColorComponent } from '@allianz/ng-aquila/text';

如果在独立组件中使用，需将

NxAttentionColorComponent

添加到组件的

imports

数组中。

5.3 Headline Size

5.3 标题尺寸

remove assignments to
```
nxHeadline
```
in HTML headline elements (e.g.
```
<h1 nxHeadline="page">
```
) and replace with
```
<h1 nxHeadline size="3xl">
```
for all small stage headlines. Ensure the main headline in
```
nx-small-stage
```
uses
```
size="3xl"
```
for A1 consistency.

移除HTML标题元素中的
```
nxHeadline
```
赋值（例如
```
<h1 nxHeadline="page">
```
），并替换为
```
<h1 nxHeadline size="3xl">
```
，适用于所有小型阶段组件的标题。确保
```
nx-small-stage
```
中的主标题使用
```
size="3xl"
```
以符合A1设计一致性要求。

Migration Tracking

迁移追踪

After completing each step, record the migration so adoption can be tracked across teams via GitHub search.

完成每个步骤后，请记录迁移情况，以便通过GitHub搜索跨团队追踪采用情况。

Project-level metadata in

package.json

package.json

中的项目级元数据

After Step 1 (theme applied), add an

a1Migration

key to

package.json

. After each subsequent step completes, append the step name to the

steps

array:

json

"a1Migration": {
  "skillVersion": "0.1.3",
  "appliedAt": "YYYY-MM-DD",
  "theme": "<spacious|compact|dense>",
  "steps": ["theme"]
}

Append step names as they complete:

"theme"

"tiles"

"info-icons"

"layout"

"small-stage"

A fully migrated project looks like:

json

"a1Migration": {
  "skillVersion": "0.1.3",
  "appliedAt": "YYYY-MM-DD",
  "theme": "<spacious|compact|dense>",
  "steps": ["theme", "tiles", "info-icons", "layout", "small-stage"]
}

完成步骤1（主题应用）后，在

package.json

中添加

a1Migration

键。后续每个步骤完成后，将步骤名称追加到

steps

数组中：

json

"a1Migration": {
  "skillVersion": "0.1.3",
  "appliedAt": "YYYY-MM-DD",
  "theme": "<spacious|compact|dense>",
  "steps": ["theme"]
}

完成步骤后追加步骤名称：

"theme"

、

"tiles"

、

"info-icons"

、

"layout"

、

"small-stage"

。

完全迁移后的项目示例：

json

"a1Migration": {
  "skillVersion": "0.1.3",
  "appliedAt": "YYYY-MM-DD",
  "theme": "<spacious|compact|dense>",
  "steps": ["theme", "tiles", "info-icons", "layout", "small-stage"]
}

tracking of additional migration runs

追踪额外的迁移运行

package.json

already has an

a1Migration

key, add the steps to the array for steps that ran in the current session.

如果

package.json

已存在

a1Migration

键，请将当前会话中完成的步骤添加到数组中。

a1-migration

Original

Translation

A1 Design System Migration

A1设计系统迁移

When to Use

适用场景

How to Apply Changes

如何应用更改

Step 1: Apply A1 Theme

步骤1：应用A1主题

Procedure

操作流程

Step 2: Migrate Circle Toggles → Tiles

步骤2：将圆形切换组件迁移为卡片组件

Imports

导入

Decision Rules

决策规则

Selection / Forms Pattern

选择/表单模式

Layout Rules

布局规则

Step 3: Migrate Info Popups → new Info Icon Component

步骤3：将信息弹出框迁移为新的信息图标组件

Step 4: Update Layout — Left Alignment

步骤4：更新布局——左对齐

Checklist

检查清单

Vertical Spacing Adjustments

垂直间距调整

Headline Sizes

标题尺寸

Step 5: Adjust Small Stages

步骤5：调整小型阶段组件

5.1 Subline → Eyebrow

5.1 副标题 → 眉栏

5.2 Partial Headline Coloring (required)

5.2 标题部分着色（必填）

5.3 Headline Size

5.3 标题尺寸

Migration Tracking

迁移追踪

Project-level metadata in package.json

package.json中的项目级元数据

tracking of additional migration runs

追踪额外的迁移运行

Project-level metadata in
`package.json`

`package.json`
中的项目级元数据