Как да структурирате Storybook, който служи като договор

Storybook не е галерия

През 2024 г. от почти 17 милиона сайта, анализирани от Web Almanac, само 29 % от мобилните сайтове са имали текст с достатъчен контраст. Седем от десет не се четат добре на телефон и почти нито един не е бил такъв нарочно: никой не е проверил. Много екипи инсталират Storybook, пишат двадесет истории и го изоставят след три месеца. Проблемът не е в инструмента: използван е като витрина, а не като това, което може да бъде — визуалният и поведенческият договор между дизайн, разработка и QA. Договорът казва какво съществува, как се използва, в какви състояния може да бъде и какво не е позволено. Той не замества дизайнерските решения, нито договора на API-тата; той е най-полезното доказателство как се държи интерфейсът.

1. Йерархия със зависимости, които текат надолу

Използваме Atomic Design като речник за композиция — атоми, молекули, организми — и го разширяваме, когато помага да се управлява продуктът:

Основи → Атоми → Молекули → Организми → Секции → Страници

• Основи: цветове, типография, разстояния, визуални шаблони. Те не са компоненти: те са правилата.
• Атоми: бутон, поле, икона, значка. Не познават бизнес правила, макар да имат собствено поведение.
• Молекули: поле със своя етикет и своята грешка; карта.
• Организми: заглавна част, долен колонтитул, цяла форма.
• Секции: блокове със съдържание, настройвани чрез свойства, вместо да се копират от страница на страница.
• Страници: организират данните, маршрутите и контекста; повторно използваемата логика за представяне живее долу.

Това е архитектурна конвенция, а не универсален закон. Правилото, което я прави полезна, е посоката: базовият слой никога не внася слой на продукта. Това не пречи промяна в токен или в споделен компонент да засегне страниците — трябва да ги засегне, — но прави въздействието проследимо и задължава онези, които го ползват, да проверят.

Знаете ли днес кои екрани се променят, ако утре се смени основният цвят на марката Ви?

2. Основите — като текст, който се чете

Преди първия бутон документирайте основите като разказни страници в самия Storybook: палитрата и кога се използва всеки цвят, типографията и нейната йерархия, визуалните шаблони. И нека живеят като токени: цветът не се пише в компонента, а се взема от токена. Така смяната на марката е смяна на един токен, а визуалната регресия Ви казва какво друго се е променило. (Стандартният формат на токените все още е чернова и самият му текст моли да не се внедрява засега: токените се определят във Вашата система и се експортират, когато стандартът се стабилизира.)

3. Всяка история отговаря на четири въпроса

1. Какво е и кога се използва (и кога не).
2. Вариантите ѝ: размери, тонове, с икона или без нея.
3. Състоянията ѝ: зарежда се, празно, с грешка, деактивирано, изпраща се, и граничните случаи — дълги текстове, непълни данни, бавни отговори. Там изживяването се чупи.
4. Достъпността ѝ: как я обявява екранен четец, какво става с клавиатурата и фокуса, какво става, ако потребителят е поискал по-малко движение.

// Илюстративно (Storybook 9, CSF3). Предполага: type Story = StoryObj<typeof meta>
// и че expect се внася от пътя към помощните средства за тестове на Вашата версия.
export const ConError: Story = {
  args: { etiqueta: "Correo", error: "Escriba un correo válido" },
  play: async ({ canvas }) => {
    const campo = canvas.getByLabelText("Correo");
    await expect(campo).toHaveAttribute("aria-invalid", "true");
    await expect(canvas.getByRole("alert")).toBeVisible();
  },
};

Историята фиксира състояние на грешка и проверява неговата семантика: че полето е отбелязано като невалидно и че съобщението се излага като предупреждение. Това я доближава до договор. За критичните потоци освен това се проверява на ръка с клавиатура и с екранен четец: автоматичното не покрива всичко.

4. Три вида проверка, а не една

• Тестове за взаимодействие: състоянията и поведението да са очакваните, както в примера.
• Автоматична проверка на достъпността във всяка история: контраст, роли, достъпни имена. Внимавайте с границите ѝ: средно автоматичните тестове откриват 57 % от проблемите с достъпността (Deque, върху над 13 000 страници), а правилото за минималния размер на докосваните бутони от WCAG 2.2 е изключено по подразбиране в най-използвания инструмент. Трябва да се включи на ръка; останалото се покрива с проверка с клавиатура и екранен четец.
• Визуална регресия: тази, която открива, че промяна в токен е преместила нещо на двадесет екрана, които никой не е отварял.

Заедно те превръщат един каталог в договор.

5. Контекстът — от лентата с инструменти

Ако продуктът Ви използва няколко езика или светла и тъмна тема, изложете ги като глобални контроли на Storybook, свързани чрез декоратори със същите доставчици на контекст като реалното приложение. Използвайте ги, за да изследвате рисковите комбинации — бутонът, който не се събира на немски, текстът, който изчезва в тъмна тема — и определете кои комбинации се тестват винаги.

6. Публикува се сам

Storybook, който някой трябва да се сети да публикува, вече е остарял. Публикува се автоматично при интегриране на одобрени промени, като справка, която дизайнът, QA и клиентът могат да отворят, с достъпа, който изисква чувствителността на продукта. Тази справка е тази, която се преглежда, а не снимка на екрана в чат.

7. Кога нещо се издига на ново ниво

Примитивите на марката — бутон, поле, типография — се раждат като част от системата от първия ден. За останалото:

• Повторението е сигнал, а не праг. Един шаблон се консолидира, когато намерението и вариантите му вече са стабилни; абстрахирането по-рано обикновено струва повече от един видим дубликат. На практика това рядко става преди третото използване.
• Споделянето между проекти изисква управление. Когато втори продукт се нуждае от същите компоненти, системата става пакет с ясен собственик, версии и път за възприемане; там Storybook обикновено става най-полезната справка, без да замества документацията на решенията.

Какво още ни липсва, казано на глас

Проверяваме достъпността автоматично във всяка история, но днес проверката предупреждава, а не блокира. Стъпката, която много екипи отлагат — и която ние изискваме като следваща — е грешка в достъпността или счупено състояние да спре публикуването, както един червен тест. Договор, който не може да спре една промяна, е само предложение.

Следва в поредицата: Парадигмите на модерния фронтенд, без димна завеса · Какво трябва да има един професионален фронтенд, преди да излезе в продукция.