# NL 设计系统

## NL 设计系统 界面预览

切换原始主题，编辑集合位置，保存或取消，且不更改记录。

## NL 设计系统 设计参考

具体的贡献者组合：@utrecht/component-library-css 9.0.15。公开的令牌名称和类名属于经过检查的库 API；标注为“example”的数值和颜色是应用自身的设置，并非通用的 NL Design System 规范。

### 架构

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| Component implementation | Utrecht CSS 9.0.15 | 这是一个选定的贡献者实现，并非唯一的 NL Design System 实现。 |
| Theme boundary | Wrapper-scoped CSS custom properties | 相同的语义化标记支持多种品牌形象。 |
| Source design tokens | Design Tokens JSON standard | 各组织会说明自己的品牌样式，供他人复用。 |
### 真实的按钮令牌 API

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --utrecht-button-min-block-size | 48px in example; 44px library fallback | 明确设置目标尺寸。 |
| --utrecht-button-border-radius | 4px / 8px in example themes | 由应用设置的几何属性。 |
| --utrecht-button-primary-action-background-color | #005a5b / #57328c in example themes | 自定义的操作颜色；前景色为白色。 |
| --utrecht-button-font-size | 1rem in example | 组件文本角色。 |
| --utrecht-focus-outline-width | 3px in example | 公开的焦点环配置。 |
### 数据列表 API

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| .utrecht-data-list + .utrecht-data-list--rows | dl root | 具有语义含义的命名值。 |
| .utrecht-data-list__item | Key/value wrapper | 响应式网格行。 |
| --utrecht-data-list-rows-column-min-inline-size | 12ch in example | 为收据标签选择的最小列宽。 |
| --utrecht-data-list-rows-column-inline-size | 45% in example | 空间足够时显示两列。 |
| --utrecht-data-list-rows-gap | 24px in example | 键和值之间的间距。 |
## NL 设计系统 完整指南

实用指南，介绍如何为真实界面选择、应用和评审此系统。

完整指导、实现起点和源代码链接。

## NL 设计系统 选择一种组合

### 这是一个生态系统，而非单一主题

> NL Design System 明确支持组合来自多个组织的贡献，同时通过设计令牌描述各组织的品牌样式。因此，实际采用的基本单元是选定的组件实现加选定的主题。本页选择 Utrecht CSS 贡献者实现，并搭配自定义的演示主题。

这个选择并不意味着 Utrecht 是所有 NL Design System 组件的规范实现。它为读者提供了一条可复现的路径，同时避免凭空设定全国通用的字体、蓝色或间距比例。此处使用的原生 CSS 软件包是 @utrecht/component-library-css 9.0.15。

阅读配套规范

## NL 设计系统 公开组件令牌

### 将应用值与库的 CSS 分开

所提供的主题会在包装元素上设置公开的 --utrecht-* 自定义属性。按钮会使用这些值，而类名决定组件的结构。以 --_utrecht- 开头的变量是经过检查的 CSS 中的内部计算值；直接修改这些变量会使应用依赖实现细节。

示例中的青绿色 #005a5b 和紫色 #57328c 是应用自定义的颜色，用于展示可替换的品牌样式，且不会照搬市政机构的品牌形象。两种颜色的操作文本均为白色，悬停色则单独定义。没有任何颜色被描述为官方 NL Design System 令牌值。

```
.example-theme {
  /* Original application values, not a national house style. */
  --utrecht-document-font-family: Arial, sans-serif;
  --utrecht-button-font-size: 1rem;
  --utrecht-button-line-height: 1.5;
  --utrecht-button-font-weight: 700;
  --utrecht-button-border-radius: .25rem;
  --utrecht-button-min-block-size: 48px;
  --utrecht-button-padding-block-start: .75rem;
  --utrecht-button-padding-block-end: .75rem;
  --utrecht-button-padding-inline-start: 1.25rem;
  --utrecht-button-padding-inline-end: 1.25rem;
  --utrecht-button-primary-action-background-color: #005a5b;
  --utrecht-button-primary-action-color: #fff;
  --utrecht-button-primary-action-hover-background-color: #003f40;
  --utrecht-button-primary-action-hover-color: #fff;
  --utrecht-focus-outline-color: #111;
  --utrecht-focus-outline-width: 3px;
  --utrecht-focus-outline-offset: 3px;
  --utrecht-focus-outline-style: solid;
}
```

