# UNDP 设计系统

## UNDP 设计系统 界面预览

使用方向键导航、查看各部分，并重置本地阅读计数。

## UNDP 设计系统 设计参考

取自公开发布的 @undp/design-system-assets 2.0.2 的具体数值与行为。原创建页布局和进度行为已另行标明。

### 配色与语义界面表面

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --undpds-color-blue-600 | #006eb5 | 采用公开软件包中的实际值。示例将蓝色用于编辑内容的引导部分，将黄色用于辅助阅读卡片；这些内容映射为原创。 |
| --undpds-color-blue-700 | #1f5a95 | 采用公开软件包中的实际值。示例将蓝色用于编辑内容的引导部分，将黄色用于辅助阅读卡片；这些内容映射为原创。 |
| --undpds-color-gray-200 | #f7f7f7 | 采用公开软件包中的实际值。示例将蓝色用于编辑内容的引导部分，将黄色用于辅助阅读卡片；这些内容映射为原创。 |
| --undpds-color-gray-300 | #edeff0 | 采用公开软件包中的实际值。示例将蓝色用于编辑内容的引导部分，将黄色用于辅助阅读卡片；这些内容映射为原创。 |
| --undpds-color-gray-700 | #232e3d | 采用公开软件包中的实际值。示例将蓝色用于编辑内容的引导部分，将黄色用于辅助阅读卡片；这些内容映射为原创。 |
| --undpds-color-yellow-600 | #fbc412 | 采用公开软件包中的实际值。示例将蓝色用于编辑内容的引导部分，将黄色用于辅助阅读卡片；这些内容映射为原创。 |
| --undpds-color-dark-red | #d12800 | 采用公开软件包中的实际值。示例将蓝色用于编辑内容的引导部分，将黄色用于辅助阅读卡片；这些内容映射为原创。 |
| --undpds-color-background-default | #fff | 采用公开软件包中的实际值。示例将蓝色用于编辑内容的引导部分，将黄色用于辅助阅读卡片；这些内容映射为原创。 |
| --undpds-color-border-default | #000 | 采用公开软件包中的实际值。示例将蓝色用于编辑内容的引导部分，将黄色用于辅助阅读卡片；这些内容映射为原创。 |
### 当前间距比例

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --undpds-spacing-002 | 2px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-004 | 4px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-008 | 8px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-012 | 12px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-016 | 16px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-024 | 24px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-032 | 32px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-040 | 40px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-048 | 48px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-064 | 64px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-080 | 80px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-096 | 96px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
| --undpds-spacing-160 | 160px | 按原样使用导出的名称。组件 CSS 也保留了旧版数字别名；不要根据别名后缀推断数值。 |
### 字体与边框参考

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| --undpds-font-family-proximanova | ProximaNova,sans-serif | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
| --undpds-font-family-sohnebreit | SohneBreit,ProximaNova,sans-serif | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
| --undpds-font-size-14 | 0.875rem | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
| --undpds-font-size-16 | 1rem | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
| --undpds-font-size-20 | 1.25rem | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
| --undpds-font-size-24 | 1.5rem | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
| --undpds-font-size-32 | 2rem | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
| --undpds-font-size-40 | 2.5rem | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
| --undpds-font-weight-regular | 400 | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
| --undpds-font-weight-bold | 700 | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
| --undpds-border-default | 2px | 这些是已发布的声明，并不表示此预览会加载品牌字体。预览有意使用 Arial 作为回退字体。 |
### 原生选项卡的结构与行为

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| data-undpds-component | tabs | 标记由 tabs() 扫描的根元素。 |
| Tab collection | .tabs-title[role="tab"] | 示例使用可聚焦的列表项及对应面板；原生初始化会设置 ID 和 aria-controls。 |
| Panels | .tabs-content > .tabs-panel | 每个选项卡对应一个面板，顺序一致；每个面板都有稳定且唯一的 ID。 |
| Deep links | data-deep-link="false" | 切换部分时，避免嵌入式示例修改 URL 哈希。 |
| Keyboard | Arrow keys, Home, End, Enter, Space | 原生脚本会移动焦点，并激活对应面板。 |
| State | aria-selected, tabindex, hidden, aria-hidden | 初始化和选择操作都会更新语义属性及面板的实际可见状态。 |
## UNDP 设计系统 完整指南

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

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

