# Дизайн-система 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 | Используйте крупный размер, если этого требует сценарий с сенсорным вводом; размеры взяты из документации 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; доступный стек системных шрифтов без засечек — отдельная роль. В Codex также предусмотрена роль serif heading-main на основе Linux Libertine с запасными вариантами Georgia, Times и другими шрифтами. В предпросмотре заголовок статьи набран шрифтом с засечками, а элементы управления — шрифтом без засечек; загружать шрифты не требуется.

В справочнике ниже font-size-medium со значением 1rem отделён от line-height-medium со значением 1.625rem. Значение line-height-content без единиц измерения предназначено для пользовательского контента; это не универсальное указание заменять внутренний межстрочный интервал каждого компонента. Позвольте нативным полям ввода и кнопкам CSS сохранять собственные метрики элементов управления.

Прочитать вспомогательную спецификацию

## Интервалы и контрольные точки дизайн-системы Codex

### Используйте именованную шкалу и предусмотренные исключения

В Codex spacing-100 равен 16px, spacing-150 — 24px, а spacing-200 — 32px. В шкале есть и явные исключения: spacing-30 равен 5px и используется для вертикальных внутренних отступов элементов управления при стандартной высоте 32px. Если округлить все интервалы до сетки с шагом 8px, задокументированное решение для компонента будет утрачено.

В примере список результатов занимает всю ширину при ширине области просмотра менее 640px — это задокументированная граница планшетного макета. Максимальная ширина для чтения 56rem выбрана на уровне приложения. Контрольные точки для настольных экранов — 1120px, а для широких настольных экранов — 1680px; эти пороги определяют категории областей просмотра, а не автоматически предоставляемую каждому приложению сетку.

Прочитать вспомогательную спецификацию

## Цвета и роли действий в дизайн-системе Codex

### Цвет действия, продвигающего процесс, — не просто декоративный синий

Codex разделяет тип действия и вес кнопки. Действие progressive продвигает процесс, тогда как вес primary обозначает основное действие в текущем представлении. Для поиска в этом локальном указателе подходит нейтральная кнопка normal; малозаметный элемент управления quiet позволяет очистить запрос, не отвлекая от результатов.

В скомпилированном CSS содержатся резервные значения цветов для пользовательских свойств, в том числе базовый цвет текста #202122 и цвет progressive #36c. Для этих состояний в предпросмотре используются нативные компоненты CSS. Светлый фон панели результатов относится к макету приложения, а не к новому токену статуса Codex.

Прочитать вспомогательную спецификацию

## Анатомия SearchInput в дизайн-системе Codex

### Продуманно объединяйте поле ввода и кнопку

Структура только с CSS требует класс .cdx-search-input--has-end-button на корневом элементе, обёртку .cdx-search-input__input-wrapper, элемент .cdx-text-input с модификатором start-icon и кнопку с классом .cdx-search-input__end-button. Без обёрток нарушаются объединённая геометрия элементов и выравнивание значка.

Видимая подпись задаёт область поиска. Элемент span со значком носит декоративный характер и скрыт от API специальных возможностей. Форма обрабатывает нажатие Enter и активацию кнопки через один обработчик отправки; после обновления результатов их количество объявляется в области статуса с вежливым режимом объявления. Если поле пусто, отображаются все локальные примеры.

- Используйте SearchInput для поиска контента на странице.

- Используйте TypeaheadSearch, если нужны предиктивные подсказки для навигации.

- Используйте Lookup, чтобы выбрать значение для поля формы.

Прочитать вспомогательную спецификацию

## Результаты и подробное чтение в дизайн-системе Codex

### Сохраняйте место читателя

У каждого результата есть заголовок с названием, краткое оригинальное описание и кнопка, открывающая локальную панель чтения. Панель — это композиция приложения, а не Dialog из Codex: она остаётся в обычном потоке документа, не имеет модального фона и не удерживает фокус.

