Design System Club

Integracao Storybook Zeroheight

Introdução

Um Design System é tão valioso quanto é utilizável. Mesmo o sistema mais bem projetado e tecnicamente robusto terá impacto limitado se as equipes não conseguirem entender como e quando usar seus componentes. É aqui que plataformas de documentação como Storybook e Zeroheight se tornam essenciais, transformando um conjunto de componentes e diretrizes em um recurso vivo, interativo e acessível.

O Storybook se estabeleceu como uma ferramenta poderosa para desenvolvedores, permitindo visualizar, testar e documentar componentes de UI em um ambiente isolado. Por outro lado, o Zeroheight oferece uma abordagem mais holística, permitindo criar documentação abrangente que combina diretrizes de design, princípios e componentes técnicos em uma experiência coesa.

A integração eficaz dessas ferramentas com seu Design System cria uma ponte entre design e desenvolvimento, garantindo que todos os membros da equipe tenham acesso às informações de que precisam, no formato mais adequado para seu fluxo de trabalho. Neste artigo, exploraremos como implementar essa integração, desde a configuração técnica até estratégias para manter a documentação sincronizada e relevante ao longo do tempo.

O que é Integração com Storybook/Zeroheight?

A Integração com Storybook/Zeroheight refere-se ao processo de conectar seu Design System a estas plataformas de documentação, criando um ecossistema onde componentes, tokens, diretrizes e exemplos de uso são apresentados de forma coesa e interativa. Esta integração vai além de simplesmente usar estas ferramentas; trata-se de estabelecer um fluxo contínuo de informações entre seu código, seus designs e sua documentação.

Storybook

O Storybook é uma ferramenta de desenvolvimento para criar, testar e documentar componentes de UI de forma isolada. Suas principais características incluem:

  1. Ambiente isolado: Permite visualizar componentes fora do contexto da aplicação.
  2. Stories: Exemplos interativos que mostram diferentes estados e variações de componentes.
  3. Addons: Extensões que adicionam funcionalidades como controles interativos, testes de acessibilidade e visualização responsiva.
  4. Documentação automática: Geração de documentação técnica a partir de comentários e tipos no código.
  5. Testes visuais: Integração com ferramentas de teste visual para detectar regressões.

Zeroheight

O Zeroheight é uma plataforma dedicada à documentação de Design Systems, com foco em criar uma experiência unificada para designers e desenvolvedores. Suas principais características incluem:

  1. Documentação abrangente: Suporte para diretrizes, princípios, componentes e padrões.
  2. Integração com ferramentas de design: Conexão direta com Figma, Sketch e Adobe XD.
  3. Incorporação de código: Capacidade de mostrar exemplos de código junto com designs.
  4. Personalização: Adaptação da aparência e estrutura para alinhar com sua marca.
  5. Controle de versão: Gerenciamento de diferentes versões da documentação.

Integração eficaz

Uma integração eficaz entre seu Design System e estas plataformas envolve:

  • Sincronização automática: Atualizações no código ou design refletem automaticamente na documentação.
  • Consistência visual: Representação visual idêntica de componentes em todas as plataformas.
  • Documentação completa: Combinação de aspectos técnicos e de design para cada componente.
  • Exemplos contextuais: Demonstrações de como os componentes são usados em situações reais.
  • Feedback integrado: Mecanismos para coletar e incorporar feedback dos usuários.
  • Versionamento coordenado: Alinhamento entre versões do código e da documentação.

Esta integração cria um ciclo virtuoso onde a documentação reflete com precisão o estado atual do Design System, facilitando sua adoção e evolução contínua.

Por que é importante?

Implementar uma integração robusta entre seu Design System e plataformas de documentação como Storybook e Zeroheight traz múltiplos benefícios:

  1. Documentação sempre atualizada: Reduz a divergência entre o código real e sua documentação, garantindo que os usuários sempre vejam informações precisas.
  2. Experiência unificada: Cria uma fonte única da verdade que atende às necessidades de diferentes perfis (designers, desenvolvedores, product managers).
  3. Adoção acelerada: Facilita o entendimento e uso do Design System, reduzindo a curva de aprendizado e aumentando a adoção.
  4. Colaboração aprimorada: Estabelece uma linguagem comum entre design e desenvolvimento, facilitando a comunicação e colaboração.
  5. Testes mais eficazes: Permite testar componentes em isolamento, identificando problemas antes que afetem produtos reais.
  6. Feedback contínuo: Cria canais para coletar insights dos usuários do Design System, informando sua evolução.
  7. Onboarding simplificado: Facilita a integração de novos membros da equipe, que podem explorar e entender o sistema rapidamente.
  8. Consistência reforçada: Torna mais visíveis inconsistências ou desvios do Design System, incentivando maior padronização.
  9. Demonstração de valor: Torna tangível o valor do Design System para stakeholders, facilitando a justificativa de investimentos.
  10. Evolução sustentável: Facilita a implementação e comunicação de mudanças no Design System ao longo do tempo.

