feat(ranui): unify design guidance and refine component interactions

.agents/plugins/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "ran",
+  "interface": {
+    "displayName": "ran"
+  },
+  "plugins": [
+    {
+      "name": "ran",
+      "source": {
+        "source": "local",
+        "path": "./plugins/ran"
+      },
+      "policy": {
+        "installation": "AVAILABLE"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

.claude-plugin/marketplace.json

@@ -4,23 +4,15 @@
     "name": "chaxus",
     "url": "https://github.com/chaxus/ran"
   },
-  "description": "Skills for the ran monorepo libraries — ranui (web components) and ranuts (utilities) — so AI can read and use them without spelunking the source. Install whichever you use.",
+  "description": "Product design methods and version-aware ranui and ranuts skills in one plugin.",
   "metadata": {
     "pluginRoot": "./plugins"
   },
   "plugins": [
     {
-      "name": "ranui",
-      "source": "./plugins/ranui",
-      "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.",
+      "name": "ran",
+      "source": "./plugins/ran",
+      "description": "Product design methods and version-aware ranui and ranuts skills in one plugin.",
       "author": {
         "name": "chaxus"
       }

.github/workflows/ci.yml

@@ -5,6 +5,11 @@ on:
     paths:
       - "packages/**"
       - "bin/**"
+      - "tsconfig.tooling.json"
+      - "plugins/**"
+      - "design/**"
+      - ".agents/plugins/**"
+      - ".claude-plugin/**"
       - "package.json"
       - "pnpm-lock.yaml"
       - "pnpm-workspace.yaml"
@@ -17,6 +22,11 @@ on:
     paths:
       - "packages/**"
       - "bin/**"
+      - "tsconfig.tooling.json"
+      - "plugins/**"
+      - "design/**"
+      - ".agents/plugins/**"
+      - ".claude-plugin/**"
       - "package.json"
       - "pnpm-lock.yaml"
       - "pnpm-workspace.yaml"
@@ -61,6 +71,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Type-check repository tooling
+        run: pnpm typecheck:tooling
+
       - name: Verify repository scripts
         run: pnpm run verify:scripts
 
@@ -146,7 +159,7 @@ jobs:
           pnpm release:prepare
           pnpm verify:release
 
-      # `pnpm run test` reaches ranui through `run-checks.mjs`, which runs the package's
+      # `pnpm run test` reaches ranui through `run-checks.ts`, which runs the package's
       # own `test` script. That script runs `vitest run`; the coverage gate used to be a
       # separate step that ran `vitest run --coverage` afterwards, executing the same
       # suite a second time to produce one report. Asking for coverage up front makes the

.github/workflows/e2e.yml

@@ -6,6 +6,9 @@ on:
     paths:
       - "packages/docs/**"
       - "packages/ranui/**"
+      - "plugins/ran/**"
+      - "design/**"
+      - ".agents/plugins/**"
       - "packages/ranuts/**"
       - "packages/ranview/**"
       - "packages/im/**"
@@ -18,6 +21,9 @@ on:
     paths:
       - "packages/docs/**"
       - "packages/ranui/**"
+      - "plugins/ran/**"
+      - "design/**"
+      - ".agents/plugins/**"
       - "packages/ranuts/**"
       - "packages/ranview/**"
       - "packages/im/**"
@@ -73,6 +79,10 @@ jobs:
       - name: Build ranuts
         run: pnpm --filter ranuts run build
 
+      - name: Verify agent-evaluation browser oracles (no model calls)
+        if: matrix.browser == 'chromium'
+        run: pnpm verify:agent-evals
+
       - name: Build ranui
         run: pnpm --filter ranui run build
 
@@ -120,7 +130,7 @@ jobs:
       # The launcher installs/builds the three required workspaces inside the same
       # digest-pinned renderer used for local baseline updates. Missing PNGs fail.
       - name: Compare reviewed screenshot baselines
-        run: node packages/ranui/bin/visual.mjs check
+        run: node packages/ranui/bin/visual.ts check
       - name: Upload visual differences and environment
         if: always()
         uses: actions/upload-artifact@v7

.github/workflows/release.yml

@@ -67,7 +67,8 @@ jobs:
           pnpm verify:links
           pnpm -F docs check:langs
           pnpm verify:design
-          node bin/run-checks.mjs tsc
+          pnpm typecheck:tooling
+          node bin/run-checks.ts tsc
 
       - name: Test libraries and applications
         run: pnpm test
@@ -119,7 +120,7 @@ jobs:
           path: .release/
 
       - name: Publish verified tarballs using npm trusted publishing
-        run: node bin/release.mjs publish --tag "$RELEASE_TAG" --confirm
+        run: node bin/release.ts publish --tag "$RELEASE_TAG" --confirm
 
       - name: Preserve partial or complete publication results
         if: always()

.prettierignore

@@ -43,3 +43,13 @@ packages/ranui/docs/style-tokens-public.md
 # The next-generation docs build's output, written alongside VitePress's during the
 # migration so the two can be compared. Generated, never edited.
 packages/docs/dist
+
+# Agent reference bytes are generated from formatted canonical design sources and hash-bound.
+plugins/ran/skills/design/references/
+
+# Captured evidence JSON is an immutable measurement record. Some manifests hash
+# neighboring JSON byte-for-byte; formatting those records would invalidate provenance.
+packages/*/test/evidence/**/*.json
+
+# Preserve raw Playwright failure snapshots, including the original whitespace.
+packages/*/test/evidence/**/error-context.md

AGENTS.md

@@ -2,12 +2,16 @@
 
 Start with the owner of the change; do not load every reference or introduce a second standard.
 
+For product positioning and website ownership, start with [PRODUCT.md](PRODUCT.md).
+`packages/docs` owns ran.chaxus.com; `packages/ranpress` owns its build mechanism.
+
 | Work                                                              | Read first                                                                                                                                          |
 | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Visual hierarchy, composition, tokens and craft                   | [ranui design standard](packages/ranui/docs/DESIGN.md)                                                                                              |
-| Input, focus, drafts, feedback and recovery                       | [interaction standard](packages/ranui/docs/INTERACTION.md)                                                                                          |
-| Optional batch/queue, settings, account/data or revision workflow | [workflow patterns](packages/ranui/docs/WORKFLOW_PATTERNS.md), only when relevant                                                                   |
-| Unsure which reference owns a decision                            | Short [interface index](packages/ranui/docs/INTERFACE_GUIDE.md)                                                                                     |
+| Visual hierarchy, composition, tokens and craft                   | [portable design methods](design/DESIGN.md), then [ranui implementation adapter](packages/ranui/docs/adapters/DESIGN.md)                            |
+| Browser proof, evidence freshness and acceptance status           | [acceptance contract](design/ACCEPTANCE.md)                                                                                                         |
+| Input, focus, drafts, feedback and recovery                       | [interaction standard](design/INTERACTION.md)                                                                                                       |
+| Optional batch/queue, settings, account/data or revision workflow | [workflow patterns](design/WORKFLOW_PATTERNS.md), only when relevant                                                                                |
+| Unsure which reference owns a decision                            | Short [interface index](design/INTERFACE_GUIDE.md)                                                                                                  |
 | Component state, events, lifecycle or SSR                         | [engineering standard](packages/ranui/docs/CODING.md), then [implementation reference](packages/ranui/CLAUDE.md)                                    |
 | Exact attributes, events, slots, parts or theme variables         | Generated [component API](packages/ranui/docs/COMPONENTS.md) and [public tokens](packages/ranui/docs/style-tokens-public.md); verify against source |
 | Public documentation or localized prose                           | [documentation site reference](packages/docs/CLAUDE.md)                                                                                             |
@@ -17,6 +21,11 @@ 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.
 
+Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.
+Keep copy that adds a decision, constraint or consequence; preserve accessible names, field labels,
+units, errors and risk disclosures. [DESIGN's wording rules](design/DESIGN.md#words-are-part-of-the-interface)
+own this principle; do not remove useful guidance merely to make a screenshot quieter.
+
 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
@@ -35,3 +44,8 @@ The local scope below does not weaken the complete repository CI gates:
 
 Public ranui guidance has English and Chinese entry points under `packages/docs/src/ranui/`
 and `packages/docs/cn/src/ranui/`. Link to canonical owners instead of duplicating long rules.
+
+Shared methods are edited in `design/`; ranui-specific guidance in `packages/ranui/docs/adapters/`.
+Run `pnpm sync:design` and `pnpm sync:agent-plugin` after changing them. Generated npm guides
+and bundled plugin references are checked distributions, not additional rule owners.
+The unified `plugins/ran` entry has three skills; read only the one relevant to the task.

PRODUCT.md

@@ -1,33 +1,31 @@
-# Product
+# ran
 
-## Register
+ran provides design methods, UI components and TypeScript utilities for developers and agents building web products.
 
-brand
+## Three pillars
 
-## Users
+| Pillar     | Responsibility                                                                                   | Delivery                                          |
+| ---------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
+| Ran Design | Product composition, coherent visual language, interaction, motion and evidence-based acceptance | Portable skills, agent plugin and public guidance |
+| ranui      | Accessible custom elements, themes and explicit component behavior                               | Independently installable npm package             |
+| ranuts     | Typed utilities with explicit runtime boundaries                                                 | Independently installable npm package             |
 
-Frontend engineers, UI library maintainers, and technical learners evaluating Web Components for real applications. They arrive with a developer mindset: they want to see whether ranui is native, themeable, inspectable, and usable across frameworks before reading full API documentation.
+Ran Design must also work in products that do not use ranui. The ranui adapter connects general methods to the installed library's actual tokens and APIs. ranuts remains useful without a UI dependency.
 
-## Product Purpose
+`@alixex/ranview` remains an independently published DOM/reactivity foundation. ranpress is private build infrastructure for the website. These implementation roles do not require additional top-level product pillars.
 
-ranui is an experimental Web Components UI library. The demo should introduce the library, prove that the components are real custom elements, and make theme packs, import paths, styling hooks, and representative components easy to inspect in one page.
+## Website
 
-## Brand Personality
+**https://ran.chaxus.com** is the product website, documentation and live-example destination. Its existing application owner is `packages/docs`; its build mechanism is `packages/ranpress`. Keep one navigation, search and locale system for the three pillars. The personal `chaxus.com` application is retired from this repository; domain and hosting administration are separate.
 
-Precise, experimental, and tool-minded. The interface should feel like a component workbench for engineers, not a generic SaaS landing page or a decorative gallery.
+The website should help a visitor understand the product, try a real interaction, choose a library or agent workflow, and reach accurate instructions. Use composed examples with realistic content and complete states. Let the same example connect design rationale, implementation and verification.
 
-## Anti-references
+## Ownership and quality
 
-Avoid purple-gradient SaaS templates, oversized hero metrics, vague marketing claims, stock illustrations, and demo pages that look like raw component test fixtures. Avoid hiding the actual components behind screenshots or decorative mockups.
+General methodology belongs to a neutral `design/` owner as it is extracted. Package source owns APIs and tokens. Skills route to the applicable references; public pages explain and demonstrate them. Generated distributions may include copies, but those copies must identify their source and cannot become separately edited standards.
 
-## Design Principles
+A library consumer should not need the plugin, and a plugin user should not need to install ranui to use general design guidance. Package and plugin releases are independent; library-specific guidance must identify its applicable version.
 
-- Show real components first.
-- Treat theme switching as the signature interaction.
-- Keep developer next steps visible: install, import, inspect, style.
-- Make the page dense enough for scanning without feeling like an API dump.
-- Preserve ranui's experimental honesty while making the library feel intentional.
+A polished result combines coherent proportions and typography with complete behavior, readable content and purposeful motion. Claims about visuals require current rendered evidence; claims about transitions require continuous recordings. Automated checks, agent review and human acceptance are distinct.
 
-## Accessibility & Inclusion
-
-Target WCAG AA contrast for page chrome and documentation content. Respect reduced motion, keep touch targets at least 44px on coarse pointers, avoid hover-only functionality, and ensure anchors land below sticky navigation.
+The accepted direction and staged implementation are recorded in the [architecture plan](docs/superpowers/plans/2026-10-23-ran-product-architecture.md). The [ranui demo brief](packages/ranui/demo/PRODUCT.md) applies only to its component workbench.

README.md

@@ -6,7 +6,7 @@
 </p>
 
 <h1 align="center">ran</h1>
-<p align="center">UI components and TypeScript tools for web applications.</p>
+<p align="center">Design methods, UI components and TypeScript tools for web products.</p>
 <p align="center"><a href="https://ran.chaxus.com/">Documentation</a> · <a href="https://github.com/chaxus/ran/actions/workflows/ci.yml">CI</a></p>
 <p align="center"><b>English</b> · <a href="./README.zh-CN.md">中文</a> · <a href="./README.ja.md">日本語</a> · <a href="./README.es.md">Español</a> · <a href="./README.pt.md">Português</a> · <a href="./README.ko.md">한국어</a> · <a href="./README.de.md">Deutsch</a> · <a href="./README.fa.md">فارسی</a></p>
 
@@ -49,28 +49,47 @@ Components use custom elements and standard browser events, so no React or Vue r
 
 ## 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.
+The unified **ran** plugin contains [design](./plugins/ran/skills/design/SKILL.md),
+[ranui](./plugins/ran/skills/ranui/SKILL.md) and [ranuts](./plugins/ran/skills/ranuts/SKILL.md)
+skills. Design guidance works with the host's existing stack, including projects without ranui.
+Library skills read the host's installed package version and public contracts. The plugin bundles
+its design references; it needs no MCP server, account or hook.
 
-**Claude Code plugin** — add this repository's marketplace, then install ranui:
+For this checkout, register the local marketplace with `codex plugin marketplace add .`
+or `claude plugin marketplace add .`, then install `ran@ran`. The remote instructions below
+apply once the unified plugin is available on the repository's default branch.
+
+**Claude Code plugin** — add this repository's marketplace, then install ran:
 
 ```sh
 claude plugin marketplace add chaxus/ran
-claude plugin install ranui@ran
+claude plugin install ran@ran
 ```
 
-Invoke `/ranui:ranui` in a new session. The same marketplace also offers `ranuts` for utility work.
+In a new session, use `/ran:design`, `/ran:ranui` or `/ran:ranuts` for the relevant task.
+
+**Codex plugin** — register the repository marketplace and install the same skill:
+
+```sh
+codex plugin marketplace add chaxus/ran
+codex plugin add ran@ran
+```
 
-**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).
+Start a new task and invoke `$design`, `$ranui` or `$ranuts`. For a local checkout, use `codex plugin marketplace add .`
+from the repository root. The portable [plugin manifest](./plugins/ran/plugin.json) and
+[Codex marketplace](./.agents/plugins/marketplace.json) follow the
+[official packaging format](https://developers.openai.com/plugins/build/plugins).
+Both installation routes load the same three skill bodies and bundled design references.
 
 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).
+The [UI task lookup](./packages/ranui/docs/INTERFACE_GUIDE.md#ui-task-lookup) routes to one owner:
+[design](./packages/ranui/docs/DESIGN.md), [interaction](./packages/ranui/docs/INTERACTION.md),
+[public API](./packages/ranui/docs/COMPONENTS.md), or [evidence and decisions](./packages/ranui/docs/ACCEPTANCE.md).
+The plugin starts with a short task contract, preserves the host's product decisions and requires
+actual rendered evidence for UI claims. Automated checks, agent inspection and human acceptance
+remain distinct. [Six opt-in live scenarios](./plugins/ran/evals/README.md) test the guidance's
+behavior separately from its token/API checks. Source contributors start with [AGENTS.md](./AGENTS.md).
 
 ## Work on the repository