aperte s para abrir a busca
Storybook Storybook
v1.104.0

# Coruja Web UI

Estratégia Storybook production package unit

# Sumário

# Problemas erros ou novas sugestões e funcionalidades

Caso tenha alguma sugestão de funcionalidade ou erro para reportar, recomendamos que crie uma nova Issue (opens new window), assim conseguimos manter um histório de decisões além de facilitar a gestão do projeto 😄

# Projeto

Esse repositório é dedicado ao desenvolvimento do Design System da Estratégia Educacional o CorujaDS Web. Foi desenvolvido usando essas tecnologias.

# Onboarding para o time de design

Este repositório está preparado para o time de design criar e ajustar componentes do DS com a ajuda do Claude Code (opens new window). O Claude conhece as regras do DS, conversa com você antes de mexer em qualquer coisa, confere o próprio trabalho e abre o PR para a engenharia revisar. Você não precisa saber programar; precisa saber o que quer mudar, de preferência com o Figma ou o protótipo em mãos.

Você não precisa rodar os comandos deste onboarding à mão. Todo o processo, da configuração da máquina à abertura do PR, pode ser feito pedindo ao Claude: "configura meu ambiente", "atualiza o projeto", "abre o Storybook". Os comandos aparecem aqui só como base técnica, para você entender o que acontece em cada passo. Duas coisas dependem de você:

  • instalar o Claude Code;
  • fazer o login no GitHub, que abre o navegador e pede a sua senha.

Antes de instalar qualquer coisa na sua máquina, o Claude pede a sua confirmação.

# Combinados

  • Toda mudança no DS custa tempo da engenharia. Depois que entra, cada produto precisa atualizar a versão, conferir as telas e às vezes adaptar o código. Peça só o que o design precisa, de forma específica.

  • Baseie o pedido no Figma ou no protótipo. O link não é obrigatório, mas ajuda muito na revisão.

  • Um componente por PR. Mudanças grandes viram partes menores, e o Claude sugere como dividir.

  • O DS monta peças visuais. Não entram aqui:

    • componente de uma tela só;
    • regra de negócio, como preço, permissão ou busca de dados;
    • biblioteca externa de componentes.

    Se o pedido cair num desses casos, o Claude explica e sugere outro caminho.

  • Quem aprova e publica é a engenharia. Você valida no Storybook; o merge é feito pelos codeowners.

# O que você precisa ter

  • Conta no GitHub com acesso ao repositório estrategiahq/coruja-web-ui. Se não tiver, peça ao time de engenharia do DS (CO_Front).
  • Claude Code (opens new window) instalado, como extensão do VS Code ou no Terminal.
  • Acesso ao Figma do DS.

# Configuração (só uma vez)

O jeito mais fácil tem duas etapas:

  1. Abra o Claude Code em qualquer pasta e peça "baixa o coruja-web-ui e me ajuda a configurar o ambiente".
  2. Assim que o projeto estiver baixado, abra o Claude Code na pasta coruja-web-ui. É lá que ele conhece as regras do DS, o passo a passo de configuração e os erros comuns de instalação.

Os comandos abaixo mostram o que acontece em cada passo e servem para quem preferir fazer à mão.

Os comandos são para o Terminal do macOS ou do Linux. No Windows:

Na dúvida, fale com o time de engenharia do DS.

  1. Git. No macOS, se ainda não tiver:

    xcode-select --install
    1

  2. nvm, que deixa o Node na versão certa do projeto. O comando abaixo é o das instruções oficiais (opens new window); confira lá se há versão mais nova:

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.41.0/install.sh | bash
    1

    Depois, feche e abra o Terminal.

  3. GitHub CLI e login na sua conta. O login abre o navegador:

    brew install gh   # macOS com Homebrew; sem Homebrew, baixe em https://cli.github.com
gh auth login
    1
    2

  4. Seu nome e e-mail no git, com o mesmo e-mail da conta do GitHub:

    git config --global user.name "Seu Nome"
git config --global user.email "seu-email@estrategia.com"
    1
    2

  5. Baixar o projeto e instalar:

    gh repo clone estrategiahq/coruja-web-ui
cd coruja-web-ui
nvm install
npm install --legacy-peer-deps
    1
    2
    3
    4

  6. Conferir o ambiente:

    node .claude/hooks/ambiente.js --texto
    1

    O resultado tem que terminar com "Ambiente pronto.". Se não terminar, ele mostra o que falta e como resolver.

Se algum passo der erro, mostre a mensagem ao Claude: ele conhece os erros mais comuns de instalação.

# Para começar a trabalhar (todo dia)

  1. Abra o Claude Code na pasta do projeto:

    • VS Code: abra a pasta coruja-web-ui e o painel do Claude;
    • Terminal: rode claude dentro da pasta.

    Na primeira vez, se ele perguntar se você confia na pasta, confirme: é isso que ativa as checagens do projeto. Ao abrir, ele confere o ambiente e avisa se faltar algo.

  2. Peça: "atualiza o projeto e abre o Storybook". O Storybook fica em http://localhost:9009 e mostra todos os componentes. Se você estiver no meio de um trabalho, o Claude atualiza sem perder o que já foi feito.

Por baixo, o Claude roda o equivalente a isto, dependendo de onde você está:

  • Começando um trabalho novo, sem nada em andamento, ele vai para a main atualizada:

    git checkout main
