# UI Primitives

> Use when building or refactoring massCode UI components with local Ui primitives or Shadcn, especially for cn, cva, notifications, and rules against reimplementing basic controls.

- Skill: `masscodeio/ui-primitives` (Agent Skill)
- Install (CLI): `npx skillmds@latest add masscodeio/ui-primitives`
- Raw SKILL.md: https://api.skillmd.com/api/skills/masscodeio/ui-primitives/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: masscodeio (https://skillmd.com/u/masscodeio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/masscodeio/ui-primitives

---


# UI Primitives

## Overview

Базовые UI-элементы в massCode должны собираться из существующих `Ui*` компонентов и Shadcn-паттернов. Этот skill отвечает за component-level usage rules, а не за общую визуальную базу.

## Component Usage

- Локальные UI-компоненты доступны через auto-import с префиксом `Ui`.
- Базовые элементы вроде button, input, checkbox, action button не переизобретай на сыром HTML, если есть готовый `Ui*` вариант.
- Если нужного элемента нет, сначала создай его в `src/renderer/components/ui/`, потом используй в фиче.

## Buttons

- Primary action должен быть явным и не конкурировать с несколькими равноправными CTA в одном контейнере.
- Icon-only actions должны быть понятны по контексту и иметь tooltip или другой доступный label path.
- Loading и pending actions должны использовать существующий button pattern, а не ad-hoc “disabled text swap”.
- Destructive actions не должны выглядеть как обычные secondary controls.

## Cards And Containers

- Для автономных panel-like блоков используй существующий `Card` / `Ui*` container pattern, если он уже есть в области.
- Внутренние muted blocks не нужно пересобирать разными `div`-паттернами в каждой фиче.
- Repeated panel structure должна переезжать в shared primitive или local feature primitive, а не копироваться markup-в-маркап.

## Readonly And Copyable Content

- Длинный readonly output, generated text, URLs и similar content не показывай как “обычный disabled input”, если это ухудшает чтение.
- Для copy flows используй существующий copy pattern и уведомления через `useSonner()`.
- Readonly content должен оставаться визуально читаемым и удобно копируемым.

## Styling Helpers

- Для variants используй `cva`.
- Для склейки классов используй `cn()`.
- Не делай variants вручную строковыми `if`-цепочками там, где нужен нормальный variant API.

## Shadcn Rules

- Shadcn-компоненты импортируй вручную из `@/components/ui/shadcn/*`.
- Для namespace-based компонентов используй паттерн вроде `import * as Dialog from '@/components/ui/shadcn/dialog'`.

## Notifications

- Для уведомлений используй `useSonner()`.
- Не добавляй локальную, параллельную систему toast/notification внутри фичи.

## Tooltip, Popover, Overlay

- Tooltip — для короткого пояснения.
- Popover — для richer inline content, picker-like content или contextual controls.
- Не заменяй их ad-hoc overlay-разметкой без необходимости.
- Validation и inline guidance должны использовать существующие tooltip/popover primitives, если проект уже их применяет в аналогичных местах.

## Dialog Focus

- Во всех диалогах явно управляй фокусом при открытии и закрытии. Не допускай автоматического фокуса на крестике закрытия и появления tooltip на кнопке открытия из-за возврата фокуса после закрытия.
- По умолчанию отменяй стандартный autofocus на `DialogContent`:

  ```vue
  @open-auto-focus="(e) => e.preventDefault()"
  @close-auto-focus="(e) => e.preventDefault()"
  ```

- Исключение — намеренный фокус на конкретном поле или действии, нужном для сценария диалога. Задавай такую цель явно; при закрытии выбирай цель возврата фокуса без побочного показа tooltip.
- Сохраняй focus trap и клавиатурную навигацию. Проверяй открытие и закрытие мышью и клавиатурой, включая Escape.

## Common Mistakes

- Писать ещё одну кнопку или input с нуля “потому что быстрее”.
- Склеивать сложные conditional classes без `cn()`.
- Дублировать существующий primitive внутри feature directory вместо общего `src/renderer/components/ui/`.
- Использовать disabled input как универсальный readonly display surface.
- Делать overlay pattern вручную там, где уже есть Shadcn primitive.
- Смешивать правила primitives с вопросами визуальной базы, которые должны идти в `ui-foundations`.