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

package/AGENTS.md

@@ -70,6 +70,9 @@ 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.
 - If you are unsure whether something is public, assume only exports from `remote` and `assets/*` are safe for consumer code.
 - If a needed capability is missing from the public API, say that clearly instead of suggesting internal imports.
@@ -96,7 +99,7 @@ Commonly used exports from `remote` include:
 
   <UiPageFooter>
     <template #actions>
-      <UiButton @click="save">
+      <UiButton variant="success" @click="save">
         Сохранить
       </UiButton>
     </template>
@@ -120,6 +123,14 @@ const save = () => {}
 </script>
 ```
 
+For page actions, use `Success Primary` for the strongest save/apply/create action, usually in
+`UiPageFooter`. Use `Default Primary` for another important action with a different meaning, and
+move neighboring actions to secondary or tertiary appearances.
+`UiPageHeader` and `UiPageFooter` share the same page-level action scope. When a page is split into
+`UiCollapseBox` sections, each collapse footer starts a local action scope: it can have its own
+single `Default Primary` action, while neighboring local actions should still use secondary or
+tertiary appearances.
+
 ## If You Need More Context
 
 - Package README:

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

@@ -32,27 +32,29 @@ When generating UI code, use this order:
 3. open a detailed profile from [`PROFILES.md`](./PROFILES.md) if one exists;
 4. read the relevant page profile from [`PROFILES.md`](./PROFILES.md) when the task is about complete
    pages, modals, sidebars, filters, tables, or settings layouts;
-5. use [`FORMAT.md`](./FORMAT.md) as the schema for what information is considered reliable;
-6. read [`STYLING.md`](./STYLING.md) when the task is about classes, variables, typography, or visual zones;
-7. if no profile exists yet, fall back to public type declarations and state any inference explicitly.
+5. read [`WidgetComposition.yml`](./profiles/widgets/WidgetComposition.yml) when the task is about UI
+   mounted through `defineWidgetRunner`;
+6. use [`FORMAT.md`](./FORMAT.md) as the schema for what information is considered reliable;
+7. read [`STYLING.md`](./STYLING.md) when the task is about classes, variables, typography, or visual zones;
+8. if no profile exists yet, fall back to public type declarations and state any inference explicitly.
 
 ## Runtime Embedding References
 
 When generating code for a CRM extension, separate UI component choice from runtime placement:
 
-- [`targets` and contexts](../../v1-endpoint/docs/targets.md): explains that `target` is the CRM
+- In `@retailcrm/embed-ui-v1-endpoint`, `docs/targets.md` explains that `target` is the CRM
   embedding point, while `context` is the reactive CRM data available at that point.
-- [`menu placements`](../../v1-endpoint/docs/menu-placements.md): explains how host/manifest menu
+- In `@retailcrm/embed-ui-v1-endpoint`, `docs/menu-placements.md` explains how host/manifest menu
   items map to remote page codes.
-- [`page routes`](../../v1-endpoint/docs/page-routes.md): explains how page `code`, CRM route names,
-  and `definePageRunner` are connected.
-- [`defineWidgetRunner`](../../v1-endpoint/docs/define-widget-runner.md): shows how a widget receives
+- In `@retailcrm/embed-ui-v1-endpoint`, `docs/page-routes.md` explains how page `code`, CRM route
+  names, and `definePageRunner` are connected.
+- In `@retailcrm/embed-ui-v1-endpoint`, `docs/define-widget-runner.md` shows how a widget receives
   the current `target` prop.
-- [`definePageRunner`](../../v1-endpoint/docs/define-page-runner.md): shows how a page receives the
+- In `@retailcrm/embed-ui-v1-endpoint`, `docs/define-page-runner.md` shows how a page receives the
   current `code` prop.
-- [`context concept`](../../v1-contexts/docs/ru/CONCEPT.md): explains predefined CRM contexts such as
-  `order/card`, `customer/card`, `user/current`, and `settings`.
-- [`custom context`](../../v1-contexts/docs/ru/CUSTOM.md): explains custom-field contexts.
+- In `@retailcrm/embed-ui-v1-contexts`, `docs/ru/CONCEPT.md` explains predefined CRM contexts such
+  as `order/card`, `customer/card`, `user/current`, and `settings`.
+- In `@retailcrm/embed-ui-v1-contexts`, `docs/ru/CUSTOM.md` explains custom-field contexts.
 
 ## Default Recommendation For Common Forms
 
@@ -87,12 +89,16 @@ Default screen rules:
   card/settings page, multi-column page, collapse-block page, modal sidebar, or modal window;
 - use `UiPageHeader` for page identity and top-level actions;
 - 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;
+- 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 `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.
 
 ## Default Recommendation For Table Screens