git pull
    1
    2

  • No meio de um trabalho, ele continua na sua branch e só busca as novidades. Trazer as mudanças da main para a sua branch só acontece se você pedir:

    git fetch origin
    1

Nos dois casos, ele termina com:

nvm use
npm install --legacy-peer-deps
npm run story
1
2
3

# Como pedir

Fale como falaria com alguém da engenharia. Por exemplo:

  • "Quero criar um componente de card com imagem, título e etiqueta. O Figma é <link>."
  • "O hover do CButton está diferente do Figma: <link>."
  • "Preciso de um ícone novo de bandeira, que já está no Figma de ícones."
  • "Recebi revisão no meu PR, responde os comentários."
  • "Me ajuda a configurar o ambiente."

Depois do pedido:

  1. O Claude faz perguntas para entender o pedido e confere se ele cabe no DS.
  2. Ele mede o impacto, ou seja, quantos produtos e telas usam o que vai mudar, e classifica a mudança como baixa, média ou alta. Se a mudança for grande, sugere montar um plano antes.
  3. Ele faz a mudança, e você confere o resultado no Storybook, nos temas e no dark mode.
  4. Ele revisa o próprio trabalho, cria a branch, faz o commit e abre o PR.
  5. Você cola um print do Storybook na seção "Prova Visual" do PR, pelo GitHub.
  6. A engenharia revisa. Quando chegarem comentários, peça ao Claude para responder à revisão.

Dúvidas: fale com o time de engenharia do DS (CO_Front).

# Pré-requisitos

# Instalando o Design System no seu projeto

  1. Configure a variável de ambiente NODE_AUTH_TOKEN no seu projeto local para dependências privadas e poder instalar o design system:
$ export NODE_AUTH_TOKEN=<seu token>
1

Não possui um token? Gere um novo através desse link (opens new window), com as permissões repo e read:packages.

  1. Instale esse pacote como dependência do projeto:

    $ npm install @estrategiahq/coruja-web-ui
    1

  2. Importe os estilos:

    import '@estrategiahq/coruja-web-ui/dist/coruja-web-ui.css';

// Caso você deseje utilizar o Tailwind já seguindo os padrões do Chapter Web:
// OBS: Hoje esse import é OBRIGATÓRIO, pois estamos migrando os componentes
// e removendo o Tailwind internamente
import '@estrategiahq/coruja-web-ui/dist/coruja-tailwind.css';
    1
    2
    3
    4
    5
    6

    Normalmente, no arquivo principal da sua aplicação.

  3. Agora é só começar a usar:

    <template>
    <div class="c-container">
      <div class="c-row">
        <div class="c-col">
          <h1 class="c-text-h1 c-text-primary">
            Bem Vindo
          </h1>
          <c-button>Enviar</c-button>
        </div>
      </div>
    </div>
</template>

<script>
import { CButton } from '@estrategiahq/coruja-web-ui'

export default {
  name: 'App',
  components: {
    CButton
  },
}
</script>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23

    Nota: As classes do Design System começam com o prefixo c-.

# Utilizando as utilidades de Sass

Temos também disponível utilidades feitas usando Sass (opens new window), que permitem mais flexibilidade na hora de usar o que o Design System fornece.

Para usar basta importar nosso arquivo Sass:

<style lang="scss">
  @import '~@estrategiahq/coruja-web-ui/dist/sass/utils.scss';

  body {
    // Usa nosso mixin de media-query
    @include c-mq(lg) {
      background-color: red;
    }
  }
</style>
1
2
3
4
5
6
7
8
9
10

Para mais informações consulte nosso guia (opens new window)

# Executando o Design System em ambiente local

  1. Instale as dependências:

    $ npm install --legacy-peer-deps
    1

  2. Para iniciar o storybook:

    $ npm run story
    1

  3. Para iniciar a documentação:

    $ npm run docs
    1

# Tarefas comuns

Aqui temos alguns dos comandos que você pode querer usar:

Comando Uso
npm run build Usa o rollup pra fazer o build do projeto
npm run build:bundle Executa o build do bundle de produção
npm run build:watch Performa um build a cada vez que um arquivo é alterado
npm run build:report Executa o build e, ao final, abre o relatório do bundle analyzer
npm run test Roda a suite de testes
npm run test:clearCache Remove o diretório de cache do Jest
npm run test:watch Inicia uma instância do jest que roda os testes sempre que há uma alteração em um arquivo
npm run docs Inicia a documentação do Design System em vuepress
npm run docs:build Executa o build da documentação. Output encontra-se em docs-dist
npm run story Inicia o storybook do projeto
npm run lint Roda o linter do projeto
npm run lint:fix Corrige os erros apontados pelo linter
npm run healthcheck Executa o healthcheck

# Testes

Os testes são feitos usando o Jest (opens new window). Alguns dos comandos disponíveis (e que podem ser úteis):

# executa os testes
$ npm run test
# limpa o diretório de cache do Jest
$ npm run test:cleanCache
# inicia o Jest e roda os testes a cada nova mudança
$ npm run test:watch
1
2
3
4
5
6
7

# Tecnologias

Este projeto foi feito usando: - VueJS - Sass

Testes: - Jest

Documentação: - Storybook - Vuepress

Bundle Tools - Rollup

# Informações adicionais

# Como contribuir