代码参考

阅读配套规范

## NL 设计系统 字体排版与尺寸

### 补齐主题中缺少的设置

示例为文档阅读设置了 Arial, sans-serif 字体、18px 字号和 1.6 倍行高。第一个主题使用 32px 标题和 4px 按钮圆角；第二个主题采用相同的易读正文尺寸、8px 圆角和衬线标题。这些主题变化经过刻意设计，效果一目了然。

如果未设置令牌，原生按钮会将 44px 作为块尺寸的最小回退值。我们的主题将其设为 48px，并明确指定块向和行内向内边距。这是一个真实的 CSS API，其取值由应用自行选择，而不是臆测适用于整个生态系统的尺寸。布局的内容最大宽度为 56rem，间距为 24px，均由此示例设置。

阅读配套规范

## NL 设计系统 数据列表结构

### 用于命名值的定义列表

收据使用 dl、.utrecht-data-list 和 .utrecht-data-list--rows 修饰类。每个 .utrecht-data-list__item 都包含一个 dt 键和一个 dd 值。rows 修饰类会启用响应式网格、行间距和边框；如果不使用它，基础数据列表不会启用这种布局。即使尚未加载主题，HTML 仍具有语义。

收据列出了领取地点、参考编号和所选商品。这不是由重复记录组成的表格：每个键对应同一请求中的不同属性。窄屏下，键和值会垂直排列。应用会设置行令牌，让较长的地点名称能够完整显示，不会被裁切。

- 使用 dt 表示属性名称，使用 dd 表示当前值。

- 将每组键值对放入文档规定的项目包装元素中。

- 允许标识符和较长的地点名称换行，避免页面宽度被撑大。

阅读配套规范

## NL 设计系统 操作语义

### 按钮类名本身不会提供工作流程

.utrecht-button 提供基础组件，.utrecht-button--primary-action 则选择主要操作的外观令牌组。对于不应提交外层表单的本地操作，原生元素仍需设置 type=button。在应用打开编辑面板之前，数据列表保持只读。

在示例中，点击“更改领取地点”按钮会显示一组原生单选按钮。保存后，定义列表中的值会更新，并通过礼貌提示区域播报新的领取地点。取消操作会关闭面板，但不会更改已保存的值。这些行为由应用代码实现；仅安装 CSS 软件包并不会自动提供这些功能。

阅读配套规范

## NL 设计系统 安全切换主题

### 更改包装元素，保留记录

主题选择器会更改外层包装元素上的 data-theme。组件类名、记录值和选中的单选项都保持不变。这具体展示了白标分离：同一张收据和同一交互可以采用不同的视觉形象。

此处的主题切换仅用于演示开发过程，并非公共服务必须提供的设置。在真正的多组织服务中，应根据可信的应用配置选择主题。主题值不应影响资格认定、验证或状态的含义。

1. 只加载一次带版本号的组件 CSS。

2. 将相关主题令牌应用于外层元素。

3. 在该容器内渲染相同的语义化组件标记。

4. 验证每种受支持主题下的焦点状态、文本换行和状态颜色。

阅读配套规范

## NL 设计系统 无障碍性与成熟度

### 评估选定的贡献

NL Design System 接力模型说明了各项贡献如何逐步发展为共享标准。组件出现在社区代码库中，并不意味着任何组合都已达到生产就绪状态。请依据组件文档，核实所选实现、支持的状态和当前成熟度。

预览会持续显示位置选项的图例，在保存结果后播报更新，并在编辑完成后将焦点返回到触发按钮。切换主题不会移除焦点。用户仍可使用原生单选按钮的键盘控件和应用自身的焦点轮廓进行操作；这些检查是对组件贡献者测试的补充，而非替代。

阅读配套规范

## NL 设计系统 安装并管理主题

### 仅集成 CSS

安装经过验证的 CSS 软件包，并通过支持 CSS 的打包工具导入 dist/index.css，然后导入主题样式表。此处使用的仅限 CSS 的数据列表和按钮无需 React 提供程序或 JavaScript 组件初始化程序。原有应用脚本负责编辑、保存、取消和切换主题。