## UNDP 设计系统 UNDP 运行时与资源边界

### 为静态页面选择资源包

> 提供的示例安装了版本为 2.0.2 的 @undp/design-system-assets。该发行包包含基础 CSS、组件 CSS 和浏览器脚本；这与从头运行完整的 Storybook 开发仓库不同。此组合只需要基础样式表、选项卡样式表和选项卡脚本。加载 all.min.js 或所有组件样式表只会引入无关行为，并不能改善阅读界面。

- base-minimal.min.css 提供基础样式和字体排印声明。

- components/tab.min.css 提供原生选项卡样式。

- js/tabs.min.js 导出 tabs() 初始化函数。

### 明确区分机构品牌形象与示例内容

这份简报是原创的 OpenDesign 本地工作坊规划练习内容，并非联合国开发计划署（UNDP）的项目、政策声明或报告门户。预览中不含徽章或机构导航。我们会准确标明原生样式与行为，同时清楚说明简报、复选框进度和重置操作均为原创应用代码。

## UNDP 设计系统 UNDP 设计系统的颜色角色与编辑层级

### 围绕实际的蓝色色阶构建

已发布的 --undpds-color-blue-600 为 #006eb5，blue-700 为 #1f5a95。示例将前者用作重点区块的背景，后者用于重置操作。gray-200 为辅助卡片提供克制的背景，gray-300 用于分隔标签页，yellow-600 则增添边框强调色。当前标签页使用库中定义的深红色下划线。这些角色都能在所提供的 CSS 中直接查看，而不是根据截图推测。

### 不要把 SDG 颜色赋予臆造的状态含义

基础软件包除通用颜色令牌外，还包含独立的 SDG 配色。开发主题页面不应仅因这些颜色可用，就把它们随意指定为成功或错误状态。在此版式中，完成状态通过已勾选的控件和清晰易读的计数来表达，不依赖颜色传递状态。

## UNDP 设计系统 UNDP 设计系统的排版、间距与字体范围

### 区分字体声明与已加载字体

软件包声明了 ProximaNova 和 SohneBreit 字体系列，并包含字体文件，但此预览有意使用 Arial 作为后备字体。示例说明和 CSS 中都能看到这一替换。参考表仍记录了实际的字体系列声明，帮助读者了解原始设计系统。项目如需采用品牌字体，必须妥善处理相应资源和使用权，不能想当然地认为只要写上 font-family 名称，字体就会自动可用。

### 使用实际的间距名称

当前像素间距刻度从 spacing-002 延伸至 spacing-160，其中包括 12、24 和 48 像素。标签页样式表还使用 spacing-03（8px）和 spacing-09（48px）等旧别名；此版本中两者均有定义。演示保留这些库规则，并添加了双栏编辑式布局，在 720px 以下变为单栏。该布局断点是原创的版式设计决定，与组件样式表中的 48em 断点不同。

## UNDP 设计系统 UNDP 原生标签页结构与初始化

### 确保标签页与面板集合保持对应

根元素包含 data-undpds-component="tabs"；标签列表使用 role="tablist"，其中有三个带 role="tab" 的 .tabs-title 元素；三个 .tabs-panel 区块则位于 .tabs-content 内。脚本按顺序配对这两组元素。若缺少面板或两组数量不一致，初始化便无法正常工作。因此，每个面板在运行 tabs() 前都应有稳定的 ID 和完整内容。原生初始化会建立 aria-controls 与 aria-labelledby 关系，并通过 is-active 标记选中项。

### 有意决定是否采用哈希行为

软件包默认启用深层链接。在此嵌入式工作区中，标签列表上的 data-deep-link="false" 可避免切换区块时将 URL 哈希写入地址栏。如果分享特定区块有帮助，独立发布页面可以启用深层链接，但之后必须测试初始哈希选中状态和历史记录变化。不要在嵌入式预览中照搬哈希约定，而不先确定由哪个页面负责导航。

## UNDP 设计系统 UNDP 键盘导航与可见状态

### 验证面板是否确实显示

方向键以及 Home 或 End 键会通过原生实现切换当前标签页并移动焦点。Enter 和 Space 键也能激活标签页。脚本会同步更新 tabindex、aria-selected、hidden 和 aria-hidden。若只测试 is-active CSS 类，便可能漏掉多个面板仍同时显示，或隐藏面板仍可获得焦点的问题。浏览器检查会同时验证选中项和实际显示的内容。