@@ -101,6 +107,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;
@@ -112,7 +120,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:
 
@@ -121,6 +131,32 @@ 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`;
+- 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`.
+
+## Default Recommendation For Widgets
+
+When building a widget mounted into a CRM target, keep the inline target UI compact and predictable:
+
+- read [`WidgetComposition.yml`](./profiles/widgets/WidgetComposition.yml) before composing widget UI;
+- render only simple inline UI in the target: `UiToolbarButton`, `UiToolbarLink`, short text, and icons;
+- move forms, tables, maps, filters, summaries, and multi-step flows into `UiModalSidebar` or `UiModalWindow`;
+- avoid custom panels, page headers, page footers, wide fixed layouts, or standalone screens inside the target slot;
+- read the endpoint target profile before choosing labels, modal type, or data access.
+
 ## External Documentation Patterns
 
 These references are useful when extending the profiles and examples in this package:

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/PROFILES.md

@@ -7,6 +7,7 @@ The current profile layer is structured like this:
 - the index stays in markdown so both humans and agents can navigate it easily;
 - component profiles live in `docs/profiles/components/*.yml`;
 - page-composition profiles live in `docs/profiles/pages/*.yml`;
+- widget-composition profiles live in `docs/profiles/widgets/*.yml`;
 - YAML is the source of truth for structure, props, slots, emits, composition, page patterns, and AI rules.
 
 ## Table Of Contents
@@ -34,6 +35,7 @@ Use these entrypoints:
 - [`COMPONENTS.md`](./COMPONENTS.md) for the full linked component index
 - `docs/profiles/components/*.yml` for per-component machine-readable profiles
 - `docs/profiles/pages/*.yml` for page, modal, sidebar, filter, table, and settings-layout profiles
+- `docs/profiles/widgets/*.yml` for embedded widget composition profiles
 
 Current high-signal core profiles:
 
@@ -62,6 +64,10 @@ Current page profiles:
 - [`ModalSidebar`](./profiles/pages/ModalSidebar.yml)
 - [`ModalWindow`](./profiles/pages/ModalWindow.yml)
 
+Current widget profiles:
+
+- [`WidgetComposition`](./profiles/widgets/WidgetComposition.yml)
+
 ## What To Read First
 
 - `key_props` if you need to choose a component quickly.
@@ -71,6 +77,7 @@ Current page profiles:
 - `examples` if you need copyable usage snippets.
 - `ai_notes` if the agent needs safe defaults and anti-patterns.
 - `profiles/pages/*.yml` if the task is about a full page, modal, sidebar, filter, table, or settings layout.
+- `profiles/widgets/*.yml` if the task is about UI mounted through `defineWidgetRunner`.
 
 ## Styling Reads
 
@@ -82,3 +89,4 @@ Current page profiles:
 - All new updates should be made in YAML profiles.
 - Keep component-level details in `profiles/components`.
 - Keep page-composition details in `profiles/pages`.
+- Keep widget-composition details in `profiles/widgets`.

package/docs/README.md

@@ -62,7 +62,9 @@ If you need to generate UI quickly:
 5. the relevant profile from [`PROFILES.md`](./PROFILES.md)
 6. the relevant page profile from [`PROFILES.md`](./PROFILES.md) if the task is about complete pages,
    modals, sidebars, filters, tables, or settings layouts
-7. [`STYLING.md`](./STYLING.md) if the task is about classes, variables, typography, or layout tuning
+7. the widget composition profile from [`PROFILES.md`](./PROFILES.md) if the task is about UI mounted
+   through `defineWidgetRunner`
+8. [`STYLING.md`](./STYLING.md) if the task is about classes, variables, typography, or layout tuning
 
 If you are extending the docs:
 

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,21 @@ 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.
+
+## 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/UiButton.yml

