HIF / Документация / Архитектура системы

Инженерия дизайн-систем

Статус: инженерный справочник

Версия: 0.1

Документ определяет, как знания HIF превращаются в сопровождаемую дизайн-систему без сведения проектирования интерфейса к библиотеке компонентов. Он соединяет практики крупных публичных систем с семантической и человеко-центричной основой HIF.

1. Назначение

Дизайн-система успешна, когда правильные, согласованные и доступные продуктовые решения легче создавать и сопровождать в масштабе. Само по себе успех не доказывает ни одно из следующего:

большое число компонентов;
похожие скриншоты;
число загрузок пакета;
общий инструмент дизайна;
токен для каждого визуального значения;
обязательное внедрение.

Система ОБЯЗАНА сохранять прослеживаемую цепочку от человеческой потребности до production-поведения:

потребность → задача → объект → команда → состояние → паттерн → компонент → токен → реализация → основание

Разрыв цепочки создаёт компоненты без задачи, токены без ролей, паттерны без исследований, расхождение дизайна и кода, недоступные композиции доступных примитивов и бренд, скрывающий ненадёжное поведение.

2. Архитектура системы

HIF использует следующие слои. Верхние придают нижним смысл; нижние реализуют, но НЕ ДОЛЖНЫ переопределять семантику верхних.

2.1 Конституция

Конституция задаёт универсальные обязанности: цель, идентичность объектов, команды, состояние, обратную связь, ошибки, обратимость, доступность, автономию, приватность и оценку.

2.2 Профиль продукта

Профиль фиксирует аудиторию, контекст, риск, платформы, ввод, языки, плотность, уровень доступности, бюджеты производительности, внешние конвенции и обоснованные исключения.

2.3 Доменная модель и словарь контента

Слой определяет:

типы и идентичность объектов;
отношения и разрешения;
команды, предусловия и последствия;
машины состояний и persistence;
канонические имена, глаголы и сообщения;
чувствительные и значимые понятия.

Словарь — общий API дизайна, разработки, поддержки, аналитики и документации. Синонимы ради разнообразия НЕ СЛЕДУЕТ вводить, если они размывают identity объекта или команды.

2.4 Принципы опыта

Принцип направляет решения при отсутствии точного паттерна и ОБЯЗАН содержать:

ожидаемый человеческий результат;
область и контрпримеры;
наблюдаемое основание;
вопрос проверки;
конфликты и приоритет.

«Простой», «приятный», «интуитивный» и «спокойный» сами по себе не критерии приёмки.

2.5 Паттерны

Паттерн координирует компоненты и content rules для повторяемой задачи: authentication, search/filter, create/edit/save, destructive action, permission, upload/processing, empty/loading/error/partial, undo/recovery, onboarding, settings, collaboration и concurrent editing.

Паттерн владеет workflow semantics и ОБЯЗАН описывать alternatives, entry/exit, failure, interruption, recovery и measurement.

2.6 Компоненты

Компонент реализует одну повторяемую интерфейсную ответственность со стабильным семантическим контрактом. В него входят дизайн, поведение, код, содержание, доступность, проверки и документация.

2.7 Foundations и токены

Foundations выражают общесистемные роли colour, type, space, size, shape, border, elevation, motion, opacity, sound и других сред. Токены передают решения инструментам и реализациям.

2.8 Реализации и адаптеры

Реализации воплощают контракт для web, Android, Apple, Windows, embedded и других целей. Platform adapters МОГУТ отрисовывать разные контролы, сохраняя семантику и результаты.

2.9 Основания качества

Доказательства связывают требования с автоматическими проверками, ручной верификацией, пользовательскими исследованиями, полевыми данными, результатами поддержки и историей инцидентов.

3. Модель источников истины

Для каждого вида решения ОБЯЗАН быть один нормативный владелец:

Решение	Нормативный источник	Производные представления
Обязанность интерфейса	Конституция HIF	Правила проверки, критерии тестирования
Границы и исключения продукта	Профиль	Ограничения списка работ, отчёт аудита
Смысл объекта и команды	Доменная модель	Схема API, текст интерфейса, таксономия аналитики
Поведение паттерна	Pattern specification	Prototypes, journey tests
API компонента	Component specification	Framework implementations, design assets
Роль и значение foundation	Token source	CSS, Swift, Kotlin, design variables
Поддержка доступности	Доказательства проверки	Панель состояния, документация
Зрелость выпуска	Реестр и журнал изменений	Теги пакетов, метки документации

