Codex는 Vue 컴포넌트와 문서화된 CSS 전용 컴포넌트 구조를 제공합니다. 실제 예제에서는 후자를 선택합니다. 검색 컨트롤은 Codex에 문서화된 래퍼, 텍스트 입력, 끝 버튼 클래스를 그대로 사용하며, 애플리케이션의 로컬 스크립트가 원문으로 작성된 세 개의 문서 요약을 필터링합니다. 별도의 Vue 예제에서는 이에 상응하는 패키지 가져오기를 보여줍니다.
CSS 전용 검색은 생김새가 비슷하다는 이유만으로 예측형 콤보박스가 되지 않습니다. 이 예제는 검색어를 제출하고 결과 목록을 표시합니다. ARIA listbox 패턴을 사용하지 않으며 TypeaheadSearch를 구현한다고 주장하지도 않습니다.
font-family-base 토큰은 sans-serif로 해석되며, 사용 가능한 system-sans 스택은 별도의 역할입니다. Codex는 Linux Libertine을 기반으로 Georgia, Times 등의 대체 글꼴을 지정하는 serif heading-main 역할도 제공합니다. 미리보기에서는 글꼴을 다운로드하지 않고 세리프체 문서 제목과 산세리프체 컨트롤을 사용합니다.
아래 레퍼런스에서는 1rem인 font-size-medium과 1.625rem인 line-height-medium을 구분합니다. 단위 없는 line-height-content 값은 사용자 생성 콘텐츠를 위한 것으로, 모든 컴포넌트의 내부 행간을 바꾸라는 일괄 지침이 아닙니다. 기본 입력과 버튼의 CSS는 각 컨트롤의 고유한 크기 값을 유지하도록 하세요.
Codex의 spacing-100은 16px, spacing-150은 24px, spacing-200은 32px입니다. 스케일에는 명시적인 예외도 있습니다. spacing-30은 5px이며, 기본 높이가 32px인 컨트롤의 세로 패딩에 사용됩니다. 모든 간격을 8px 그리드에 맞춰 반올림하면 문서화된 컴포넌트 결정이 사라집니다.
이 예제는 문서화된 태블릿 경계인 640px 미만에서 결과 목록을 전체 너비로 표시합니다. 읽기 영역의 최대 너비는 애플리케이션에서 56rem으로 설정합니다. 데스크톱 중단점은 1120px, 넓은 데스크톱 중단점은 1680px입니다. 이 기준은 뷰포트 범주를 설명할 뿐, 모든 애플리케이션에 자동으로 제공되는 그리드를 뜻하지는 않습니다.
Codex는 액션의 종류와 버튼의 강조 수준을 구분합니다. progressive 액션은 절차를 진행하고, primary 강조 수준은 해당 화면의 주요 액션을 나타냅니다. 로컬 인덱스를 검색할 때는 중립적인 normal 버튼이 적절하며, quiet 컨트롤로 결과와 경쟁하지 않으면서 검색 내용을 지울 수 있습니다.
컴파일된 CSS에는 사용자 지정 속성의 대체 색상이 포함되어 있습니다. 기본 텍스트는 #202122, progressive는 #36c입니다. 미리보기에서는 이러한 상태에 기본 컴포넌트 CSS를 사용합니다. 옅은 결과 패널 배경은 애플리케이션 레이아웃이며, 새로 만들어낸 Codex 상태 토큰이 아닙니다.
CSS 전용 구조에서는 루트에 .cdx-search-input--has-end-button을, .cdx-search-input__input-wrapper 래퍼에 .cdx-text-input과 시작 아이콘 수정자를, 버튼에 .cdx-search-input__end-button을 사용해야 합니다. 래퍼를 생략하면 결합된 형태와 아이콘 정렬이 유지되지 않습니다.
표시되는 레이블은 검색 범위를 나타냅니다. 아이콘 span은 장식용이므로 접근성 API에서 숨깁니다. 폼은 하나의 submit 리스너로 Enter 키 입력과 버튼 활성화를 처리합니다. 결과가 갱신되면 정중한 상태 영역을 통해 개수가 안내됩니다. 입력란이 비어 있으면 로컬 예제가 모두 다시 표시됩니다.
각 결과에는 제목, 원문으로 작성된 짧은 설명, 로컬 읽기 패널을 여는 버튼이 있습니다. 이 패널은 애플리케이션에서 구성한 요소이지 Codex Dialog가 아닙니다. 일반 문서 흐름 안에 표시되고, 모달 배경을 사용하지 않으며, 포커스를 가두지도 않습니다.
예제를 열면 패널 제목으로 포커스를 이동합니다. 패널을 닫으면 패널을 연 버튼으로 포커스를 돌려보냅니다. 다시 검색하면 이전 상세 내용을 닫고 결과 개수를 다시 계산하므로, 이전 문서가 새 검색어의 결과인 것처럼 남지 않습니다. 일치하는 결과가 없으면 설명 문구와 명시적인 지우기 액션을 표시합니다.
컴포넌트 문서에는 왼쪽에서 오른쪽으로 쓰는 방향과 오른쪽에서 왼쪽으로 쓰는 방향의 예제가 있습니다. Codex는 다국어 지식 생태계에서 사용되므로, 애플리케이션 레이아웃에서는 모든 아이콘과 읽기 액션이 왼쪽에 있다고 가정하지 말고 인라인/블록 방향을 고려한 간격을 사용해야 합니다. 예제의 사용자 지정 레이아웃에서는 방향이 중요한 곳에 margin-inline과 padding-inline을 사용합니다.
여기서 검색은 제출할 때만 실행됩니다. 따라서 IME 조합 중인 텍스트를 완성된 검색어로 처리하지 않습니다. 프로덕션 자동 완성 기능에는 조합 상태를 고려한 입력 처리, 비동기 요청 취소, 올바른 메뉴 상호작용 모델이 필요합니다. CSS 전용 로컬 예제에서는 이러한 기능을 구현한다고 주장하지 않습니다.
확인된 패키지는 @wikimedia/codex 2.7.0이며 스타일 진입점으로 dist/codex.style.css를 제공합니다. CSS만 사용하는 데모는 모든 컨트롤이 기본 HTML 요소이고 작은 로컬 스크립트가 필터링과 읽기 패널 상태를 관리하므로 Vue 런타임이 필요하지 않습니다. 프레임워크에서 상태를 관리하는 편이 유용한 경우 Vue 버전에서 CdxSearchInput과 CdxButton을 가져옵니다.
코드 번들은 GPL-2.0-or-later 라이선스이며, 라이선스는 로컬 에셋과 함께 제공됩니다. 예제에는 Wikipedia의 정체성이나 문서 콘텐츠를 복사하지 않았습니다. 실제 검색 엔드포인트에 연결하기 전에는 로컬 검색 결과 없음 상태의 이름만 바꾸는 대신 네트워크 오류, 로딩, 오래된 응답을 별도로 처리하세요.
전체 문서에 레이아웃, 컨트롤 및 초기화가 포함되어 있습니다. 링크된 예시 아카이브의 압축을 풀면 정확한 상대 경로의 벤더 에셋을 얻을 수 있습니다. 그런 다음 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>
Sources에서 완전한 예시를 다운로드하세요. README에 정확한 로컬 실행 명령이 안내되어 있습니다.
벤더 경로는 이 문서에 대한 상대 경로로 유지하세요. 아카이브에는 이 미리보기에 사용된 에셋이 모두 포함되어 있습니다.
04
Codex 디자인 시스템 에이전트 설정
구현 시작점
독립형 미리보기에서 기본 스타일시트를 로컬로 확인했습니다. 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';
프로젝트를 위한 프롬프트
에이전트 프롬프트
Codex 2.7.0의 CSS 전용 SearchInput 및 버튼을 사용해 로컬 지식 색인을 구축하세요. 문서화된 끝 버튼 래퍼, 명시적인 검색 레이블, 기본 양식 제출 기능을 유지하세요. 결과 수, 일치 항목 없음 메시지, 지우기 동작을 표시하세요. 결과 세부 정보를 인라인으로 열고, 제목에 포커스를 맞춘 뒤 닫을 때 처음 실행한 버튼으로 포커스를 돌려보내세요. TypeaheadSearch나 모달 의미를 주장하지 마세요. 공식 글꼴 및 간격 역할을 사용하되 콘텐츠 너비는 애플리케이션에서 정한 값임을 밝히세요.
05
Codex 디자인 시스템 출처 및 범위
독창적인 요약을 사용한 독립형 OpenDesign 예제입니다. Wikipedia 콘텐츠나 정체성을 복사하지 않았습니다. CSS 전용 컨트롤은 기본 Codex 요소이며, 검색 필터링과 인라인 읽기 패널은 애플리케이션 코드로 구현합니다.