@@ -228,7 +228,9 @@ composition:
 
 ai_notes:
   do:
-    - Start with appearance=primary for the main CTA.
+    - 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.
   avoid:
     - Do not replace UiButton with UiLink when the action should read as a button.

package/docs/profiles/components/UiCollapseBox.yml

@@ -76,6 +76,26 @@ examples:
       import MyCustomIcon from '@retailcrm/embed-ui-v1-components/assets/sprites/actions/info.svg'
       import { UiCollapseBox } from '@retailcrm/embed-ui-v1-components/remote'
       </script>
+  - title: Section with local action
+    code: |
+      <template>
+        <UiCollapseBox>
+          <template #title>Connection settings</template>
+          <template #body-content>Section form content</template>
+          <template #footer-content>
+            <UiButton @click="saveSection">Save section</UiButton>
+          </template>
+        </UiCollapseBox>
+      </template>
+
+      <script lang="ts" setup>
+      import {
+        UiButton,
+        UiCollapseBox,
+      } from '@retailcrm/embed-ui-v1-components/remote'
+
+      const saveSection = () => {}
+      </script>
 use_when:
   - You need a ready-to-use collapsible box.
   - You need grouped expandable sections with consistent visuals.
@@ -112,8 +132,12 @@ ai_notes:
   do:
     - Use UiCollapseBox for structured disclosure UI.
     - Put the summary in the header and details in the body; avoid hiding critical required fields.
+    - Treat the footer and footer-content slots as a local action area for the section.
+    - Use one Default Primary button in a collapse footer for the main local action when the page has several independent sections.
+    - Use Success Primary in a collapse footer only when that section's local action is the strongest create/save/apply action.
   avoid:
     - Do not rebuild collapse header UI manually when this component already fits.
+    - Do not put several primary buttons of the same variant in one collapse footer.
 
 composition:
   works_well_with:

package/docs/profiles/components/UiField.yml

@@ -13,22 +13,21 @@ 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 +60,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,6 +158,7 @@ api:
           - one form control
           - UiTextbox
           - UiSelect
+          - UiNumberStepper
           - UiDatePicker
         avoid:
           - several unrelated controls
@@ -248,6 +298,7 @@ composition:
   works_well_with:
     - UiTextbox
     - UiSelect
+    - UiNumberStepper
     - UiDatePicker
     - UiTimePicker
   patterns:
@@ -258,7 +309,10 @@ composition:
 ai_notes:
   do:
     - Forward slot props into the actual control in most form scenarios.
+    - 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 control.
   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 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/UiPageFooter.yml

@@ -84,7 +84,7 @@ api:
           - wide content blocks
           - nested page sections
       layout_effect: Renders as the flexible left area and can contain multiple actions.
-      notes: Use this slot for save, apply, cancel, or save-and-exit actions.
+      notes: Use this slot for save, apply, cancel, or save-and-exit actions. The main save/apply action is usually a Success Primary UiButton.
     - name: aside
       zone: right-side aside action group
       creates: Separate aside action area.
@@ -156,6 +156,8 @@ ai_notes:
   do:
     - Import UiPageFooter from @retailcrm/embed-ui-v1-components/remote.
     - Use the actions slot for primary and secondary page actions.
+    - Use UiButton variant="success" for the strongest save/apply/create action in the footer.
+    - Keep neighboring footer actions less dominant unless they are the page's single Default Primary or Danger Primary by meaning.
     - Use the aside slot for a separated destructive or secondary action.
     - Put UiButton or another public action component inside slots.
     - Add page-level positioning only in the host/page layout when the footer must stick to a specific shell area.
@@ -164,3 +166,4 @@ ai_notes:
     - Do not import UiPageFooter from internal package paths.
     - Do not expect UiPageFooter to create buttons from props.
     - Do not expect UiPageFooter to be fixed to the bottom of the window automatically.
+    - Do not put multiple Success Primary, Default Primary, or Danger Primary actions with the same variant in the footer.

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.