«Single source of truth» не требует одного приложения. Два файла не могут молча владеть одним решением.

Generated artefacts ОБЯЗАНЫ нести версию источника и generation metadata. Ручное изменение generated output должно проваливать validation либо детерминированно перезаписываться.

4. Дизайн-токены

4.1 Назначение

Токен — именованное решение, а не alias каждого literal. Токены СЛЕДУЕТ использовать, чтобы:

создать общий язык design и code;
отделить semantic use от текущего value;
обеспечить controlled themes, modes, brands и platforms;
сделать изменение reviewable и distributable;
поддержать validation и migration.

Stable Design Tokens Community Group format 2025.10 даёт vendor-neutral JSON interchange. Это Final Report W3C Community Group, но не W3C Recommendation. HIF СЛЕДУЕТ применять его при достаточной поддержке, фиксируя extensions и transformations.

4.2 Обязательные слои

Primitive tokens хранят raw scales и assets. Product code обычно НЕ ДОЛЖЕН их потреблять.
Semantic tokens называют назначение: text.primary, surface.raised, border.danger, motion.feedback. Это основной consumer API.
Component tokens выражают специфичное решение только при отсутствии подходящего semantic token и НЕ ДОЛЖНЫ применяться вне компонента.

Aliases ОБЯЗАНЫ образовывать ациклический разрешимый граф. Build падает при missing references, cycles, incompatible types или unresolved mode.

4.3 Именование

Имя СЛЕДУЕТ строить от стабильного смысла к переменной детали:

category.property.role.state.emphasis

Например: colour.text.primary, colour.border.danger.focused, space.container.inline, motion.duration.feedback.

Нельзя кодировать текущее значение в семантическом имени: вместо grey-quiet-text — colour.text.secondary.

Система ОБЯЗАНА использовать один документированный dialect. Описания переводятся, идентификаторы остаются language-neutral и stable.

4.4 Modes, themes и brands

ОБЯЗАТЕЛЬНО различать:

mode — условие пользователя или среды: light, dark, high-contrast, reduced-motion, compact;
theme — согласованная карта ролей в значения;
brand — identity rules и assets;
platform — conventions и capabilities;
density — policy пространства и target size.

Нельзя сводить измерения в один theme switch. Dark brand не dark mode; compact не reduced size; high contrast не цветовая тема.

Каждую карту ОБЯЗАТЕЛЬНО проверять на contrast и non-colour cues, scaling, forced colours, state distinguishability, charts, images/logos, motion и transparency preferences.

4.5 Governance токенов

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

Новый primitive требует доказать недостаточность scale. Новый semantic — повторяемый смысл. Component token — документированное ограничение компонента. Raw values СЛЕДУЕТ находить linting; exceptions явны и узки.

5. Контракт компонента

Stable component specification ОБЯЗАНА включать следующие разделы.

5.1 Назначение и не-назначение

решаемая проблема;
контексты;
когда не использовать;
related/alternative components;
доказательства повторяемости.

5.2 Анатомия

named parts и slots;
required/optional elements;
ownership labels/descriptions;
разрешённая composition;
nesting constraints.

5.3 Модель состояний

Как минимум рассматриваются:

enabled/disabled;
rest/hover/focus/pressed;
selected/unselected;
checked/mixed/unchecked;
expanded/collapsed;
empty/populated;
valid/warning/invalid;
loading/pending/success/failure;
read-only/editable;
offline/stale/conflicted.

Реализуются только применимые states, но пропуски намеренны. Visual, accessible и domain state ОБЯЗАНЫ совпадать.

5.4 Поведение

commands и events;
keyboard, pointer, touch, pen, voice и assistive input;
focus entry, movement, trapping, restoration и visibility;
timing, repetition и cancellation;
scrolling/overflow;
responsive transformation;
drag-and-drop alternative;
interruption и recovery.

5.5 Контент

грамматика label;
безопасные для localisation length constraints;
helper, empty, warning и error text;
numbers, dates, currency и units;
truncation и доступ к full value;
bidirectionality и mixed direction;
accessible names/descriptions.

Placeholder НЕ ДОЛЖЕН заменять постоянный label. Icon-only action требует accessible name и СЛЕДУЕТ давать видимое объяснение, если смысл не общепринят.

