# Codex 设计系统

## Codex 设计系统界面预览

搜索三个原创示例，查看一条结果，关闭它，或尝试一个无匹配项的查询。

## Codex 设计系统设计参考

@wikimedia/codex 2.7.0 原生 CSS 和当前官方令牌/组件参考。独立预览采用文档所述的 CSS 专用路由；内容宽度和结果面板布局属于应用层选择。

### 字体角色

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| font-family-base | sans-serif | 文档/控件基础角色。 |
| font-family-heading-main | Linux Libertine, Georgia, Times, Source Serif 4, serif | 用于首个标题的特殊角色，带有本地后备字体。 |
| font-size-small / medium / large | 0.875rem / 1rem / 1.125rem | 辅助文本、默认文本和较大字号文本。 |
| line-height-medium | 1.625rem | 组件/功能行高令牌。 |
| line-height-content | 1.625 | 用于用户生成内容的无单位角色。 |
### 间距

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| spacing-25 / 50 / 75 | 4px / 8px / 12px | 紧凑的间距关系。 |
| spacing-100 / 150 / 200 | 16px / 24px / 32px | 标准布局节奏。 |
| spacing-30 | 5px | 针对默认控件垂直内边距的文档化例外。 |
| spacing-horizontal-button | 12px − 1px | 计入按钮边框。 |
### 视口与控件

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| Mobile / tablet minima | 320px / 640px | 视口边界。 |
| Desktop / desktop-wide minima | 1120px / 1680px | 更大的视口边界。 |
| Button small / medium / large | 24px / 32px / 44px minimum | 在触控场景需要时使用 large；尺寸参见 Button 文档。 |
### 编译后的默认颜色回退值

| 名称 / 规则 | 值 / 配置 | 用途 |
| --- | --- | --- |
| color-base | #202122 | 默认的易读文本。 |
| color-progressive | #36c | 表示流程推进的操作颜色；并非适用于每条记录的状态。 |
## Codex 设计系统完整指南

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

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

## Codex 设计系统 仅使用 CSS 的实现与 Vue 路由

### 选择所需的实现方式

> Codex 提供 Vue 组件和文档化的仅使用 CSS 的组件结构。在线示例采用后者：搜索控件使用 Codex 文档中列出的精确包装器、文本输入框和末端按钮类，并通过本地应用脚本筛选三个原创文章摘要。单独的 Vue 示例展示了对应的包导入方式。

仅使用 CSS 实现的搜索控件，不会因为外观相似就变成预测式组合框。此示例提交查询并呈现结果列表，不使用 ARIA listbox 模式，也不声称实现了 TypeaheadSearch。

阅读配套规范

## Codex 设计系统：便于阅读的排版

### 区分内容与控件的角色

font-family-base 令牌解析为 sans-serif；可用的 system-sans 字体栈属于另一个角色。Codex 还提供 serif heading-main 角色，以 Linux Libertine 为首选，并配有 Georgia、Times 等回退字体。预览采用衬线文章标题和无衬线控件，不会下载字体。

下方参考内容将 font-size-medium（1rem）与 line-height-medium（1.625rem）区分开来。无单位的 line-height-content 值适用于用户生成的内容，并不意味着要一概替换每个组件的内部行高。让原生 input 和 button CSS 保留各自的控件度量值。

阅读配套规范

## Codex 设计系统：间距与断点

### 使用命名尺度，并留意其中的例外

Codex 的 spacing-100 为 16px，spacing-150 为 24px，spacing-200 为 32px。该尺度也包含明确的例外：spacing-30 为 5px，可用于默认高度为 32px 的控件垂直内边距。将所有间距都四舍五入到 8px 网格，会抹去有文档记录的组件设计决策。

此示例在宽度低于 640px 时让结果列表占满宽度，采用文档中定义的平板边界。其最大阅读宽度为应用自行选定的 56rem。桌面断点为 1120px，宽屏桌面断点为 1680px；这些阈值用于描述视口类别，并不代表每个应用都会自动获得网格布局。

阅读配套规范

## Codex 设计系统：颜色与操作角色

### Progressive 并非通用的蓝色装饰

Codex 区分操作类型与按钮权重。progressive 操作用于推进流程，而 primary 权重用于标识视图中的主要操作。neutral normal 按钮适合搜索此本地索引；quiet 控件则可以清除搜索内容，而不与结果争夺注意力。

