From 5511c75c9cca62212a3632e0604e97274d70d07f Mon Sep 17 00:00:00 2001 From: chaxus Date: Sun, 25 Oct 2026 11:01:35 +0800 Subject: [PATCH] docs(design): renumber sections and move ranui names into the adapter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Number the portable DESIGN sections 1–10 without a gap and update every cross-reference and anchor. - Unnumber the adapter's component headings so they no longer collide with the portable section numbers. - Word the navigation-layer rules generically; the r-* mapping lives in the ranui adapter. - Keep one spacing relationship table instead of a second rhythm list. - Use `heading` (not the stale `title`) in the r-card reference and list `hoverable`. - Clarify the design skill's approval sentence and that the 2026-10-22 eval installed the `ranui` agent plugin 1.2.0, not the npm package. Co-Authored-By: Claude Opus 5.5 --- design/DESIGN.md | 20 +++++------ design/INTERFACE_GUIDE.md | 4 +-- packages/docs/CLAUDE.md | 2 +- .../docs/cn/src/ranui/design-guides/index.md | 2 +- .../docs/src/ranui/design-guides/index.md | 2 +- packages/docs/styles/docs.css | 2 +- packages/docs/styles/home.css | 2 +- packages/ranui/CLAUDE.md | 21 +++++------ packages/ranui/docs/CODING.md | 2 +- packages/ranui/docs/DESIGN.md | 35 ++++++++++--------- packages/ranui/docs/INTERFACE_GUIDE.md | 4 +-- packages/ranui/docs/adapters/DESIGN.md | 15 ++++---- packages/ranui/test/e2e/layout-contract.md | 2 +- .../ran/evals/results/2026-10-22/README.md | 3 +- plugins/ran/skills/design/SKILL.md | 4 +-- .../ran/skills/design/references/DESIGN.md | 20 +++++------ .../design/references/INTERFACE_GUIDE.md | 4 +-- .../skills/design/references/manifest.json | 8 ++--- 18 files changed, 78 insertions(+), 74 deletions(-) diff --git a/design/DESIGN.md b/design/DESIGN.md index 4a9398cc99..d009aff33f 100644 --- a/design/DESIGN.md +++ b/design/DESIGN.md @@ -92,9 +92,9 @@ may move to demonstrate loading; a decorative status pulse must not imply live a - Test actual pointer/touch gestures, hover fallback and keyboard routes where affected; checking two color schemes does not establish input parity. -## 11. Composition — the page, not the component +## 9. Composition — the page, not the component -Choose the page structure in §12 first; then compose its components with these rules. +Choose the page structure in §10 first; then compose its components with these rules. ### Style coherence across components and pages @@ -416,7 +416,7 @@ actual runtime/capture identity, browser measurements and separate automated, ag results. The source-only [browser example](https://github.com/chaxus/ran/blob/main/packages/ranui/test/e2e/layout-contract.md) contains setup commands and test utility details; they are not public package APIs. -## 12. Information architecture — the shape before the composition +## 10. Information architecture — the shape before the composition Choose structure before composition for information-dense consoles, dashboards and workbenches. Complete API data is not a page design: the reader still needs a clear order for understanding @@ -475,7 +475,7 @@ point that links back to it. Default reading order — page identity → current status or exception → primary task and primary action → the information the judgement needs → relationships, changes, evidence → secondary information and low-frequency actions. **One primary action per task region**, and it is the -most likely next step, not the most destructive one (§11, "Emphasis is a budget", governs how +most likely next step, not the most destructive one (§9, "Emphasis is a budget", governs how much weight it may take). ### Density is effective information, not controls per inch @@ -500,12 +500,12 @@ redundant return shortcut, or repeat that parent as an inert crumb above its ret When returning through the parent already reaches the ancestor, that journey preserves access without adding another detail-header row. Use breadcrumbs when the hierarchy itself helps the task. -**`r-modal` is not a navigation layer.** Anything needing a copyable link, history, a -side-by-side comparison, or work that survives a refresh gets a route. Reserve the modal for a -short confirmation or a single field, `r-popover` / `r-dropdown` for transient context, and -`r-disclosure-row` for progressive disclosure. +**A modal is not a navigation layer.** Anything needing a copyable link, history, a +side-by-side comparison, or work that survives a refresh gets a route. Reserve a modal for a +short confirmation or a single field, a popover or menu for transient context, and a disclosure +row for progressive disclosure. -**`r-tabs` carries peer views of one object** — its conversation, its checks, its diff — never +**Tabs carry peer views of one object** — its conversation, its checks, its diff — never unrelated modules; that is navigation's job. If the chosen library lacks a suitable primitive, use existing semantic elements and host tokens; @@ -527,4 +527,4 @@ unrelated flows merely to satisfy the list. Repository CI still runs its complet - [ ] Run the host’s applicable checks and inspect actual browser evidence. - [ ] Copy follows §6; nothing signals state by color alone (§7). - [ ] For a dense surface: one primary model, the skeleton chosen from the question rather - than the payload, and every fact with one authoritative location (§12). + than the payload, and every fact with one authoritative location (§10). diff --git a/design/INTERFACE_GUIDE.md b/design/INTERFACE_GUIDE.md index 72a26dbd18..2116830808 100644 --- a/design/INTERFACE_GUIDE.md +++ b/design/INTERFACE_GUIDE.md @@ -8,7 +8,7 @@ workflow recipes apply only when a task needs them. | Decision | Owner | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Visual hierarchy, composition, type, spacing, density, color and motion | [DESIGN.md](./DESIGN.md), [composition](./DESIGN.md#11-composition--the-page-not-the-component) and [density](./DESIGN.md#density-follows-control-roles) | +| Visual hierarchy, composition, type, spacing, density, color and motion | [DESIGN.md](./DESIGN.md), [composition](./DESIGN.md#9-composition--the-page-not-the-component) and [density](./DESIGN.md#density-follows-control-roles) | | Observable input, focus, keyboard, drafts, feedback, progress and recovery | [INTERACTION.md](./INTERACTION.md#1-inputs-drafts-and-intent) (inputs), [focus](./INTERACTION.md#2-reachable-controls-and-predictable-focus), [recovery](./INTERACTION.md#4-progress-failure-and-recovery) | | Optional batches/queues, capability-aware settings, account/data access or result revisions | [WORKFLOW_PATTERNS.md](./WORKFLOW_PATTERNS.md) | | Actual browser proof, evidence freshness and review authority | [ACCEPTANCE.md](./ACCEPTANCE.md) | @@ -33,7 +33,7 @@ These links route to existing rules; they introduce no additional standard or de | Uneven vertical spacing, wrapped copy, hidden helper leaving a hole | [vertical rhythm](./DESIGN.md#vertical-rhythm-across-sibling-views) | Independently expected relationships; show/hide and resize; distinguish frame gap from text leading and baseline space | | Controls line up but labels or icons drift | [alignment](./DESIGN.md#alignment-is-structure-not-polish) | Frame, text Range, icon and hit-area measurements; reverse-check text-only drift | | Oversized commands, weak hierarchy or cramped touch controls | [command hierarchy](./DESIGN.md#command-hierarchy-in-constrained-panes), [density](./DESIGN.md#density-follows-control-roles) | Full adjacent control group at actual mouse/touch density, with resting affordance and reachable targets | -| Redundant navigation or misplaced actions | [information architecture](./DESIGN.md#12-information-architecture--the-shape-before-the-composition) | Complete the route and return path; verify labels, action placement and focus against INTERACTION | +| Redundant navigation or misplaced actions | [information architecture](./DESIGN.md#10-information-architecture--the-shape-before-the-composition) | Complete the route and return path; verify labels, action placement and focus against INTERACTION | | Add animation or subtle effects | [motion](./DESIGN.md#5-motion--prefer-none), [craft](./DESIGN.md#evaluate-craft-through-evidence) | Repeat and interrupt the action; inspect reduced motion and theme switching | For deliberate visual exploration, use the optional [reference research index](./REFERENCE_RESEARCH.md) diff --git a/packages/docs/CLAUDE.md b/packages/docs/CLAUDE.md index 60e0a0527c..4c6765a2ad 100644 --- a/packages/docs/CLAUDE.md +++ b/packages/docs/CLAUDE.md @@ -293,7 +293,7 @@ Use the shared composition and information architecture rules for pages, and com violation, and a count that falls fails until it is lowered. The baseline records debt, not permission — the target for every entry is zero. -Two rules from §11 that this site's stylesheets are built around, because breaking them was +Two rules from §9 that this site's stylesheets are built around, because breaking them was invisible and expensive: - **The measure governs text, not the column.** `--measure` caps paragraphs and lists; diff --git a/packages/docs/cn/src/ranui/design-guides/index.md b/packages/docs/cn/src/ranui/design-guides/index.md index aa3f7846ed..aeaf36da81 100644 --- a/packages/docs/cn/src/ranui/design-guides/index.md +++ b/packages/docs/cn/src/ranui/design-guides/index.md @@ -82,7 +82,7 @@ description: '使用 ranui 构建界面：根据元素的用途选择设计令 不要让内层卡片、整组底色和逐行分隔线重复表达同一个分组。声明相邻控件共享的图标／勾选框列和文字列。 输入控件的功能性边框、键盘焦点框继续保留。验收应查看静止的完整面板， 并说明每条边框、底色和分隔线的独立用途； -[权威组合规范](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#11-composition--the-page-not-the-component) +[权威组合规范](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#9-composition--the-page-not-the-component) 维护例外及验收条件。 纵向间距按元素关系统一：标题与说明、字段与提示可用 8px，组间 16px，相关子区块间 24px。 diff --git a/packages/docs/src/ranui/design-guides/index.md b/packages/docs/src/ranui/design-guides/index.md index 43374b0e97..aba1173967 100644 --- a/packages/docs/src/ranui/design-guides/index.md +++ b/packages/docs/src/ranui/design-guides/index.md @@ -95,7 +95,7 @@ menu/list contexts; do not mandate them everywhere. A nested card, group fill an separators must not repeat the same boundary. Declare shared icon/checkbox and text columns across adjacent controls. Retain functional field frames and keyboard focus outlines. Inspect the resting whole pane and explain the distinct purpose of each remaining border, fill or divider; -the [canonical composition rules](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#11-composition--the-page-not-the-component) +the [canonical composition rules](https://github.com/chaxus/ran/blob/main/packages/ranui/docs/DESIGN.md#9-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 diff --git a/packages/docs/styles/docs.css b/packages/docs/styles/docs.css index ff71812f29..15b7fc5632 100644 --- a/packages/docs/styles/docs.css +++ b/packages/docs/styles/docs.css @@ -1274,7 +1274,7 @@ ran-demo p { @media (min-width: 1240px) { /* - * One inset for the header, the sidebar and the outline — they are siblings and §11 asks + * One inset for the header, the sidebar and the outline — they are siblings and §9 asks * siblings to share a content inset. 16px against a 1440px viewport read as flush; this * moves all three together, so the wordmark still lines up with the sidebar exactly. */ diff --git a/packages/docs/styles/home.css b/packages/docs/styles/home.css index 2c6a9a3ef1..7f7b085088 100644 --- a/packages/docs/styles/home.css +++ b/packages/docs/styles/home.css @@ -433,7 +433,7 @@ /* * Three ways in, not three cards. * - * These are cells in a gallery — §11's example of what a box is *not* for. Bordered and + * These are cells in a gallery — §9's example of what a box is *not* for. Bordered and * filled, they read as three separate objects competing with the hero directly above, * and the 3D tilt and hover spotlight spent the page's whole emphasis budget on * navigation furniture. A shared top rule, the column spine, and a link that responds on diff --git a/packages/ranui/CLAUDE.md b/packages/ranui/CLAUDE.md index bb441d9161..129d886262 100644 --- a/packages/ranui/CLAUDE.md +++ b/packages/ranui/CLAUDE.md @@ -99,7 +99,7 @@ export class MyComponent extends RanElement { // Capture each element as it is built. Never `root.querySelector('.ran-mycomp-inner')!` // afterwards: that re-derives the element through a class name, and a rename on one side - // yields `null` that the `!` waves through. `verify:design` rejects it (DESIGN.md §9). + // yields `null` that the `!` waves through. `verify:design` rejects it (DESIGN.md, "Hold what you build"). const inner = createRef(); this._shadowDom.appendChild( Div() @@ -633,7 +633,7 @@ Every component's `index.less` automatically receives `@import "base.less"` via ### CSS variable naming tiers -Use [DESIGN's token roles](docs/DESIGN.md#10-component-token-naming) and the generated +Use [DESIGN's token roles](docs/DESIGN.md#ranui-component-token-naming) and the generated [public token catalog](docs/style-tokens-public.md), rather than a second value snapshot. Foundation declarations are in `theme/tokens.less` and `theme/dark.less` in a source checkout; installed readers can inspect the installed package’s `dist/ranui.css`. Primary actions are monochrome; @@ -707,13 +707,14 @@ A structured content container with header, body, and footer zones. **Attributes / Properties:** -| Name | Type | Default | Description | -| ------------- | -------- | ------- | --------------------------------------------- | -| `title` | `string` | `''` | Card heading (hidden when empty via `:empty`) | -| `description` | `string` | `''` | Subtitle below title (hidden when empty) | -| `sheet` | `string` | `''` | CSS injected into shadow DOM | +| Name | Type | Default | Description | +| ------------- | --------- | ------- | -------------------------------------------------------- | +| `heading` | `string` | `''` | Card heading (hidden when empty via `:empty`) | +| `description` | `string` | `''` | Subtitle below heading (hidden when empty) | +| `hoverable` | `boolean` | `false` | Hover feedback (border and shadow); clickable cards only | +| `sheet` | `string` | `''` | CSS injected into shadow DOM | -**Header visibility:** Controlled by `:host(:not([title]):not([description])) .ran-card-header { display: none }` — header is invisible when neither attribute is set. +**Header visibility:** `_syncHeader()` hides the header unless the heading, the description or the `extra` slot has an assigned element. **Footer visibility:** Controlled by `slotchange` on `slot[name="footer"]` — footer `div` starts with `style.display='none'`, shown when `slot.assignedElements().length > 0`. @@ -1172,7 +1173,7 @@ describe('r-card contract', () => { const card = document.createElement('r-card') as Card; document.body.appendChild(card); - card.setAttribute('title', 'Hello'); + card.setAttribute('heading', 'Hello'); expect((card as any)._titleEl.textContent).toBe('Hello'); }); @@ -1181,7 +1182,7 @@ describe('r-card contract', () => { document.body.appendChild(card); const spy = vi.spyOn(card as any, '_syncTitle'); - card.attributeChangedCallback('title', 'same', 'same'); + card.attributeChangedCallback('heading', 'same', 'same'); expect(spy).not.toHaveBeenCalled(); }); diff --git a/packages/ranui/docs/CODING.md b/packages/ranui/docs/CODING.md index a1aa48bfcd..e8b1bf9acd 100644 --- a/packages/ranui/docs/CODING.md +++ b/packages/ranui/docs/CODING.md @@ -126,7 +126,7 @@ Events are the outward half of the contract, so treat a change to one as a break - **Tokens, never literals.** Component tokens follow `--ran-{component}-{element}[-{state}]-{property}` and default to a semantic token; the - naming rules and the reasoning are DESIGN.md §10. + naming rules and the reasoning are in [DESIGN.md](DESIGN.md#ranui-component-token-naming). - **A fallback must name a token that exists and that flips.** Both failure modes are silent and both are machine-checked (DESIGN.md §1). - **No palette property in a `transition`, no `transition: all`.** CSS cannot tell an diff --git a/packages/ranui/docs/DESIGN.md b/packages/ranui/docs/DESIGN.md index aa9a6ed306..8ffa0ec7b0 100644 --- a/packages/ranui/docs/DESIGN.md +++ b/packages/ranui/docs/DESIGN.md @@ -94,9 +94,9 @@ may move to demonstrate loading; a decorative status pulse must not imply live a - Test actual pointer/touch gestures, hover fallback and keyboard routes where affected; checking two color schemes does not establish input parity. -## 11. Composition — the page, not the component +## 9. Composition — the page, not the component -Choose the page structure in §12 first; then compose its components with these rules. +Choose the page structure in §10 first; then compose its components with these rules. ### Style coherence across components and pages @@ -418,7 +418,7 @@ actual runtime/capture identity, browser measurements and separate automated, ag results. The source-only [browser example](https://github.com/chaxus/ran/blob/main/packages/ranui/test/e2e/layout-contract.md) contains setup commands and test utility details; they are not public package APIs. -## 12. Information architecture — the shape before the composition +## 10. Information architecture — the shape before the composition Choose structure before composition for information-dense consoles, dashboards and workbenches. Complete API data is not a page design: the reader still needs a clear order for understanding @@ -477,7 +477,7 @@ point that links back to it. Default reading order — page identity → current status or exception → primary task and primary action → the information the judgement needs → relationships, changes, evidence → secondary information and low-frequency actions. **One primary action per task region**, and it is the -most likely next step, not the most destructive one (§11, "Emphasis is a budget", governs how +most likely next step, not the most destructive one (§9, "Emphasis is a budget", governs how much weight it may take). ### Density is effective information, not controls per inch @@ -502,12 +502,12 @@ redundant return shortcut, or repeat that parent as an inert crumb above its ret When returning through the parent already reaches the ancestor, that journey preserves access without adding another detail-header row. Use breadcrumbs when the hierarchy itself helps the task. -**`r-modal` is not a navigation layer.** Anything needing a copyable link, history, a -side-by-side comparison, or work that survives a refresh gets a route. Reserve the modal for a -short confirmation or a single field, `r-popover` / `r-dropdown` for transient context, and -`r-disclosure-row` for progressive disclosure. +**A modal is not a navigation layer.** Anything needing a copyable link, history, a +side-by-side comparison, or work that survives a refresh gets a route. Reserve a modal for a +short confirmation or a single field, a popover or menu for transient context, and a disclosure +row for progressive disclosure. -**`r-tabs` carries peer views of one object** — its conversation, its checks, its diff — never +**Tabs carry peer views of one object** — its conversation, its checks, its diff — never unrelated modules; that is navigation's job. If the chosen library lacks a suitable primitive, use existing semantic elements and host tokens; @@ -529,7 +529,7 @@ unrelated flows merely to satisfy the list. Repository CI still runs its complet - [ ] Run the host’s applicable checks and inspect actual browser evidence. - [ ] Copy follows §6; nothing signals state by color alone (§7). - [ ] For a dense surface: one primary model, the skeleton chosen from the question rather - than the payload, and every fact with one authoritative location (§12). + than the payload, and every fact with one authoritative location (§10). --- @@ -646,11 +646,7 @@ Scales: `--ran-gray-100..1000`, `--ran-gray-alpha-100..1000` (translucent, layer A **4px base unit** with **nine values** only: `--ran-space-1..24` → `4, 8, 12, 16, 24, 32, 40, 64, 96`px. -**Rhythm** - -- `8px` between elements inside a group. -- `16px` between groups. -- `32–40px` between sections. +[ranui spacing relationships](#ranui-spacing-relationships) map each relationship to a step. **Rule:** pick a value from the scale. Don't invent `20px`/`28px` — a limited set is what creates the page's rhythm. @@ -727,7 +723,7 @@ transition: var(--ran-checkbox-tick-transition, transform 0.1s cubic-bezier(0.71 transition: var(--ran-input-transition, none); ``` -## 9. Components — how to apply the system +## ranui components — how to apply the system - Reuse existing semantic native controls or supported ranui primitives; do not rebuild them merely for styling. Choose a ranui component when its contract fits; preserve native form and keyboard semantics, including supported native controls in overlay slots ([INTERACTION §2](./INTERACTION.md#2-reachable-controls-and-predictable-focus)). - Theme through **CSS variables**, **`::part()`**, or the **`sheet`** attribute (escape hatch). CSS variables cross Shadow DOM; selectors do not. @@ -755,7 +751,7 @@ Build shadow structure once and retain its references; do not rediscover it thro [CODING §2](./CODING.md#2-the-component-skeleton) owns construction, runtime-child exceptions and SSR implementation. These are engineering requirements, not extra visual recipes. -## 10. Component token naming +## ranui component token naming Use `--ran-{component}-{element}[-{state}]-{property}`. Keep the existing component prefix; name the most specific distinct UI part, not its full DOM/BEM path. Keep track/fill as @@ -770,6 +766,11 @@ owns available names. This section owns naming; do not hand-maintain another cat ## Applying generic composition to ranui +The [navigation-layer rules](./DESIGN.md#containers-do-not-fix-structure) map to ranui as +follows: `r-modal` for a short confirmation or a single field, `r-popover` / `r-dropdown` for +transient context, `r-disclosure-row` for progressive disclosure, and `r-tabs` only for peer +views of one object. + ### ranui spacing relationships | Relationship | Token | Example | diff --git a/packages/ranui/docs/INTERFACE_GUIDE.md b/packages/ranui/docs/INTERFACE_GUIDE.md index 84efa00171..d4837243a2 100644 --- a/packages/ranui/docs/INTERFACE_GUIDE.md +++ b/packages/ranui/docs/INTERFACE_GUIDE.md @@ -10,7 +10,7 @@ workflow recipes apply only when a task needs them. | Decision | Owner | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Visual hierarchy, composition, type, spacing, density, color and motion | [DESIGN.md](./DESIGN.md), [composition](./DESIGN.md#11-composition--the-page-not-the-component) and [density](./DESIGN.md#density-follows-control-roles) | +| Visual hierarchy, composition, type, spacing, density, color and motion | [DESIGN.md](./DESIGN.md), [composition](./DESIGN.md#9-composition--the-page-not-the-component) and [density](./DESIGN.md#density-follows-control-roles) | | Observable input, focus, keyboard, drafts, feedback, progress and recovery | [INTERACTION.md](./INTERACTION.md#1-inputs-drafts-and-intent) (inputs), [focus](./INTERACTION.md#2-reachable-controls-and-predictable-focus), [recovery](./INTERACTION.md#4-progress-failure-and-recovery) | | Optional batches/queues, capability-aware settings, account/data access or result revisions | [WORKFLOW_PATTERNS.md](./WORKFLOW_PATTERNS.md) | | Actual browser proof, evidence freshness and review authority | [ACCEPTANCE.md](./ACCEPTANCE.md) | @@ -35,7 +35,7 @@ These links route to existing rules; they introduce no additional standard or de | Uneven vertical spacing, wrapped copy, hidden helper leaving a hole | [vertical rhythm](./DESIGN.md#vertical-rhythm-across-sibling-views) | Independently expected relationships; show/hide and resize; distinguish frame gap from text leading and baseline space | | Controls line up but labels or icons drift | [alignment](./DESIGN.md#alignment-is-structure-not-polish) | Frame, text Range, icon and hit-area measurements; reverse-check text-only drift | | Oversized commands, weak hierarchy or cramped touch controls | [command hierarchy](./DESIGN.md#command-hierarchy-in-constrained-panes), [density](./DESIGN.md#density-follows-control-roles) | Full adjacent control group at actual mouse/touch density, with resting affordance and reachable targets | -| Redundant navigation or misplaced actions | [information architecture](./DESIGN.md#12-information-architecture--the-shape-before-the-composition) | Complete the route and return path; verify labels, action placement and focus against INTERACTION | +| Redundant navigation or misplaced actions | [information architecture](./DESIGN.md#10-information-architecture--the-shape-before-the-composition) | Complete the route and return path; verify labels, action placement and focus against INTERACTION | | Add animation or subtle effects | [motion](./DESIGN.md#5-motion--prefer-none), [craft](./DESIGN.md#evaluate-craft-through-evidence) | Repeat and interrupt the action; inspect reduced motion and theme switching | For deliberate visual exploration, use the optional [reference research index](./REFERENCE_RESEARCH.md) diff --git a/packages/ranui/docs/adapters/DESIGN.md b/packages/ranui/docs/adapters/DESIGN.md index 93abac10c4..86cd275965 100644 --- a/packages/ranui/docs/adapters/DESIGN.md +++ b/packages/ranui/docs/adapters/DESIGN.md @@ -111,11 +111,7 @@ Scales: `--ran-gray-100..1000`, `--ran-gray-alpha-100..1000` (translucent, layer A **4px base unit** with **nine values** only: `--ran-space-1..24` → `4, 8, 12, 16, 24, 32, 40, 64, 96`px. -**Rhythm** - -- `8px` between elements inside a group. -- `16px` between groups. -- `32–40px` between sections. +[ranui spacing relationships](#ranui-spacing-relationships) map each relationship to a step. **Rule:** pick a value from the scale. Don't invent `20px`/`28px` — a limited set is what creates the page's rhythm. @@ -192,7 +188,7 @@ transition: var(--ran-checkbox-tick-transition, transform 0.1s cubic-bezier(0.71 transition: var(--ran-input-transition, none); ``` -## 9. Components — how to apply the system +## ranui components — how to apply the system - Reuse existing semantic native controls or supported ranui primitives; do not rebuild them merely for styling. Choose a ranui component when its contract fits; preserve native form and keyboard semantics, including supported native controls in overlay slots ([INTERACTION §2](../INTERACTION.md#2-reachable-controls-and-predictable-focus)). - Theme through **CSS variables**, **`::part()`**, or the **`sheet`** attribute (escape hatch). CSS variables cross Shadow DOM; selectors do not. @@ -220,7 +216,7 @@ Build shadow structure once and retain its references; do not rediscover it thro [CODING §2](../CODING.md#2-the-component-skeleton) owns construction, runtime-child exceptions and SSR implementation. These are engineering requirements, not extra visual recipes. -## 10. Component token naming +## ranui component token naming Use `--ran-{component}-{element}[-{state}]-{property}`. Keep the existing component prefix; name the most specific distinct UI part, not its full DOM/BEM path. Keep track/fill as @@ -235,6 +231,11 @@ owns available names. This section owns naming; do not hand-maintain another cat ## Applying generic composition to ranui +The [navigation-layer rules](../DESIGN.md#containers-do-not-fix-structure) map to ranui as +follows: `r-modal` for a short confirmation or a single field, `r-popover` / `r-dropdown` for +transient context, `r-disclosure-row` for progressive disclosure, and `r-tabs` only for peer +views of one object. + ### ranui spacing relationships | Relationship | Token | Example | diff --git a/packages/ranui/test/e2e/layout-contract.md b/packages/ranui/test/e2e/layout-contract.md index e560b963d4..18339eff96 100644 --- a/packages/ranui/test/e2e/layout-contract.md +++ b/packages/ranui/test/e2e/layout-contract.md @@ -1,7 +1,7 @@ # Browser layout acceptance example This is a host composition example and test-only measurement utility, not a ranui API or a -set of required product dimensions. The normative owner is [DESIGN §11](../../docs/DESIGN.md#alignment-is-structure-not-polish). +set of required product dimensions. The normative owner is [DESIGN §9](../../docs/DESIGN.md#alignment-is-structure-not-polish). From the repository root: diff --git a/plugins/ran/evals/results/2026-10-22/README.md b/plugins/ran/evals/results/2026-10-22/README.md index 09100f9d37..7c6a768287 100644 --- a/plugins/ran/evals/results/2026-10-22/README.md +++ b/plugins/ran/evals/results/2026-10-22/README.md @@ -44,7 +44,8 @@ removed; [tools-cleanup.patch](./tools-cleanup.patch) records that cosmetic delt `feedback.mjs` probe and negative/restored control are separate from the frozen v1 rubric. Final deterministic controls were rerun against the shipped tools. -Codex marketplace discovery, actual installation of ranui 1.2.0, cached/source skill byte equality, +Codex marketplace discovery, actual installation of the then-separate `ranui` agent plugin +1.2.0 (since merged into `plugins/ran`; not the npm package), cached/source skill byte equality, and a new read-only `$ranui` session were exercised. It routed the copy/snapshot rule and stale screenshots to their canonical owners. Temporary plugin/marketplace entries were removed and the user's marketplace inventory returned unchanged. Both Claude manifests validated; no Claude diff --git a/plugins/ran/skills/design/SKILL.md b/plugins/ran/skills/design/SKILL.md index 60b8b8b34a..6b54add4a4 100644 --- a/plugins/ran/skills/design/SKILL.md +++ b/plugins/ran/skills/design/SKILL.md @@ -19,8 +19,8 @@ Preserve accessible names, useful constraints, errors and consequences. Use screenshots of the actual host to inspect layout, content density and responsive states. Use continuous recordings for changed transitions, streaming, navigation and interruption. Record the source/runtime being inspected, observations and limits; fixtures do not certify another product. -Distinguish automated checks, agent visual review and human acceptance. Complete authorized work without -introducing an additional approval gate. +Distinguish automated checks, agent visual review and human acceptance. Do not add a confirmation step +to work that is already authorized; the host project's own approval rules still apply. When the project uses ranui or ranuts, load that library's sibling skill for installed-version contracts. These design references describe methods, not APIs or permission to install or upgrade dependencies. diff --git a/plugins/ran/skills/design/references/DESIGN.md b/plugins/ran/skills/design/references/DESIGN.md index 4be8d5a0de..d2c28a6474 100644 --- a/plugins/ran/skills/design/references/DESIGN.md +++ b/plugins/ran/skills/design/references/DESIGN.md @@ -94,9 +94,9 @@ may move to demonstrate loading; a decorative status pulse must not imply live a - Test actual pointer/touch gestures, hover fallback and keyboard routes where affected; checking two color schemes does not establish input parity. -## 11. Composition — the page, not the component +## 9. Composition — the page, not the component -Choose the page structure in §12 first; then compose its components with these rules. +Choose the page structure in §10 first; then compose its components with these rules. ### Style coherence across components and pages @@ -418,7 +418,7 @@ actual runtime/capture identity, browser measurements and separate automated, ag results. The source-only [browser example](https://github.com/chaxus/ran/blob/main/packages/ranui/test/e2e/layout-contract.md) contains setup commands and test utility details; they are not public package APIs. -## 12. Information architecture — the shape before the composition +## 10. Information architecture — the shape before the composition Choose structure before composition for information-dense consoles, dashboards and workbenches. Complete API data is not a page design: the reader still needs a clear order for understanding @@ -477,7 +477,7 @@ point that links back to it. Default reading order — page identity → current status or exception → primary task and primary action → the information the judgement needs → relationships, changes, evidence → secondary information and low-frequency actions. **One primary action per task region**, and it is the -most likely next step, not the most destructive one (§11, "Emphasis is a budget", governs how +most likely next step, not the most destructive one (§9, "Emphasis is a budget", governs how much weight it may take). ### Density is effective information, not controls per inch @@ -502,12 +502,12 @@ redundant return shortcut, or repeat that parent as an inert crumb above its ret When returning through the parent already reaches the ancestor, that journey preserves access without adding another detail-header row. Use breadcrumbs when the hierarchy itself helps the task. -**`r-modal` is not a navigation layer.** Anything needing a copyable link, history, a -side-by-side comparison, or work that survives a refresh gets a route. Reserve the modal for a -short confirmation or a single field, `r-popover` / `r-dropdown` for transient context, and -`r-disclosure-row` for progressive disclosure. +**A modal is not a navigation layer.** Anything needing a copyable link, history, a +side-by-side comparison, or work that survives a refresh gets a route. Reserve a modal for a +short confirmation or a single field, a popover or menu for transient context, and a disclosure +row for progressive disclosure. -**`r-tabs` carries peer views of one object** — its conversation, its checks, its diff — never +**Tabs carry peer views of one object** — its conversation, its checks, its diff — never unrelated modules; that is navigation's job. If the chosen library lacks a suitable primitive, use existing semantic elements and host tokens; @@ -529,4 +529,4 @@ unrelated flows merely to satisfy the list. Repository CI still runs its complet - [ ] Run the host’s applicable checks and inspect actual browser evidence. - [ ] Copy follows §6; nothing signals state by color alone (§7). - [ ] For a dense surface: one primary model, the skeleton chosen from the question rather - than the payload, and every fact with one authoritative location (§12). + than the payload, and every fact with one authoritative location (§10). diff --git a/plugins/ran/skills/design/references/INTERFACE_GUIDE.md b/plugins/ran/skills/design/references/INTERFACE_GUIDE.md index 3031e1198a..d3e88fc4cf 100644 --- a/plugins/ran/skills/design/references/INTERFACE_GUIDE.md +++ b/plugins/ran/skills/design/references/INTERFACE_GUIDE.md @@ -10,7 +10,7 @@ workflow recipes apply only when a task needs them. | Decision | Owner | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Visual hierarchy, composition, type, spacing, density, color and motion | [DESIGN.md](./DESIGN.md), [composition](./DESIGN.md#11-composition--the-page-not-the-component) and [density](./DESIGN.md#density-follows-control-roles) | +| Visual hierarchy, composition, type, spacing, density, color and motion | [DESIGN.md](./DESIGN.md), [composition](./DESIGN.md#9-composition--the-page-not-the-component) and [density](./DESIGN.md#density-follows-control-roles) | | Observable input, focus, keyboard, drafts, feedback, progress and recovery | [INTERACTION.md](./INTERACTION.md#1-inputs-drafts-and-intent) (inputs), [focus](./INTERACTION.md#2-reachable-controls-and-predictable-focus), [recovery](./INTERACTION.md#4-progress-failure-and-recovery) | | Optional batches/queues, capability-aware settings, account/data access or result revisions | [WORKFLOW_PATTERNS.md](./WORKFLOW_PATTERNS.md) | | Actual browser proof, evidence freshness and review authority | [ACCEPTANCE.md](./ACCEPTANCE.md) | @@ -35,7 +35,7 @@ These links route to existing rules; they introduce no additional standard or de | Uneven vertical spacing, wrapped copy, hidden helper leaving a hole | [vertical rhythm](./DESIGN.md#vertical-rhythm-across-sibling-views) | Independently expected relationships; show/hide and resize; distinguish frame gap from text leading and baseline space | | Controls line up but labels or icons drift | [alignment](./DESIGN.md#alignment-is-structure-not-polish) | Frame, text Range, icon and hit-area measurements; reverse-check text-only drift | | Oversized commands, weak hierarchy or cramped touch controls | [command hierarchy](./DESIGN.md#command-hierarchy-in-constrained-panes), [density](./DESIGN.md#density-follows-control-roles) | Full adjacent control group at actual mouse/touch density, with resting affordance and reachable targets | -| Redundant navigation or misplaced actions | [information architecture](./DESIGN.md#12-information-architecture--the-shape-before-the-composition) | Complete the route and return path; verify labels, action placement and focus against INTERACTION | +| Redundant navigation or misplaced actions | [information architecture](./DESIGN.md#10-information-architecture--the-shape-before-the-composition) | Complete the route and return path; verify labels, action placement and focus against INTERACTION | | Add animation or subtle effects | [motion](./DESIGN.md#5-motion--prefer-none), [craft](./DESIGN.md#evaluate-craft-through-evidence) | Repeat and interrupt the action; inspect reduced motion and theme switching | For deliberate visual exploration, use the optional [reference research index](./REFERENCE_RESEARCH.md) diff --git a/plugins/ran/skills/design/references/manifest.json b/plugins/ran/skills/design/references/manifest.json index 042f7a6caf..bb84f3fadf 100644 --- a/plugins/ran/skills/design/references/manifest.json +++ b/plugins/ran/skills/design/references/manifest.json @@ -10,9 +10,9 @@ }, { "source": "design/DESIGN.md", - "sha256": "e155cd85297c6024c201dfce74c3f48b2fc21082a8255c1dda3542e5ab601b6f", + "sha256": "87b6fa30179fea6dd20d6b9d2eedc6e3421f1bec624c500357d5e0da923ea6b3", "output": "DESIGN.md", - "outputSha256": "7cd2d4cfa1ee38930fccc2528164a845c6c1326fad0c1f3671475d9c04ed716d" + "outputSha256": "cfc4e6451444b4da4db4df4b96b3cca7a2358f5c3beee850eb56159a0d0919c1" }, { "source": "design/INTERACTION.md", @@ -22,9 +22,9 @@ }, { "source": "design/INTERFACE_GUIDE.md", - "sha256": "0dec552801694c9bdeae3e01350918280b76dfb525dcf095905ade560fdc1323", + "sha256": "7e05ef8f5dcd216ed6054e4829a2d225a6a0f48433ca0bb97752e65b8a76f2f5", "output": "INTERFACE_GUIDE.md", - "outputSha256": "c6f12d12178a9ff015161d5e294e402d5dcca7eaa88ab230c56de064c34f9aa0" + "outputSha256": "075b80aa1c9a406897b026500e856cae2114662d42d29eea2c4d92d3901b9fb0" }, { "source": "design/README.md",