打包后的组件源代码采用 EUPL-1.2 许可证。分发时请保留源代码和许可证声明；代码许可证不意味着可以复用市政机构的徽标。本示例特意使用原创主题，不含任何市政标识。

阅读配套规范

## NL 设计系统组件示例

### 原生按钮使用的主题令牌

完整的选中按钮主题。数值为原创；API 名称来自 Utrecht。

```
.example-theme {
  /* Original application values, not a national house style. */
  --utrecht-document-font-family: Arial, sans-serif;
  --utrecht-button-font-size: 1rem;
  --utrecht-button-line-height: 1.5;
  --utrecht-button-font-weight: 700;
  --utrecht-button-border-radius: .25rem;
  --utrecht-button-min-block-size: 48px;
  --utrecht-button-padding-block-start: .75rem;
  --utrecht-button-padding-block-end: .75rem;
  --utrecht-button-padding-inline-start: 1.25rem;
  --utrecht-button-padding-inline-end: 1.25rem;
  --utrecht-button-primary-action-background-color: #005a5b;
  --utrecht-button-primary-action-color: #fff;
  --utrecht-button-primary-action-hover-background-color: #003f40;
  --utrecht-button-primary-action-hover-color: #fff;
  --utrecht-focus-outline-color: #111;
  --utrecht-focus-outline-width: 3px;
  --utrecht-focus-outline-offset: 3px;
  --utrecht-focus-outline-style: solid;
}
```

代码参考

### 命名值和编辑触发按钮

使用语义化的 dl/dt/dd 和贡献者组件类。

```
<dl class="utrecht-data-list utrecht-data-list--rows">
  <div class="utrecht-data-list__item">
    <dt class="utrecht-data-list__item-key">Collection location</dt>
    <dd class="utrecht-data-list__item-value">North library desk</dd>
  </div>
  <div class="utrecht-data-list__item">
    <dt class="utrecht-data-list__item-key">Reference</dt>
    <dd class="utrecht-data-list__item-value">DEMO-2048</dd>
  </div>
</dl>
<button type="button" class="utrecht-button utrecht-button--primary-action">
  Change collection location
</button>
```

代码参考

### 完整的独立示例

完整文档包含其布局、控件与初始化。解压所链接的示例归档，即可获得完全一致的相对 vendor 资源，然后通过 HTTP 提供服务。

