docs(design): renumber sections and move ranui names into the adapter

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).

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)

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;

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。

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

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.
    */

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

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<HTMLDivElement>();
     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();
   });
 

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