### 让审核控件始终隶属于对应区块

每个面板都包含一个原生复选框，标签为“将此区块标记为已审核”。面板隐藏后，状态仍会保留，因为节点并未重新创建。进度计数以礼貌状态消息的形式呈现，且仅描述此本地预览。它既不是学习凭证，也不是服务器端的完成记录。用户可以返回某个区块，直接更改勾选状态。

## UNDP 设计系统 UNDP 本地进度与恢复

### 明确说明重置的作用范围

重置阅读进度会清除三个复选框并重新计算数量，但不会更改当前标签页或清除内容。事件处理程序使用与复选框变更相同的进度函数，避免用两套不同的说明来描述完成状态。此示例不会在当前文档之外保存任何内容，因此完整重新加载页面后会开始新的阅读会话。

### 避免让选读内容显得像是必读

计数有助于了解进度，但不会阻止读者访问后续部分。即使尚未阅读任何部分，三个标签页仍然都可用，读者可以按任意顺序浏览。如果生产工作流程需要确认阅读，则应单独实现相应要求、错误处理和持久化，而不是套用此处的本地进度模型。

## UNDP 设计系统 UNDP 响应式阅读布局

### 调整内容布局，而非缩小内容

在较宽屏幕上，蓝色简介和每个面板均采用双栏布局。屏幕宽度为 720px 时，内容改为纵向排列，外侧内边距缩小至 16px，主标题也相应缩小。标签列表会在需要时换行，同时保留所有标签。面板没有固定高度，因此较长的译文或段落不会被裁切；辅助说明也保留为真实文本，而非装饰性图片。

### 测试嵌入式宽度

详情页的内容列比浏览器视口窄。此示例不仅在桌面、平板和手机屏幕尺寸下进行了测试，也作为独立文档测试到 280px 宽度。在整个手机屏幕上显示正常的组件，放进详情页内缩的框架后仍可能溢出；共用的页面检查会同时测量这两种情况。

## UNDP 设计系统 UNDP 完整静态集成

### 将提供的文件放在一起

将提供的 index.html、undp.css 和 undp-app.js 保存在同一目录中，安装锁定版本的 assets 包，然后提供该目录。HTML 会先载入该包的基础 CSS、标签页 CSS 和标签页浏览器脚本，再载入简短的应用脚本。此示例无需打包工具、jQuery 或 GSAP。本地嵌入式预览会内联相同的组件资源，同时移除未使用的 font-face 声明。

1. 将提供的三个文件保存在同一目录中。

2. 安装 @undp/design-system-assets@2.0.2。

3. 提供此文件夹，并使用鼠标和键盘测试标签页切换。

4. 阅读所有部分，切换回其他部分，然后重置本地计数。

### 区分组件行为与应用行为

标签页脚本负责面板选择和键盘导航。简短的应用脚本仅负责阅读复选框、计数和重置。这样的职责划分便于检查升级内容：先比对原生标签页行为和设计令牌变更，再验证本地状态是否仍能正常工作。复制整个应用框架会让人难以分辨哪些行为实际来自设计系统。

## UNDP 设计系统组件示例

### undp-index.html — 完整源代码

将此文件保存为 index.html；其中包含全部三个内容面板和资源导入。

