# Code: Руководства

## Паттерны

### Встроенная команда в инструкции

Когда использовать:

- документация или текст подсказки упоминает короткую команду

Заметки о композиции:

- оборачивайте в `Code` только саму команду
- окружающий текст инструкции оставляйте в `Text`

Компромиссы:

- легко найти взглядом
- не подходит для многострочных примеров

```tsx
import { Code, Text } from '@vega-ui/react';

export default function InlineCommandInInstructionalCopy() {
  return (
    <Text asChild size={3}>
      <p style={{ maxWidth: '60ch' }}>
        If the dev server fails to start, delete <Code>node_modules</Code>, run <Code>pnpm install</Code> and try
        again.
      </p>
    </Text>
  );
}
```

### Встроенный идентификатор

Когда использовать:

- имя поля, переменная окружения или токен требуют выделения

Заметки о композиции:

- делайте идентификатор коротким
- не оборачивайте в `Code` целые поясняющие предложения

Компромиссы:

- проясняет машиночитаемые имена
- при чрезмерном использовании создаёт визуальный шум

```tsx
import { Code, Text } from '@vega-ui/react';

const variables = [
  { name: 'DATABASE_URL', description: 'Postgres connection string for the primary database.' },
  { name: 'SENTRY_DSN', description: 'Error reporting endpoint. Leave empty to disable reporting.' },
  { name: 'VEGA_THEME', description: 'Forces the initial theme: light or dark.' },
];

export default function InlineIdentifier() {
  return (
    <dl style={{ display: 'grid', gap: 'var(--spacing-8)', width: '100%', margin: 0 }}>
      {variables.map((variable) => (
        <div key={variable.name} style={{ display: 'grid', gap: 'var(--spacing-2)' }}>
          <dt><Code size={2}>{variable.name}</Code></dt>
          <Text asChild size={2} style={{ color: 'var(--label-secondary)' }}>
            <dd style={{ margin: 0 }}>{variable.description}</dd>
          </Text>
        </div>
      ))}
    </dl>
  );
}
```

### Текст вперемешку с кодом

Когда использовать:

- основной текст содержит один-два технических фрагмента

Заметки о композиции:

- абзац оставьте `Text`
- используйте `Code` только для фрагментов с семантикой кода

Компромиссы:

- сохраняет читаемость
- длинные технические отрывки лучше вынести в блочный пример

```tsx
import { Code, Text } from '@vega-ui/react';

export default function MixedProseAndCode() {
  return (
    <Text asChild size={3}>
      <p style={{ maxWidth: '60ch' }}>
        The form sends the selected plan as <Code>plan_id</Code>. Read it on the server with{' '}
        <Code>formData.get('plan_id')</Code>; an empty value means the user kept the free tier.
      </p>
    </Text>
  );
}
```

## Сравнение

### Быстрое правило выбора

Используйте `Code` для встроенных команд, идентификаторов и токенов. Для обычного текста используйте `Text`, а для больших фрагментов — отдельное решение для блоков кода.

### `Code` или `Text`

- Используйте `Code` для семантики встроенного кода.
- Используйте `Text` для обычного текста.

### `Code` или `Badge`

- Используйте `Code` для идентификаторов и команд, похожих на код.
- Используйте `Badge` для статусов и категорий.

### `Code` или блоки кода в markdown

- Используйте `Code` для коротких встроенных фрагментов.
- Для многострочных примеров используйте блоки кода в markdown или отдельный компонент блока.

### Выбирайте этот компонент, когда

- содержимое — короткий токен кода, команда или идентификатор
- важна семантика `<code>`

### Не выбирайте этот компонент, когда

- содержимое — абзац текста
- фрагмент многострочный или требует подсветки синтаксиса

## Решение проблем

### Встроенный фрагмент кода переносится в неудобных местах

#### Симптом

Длинные команды или пути переносятся, и их труднее читать.

#### Вероятная причина

`Code` рассчитан на встроенные фрагменты и разрешает перенос, чтобы избежать переполнения.

#### Как проверить

- оцените длину содержимого
- проверьте, не будет ли фрагмент читаться лучше в виде блока

#### Исправление

Используйте отдельный многострочный пример кода, когда содержимое перестаёт быть по-настоящему встроенным.

### Фрагмент выглядит как плашка статуса, а не как код

#### Симптом

Интерфейс подаёт фрагменты кода так, будто это бейджи или теги.

#### Вероятная причина

`Code` используется как универсальная выделенная метка.

#### Как проверить

- проверьте, действительно ли содержимое — команда, токен или идентификатор

#### Исправление

Перейдите на `Badge`, `Text` или другой семантический примитив, если содержимое не является кодом.

### Собственные переопределения снижают контраст

#### Симптом

Встроенный код плохо читается на своём фоне.

#### Вероятная причина

Тема или локальные переопределения изменили сочетание заливки и цвета текста.

#### Как проверить

- сравните токены переднего плана и фона в отрендеренном элементе
- проверьте читаемость в светлой и тёмной темах

#### Исправление

Используйте стандартную пару `--fills-secondary` и `--label-secondary` или заново проверяйте контраст при их переопределении.