При открытии примера фокус перемещается на заголовок панели. При закрытии фокус возвращается на открывшую её кнопку. Новый поиск закрывает предыдущий материал и пересчитывает количество результатов, чтобы устаревшая статья не воспринималась как результат нового запроса. Если совпадений нет, отображается поясняющий текст и отдельное действие для очистки поиска.

Прочитать вспомогательную спецификацию

## Направление текста и поведение ввода в дизайн-системе Codex

### Учитывайте языки помимо английского

В документации компонентов есть примеры для направления письма слева направо и справа налево. Codex используется в многоязычной среде знаний, поэтому макет приложения должен опираться на логические интервалы по inline- и block-оси, а не исходить из того, что все значки и действия чтения расположены слева. В пользовательском макете примера там, где важна направленность, используются margin-inline и padding-inline.

В этом примере поиск запускается только при отправке формы. Это не позволяет принять промежуточный текст при вводе с помощью IME за завершённый запрос. Для производственной реализации автодополнения потребуются обработка ввода с учётом композиции, отмена асинхронных запросов и корректная модель взаимодействия с меню; пример только с 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>
```

Справочник по коду

### Полный автономный пример

Полный документ включает разметку, элементы управления и инициализацию. Распакуйте связанный архив примера, чтобы получить нужные относительные пути к ресурсам поставщика, затем запустите его через 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.

- Оставьте пути к ресурсам поставщика относительными к этому документу; архив включает все ресурсы, используемые в предварительном просмотре.

## Настройка агента дизайн-системы Codex

### Отправная точка для реализации

Работа нативной таблицы стилей локально проверена в автономном предпросмотре. Код Vue — отдельный пример интеграции, а не среда выполнения этого предпросмотра. Полный ZIP с рабочим примером в разделе Sources также содержит точные зависимости для предпросмотра и полный документ. Распакуйте архив, запустите в этой директории 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';
```

### Запрос для вашего проекта

```
Создайте локальный указатель по материалам с SearchInput и кнопками Codex 2.7.0 только с CSS. Сохраните задокументированные обёртки конечной кнопки, явную подпись поиска и нативную отправку формы. Показывайте количество результатов, сообщение об отсутствии совпадений и действие для очистки. Открывайте подробности результата в строке, переводите фокус на заголовок и при закрытии возвращайте его на инициировавшую кнопку. Не заявляйте семантику TypeaheadSearch или модального окна. Используйте официальные роли шрифтов и интервалов, указав, что ширина контента выбрана на уровне приложения.
```

## Источники и область применения дизайн-системы Codex

Самостоятельный пример OpenDesign с оригинальными краткими описаниями. Контент и оформление Wikipedia не копируются. Элементы управления только с CSS — нативные элементы Codex; фильтрация поиска и встроенная панель чтения реализованы на уровне приложения.

- Обзор Codex Официальная страница дизайн-системы Wikimedia.

- Доступ к Codex Доступные ресурсы для дизайна и разработки.

- Руководство по стилю Рекомендации по визуальному оформлению, контенту и взаимодействию.

- Скачать полный рабочий пример ZIP-архив с полным HTML, локальными зависимостями CSS/JavaScript, лицензиями и точными инструкциями по запуску. Сборка не требуется.

## Связанные ресурсы дизайн-системы Codex

### Agriculture дизайн-система

Создавайте многоэтапные сценарии обслуживания с помощью конкретных значений отступов AgDS, адаптивных свойств и модели статусов TaskList. Попробуйте подготовительный процесс, где этап проверки становится доступен только после выполнения предварительных условий.

### Alberta дизайн-система

Используйте встроенные веб-компоненты Alberta и опубликованные токены дизайна, чтобы создать полный контрольный список подготовки с доступными вариантами, вычисляемым прогрессом и понятными результатами проверки.

### Amsterdam

Используйте реальный контракт открытого компонента Switch от Amsterdam, полную нейтральную тему, доступные подписи и настройки чтения с мгновенным применением.


- [Справочник по реализации](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)