@retailcrm/embed-ui-v1-components 0.9.24 → 0.9.26

package/AGENTS.md

@@ -70,6 +70,7 @@ Commonly used exports from `remote` include:
 - Prefer package public exports over reimplementing CRM-styled controls manually.
 - Match component choice to semantics:
   use `UiField` for labeled form controls, `UiAlert` for state messages, `UiPageHeader` for page-level headings.
+- When a component uses only the default slot, prefer the `v-slot` directive on the component instead of `<template #default>`.
 - For widget targets, keep inline UI compact: prefer `UiToolbarButton`, `UiToolbarLink`, short text, and icons.
 - Move complex widget UI into `UiModalSidebar` or `UiModalWindow` instead of expanding the target slot.
 - Keep imports on the public package boundary.

package/README.md

@@ -68,3 +68,12 @@ npx @retailcrm/embed-ui-v1-components init-agents
 Если `AGENTS.md` уже существует, команда допишет в конец инструкции для
 `@retailcrm/embed-ui-v1-components`, если такого блока там еще нет. С `--force`
 можно обновить уже существующий блок пакета.
+
+Для project-level skills можно создать `.agents/skills/embed-ui-v1-components-ui/SKILL.md`:
+
+```bash
+npx @retailcrm/embed-ui-v1-components init-skills
+```
+
+Skill описывает повторяемый workflow для выбора page pattern, чтения профилей компонентов,
+проверки styling constraints и ревью table pagination/form/widget composition.

package/bin/embed-ui-v1-components.mjs

@@ -10,9 +10,12 @@ const DEFAULT_NEWLINE = '\n'
 const AGENTS_SECTION_HEADER = '## @retailcrm/embed-ui-v1-components'
 const AGENTS_SECTION_START = '<!-- embed-ui-agents:start -->'
 const AGENTS_SECTION_END = '<!-- embed-ui-agents:end -->'
+const SKILL_NAME = 'embed-ui-v1-components-ui'
+const SKILL_TEMPLATE_PATH = `templates/skills/${SKILL_NAME}/SKILL.md.txt`
 
 const HELP_TEXT = `Usage:
   npx ${PACKAGE_NAME} init-agents [target] [options]
+  npx ${PACKAGE_NAME} init-skills [target] [options]
 
 Options:
   -f, --force           Replace existing package section in AGENTS.md
@@ -20,6 +23,7 @@ Options:
 
 Examples:
   npx ${PACKAGE_NAME} init-agents
+  npx ${PACKAGE_NAME} init-skills
   npx ${PACKAGE_NAME} init-agents ./my-project
   npx ${PACKAGE_NAME} init-agents --force
 `
