LLM Wiki — это Wiki, которая организует способы поиска и использования материалов LLM в определённой области. Она указывает LLM, что читать в первую очередь в зависимости от вопроса, и сообщает, какому источнику отдавать приоритет, если содержание материалов различается.
Она также ведёт отдельную запись информации, которая ещё не была проверена. Поскольку новые подтверждённые в ходе работы сведения добавляются обратно в Wiki, следующую задачу можно начать с уже организованных критериев и оставшихся вопросов.
Зачем нужна LLM Wiki
Простое собирание множества документов в одном месте не превращает их автоматически в знания. Если LLM не знает, где находятся необходимые материалы, какая информация является самой свежей или чему следовать при противоречии между разными записями, она может выдать неправильный ответ даже после прочтения множества документов.
Библиотека отличается от склада, где книги просто сложены в кучу, наличием классификации и каталогов. VUI LLM Wiki организует материалы таким же образом. Она сужает круг документов для чтения в соответствии с типом работы и указывает расположение и приоритет каждого материала.
Также фиксируются случаи, когда ответ найти не удалось. Сохранение временно обработанного содержимого и ещё не проверенных вопросов не позволяет LLM заполнять пробелы догадками, благодаря чему следующая задача может повторно проверить работу, начиная с этого места.
Предпосылки создания VUI LLM Wiki
Мне поручили долгосрочную задачу по созданию VUI Design System. Проблема заключалась в том, что я не был систематически обучен визуальному дизайну. Было трудно, просто глядя на экран, сразу определить, является ли он «похожим на VUI» или «не похожим на VUI».
Я считал, что создать Design System, которую можно было бы поддерживать в долгосрочной перспективе, опираясь только на личную интуицию, будет сложно. Поэтому сначала мне нужно было систематизировать, что проверять при оценке VUI-дизайна и как воспроизводить это суждение при повторном возникновении той же проблемы.
Принципы организации VUI LLM Wiki
Материалы, используемые для оценки VUI, — это дизайны Figma, исходный код и темы VUI, сгенерированные токены и спецификации компонентов, Storybook и записи QA и были расположены в нескольких местах. Wiki не копирует эти материалы, а организует путь и приоритеты для перехода к материалам, относящимся к каждому вопросу.
1. Справочные материалы
Figma показывает внешний вид, задуманный дизайнером. packages/vui-ui и packages/vui-theme содержат текущий рабочий код, а сгенерированные токены и спецификации компонентов систематизируют доступные имена и функции. Storybook, отчёты Figma Sync и записи QA используются для сравнения результатов реализации.
2. Критерии оценки
Если материалы различаются, следуйте порядку, организованному в authority.md. При переносе нового дизайна используйте Figma как целевой образец; при объяснении текущего поведения проверяйте исходный код и тему. Компоненты, токены и экранные паттерны разделены на соответствующие списки, а ещё не утверждённая информация записывается отдельно в gap-index.md.
3. Путь чтения
wiki.md указывает начальную точку, подходящую для задачи. После этого читайте только соответствующую карточку компонента, документ о токенах или экранный паттерн. DESIGN.md — это список для чтения, который ещё сильнее сужает набор документов, необходимых для часто повторяющихся задач; когда требуется принять решение, переходите по ссылкам обратно к исходным материалам.
Структура каталогов
В docs/design эти принципы разделены на четыре группы документов. Поскольку wiki.md направляет вас к документам, подходящим для задачи, запоминать имена всех файлов не нужно.
Точки входа и правила docs/design/wiki.md, authority.md, validation.md
wiki.md предоставляет начальные точки для конкретных задач. authority.md определяет, чему следовать при различии материалов, а validation.md содержит список пунктов, которые нужно проверить после обновления Wiki.
Списки docs/design/profiles/company/*-index.md
Эти списки отдельно организуют компоненты, токены, экранные паттерны и нерешённые вопросы. Они выбирают только документы, относящиеся к текущему вопросу.
Подробные документы components/*.card.md, patterns/*.md, tokens/*.md
В них объясняется использование компонентов, способы структурирования экранов и принципы использования токенов с необходимым уровнем детализации.
Списки для чтения по конкретным задачам DESIGN.md, exports/*.DESIGN.md
В них собраны только документы, необходимые для повторяющихся задач, таких как экраны списков CRUD или Forms. LLM начинает отсюда, а не с чтения всей Wiki, и проверяет исходные материалы, когда требуется принять решение.
Использование и обновление Figma Sync
Процесс переноса одобренного дизайнером дизайна Figma в компоненты VUI и Storybook называется Figma Sync. Он не сводится лишь к тому, чтобы сделать экран визуально похожим. Состояния компонентов необходимо связать с существующим API, а токены VUI — отличать от элементов оформления, используемых только в Storybook.
Когда я начал Figma Sync, сначала я проверил соответствующую карточку компонента и документ о токенах в Wiki. Я отразил новые подтверждённые в ходе работы сведения в соответствующих документах, а части без ответов оставил как нерешённые вопросы (пробелы). После завершения работы я также обновил Wiki.
Случай проверки Tooltip
На первый взгляд первая версия Tooltip казалась почти завершённой. Однако направление и положение стрелки отличались от Figma, а пунктирная рамка, используемая для пояснений в Storybook, также попала на итоговый экран.
Если бы я вносил исправления, основываясь только на экране, то мог бы изменить размер и положение стрелки с помощью произвольных чисел. Следуя Wiki, я по порядку проверил определение направления в Figma, существующий API VuiTooltip, область применения элементов оформления Storybook и доступные токены.
Рисунок 1. Tooltip до исправления. На одном экране смешаны оформление Storybook и проблемы со стрелкой для каждого направления.
Рисунок 2. Tooltip после исправления. Используется существующее направление VuiTooltip, а оформление, предназначенное только для Storybook, отделено.
После проверки выяснилось, что направление можно обработать с помощью существующего направления VuiTooltip. Специфичное для Storybook оформление было отделено от реализации. С другой стороны, поскольку для формы стрелки не существовало подтверждённого токена, этот вопрос оставили нерешённым, вместо того чтобы произвольно создавать правило.
Случай дифференциации состояний MenuItem
Проблема с MenuItem заключалась в том, что состояния disabled и disabled + selected рассматривались как одинаковые. В первоначальной реализации цвет фона selected применялся ко всем состояниям disabled, из-за чего даже у невыбранных элементов оставался серый фон.
В Wiki я одновременно изучил карточку VuiMenuItem, экраны для отдельных состояний в Figma, а также текстовые токены и токены действий VUI. В Figma у отключённых элементов фон был прозрачным, а фон selected сохранялся только для состояния disabled + selected. Поэтому для текста в состоянии disabled я применил text.disabled, сохранив прозрачный фон, а action.selected применил только при наличии также состояния selected.
Рисунок 3. MenuItem до исправления. Фон selected применялся даже к невыбранным отключённым элементам.
Рисунок 4. MenuItem после исправления. Для отключённых элементов был сохранён прозрачный фон, а фон selected применялся только к состоянию disabled + selected.
Случай создания дизайна Kanban
Во время последнего Sprint нам понадобился шаблон Kanban, который можно было бы действительно использовать в течение короткого периода времени. Это стало хорошей возможностью выяснить, может ли VUI LLM Wiki помогать не только с исправлением существующих компонентов, но и с проектированием новых экранов.
Сначала я изучил экраны CRUD/List и сценарии Dialog в Wiki. Я создал доску, колонки, карточки, а также действия создания, редактирования и удаления, используя существующие компоненты VUI, и применил семантические токены для цветов статусов и поверхностей карточек. Хотя это был мой первый Kanban, мне удалось быстро создать дизайн, соответствующий другим экранам VUI.
Рисунок 5. Экран бэклога Kanban, созданный по шаблонам, компонентам и путям токенов в VUI LLM Wiki.
После завершения VUI LLM Wiki те же стандарты дизайна можно будет соблюдать даже при смене LLM, назначенной для выполнения задачи. Новые компоненты и экраны также можно будет развивать в направлении, характерном для VUI, начиная с уже систематизированных решений, а не делая предположения с нуля каждый раз.
Joseph