@jskit-ai/agent-docs 0.1.117 → 0.1.119

package/guide/agent/app-setup/a-more-interesting-shell.md

@@ -681,11 +681,21 @@ navigation.
 
 The open drawer is content-aware by default. After the visible semantic
 placements and fonts settle, `ShellLayout` measures the rendered labels and
-keeps the drawer edge approximately 10 CSS pixels beyond the widest label. It
-remeasures when placements, localization, fonts, the active surface, or the
-window layout change, and clamps unusually long labels to a safe range. The
-closed desktop rail remains 80 CSS pixels wide by default, with every icon and
-its Material selected-state indicator centred in the rail. Rail tooltips use
+uses Material's 12px outer item inset and one `navigationItemSpacing` value for
+the icon-to-label gap and the space between the widest label and the drawer
+edge. The spacing defaults to 12 CSS pixels and can be set from 8–24px. The
+shell remeasures when placements, localization, fonts, spacing, the active
+surface, or the window layout change, and clamps unusually long labels to a safe range. The
+surface label appears once in the top app bar; the drawer starts with its
+destinations instead of repeating that label as an uppercase subheader.
+
+The closed desktop rail remains 80 CSS pixels wide by default, with every icon
+and its Material selected-state indicator centred in the rail. The expanded
+drawer uses the same icon centreline, so toggling the drawer reveals or hides
+labels without making the icons jump sideways. The empty space around a 24px
+icon in the default rail is intentional Material touch/indicator space, not a
+second drawer padding. Products that deliberately need a denser rail can set
+`railWidth`; the shell still enforces a 48px minimum target. Rail tooltips use
 one explicit opaque theme color pair and open on pointer hover or keyboard
 focus.
 
@@ -701,11 +711,11 @@ product has another discoverable navigation affordance:
 The default is `desktop-drawer-closed-mode="rail"`. Prefer that Material 3
 pattern; do not imitate a rail with custom CSS or a second menu registry.
 
-Applications that need fixed product-specific dimensions can use the public
-width props instead of overriding Vuetify drawer CSS:
+Applications that need product-specific dimensions or spacing can use the
+public props instead of overriding Vuetify drawer CSS:
 
 ```vue
-<ShellLayout :drawer-width="280" :rail-width="88">
+<ShellLayout :drawer-width="280" :rail-width="64" :navigation-item-spacing="12">
   <RouterView />
 </ShellLayout>
 ```
@@ -714,9 +724,24 @@ Omit `drawer-width` to retain content-aware sizing. Omit `rail-width` to retain
 the 80px Material navigation-rail default. Drawer overrides are clamped to
 120–360px and rail overrides to 48–160px so shell navigation cannot consume an
 unsafe share of the viewport or shrink below its touch targets. The app-owned
-`src/components/ShellLayout.vue` wrapper forwards these attributes to the
-package component, so an application does not need to copy or restyle the
-drawer implementation.
+`src/components/ShellLayout.vue` wrapper also forwards
+`navigation-item-spacing`, so an application does not need to copy or restyle
+the drawer implementation.
+
+### Updating an existing shell app
+
+Commit the app's work and run:
+
+```bash
+npm run jskit:update
+```
+
+Keep the generated/app-owned `src/components/ShellLayout.vue` wrapper and let
+it continue forwarding attributes to the package component. No copied drawer,
+`.v-navigation-drawer` CSS, duplicate surface heading, or replacement smoke
+test is required. If the product intentionally wants a denser desktop rail,
+set the supported prop in that wrapper, for example `:rail-width="64"`; omit it
+to keep the Material 3 80px default.
 
 `useShellErrorPresentationStore()` exposes the current banner, snackbar, and dialog presentation state behind `ShellErrorHost`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.117",
+  "version": "0.1.119",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/placements.md

@@ -58,8 +58,8 @@ Runtime behavior:
 - Runtime resolves the component token as `entry.componentToken || variant.renderers[entry.kind]`.
 - Entries without a resolvable component token do not render.
 - `when()` receives placement context including `app`, `surface`, `target`, `layoutClass`, runtime context, local outlet context, and context contributors.