Como aplicar na prática

Implementar uma integração eficaz entre seu Design System e plataformas de documentação envolve várias etapas:

1. Configurar o Storybook

Comece configurando o Storybook para seu Design System:

Instalação básica

# Instalar Storybook em um projeto existente
npx storybook init

# Ou criar um novo projeto com Storybook
npx create-react-app my-design-system
cd my-design-system
npx storybook init

Estrutura de stories

Organize suas stories de forma consistente:

// Button.stories.js
import { Button } from './Button';

export default {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: {
      options: ['primary', 'secondary', 'tertiary'],
      control: { type: 'select' }
    },
    size: {
      options: ['small', 'medium', 'large'],
      control: { type: 'radio' }
    },
    disabled: {
      control: { type: 'boolean' }
    }
  }
};

// Template básico
const Template = (args) => ;

// Variações do componente
export const Primary = Template.bind({});
Primary.args = {
  variant: 'primary',
  size: 'medium',
  children: 'Primary Button'
};

export const Secondary = Template.bind({});
Secondary.args = {
  variant: 'secondary',
  size: 'medium',
  children: 'Secondary Button'
};

export const Small = Template.bind({});
Small.args = {
  variant: 'primary',
  size: 'small',
  children: 'Small Button'
};

export const Disabled = Template.bind({});
Disabled.args = {
  variant: 'primary',
  size: 'medium',
  disabled: true,
  children: 'Disabled Button'
};

Documentação aprimorada com MDX

Utilize MDX para criar documentação mais rica:

// Button.stories.mdx
import { Meta, Story, Canvas, ArgsTable } from '@storybook/addon-docs';
import { Button } from './Button';

# Button

Buttons expressam ações que os usuários podem realizar no sistema.

## Quando usar

- Para iniciar uma ação
- Para submeter um formulário
- Para confirmar uma decisão

## Variantes


  
    
  
  
    
  
  
    
  


## Tamanhos


  
    
  
  
    
  
  
    
  


## Estados


  
    
  
  
    
  


## Propriedades



## Diretrizes de uso

- Use apenas um botão primário por seção
- Mantenha textos curtos e orientados à ação
- Evite usar muitos botões próximos uns dos outros

Addons essenciais

Configure addons para aprimorar a documentação:

// .storybook/main.js
module.exports = {
  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y',
    'storybook-addon-designs',
    'storybook-dark-mode',
    '@storybook/addon-viewport'
  ],
  framework: '@storybook/react'
};

Tema personalizado

Adapte o Storybook para refletir a identidade do seu Design System:

// .storybook/manager.js
import { addons } from '@storybook/addons';
import { themes } from '@storybook/theming';
import customTheme from './customTheme';

addons.setConfig({
  theme: customTheme,
});

// .storybook/customTheme.js
import { create } from '@storybook/theming';

export default create({
  base: 'light',
  brandTitle: 'Acme Design System',
  brandUrl: 'https://acme.com',
  brandImage: 'https://acme.com/logo.png',

  // UI
  appBg: '#F8F8F8',
  appContentBg: '#FFFFFF',
  appBorderColor: '#E0E0E0',

  // Typography
  fontBase: '"Open Sans", sans-serif',
  fontCode: 'monospace',

  // Colors
  colorPrimary: '#0066CC',
  colorSecondary: '#0066CC',

  // Toolbar default and active colors
  barTextColor: '#333333',
  barSelectedColor: '#0066CC',
  barBg: '#FFFFFF',
});

2. Configurar o Zeroheight

Configure o Zeroheight para criar uma documentação mais abrangente:

Estrutura básica

Organize sua documentação em seções lógicas:

  1. Introdução
    – Visão geral
    – Princípios
    – Como começar
  2. Fundamentos
    – Cores
    – Tipografia
    – Espaçamento
    – Iconografia
    – Grid e Layout
  3. Componentes
    – Formulários
    – Navegação
    – Feedback
    – Visualização de dados
    – Layout
  4. Padrões
    – Fluxos de autenticação
    – Formulários complexos
    – Navegação entre páginas
    – Tratamento de erros
  5. Recursos
    – Downloads
    – Ferramentas
    – Changelog
    – Roadmap

Integração com Figma

Conecte seus componentes do Figma:

  1. Na plataforma Zeroheight, vá para “Configurações” > “Integrações”
  2. Conecte sua conta do Figma
  3. Selecione os arquivos e frames que contêm seus componentes
  4. Configure a sincronização automática para manter a documentação atualizada

Incorporação de código

Adicione exemplos de código aos componentes:

  1. Na seção de componentes, adicione um bloco de código
  2. Cole o snippet relevante ou use a integração com GitHub
  3. Configure a linguagem e estilo de formatação
  4. Adicione comentários explicativos quando necessário

Personalização de marca