5.6 Доступность

semantic element/platform role;
name, description, value и state;
keyboard model;
focus rules;
target size;
contrast/non-colour;
text resize/reflow;
reduced motion/preferences;
ожидания для программы экранного доступа;
known limitations и tested combinations.

ARIA НЕ ДОЛЖНА заменять нативный элемент HTML с нужной семантикой. Поддержка заявляется на основании доказательств, а не намерения.

5.7 Визуальная спецификация

semantic tokens всех публичных решений;
layout и intrinsic sizing;
min/max/content-driven dimensions;
typography/icon alignment;
states во всех modes;
density/platform variants;
цель и interruption animation;
high contrast/forced colour.

5.8 API и расширение

properties, attributes, slots, events, methods;
controlled/uncontrolled state;
supported customisation;
private boundaries;
version/deprecation guarantees;
SSR/hydration/native lifecycle;
privacy-preserving analytics hooks.

Consumers НЕ ДОЛЖНЫ зависеть от private DOM, selectors, layers или timing.

5.9 Документация и примеры

Стабильный компонент ОБЯЗАН иметь минимальный корректный пример, реалистичную композицию, состояния и варианты, требования доступности и клавиатуры, руководство по содержанию, допустимые и недопустимые способы применения, матрицу поддержки, миграцию и копируемые примеры, проходящие контроль качества.

6. Паттерны

6.1 Когда паттерн оправдан

Shared pattern требует:

одной user problem минимум в двух достоверных contexts;
стабильных objects, commands и consequences;
доказательства снижения когнитивной стоимости и стоимости поставки;
отсутствия достаточного существующего паттерна;
accountable maintainer.

Визуального сходства недостаточно.

6.2 Спецификация паттерна

ОБЯЗАТЕЛЬНО описываются:

user need и context;
entry conditions;
canonical sequence и alternatives;
object/command/state model;
components/content;
permissions/privacy;
loading/empty/error/partial;
interruption/cancel/undo/recovery;
responsive/cross-platform transformation;
доступность и локализация;
меры успеха и вреда;
доказательства, ограничения и открытые вопросы.

6.3 Граница целого пути

Паттерн включает переходы за пределами экрана: email, notifications, system permissions, help, identity, offline, human support и return paths.

Система чётко различает component (интерфейсная ответственность), pattern (решение задачи), template (layout), service (сквозная способность дать результат).

7. Жизненный цикл вклада и зрелости

7.1 Стадии

Статус	Смысл	Ожидание consumer
Предложение	Проблема и доказательства рассматриваются	Не системная зависимость
Экспериментальный	Есть проверяемое решение	Только явное подключение; несовместимые изменения ожидаемы
Candidate	Contract почти полон	Ограниченный production с named adopters
Stable	Definition of done выполнен	Поддержка; breaking только major + migration
Deprecated	Планируется замена/удаление	Без нового adoption; warning и migration
Retired	Поддержка/распространение прекращены	Исторические docs доступны

Зрелость отдельно относится к спецификации, коду, дизайнерскому ресурсу, документации и доказательствам доступности. Общая метка не скрывает слабое измерение.

7.2 Proposal record

ОБЯЗАТЕЛЬНЫ problem/users/contexts, current workarounds/costs, исследования, использование и инциденты, причину недостаточности существующего ресурса, семантику и API, риски доступности, локализации, конфиденциальности и безопасности, два контекста потребления, ответственного и сопровождение, эксперимент и успех, альтернативы и нецели.

7.3 Права решений

Система управления ОБЯЗАНА назначить ответственного за продукт системы; сопровождающих дизайн, разработку, доступность и содержание; специалистов платформ; ответственных за токены и выпуски; представителей продуктов; лицо, разрешающее тупиковые разногласия; проверку безопасности, конфиденциальности и физической безопасности.

Contribution может быть open при явных decision rights. Central team публикует основания принятия, откладывания и отказа.

7.4 Definition of done

Stable asset требует approved problem/semantic contract, design-code parity, states/inputs, Profile compatibility, tokens, unit/interaction/visual tests, автоматические и ручные проверки доступности, локализацию, двунаправленное письмо и содержание, производительность, документацию и безопасные примеры, матрицу поддержки, ответственных и поддержку, журнал изменений и миграцию и хотя бы одну production validation, если позволяет риск.

8. Инженерия качества