```
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>NL Design System composition</title><link rel="stylesheet" href="vendor/utrecht-9.0.15/index.css"><style>.example-theme {
  /* Original application values, not a national house style. */
  --utrecht-document-font-family: Arial, sans-serif;
  --utrecht-button-font-size: 1rem;
  --utrecht-button-line-height: 1.5;
  --utrecht-button-font-weight: 700;
  --utrecht-button-border-radius: .25rem;
  --utrecht-button-min-block-size: 48px;
  --utrecht-button-padding-block-start: .75rem;
  --utrecht-button-padding-block-end: .75rem;
  --utrecht-button-padding-inline-start: 1.25rem;
  --utrecht-button-padding-inline-end: 1.25rem;
  --utrecht-button-primary-action-background-color: #005a5b;
  --utrecht-button-primary-action-color: #fff;
  --utrecht-button-primary-action-hover-background-color: #003f40;
  --utrecht-button-primary-action-hover-color: #fff;
  --utrecht-focus-outline-color: #111;
  --utrecht-focus-outline-width: 3px;
  --utrecht-focus-outline-offset: 3px;
  --utrecht-focus-outline-style: solid;
}
*{box-sizing:border-box}body{margin:0}.example-theme{font:18px/1.6 Arial,sans-serif;color:#222;--accent:#005a5b;--wash:#eef6f4;--utrecht-data-list-rows-column-min-inline-size:12ch;--utrecht-data-list-rows-column-inline-size:45%;--utrecht-data-list-rows-gap:24px;--utrecht-data-list-rows-border-bottom-width:1px;--utrecht-data-list-rows-border-bottom-color:#ccd4d2;--utrecht-data-list-rows-item-padding-block-start:16px;--utrecht-data-list-rows-item-padding-block-end:16px;--utrecht-data-list-item-key-font-weight:700;--utrecht-data-list-item-value-line-height:1.6}.example-theme[data-theme=plum]{--accent:#57328c;--wash:#f5effa;--utrecht-button-primary-action-background-color:#57328c;--utrecht-button-primary-action-hover-background-color:#3c2262;--utrecht-button-border-radius:8px}.example-theme[data-theme=plum] h1{font-family:Georgia,serif}.toolbar{background:var(--wash);padding:20px 24px;border-bottom:4px solid var(--accent);display:flex;gap:16px;align-items:center;justify-content:space-between;flex-wrap:wrap}.toolbar label{font-size:16px}.toolbar select{font:inherit;max-width:100%;padding:8px}article{max-width:56rem;margin:auto;padding:32px 24px}h1{font-size:32px;line-height:1.3;margin:8px 0 24px}h2{font-size:24px}p{margin:16px 0}.utrecht-data-list__item-value{margin:0;overflow-wrap:anywhere}.utrecht-button{margin-block:8px}.editor{background:var(--wash);padding:24px;margin-block:24px}fieldset{border:0;padding:0;margin:0}legend{font-size:22px;font-weight:700;margin-bottom:16px}.choice{display:flex;align-items:center;gap:12px;padding:12px 0}.choice input{width:24px;height:24px;accent-color:var(--accent)}.buttons{display:flex;gap:24px;flex-wrap:wrap;align-items:center}.cancel{font:inherit;background:none;border:0;text-decoration:underline;min-height:48px;color:var(--accent);cursor:pointer}small{display:block;font-size:14px;margin-top:32px;color:#555}:focus-visible{outline:3px solid #111;outline-offset:3px}[hidden]{display:none!important}#notice{font-weight:700;color:var(--accent)}@media(max-width:600px){.example-theme{--utrecht-data-list-rows-column-min-inline-size:100%;}h1{font-size:28px}.toolbar{align-items:flex-start;flex-direction:column}.editor{padding:16px}}
</style><main class="example-theme" data-theme="teal"><div class="toolbar"><strong>Community collection · Example</strong><label>Original theme <select id="theme"><option value="teal">Teal</option><option value="plum">Plum</option></select></label></div><article><p>CONTRIBUTOR COMPONENTS + YOUR THEME</p><h1>Review your collection details</h1><p>This receipt uses Utrecht CSS components. Switching the theme changes public design tokens and preserves your choices.</p><dl class="utrecht-data-list utrecht-data-list--rows"><div class="utrecht-data-list__item"><dt class="utrecht-data-list__item-key">Item</dt><dd class="utrecht-data-list__item-value">Community reading pack</dd></div><div class="utrecht-data-list__item"><dt class="utrecht-data-list__item-key">Collection location</dt><dd class="utrecht-data-list__item-value" id="location">North library desk</dd></div><div class="utrecht-data-list__item"><dt class="utrecht-data-list__item-key">Reference</dt><dd class="utrecht-data-list__item-value">DEMO-2048</dd></div></dl><button id="edit" type="button" class="utrecht-button utrecht-button--primary-action">Change collection location</button><form class="editor" hidden><fieldset><legend>Choose a collection location</legend><label class="choice"><input type="radio" name="place" value="North library desk" checked>North library desk</label><label class="choice"><input type="radio" name="place" value="Riverside community room">Riverside community room</label><label class="choice"><input type="radio" name="place" value="Central welcome counter">Central welcome counter</label></fieldset><div class="buttons"><button class="utrecht-button utrecht-button--primary-action" type="submit">Save location</button><button type="button" class="cancel" id="cancel">Cancel</button></div></form><p id="notice" role="status"></p><small>Independent OpenDesign specimen. Utrecht CSS 9.0.15; original themes and fictional data. No municipal identity or external submission.</small></article></main><script>
const main=document.querySelector('main'),theme=document.querySelector('#theme'),edit=document.querySelector('#edit'),form=document.querySelector('form'),locationText=document.querySelector('#location'),notice=document.querySelector('#notice');let saved=locationText.textContent;theme.onchange=()=>main.dataset.theme=theme.value;edit.onclick=()=>{form.hidden=false;edit.hidden=true;notice.textContent='';[...form.elements.place].forEach(r=>r.checked=r.value===saved);form.querySelector(':checked').focus()};function close(){form.hidden=true;edit.hidden=false;edit.focus()}form.onsubmit=e=>{e.preventDefault();saved=form.elements.place.value;locationText.textContent=saved;notice.textContent='Collection location updated to '+saved+'.';close()};document.querySelector('#cancel').onclick=()=>{notice.textContent='No changes saved.';close()};
</script></html>
```