```
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Workshop reading brief</title><link rel="stylesheet" href="./node_modules/@undp/design-system-assets/css/base-minimal.min.css"><link rel="stylesheet" href="./node_modules/@undp/design-system-assets/css/components/tab.min.css"><link rel="stylesheet" href="./undp.css"></head><body><main><header class="intro"><div><p class="eyebrow">Learning brief / original sample</p><h1>Plan a local resilience workshop</h1></div><p>A small reading workspace for exploring how a development brief can separate context, participation and follow-through.</p></header><p class="study-note">Native UNDP 2.0.2 tab styles and keyboard behavior. Original OpenDesign sample content, not a UNDP programme or official policy. This preview uses Arial fallback rather than the distributed brand fonts.</p><div class="tabs" data-undpds-component="tabs"><ul role="tablist" aria-label="Workshop reading sections" data-deep-link="false"><li role="tab" class="tabs-title is-active" tabindex="0">Understand</li><li role="tab" class="tabs-title" tabindex="-1">Include</li><li role="tab" class="tabs-title" tabindex="-1">Follow through</li></ul><div class="tabs-content"><section id="understand" class="tabs-panel is-active"><div class="panel-grid"><div><h2>Start with the local context</h2><p>A useful workshop begins with a question people can answer from experience. Ask which everyday service is hardest to rely on during a disruption. Avoid assuming that a technical solution is already agreed.</p><h3>Prepare the conversation</h3><ol><li>Write one plain-language question.</li><li>Invite examples of what already works.</li><li>Record uncertainty separately from an agreed need.</li></ol></div><aside class="reading-card"><h3>What would change the decision?</h3><p>Collect contrasting experiences, not just the first answer. A disagreement can reveal who is missing from the conversation.</p><label><input type="checkbox" data-read="understand">Mark this section as reviewed</label></aside></div></section><section id="include" class="tabs-panel"><div class="panel-grid"><div><h2>Make participation practical</h2><p>Participation depends on when, where and how a session takes place. Offer more than one way to contribute and explain how notes will be used before the discussion begins.</p><h3>Remove avoidable barriers</h3><ol><li>Offer spoken and written contributions.</li><li>Ask participants about access needs privately.</li><li>Explain how to decline recording or attribution.</li></ol></div><aside class="reading-card"><h3>Who has not been heard?</h3><p>A count of attendees does not prove representative participation. Check whether the invitation, language or format prevented people from joining.</p><label><input type="checkbox" data-read="include">Mark this section as reviewed</label></aside></div></section><section id="follow" class="tabs-panel"><div class="panel-grid"><div><h2>Close the loop with participants</h2><p>End with a short record of decisions, open questions and named next steps. Send a readable summary back through a channel that participants can actually access.</p><h3>Turn discussion into a next step</h3><ol><li>Separate decisions from suggestions.</li><li>Attach an owner and review point to the next action.</li><li>Invite corrections before treating the notes as agreed.</li></ol></div><aside class="reading-card"><h3>What happens after the session?</h3><p>A clear follow-up commitment is more useful than a polished report with no owner. Keep unresolved issues visible in the next conversation.</p><label><input type="checkbox" data-read="follow">Mark this section as reviewed</label></aside></div></section></div></div><div class="bottom"><p id="progress" role="status">0 of 3 sections reviewed in this preview</p><button id="reset" type="button">Reset reading progress</button></div></main><script src="./node_modules/@undp/design-system-assets/js/tabs.min.js"></script><script src="./undp-app.js"></script></body></html>
```

代码参考

- 请将文件名与相对包路径一并保留。

### undp.css — 完整源代码

原始响应式布局，并明确设置 Arial 作为备用字体。

```
*{box-sizing:border-box}body{margin:0;font-family:Arial,sans-serif}h1,h2,h3,p,button{font-family:inherit}main{max-width:1100px;margin:auto;padding:40px}.intro{display:grid;grid-template-columns:1.4fr 1fr;gap:40px;padding:32px;background:var(--undpds-color-blue-600);color:white}.intro h1{font-size:40px;line-height:1.1;margin:16px 0}.intro p{font-size:16px;line-height:1.6}.eyebrow{font-size:12px!important;font-weight:700;letter-spacing:.08em;text-transform:uppercase}.study-note{font-size:13px;line-height:1.6;margin:24px 0}.tabs>ul{display:flex;flex-wrap:wrap;padding-left:0;gap:16px;margin-top:32px}.tabs>ul li{margin-right:0;padding:12px 0;font-size:16px}.tabs-title:focus-visible{outline:3px solid var(--undpds-color-blue-600);outline-offset:4px}.tabs-panel{padding-top:24px!important}.panel-grid{display:grid;grid-template-columns:1fr 1fr;gap:32px}h2{font-size:28px;line-height:1.2;margin:0 0 24px}h3{font-size:20px;line-height:1.3}p,li{font-size:16px;line-height:1.6}li{margin-bottom:12px}.reading-card{background:var(--undpds-color-gray-200);padding:24px;border-left:4px solid var(--undpds-color-yellow-600)}.reading-card p:last-child{margin-bottom:0}label{display:flex;gap:12px;align-items:flex-start;margin-top:24px;font-size:16px;line-height:1.5}input{width:20px;height:20px;accent-color:var(--undpds-color-blue-600);flex-shrink:0}#progress{border-top:2px solid var(--undpds-color-gray-300);padding-top:24px;font-size:14px}button{background:transparent;border:2px solid var(--undpds-color-blue-600);color:var(--undpds-color-blue-700);padding:12px 16px;font-weight:700;cursor:pointer;min-height:44px}.bottom{display:flex;justify-content:space-between;gap:24px;align-items:center;margin-top:32px}button:focus-visible,input:focus-visible{outline:3px solid var(--undpds-color-blue-600);outline-offset:4px}[hidden]{display:none!important}@media(max-width:720px){main{padding:16px}.intro,.panel-grid{grid-template-columns:1fr;gap:16px}.intro{padding:24px}.intro h1{font-size:32px}.bottom{flex-wrap:wrap}}
```