8.1 Портфель проверок

Ни одна проверка не доказывает качество целиком:

Основание	Что находит	Чего не доказывает
Type/schema	Неверный API/token	Usability/perception
Unit	Local logic/transitions	Correct composition
Interaction	Keyboard/pointer/events	Реальный AT output
Automated a11y	Машинно обнаружимые нарушения	WCAG conformance/usability
Visual regression	Rendering drift	Semantic correctness
Screenshot matrix	Themes/locales/density/breakpoints	Behaviour
Программа экранного доступа	Объявления и управление	Опыт всех пользователей
Keyboard-only	Focus/operability	Touch/voice
Масштабирование, перекомпоновка и принудительные цвета	Адаптация	Когнитивная доступность
Performance lab	Controlled regressions	Real-user experience
Field telemetry	Реальные distributions/failures	Intent/causality
Usability research	Comprehension/difficulty	Population prevalence
Support/incidents	Серьёзные lived failures	Полная распространённость

8.2 Обязательная матрица

Профиль задаёт точную матрицу. Для веба как минимум СЛЕДУЕТ проверить engines/ области просмотра, клавиатуру, репрезентативное сочетание программы экранного доступа и браузера, текст 200% и масштаб 400% с перекомпоновкой, светлую, тёмную, высококонтрастную темы и принудительные цвета, уменьшение движения, письмо слева направо и справа налево, expansion locale, pointer/touch, slow network/offline/delay.

8.3 Статус доступности

По полезной модели Carbon отдельно показываются отрисовка по умолчанию, сложные сценарии и ошибки, клавиатура, программа экранного доступа, масштабирование и перекомпоновка, принудительные цвета и контраст, цели касания и оценка людьми.

Статусы: not applicable, not tested, automated pass, manually tested, verified с пользователями, известное ограничение, заблокировано. Обязательны дата, версия, среда и ссылка на доказательство.

8.4 Производительность

Budgets охватывают system assets и pages: package/style size, render/update, memory, input latency, layout stability, loading, fonts/icons и SSR/hydration.

Для веба current Core Web Vitals СЛЕДУЕТ измерять в поле на 75-м перцентиле. Lab tests предотвращают regression, но не выдаются за field performance.

8.5 Контрольные этапы качества

format/schema/token validation;
type/lint/unit;
interaction и automated a11y;
visual/theme/locale/breakpoint;
integration/journey;
ручная проверка доступности и платформы;
оценка кандидата и полевой мониторинг.

Экстренное изменение МОЖЕТ сократить контрольный этап только с явно назначенным ответственным за риск и последующей проверкой.

9. Документация как продукт

Docs ОБЯЗАНЫ обслуживать designers, engineers, content, product, QA и auditors без скрытого институционального знания.

9.1 Информационная архитектура

СЛЕДУЕТ публиковать основания, компоненты, паттерны, содержание, доступность, платформы, ресурсы и пакеты, порядок участия, выпуски и миграции, состояние и known limitations.

Search synonyms ведут к canonical objects. Deprecated pages остаются доступны и ссылаются на replacement.

9.2 Качество документации

Страница ОБЯЗАНА указывать ответственного, состояние и версию; различать требования и эвристики; показывать назначение до API; использовать содержательные примеры; объявлять доступность; связывать альтернативы; содержать обновления и сведения об устаревании; проходить проверку ссылок, орфографии, заголовков и примеров.

Screenshot не может быть единственной спецификацией.

9.3 Синхронизация

Design assets, code и docs СЛЕДУЕТ выпускать из одного change record. Непрерывные проверки находят недокументированные API, устаревшие примеры, отсутствующие токены, несоответствие состояния, отсутствующий вариант дизайна, неработающие ссылки и устаревшие доказательства доступности.

10. Выпуск, совместимость и миграция

10.1 Версионирование

Система ОБЯЗАНА определить public API: properties/events, token IDs/types, import paths, styling hooks, semantic behaviour, keyboard и persisted formats.

Semantic versioning допустим, но visual/behavioural change может быть breaking без изменения type signature.

10.2 Классы изменений

Patch — compatible correction без migration.
Minor — additive или opt-in future behaviour.
Major — removal/rename/default semantics/consumer work.
Обновление правил — руководство меняет проверку без изменения кода пакета.

Примечание к выпуску ОБЯЗАНО назвать влияние на пользователя и потребителя, риск и требуемое действие.

