diff --git a/README.kr.md b/README.kr.md
new file mode 100644
index 0000000..5cafcf3
--- /dev/null
+++ b/README.kr.md
@@ -0,0 +1,212 @@
+Design -isms
+스타일을 보고, 화면을 조합하고, 구현으로 이어가세요.
+디자인 레퍼런스 아틀라스 · 프런트엔드 패턴 · 에이전트용 Code Mode MCP
+
+English · 한국어
+
+
+ 사이트 둘러보기 → ·
+ MCP 설치 ·
+ MCP ·
+ 플러그인 가이드 ·
+ 문제 제보
+
+
+
+ 
+ 
+
+
+## MCP 설치
+
+Node.js 22 이상이 필요합니다. 저장소를 내려받으면 커밋된 JavaScript로 바로 조회할 수 있습니다.
+MCP만 사용할 때는 `npm install`이나 빌드가 필요하지 않습니다.
+
+```bash
+git clone https://github.com/lidge-jun/design-isms.git
+```
+
+MCP 클라이언트에 다음 stdio 서버를 추가하세요. `/absolute/path/design-isms`를 실제 **절대 경로**로 바꿉니다.
+아래는 `mcpServers` 형식이며, 설정 파일 위치와 최상위 키는 호스트마다 다를 수 있습니다.
+
+```json
+{
+ "mcpServers": {
+ "design-isms": {
+ "command": "node",
+ "args": ["/absolute/path/design-isms/scripts/mcp/server.mjs"]
+ }
+ }
+}
+```
+
+연결되면 `execute_code` 도구 하나가 보입니다. `return actions.find();`로 지원 연산을 확인하세요.
+[API와 사용 예시](#code-mode-mcp) · [에이전트 스킬 설치](#코딩-에이전트에서-사용) · [사이트 열기](https://lidge-jun.github.io/design-isms/)
+
+
+
+**어떤 스타일인지 알아보는 순간부터, 어떻게 만들지 결정하는 순간까지.**
+Design -isms는 스타일별 시각 자료와 구현 가이드, 실제 조작할 수 있는 UI 패턴을 모은 레퍼런스입니다.
+브라우저에서 살펴보거나, 코딩 에이전트가 같은 데이터를 검색해 팔레트·서체·레이아웃·코드 예시를 가져올 수 있습니다.
+
+## 화면에서 확인하세요
+
+| 필요한 것 | 살펴볼 내용 |
+| --- | --- |
+| **디자인 방향** | Minimalism, Bauhaus, Brutalism 등 스타일의 이미지·역사·팔레트·실제 사이트 예시 |
+| **동작하는 UI** | 바텀시트, 드로어, 스크롤 리빌 등의 데모·HTML/CSS/JS·접근성 및 성능 체크 |
+| **화면 구성** | 제품 소개·기사 읽기·설정 작업 레시피와 교체 가능한 스타일·색상·서체·모션 |
+| **구현 근거** | 사용하기 좋은 상황, 피해야 할 상황, 구현 제약과 출처를 담은 한영 브리프 |
+
+### 재료를 고르고, 구현 가이드를 복사하세요
+
+메인 페이지의 **화면에 맞는 조합 찾기**에서 목적을 선택하세요. 허용된 대안으로 재료를 바꾸고,
+상세 레퍼런스를 확인한 뒤 **구현 가이드 복사**로 에이전트에게 전달할 수 있습니다.
+자동 복사가 막히면 전문을 직접 선택해 복사할 수 있습니다.
+
+
+
+레시피는 구현을 위한 설계 자료입니다. 완성된 페이지를 생성하거나 사용자 제품의 품질을 자동으로 보증하지는 않습니다.
+사이트 화면은 한국어와 영어로 전환할 수 있습니다. 위 이미지는 실제 사이트를 캡처했습니다.
+
+## 카탈로그
+
+| 카탈로그 | 항목 | 포함된 자료 |
+| --- | ---: | --- |
+| [Design ISMs](https://lidge-jun.github.io/design-isms/) | 49 | 시각 스타일과 AI Slop 진단, 목업 이미지, 팔레트, 개발 가이드 |
+| [UI Effects](https://lidge-jun.github.io/design-isms/effects.html) | 94 | 인터페이스 패턴 46종과 시각 효과 48종, 전용 데모와 코드 |
+| [Color Systems](https://lidge-jun.github.io/design-isms/color.html) | 25 | 역할별 색상, light/dark 변형, 대비 가이드 |
+| [Typography Pairings](https://lidge-jun.github.io/design-isms/typography.html) | 20 | 서체 조합, 타입 스케일, 라이브 스페시먼 |
+| [Layout Patterns](https://lidge-jun.github.io/design-isms/layout.html) | 25 | 반응형 와이어프레임과 구현 스니펫 |
+| [Motion Presets](https://lidge-jun.github.io/design-isms/motion.html) | 20 | easing·duration, 재생 제어, 모션 감소 대응 |
+
+Liquid Glass의 재질 비교와 Motion의 진행률·탭·목록 재정렬 같은 조작 예제도 확인할 수 있습니다.
+카탈로그의 목업·가이드 이미지는 AI 생성 자료이며 실제 서비스의 스크린샷과 구분됩니다.
+AI Slop은 진단용 항목으로, 스타일 추천과 관련 항목에는 노출되지 않습니다.
+
+## 빠른 시작
+
+### 웹에서 사용
+
+**[Design -isms 열기](https://lidge-jun.github.io/design-isms/)** — 설치나 계정 없이 탐색할 수 있습니다.
+스타일 이름을 모르면 **스타일 찾기**를, 만들 화면의 목적이 정해졌다면 **화면에 맞는 조합 찾기**를 사용하세요.
+
+### 코딩 에이전트에서 사용
+
+Claude Code에는 두 명령으로 설치합니다.
+
+```bash
+claude plugin marketplace add lidge-jun/design-isms
+claude plugin install design-isms@lidge-jun
+```
+
+```text
+내 포트폴리오에 맞는 디자인 스타일을 비교해줘.
+바텀시트의 구현 코드와 접근성 체크를 보여줘.
+```
+
+`style`과 `effect` 스킬이 저장소의 JSON을 읽습니다. 연결된 Design -isms MCP가 있으면 같은 자료를
+MCP로 조회할 수 있습니다. **플러그인 설치와 MCP 연결은 별도 설정**입니다.
+Codex·agy 설치, 스킬 호출과 문제 해결은 [플러그인 가이드](docs/PLUGIN.md)를 참고하세요.
+
+## Code Mode MCP
+
+공개 도구는 **`execute_code` 하나**입니다. 상주 설명은 2,000 UTF-8바이트 이하로 유지하고,
+세부 API는 필요할 때 `actions.find()`와 `actions.describe()`로 조회합니다.
+
+아래 코드를 `execute_code`의 `code` 인수로 전달하면 조합을 구현 브리프로 바꿉니다.
+
+```js
+const composition = design.compose({
+ recipeId: 'settings-workspace',
+ lang: 'ko'
+});
+return design.brief({ composition }).text;
+```
+
+| 연산 | 용도 |
+| --- | --- |
+| `design.search` / `design.get` | 카탈로그 검색과 상세·가이드·코드 조회 |
+| `design.recipes` / `design.compose` | 레시피 탐색과 허용된 대안 조합 |
+| `design.brief` | 검증한 조합을 Markdown으로 변환 |
+| `actions.find` / `actions.describe` | 연산 목록, 인수와 예시 확인 |
+
+작은 동기 함수가 일반 데이터를 반환하므로 `map`, `filter`, `reduce`로 가공할 수 있습니다.
+MCP의 기본 응답 한도는 JSON-RPC 포장을 포함한 8KiB입니다. 코드를 중간에서 자르지 않고,
+전체 반환이 불가능하면 `RESPONSE_TOO_LARGE`로 알려줍니다.
+
+로컬 stdio 전용이며 네트워크 포트를 열지 않습니다. 신뢰한 에이전트용으로, Worker/VM을 악성 코드용
+보안 샌드박스로 취급하면 안 됩니다. [API·페이지 이동·실행 제한](docs/PLUGIN.md#10-작은-연산을-조합하는-mcp--cli)을 확인하세요.
+
+## CLI와 셸 파이프
+
+`cd design-isms`로 저장소에 들어간 뒤 같은 연산을 줄 단위 JSON으로 사용할 수 있습니다. stdin 한 줄에 요청 하나, stdout 한 줄에 결과 하나입니다.
+
+```sh
+printf '%s\n' '{"op":"design.search","args":{"query":"바텀 시트","limit":3}}' |
+ node scripts/design-query.mjs
+```
+
+
+조합 → 브리프 파이프 예시 (jq 필요)
+
+```sh
+printf '%s\n' '{"op":"design.compose","args":{"recipeId":"settings-workspace","lang":"ko"}}' |
+ node scripts/design-query.mjs |
+ jq -c '{op:"design.brief",args:{composition:.}}' |
+ node scripts/design-query.mjs
+```
+
+오류도 JSON 한 줄로 반환하며 다음 요청을 계속 처리합니다. 오류가 하나라도 있으면 종료 코드는 1입니다.
+CLI는 임의의 JavaScript를 실행하지 않습니다.
+
+
+
+## 개발과 기여
+
+Node.js 22 이상과 npm을 사용합니다. 로컬 서버는 아래 명령에서 만든 `.pages/`를 제공합니다.
+
+```bash
+npm ci
+npm run build
+npm run verify
+npm run pages:stage
+npm run serve
+```
+
+브라우저에서 **http://127.0.0.1:4173**을 여세요. 수정 후에는 `build` → `verify` → `pages:stage`를 다시 실행합니다.
+TypeScript는 `src/`, 커밋할 브라우저 산출물은 `assets/js/`, 사이트·스킬·MCP의 공통 데이터는 `assets/data/`에 있습니다.
+`verify`는 파일을 생성하지 않습니다.
+
+변경은 `dev` 대상 PR로 제안합니다. 검증한 `dev`를 `main`에 반영하면 GitHub Actions가 다시 검증한 뒤
+허용된 `.pages/` 파일만 GitHub Pages에 배포합니다. 스킬·MCP 서버·개발 문서는 사이트 배포에 포함되지 않습니다.
+문제 제보에는 페이지 주소, 화면 크기, 재현 순서를 함께 적어주세요.
+
+| 문서 | 내용 |
+| --- | --- |
+| [프로젝트 구조](structure/README.md) | 모듈별 책임과 데이터의 기준 파일 |
+| [기여 규칙](AGENTS.md) | 카탈로그 추가, 생성 JS, 이미지·접근성·검증 계약 |
+| [플러그인과 MCP](docs/PLUGIN.md) | 설치, 스킬, API와 문제 해결 |
+| [FAQ](https://lidge-jun.github.io/design-isms/faq.html) | 디자인 자료를 고르고 사용하는 방법 |
+
+
+카탈로그 유지보수
+
+원본 PNG와 WebP 미리보기는 함께 관리합니다. 이미지를 바꾸면 `npm run images:thumbs`와 해당 감사 절차를 실행하고,
+`npm run verify`로 해시·이미지 품질·비대상 자료의 보존을 확인하세요. 자세한 절차는 [기여 규칙](AGENTS.md)에 있습니다.
+
+카탈로그: 49 ISMs / 94 effects / 18 FAQ answers.
+
+
+
+## 출처와 크레딧
+
+| 프로젝트 | 반영한 내용 | 원본 라이선스 |
+| --- | --- | --- |
+| [StyleGallery](https://github.com/changeroa/StyleGallery) · IYEN | 필수·보조·교체 가능 요소와 화면 조합 제약 | 코드 MIT · 문서 CC BY 4.0 |
+| [Taste Skill](https://github.com/Leonxlnx/taste-skill) · Leonxlnx | 목적에 맞는 디자인, 정보 밀도와 모션, 기존 디자인 보존 | MIT |
+| [aside-codemode](https://github.com/lidge-jun/aside-codemode) · lidge-jun | 하나의 MCP 도구와 점진적 API 탐색 | MIT |
+| [TasteCode](https://github.com/Leonxlnx/tastecode) · Leonxlnx / Blueemi | Browser/Design Mode의 화면 안정화와 DOM 검토 방식 조사 | Apache-2.0 · 코드 미포함 |
+
+확인한 리비전, 각색 범위와 원문 고지는 [ATTRIBUTION.md](docs/ATTRIBUTION.md)에 보존합니다.
+위 라이선스는 각 원본 자료에 적용되며, 이 저장소 전체나 AI 생성 이미지의 이용 조건을 대신하지 않습니다.
diff --git a/README.md b/README.md
index e13ab6f..8e3df9f 100644
--- a/README.md
+++ b/README.md
@@ -1,237 +1,203 @@
-# Design -isms
+Design -isms
+Find a style. Compose a screen. Build with a reference.
+A visual design atlas, frontend pattern library, and Code Mode MCP for coding agents.
-49개 디자인 ism을 한 번에 훑어보는 시각 레퍼런스 보드입니다. 각 스타일은 AI mockup 이미지, 역사/맥락, 컬러 팔레트, 실제 사이트 예시, 이미지 생성 프롬프트, 관련 ISM, 그리고 팝업 하단의 개발 가이드까지 함께 제공합니다.
+English · 한국어
-별도 페이지 `effects.html`에서는 모바일과 데스크탑 프런트엔드 UI 후보군을 이름을 몰라도 찾아볼 수 있게 정리합니다. 카드별 미니 데모, 상세 모달, 접근성 체크, 성능 체크, 94개 전체 ima2 guide 이미지와 WebP preview, 그리고 효과별 배경/히스토리/사용 시점 문서를 포함합니다.
+
+ Explore the atlas → ·
+ Install MCP ·
+ Agent skills ·
+ API ·
+ Report an issue
+
-Catalog 드롭다운으로 이어지는 네 개의 자매 카탈로그가 백과사전을 완성합니다: `color.html`(역할 기반 팔레트 25종 — light/dark 변형과 WCAG AA 대비 검사), `typography.html`(폰트 페어링 20종 — 라이브 웹폰트 스페시멘과 타입 스케일), `layout.html`(반응형 섹션 패턴 25종 — 데스크탑/태블릿/모바일 3단 와이어프레임 비교와 코드 스니펫), `motion.html`(모션 레시피 20종 — easing 곡선 시각화, 라이브 데모, reduced-motion 대응). ISM 모달의 "관련 카탈로그" 섹션과 각 카탈로그 모달의 관련 ISM/Effects 링크가 서로를 잇습니다.
+
+
+
+
-[Live Site](https://lidge-jun.github.io/design-isms/) · [Repository](https://github.com/lidge-jun/design-isms)
+## Install the MCP
-## AI Agent Plugin
-
-이 저장소는 Claude Code · Codex · agy용 플러그인이기도 합니다. 사이트와 같은 데이터셋을 에이전트가 직접 질의해 팔레트·폰트·그리드 수치와 실행 가능한 UI 코드를 반환합니다.
+Requires **Node.js 22+**. Clone the repository; the query runtime uses committed JavaScript and Node built-ins, so no `npm install` or build is needed for MCP use.
```bash
-claude plugin marketplace add lidge-jun/design-isms
-claude plugin install design-isms@lidge-jun
+git clone https://github.com/lidge-jun/design-isms.git
```
-설치·스킬 사용법·문제 해결은 [docs/PLUGIN.md](docs/PLUGIN.md)를 참고하세요.
+Add this stdio server to your MCP client. Replace `/absolute/path/design-isms` with the **absolute path** to your clone.
+This example uses the `mcpServers` format; your host may use a different configuration file or top-level key.
+
+```json
+{
+ "mcpServers": {
+ "design-isms": {
+ "command": "node",
+ "args": ["/absolute/path/design-isms/scripts/mcp/server.mjs"]
+ }
+ }
+}
+```
-## What It Shows
+Once connected, you should see one tool: **`execute_code`**. Run `return actions.find();` to discover its operations.
+[API and examples](#code-mode-mcp) · [Agent skill installation](#agent-skills) · [Use the website](https://lidge-jun.github.io/design-isms/)
-- 49 design -isms from Minimalism to the AI Slop anti-pattern diagnosis
-- 147 AI-generated ISM mockup images
-- 147 lightweight ISM WebP thumbnails for fast card/modal loading
-- Original PNG lightbox only when the user clicks an image
-- 10 real website examples per ism, initially collapsed to 3
-- Modal detail view with history, prompts, palette, keywords, related ISMs
-- Development guide per ism: fitting components, build method, verification points
-- Korean/English UI toggle
-- Frontend UI Candidates page with 94 entries: 46 interface patterns and 48 visual effects
-- 94 dedicated live demo types for the candidate cards and modals
-- 94 guide images under `assets/images/effects/`
-- 94 guide WebP previews under `assets/images/thumbs/effects/`
-- Long-form effect documentation in `assets/data/effects-docs.json`
-- 8 newly added ima2-generated ISM styles: Editorial Typography, Variable Typography, Monospace / Terminal UI, Pixel Art UI, De Stijl, Constructivism, Isometric 3D UI, and Pop Art
-- Grok research prompts and ima2 prompt manifests for the ISM/effects expansion batch
+
-## Implementation Principles
+Design -isms connects visual references to implementation decisions. Browse styles and interactive UI patterns,
+or let your coding agent query the same catalog for palettes, typography, layout guidance, and code examples.
-Catalog source-of-truth counts: 49 ISMs / 94 effects / 18 FAQ answers.
+## From reference to implementation
-- README, `AGENTS.md`, `structure/README.md`, and `devlog/` must stay aligned with the shipped behavior.
-- `src/*.ts` is the editable source; `assets/js/*.js` is generated output and still committed because GitHub Pages serves static files directly.
-- The site uses plain static scripts, not `script type="module"`. Keep script order explicit in HTML.
-- The shared top navigation is duplicated in static HTML across all seven public pages (`index.html`, `effects.html`, `faq.html`, `color.html`, `typography.html`, `layout.html`, `motion.html`); every page exposes the same six axes (Isms / Catalog / FAQ / GitHub / Lang / Count) in identical order, with the Catalog dropdown listing Effects / Color / Typography / Layout / Motion, validated by `npm run verify:nav`.
-- FAQ content lives in `assets/data/faq.json` (bilingual, source-linked, 18 answers) and renders through `src/faq.ts` → `assets/js/faq.js`; `faq.html` is a thin entry document with no inline styles or scripts.
-- Shared storage/history guards, loading dismissal, retryable fatal states, and broken-image fallbacks live in `src/app-runtime.ts` → `assets/js/app-runtime.js`; all three pages load it before their page renderer and share `assets/css/runtime-states.css`.
-- The visual shell uses the Annotated Specimen Atlas system: shared tokens live in `assets/css/theme-atlas.css`, loaded after `style.css` and before `nav.css` on every page.
-- The ISM modal on `index.html` uses `AppDialogA11y` (`src/app-dialog.ts`) for focus trap, Escape layering, scroll lock, and focus restore; `assets/js/app-dialog.js` must load before `assets/js/app.js`.
-- The ISM modal is implemented: history appears under the title, the main prompt is always visible, secondary prompts are collapsible, example sites show 3 first and expand to the rest, and related ISMs are computed from keyword overlap.
-- The effects page is a 94-entry catalog: 46 interface patterns plus 48 visual effects across 7 families (scroll, text motion, hero background, cursor, view transition, micro-interaction).
-- Every effects candidate must have a dedicated `demo.type` equal to its effect `id`, and that type must exist in `src/effects-demos.ts`. Do not reuse a generic seed demo for a new candidate.
-- Effects long-form writing lives in `assets/data/effects-docs.json` and renders through `src/effects-docs.ts`. Keep `assets/data/effects.json` compact for operational card/demo data.
-- Every effects guide image keeps the original PNG at `assets/images/effects/{effect-id}/guide.png` and uses a generated WebP preview at `assets/images/thumbs/effects/{effect-id}/guide.webp`.
-- New ISM images keep originals at `assets/images/{ism-id}/` and runtime previews under `assets/images/thumbs/{ism-id}/`.
-- `assets/data/image-pairs-manifest.json` locks all 331 PNG/WebP pairs (211 legacy + 30 effects expansion + 25 color + 20 typography + 25 layout + 20 motion) by path, dimensions, SHA-256, and an independent source-resize/preview pixel-relation limit; `npm run images:thumbs` updates it atomically and does not rely on mtimes.
-- The production image-quality gate audits the 211 immutable legacy slots in four complete contact sheets; catalog additions are admitted by live hash and validated by `verify-catalog` domain ledgers. `npm run verify:image-quality` checks the immutable baseline, per-slot rubric ledger, generation attempts, approved prompt changes, final sheets, and non-target byte stability.
-- `npm run verify` is non-emitting: edit TypeScript, run `npm run build`, then verify committed JS parity and all content/asset/release gates.
-- `npm run pages:stage` creates the only deployable tree at `.pages/`; Pages workflows upload that allowlisted tree, never the repository root.
-- Do not publish a separate reference/backlog page; generated visual styles belong in the ISMS catalog or the Effects catalog.
-- Any visual or image pipeline change must run `npm run verify`; image changes must also run `npm run images:thumbs` (sharp-based, `--force` / `--scope effects|isms|color|typography|layout|motion|all`) and pass `npm run images:audit`.
-- Effect guide regeneration is provenance-tracked: audit ledger `devlog/_fin/260715_production_upgrade/031_effect_guide_audit.csv`, manifest `devlog/_fin/260715_production_upgrade/032_effect_guide_manifest.jsonl`; sister-catalog guides use per-domain ledgers under `devlog/_fin/260717_design-encyclopedia-upgrade/`.
-
-## Project Structure
+| What you need | What you get |
+| --- | --- |
+| **A design direction** | Style mockups, history, palettes, and real website references, from Minimalism to Bauhaus and Brutalism |
+| **A working pattern** | Bottom sheets, drawers, scroll reveals, and more, with demos, HTML/CSS/JS, and accessibility guidance |
+| **A screen composition** | Product landing, editorial reading, and settings recipes with compatible style, color, type, and motion alternatives |
+| **An implementation brief** | Usage guidance, constraints, checks, and sources in English or Korean |
-```text
-701_design-isms/
-├── index.html
-├── effects.html
-├── assets/
-│ ├── css/
-│ │ ├── style.css
-│ │ ├── nav.css
-│ │ ├── effects.css
-│ │ ├── effects-docs.css
-│ │ ├── effects-demos.css
-│ │ └── effects-demos-candidates.css
-│ ├── data/
-│ │ ├── isms.json
-│ │ ├── effects.json
-│ │ ├── effects-docs.json
-│ │ ├── image-pairs-manifest.json
-│ │ └── research-prompts.json
-│ ├── images/{ism-id}/*.png
-│ ├── images/effects/{effect-id}/guide.png
-│ ├── images/thumbs/{ism-id}/*.webp
-│ ├── images/thumbs/effects/{effect-id}/guide.webp
-│ └── js/
-│ ├── effects-demos.js
-│ ├── effects-docs.js
-│ ├── app-runtime.js
-│ ├── app.js
-│ └── effects.js
-├── src/
-│ ├── app.ts
-│ ├── app-runtime.ts
-│ ├── effects-demos.ts
-│ ├── effects-docs.ts
-│ └── effects.ts
-├── scripts/generate-thumbnails.mjs
-├── scripts/verify-generated.mjs
-├── scripts/verify-content.mjs
-├── scripts/verify-assets.mjs
-├── scripts/stage-pages.mjs
-├── scripts/prepare-expansion-data.mjs
-├── structure/
-├── devlog/
-├── package.json
-└── tsconfig.json
-```
+### Choose the ingredients. Copy the brief.
-## Development
+Open the recipe chooser on the home page, select a screen purpose, and adjust the permitted alternatives.
+Inspect the linked references, then copy the implementation brief into your coding agent. If automatic copying is unavailable,
+the full text remains selectable.
-```bash
-npm install
-npm run typecheck
-npm run build
-npm run verify
-npm run pages:stage
-```
+
-The browser entry files are generated for GitHub Pages:
+Recipes provide design guidance; they do not generate a finished page or certify your product.
+The site supports English and Korean. These screenshots show the actual interface; mockups within catalog cards are AI-generated reference images.
-- Edit `src/app.ts`, then run `npm run build` for `assets/js/app.js`.
-- Edit `src/effects-demos.ts`, `src/effects-docs.ts`, or `src/effects.ts`, then run `npm run build` for `assets/js/effects-demos.js`, `assets/js/effects-docs.js`, and `assets/js/effects.js`.
+## Catalogs
-## Image Pipeline
+| Catalog | Entries | Includes |
+| --- | ---: | --- |
+| [Design ISMs](https://lidge-jun.github.io/design-isms/) | 49 | Visual styles and an AI Slop diagnostic, mockups, palettes, and implementation guides |
+| [UI Effects](https://lidge-jun.github.io/design-isms/effects.html) | 94 | 46 interface patterns and 48 visual effects, each with a dedicated demo |
+| [Color Systems](https://lidge-jun.github.io/design-isms/color.html) | 25 | Semantic palettes, light/dark variants, and contrast guidance |
+| [Typography Pairings](https://lidge-jun.github.io/design-isms/typography.html) | 20 | Font pairings, type scales, and live specimens |
+| [Layout Patterns](https://lidge-jun.github.io/design-isms/layout.html) | 25 | Responsive wireframes and implementation snippets |
+| [Motion Presets](https://lidge-jun.github.io/design-isms/motion.html) | 20 | Easing, duration, playback controls, and reduced-motion alternatives |
-```bash
-npm run images:thumbs
-```
+Try the Liquid Glass material comparison and interactive motion examples for progress, tabs, and list reordering.
+The AI Slop entry is diagnostic only; it is excluded from recommendations and related styles.
-The static pages use WebP thumbnails/previews for card and modal image loading. The original 1536x1024 PNG files are kept for click-to-zoom lightbox views and source preservation. The thumbnail command updates the 331-pair SHA manifest after every successful run.
+## Agent skills
-Expansion image batches are generated from deterministic manifests. The current ima2 command shape is:
+For Claude Code:
```bash
-ima2 ping
-ima2 gen --stdin -q high -s 1536x1024 -o --json --timeout 300
+claude plugin marketplace add lidge-jun/design-isms
+claude plugin install design-isms@lidge-jun
```
-The current expansion batch generated 24 new ISM PNG originals and `npm run images:thumbs` generated matching WebP previews. The production completion audit later replaced only the two rubric-failed landing images (`minimalism`, `indie-web`) using ima2 with `gpt-5.6-sol`, high reasoning, and high image quality; the other 209 slots remain byte-identical to their captured baseline.
+```text
+Compare design styles for my portfolio.
+Show me bottom-sheet implementation code and accessibility checks.
+```
-## Data
+The `style` and `effect` skills read the repository's JSON. They can query a connected Design -isms MCP server when available.
+**Plugin installation and MCP configuration are separate steps.**
+For Codex and agy installation, skill usage, and troubleshooting, see the [plugin guide (Korean)](docs/PLUGIN.md).
-- Edit core ISM data in `assets/data/isms.json`.
-- Edit frontend UI candidate data in `assets/data/effects.json`.
-- Edit frontend UI long-form documentation in `assets/data/effects-docs.json`.
-- Edit reusable Grok/ima2 prompt records in `assets/data/research-prompts.json`.
-- Add original images under `assets/images/{ism-id}/`.
-- Add guide images under `assets/images/effects/{effect-id}/guide.png`.
-- Regenerate thumbnails with `npm run images:thumbs` after changing images.
-- Keep image filenames aligned with `isms.json`.
+## Code Mode MCP
-## Deploy
+One public tool, **`execute_code`**, exposes small synchronous functions that return ordinary data.
+Its resident description stays below **2,000 UTF-8 bytes**; discover full operation schemas with `actions.find()` and `actions.describe()` as needed.
-GitHub Pages deploys automatically on `main` pushes through `.github/workflows/deploy.yml`.
-Agents should commit or push only when the user explicitly asks in the same turn.
+Pass this as the tool's `code` argument to compose a screen and return its implementation brief:
-```bash
-git add -A
-git commit -m "[agent] feat: update design isms"
-git push origin main
+```js
+const composition = design.compose({
+ recipeId: 'settings-workspace',
+ lang: 'en'
+});
+return design.brief({ composition }).text;
```
-### Liquid Glass 구현 가이드
+| Operation | Purpose |
+| --- | --- |
+| `design.search` / `design.get` | Search catalogs and retrieve summaries, guides, or code |
+| `design.recipes` / `design.compose` | Discover recipes and compose permitted alternatives |
+| `design.brief` | Validate a composition and format it as Markdown |
+| `actions.find` / `actions.describe` | Discover operations, arguments, and examples |
-`#refractive-glass-ui`에서 Liquid Glass의 배경과 Apple 27 세대 프리뷰의 재질 개선을
-읽을 수 있습니다. 모달의 재질 예제는 장면 선택과 불투명 대안을 직접 비교합니다.
-웹용 CSS 응용이며 Apple 네이티브 굴절 렌더링과는 구별합니다.
-본문은 안정된 면에 두고, 유리 재질은 내비게이션·제어부에 제한합니다.
+Use JavaScript's `map`, `filter`, and `reduce` to work with the returned values.
+The default MCP response budget is **8 KiB**, including the JSON-RPC envelope. Code is returned whole or rejected with `RESPONSE_TOO_LARGE`.
+Direct search pages can be shortened at item boundaries, with a cursor for the remaining results.
-### 직접 조작하는 모션 레시피
+The server uses local stdio and opens no network port. It is intended for trusted local agents:
+Worker/VM limits contain mistakes, but are **not a security sandbox for hostile JavaScript**.
+See [API details, pagination, and execution limits (Korean)](docs/PLUGIN.md#10-작은-연산을-조합하는-mcp--cli).
-Motion Presets의 진행률·스크롤 등장·접기·탭·목록 재정렬은 상세 화면에서 직접 조작합니다.
-카드의 반복 미리보기는 0.4배속이며, 상세 조작 예제는 레시피의 시간을 사용합니다.
-일반 미리보기는 재생·일시정지·이어 재생·처음부터 재생을 구분합니다.
-CSS 레시피에는 필요한 JavaScript 상태 관리와 모션 감소 대응을 함께 설명합니다.
-재생 제어는 [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Animation),
-키보드 탭은 [WAI-ARIA Tabs Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/)을 참고합니다.
+## CLI and Unix pipes
-이미지 교체는 원본·WebP·프롬프트·검토 기록을 함께 갱신합니다. 이전 품질 감사 결과는
-해시별 이력으로 보관하며, 후속 결과도 비대상 이미지가 그대로인지 검증합니다.
+From your clone (`cd design-isms`), query the same operations using newline-delimited JSON: one request on stdin, one result on stdout.
-## References and acknowledgements
+```sh
+printf '%s\n' '{"op":"design.search","args":{"query":"bottom sheet","limit":3}}' |
+ node scripts/design-query.mjs
+```
-화면 조합과 에이전트 인터페이스 개선에는 다음 프로젝트의 설계 원칙을 참고합니다.
-각 원본의 확인 버전, 적용 범위와 라이선스 고지는 [출처 기록](docs/ATTRIBUTION.md)에 정리했습니다.
+
+Compose → brief pipeline (requires jq)
-| Project | Reference scope | License |
-| --- | --- | --- |
-| [StyleGallery](https://github.com/changeroa/StyleGallery) · IYEN | 화면 레시피의 필수·교체 가능 요소, 스크롤 책임, 검증 범위 구분 | Code: MIT / documentation: CC BY 4.0 |
-| [Taste Skill](https://github.com/Leonxlnx/taste-skill) · Leonxlnx | 목적에 맞는 디자인 선택, 정보 밀도와 모션의 분리, 기존 디자인 시스템 보존 | MIT |
-| [aside-codemode](https://github.com/lidge-jun/aside-codemode) · lidge-jun | 작은 MCP 도구 설명과 필요할 때 조회하는 상세 API | MIT |
+```sh
+printf '%s\n' '{"op":"design.compose","args":{"recipeId":"settings-workspace","lang":"en"}}' |
+ node scripts/design-query.mjs |
+ jq -c '{op:"design.brief",args:{composition:.}}' |
+ node scripts/design-query.mjs
+```
+
+Errors are also JSON lines. Processing continues after an invalid request; the process exits with code 1 if any request failed.
+The CLI does not execute arbitrary JavaScript. Use `node scripts/design-query.mjs --help` to inspect available operations.
+
+
+
+## Development and contributions
-기존 카탈로그 데이터와 이미지의 원본은 이 저장소에 있습니다. 위 프로젝트의 전체 자료나
-프레임워크를 포함한다는 뜻은 아니며, 새 기능의 구현 상태는 해당 PR과 사용 문서를 따릅니다.
+Use Node.js 22+ and npm. The local server serves the `.pages/` output created below.
-## 화면 레시피와 공통 검색 코어
+```bash
+npm ci
+npm run build
+npm run verify
+npm run pages:stage
+npm run serve
+```
-`assets/data/recipes.json`은 제품 소개, 편집형 읽기, 설정 작업 화면의 세 레시피를 담습니다.
-각 레시피는 기존 카탈로그 항목을 참조하며 필수·보조·교체 가능 역할, 허용 대안, 구현 제약과
-확인할 항목을 제공합니다. 완성된 페이지 코드나 제품 검증 결과를 뜻하지 않습니다.
+Open **http://127.0.0.1:4173**. After editing, run `build` → `verify` → `pages:stage` again.
+TypeScript lives in `src/`; commit its browser output in `assets/js/`.
+The website, skills, and MCP share `assets/data/`. Verification does not generate files.
-`src/design-*.ts`의 순수 코어는 브라우저와 Node에서 같은 검색·상세 조회·조합 규칙을 사용합니다.
-검색 결과에는 데이터 버전과 다음 커서가 붙고, anti-pattern은 명시적 조회에서만 나옵니다.
-`npm run test:design-core`로 검색·경계 입력·페이지 이동·레시피 계약을 검증합니다.
-MCP와 CLI는 아래 명령으로 사용할 수 있습니다. 사이트에서는 상단의 화면 조합 도구를 펼쳐 같은 레시피를 선택합니다.
+Submit changes as PRs targeting `dev`. Promoting verified changes to `main` runs verification again and deploys only the
+allowlisted `.pages/` output to GitHub Pages. Skills, the MCP server, and development documentation stay outside that deployment.
+For bug reports, include the page URL, viewport size, and steps to reproduce.
-## Code Mode MCP와 NDJSON CLI
+| Documentation | Contents |
+| --- | --- |
+| [Project structure](structure/README.md) | Module ownership and sources of truth |
+| [Contribution rules (Korean)](AGENTS.md) | Catalog additions, generated JS, imagery, accessibility, and verification contracts |
+| [Plugin and MCP guide (Korean)](docs/PLUGIN.md) | Installation, skills, API details, and troubleshooting |
+| [FAQ](https://lidge-jun.github.io/design-isms/faq.html) | Choosing and using design references |
-`node scripts/mcp/server.mjs`는 공개 도구 하나(`execute_code`)로 카탈로그를 조회합니다.
-`actions.find()` / `actions.describe()`로 상세 API를 읽고, `design.search/get/recipes/compose/brief`를
-일반 JavaScript와 조합합니다. 상주 설명은 2,000바이트 이하, 기본 응답은 전체 wire 기준 8KiB입니다.
+
+Catalog maintenance
-`node scripts/design-query.mjs`는 같은 연산을 줄 단위 JSON으로 제공합니다. `compose`가 반환한
-값을 `brief`에 넘기면 언어와 데이터 버전을 보존한 Markdown을 얻습니다.
+Keep PNG originals and WebP previews together. After changing imagery, run `npm run images:thumbs` and the relevant audit procedure,
+then `npm run verify` to check hashes, image quality, and preservation of unrelated assets. See the [contribution rules](AGENTS.md).
-```sh
-printf '%s\n' '{"op":"design.search","args":{"query":"바텀 시트","limit":3}}' | node scripts/design-query.mjs
-node scripts/design-query.mjs --help
-```
+Catalog source-of-truth counts: 49 ISMs / 94 effects / 18 FAQ answers.
-설정과 파이프 예시, 크기·실행 제한은 [플러그인 안내](docs/PLUGIN.md#10-작은-연산을-조합하는-mcp--cli)에 있습니다.
-이 MCP는 신뢰한 로컬 에이전트용이며 Worker/VM을 악성 코드용 보안 샌드박스로 취급하지 않습니다.
+
-## 화면에 맞는 조합 찾기
+## Credits and source licenses
-메인 페이지에서 조합 도구를 펼치면 제품 소개·기사 읽기·설정 작업 중 목적을 고를 수 있습니다.
-스타일, 배치, 색상, 서체, 효과와 모션을 허용된 대안으로 바꾸고 실제 레퍼런스를 열어보세요.
-선택한 조합의 구현 제약·확인 항목·출처를 한영 브리프로 복사할 수 있습니다.
+| Project | Adapted or referenced ideas | Upstream license |
+| --- | --- | --- |
+| [StyleGallery](https://github.com/changeroa/StyleGallery) · IYEN | Required, supporting, and substitutable recipe roles; composition constraints | Code: MIT · documentation: CC BY 4.0 |
+| [Taste Skill](https://github.com/Leonxlnx/taste-skill) · Leonxlnx | Purpose-led design, density and motion, preserving existing design systems | MIT |
+| [aside-codemode](https://github.com/lidge-jun/aside-codemode) · lidge-jun | A single MCP tool with progressive API discovery | MIT |
+| [TasteCode](https://github.com/Leonxlnx/tastecode) · Leonxlnx / Blueemi | Browser/Design Mode settling and DOM review practices; research only | Apache-2.0 · no code included |
-자료는 처음 펼칠 때 읽고 재사용합니다. 실패하면 도구 안에서 다시 시도할 수 있으며,
-자동 복사가 막힌 환경에서는 전문을 직접 선택해 복사합니다. 기존 카탈로그 탐색과
-스타일 찾기는 그대로 사용할 수 있습니다.
+Pinned revisions, adaptation scopes, and original notices are recorded in [ATTRIBUTION.md](docs/ATTRIBUTION.md).
+These licenses apply to their respective upstream materials; they do not establish a blanket license for this repository or its AI-generated images.
diff --git a/docs/images/README.md b/docs/images/README.md
new file mode 100644
index 0000000..2077e41
--- /dev/null
+++ b/docs/images/README.md
@@ -0,0 +1,14 @@
+# README screenshots
+
+These are unretouched browser captures of the live Design -isms site at
+`https://lidge-jun.github.io/design-isms/`, captured on 2026-09-22.
+
+- `atlas.png`: 1440 × 1000, Korean catalog overview.
+- `recipes.png`: 1440 × 900, Korean settings-workspace recipe with the Bauhaus alternative.
+- `atlas-en.png`: 1440 × 1000, English catalog overview.
+- `recipes-en.png`: 1440 × 900, English settings-workspace recipe with the Bauhaus alternative.
+- Deployed source: `57e8fcab57df9d3cb8f1a2f94f2e4c28da7b32ac`.
+
+The screenshots depict the actual interface. Mockups shown inside catalog cards
+are AI-generated reference images. These documentation assets are outside the
+GitHub Pages staging allowlist and do not alter catalog image-quality ledgers.
diff --git a/docs/images/atlas-en.png b/docs/images/atlas-en.png
new file mode 100644
index 0000000..8f764cf
Binary files /dev/null and b/docs/images/atlas-en.png differ
diff --git a/docs/images/atlas.png b/docs/images/atlas.png
new file mode 100644
index 0000000..deb196c
Binary files /dev/null and b/docs/images/atlas.png differ
diff --git a/docs/images/recipes-en.png b/docs/images/recipes-en.png
new file mode 100644
index 0000000..60a19a5
Binary files /dev/null and b/docs/images/recipes-en.png differ
diff --git a/docs/images/recipes.png b/docs/images/recipes.png
new file mode 100644
index 0000000..21ba036
Binary files /dev/null and b/docs/images/recipes.png differ