代码参考

- 请将文件名与相对包路径一并保留。

### undp-app.js — 完整源代码

原生标签页初始化，以及原始的本地进度与重置行为。

```
tabs();const boxes=[...document.querySelectorAll('[data-read]')];function progress(){document.querySelector('#progress').textContent=boxes.filter(x=>x.checked).length+' of 3 sections reviewed in this preview';}boxes.forEach(x=>x.addEventListener('change',progress));document.querySelector('#reset').addEventListener('click',()=>{boxes.forEach(x=>x.checked=false);progress();});
```

代码参考

- 请将文件名与相对包路径一并保留。

## UNDP 设计系统 Agent 设置

### 实现起点

打开 http://localhost:8000/。HTML 会导入实际的包资源；无需完整的 Storybook 项目。

```
npm init -y
npm install @undp/design-system-assets@2.0.2
# Save the supplied HTML as index.html alongside undp.css and undp-app.js.
python3 -m http.server 8000
```

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

```
使用提供的所有 HTML、CSS 和 JavaScript，实现 UNDP 2.0.2 原生标签页阅读工作区。保留实际设计令牌名称、标签页与面板数量一致、方向键/Home/End 键行为、明确设置的 Arial 备用字体、仅本地保存的阅读进度，以及不会设为访问门槛的导航。原始工作坊文本应与机构政策内容明确区分。
```

## UNDP 设计系统 来源与适用范围

一份使用 UNDP 2.0.2 原生标签页资源的 OpenDesign 应用指南，内容为原创。明确设置 Arial 作为备用字体；本指南不代表 UNDP 的任何项目或官方政策。

- 官方设计系统 组件文档和当前设计指南。

- 官方代码仓库 分发方式与开发背景。

- 锁定版本的基础 CSS 此版本实际使用的设计令牌和排版声明。

- 锁定版本的标签页实现 选择、焦点、深层链接和面板可见性。

## UNDP 设计系统 相关资源

### USWDS

将 USWDS 间距令牌、主题角色、语义表格和原生折叠面板结合起来，打造可搜索的机会对比体验。

### VA 设计系统

运用 VA 的语义令牌和原生 Process List，打造清晰的服务流程：展示步骤说明和含义明确的状态标签，并提供补充详情，同时保持主要路径清晰易读。

### W3C 设计系统

运用流式字体、语义化颜色角色和原生折叠内容，打造适应力强的阅读界面，即使没有 JavaScript，内容依然清晰易读。


- [实现参考](https://github.com/undp/design-system)
- [来源](https://cdn.jsdelivr.net/npm/@undp/design-system-assets@2.0.2/css/base-minimal.min.css)
- [来源](https://cdn.jsdelivr.net/npm/@undp/design-system-assets@2.0.2/js/tabs.min.js)
- [代码参考](https://github.com/undp/design-system)
- [官方设计系统 组件文档和当前设计指南。](https://design.undp.org/)
- [官方代码仓库 分发方式与开发背景。](https://github.com/undp/design-system)
- [锁定版本的基础 CSS 此版本实际使用的设计令牌和排版声明。](https://cdn.jsdelivr.net/npm/@undp/design-system-assets@2.0.2/css/base-minimal.min.css)
- [锁定版本的标签页实现 选择、焦点、深层链接和面板可见性。](https://cdn.jsdelivr.net/npm/@undp/design-system-assets@2.0.2/js/tabs.min.js)
