---
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`.