Adapte a aparência para refletir sua identidade visual:

  1. Configure cores primárias e secundárias
  2. Adicione seu logotipo
  3. Personalize fontes e estilos
  4. Ajuste a navegação e estrutura conforme necessário

3. Integrar Storybook com Zeroheight

Crie uma conexão entre as duas plataformas:

Incorporação de Storybook no Zeroheight

Exportação de Storybook para Zeroheight

Utilize a integração nativa do Zeroheight:

  1. No Zeroheight, vá para “Configurações” > “Integrações” > “Storybook”
  2. Forneça a URL do seu Storybook publicado
  3. Selecione quais stories deseja importar
  4. Configure a sincronização automática

4. Automatizar a sincronização

Estabeleça processos para manter a documentação atualizada:

Integração contínua para Storybook

# .github/workflows/storybook.yml
name: Deploy Storybook

on:
  push:
    branches:
      - main
      - develop

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '16'

      - name: Install dependencies
        run: npm ci

      - name: Build Storybook
        run: npm run build-storybook

      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@4.1.4
        with:
          branch: gh-pages
          folder: storybook-static

Webhooks para atualização automática

Configure webhooks para notificar o Zeroheight sobre mudanças:

// scripts/notify-zeroheight.js
const fetch = require('node-fetch');

async function notifyZeroheight() {
  try {
    const response = await fetch('https://api.zeroheight.com/v1/webhook/update', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.ZEROHEIGHT_API_KEY}`
      },
      body: JSON.stringify({
        projectId: process.env.ZEROHEIGHT_PROJECT_ID,
        source: 'storybook',
        url: 'https://your-storybook-url.com'
      })
    });

    const data = await response.json();
    console.log('Zeroheight notification sent:', data);
  } catch (error) {
    console.error('Error notifying Zeroheight:', error);
  }
}

notifyZeroheight();

5. Enriquecer a documentação

Vá além da documentação básica para criar um recurso verdadeiramente valioso:

Exemplos contextuais

Mostre componentes em contextos reais de uso:

// ButtonInContext.stories.js
import React from 'react';
import { Button } from './Button';
import { Card } from './Card';
import { Modal } from './Modal';

export default {
  title: 'Examples/ButtonInContext',
};

export const InCard = () => (

Ajuste suas preferências de notificação e privacidade.


  
);

export const InModal = () => (

Tem certeza que deseja excluir este item? Esta ação não pode ser desfeita.


  
);

Diretrizes de acessibilidade

Documente considerações de acessibilidade para cada componente:

## Acessibilidade

### WCAG 2.1 Compliance
Este componente atende aos seguintes critérios:
- 1.4.3 Contraste (Mínimo) (AA)
- 2.1.1 Teclado (A)
- 2.4.7 Foco Visível (AA)

### Teclado e Navegação
- O botão é focável via teclado usando Tab
- Pode ser ativado com Enter ou Space
- Quando em estado de carregamento, mantém o foco mas desabilita a interação

### Leitores de tela
- Usa o atributo `aria-disabled` quando visualmente habilitado mas não interativo
- Inclui `aria-busy="true"` durante o estado de carregamento
- Botões com ícones sem texto incluem `aria-label` descritivo

### Exemplos de implementação
```jsx
// Botão com ícone acessível


// Botão de carregamento



#### Guias de migração

Documente como migrar de versões anteriores:

```mdx
## Guia de migração da v1.x para v2.0

### Mudanças na API

| v1.x | v2.0 | Notas |
|------|------|-------|
| `` | `` | Propriedade `type` renomeada para `variant` |
| `` | `` | Props booleanas substituídas por enum `size` |
| `` | `` | Estilo `flat` renomeado para `tertiary` |

### Exemplo de migração

Antes:
```jsx

Depois:

Utilitário de migração automática

Fornecemos um codemod para ajudar na migração:

npx @acme/design-system-codemod button-v2


### 6. Implementar feedback e métricas

Crie mecanismos para coletar insights sobre o uso da documentação:

#### Feedback direto

Adicione formulários de feedback em cada página:

```jsx
// FeedbackForm.jsx
import React, { useState } from 'react';

export const FeedbackForm = ({ pageId, componentName }) => {
  const [rating, setRating] = useState(null);
  const [comment, setComment] = useState('');
  const [submitted, setSubmitted] = useState(false);

  const handleSubmit = async (e) => {
    e.preventDefault();

    try {
      await fetch('https://api.your-design-system.com/feedback', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          pageId,
          componentName,
          rating,
          comment,
          timestamp: new Date().toISOString()
        })
      });

      setSubmitted(true);
    } catch (error) {
      console.error('Error submitting feedback:', error);
    }
  };

  if (submitted) {
    return

Obrigado pelo seu feedback!

;
  }

  return (

Esta documentação foi útil?

{[1, 2, 3, 4, 5].map((value) => ( ))}

Autor:

nellucci

/

Tags:

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *