docs: add React component style change

2026-08-25 15:33:29 +03:00
parent 6e2890f86f
commit 18a9487432
6 changed files with 440 additions and 0 deletions
@@ -0,0 +1,67 @@
+## Why
+
+Frontend сейчас содержит несколько допустимых способов объявлять React
+components, props и exports. Из-за этого соседние files выглядят по-разному:
+часть компонентов объявлена как function declarations, часть может появляться
+как const-valued components, props иногда типизируются inline, а exported API
+может быть смешан с body файла.
+
+Эта неоднородность делает review менее механическим и ухудшает AI-assisted
+changes: future edits могут копировать любой локальный пример и при этом
+расширять разброс стилей. Проблема стала видимой после ручного приведения
+account heading component к более явному стилю, который лучше отделяет props
+contract, component body и module export surface.
+
+Это нужно закрепить сейчас, пока frontend ещё достаточно мал для одной
+behavior-preserving миграции. После фиксации единого стиля новые изменения
+будут проще читать, сравнивать и проверять, а будущие agents получат один
+канонический пример вместо конкурирующих local patterns.
+
+## What Changes
+
+- Установить один frontend-wide стиль для React components: component
+  declaration должна быть const-valued, props contract должен быть named type
+  рядом с компонентом или в предназначенном для типов module, а props
+  destructuring должен происходить внутри component body.
+- Свести обычный module export surface к одному named export block внизу
+  authored source file, а чистые barrels оформлять прямыми re-exports без
+  промежуточных imports, сохраняя читаемый public API и запрещая default export
+  для frontend source.
+- Сделать автоматически проверяемую часть этого стиля частью frontend
+  verification gate.
+- Зафиксировать оставшуюся непроверяемую часть как mandatory frontend
+  convention для maintainers, reviewers и AI agents, не выдавая её за hard
+  guardrail.
+- Мигрировать существующий frontend source к единому стилю без изменения
+  user-visible behavior, routes, localized text, API contract, data fetching,
+  state selection, rendering states или visual design.
+- Non-goal: добавлять custom style checker, если existing frontend tooling не
+  поддерживает конкретный preferred convention.
+- Non-goal: менять frontend architecture boundaries, Feature-Sliced Design
+  imports, generated API types, backend behavior, durable data behavior или
+  product requirements.
+- Non-goal: вводить новые product-visible states, labels, interactions or
+  capabilities.
+
+## Capabilities
+
+### New Capabilities
+
+_Нет._
+
+### Modified Capabilities
+
+- `frontend-quality-guardrails`: frontend quality gate must include the
+  automatically enforceable part of the unified React component style.
+
+## Impact
+
+Users должны видеть то же приложение до и после change. Изменение затрагивает
+frontend maintainers, reviewers и AI agents: authored React source получает
+единый style contract, а frontend verification начинает отклонять нарушения
+той части contract, которую можно проверить existing local tooling.
+
+Affected implementation area — frontend source style, frontend-local
+conventions и frontend verification. Specs отслеживает SDD lifecycle и меняет
+frontend quality guardrail requirement. Backend и product-facing
+documentation не должны меняться.