fix(ranui): refine reasoning and streamline agent design guidance

.claude-plugin/marketplace.json

@@ -12,14 +12,18 @@
     {
       "name": "ranui",
       "source": "./plugins/ranui",
-      "description": "ranui web-component library: import map, element inventory, builder/reactivity, accessibility, conventions.",
-      "author": { "name": "chaxus" }
+      "description": "Build, review and polish ranui UI: task-to-rule lookup, public contracts and browser acceptance.",
+      "author": {
+        "name": "chaxus"
+      }
     },
     {
       "name": "ranuts",
       "source": "./plugins/ranuts",
       "description": "ranuts utility library: import map (utils/node/visual/vnode), ranuts/utils inventory, conventions.",
-      "author": { "name": "chaxus" }
+      "author": {
+        "name": "chaxus"
+      }
     }
   ]
 }

AGENTS.md

@@ -17,6 +17,8 @@ Start with the owner of the change; do not load every reference or introduce a s
 do not create a parallel palette or copy one application's dimensions into library defaults.
 The index routes decisions; workflow recipes describe host responsibilities, not extra ranui APIs.
 
+For visual changes, use the [UI task lookup](packages/ranui/docs/INTERFACE_GUIDE.md#ui-task-lookup)
+to find exact owner sections and an evidence brief.
 Read only applicable owner sections; reuse existing controls and local token mappings. Stop when
 the contract, smallest patch and evidence are clear. Optional recipes do not require new infrastructure.
 

README.md

@@ -47,6 +47,31 @@ document.body.append(button);
 
 Components use custom elements and standard browser events, so no React or Vue runtime is required. Import other components through their own entries, such as `ranui/input`. See the [component examples](https://ran.chaxus.com/src/ranui/) for markup, events and customization, or a [standalone script example](./packages/ranui/README.md#iife--cdn) for use without a bundler.
 
+## Use with an agent
+
+The [ranui skill](./plugins/ranui/skills/ranui/SKILL.md) guides UI implementation, visual
+review and browser acceptance. It reads the host's installed ranui references on demand;
+it does not install the library or add tools, hooks or external services.
+
+**Claude Code plugin** — add this repository's marketplace, then install ranui:
+
+```sh
+claude plugin marketplace add chaxus/ran
+claude plugin install ranui@ran
+```
+
+Invoke `/ranui:ranui` in a new session. The same marketplace also offers `ranuts` for utility work.
+
+**Codex skill** — after cloning this repository, copy `plugins/ranui/skills/ranui/` into
+your host project's `.agents/skills/ranui/`. Start a new task and invoke `$ranui`.
+This uses the same skill body; the `.claude-plugin` manifest is the Claude installation route.
+See [Codex skill discovery](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills).
+
+Example task: “Use ranui to polish this settings pane: keep related text together, align
+control labels, and verify actual screenshots in light/dark at narrow/wide widths.”
+The [UI task lookup](./packages/ranui/docs/INTERFACE_GUIDE.md#ui-task-lookup) maps these
+requests to canonical rules and an evidence brief. Source contributors start with [AGENTS.md](./AGENTS.md).
+
 ## Work on the repository
 
 Use Node 24+ and pnpm 11.6.0.

README.zh-CN.md

@@ -47,6 +47,30 @@ document.body.append(button);
 
 组件使用浏览器原生的自定义元素和标准事件，无需 React 或 Vue 运行时。其他组件通过各自入口引入，例如 `ranui/input`。在[组件示例](https://ran.chaxus.com/cn/src/ranui/)中查看标签、事件和定制方式；不使用构建工具时，可参考[独立脚本示例](./packages/ranui/README.zh-CN.md#iife--cdn)。
 
+## 与 agent 一起使用
+
+[ranui skill](./plugins/ranui/skills/ranui/SKILL.md) 用于界面实现、视觉审查和浏览器验收。
+它按需读取宿主项目已安装的 ranui 规范，不会安装组件库，也不包含工具、hooks 或外部服务。
+
+**Claude Code 插件**：添加本仓库的 marketplace，再安装 ranui：
+
+```sh
+claude plugin marketplace add chaxus/ran
+claude plugin install ranui@ran
+```
+
+新会话中使用 `/ranui:ranui`。同一 marketplace 也提供用于工具函数任务的 `ranuts`。
+
+**Codex skill**：克隆本仓库后，将 `plugins/ranui/skills/ranui/` 复制到宿主项目的
+`.agents/skills/ranui/`，新建任务后使用 `$ranui`。两者使用同一份 skill 正文；
+`.claude-plugin` 清单用于 Claude 的插件安装。
+参见 [Codex skill 发现规则](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills)。
+
+使用示例：“按 ranui 规范优化这个设置侧栏，收拢相关文案、对齐控件文字，
+并用明暗主题、窄宽屏的实际截图验收。”
+[UI 任务索引](./packages/ranui/docs/INTERFACE_GUIDE.md#ui-task-lookup) 将这些问题直接对应到
+权威规则和验收简表。修改 ran 源码时先读 [AGENTS.md](./AGENTS.md)。
+
 ## 参与开发
 
 使用 Node 24+ 和 pnpm 11.6.0。

packages/docs/cn/src/ranui/design-guides/index.md

@@ -85,6 +85,12 @@ description: '使用 ranui 构建界面：根据元素的用途选择设计令
 [权威组合规范](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#11-composition--the-page-not-the-component)
 维护例外及验收条件。
 
+纵向间距按元素关系统一：标题与说明、字段与提示可用 8px，组间 16px，相关子区块间 24px。
+每一处间距只由一层布局负责；先计入子元素 margin、已有内边距和行内控件的基线留白，再决定是否增加间隔。
+换行、提示隐藏和错误出现后，都要在浏览器中实测。
+[权威纵向节奏规范](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#vertical-rhythm-across-sibling-views)
+维护例外与可运行的反向校验，不改变组件默认值。
+
 ## 选排版
 
 先问这段文字是什么**角色**（heading、label、copy、button、mono），字体、字号、字重、行高就从

packages/docs/de/src/ranui/design-guides/index.md

@@ -53,6 +53,14 @@ Nimm jeden Abstand aus der [neunstufigen Skala](/de/src/ranui/design-system/#spa
 
 Erfinde kein `20px` oder `28px`. Den Rhythmus einer Seite erzeugt gerade die begrenzte Auswahl; ein einziger Abstand außerhalb der Skala bricht ihn. Halte gemeinsame Achsen über Bereiche hinweg (Kanten, Grundlinien und Spalten, die fluchten) und prüfe die Ausrichtung an den gezeichneten Pixeln statt nach Augenmaß.
 
+Vertikale Abstände folgen der Beziehung: Titel/Beschreibung und Feld/Hinweis können 8px,
+getrennte Gruppen 16px und zusammengehörige Unterabschnitte 24px verwenden. Jeder Abstand
+hat genau einen Verantwortlichen; berücksichtigen Sie Kind-Margins, Innenabstände und
+Grundlinienraum bei Inline-Steuerelementen. Prüfen Sie Zeilenumbrüche sowie ausgeblendete
+Hinweise und Fehlerzustände im Browser. Die
+[verbindlichen Regeln zum vertikalen Rhythmus](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#vertical-rhythm-across-sibling-views)
+enthalten Ausnahmen und ausführbare Gegenproben, ohne Komponentenvorgaben zu ändern.
+
 ## Schrift wählen
 
 Frag, welche **Rolle** der Text spielt (Überschrift, Beschriftung, Fließtext, Schaltfläche, dicktengleich), und Schriftart, Größe, Stärke und Zeilenhöhe ergeben sich alle aus der [Schriftskala](/de/src/ranui/design-system/#typography). Wähl keine rohen Pixelwerte je Einzelfall.

packages/docs/es/src/ranui/design-guides/index.md

@@ -53,6 +53,14 @@ Toma cada espacio de la [escala de nueve valores](/es/src/ranui/design-system/#s
 
 No inventes `20px` ni `28px`. El conjunto limitado es lo que produce el ritmo de la página; un solo espacio fuera de la escala es lo que lo rompe. Mantén ejes compartidos entre regiones (bordes, líneas base y columnas que se alinean) y comprueba la alineación contra los píxeles dibujados, no a ojo.
 
+El ritmo vertical depende de la relación: título/descripción y campo/ayuda pueden usar 8px,
+los grupos separados 16px y las subsecciones relacionadas 24px. Cada separación debe tener
+un solo responsable; cuente los márgenes de los hijos, el relleno existente y el espacio de
+línea base de los controles en línea. Compruebe los saltos de línea, la ayuda oculta y los
+errores en el navegador. Las
+[reglas canónicas de ritmo vertical](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#vertical-rhythm-across-sibling-views)
+incluyen excepciones y pruebas inversas ejecutables, sin cambiar los valores predeterminados de los componentes.
+
 ## Elegir la tipografía
 
 Pregunta qué **rol** cumple el texto (título, etiqueta, cuerpo, botón, monoespaciado) y la fuente, el tamaño, el grosor y la altura de línea salen todos de la [escala tipográfica](/es/src/ranui/design-system/#typography). No elijas píxeles crudos caso por caso.

packages/docs/fa/src/ranui/design-guides/index.md

@@ -53,6 +53,13 @@ description: 'قواعد طراحی برای ساختن صفحه با ranui: ن
 
 `20px` یا `28px` اختراع نکنید. ریتم صفحه را همان مجموعه محدود می‌سازد و یک فاصله بیرون از مقیاس آن را می‌شکند. ستون فقرات مشترک میان نواحی را حفظ کنید (لبه‌ها، خط‌های مبنا و ستون‌هایی که هم‌راستا می‌شوند) و هم‌ترازی را با پیکسل‌های رسم‌شده بسنجید نه با چشم.
 
+فاصلهٔ عمودی را بر اساس رابطهٔ عناصر یکسان کنید: عنوان و توضیح یا فیلد و راهنما می‌توانند 8px،
+گروه‌های جدا 16px و زیربخش‌های مرتبط 24px فاصله داشته باشند. هر فاصله فقط یک مسئول داشته باشد؛
+حاشیهٔ عناصر فرزند، فاصلهٔ داخلی موجود و فضای خط مبنای کنترل‌های درون‌خطی را ابتدا حساب کنید.
+شکستن سطر، راهنمای پنهان و حالت خطا را در مرورگر اندازه‌گیری کنید.
+[راهنمای مرجع ریتم عمودی](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#vertical-rhythm-across-sibling-views)
+استثناها و آزمون‌های معکوس قابل اجرا را تعریف می‌کند، بدون تغییر پیش‌فرض اجزا.
+
 ## انتخاب تایپوگرافی
 
 بپرسید متن چه **نقشی** دارد (عنوان، برچسب، بدنه، دکمه، تک‌عرض) و آنگاه قلم و اندازه و وزن و ارتفاع خط، همه از [مقیاس تایپوگرافی](/fa/src/ranui/design-system/#typography) درمی‌آیند. برای هر مورد جداگانه پیکسل خام انتخاب نکنید.

packages/docs/ja/src/ranui/design-guides/index.md

@@ -53,6 +53,13 @@ ranui のコンポーネントで組み立てた画面が、部品の寄せ集
 
 `20px` や `28px` を発明しないでください。ページのリズムを生むのは限られた選択肢のほうで、スケールから外れた余白ひとつがそれを壊します。領域をまたいだ共通の背骨（揃った端、ベースライン、カラム）を保ち、揃っているかは目ではなく描画されたピクセルで確かめてください。
 
+縦方向の間隔は要素の関係でそろえます。タイトルと説明、フィールドと補足には 8px、
+グループ間には 16px、関連する小区画の間には 24px を使えます。各間隔を管理する層は一つにし、
+子要素の margin、既存の内側余白、インラインコントロールのベースライン余白を先に数えます。
+折り返し、補足の非表示、エラー表示をブラウザーで実測してください。
+[縦方向のリズムに関する正式な規則](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#vertical-rhythm-across-sibling-views)
+に例外と実行可能な逆検証をまとめており、コンポーネントの既定値は変更しません。
+
 ## 文字の選び方
 
 そのテキストがどんな**役割**を担うか（見出し、ラベル、本文、ボタン、等幅）を問えば、フォント・大きさ・太さ・行間はすべて[タイプスケール](/ja/src/ranui/design-system/#typography)から決まります。個別に生の px を選ばないでください。

packages/docs/ko/src/ranui/design-guides/index.md

@@ -53,6 +53,13 @@ ranui 컴포넌트로 만든 화면이 부품 더미가 아니라 **하나의 
 
 `20px`이나 `28px`을 지어내지 마세요. 페이지의 리듬을 만드는 것은 제한된 선택지이고, 그것을 깨뜨리는 것은 스케일을 벗어난 간격 하나입니다. 영역을 가로지르는 공통의 등뼈(맞춰진 가장자리, 기준선, 열)를 지키고, 정렬은 눈이 아니라 그려진 픽셀로 확인하세요.
 
+세로 간격은 요소의 관계에 맞춰 통일합니다. 제목과 설명, 필드와 도움말은 8px,
+서로 다른 그룹은 16px, 관련 하위 구역은 24px을 사용할 수 있습니다. 각 간격은 한 계층에서만
+관리하고, 자식 요소의 margin, 기존 안쪽 여백, 인라인 컨트롤의 기준선 여백을 먼저 계산합니다.
+줄바꿈, 도움말 숨김, 오류 표시 상태를 브라우저에서 실측하세요.
+[세로 리듬의 공식 지침](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#vertical-rhythm-across-sibling-views)
+에서 예외와 실행 가능한 역검증을 다루며, 컴포넌트 기본값은 변경하지 않습니다.
+
 ## 글자 고르기
 
 그 글자가 어떤 **역할**을 하는지(제목, 레이블, 본문, 버튼, 고정폭) 물으면 글꼴·크기·굵기·행간이 모두 [타입 스케일](/ko/src/ranui/design-system/#typography)에서 따라 나옵니다. 인스턴스마다 날 px을 고르지 마세요.

packages/docs/pt/src/ranui/design-guides/index.md

@@ -53,6 +53,14 @@ Tire cada espaço da [escala de nove valores](/pt/src/ranui/design-system/#spaci
 
 Não invente `20px` nem `28px`. É o conjunto limitado que produz o ritmo da página; um único espaço fora da escala é o que o quebra. Mantenha espinhas compartilhadas entre regiões (bordas, linhas de base e colunas que se alinham) e confira o alinhamento contra os pixels desenhados, não a olho.
 
+O ritmo vertical depende da relação: título/descrição e campo/ajuda podem usar 8px,
+grupos separados 16px e subseções relacionadas 24px. Cada intervalo deve ter um único
+responsável; conte as margens dos filhos, o preenchimento existente e o espaço da linha
+de base dos controles em linha. Verifique quebras de linha, ajuda oculta e estados de erro
+no navegador. As
+[regras canônicas de ritmo vertical](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#vertical-rhythm-across-sibling-views)
+definem exceções e testes inversos executáveis, sem alterar os padrões dos componentes.
+
 ## Escolher a tipografia
 
 Pergunte que **papel** o texto cumpre (título, rótulo, corpo, botão, monoespaçado) e a fonte, o tamanho, o peso e a altura de linha saem todos da [escala tipográfica](/pt/src/ranui/design-system/#typography). Não escolha pixels crus caso a caso.

packages/docs/src/ranui/design-guides/index.md

@@ -98,6 +98,13 @@ the resting whole pane and explain the distinct purpose of each remaining border
 the [canonical composition rules](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#11-composition--the-page-not-the-component)
 own the exceptions and acceptance criteria.
 
+Keep vertical rhythm consistent by relationship: title/description and field/hint pairs can
+use 8px, separate groups 16px, and related subsections 24px. Give each gap one owner;
+count child margins, existing padding and inline baseline space before adding another gap.
+Verify wrapped copy and hidden helper/error states in the browser. The
+[canonical vertical-rhythm guidance](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#vertical-rhythm-across-sibling-views)
+owns the exceptions and runnable reverse checks, without changing component defaults.
+
 ## Choosing type
 
 Ask what **role** the text plays (heading, label, copy, button, mono) and the font, size,