编译后的 CSS 包含自定义属性的回退颜色，例如基础文本色 #202122 和 progressive 颜色 #36c。预览使用原生组件 CSS 呈现这些状态。浅色结果面板背景属于应用布局，并非新创的 Codex 状态令牌。

阅读配套规范

## Codex 设计系统：SearchInput 结构

### 有意组合输入框与按钮

仅使用 CSS 的结构要求根元素带有 .cdx-search-input--has-end-button，包含 .cdx-search-input__input-wrapper、带有 start-icon 修饰符的 .cdx-text-input，以及带有 .cdx-search-input__end-button 的按钮。省略包装器会破坏组合后的几何结构和图标对齐。

可见标签用于说明搜索范围。图标 span 仅用于装饰，并会从无障碍 API 中隐藏。表单通过同一个 submit 监听器处理 Enter 键和按钮激活；结果更新后，会通过礼貌提示状态区域播报数量。输入为空时，会恢复显示所有本地示例。

- 使用 SearchInput 查找页面内容。

- 需要预测式导航建议时，使用 TypeaheadSearch。

- 需要将选项作为表单值进行选择时，使用 Lookup。

阅读配套规范

## Codex 设计系统：结果与详情阅读

### 让读者保持阅读位置

每条结果都包含带标题的标题项、简短的原创描述，以及一个用于打开本地阅读面板的按钮。该面板由应用组合而成，并非 Codex Dialog：它处于文档的正常流中，没有模态背景，也不会锁定焦点。

打开示例时，焦点会移至面板标题；关闭面板后，焦点会返回打开它的按钮。再次搜索会关闭先前的详情面板并重新计算结果数量，避免旧文章看起来像是新查询的结果。没有匹配项时，会显示说明文字和明确的清除操作。

阅读配套规范

## Codex 设计系统：方向与输入行为

### 为英语以外的语言做好准备

组件文档提供从左到右和从右到左的示例。Codex 面向多语言知识生态，因此应用布局应使用逻辑内联/块级间距，而不是假定所有图标和阅读操作都位于左侧。示例的自定义布局在方向性有影响的地方使用 margin-inline 和 padding-inline。

此处的搜索仅在提交时执行，避免将输入法编辑过程中的组合文本误当作已完成的查询。生产环境中的自动补全还需要处理输入法组合、取消异步请求，并实现正确的菜单交互模式；这个仅使用 CSS 的本地示例不会声称具备这些功能。

阅读配套规范

## Codex 设计系统：集成与扩展

### 固定库版本，自行实现结果逻辑

已验证的程序包为 @wikimedia/codex 2.7.0，其样式入口为 dist/codex.style.css。仅使用 CSS 的演示无需 Vue 运行时，因为其中所有控件都是原生 HTML，筛选和阅读面板状态由简短的本地脚本管理。需要由框架管理状态时，Vue 版本会导入 CdxSearchInput 和 CdxButton。

代码包采用 GPL-2.0-or-later 许可证，许可证文件随本地资源一并提供。示例不会复制 Wikipedia 的品牌标识或文章内容。连接实际搜索端点之前，请分别处理网络故障、加载状态和过期响应，不要把本地的无结果状态重新标记为其他状态。

1. 安装固定版本的程序包，或复制其样式表并附上许可证。

2. 呈现文档所述的仅使用 CSS 的结构，或使用导出的 Vue 组件。

3. 在应用中添加查询和结果逻辑，并保留搜索语义。

4. 使用实际翻译内容检查键盘焦点和窄屏布局。

阅读配套规范

## Codex 设计系统：组件示例

### 带有可见标签的仅使用 CSS 的搜索

采用文档所述的包装结构，并通过原生表单提交。

```
<form id="article-search" role="search">
  <label for="query">Find an example article</label>
  <div class="cdx-search-input cdx-search-input--has-end-button">
    <div class="cdx-search-input__input-wrapper">
      <div class="cdx-text-input cdx-text-input--has-start-icon">
        <input id="query" class="cdx-text-input__input" type="search">
        <span class="cdx-text-input__icon cdx-text-input__start-icon" aria-hidden="true"></span>
      </div>
    </div>
    <button type="submit" class="cdx-button cdx-search-input__end-button">Search</button>
  </div>
</form>
<p id="result-count" role="status"></p>
```

代码参考

### Vue 搜索组合

实际导入 Codex 并使用 Vue 状态；本地提交的查询结果用于说明集成边界。