@@ -250,6 +254,14 @@ ${AGENTS_SECTION_END}
 `
 }
 
+const createSkill = (target, packageDocsPath) => {
+  const packageRoot = getCurrentPackageRoot() ?? findPackageRoot(target)
+  const templatePath = path.join(packageRoot, SKILL_TEMPLATE_PATH)
+  const template = fs.readFileSync(templatePath, 'utf8')
+
+  return template.replaceAll('__PACKAGE_DOCS_PATH__', packageDocsPath)
+}
+
 const findMarkedSectionRange = (content) => {
   const start = content.indexOf(AGENTS_SECTION_START)
   const end = content.indexOf(AGENTS_SECTION_END, start + AGENTS_SECTION_START.length)
@@ -381,15 +393,52 @@ const initAgents = (target, force) => {
   console.log(`The ${PACKAGE_NAME} instructions were appended to the end of the file.`)
 }
 
+const initSkills = (target, force) => {
+  if (!fs.existsSync(target)) {
+    throw new Error(`Target path does not exist: ${target}`)
+  }
+
+  const stat = fs.statSync(target)
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Target path is not a directory: ${target}`)
+  }
+
+  const packageDocsPath = createPackageDocsPath(target)
+  const skillPath = path.join(target, '.agents', 'skills', SKILL_NAME, 'SKILL.md')
+  const fileExists = fs.existsSync(skillPath)
+
+  if (fileExists && !force) {
+    console.log(`${skillPath} already exists`)
+    console.log('Nothing was changed. Re-run with --force to refresh that skill.')
+    return
+  }
+
+  if (!fs.existsSync(path.dirname(skillPath))) {
+    fs.mkdirSync(path.dirname(skillPath), { recursive: true })
+  }
+
+  fs.writeFileSync(skillPath, createSkill(target, packageDocsPath), 'utf8')
+
+  const action = fileExists ? 'updated' : 'created'
+  console.log(`SKILL: ${action} ${skillPath}`)
+}
+
 const main = () => {
   try {
     const options = parseArgs(process.argv.slice(2))
 
-    if (options.command !== 'init-agents') {
-      throw new Error(`Unknown command: ${options.command}`)
+    if (options.command === 'init-agents') {
+      initAgents(options.target, options.force)
+      return
+    }
+
+    if (options.command === 'init-skills') {
+      initSkills(options.target, options.force)
+      return
     }
 
-    initAgents(options.target, options.force)
+    throw new Error(`Unknown command: ${options.command}`)
   } catch (error) {
     console.error(error instanceof Error ? error.message : String(error))
     console.error('')

package/bin/postinstall.mjs

@@ -33,6 +33,9 @@ console.log(`[${PACKAGE_NAME}] Component profiles live in docs/profiles/componen
 if (!hasAgentsFile) {
   console.log(`[${PACKAGE_NAME}] To scaffold AGENTS.md for this project, run:`)
   console.log(`  npx ${PACKAGE_NAME} init-agents`)
+  console.log(`[${PACKAGE_NAME}] To install project-level skills, run:`)
+  console.log(`  npx ${PACKAGE_NAME} init-skills`)
 } else {
   console.log(`[${PACKAGE_NAME}] AGENTS.md already exists in this project, so no scaffold was created automatically`)
+  console.log(`[${PACKAGE_NAME}] Project-level skills can be installed with: npx ${PACKAGE_NAME} init-skills`)
 }

package/docs/AI.md

@@ -63,10 +63,13 @@ When building a basic form or settings screen, start from patterns like:
 ```ts
 import {
   UiButton,
+  UiCheckbox,
   UiField,
+  UiNumberStepper,
   UiPageFooter,
   UiPageHeader,
   UiSelect,
+  UiSwitch,
   UiTextbox,
 } from '@retailcrm/embed-ui-v1-components/remote'
 ```
@@ -75,6 +78,9 @@ Typical compositions:
 
 - `UiField` + `UiTextbox`
 - `UiField` + `UiSelect`
+- `UiField` + `UiNumberStepper`
+- `UiSwitch` + visible label + hint row
+- `UiCheckbox` + visible label row or checkbox group
 - `UiPageHeader` + `UiButton`
 - `UiSelect` + `UiSelectOption`
 
@@ -91,13 +97,20 @@ Default screen rules:
 - use `UiPageFooter` for page-level save/cancel/delete actions instead of recreating a local footer;
 - use one `Success Primary` button for the strongest save/apply/create action that commits a result; use `Default Primary`
   only for another important action with a different meaning;
+- use `Secondary` buttons for real neighboring commands that should still look like buttons;
+- use `Tertiary` buttons for lower-emphasis edit, open, configure, cancel, close, and optional commands near headers,
+  cards, tables, and inline content;
+- apply the 24px top and 32px side/bottom padding rule to white content surfaces, not to the page root wrapper;
 - keep filters and controls near the content they affect;
-- use `UiField` around labeled form controls;
+- use `UiField` around labeled textbox, select, number, date, and time controls;
 - use `UiTable` for structured result lists;
 - use `UiLink` for navigation and inline links, `UiButton` for commands;
 - use `UiLoader` with `overlay: true` when loading should dim the covered page or module content;
 - keep public imports on `@retailcrm/embed-ui-v1-components/remote`;
+- when a component uses only the default slot, prefer `v-slot` on the component instead of `<template #default>`;
 - avoid custom markup that recreates textbox, select, button, link, or table chrome.
+- before passing enum-like prop values, check the component profile or public type; omit optional props instead of
+  inventing neutral values such as `"none"` when they are not listed.
 
 ## Default Recommendation For Table Screens
 
@@ -105,6 +118,8 @@ When building a registry, catalog, journal, search result, order list, customer
 screen where users scan and refine datasets:
 
 - put search and filters directly above `UiTable`;
+- do not wrap `UiTable` in an extra white card or padded content surface;
+- use a plain layout or scroll wrapper around `UiTable` only when width or overflow control is needed;
 - use `UiTextbox` for free-text search and `UiSelect` or compact toggle controls for finite filters;
 - keep filters, sorting, page, and page size in GET query parameters when the host app has routing;
 - hydrate initial filter and pagination state from the current query;
@@ -116,7 +131,9 @@ screen where users scan and refine datasets:
 - use chevron icon assets for table footer previous/next controls instead of text glyphs;
 - add local CSS for table footer layout and states; use [`UiTable.yml`](./profiles/components/UiTable.yml)
   for the reference table footer example;
-- set `size="small"` on `UiLink` inside table cells so links match table body typography.
+- set `size="small"` on `UiLink` inside table cells so links match table body typography;
+- prefer icon-only row action buttons inside dense table rows; keep the same action text in
+  `aria-label` and `UiTooltip`.
 
 Suggested query names:
 
@@ -125,6 +142,28 @@ Suggested query names:
 - `sort` and `direction` for sorting;
 - `page` and `pageSize` for pagination.
 
+## Default Recommendation For Forms
+
+When building forms with remote controls:
+
+- use `v-model:value` for value-bearing controls such as `UiTextbox`, `UiSelect`, `UiNumberStepper`,
+  and `UiSwitch`;
+- if a field looks filled but backend validation receives an empty value, check the Network payload
+  before changing the component binding;
+- use `UiField` for labeled text, select, date, and number controls;
+- forward `UiField` slot props into the actual child control when it accepts `id`, especially
+  `UiTextbox`, `UiSelect`, and `UiNumberStepper`;
+- put validation errors inside the relevant field composition, not as unrelated sibling blocks;
+- when a component uses only the default slot, prefer `v-slot` on the component instead of
+  `<template #default>`;
+- do not wrap `UiSwitch` in `UiField`; place the switch next to a visible label and optional hint,
+  and connect `UiSwitch :id` with `label :for`.
+- do not wrap simple `UiCheckbox` rows in `UiField`; place the checkbox next to a visible label and optional hint.
+- use `UiSwitch` for compact immediate boolean settings, feature toggles, and enable/disable flags.
+- use `UiCheckbox` for checkbox groups, table row selection, "select all", acknowledgements, and checkbox-shaped choices.
+- use `UiNumberStepper` for bounded numeric settings, quantities, durations, limits, and values with meaningful increments.
+- use `UiTextbox` for numeric-looking text such as phone numbers, codes, identifiers, and free-form numeric strings.
+
 ## Default Recommendation For Widgets
 
 When building a widget mounted into a CRM target, keep the inline target UI compact and predictable:

package/docs/FORMAT.md

@@ -242,6 +242,7 @@ A short list of rules specifically for code generation:
 - Use short, concrete statements instead of vague praise.
 - Use the exact names of props, emits, and slots.
 - For slots, describe not only the name, but also what the slot does and which content restrictions exist.
+- In examples with only a default slot, prefer `v-slot` on the component instead of `<template #default>`.
 - For styling, distinguish between safe CSS variables and descriptive class names.
 - Keep runnable examples in YAML profiles when they clarify safe public usage.
 - Do not mix "how the component looks right now" with "what is publicly guaranteed".

package/docs/STYLING.md

@@ -77,6 +77,13 @@ Base font family:
 
 - `-apple-system, BlinkMacSystemFont, "Segoe UI", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", "Roboto", sans-serif`
 
+Extension UI should normally not set `font-family` in local styles. Let the CRM host and Embed UI
+components inherit the shared stack.
+
+If a local style must set `font-family`, use the shared stack above exactly. Do not replace it with
+Arial, Inter, Roboto-only, or another custom stack unless the task or project `AGENTS.md` records a
+project-specific design requirement.
+
 Main sizes:
 
 - `h1`: `40px / 44px`
@@ -125,6 +132,21 @@ Profiles split CSS variables into practical groups:
 - `internal_layout_variables`
   useful for reasoning and debugging, but not recommended as external override points.
 
+## State Styling
+
+Interactive states should come from the component implementation, documented props, and documented
+CSS variables.
+
+For controls such as `UiSelect`, `UiTextbox`, and buttons:
+
+- do not add custom selected, active, focused, pressed, or invalid outlines/borders just because a
+  state is visible in Figma or CRM;
+- first check the component profile for the exact root/state classes, zones, CSS variables, and
+  notes about safe overrides;
+- use documented variables or local wrapper styles only when the profile says that pattern is safe;
+- if design review asks for a state that the profile does not document, treat it as a project-specific
+  requirement and record that requirement before changing CSS.
+
 ## Typical Safe Strategy
 
 For style-sensitive generation:
@@ -132,7 +154,43 @@ For style-sensitive generation:
 1. choose the correct component and size prop first;
 2. use documented slots to create the right visual zones;
 3. use documented CSS variables if a theme override is needed;
-4. avoid relying on internal descendant selectors unless the profile says that is safe.
+4. avoid relying on internal descendant selectors unless the profile says that is safe;
+5. state which styling source is being followed when the change was requested by design feedback.
+
+## Remote Page Styles
+
+For Vue remote pages and page-like components, prefer local CSS Modules:
+
+```vue
+<style module lang="less">
+```
+
+Apply classes through `$style[...]` in the template. Use `@import (reference)` from
+`@retailcrm/embed-ui-v1-components/assets/stylesheets/*` for shared LESS tokens and typography
+mixins.
+
+Remote page styles should normally:
+
+- use package spacing, palette, geometry, and typography tokens instead of local hardcoded colors,
+  font sizes, weights, and spacing;
+- keep styles local to the page or component through CSS Modules;
+- avoid shared global files such as `admin.less` as the default strategy;
+- avoid duplicating CRM host layout padding on the page root;
+- put documented 24px top and 32px side/bottom padding on white content surfaces when such a
+  surface exists.
+
+## Design Feedback Triage
+
+When design feedback does not match the current implementation, resolve the source before editing:
+
+1. check public RetailCRM docs, local package docs, the component profile, the page profile, this
+   `STYLING.md`, Figma, and CRM computed styles when available;
+2. if Embed UI docs describe the rule, follow the documented rule or update the component profile
+   before relying on source-code internals;
+3. if Embed UI docs do not describe the requested rule, treat it as a project-specific design
+   requirement;
+4. record project-specific values in the task text or project `AGENTS.md`;
+5. when sources conflict, state the chosen source before changing markup or CSS.
 
 ## How To Mention Styles In Profiles
 

package/docs/profiles/components/UiAvatar.yml

@@ -16,7 +16,6 @@ examples:
           name="Anna Smith"
           src="https://example.com/avatar.jpg"
           size="sm"
-          status="none"
         />
       </template>
 
@@ -37,7 +36,17 @@ api:
     - name: src
     - name: name
     - name: status
+      values:
+        - busy
+        - break
+        - dinner
+        - free
+      notes: Omit status when no indicator should be shown; do not pass "none".
     - name: size
+      values:
+        - xs
+        - sm
+        - lg
     - name: href
 
 rendered_structure:
@@ -61,8 +70,10 @@ ai_notes:
   do:
     - Use UiAvatar for identity display, not for general media.
     - Provide name whenever possible so fallback identity stays meaningful.
+    - Omit optional enum-like props when no listed value applies.
   avoid:
     - Do not use it for generic content images or large media blocks.
+    - Do not pass unsupported neutral values such as status="none"; check listed values first.
 
 composition:
   works_well_with:

package/docs/profiles/components/UiButton.yml

@@ -211,6 +211,8 @@ behavior:
       notes: Enables the separate locked state.
   notes:
     - If href is present, the component becomes a link-shaped action.
+    - appearance="secondary" is for neighboring commands that should still read as real buttons.
+    - appearance="tertiary" is for lower-emphasis actions near headers, cards, tables, and inline content.
 
 accessibility:
   notes:
@@ -231,7 +233,9 @@ ai_notes:
     - Start with appearance=primary for the main CTA, then choose variant by meaning.
     - Use variant="success" for the strongest create/save/apply action when it commits a result, and keep only one Success Primary on a page.
     - Use the default variant for an important primary action that is not the strongest commit action.
-    - Use secondary or tertiary for neighboring actions near titles.
+    - Use secondary for a real neighboring command that should still look like a button.
+    - Use tertiary for lower-emphasis edit, open, configure, cancel, close, and optional commands that should not compete with the main flow.
   avoid:
     - Do not replace UiButton with UiLink when the action should read as a button.
     - Do not use UiButton for regular inline text navigation.
+    - Do not default every non-primary action to secondary; choose tertiary when the action is only supportive.

package/docs/profiles/components/UiCheckbox.yml

@@ -1,7 +1,7 @@
 component: UiCheckbox
 summary: >
-  UiCheckbox is a boolean or set-membership control. It supports single boolean-like usage
-  as well as model-plus-value patterns for checkbox groups.
+  UiCheckbox is a checkbox or set-membership control. It supports single acknowledgement-like
+  choices, table row selection, "select all" states, and model-plus-value patterns for checkbox groups.
 
 public_import:
   from: '@retailcrm/embed-ui-v1-components/remote'
@@ -37,12 +37,14 @@ examples:
       const channels = ref<string[]>([])
       </script>
 use_when:
-  - You need a yes or no control.
+  - You need a checkbox-shaped boolean choice such as an acknowledgement or confirmation.
   - You need one value inside a checkbox group model.
+  - You need row selection, mass selection, or an indeterminate "select all" control.
 
 avoid_when:
   - You need exclusive single choice, use UiRadio instead.
-  - You need a more compact toggle-like control, use UiSwitch instead.
+  - You need a compact immediate on or off setting, use UiSwitch instead.
+  - You need a settings toggle row where a switch better communicates enable or disable state.
 
 api:
   key_props:
@@ -73,26 +75,32 @@ behavior:
   notes:
     - model plus value supports group-style selection.
     - indeterminate is useful for partial selection states.
+    - For ordinary settings toggles, UiSwitch is usually the better control even when the value is boolean.
 
 ai_notes:
   do:
-    - Use for boolean choice or checkbox-group membership.
+    - Use for checkbox-group membership, acknowledgement-like boolean choices, and table row selection.
     - Use indeterminate for parent selection such as "select all visible rows".
   avoid:
     - Do not use for mutually exclusive options.
+    - Do not replace UiSwitch settings toggles with UiCheckbox just because the value is boolean.
 
 composition:
   works_well_with:
-    - UiField
+    - visible label
+    - hint text
     - UiTable
     - UiTableColumn
   patterns:
-    - title: Form boolean
-      notes: Wrap in UiField when the checkbox needs a persistent label, hint, or validation text.
+    - title: Checkbox row
+      notes: Place UiCheckbox on the left, label and optional hint on the right, similar to a UiSwitch settings row.
+    - title: Checkbox group
+      notes: Use several UiCheckbox controls with one array model and visible labels for multi-selection.
     - title: Table row selection
       notes: Use in the first narrow UiTableColumn for row selection; use indeterminate in the header checkbox for partial selection.
   avoid:
     - Do not use as a visual switch replacement when the action is an immediate on or off setting.
+    - Do not wrap simple checkbox rows in UiField; use an explicit row with visible label and optional hint.
 
 accessibility:
   notes:

package/docs/profiles/components/UiField.yml

@@ -12,23 +12,21 @@ public_import:
 related_components:
   - UiTextbox
   - UiSelect
-  - UiCheckbox
+  - UiNumberStepper
   - UiDatePicker
 
 examples:
   - title: Basic usage
     code: |
       <template>
-          <UiField id="name-field" label="Name" hint="At least 3 characters">
-              <template #default="field">
-                  <UiTextbox
-                      :id="field.id"
-                      :input-attributes="{
-                          'aria-labelledby': field.ariaLabelledby,
-                          'aria-invalid': field.ariaInvalid,
-                      }"
-                  />
-              </template>
+          <UiField v-slot="field" id="name-field" label="Name" hint="At least 3 characters">
+              <UiTextbox
+                  :id="field.id"
+                  :input-attributes="{
+                      'aria-labelledby': field.ariaLabelledby,
+                      'aria-invalid': field.ariaInvalid,
+                  }"
+              />
           </UiField>
       </template>
 
@@ -61,6 +59,56 @@ examples:
       <script lang="ts" setup>
       import { UiField, UiTextbox } from '@retailcrm/embed-ui-v1-components/remote'
       </script>
+  - title: Select inside a field
+    code: |
+      <template>
+          <UiField v-slot="field" id="manager-field" label="Manager">
+              <UiSelect
+                  :id="field.id"
+                  v-model:value="manager"
+                  :invalid="field.ariaInvalid === 'true'"
+                  placeholder="Select manager"
+              >
+                  <UiSelectOption value="anna" label="Anna Smith" />
+                  <UiSelectOption value="ilya" label="Ilya Johnson" />
+              </UiSelect>
+          </UiField>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+
+      import {
+        UiField,
+        UiSelect,
+        UiSelectOption,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const manager = ref<string | null>(null)
+      </script>
+  - title: Number stepper inside a field
+    code: |
+      <template>
+          <UiField v-slot="field" id="duration-field" label="Duration, minutes">
+              <UiNumberStepper
+                  :id="field.id"
+                  v-model:value="duration"
+                  :min="0"
+                  :step="15"
+              />
+          </UiField>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+
+      import {
+        UiField,
+        UiNumberStepper,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const duration = ref(30)
+      </script>
 use_when:
   - You need a labeled form control with consistent field semantics.
   - You need to pass id, aria-labelledby, and aria-invalid into an inner control.
@@ -109,9 +157,12 @@ api:
           - one form control
           - UiTextbox
           - UiSelect
+          - UiNumberStepper
           - UiDatePicker
         avoid:
           - several unrelated controls
+          - UiSwitch setting rows
+          - UiCheckbox setting rows
           - decorative layout only
           - raw content without using slot props
       layout_effect: The control sits below the headline and inherits field-level semantics through slot props.
@@ -248,6 +299,7 @@ composition:
   works_well_with:
     - UiTextbox
     - UiSelect
+    - UiNumberStepper
     - UiDatePicker
     - UiTimePicker
   patterns:
@@ -258,7 +310,12 @@ composition:
 ai_notes:
   do:
     - Forward slot props into the actual control in most form scenarios.
-    - Use UiField as a semantic wrapper for a single control.
+    - Pass field.id to child controls that accept id, including UiTextbox, UiSelect, and UiNumberStepper.
+    - Use v-slot on UiField when the field uses only the default slot.
+    - Use UiField as a semantic wrapper for a single textbox, select, number, date, or time control.
+    - Place validation errors inside the relevant field composition instead of rendering them as unrelated sibling blocks.
   avoid:
     - Do not use UiField as a generic visual container without control semantics.
+    - Do not use UiField for UiSwitch settings rows; pair UiSwitch with a visible label and hint text instead.
+    - Do not use UiField for simple UiCheckbox rows; pair UiCheckbox with a visible label and optional hint instead.
     - Do not ignore id and ariaLabelledby when accessibility matters.

package/docs/profiles/components/UiModalSidebar.yml

@@ -44,18 +44,30 @@ examples:
                               </div>
 
                               <template #footer>
-                                  <UiButton @click="modalSidebarInner = false">
-                                      Close
-                                  </UiButton>
+                                  <div style="display: flex; align-items: center; gap: 12px;">
+                                      <UiButton @click="modalSidebarInner = false">
+                                          Save
+                                      </UiButton>
+
+                                      <UiButton appearance="secondary" @click="modalSidebarInner = false">
+                                          Close
+                                      </UiButton>
+                                  </div>
                               </template>
                           </UiModalSidebar>
                       </div>
                   </div>
 
                   <template v-if="footer" #footer>
-                      <UiButton @click="open = false">
-                          Close
-                      </UiButton>
+                      <div style="display: flex; align-items: center; gap: 12px;">
+                          <UiButton @click="open = false">
+                              Save
+                          </UiButton>
+
+                          <UiButton appearance="secondary" @click="open = false">
+                              Close
+                          </UiButton>
+                      </div>
                   </template>
               </UiModalSidebar>
           </div>
@@ -125,6 +137,9 @@ ai_notes:
   do:
     - Use UiModalSidebar when page context should stay visually connected to the modal content.
     - Use for inspect, edit, or secondary workflows that relate to the current list or page.
+    - Group several footer buttons in flex rows; 12px and 16px are the common gaps inside a group.
+    - Footer actions may be split into left and right groups when their meanings differ.
+    - Put destructive icon-only actions on the right and confirm them with UiPopconfirm okVariant="danger"; the confirmation button is primary by default.
   avoid:
     - Do not use for short confirmations; use UiModalWindow.
 
@@ -133,6 +148,7 @@ composition:
     - UiTable
     - UiField
     - UiButton
+    - UiPopconfirm
   patterns:
     - title: Row detail side panel
       notes: Open from a table row when the user should keep list context visible.

package/docs/profiles/components/UiNumberStepper.yml

@@ -28,9 +28,11 @@ examples:
 use_when:
   - You need numeric input with explicit step controls.
   - You need range constraints and nullable numeric state.
+  - You need bounded numeric settings, quantities, durations, limits, delays, or values with meaningful increments.
 
 avoid_when:
   - You need plain text or decimal input without stepper controls.
+  - You need numeric-looking text such as phone numbers, codes, identifiers, or free-form strings.
 
 api:
   key_props:
@@ -82,6 +84,7 @@ ai_notes:
     - Prefer nullable when clearing the value is a valid state.
   avoid:
     - Do not use when the value is an identifier, phone, code, or other numeric-looking text.
+    - Do not replace with UiTextbox for bounded numeric settings unless a runtime limitation is documented.
 
 accessibility:
   notes:

package/docs/profiles/components/UiSelect.yml

@@ -312,6 +312,10 @@ styling:
     - The trigger reuses the textbox visual model.
     - The dropdown reuses popper variables for padding, radius, and floating surface geometry.
     - Classes are descriptive implementation hooks, not a stable external styling contract.
+    - Selected, active, focused, pressed, invalid, and disabled states should come from UiSelect and
+      UiSelectOption implementation styles or documented CSS variables.
+    - Do not add custom outlines or borders for selected options unless the task records a
+      project-specific design requirement.
   root_classes:
     - .ui-v1-select
     - .ui-v1-select__trigger
@@ -375,6 +379,8 @@ behavior:
     - In multiple mode values are toggled inside the array model.
     - Filtering matches option labels and descriptions.
     - If nothing matches, a no-result block is shown.
+    - Selected option styling is owned by the select option implementation; do not recreate it with
+      local borders or outline styles.
   keyboard:
     - Arrow keys move the active highlight.
     - Escape closes the dropdown.
@@ -414,3 +420,5 @@ ai_notes:
     - Do not place arbitrary div wrappers inside the option tree.
     - Do not choose UiSelect when free text input is the real need.
     - Do not assume the dropdown lives in normal document flow next to the trigger.
+    - Do not add custom selected-option outlines, borders, or active-state chrome unless a
+      project-specific design requirement explicitly asks for it.

package/docs/profiles/components/UiSelectOption.yml

@@ -70,5 +70,7 @@ styling:
   notes:
     - Use documented props and slots as the primary styling API.
     - Internal .ui-v1-* classes are descriptive implementation details for reasoning and debugging unless a profile marks them as public theme hooks.
+    - Selected, active, focused, pressed, and disabled option states are owned by UiSelect/UiSelectOption implementation styles.
+    - Do not add custom outlines or borders for selected options unless the task records a project-specific design requirement.
   root_classes:
     - .ui-v1-select-option

package/docs/profiles/components/UiSwitch.yml

@@ -58,11 +58,74 @@ examples:
 
       const enabled = ref(false)
       </script>
+  - title: Settings row with label and hint
+    code: |
+      <template>
+        <div class="settings-switch-row">
+          <UiSwitch
+            :id="switchId"
+            v-model:value="enabled"
+          />
+
+          <div class="settings-switch-row__content">
+            <label
+              class="settings-switch-row__label"
+              :for="switchId"
+            >
+              Enable automatic assignment
+            </label>
+
+            <div class="settings-switch-row__hint">
+              New requests will be assigned to available managers.
+            </div>
+          </div>
+        </div>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref, useId } from 'vue'
+
+      import { UiSwitch } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const enabled = ref(false)
+      const switchId = useId()
+      </script>
+
+      <style lang="less" scoped>
+      @import (reference) '@retailcrm/embed-ui-v1-components/assets/stylesheets/layout.less';
+      @import (reference) '@retailcrm/embed-ui-v1-components/assets/stylesheets/palette.less';
+      @import (reference) '@retailcrm/embed-ui-v1-components/assets/stylesheets/typography.less';
+
+      .settings-switch-row {
+        display: flex;
+        align-items: flex-start;
+        gap: 3 * @spacing-unit;
+      }
+
+      .settings-switch-row__content {
+        display: grid;
+        gap: @spacing-xxs;
+        min-width: 0;
+      }
+
+      .settings-switch-row__label {
+        color: @black-500;
+        .text-small-accent();
+      }
+
+      .settings-switch-row__hint {
+        color: @grey-800;
+        .text-small();
+      }
+      </style>
 use_when:
   - You need a compact on or off toggle.
+  - You need an immediate boolean setting, feature flag, enable or disable control, or settings row.
 
 avoid_when:
   - You need checkbox-group semantics.
+  - You need a UiField-style labeled wrapper; pair UiSwitch with a visible label and hint text instead.
+  - You need an acknowledgement, legal confirmation, table selection, or multi-select choice; use UiCheckbox instead.
 
 api:
   key_props:
@@ -93,18 +156,24 @@ behavior:
 
 composition:
   works_well_with:
-    - UiField
+    - visible label
+    - hint text
   patterns:
     - title: Settings row
-      notes: Pair with a visible label and optional description so the on or off state is unambiguous.
+      notes: Place UiSwitch on the left, label and hint on the right, and connect UiSwitch id with label for.
   avoid:
     - Do not use without a nearby label; the switch alone does not explain what will change.
+    - Do not wrap UiSwitch in UiField.
 
 ai_notes:
   do:
     - Use for compact feature toggles and enable or disable settings.
+    - Generate an id, pass it to UiSwitch, and connect the visible label with label for.
+    - Put helper text below the label in the settings row, not in UiField hint.
   avoid:
     - Do not use for multi-select lists or legal acknowledgements; use UiCheckbox.
+    - Do not replace compact settings toggles with UiCheckbox just because the value is boolean.
+    - Do not use UiField around UiSwitch.
 
 accessibility:
   notes:

package/docs/profiles/components/UiTable.yml

@@ -10,13 +10,16 @@ public_import:
 
 related_components:
   - UiAvatar
+  - UiButton
   - UiCheckbox
   - UiLink
+  - UiPopperConnector
   - UiTableColumn
   - UiTableFooterButton
   - UiTableFooterSection
   - UiTableSorter
   - UiTag
+  - UiTooltip
 
 examples:
   - title: Basic table
@@ -64,6 +67,68 @@ examples:
         Sent: '#1FA971',
       }
       </script>
+  - title: Icon-only row action with tooltip
+    notes:
+      - Use narrow action columns for row commands.
+      - Keep the visible control icon-only; put the action text in aria-label and UiTooltip.
+    code: |
+      <template>
+        <UiTable
+          bordered
+          :rows="rows"
+          row-key="id"
+        >
+          <UiTableColumn label="Name">
+            <template #cell="{ row }">
+              {{ row.name }}
+            </template>
+          </UiTableColumn>
+
+          <UiTableColumn :width="48" label="" trim>
+            <template #cell="{ row }">
+              <UiPopperConnector>
+                <UiButton
+                  :aria-label="`Edit ${row.name}`"
+                  appearance="tertiary"
+                  size="sm"
+                  @click="edit(row)"
+                >
+                  <IconEdit aria-hidden="true" />
+                </UiButton>
+
+                <UiTooltip>
+                  Edit {{ row.name }}
+                </UiTooltip>
+              </UiPopperConnector>
+            </template>
+          </UiTableColumn>
+        </UiTable>
+      </template>
+
+      <script lang="ts" setup>
+      import IconEdit from '@retailcrm/embed-ui-v1-components/assets/sprites/ui/edit.svg'
+      import {
+        UiButton,
+        UiPopperConnector,
+        UiTable,
+        UiTableColumn,
+        UiTooltip,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      type Row = {
+        id: number
+        name: string
+      }
+
+      const rows: Row[] = [
+        { id: 101, name: 'Anna Smith' },
+        { id: 102, name: 'Ilya Johnson' },
+      ]
+
+      const edit = (row: Row) => {
+        console.log(row)
+      }
+      </script>
   - title: Expandable rows table
     notes:
       - Use the expand slot and cell toggle helper for expandable row details.
@@ -421,6 +486,7 @@ use_when:
 
 avoid_when:
   - You need a simple list or card layout.
+  - You need content inside a generic white card surface instead of a table.
 
 api:
   key_props:
@@ -491,6 +557,7 @@ geometry:
     - Root fills available width.
     - fixed=true switches table-layout from auto to fixed.
     - bordered=true adds border and corner rounding through CSS variables.
+    - Do not wrap UiTable in an extra white content surface; use a plain layout or scroll wrapper only when needed.
     - Filters and search controls should usually be placed above the table, not in the table root.
     - Table-scoped pagination belongs in footer slots when custom controls are needed.
 
@@ -593,6 +660,12 @@ composition:
       - Add scoped CSS for footer meta height, control-row background, pagination button size, active page state, arrow icon size, and vertical dividers.
       - Persist page and page size in URL query parameters when routing is available.
       - Reset page to 1 when filters or sorting change.
+  actions:
+    notes:
+      - Prefer narrow action columns with icon-only UiButton controls for row commands.
+      - Keep visible button text out of dense table rows; provide aria-label and matching UiTooltip text.
+      - Use package sprite icons and set aria-hidden on the icon itself.
+      - Wrap action buttons and UiTooltip in UiPopperConnector. Add UiPopperTarget only for custom non-component targets.
 
 ai_notes:
   do:
@@ -603,9 +676,12 @@ ai_notes:
     - Compose footer controls with UiTableFooterSection and UiTableFooterButton.
     - Copy the Entity list table footer example when building a realistic entity-list footer.
     - Use UiTableSorter for sortable headers.
+    - Use icon-only row action buttons with aria-label and UiTooltip in action columns.
   avoid:
     - Do not hide table filters in page header actions.
+    - Do not wrap UiTable in an additional white card, panel, or content-surface container.
     - Do not use UiButton inside table footer pagination.
+    - Do not put visible text buttons in dense table action columns.
     - Do not put pagination only in local state when the screen has routable result sets.
     - Do not import table internals from host or src paths.
 

package/docs/profiles/components/UiTextbox.yml

@@ -37,12 +37,14 @@ use_when:
   - You need a standard text input.
   - You need search, email, phone, url, or password input.
   - You need decimal or numeric input without a separate stepper.
+  - You need numeric-looking text such as a phone, code, identifier, article, external id, or free-form numeric string.
   - You need a multiline control in the same visual language.
   - You need an input that composes well with UiField and inline editing.
 
 avoid_when:
   - You need value selection, not free-form input.
   - You need explicit increment and decrement UX.
+  - You need bounded numeric settings, quantities, durations, limits, or values with meaningful increments; use UiNumberStepper instead.
   - You need advanced formatting beyond the prefix or suffix model.
 
 api:

package/docs/profiles/components/UiTooltip.yml

@@ -60,6 +60,7 @@ ai_notes:
   do:
     - Use UiTooltip for tooltip semantics and UiPopper for lower-level floating behavior.
     - Keep tooltip content short and non-essential.
+    - For icon-only controls, keep tooltip text aligned with the control aria-label.
   avoid:
     - Do not put forms, tables, or multi-step interactions in tooltips.
 

package/docs/profiles/pages/CardSettingsPage.yml

@@ -20,7 +20,11 @@ expected_structure:
   - Header actions can be accompanied by text information or status labels.
   - Optional top tabs.
   - Main content sits on a white content surface.
+  - The white content surface owns the 24px top and 32px side/bottom padding.
+  - The page root wrapper should not repeat that padding.
   - Content can include text, buttons, fields, checkboxes, radio groups, switches, and other form controls.
+  - Textbox, select, number, date, and time controls usually live inside UiField.
+  - UiSwitch and simple UiCheckbox rows should use their own row layout with a visible label and optional hint, not UiField.
   - A bottom save panel is optional.
   - If a bottom save panel is used, its main save or apply action should be Success Primary.
 
@@ -53,8 +57,14 @@ recommended_components:
 ai_notes:
   do:
     - Keep form controls grouped by task or semantic section.
-    - Use UiField around labelled form controls.
+    - Use UiField around labeled textbox, select, number, date, and time controls.
+    - Use UiSwitch for compact enable or disable settings.
+    - Use UiCheckbox for checkbox groups, table selection, acknowledgements, and checkbox-shaped boolean choices.
     - Use tabs only when they reduce visible complexity without hiding required work.
     - Keep save/apply as the strongest footer action and move neighboring actions to secondary or tertiary appearances unless their variant has a distinct page-level meaning.
+    - Prefer tertiary for low-emphasis local actions that should not compete with the settings save flow.
   avoid:
     - Do not create a decorative landing page for operational settings.
+    - Do not put content-surface padding on the root page wrapper.
+    - Do not use UiCheckbox as the default replacement for UiSwitch just because a setting is boolean.
+    - Do not wrap UiSwitch or simple UiCheckbox rows in UiField.

package/docs/profiles/pages/EntityListPage.yml

@@ -18,12 +18,16 @@ expected_structure:
   - One or more 48px page buttons on the right side of the header.
   - If there are multiple header buttons, one should be primary and the rest can be secondary or tertiary.
   - The main Default Primary button usually creates a new entity for the list when there is no stronger Success Primary action on the page.
+  - Supporting header actions that should not compete with the create action are usually tertiary rather than secondary.
   - Filters above the table, built from controls such as select, textbox, and combobox-like selection components.
   - Filter controls should run in rows of roughly 4-5 fields, then wrap to the next row.
   - Filters can be collapsible.
   - Filter apply action uses a default secondary 36px text button.
   - Filter reset action uses a danger secondary 36px icon button.
   - Entity data is shown in a table.
+  - UiTable should not be wrapped in an extra white content surface.
+  - A wrapper around UiTable should only handle layout, width, or scrolling, without card chrome or content-surface padding.
+  - Row action columns should use icon-only buttons with aria-label and UiTooltip instead of visible text buttons.
   - The table may scroll and may support export.
 
 recommended_components:
@@ -61,6 +65,11 @@ ai_notes:
     - Keep filters and table controls directly above the table.
     - Persist filters, sorting, page, and page size in query parameters when routing is available.
     - Reset page to 1 when filters or sorting change.
+    - Use narrow icon-only row action columns with matching aria-label and UiTooltip text.
+    - Use tertiary for low-emphasis header or row-adjacent commands when a secondary button would be too visually heavy.
   avoid:
     - Do not hide filters in page header actions.
     - Do not put pagination only in local state when the result set is routable.
+    - Do not place UiTable inside an additional white card or padded content surface.
+    - Do not use visible text buttons for dense table row actions.
+    - Do not make every header action secondary when only one action should draw attention.

package/docs/profiles/pages/ModalSidebar.yml

@@ -44,18 +44,30 @@ examples:
                               </UiButton>
                           </div>
 
-                          <UiButton
-                              aria-label="Delete"
-                              appearance="tertiary"
-                              class="modal-sidebar-footer__delete"
-                              variant="danger"
-                              @click="deleteItem"
-                          >
-                              <IconDelete
-                                  aria-hidden="true"
-                                  class="modal-sidebar-footer__delete-icon"
-                              />
-                          </UiButton>
+                          <div class="modal-sidebar-footer__aside">
+                              <UiPopconfirm
+                                  ok-variant="danger"
+                                  title="Delete item?"
+                                  @ok="deleteItem"
+                              >
+                                  <template #trigger="{ open: popconfirmOpen }">
+                                      <UiButton
+                                          :active="popconfirmOpen"
+                                          aria-label="Delete"
+                                          appearance="tertiary"
+                                          class="modal-sidebar-footer__delete"
+                                          variant="danger"
+                                      >
+                                          <IconDelete
+                                              aria-hidden="true"
+                                              class="modal-sidebar-footer__delete-icon"
+                                          />
+                                      </UiButton>
+                                  </template>
+
+                                  This action cannot be undone.
+                              </UiPopconfirm>
+                          </div>
                       </div>
                   </template>
               </UiModalSidebar>
@@ -69,6 +81,7 @@ examples:
       import {
         UiButton,
         UiModalSidebar,
+        UiPopconfirm,
       } from '@retailcrm/embed-ui-v1-components/remote'
 
       const open = ref(false)
@@ -95,6 +108,12 @@ examples:
       }
 
       .modal-sidebar-footer__main {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+      }
+
+      .modal-sidebar-footer__aside {
         display: flex;
         align-items: center;
         gap: 16px;
@@ -127,6 +146,10 @@ expected_structure:
   - Fixed footer at the bottom.
   - Footer usually contains save, cancel or close, and delete actions.
   - Footer can also contain a copy button or auxiliary text.
+  - Footer actions may be split into left and right groups.
+  - Footer action groups usually use a 12px or 16px gap between neighboring buttons.
+  - Destructive footer actions are often icon-only buttons aligned to the right edge.
+  - Destructive icon-only actions should usually open UiPopconfirm with okVariant="danger"; its confirmation button is primary by default.
   - Content can be flexible, but should stay compact.
   - Small tables can be placed in sidebars.
 
@@ -135,6 +158,8 @@ recommended_components:
     profile: ../components/UiModalSidebar.yml
   - name: UiButton
     profile: ../components/UiButton.yml
+  - name: UiPopconfirm
+    profile: ../components/UiPopconfirm.yml
   - name: UiTag
     profile: ../components/UiTag.yml
   - name: UiField
@@ -151,6 +176,9 @@ ai_notes:
   do:
     - Use for inspect, edit, or secondary workflows related to the current list or page.
     - Keep the flow compact.
+    - Split footer actions into meaningful left and right groups when secondary or destructive actions need separation.
+    - Use 12px or 16px gaps inside each footer action group.
+    - Put destructive icon-only actions on the right and confirm them with UiPopconfirm okVariant="danger"; the confirmation button is primary by default.
   avoid:
     - Do not use for bulky or complex interfaces.
     - Do not use collapse blocks inside sidebars.

package/docs/profiles/pages/MultiColumnPage.yml

@@ -14,6 +14,7 @@ examples_from_design:
 layout_rules:
   - Content is placed on surfaces.
   - The most common surface spans the full screen width.
+  - Surface padding belongs to each content surface, not to the page root wrapper.
   - Semantic blocks can be arranged vertically and horizontally.
   - Distance between blocks is 24px.
   - Allowed width distributions are 100%, 50% / 50%, and 30% / 70%.
@@ -25,3 +26,4 @@ ai_notes:
   avoid:
     - Do not use marketing-style layouts.
     - Do not split content into columns when a single linear form is easier to complete.
+    - Do not duplicate content-surface padding on the page root wrapper.

package/docs/profiles/pages/PageComposition.yml

@@ -22,6 +22,8 @@ shared_rules:
   - Use Default Primary for an important action that is secondary to the Success Primary or does not commit a result.
   - Use Danger Primary only for one critical destructive action when the page needs it.
   - If several actions compete for attention, choose the main one for Success Primary and move the rest to Default Primary, secondary, tertiary, or dropdown actions by meaning.
+  - Use secondary for a real neighboring command that should still read as a button.
+  - Use tertiary for lower-emphasis header, card, inline, configure, edit, open, cancel, and close actions that should not compete with the main flow.
   - UiPageHeader actions and UiPageFooter actions belong to the same page-level action scope.
   - Treat each UiCollapseBox footer as a separate local action scope with the same rules scoped to that section.
   - A page can have several Default Primary buttons when each one belongs to a different UiCollapseBox footer.
@@ -29,6 +31,8 @@ shared_rules:
   - Components inside pages and blocks should be spaced by values divisible by 4px.
   - Common spacing values are 4, 8, 12, 16, 20, 24, 28, and 32px.
   - Content blocks commonly use 32px left, right, and bottom padding and 24px top padding.
+  - The 24px top and 32px side/bottom padding rule belongs to white content surfaces, not to the page root wrapper.
+  - Do not duplicate content-surface padding on the page root; outer page spacing is controlled by the CRM host layout.
   - Prefer public components from @retailcrm/embed-ui-v1-components/remote.
   - Do not invent custom chrome for pages, forms, tables, tabs, buttons, modals, or sidebars when a documented component fits.
 
@@ -58,7 +62,10 @@ ai_notes:
     - Choose ModalWindow or a full page when content needs wide tables, several sections, or complex controls.
     - Keep operational CRM screens dense, scannable, and work-focused.
     - Prefer variant="success" for the main save/apply/create action and keep it visually dominant.
+    - Prefer appearance="tertiary" for supportive actions that sit near content but should stay visually quiet.
   avoid:
     - Do not turn internal CRM work screens into marketing-style layouts.
     - Do not hide filters or primary workflow controls away from the content they affect.
     - Do not place multiple Success Primary, Default Primary, or Danger Primary actions with the same variant in the page-level scope or inside one collapse-box scope.
+    - Do not default every non-primary action to appearance="secondary"; choose by local action importance.
+    - Do not add page-surface padding to both the page root and the white content surface.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@retailcrm/embed-ui-v1-components",
   "bin": "bin/embed-ui-v1-components.mjs",
   "type": "module",
-  "version": "0.9.24",
+  "version": "0.9.26",
   "license": "MIT",
   "author": "RetailDriverLLC <integration@retailcrm.ru>",
   "repository": {
@@ -48,7 +48,8 @@
     "docs",
     "index.cjs",
     "index.js",
-    "README.md"
+    "README.md",
+    "templates"
   ],
   "scripts": {
     "build": "yarn build:host && yarn build:remote",

package/templates/skills/embed-ui-v1-components-ui/SKILL.md.txt

@@ -0,0 +1,53 @@
+---
+name: embed-ui-v1-components-ui
+description: Use when building, editing, or reviewing RetailCRM JS module UI with @retailcrm/embed-ui-v1-components. Covers page pattern selection, component profile lookup, styling constraints, table pagination fidelity, forms, widgets, and visual-review triage.
+---
+
+# Embed UI v1 Components UI
+
+Use this skill before changing frontend UI built with `@retailcrm/embed-ui-v1-components`.
+
+## Reading order
+
+1. Read project `AGENTS.md` if it exists.
+2. Read `__PACKAGE_DOCS_PATH__/AGENTS.md`.
+3. Read `__PACKAGE_DOCS_PATH__/docs/AI.md`.
+4. Read `__PACKAGE_DOCS_PATH__/docs/PROFILES.md`.
+5. Read `__PACKAGE_DOCS_PATH__/docs/STYLING.md` for typography, spacing, CSS variables, and selector boundaries.
+6. Open the relevant component profiles from `__PACKAGE_DOCS_PATH__/docs/profiles/components/*.yml`.
+7. For full screens, overlays, filters, tables, or settings layouts, open the relevant page profile from `__PACKAGE_DOCS_PATH__/docs/profiles/pages/*.yml`.
+
+## Workflow
+
+1. Choose the page pattern before writing code: `EntityListPage`, `CardSettingsPage`, `CollapseBlockPage`, `MultiColumnPage`, `ModalSidebar`, or `ModalWindow`.
+2. List the component profiles you are using.
+3. Use `@retailcrm/embed-ui-v1-components/remote` for extension UI components and `@retailcrm/embed-ui-v1-components/assets/...` for icons.
+4. Do not import from `@retailcrm/embed-ui-v1-components/dist/*`, `@retailcrm/embed-ui-v1-components/host`, source files, or repository-only paths in extension frontend code.
+5. Do not hand-roll buttons, inputs, selects, tables, or links when a documented Embed UI component exists.
+6. Do not set arbitrary `font-family`; inherit the host/component stack unless a project-specific design requirement says otherwise.
+7. Do not style internal `.ui-v1-*` selectors unless the profile or `STYLING.md` explicitly documents that override pattern.
+8. For Vue remote pages, prefer `<style module lang="less">` with `$style[...]` and package LESS tokens/mixins.
+9. Before passing enum-like prop values, check the profile or public type; omit optional props instead of inventing neutral values.
+
+## High-signal checks
+
+- For entity lists, use `UiTable`, `UiTableColumn`, and table footer slots.
+- For table pagination, follow the reference example in `UiTable.yml`: button sizes, active state, dividers, arrow assets, and scoped selector pattern.
+- For form fields, use `UiField` with the matching control and forward slot props such as `id` when the control accepts them.
+- Put validation errors inside the relevant field composition, not as unrelated sibling blocks.
+- For `UiSwitch`, use the documented switch + visible label + hint row instead of wrapping it in `UiField`.
+- For simple `UiCheckbox` rows, use checkbox + visible label + optional hint instead of wrapping it in `UiField`.
+- Use `UiSwitch` for compact boolean settings and `UiCheckbox` for checkbox groups, table row selection, select-all, and acknowledgements.
+- Use `UiNumberStepper` for bounded numeric settings and `UiTextbox` for numeric-looking text such as phones, codes, and identifiers.
+- Use `Secondary` buttons for real neighboring commands and `Tertiary` buttons for lower-emphasis edit/open/configure/cancel/close actions.
+- For widgets mounted into CRM targets, keep inline UI compact; move complex UI into `UiModalSidebar` or `UiModalWindow`.
+- For sidebar footers, group related actions, use 12px or 16px gaps inside groups, and confirm destructive icon-only actions with `UiPopconfirm okVariant="danger"`.
+
+## Design feedback triage
+
+When design feedback does not match the package docs:
+
+1. Check the component profile, page profile, `STYLING.md`, Figma, and CRM computed styles.
+2. If Embed UI docs do not contain the requested rule, treat it as a project-specific design requirement.
+3. State which source wins before editing.
+4. Keep the selected values documented in the task or project `AGENTS.md`.