# Дизайн таблиц документации — ответы Соннета и итоговый план

> Консультация с Claude Sonnet от 2026-07-18 по дизайну страниц параметров Terraform-провайдера Nubes.
> Полный контекст и вопросы: см. историю чата.

---

## Ответы Соннета (кратко)

| # | Вопрос | Ответ Соннета |
|---|--------|--------------|
| 1 | Приоритеты правильные? | Да, но Default должен быть ВЫШЕ Constraints. Юзер сначала смотрит Default, и только если не устраивает — лезет в Constraints |
| 2 | Пропорции ширин? | Code **20-22%**, Default **12%**, Description **32-40%**, Constraints **29-31%** |
| 3 | Убирать ID? Type → иконки? | **ID — убрать совсем.** Type — заменить иконками-баджами (`123`, `"…"`, `{…}`, `[…]`) в ячейке Code. Экономия колонки |
| 4 | Required: ✓ или ★? | **Красная ★ перед Code.** Универсальная конвенция (HTML-формы, Swagger). Экономия колонки |
| 5 | Description прятать? | **line-clamp(2) с кнопкой «▼ ещё».** Короткие (<80 символов) показывать полностью |
| 6 | Constraints — monospace? | **Да.** `font-family: monospace`, `overflow-wrap: anywhere`. `break-all` рвёт regex нечитаемо |
| 7 | Поиск по параметрам? | **Не нужен.** ~16 параметров на сервис, Ctrl+F браузера хватает |
| 8 | Цветовое кодирование строк? | **Да, тонко.** Required: `#fffbf0`, Nested: `padding-left + #f8f8f8`, Zebra: `#fafafa`/`#fff` |
| 9 | Sticky thead? | **Да.** `position: sticky; top: 0` |
| 10 | Что упустили? | **Кнопка копирования Code** (⧉ при hover). **Порядок строк** (required первые). ~~Мобильный вид~~ — не актуально, аудитория только десктоп |
---

## Итоговый план (объединённое мнение Соннета + моё)

### Этап 1 — быстро, только CSS (сделать сейчас)

| # | Что | Как |
|---|---|---|
| 1 | ★ вместо колонки Required | CSS: скрыть текст, `::before { content: "★"; color: #e74c3c; }` перед Code |
| 2 | Убрать ID | `display: none` на `th:nth-child(1)`, `td:nth-child(1)` |
| 3 | Monospace для Constraints | `font-family: monospace`, `overflow-wrap: anywhere` |
| 4 | Sticky thead | `position: sticky; top: 0; z-index: 1` |
| 5 | line-clamp(2) для Description | `display: -webkit-box; -webkit-line-clamp: 2` |
| 6 | Перераспределить ширины | По таблице ниже |
| 7 | Zebra striping | `tr:nth-child(even) { background: #fafafa }` |

### Этап 2 — правки генератора (позже)

| # | Что | Как |
|---|---|---|
| 8 | ★ генерировать в HTML (не CSS) | В `writers.go` добавить `★` перед Code для required |
| 9 | Иконки типов | В `writers.go`: `string` → `"…"`, `integer` → `123`, `map-fixed` → `{…}` и т.д. |
| 10 | Кнопка копирования | JS: при клике на Code копировать в буфер |
| 11 | Порядок строк | Required-параметры первыми в `renderParamTable` |

### Новые ширины колонок (после удаления ID и Required)

**Основная таблица (4 колонки):**
| Code+Type | Default | Description | Constraints |
|---|---|---|---|
| 22% | 13% | 35% | 30% |

**Nested-таблица (5 колонок, ID и Required убраны):**
| ★Code+Type | Default | Description | Constraints |
|---|---|---|---|
| 22% | 12% | 35% | 31% |

---

## Моё мнение

Соннет дал очень толковые ответы. Главные инсайты для меня:

1. **★ красная звёздочка вместо колонки Required** — это убивает двух зайцев: семантически точнее (★ = «обязательно», а не ✓ = «ок»), и экономит колонку. Я до этого думал про ✓ и не догадался до ★.

2. **Default выше Constraints** — логично. Я ставил Constraints наравне с Default, но реально юзер сначала смотрит дефолт. Constraints — fallback.

3. **line-clamp(2)** — компромисс между «прятать» и «показывать всё». 73% описаний влезут, CTRL+F работает, вертикальный ритм не ломается. Лучше чем сворачивать.

4. **Кнопка копирования** — я упустил. Самая частая операция юзера — скопировать имя параметра. Иконка ⧉ при hover — микрофича с огромным эффектом.

5. **Порядок строк** — required первыми. Тоже упустил. Сейчас они вразнобой из YAML.

Единственное с чем не согласен: **поиск**. Соннет говорит «не нужен, Ctrl+F хватает». Но когда параметров 25+ и они называются `access_configuration_allow_list_ip_space_master`, Ctrl+F неудобен. Фильтр с debounce в 5 строк JS — не переусложнение, а реальная помощь. Но это на потом, не в первую очередь.