```
<script setup>
import { ref } from 'vue';
import { CdxSearchInput, CdxButton } from '@wikimedia/codex';
import '@wikimedia/codex/dist/codex.style.css';
const query = ref('');
const submitted = ref('');
function search() { submitted.value = String(query.value).trim(); }
</script>
<template>
  <form role="search" @submit.prevent="search">
    <CdxSearchInput v-model="query" aria-label="Find an example article" />
    <CdxButton action="progressive" weight="primary" type="submit">Search</CdxButton>
  </form>
  <p role="status">Submitted query: {{ submitted || 'All examples' }}</p>
</template>
```

代码参考

### 完整的独立示例

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

```
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Codex knowledge search</title><link rel="stylesheet" href="vendor/codex-2.7.0/codex.style.css"><style>*{box-sizing:border-box}body{font:16px/1.625 sans-serif;color:#202122;margin:0}main{max-width:56rem;margin:auto;padding:32px 24px}h1{font:normal 32px/1.3 Georgia,serif;border-bottom:1px solid #a2a9b1;padding-bottom:12px}h2{font-size:20px;margin:0 0 8px}label{display:block;font-weight:700;margin-bottom:8px}.top{font-size:14px;color:#54595d}.result{padding:24px 0;border-bottom:1px solid #c8ccd1}.result p{margin:8px 0 16px}.tools{display:flex;align-items:center;gap:16px;justify-content:space-between}.reading{padding:24px;background:#f8f9fa;border:1px solid #a2a9b1;margin-block:24px}.reading h2:focus{outline:2px solid #36c;outline-offset:4px}small{display:block;margin-top:32px;color:#54595d;font-size:14px}[hidden]{display:none!important}@media(max-width:639px){main{padding:24px 16px}.tools{align-items:stretch;flex-direction:column}.result .cdx-button{width:100%}}
</style><main><p class="top">Independent knowledge index · Codex CSS-only</p><h1>Explore the example collection</h1><p>Find an original topic summary and open its reading panel. This small index runs entirely in your browser.</p><form id="article-search" role="search">
  <label for="query">Find an example article</label>
  <div class="cdx-search-input cdx-search-input--has-end-button">
    <div class="cdx-search-input__input-wrapper">
      <div class="cdx-text-input cdx-text-input--has-start-icon">
        <input id="query" class="cdx-text-input__input" type="search">
        <span class="cdx-text-input__icon cdx-text-input__start-icon" aria-hidden="true"></span>
      </div>
    </div>
    <button type="submit" class="cdx-button cdx-search-input__end-button">Search</button>
  </div>
</form>
<p id="result-count" role="status"></p><div class="tools"><p id="empty" hidden>No matching topics. Try “river” or clear the search.</p><button type="button" class="cdx-button cdx-button--weight-quiet" id="clear">Clear search</button></div><div id="results"></div><section class="reading" id="reading" hidden><h2 id="reading-title" tabindex="-1"></h2><p id="reading-text"></p><button type="button" class="cdx-button" id="close">Close reading panel</button></section><small>Original example content. Wikimedia Codex 2.7.0 controls; application-owned results and inline panel. No external search request.</small></main><script>
const data=[{title:'River observation notes',text:'A field notebook can record water level, weather and observation time together. Repeated observations from the same location help readers compare conditions without confusing a new measurement with a changed method.',summary:'Organising repeated observations at a river station.'},{title:'Community archive descriptions',text:'An archive description records what an item is, when it was created and how it relates to other items. A clear description distinguishes an original document from a later copy and identifies uncertain dates without hiding that uncertainty.',summary:'Describing original documents and their context.'},{title:'Garden seed collection',text:'A seed record can distinguish the plant name, collection date and storage method. Keeping those attributes separate makes it easier to compare batches, while a free-text note preserves observations that do not fit a controlled field.',summary:'Keeping plant, date and storage information readable.'}];let opener;const results=document.querySelector('#results'),query=document.querySelector('#query'),reading=document.querySelector('#reading'),count=document.querySelector('#result-count');function render(){reading.hidden=true;results.replaceChildren();const found=data.filter(d=>(d.title+' '+d.summary).toLowerCase().includes(query.value.trim().toLowerCase()));count.textContent=found.length+' example topics';document.querySelector('#empty').hidden=found.length>0;for(const d of found){let a=document.createElement('article');a.className='result';let h=document.createElement('h2');h.textContent=d.title;let p=document.createElement('p');p.textContent=d.summary;let b=document.createElement('button');b.type='button';b.className='cdx-button';b.textContent='Read '+d.title;b.onclick=()=>{opener=b;document.querySelector('#reading-title').textContent=d.title;document.querySelector('#reading-text').textContent=d.text;reading.hidden=false;document.querySelector('#reading-title').focus()};a.append(h,p,b);results.append(a)}}document.querySelector('form').onsubmit=e=>{e.preventDefault();render()};document.querySelector('#clear').onclick=()=>{query.value='';render();query.focus()};document.querySelector('#close').onclick=()=>{reading.hidden=true;opener?.focus()};render();
</script></html>
```

