@retailcrm/embed-ui-v1-components 0.9.23 → 0.9.25

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,72 @@ 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.
 
 avoid_when:
   - You need checkbox-group semantics.
+  - You need a UiField-style labeled wrapper; pair UiSwitch with a visible label and hint text instead.
 
 api:
   key_props:
@@ -93,18 +154,23 @@ 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 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/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,8 +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.
   - A bottom save panel is optional.
+  - If a bottom save panel is used, its main save or apply action should be Success Primary.
 
 recommended_components:
   - name: UiPageHeader
@@ -54,5 +57,7 @@ ai_notes:
     - Keep form controls grouped by task or semantic section.
     - Use UiField around labelled form controls.
     - 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.
   avoid:
     - Do not create a decorative landing page for operational settings.
+    - Do not put content-surface padding on the root page wrapper.

package/docs/profiles/pages/CollapseBlockPage.yml

@@ -15,6 +15,9 @@ expected_structure:
   - Multiple collapsible blocks with their own content and local actions.
   - If the page contains only collapse blocks, the white page surface is not needed.
   - If every collapse block has its own save action, the bottom save panel is not needed.
+  - Treat each collapse block as a local mini-page with its own action priority.
+  - Each collapse block footer can have one Default Primary action for the main local action.
+  - If a block has a stronger create/save/apply action, make that local action Success Primary and move other actions to Default Primary, secondary, or tertiary by meaning.
   - Collapse blocks can contain text, buttons, fields, controls, and small tables.
 
 avoid_inside_blocks:
@@ -41,6 +44,9 @@ ai_notes:
   do:
     - Use collapses for optional or separable sections.
     - Keep required critical actions visible enough for the workflow.
+    - Put local section actions in the UiCollapseBox footer or footer-content slot.
+    - Apply primary-button limits inside each collapse block independently from the page-level footer.
   avoid:
     - Do not nest collapses inside collapses.
     - Do not hide complex tables inside collapse blocks.
+    - Do not add a global bottom save panel when each collapse block already has its own local save action.

package/docs/profiles/pages/EntityListPage.yml

@@ -17,13 +17,16 @@ expected_structure:
   - UiPageHeader with a page title.
   - 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 primary button usually creates a new entity for the list.
+  - The main Default Primary button usually creates a new entity for the list when there is no stronger Success Primary action on the page.
   - 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 +64,9 @@ 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.
   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.

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

@@ -16,13 +16,21 @@ scope:
 shared_rules:
   - Page title uses the large accent text style, Text large Accent 24.
   - Page-level actions sit to the right of the title.
-  - A page can have only one Default Primary button and one Success Primary button.
-  - Additional page actions can use secondary or tertiary variants when the task needs them.
-  - When a group has multiple buttons, the primary action should represent the main flow.
+  - A full page should have at most one page-level primary button of each variant, Success Primary, Default Primary, and Danger Primary.
+  - Use Success Primary for the page's strongest call to action when it creates or commits a result, such as Save, Apply, or Create.
+  - Place the page-level Success Primary action in UiPageFooter for save or apply workflows.
+  - 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.
+  - 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.
   - Secondary actions should support or cancel the primary flow.
   - 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.
 
@@ -51,6 +59,9 @@ ai_notes:
     - Choose ModalSidebar only when the flow is compact.
     - 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.
   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 add page-surface padding to both the page root and the white content surface.

package/docs/profiles/widgets/WidgetComposition.yml