10.3 Deprecation

Нужны reason/replacement, first version, removal window, warning, migration руководство или автоматическое преобразование кода, срочность доступности и безопасности, безопасная для конфиденциальности телеметрия и ответственность за оставшихся потребителей. Тихое удаление стабильного ресурса запрещено.

10.4 Экспериментальная поставка

Feature flags, prerelease packages и preview libraries МОГУТ давать future changes, объявляя instability, isolation from defaults, data/migration, feedback и graduation/removal criteria.

11. Внедрение

11.1 Уровни

По полезному различию USWDS HIF измеряет:

Принятие принципов — Конституция и вопросы проверки.
Принятие руководства — паттерны и правила содержания.
Принятие реализации — токены и компоненты.
Принятие результата — улучшенные доступность, удобство использования, надёжность и поставка.

Package usage не равен успеху.

11.2 Стратегия

Начать с high-risk, high-frequency и duplicated journeys.
Создать semantic foundations до visual migration.
Дать adapters и migration tooling.
Публиковать gaps.
Соединить governance с support.
Собирать exceptions: повторяемые показывают system gap.
Измерять time saved без награды superficial conformity.

11.3 Федеративные расширения

Расширение предметной области МОЖЕТ существовать, если ядро не представляет специальный процесс. Оно ОБЯЗАНО использовать основания и контрольные этапы ядра, иметь ответственного и потребителей, не менять базовую семантику, публиковать состояние и поддержку, передавать общие результаты в основной корпус и иметь план вывода из эксплуатации.

12. Метрики

12.1 Пользовательские результаты

Успех и время задачи, значимые ошибки и восстановление, барьеры доступности, нагрузка на поддержку, доверие и ясность, полевая производительность и надёжность.

12.2 Результаты продукта

Object/command consistency, high-priority journey coverage, exception age, migration completion, duplicate patterns, shared-asset defects.

12.3 System health

Покрытие стабильных условий готовности, актуальность доказательств, время выполнения, разрешение проблем, находимость документации, отставание дизайна от кода, риски сопровождения и ответственности.

12.4 Результаты поставки

Time to conforming journey, change failure, upgrade effort, cross-platform semantic parity, generated versus duplicated work.

Adoption percentage НЕ ДОЛЖЕН быть единственной primary metric: он поощряет forced use даже при неполной системе.

13. Типичные отказы

Component warehouse: assets без модели задач.
Управление снимками экрана: проверка вида без поведения, содержания и состояния.
Token theatre: literals переименованы без semantics.
Знак доступности: результат сканера выдан за сквозную доступность.
Universal component: options смешали разные смыслы.
Private override economy: зависимость от internals.
Design-code drift: независимые releases.
Premature centralisation: непроверенный local pattern стал system burden.
Permanent experiment: production dependency без guarantees.
Silent breakage: смена defaults в minor.
Brand over platform: styling убрал знакомое поведение.
Compliance substitution: approved component выдан за successful service.
Translation after layout: fixed geometry ломает языки.
Metrics without decisions: telemetry без owners и actions.

14. Минимальная операционная модель

Организация ОБЯЗАНА создать:

Constitution и Product Profile template;
domain vocabulary/command model;
token source с primitive/semantic;
небольшой stable component set;
patterns error/loading/destructive/recovery;
руководство по содержанию и доступности;
contribution record/maturity;
автоматические контрольные этапы и ручная матрица;
version/deprecation/migration;
документация с ответственным и состоянием;
exception register;
карта результатов и периодичность проверки.

Начальный стабильный набор СЛЕДУЕТ делать малым. Широта достигается доказательствами и возможностями сопровождения.

15. Checklist выпуска stable component

Семантика

Явны problem и non-purpose.
Определены object, command, state, consequence.
Рассмотрены native/platform/system alternatives.
Focus, selection и activation не смешаны.

Дизайн и контент

Документированы anatomy, variants, compositions.
Спроектированы applicable states.
Есть content rules и realistic examples.
Проверены localisation, expansion и bidi.
Visual decisions используют semantic tokens.

Доступность

Использована native semantics.
Верны name, role, value и state.
Проверены keyboard/focus.
Проверены zoom, reflow, target и inputs.
Проверены colour, forced colour и motion.
Приложено доказательство проверки с программой экранного доступа.
Known limitations публичны.