代码参考

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

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

## Codex 设计系统：AI Agent 设置

### 实现起点

独立预览中的原生样式表已在本地验证。Vue 代码是单独的集成示例，并非该预览的运行时。Sources 中的完整可运行示例 ZIP 还提供了准确的预览依赖项和完整文档。将其解压后，在该目录中运行 python3 -m http.server 8080，然后打开 http://localhost:8080/wikimedia-codex.html。请勿通过 file:// 打开基于模块的示例。

```
npm install @wikimedia/codex@2.7.0
# CSS-aware entry for CSS-only HTML:
# import '@wikimedia/codex/dist/codex.style.css';
# For the Vue example, add Vue to the existing Vue application:
# import { CdxSearchInput, CdxButton } from '@wikimedia/codex';
```

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

```
使用 Codex 2.7.0 中仅使用 CSS 的 SearchInput 和按钮，构建本地知识索引。保留文档所述的末端按钮包装结构、明确的搜索标签和原生表单提交。显示结果数量、无匹配项提示和清除操作。以内联方式打开结果详情，将焦点移至详情标题，并在关闭时将焦点返回触发按钮。不要声称支持 TypeaheadSearch 或模态框语义。使用官方字体和间距角色，并明确说明内容宽度属于应用自身的选择。
```

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

独立的 OpenDesign 示例，使用原创摘要，不复制 Wikipedia 内容或品牌标识。仅使用 CSS 的控件是原生 Codex；搜索筛选和内联阅读面板均由应用代码实现。

- Codex 概览 Wikimedia 官方设计系统入口。

- 访问 Codex 可用的设计与开发资源。

- 样式指南 视觉、内容与交互指南。

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

## Codex 设计系统：相关资源

### Agriculture 设计系统

借助 AgDS 具体的间距、响应式属性与 TaskList 状态模型，构建更长的服务流程事务。试用一个准备流程：只有当所有前置条件都完成时，复核步骤才会解锁。

### Alberta 设计系统

使用 Alberta 的原生 Web Components 与已发布的设计令牌，构建一份完整的准备清单，具备无障碍选项、派生进度和诚实的审核反馈。

### Amsterdam

使用 Amsterdam 真实的开源 Switch 契约，搭配完整的中性主题、无障碍标签和即时的阅读偏好设置。


- [实现参考](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [来源](https://doc.wikimedia.org/codex/latest/design-tokens/font.html)
- [来源](https://doc.wikimedia.org/codex/latest/design-tokens/spacing.html)
- [来源](https://doc.wikimedia.org/codex/latest/design-tokens/breakpoint.html)
- [来源](https://doc.wikimedia.org/codex/latest/design-tokens/color.html)
- [阅读配套规范](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [阅读配套规范](https://doc.wikimedia.org/codex/latest/design-tokens/font.html)
- [阅读配套规范](https://doc.wikimedia.org/codex/latest/design-tokens/spacing/)
- [阅读配套规范](https://doc.wikimedia.org/codex/latest/components/demos/button.html)
- [阅读配套规范](https://doc.wikimedia.org/codex/latest/components/overview.html)
- [阅读配套规范](https://doc.wikimedia.org/codex/latest/using-codex/)
- [代码参考](https://doc.wikimedia.org/codex/latest/components/demos/search-input.html)
- [Codex 概览 Wikimedia 官方设计系统入口。](https://doc.wikimedia.org/codex/latest/)
- [访问 Codex 可用的设计与开发资源。](https://doc.wikimedia.org/codex/latest/using-codex/accessing-codex.html)
- [样式指南 视觉、内容与交互指南。](https://doc.wikimedia.org/codex/latest/style-guide/overview.html)