docs(ui-web): fix 6 stale comments after refactoring

diff --git a/ui/web/src/shared/composables/useAsyncAction.ts b/ui/web/src/shared/composables/useAsyncAction.ts
index 1b40bb1b9e671dc21a5e8807d8a2116570054a7e..12398a495f4dba1928556f61449f2bdadded55c8 100644 (file)
--- a/ui/web/src/shared/composables/useAsyncAction.ts
+++ b/ui/web/src/shared/composables/useAsyncAction.ts
@@ -9,7 +9,7 @@ import { useToast } from 'vue-toast-notification'
  * Creates a reactive pending-state map and a run() helper for async actions with toast notifications.
  *
  * Encapsulates the pending-key guard, toast feedback, and error logging pattern
- * shared by modern skin components.
+ * shared across layout composables.
  * @param initialPending - Object defining the pending keys (e.g. `{ connection: false, startStop: false }`)
  * @param onRefresh - Called after each successful action (e.g. `() => emit('need-refresh')`)
  * @returns `{ pending, run }` — reactive pending map and action executor

diff --git a/ui/web/src/shared/composables/useConnectorActions.ts b/ui/web/src/shared/composables/useConnectorActions.ts
index ccf8ffce35a3678274099553d34edff8157232bf..64570b93464608669bbe57460ea8ae34481a0344 100644 (file)
--- a/ui/web/src/shared/composables/useConnectorActions.ts
+++ b/ui/web/src/shared/composables/useConnectorActions.ts
@@ -62,6 +62,7 @@ export function useConnectorActions (deps: ConnectorActionsDeps): {
   }
 
   const lockConnector = (): void => {
+    // 'lock' key is shared by lockConnector and unlockConnector
     run('lock', {
       action: () => $uiClient.lockConnector(hashId.value, connectorId.value),
       errorMsg: 'Error locking connector',

diff --git a/ui/web/src/shared/composables/useLayoutData.ts b/ui/web/src/shared/composables/useLayoutData.ts
index f2df9c70d29667dad81fd856c22508b11b0c2a35..dca3b8a7386f702a0c6e4a2faa3426611d3d01bb 100644 (file)
--- a/ui/web/src/shared/composables/useLayoutData.ts
+++ b/ui/web/src/shared/composables/useLayoutData.ts
@@ -40,7 +40,8 @@ export interface LayoutData {
 /**
  * Extracts the common data-fetching and WebSocket lifecycle logic shared by layout components.
  *
- * Registers `onMounted` / `onUnmounted` hooks internally so consumers do not need to.
+ * Registers `onMounted` / `onUnmounted` hooks internally. Also exposes
+ * `registerWSEventListeners` / `unregisterWSEventListeners` for manual lifecycle management.
  * @returns Layout data state and control functions
  */
 export function useLayoutData (): LayoutData {

diff --git a/ui/web/src/shared/composables/useSkin.ts b/ui/web/src/shared/composables/useSkin.ts
index 000ecad38d32cbd189f56f64c757d2f6904d7cab..0d8a9f0d48bfee172bebe5de91c4557d953520c1 100644 (file)
--- a/ui/web/src/shared/composables/useSkin.ts
+++ b/ui/web/src/shared/composables/useSkin.ts
@@ -30,7 +30,7 @@ const activeSkinId: Ref<SkinName> = ref(
     return isValidSkin(stored) ? stored : DEFAULT_SKIN
   })()
 )
-// JS/testing hook — no CSS uses [data-skin]; skin isolation is via component class scoping.
+// Sets data-skin on document root for CSS scoping (used by modern skin) and JS/testing hooks.
 if (typeof document !== 'undefined') {
   document.documentElement.setAttribute('data-skin', activeSkinId.value)
 }

diff --git a/ui/web/src/shared/tokens/contract.ts b/ui/web/src/shared/tokens/contract.ts
index 822e456135694aee256dbc80d8358eb114c534ef..b0f5f426808943dd2317aa2d8f3a61827a7b8b36 100644 (file)
--- a/ui/web/src/shared/tokens/contract.ts
+++ b/ui/web/src/shared/tokens/contract.ts
@@ -1,8 +1,8 @@
 /**
  * CSS token contract.
  *
- * Typography and spacing tokens are provided by `base.css` (shared across all themes).
- * Color tokens (`color-*`) and `color-scheme` must be defined per theme file.
+ * Typography and spacing tokens have defaults in `base.css` and may be overridden per theme.
+ * Color tokens (`color-*`) have no defaults and MUST be defined per theme file.
  * When adding a new theme, ensure all `color-*` tokens below are defined in your theme CSS.
  *
  * Every theme file MUST define a value for each token (as `--{token-name}`).

diff --git a/ui/web/src/skins/modern/modern.css b/ui/web/src/skins/modern/modern.css
index 7fa6eb6f700d729d9b46ca376f7b54b17b56b3de..0e548d7eb24d6811eb569eeae2bcf09633ff1e31 100644 (file)
--- a/ui/web/src/skins/modern/modern.css
+++ b/ui/web/src/skins/modern/modern.css
@@ -1,7 +1,7 @@
 /* Modern skin styles.
  *
  * Flat, modern design with Material-inspired structural patterns.
- * - Teal primary (Material 500/400) + Green / Amber / Red state colours
+ * - Primary and state colours driven by the active theme contract
  * - Onest across the UI; mono only for the supervision URL itself
  * - Elevation tiers: base < card body < raised (header/modal) + sunken inserts
  * - Hovers only touch colour / shadow, never layout

diff --git a/ui/web/src/skins/registry.ts b/ui/web/src/skins/registry.ts
index ee36d43391a0a69632c2d18840d717ec3cc005f7..032a6f83c1a5bc8daf17970c9fac591fbb990866 100644 (file)
--- a/ui/web/src/skins/registry.ts
+++ b/ui/web/src/skins/registry.ts
@@ -4,8 +4,8 @@
  * Single source of truth for available skins.
  * Each skin carries metadata and a lazy CSS loader for code splitting.
  *
- * Convention: All skin CSS MUST scope rules to `html[data-skin='<id>']` to prevent
- * style bleeding when multiple skin stylesheets are loaded in the DOM simultaneously.
+ * Convention: Skin CSS should scope structural rules to `html[data-skin='<id>']` or use
+ * component-scoped class prefixes (e.g. `.classic-*`, `.modern-*`) to prevent style bleeding.
  */
 
 import type { Component } from 'vue'