@jxsuite/studio 5.2.0 → 5.4.0

package/src/surfaces/panel-signals.json

@@ -163,7 +163,11 @@
       "fontSize": "var(--jx-text-xs)",
       "color": "var(--fg-dim)"
     },
-    "& [part=\"bar-segments\"], & [part=\"bar-buttons\"]": {
+    "& [part=\"bar-segments\"]": {
+      "$description": "The Body switch is the kit's segmented control, which draws its own row, frame and selected segment; all the bar asks of it is not to shrink.",
+      "flex": "none"
+    },
+    "& [part=\"bar-buttons\"]": {
       "display": "flex",
       "flex": "none",
       "alignItems": "center"
@@ -1172,11 +1176,17 @@
                                         "textContent": "${$map.item.label}"
                                       },
                                       {
-                                        "tagName": "span",
+                                        "$description": "The mode switch is the kit's radiogroup, as the Logic panel's Handler body is. It was a `span` with `role=group` over buttons that carried `selected` alone: the one Spectrum `compact` group the conversion never reached, so it drew as two loose words and announced neither which mode was on nor that the two exclude each other. `checked` makes each segment a radio, so the caret roves and `aria-checked` is the element's own.",
+                                        "tagName": "jx-action-group",
                                         "attributes": {
-                                          "part": "bar-segments",
-                                          "role": "group",
-                                          "aria-label": "${$map.item.label}"
+                                          "part": "bar-segments"
+                                        },
+                                        "$props": {
+                                          "selects": "single",
+                                          "compact": true,
+                                          "label": {
+                                            "$ref": "$map/item/label"
+                                          }
                                         },
                                         "children": [
                                           {
@@ -1198,11 +1208,16 @@
                                                 "label": {
                                                   "$ref": "$map/item/label"
                                                 },
-                                                "selected": {
-                                                  "$ref": "$map/item/selected"
+                                                "checked": {
+                                                  "$ref": "$map/item/checked"
                                                 }
                                               },
-                                              "textContent": "${$map.item.label}",
+                                              "children": [
+                                                {
+                                                  "tagName": "span",
+                                                  "textContent": "${$map.item.label}"
+                                                }
+                                              ],
                                               "onclick": {
                                                 "$prototype": "Function",
                                                 "body": [

package/src/surfaces/panel-signals.ts

@@ -93,7 +93,11 @@ export interface SignalCellRowView {
 export interface SignalSegmentView {
   key: string;
   label: string;
-  selected: boolean;
+  /**
+   * `"true"` / `"false"`: the switch is a radiogroup, and a segment is a radio only while `checked`
+   * is non-empty. It also draws the segment selected, so there is no separate `selected`.
+   */
+  checked: "true" | "false";
   signal: string;
   field: string;
 }

package/src/surfaces/panel-stylebook-layers.json

@@ -95,7 +95,7 @@
       "whiteSpace": "nowrap"
     },
     "& [part=\"empty\"]": {
-      "$description": "Drawn here rather than borrowed from `panels/empty-state.ts`, which is a lit template a document cannot call. What is kept is the pattern's rules (§11): one sentence saying what the region is for, then where its content comes from.",
+      "$description": "Drawn here rather than borrowed from `panels/empty-state.ts`, which is a lit template a document cannot call. What is kept is the pattern's rules (studio-ui-guidelines.md §11): one sentence saying what the region is for, then where its content comes from.",
       "display": "flex",
       "flexDirection": "column",
       "alignItems": "center",

package/src/surfaces/panel-stylebook-layers.ts

@@ -108,8 +108,8 @@ function project(scope: StylebookLayersScope, values: StylebookLayersValues): vo
  *
  * Nothing is called on the elements, so the mount is all this has to wait for: the DOCUMENT is what
  * this surface renders, and the kit elements inside it settle their own templates one
- * `connectedCallback` later without anybody here asking them to (guidelines §1.1, "await the
- * element").
+ * `connectedCallback` later without anybody here asking them to (studio-ui-guidelines.md §1.1,
+ * "await the element").
  */
 export function mountStylebookLayersSurface(
   container: HTMLElement,

package/src/surfaces/preferences.json

@@ -85,7 +85,8 @@
       "maxHeight": "60vh",
       "overflowY": "auto"
     },
-    "& [part=\"title\"]": {
+    "& [part=\"section\"] > [part=\"title\"]": {
+      "$description": "The sheet's own heading, and a CHILD selector because the Assistant section mounts other documents into this one's light DOM: the credentials form draws a `[part=\"title\"]` of its own (\"AI provider key\"), and as a bare descendant this rule set the section heading's size on it. A host styles the boxes it draws, never a name its guest also uses — `tests/surface-part-names.test.ts` holds the island hosts to that.",
       "margin": "0",
       "fontSize": "var(--jx-text-lg)",
       "color": "var(--fg)"
@@ -121,8 +122,10 @@
       "gap": "var(--jx-space-2)"
     },
     "& [part=\"account\"]": {
+      "$description": "A wrapping row (studio-ui-guidelines.md §4.6): the sentence and the actions share one line while the sentence keeps its basis, and the actions drop under it when they would not. A brokered Cloudflare row carries two actions (Reconnect or Choose account, beside Disconnect), and on one line they squeezed the sentence into a column about 114px wide at the default width. Every single-action row measures exactly what it did before the wrap existed. `align-items: flex-start`, not `center`, because the sentence's height is not the row's: the AI row's endpoint wraps to five lines, and centred that put Disconnect level with the fourth line of a URL while the heading it acts on sat at the top, so the card read as two unrelated things. Pinned to the start, the button is always beside its label.",
       "display": "flex",
-      "alignItems": "center",
+      "flexWrap": "wrap",
+      "alignItems": "flex-start",
       "justifyContent": "space-between",
       "gap": "var(--jx-space-4)",
       "padding": "var(--jx-space-3)",
@@ -130,8 +133,9 @@
       "borderRadius": "var(--radius)"
     },
     "& [part=\"account-text\"]": {
-      "$description": "`min-width: 0` so a long detail sentence ellipses inside the row rather than pushing the row's own buttons off the end of it.",
+      "$description": "The wrap threshold is this basis, not a width: 120px of sentence is the least a row keeps before its actions take a line of their own. Keep it well under 200px, or a single-action row at the default sheet width wraps at rest. `min-width: 0` lets the column shrink below its content, and what then fits the detail into it is the detail's own `overflow-wrap`. Nothing here ellipsizes: the detail is the only place the row names its endpoint or account, so a truncated one would hide exactly the part that tells two of them apart.",
       "display": "flex",
+      "flex": "1 1 120px",
       "flexDirection": "column",
       "gap": "var(--jx-space-1)",
       "minWidth": "0"
@@ -140,19 +144,25 @@
       "color": "var(--fg)"
     },
     "& [part=\"account-detail\"]": {
+      "$description": "`overflow-wrap: anywhere` because the detail carries author-supplied strings with no break opportunity in them: the AI row's endpoint URL (a Cloudflare AI Gateway URL is a 32-hex account id between slashes) and the local Cloudflare row's account id. Without it one of them measured 419px in a 223px column, ran under Disconnect, past the card's border, and scrolled the whole section sideways. `anywhere` rather than `break-word`, because only `anywhere` lowers the min-content the row is sized from; not `word-break: break-all`, which would split every ordinary word in the sentences around it. It sits here rather than on the column because the label is a fixed service name and only the detail is unbounded.",
       "fontSize": "var(--jx-text-sm)",
-      "color": "var(--fg-dim)"
+      "color": "var(--fg-dim)",
+      "overflowWrap": "anywhere"
     },
     "& [part=\"account-actions\"]": {
+      "$description": "`margin-inline-start: auto` keeps the actions at the row's end when the wrap puts them on a line of their own; on a shared line `space-between` already puts them there, so the margin changes nothing.",
       "display": "flex",
       "alignItems": "center",
       "gap": "var(--jx-space-3)",
-      "flexShrink": "0"
+      "flexShrink": "0",
+      "marginInlineStart": "auto"
     },
     "& [part=\"keys\"]": {
+      "$description": "The inline-end padding is for the scrollbar, not for rhythm. A row whose title wraps pushes its `Change` button to the very end of the line, and the sheet always scrolls (64 bindings), so that button's right edge landed exactly on the scroller's content edge and read as touching the scrollbar track.",
       "display": "flex",
       "flexDirection": "column",
-      "gap": "var(--jx-space-1)"
+      "gap": "var(--jx-space-1)",
+      "paddingInlineEnd": "var(--jx-space-2)"
     },
     "& [part=\"refusal\"]": {
       "display": "flex",
@@ -177,9 +187,10 @@
       "textTransform": "uppercase",
       "color": "var(--fg-dim)"
     },
-    "& [part=\"key\"]": {
+    "& [part=\"key\"][data-command]": {
+      "$description": "Qualified by `data-command`, the attribute a binding row carries, because `key` is also the credentials form's API-key FIELD and that form is mounted into this sheet's own light DOM: as a bare descendant this rule laid a 16px flex row over a `jx-textfield`, which drew it 24px tall beside the 20px endpoint field under it. `center`, not `baseline`: the `Change` and `Reset` buttons are small kit action buttons, and a small kit control is layout-contained so its outset hit area adds nothing to this sheet's scrollable overflow, which leaves it with no baseline to export. A baseline row synthesises one from the button's bottom edge instead, and every row grew from 24px to 29px with the chord and title dropped onto it. Centred, every single-line row measures exactly what the baseline layout did (24px, with the chord, the title and the button label on one baseline); a row whose title wraps centres its chord and buttons between the title's lines. surface-baseline-rows.test.ts holds the rule for every surface.",
       "display": "flex",
-      "alignItems": "baseline",
+      "alignItems": "center",
       "gap": "var(--jx-space-4)",
       "padding": "var(--jx-space-1) 0"
     },
@@ -191,6 +202,8 @@
       "color": "var(--fg)"
     },
     "& [part=\"key-title\"]": {
+      "$description": "`flex: 1` for the same reason the chord beside it is a fixed 96px column: down 64 rows, an action that starts where the last title ended is not scannable. The title took its content's width, so `Change` landed at fourteen different offsets in the first twenty rows, and at the line's very end on a row whose title wrapped. Growing the title instead pins the actions to that end, where a reader finds them by scanning one edge. `minWidth: 0` is what still lets a long title wrap rather than widen the sheet.",
+      "flex": "1",
       "color": "var(--fg-dim)",
       "minWidth": "0"
     }

package/src/surfaces/preferences.ts

@@ -253,7 +253,8 @@ export function openPreferencesSurface(
     setKeyQuery: (value: string) => {
       /* What the control now holds, first and unconditionally. A binding only writes when the
          scope CHANGES, so a surface that decided a query without announcing the raw one would
-         leave the field showing something the scope does not have (§9.3). */
+         leave the field showing something the scope does not have
+         (studio-ui-guidelines.md §9.3). */
       scope.keyQuery = value;
       options.onKeyQuery(value);
     },
@@ -303,6 +304,13 @@ export function openPreferencesSurface(
     const box = element.querySelector<HTMLElement>('dialog[part="dialog"]') ?? element;
     box.setAttribute(REGION_ATTR, overlayRegion("dialog", "preferences"));
     showModal(element);
+    /* The nav item the sheet OPENED on, not the first one the dialog finds. `showModal()` focuses
+       the first focusable descendant, which is always Appearance, so `app.preferences` with a
+       section put the ring on one row while `aria-current` and the selected fill were on another:
+       two rows looked active at once, and the keyboard was in the wrong place to move between
+       them. Read off `aria-current` rather than from the view, because that attribute is the one
+       record of which section is showing (`preferences.json` says so on the rule that draws it). */
+    element.querySelector<HTMLElement>('[part="nav-item"][aria-current="true"]')?.focus();
     return element;
   });
 

package/src/surfaces/properties-panel.json

@@ -48,7 +48,7 @@
       "minWidth": "0"
     },
     "& [part=\"section-body\"] > [part=\"row\"], & [part=\"layout-class-slot\"] > [part=\"row\"]": {
-      "$description": "§4.1's standard form row, stacked: the label sits above a control that takes the whole width. `min-width: 0` is what keeps it honest in a narrow dock — a field refuses to shrink below its own min-content without it. Scoped to the tab's OWN rows rather than to every `part=\"row\"` beneath it, which a colour row made load-bearing: the kit is light DOM and one cascade, so a bare descendant selector also matches `jx-color-field`'s internal row — and at equal specificity with the kit's own `& > [part=\"row\"]` the winner is whichever sheet was interned later, which is not a thing a stylesheet may depend on. `[part=\"chip\"]` moved under `[part=\"chip-slot\"]` for the same reason and a sharper one: its `background: transparent` and its border would otherwise have erased a swatch's colour and drawn a box round it. The `layout-class-slot` half of the pair is there because that slot is `display: contents`, so its row is a grandchild in the DOM even though it is a child in the box tree.",
+      "$description": "studio-ui-guidelines.md §4.1's standard form row, stacked: the label sits above a control that takes the whole width. `min-width: 0` is what keeps it honest in a narrow dock — a field refuses to shrink below its own min-content without it. Scoped to the tab's OWN rows rather than to every `part=\"row\"` beneath it, which a colour row made load-bearing: the kit is light DOM and one cascade, so a bare descendant selector also matches `jx-color-field`'s internal row — and at equal specificity with the kit's own `& > [part=\"row\"]` the winner is whichever sheet was interned later, which is not a thing a stylesheet may depend on. `[part=\"chip\"]` moved under `[part=\"chip-slot\"]` for the same reason and a sharper one: its `background: transparent` and its border would otherwise have erased a swatch's colour and drawn a box round it. The `layout-class-slot` half of the pair is there because that slot is `display: contents`, so its row is a grandchild in the DOM even though it is a child in the box tree.",
       "display": "flex",
       "flexDirection": "column",
       "alignItems": "stretch",
@@ -92,7 +92,7 @@
       "minInlineSize": "0"
     },
     "& [part=\"chip-slot\"] > [part=\"chip\"]": {
-      "$description": "§6.2's provenance chip. `set` is the 6px accent dot it has always been — a circle is not a button, whatever element draws it — and the three states that carry a donor are bordered chips naming it. The fourth state, `default`, draws nothing at all: a ghost dot on every unset row says less than silence.",
+      "$description": "§6.7's provenance chip. `set` is the 6px accent dot it has always been — a circle is not a button, whatever element draws it — and the three states that carry a donor are bordered chips naming it. The fourth state, `default`, draws nothing at all: a ghost dot on every unset row says less than silence.",
       "flexShrink": "0",
       "display": "inline-flex",
       "alignItems": "center",
@@ -585,7 +585,7 @@
                 },
                 "children": [
                   {
-                    "$description": "§6.2's collapsed-header tally. It is an indicator and not a control: the heading's own click already toggles the section, so a second meaning for the same click would be worse than the silence. It says how many values in the section are set, which is what a closed section otherwise cannot say.",
+                    "$description": "§6.7's collapsed-header tally. It is an indicator and not a control: the heading's own click already toggles the section, so a second meaning for the same click would be worse than the silence. It says how many values in the section are set, which is what a closed section otherwise cannot say.",
                     "tagName": "span",
                     "attributes": {
                       "slot": "heading",
@@ -744,7 +744,7 @@
                                       },
                                       "cases": {
                                         "true": {
-                                          "$description": "§6.3's Value Source chip: the rung this value is produced at, in plain language, opening a picker of every rung the POSITION permits. The rungs are derived from the schema at that position and the picker is the kit menu every other list in the shell opens, so neither is decided here.",
+                                          "$description": "§6.6's Value Source chip: the rung this value is produced at, in plain language, opening a picker of every rung the POSITION permits. The rungs are derived from the schema at that position and the picker is the kit menu every other list in the shell opens, so neither is decided here.",
                                           "tagName": "jx-action-button",
                                           "attributes": {
                                             "part": "source",

package/src/surfaces/properties-panel.ts

@@ -104,7 +104,7 @@ export interface ContentRowView {
   tokens: ContentTokenView[];
   hasTokens: boolean;
   /**
-   * The provenance chip's shape: `""` draws nothing (§6.2's `default` state, where absence IS the
+   * The provenance chip's shape: `""` draws nothing (§6.7's `default` state, where absence IS the
    * ghost), `dot` is the 6px accent dot that clears the value, `text` states a donor without
    * offering to go there, and `press` states one and opens it.
    */
@@ -145,7 +145,7 @@ export interface ContentSectionView {
   key: string;
   label: string;
   open: boolean;
-  /** Whether anything in this section is set, so a closed section still says so (§6.2). */
+  /** Whether anything in this section is set, so a closed section still says so (§6.7). */
   hasDot: boolean;
   dotTitle: string;
   rows: ContentRowView[];

package/src/surfaces/publish.json

@@ -53,7 +53,7 @@
       "gap": "var(--jx-space-3)"
     },
     "& [part=\"actions\"]": {
-      "$description": "Wraps rather than overflows (§4.6): two buttons whose labels are whole phrases — \"Verify & Connect\", \"Preferences › Accounts\" — are wider than a narrow dialog at the sizes a reader may have set.",
+      "$description": "Wraps rather than overflows (studio-ui-guidelines.md §4.6): two buttons whose labels are whole phrases — \"Verify & Connect\", \"Preferences › Accounts\" — are wider than a narrow dialog at the sizes a reader may have set.",
       "display": "flex",
       "flexWrap": "wrap",
       "gap": "var(--jx-space-2)"

package/src/surfaces/publish.ts

@@ -309,7 +309,8 @@ export function openPublishSurface(options: PublishSurfaceOptions): PublishSurfa
     setAccount: (value: string) => {
       /* What the control now holds, first and unconditionally. A binding only writes when the
          scope CHANGES, so a surface that decided a value without announcing the raw one would
-         leave the control showing something the scope does not have (§9.3). */
+         leave the control showing something the scope does not have
+         (studio-ui-guidelines.md §9.3). */
       scope.accountId = value;
       options.onField("accountId", value);
     },

package/src/surfaces/push-plan.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioPushPlan",
-  "$description": "What pushing the schema would do, or what it did. The dry run is the whole point of the surface: a push rewrites a live database's shape, so the plan is read before the apply, and the confirm dialog around this document is the one that gates it. The ISLAND of `ui/layers.ts`'s confirm dialog rather than a dialog of its own (§12.5).",
+  "$description": "What pushing the schema would do, or what it did. The dry run is the whole point of the surface: a push rewrites a live database's shape, so the plan is read before the apply, and the confirm dialog around this document is the one that gates it. The ISLAND of `ui/layers.ts`'s confirm dialog rather than a dialog of its own (studio-ui-guidelines.md §12.5).",
   "tagName": "div",
   "attributes": {
     "part": "plan"
@@ -41,7 +41,8 @@
       "fontSize": "var(--jx-text-sm)",
       "color": "var(--warning, var(--fg-dim))"
     },
-    "& [part=\"error\"]": {
+    "& [part=\"failure\"]": {
+      "$description": "`failure` rather than `error`: every kit field draws a permanent, empty `[part=\"error\"]` of its own, and the kit is light DOM, so a rule on that name here would reach any field the plan ever holds.",
       "margin": "0",
       "fontSize": "var(--jx-text-sm)",
       "color": "var(--danger)"
@@ -100,7 +101,7 @@
       "map": {
         "tagName": "p",
         "attributes": {
-          "part": "error",
+          "part": "failure",
           "role": "alert"
         },
         "textContent": "${$map.item.text}"

package/src/surfaces/rail.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioRail",
-  "$description": "The Navigator rail: a rendering of the panel registry. The adapter hands in `groups`, every rail-able panel grouped by level with its selected state and badge, and `settingsVisible`/`settingsOpen` for the foot's gear. Nothing here is a list of panels.",
+  "$description": "The Navigator rail: a rendering of the panel registry. The adapter hands in `groups`, every rail-able panel grouped by level with its selected state and badge, and `settingsVisible`/`settingsOpen` for the foot's gear. Nothing here is a list of panels. Each button prints its record's short `railLabel` under the glyph, falling back to `title`, and carries the full `title` as its accessible name and tooltip: the visible words lead the name a reader hears (WCAG 2.5.3), and the tooltip restores what a short label leaves out.",
   "tagName": "div",
   "attributes": {
     "part": "rail"
@@ -145,7 +145,7 @@
                       "children": [
                         {
                           "tagName": "span",
-                          "textContent": "${$map.item.title}"
+                          "textContent": "${$map.item.railLabel}"
                         }
                       ]
                     }

package/src/surfaces/rail.ts

@@ -7,10 +7,12 @@
  * call in the module that owns it, and it appears here; there is nothing to update in step.
  *
  * **Every rail button opens the Navigator, and the grouping is by LEVEL.** Every button is a
- * `jx-action-button` in its stacked form, so it carries an 11px text label under its icon — an icon
- * whose only name is a hover tooltip is the accessibility failure §2 principle 6 names — and
- * `aria-pressed` states the toggle-focus semantics honestly: re-picking the open panel collapses
- * its dock, which is a two-state control, not a one-way selection.
+ * `jx-action-button` in its stacked form, so it carries a 10px text label under its icon — an icon
+ * whose only name is a hover tooltip is the accessibility failure studio-ui-guidelines.md §12.3
+ * names — and `aria-pressed` states the toggle-focus semantics honestly: re-picking the open panel
+ * collapses its dock, which is a two-state control, not a one-way selection. The label is the
+ * record's `railLabel` when it declares one (Source Control's is "Source", because the full title
+ * ellipsed in the 48px label box), and the full `title` stays the accessible name and the tooltip.
  *
  * The foot is the ⚙ **Settings** menu, a menu button rendered from the `settings/menu` placement: a
  * record joins the gear by declaring the placement and there is nothing here to update in step.
@@ -48,7 +50,10 @@ registerSurface("rail", railDoc as unknown as JxDocument);
 /** One rail button, as the surface reads it. */
 interface RailButton {
   id: string;
+  /** The full name: the control's accessible name and its tooltip. */
   title: string;
+  /** The text under the glyph: the record's `railLabel`, else its title. */
+  railLabel: string;
   icon: string;
   selected: boolean;
   /** The badge text; empty for none. */
@@ -109,6 +114,7 @@ function project(): { groups: RailGroupProjection[]; settingsVisible: boolean }
       badge: String(panel.badge?.(ctx) ?? ""),
       icon: panel.icon,
       id: panel.id,
+      railLabel: panel.railLabel ?? panel.title,
       selected: isRailPanelShowing(panel),
       title: panel.title,
     })),

package/src/surfaces/reference-field.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://jxsuite.com/schema/v1",
   "$id": "StudioReferenceField",
-  "$description": "The `reference` form control — site-architecture.md §6.1's `{ \"$ref\": \"#/content/x\" }` and §7.4's entry picker. Registered once and dispatched to by `ui/schema-form.ts` for any property whose `$ref` names a collection, so the settings forms, the entry editor and an array-of-objects cell all draw the same control without any of them knowing it exists. `ui/form-controls.ts` decides which of the three states the field is in and what each gesture commits; nothing here reads a schema or lists a directory. The three states are drawn as three different controls on purpose: a picker while the entries are known, a TEXT field while they are not — a failed read leaves the value editable with the reason beside it, because swapping it for an empty dropdown would present \"no entries\" and \"could not find out\" as the same screen — and a disabled picker saying so while the read is in flight.",
+  "$description": "The `reference` form control — site-architecture.md §6.1's `{ \"$ref\": \"#/content/x\" }` and site-architecture.md §7.4's entry picker. Registered once and dispatched to by `ui/schema-form.ts` for any property whose `$ref` names a collection, so the settings forms, the entry editor and an array-of-objects cell all draw the same control without any of them knowing it exists. `ui/form-controls.ts` decides which of the three states the field is in and what each gesture commits; nothing here reads a schema or lists a directory. The three states are drawn as three different controls on purpose: a picker while the entries are known, a TEXT field while they are not — a failed read leaves the value editable with the reason beside it, because swapping it for an empty dropdown would present \"no entries\" and \"could not find out\" as the same screen — and a disabled picker saying so while the read is in flight.",
   "tagName": "div",
   "attributes": {
     "part": "reference",

package/src/surfaces/schema-form.json

@@ -151,7 +151,7 @@
                 },
                 "cases": {
                   "true": {
-                    "$description": "The Value Source chip (§6.3): what produces this value, in the same four words every other bindable position in Studio uses. It opens the rung picker rather than cycling, so any rung the position permits is one action away. Drawn only where the host named somewhere a value could come from — a settings form that names none edits fixed values and shows no chip.",
+                    "$description": "The Value Source chip (§6.6): what produces this value, in the same four words every other bindable position in Studio uses. It opens the rung picker rather than cycling, so any rung the position permits is one action away. Drawn only where the host named somewhere a value could come from — a settings form that names none edits fixed values and shows no chip.",
                     "tagName": "jx-action-button",
                     "attributes": {
                       "part": "source",
@@ -966,7 +966,7 @@
             },
             "cases": {
               "true": {
-                "$description": "§7.1's inline tier: why this value is refused, said AT the control that refuses it and for exactly as long as the value stays bad. `role=\"alert\"` so it is announced when it appears, and a repeat counter from two up — “it refused me again” is otherwise indistinguishable from “the field is still red from last time”.",
+                "$description": "§16.1's inline tier: why this value is refused, said AT the control that refuses it and for exactly as long as the value stays bad. `role=\"alert\"` so it is announced when it appears, and a repeat counter from two up — “it refused me again” is otherwise indistinguishable from “the field is still red from last time”.",
                 "tagName": "p",
                 "attributes": {
                   "part": "field-error",

package/src/surfaces/schema-form.ts

@@ -117,7 +117,7 @@ export interface SchemaFormFieldView {
   mono: boolean;
   /** Draw the text control as a text area. */
   multiline: boolean;
-  /** Why this value is refused (§7.1's inline tier). Empty draws nothing. */
+  /** Why this value is refused (§16.1's inline tier). Empty draws nothing. */
   error: string;
   /** Whether there is a refusal to announce. A document branches on a flag, never on a length. */
   hasError: boolean;

package/src/surfaces/seo.json

@@ -194,7 +194,7 @@
       }
     },
     "& [part=\"chip\"]": {
-      "$description": "The provenance vocabulary of `panels/provenance.ts` §6.2, drawn by this document rather than borrowed as a class: `set` keeps the accent dot it has always been, `inherited` is an amber pill naming its donor, and a field nothing supplies gets no chip at all — because a ghost dot on every unset row says less than silence. The two chips that can go somewhere are `<button>`s; the ones with nowhere to go are not, which is §6.2's rule that a control which looks pressable and does nothing is a defect.",
+      "$description": "The provenance vocabulary of `panels/provenance.ts` (§6.7), drawn by this document rather than borrowed as a class: `set` keeps the accent dot it has always been, `inherited` is an amber pill naming its donor, and a field nothing supplies gets no chip at all — because a ghost dot on every unset row says less than silence. The two chips that can go somewhere are `<button>`s; the ones with nowhere to go are not, which is §6.7's rule that a control which looks pressable and does nothing is a defect.",
       "flexShrink": "0"
     },
     "& jx-dot[part=\"chip\"][data-state=\"set\"]": {

package/src/surfaces/seo.ts

@@ -41,7 +41,7 @@ import type { JxDocument } from "@jxsuite/schema/types";
 
 registerSurface("seo", seoDoc as unknown as JxDocument);
 
-/** How a field's provenance is drawn — §6.2's vocabulary, reduced to three shapes and an absence. */
+/** How a field's provenance is drawn — §6.7's vocabulary, reduced to three shapes and an absence. */
 export type SeoChipKind = "none" | "dot" | "static" | "link";
 
 /** One row of the resolved-field list: what reaches the browser, how long it is, where it came from. */
@@ -55,7 +55,7 @@ export interface SeoFieldView {
   unsetLabel: string;
   /** Whether anybody counts this field at all; `og:image` is a URL and nobody does. */
   counted: boolean;
-  /** The counter, already formatted: `61/60`. Never a total, and never a grade (§9.2, §14). */
+  /** The counter, already formatted: `61/60`. Never a total, and never a grade (§16.6). */
   count: string;
   /** Over its budget. Stated on the counter and named in the warning list — never summed. */
   over: boolean;

package/src/surfaces/settings-contributed.ts

@@ -145,7 +145,8 @@ export function mountContributedSurface(
   let disposed = false;
   /* Nothing is called on an element here, so the mount is all there is to wait for: the islands
      announce themselves through `onNodeCreated` as they are created, which is one
-     `connectedCallback` earlier than awaiting the element would be (§1.1, "await the element"). */
+     `connectedCallback` earlier than awaiting the element would be (studio-ui-guidelines.md §1.1,
+     "await the element"). */
   const ready = mountSurface("settings-contributed", scope, host, {
     onNodeCreated: (element, _path, def) => {
       if (!(element instanceof HTMLElement)) {

package/src/surfaces/settings-css-vars.json

@@ -15,8 +15,8 @@
       "fontWeight": "600",
       "color": "var(--fg)"
     },
-    "& [part=\"error\"]": {
-      "$description": "A write that failed, said under the section title rather than pinned to a control. This section saves on change and the predecessor dropped every rejection on the floor, so a read-only file made each edit look as though it had been taken and then quietly forgotten.",
+    "& [part=\"section-error\"]": {
+      "$description": "A write that failed, said under the section title rather than pinned to a control. This section saves on change and the predecessor dropped every rejection on the floor, so a read-only file made each edit look as though it had been taken and then quietly forgotten. It is `section-error` rather than `error` because every text field and select in the section draws a permanent `[part=\"error\"]` of its own in this same light-DOM tree, and a rule on that name would give their refusal sentences this margin and size too.",
       "margin": "0 0 12px",
       "fontSize": "var(--jx-text-md)",
       "color": "var(--danger)"
@@ -172,7 +172,7 @@
     {
       "tagName": "div",
       "attributes": {
-        "part": "error-slot",
+        "part": "section-error-slot",
         "role": "none"
       },
       "$switch": {
@@ -182,7 +182,7 @@
         "true": {
           "tagName": "p",
           "attributes": {
-            "part": "error",
+            "part": "section-error",
             "role": "alert"
           },
           "textContent": "${state.error}"

package/src/surfaces/settings-deploy.json

@@ -17,8 +17,8 @@
       "fontWeight": "600",
       "color": "var(--fg)"
     },
-    "& [part=\"error\"]": {
-      "$description": "A write that failed, said under the section title rather than pinned to the picker: settings save on change, so a silent rejection would read as \"my edit just vanished\", and what failed was the whole file rather than the value. Its size read `--spectrum-font-size-75` with a 12px fallback, which resolved only inside `<sp-theme>` — a document is mounted in the settings pane, where that name is not in scope and the fallback is all it would ever have taken — so the size is the kit's scale and the colour is the studio layer's.",
+    "& [part=\"section-error\"]": {
+      "$description": "A write that failed, said under the section title rather than pinned to the picker: settings save on change, so a silent rejection would read as \"my edit just vanished\", and what failed was the whole file rather than the value. Its size read `--spectrum-font-size-75` with a 12px fallback, which resolved only inside `<sp-theme>` — a document is mounted in the settings pane, where that name is not in scope and the fallback is all it would ever have taken — so the size is the kit's scale and the colour is the studio layer's. It is `section-error` rather than `error` because the adapter picker is a `jx-select`, which draws a permanent `[part=\"error\"]` of its own in this same light-DOM tree: a rule on that name would give the picker's own refusal sentence this 16px margin too.",
       "margin": "0 0 16px",
       "fontSize": "var(--jx-text-md)",
       "color": "var(--danger)"
@@ -39,7 +39,7 @@
     {
       "tagName": "div",
       "attributes": {
-        "part": "error-slot",
+        "part": "section-error-slot",
         "role": "none"
       },
       "style": {
@@ -52,7 +52,7 @@
         "true": {
           "tagName": "p",
           "attributes": {
-            "part": "error",
+            "part": "section-error",
             "role": "alert"
           },
           "textContent": "${state.error}"

package/src/surfaces/settings-deploy.ts

@@ -105,7 +105,8 @@ export function mountDeploySurface(
   let disposed = false;
   /* Nothing is called on the element, so the mount is all this has to wait for: the DOCUMENT is
      what this surface renders, and `jx-field` and `jx-select` settle their own templates one
-     `connectedCallback` later without anybody here asking them to (§1.1, "await the element"). */
+     `connectedCallback` later without anybody here asking them to (studio-ui-guidelines.md §1.1,
+     "await the element"). */
   void mountSurface("settings-deploy", scope, container).then((surface) => {
     if (disposed) {
       surface.dispose();

package/src/surfaces/settings-extensions.json

@@ -21,8 +21,8 @@
       "fontSize": "var(--jx-text-md)",
       "color": "var(--fg-dim)"
     },
-    "& [part=\"error\"]": {
-      "$description": "The last operation that failed, said under the section title. Not a second announcement: `updateSiteConfig` already files a Problem for a rejected write and `activity.fail` files one for a rejected install. §13.1 makes INLINE the tier for \"the value is on screen, and nothing else is the right place\" — the Problem is about the file, and this line is about the switch the reader is looking at.",
+    "& [part=\"section-error\"]": {
+      "$description": "The last operation that failed, said under the section title. Not a second announcement: `updateSiteConfig` already files a Problem for a rejected write and `activity.fail` files one for a rejected install. studio-ui-guidelines.md §13.1 makes INLINE the tier for \"the value is on screen, and nothing else is the right place\" — the Problem is about the file, and this line is about the switch the reader is looking at. It is `section-error` rather than `error`, the name every settings section uses, because every kit field draws a permanent `[part=\"error\"]` of its own and the kit is light DOM: a rule on that name here would reach any field the section ever holds.",
       "margin": "6px 0 0",
       "fontSize": "var(--jx-text-md)",
       "color": "var(--danger)"
@@ -39,7 +39,7 @@
       "color": "var(--fg)"
     },
     "& [part=\"row\"]": {
-      "$description": "A wrapping row, never an overflowing one (guidelines §4.6): the package name is author-supplied and unbounded, and Project Settings renders at two very different widths.",
+      "$description": "A wrapping row, never an overflowing one (studio-ui-guidelines.md §4.6): the package name is author-supplied and unbounded, and Project Settings renders at two very different widths.",
       "display": "flex",
       "flexWrap": "wrap",
       "alignItems": "flex-start",
@@ -115,7 +115,7 @@
       "flexShrink": "0"
     },
     "& [part=\"empty\"]": {
-      "$description": "The teaching empty state, drawn here rather than borrowed from `panels/empty-state.ts`: that helper is a lit template, and a document cannot call one. What is kept is the pattern's rules (§11) — one sentence saying what the region is FOR, never \"no extensions\", then where its content comes from — in the compact shape, which reads as a note inside an otherwise populated pane rather than as a whole empty region. It offers no action because there is nothing here to act on: a backend that lists no catalogue is not a project waiting to be filled in.",
+      "$description": "The teaching empty state, drawn here rather than borrowed from `panels/empty-state.ts`: that helper is a lit template, and a document cannot call one. What is kept is the pattern's rules (studio-ui-guidelines.md §11) — one sentence saying what the region is FOR, never \"no extensions\", then where its content comes from — in the compact shape, which reads as a note inside an otherwise populated pane rather than as a whole empty region. It offers no action because there is nothing here to act on: a backend that lists no catalogue is not a project waiting to be filled in.",
       "display": "flex",
       "flexDirection": "column",
       "alignItems": "flex-start",
@@ -152,7 +152,7 @@
     {
       "tagName": "div",
       "attributes": {
-        "part": "error-slot",
+        "part": "section-error-slot",
         "role": "none"
       },
       "style": {
@@ -165,7 +165,7 @@
         "true": {
           "tagName": "p",
           "attributes": {
-            "part": "error",
+            "part": "section-error",
             "role": "alert"
           },
           "textContent": "${state.error}"

package/src/surfaces/settings-extensions.ts

@@ -63,7 +63,10 @@ export interface ExtensionRowView {
   note: string;
   /** Whether Remove is offered at all — it is not for a package the project never installed. */
   canRemove: boolean;
-  /** Offered but refused, which is how §10 wants a control that cannot act right now. */
+  /**
+   * Offered but refused, which is how studio-ui-guidelines.md §10 wants a control that cannot act
+   * right now.
+   */
   removeDisabled: boolean;
   removeLabel: string;
   removeHint: string;
@@ -159,7 +162,8 @@ export function mountExtensionsSurface(
   let disposed = false;
   /* Nothing is called on an element here, so the mount is all this has to wait for: the DOCUMENT is
      what this surface renders, and the kit elements inside it settle their own templates one
-     `connectedCallback` later without anybody asking them to (§1.1, "await the element"). */
+     `connectedCallback` later without anybody asking them to (studio-ui-guidelines.md §1.1,
+     "await the element"). */
   void mountSurface("settings-extensions", scope, container).then((surface) => {
     if (disposed) {
       surface.dispose();