代码参考

- 从“来源”一节下载完整示例。其 README 给出了确切的本地启动命令。

- 保持 vendor 路径相对于本文档；该归档包含此预览所使用的全部资源。

## NL 设计系统 AI Agent 设置

### 实现起点

独立预览会在本地加载同一版本的原生 CSS。仅使用 CSS 按钮和数据列表组件无需 React 提供程序。必须同时提供原创主题值。Sources 中的完整可运行示例 ZIP 还提供了预览所需的准确依赖项和完整文档。将其解压到目录中，在该目录运行 python3 -m http.server 8080，然后打开 http://localhost:8080/nl-design-system.html。请勿通过 file:// 打开基于模块的示例。

```
npm install @utrecht/component-library-css@9.0.15
# CSS-aware application entry:
# import '@utrecht/component-library-css/dist/index.css';
# import './example-theme.css';
# Wrap the dl/button composition in <main class="example-theme">.
# Add application event handlers for editing and theme selection.
```

### 适用于你项目的提示词

```
使用 @utrecht/component-library-css 9.0.15 创建收据定义列表和主按钮。通过公开的 --utrecht-* 令牌提供作用域限定在原创包装元素内的主题，并保持内部 --_utrecht-* 变量不变。通过带标签的单选选项、保存/取消操作、礼貌的更新播报和焦点返回功能来编辑位置。展示第二个原创主题，同时不替换组件标记或丢失数据。所有数值主题值都应标明为应用自选。
```

## NL 设计系统 来源与范围

NL Design System 是一个不依附于任何品牌的生态系统。本教学示例选用一种贡献者实现和两个原创主题；它不宣称代表某种全国性视觉风格，也不使用任何市政机构的形象标识。

- 生态系统概览 公共服务共享设计资源与社区背景。

- 开发者介绍 组件、组织主题与设计令牌架构。

- 组件目录 浏览有文档说明的组件及其可用参考资料。

- 下载完整可运行示例 包含完整 HTML、本地 CSS/JavaScript 依赖、随附许可证以及确切启动说明的 ZIP 包。无需构建步骤。

## NL 设计系统 相关资源

### NSW 设计系统

通过完整的工作坊指南和独立的本地阅读清单，了解 NSW 设计令牌、Public Sans 字体排版，以及支持键盘操作的原生标签页。

### ONS 设计系统

构建一个前后不会矛盾的调查问卷：使用 ONS 原生复选框、互斥选项、准确的字体和颜色引用，以及完整的本地回顾流程。

### Ontario 设计系统

构建一份安大略风格的长篇指南，采用真实的字体排印、已发布的间距和颜色值、原生手风琴交互，以及与版本完全匹配的完整源代码。


- [实现参考](https://github.com/nl-design-system/utrecht)
- [来源](https://www.nldesignsystem.nl/handboek/developer/introductie/)
- [来源](https://github.com/nl-design-system/utrecht/tree/main/packages/button)
- [来源](https://github.com/nl-design-system/utrecht/tree/main/packages/data-list)
- [阅读配套规范](https://www.nldesignsystem.nl/handboek/developer/introductie/)
- [代码参考](https://github.com/nl-design-system/utrecht/tree/main/packages/button)
- [阅读配套规范](https://github.com/nl-design-system/utrecht/tree/main/packages/button)
- [阅读配套规范](https://github.com/nl-design-system/utrecht/tree/main/packages/component-library-css)
- [阅读配套规范](https://github.com/nl-design-system/utrecht/tree/main/packages/data-list)
- [阅读配套规范](https://www.nldesignsystem.nl/handboek/estafettemodel/)
- [代码参考](https://github.com/nl-design-system/utrecht/tree/main/packages/data-list)
- [代码参考](https://github.com/nl-design-system/utrecht)
- [生态系统概览 公共服务共享设计资源与社区背景。](https://www.nldesignsystem.nl/)
- [开发者介绍 组件、组织主题与设计令牌架构。](https://www.nldesignsystem.nl/handboek/developer/introductie/)
- [组件目录 浏览有文档说明的组件及其可用参考资料。](https://www.nldesignsystem.nl/componenten/)