@@ -0,0 +1,113 @@
+widget_profile: WidgetComposition
+summary: >
+  Composition rules for RetailCRM embedded widgets mounted into CRM target slots.
+  A widget should add a small predictable inline control to the host page and move
+  complex workflows into UiModalSidebar or UiModalWindow.
+
+use_when:
+  - You are building a component for defineWidgetRunner.
+  - You are rendering UI directly inside a widget target.
+  - You need to decide whether widget content belongs inline, in a modal sidebar, or in a modal window.
+
+inline_target_rules:
+  - Keep the UI rendered directly in the widget target simple and predictable.
+  - Prefer UiToolbarButton for compact widget actions.
+  - Prefer UiToolbarLink for compact navigation or link-shaped actions.
+  - Simple text is allowed when the widget only needs to show a short status, value, or hint.
+  - Icons are allowed when they clarify the toolbar action or compact status.
+  - Keep inline controls close to the target's existing density and spacing.
+  - Use one or a few compact controls; avoid turning the target slot into a standalone screen.
+
+complex_ui_rules:
+  - Put forms, tables, filters, maps, summaries, and multi-step workflows inside UiModalSidebar or UiModalWindow.
+  - Use UiModalSidebar for contextual editing, narrow forms, short lists, and side-panel workflows.
+  - Use UiModalWindow for wider workflows, maps, previews, or content that needs more horizontal room.
+  - The inline widget control should usually open the modal/sidebar and pass the relevant target/context data into that workflow.
+  - The modal/sidebar can use regular page-like components such as UiField, UiButton, UiTable, UiYandexMap, UiAlert, and UiLoader.
+
+avoid_inline:
+  - large cards
+  - full forms
+  - full tables
+  - filter panels
+  - nested page layouts
+  - custom panels that visually compete with the CRM page
+  - page-level headers or footers
+  - heavy custom spacing or wrappers that can break the host page layout
+
+recommended_components:
+  inline:
+    - name: UiToolbarButton
+      profile: ../components/UiToolbarButton.yml
+    - name: UiToolbarLink
+      profile: ../components/UiToolbarLink.yml
+  overlay:
+    - name: UiModalSidebar
+      profile: ../components/UiModalSidebar.yml
+    - name: UiModalWindow
+      profile: ../components/UiModalWindow.yml
+    - name: UiButton
+      profile: ../components/UiButton.yml
+    - name: UiField
+      profile: ../components/UiField.yml
+    - name: UiTable
+      profile: ../components/UiTable.yml
+
+examples:
+  - title: Compact widget action that opens a sidebar
+    code: |
+      <template>
+        <UiToolbarButton @click="opened = true">
+          Show details
+        </UiToolbarButton>
+
+        <UiModalSidebar v-model:opened="opened">
+          <template #title>Widget details</template>
+
+          <UiField id="note" label="Note">
+            <UiTextbox v-model:value="note" />
+          </UiField>
+
+          <template #footer>
+            <UiButton @click="save">Save</UiButton>
+            <UiButton appearance="secondary" @click="opened = false">Cancel</UiButton>
+          </template>
+        </UiModalSidebar>
+      </template>
+
+      <script lang="ts" setup>
+      import { ref } from 'vue'
+
+      import {
+        UiButton,
+        UiField,
+        UiModalSidebar,
+        UiTextbox,
+        UiToolbarButton,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const opened = ref(false)
+      const note = ref('')
+
+      const save = () => {
+        opened.value = false
+      }
+      </script>
+
+target_awareness:
+  - Read the endpoint target profile before choosing inline text, button labels, or modal type.
+  - Match the inline affordance to the target placement; field-level targets need especially compact UI.
+  - Do not infer data availability from the target name; read the linked context profiles.
+  - Avoid adding repeated or noisy controls to targets that can appear many times on one CRM page.
+
+ai_notes:
+  do:
+    - Render only compact, predictable UI directly in the widget target.
+    - Start inline widget UI with UiToolbarButton, UiToolbarLink, simple text, or an icon-enhanced compact action.
+    - Move complex UI into UiModalSidebar or UiModalWindow.
+    - Keep the host CRM page layout stable; the widget should enhance the target, not reshape the page.
+  avoid:
+    - Do not build a full page, dashboard, large card, form, or table directly inside a widget target.
+    - Do not use UiPageHeader or UiPageFooter for inline widget content.
+    - Do not add custom layout chrome around the widget unless the target profile explicitly calls for it.
+    - Do not make the target slot depend on wide fixed dimensions.

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.23",
+  "version": "0.9.25",
   "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,46 @@
+---
+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.
+
+## 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.
+- For `UiSwitch`, use the documented switch + visible label + hint row instead of wrapping it in `UiField`.
+- 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`.