政府与公共服务 · 新资源

Codex 设计系统.

运用 Codex 的真实 SearchInput 结构、操作层级和适于阅读的令牌。在本地文章索引中搜索、查看搜索结果,并返回原来的阅读位置。

OpenDesign 指南8 个章节14 条参考条目原始应用指南
01

Codex 设计系统界面预览

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

知识索引搜索打开完整示例
Codex 2.7.0 原生 CSS 专用 SearchInput/按钮,搭配原创的本地筛选和阅读面板逻辑。· 实现参考
02

Codex 设计系统设计参考

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

字体角色

来源
名称 / 规则值 / 配置用途
font-family-basesans-serif文档/控件基础角色。
font-family-heading-mainLinux Libertine, Georgia, Times, Source Serif 4, serif用于首个标题的特殊角色,带有本地后备字体。
font-size-small / medium / large0.875rem / 1rem / 1.125rem辅助文本、默认文本和较大字号文本。
line-height-medium1.625rem组件/功能行高令牌。
line-height-content1.625用于用户生成内容的无单位角色。

间距

来源
名称 / 规则值 / 配置用途
spacing-25 / 50 / 754px / 8px / 12px紧凑的间距关系。
spacing-100 / 150 / 20016px / 24px / 32px标准布局节奏。
spacing-305px针对默认控件垂直内边距的文档化例外。
spacing-horizontal-button12px − 1px计入按钮边框。

视口与控件

来源
名称 / 规则值 / 配置用途
Mobile / tablet minima320px / 640px视口边界。
Desktop / desktop-wide minima1120px / 1680px更大的视口边界。
Button small / medium / large24px / 32px / 44px minimum在触控场景需要时使用 large;尺寸参见 Button 文档。

编译后的默认颜色回退值

来源
名称 / 规则值 / 配置用途
color-base#202122 默认的易读文本。
color-progressive#36c表示流程推进的操作颜色;并非适用于每条记录的状态。
03

Codex 设计系统完整指南

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

DESIGN-wikimedia-codex.md

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

下载指南

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

选择所需的实现方式

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

摘自本 OpenDesign 指南

仅使用 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 设计系统:结果与详情阅读

让读者保持阅读位置

每条结果都包含带标题的标题项、简短的原创描述,以及一个用于打开本地阅读面板的按钮。该面板由应用组合而成,并非 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 的搜索

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

html
<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 状态;本地提交的查询结果用于说明集成边界。

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 提供服务。

html
<!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 路径相对于本文档;该归档包含此预览所使用的全部资源。
04

Codex 设计系统:AI Agent 设置

实现起点

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

bash
npm install @wikimedia/[email protected]
# 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';

适用于你项目的提示词

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

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

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