-- The standard `ShellLayout` sizes its open drawer from the widest currently visible placement label plus an approximately 10px logical-end gap. It remeasures after placement, locale, font, surface, and layout changes. Use the public `drawerWidth` prop only when a product needs a fixed width; do not add consumer `.v-navigation-drawer` overrides.
-- On medium and expanded layouts, closing the standard drawer produces an 80px navigation rail by default. Use `railWidth` to configure that width, or `desktopDrawerClosedMode="hidden"` only when another discoverable navigation surface exists.
+- The standard `ShellLayout` uses Material's 12px outer item inset and one `navigationItemSpacing` value (12px by default) for the icon-to-label gap and widest label's logical-end gap. It remeasures its content-aware width after placement, locale, font, surface, spacing, and layout changes. The surface label belongs once in the top app bar; do not add or restore a duplicate drawer subheader. Use `drawerWidth` only when a product needs a fixed width; do not add consumer `.v-navigation-drawer` overrides.
+- On medium and expanded layouts, closing the standard drawer produces an 80px Material navigation rail by default. Expanded and collapsed icons share one centreline. Use `railWidth` to configure an intentionally denser rail, or `desktopDrawerClosedMode="hidden"` only when another discoverable navigation surface exists.
 - The shell link renderers own rail centring, selected-state treatment, and opaque theme-aware tooltips. Applications should keep supplying the same semantic placement records rather than creating rail-only links or tooltip CSS.
 
 CLI and generators:

package/reference/autogen/packages/shell-web.md

@@ -430,13 +430,14 @@ Exports
 ### `src/client/support/drawerWidth.js`
 Exports
 - `DEFAULT_SHELL_DRAWER_WIDTH`
+- `DEFAULT_SHELL_NAVIGATION_ITEM_SPACING`
 - `DEFAULT_SHELL_RAIL_WIDTH`
 - `MAXIMUM_SHELL_DRAWER_WIDTH`
 - `MINIMUM_SHELL_DRAWER_WIDTH`
-- `SHELL_DRAWER_LABEL_END_GAP`
 - `normalizeShellDrawerWidth(value, fallback = DEFAULT_SHELL_DRAWER_WIDTH)`
+- `normalizeShellNavigationItemSpacing(value, fallback = DEFAULT_SHELL_NAVIGATION_ITEM_SPACING)`
 - `normalizeShellRailWidth(value, fallback = DEFAULT_SHELL_RAIL_WIDTH)`
-- `resolveContentAwareDrawerWidth(measurements = [], { endGap = SHELL_DRAWER_LABEL_END_GAP, minimum = MINIMUM_SHELL_DRAWER_WIDTH, maximum = MAXIMUM_SHELL_DRAWER_WIDTH, fallback = DEFAULT_SHELL_DRAWER_WIDTH } = {})`
+- `resolveContentAwareDrawerWidth(measurements = [], { endGap = DEFAULT_SHELL_NAVIGATION_ITEM_SPACING, minimum = MINIMUM_SHELL_DRAWER_WIDTH, maximum = MAXIMUM_SHELL_DRAWER_WIDTH, fallback = DEFAULT_SHELL_DRAWER_WIDTH } = {})`
 Local functions
 - `clampNumber(value, minimum, maximum)`
 

package/skills/jskit/references/ui-operations.md

@@ -41,16 +41,18 @@ Doctor must continue to report a missing managed test.
 
 ## Adaptive shell drawer
 
-Use Vuetify Material navigation. Compact close dismisses the temporary drawer.
-Wider layouts default to `desktopDrawerClosedMode="rail"`, retaining primary
-navigation as a rail. Use `desktopDrawerClosedMode="hidden"` only when another
-discoverable navigation affordance exists. Do not create a second drawer/menu
-registry or imitate the rail with CSS.
-
-The open drawer tracks its widest visible label plus about 10px. The 80px
-desktop rail centres complete 48px targets and opaque theme-owned tooltips.
-Set `ShellLayout` `drawerWidth` or `railWidth` only for a fixed product width;
-the app wrapper forwards both. Never override `.v-navigation-drawer` in an app.
+Use Vuetify Material navigation. Compact close dismisses the temporary drawer;
+wide layouts default to `desktopDrawerClosedMode="rail"`. Use `hidden` only
+with another navigation affordance.
+
+The drawer omits the app bar's surface label. Open and rail icons share a
+centreline. It uses a 12px outer item inset; `navigationItemSpacing` (12px)
+controls icon/label and label/end gaps. The 80px rail centres 48px targets; set
+`railWidth` (for example, `64`) for a denser rail or `drawerWidth` for a fixed
+drawer. The wrapper forwards these props; never override its CSS.
+
+Existing apps: commit work and run `npm run jskit:update`. Keep and adapt
+the app-owned shell wrapper and smoke test; do not copy or delete them.
 
 ## Browser verification