diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index c041233..c479a53 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -6,8 +6,8 @@ Obrigado por querer contribuir com o Web Dev Labs! - Melhorias e correções nas anotações (`notes/`) - Novos exemplos práticos em `examples/` -- Exercícios adicionais em `examples/exercises.md` -- Projetos práticos em `examples/projects.md` +- Exercícios adicionais em `notes/pratica/01-exercicios.md` +- Projetos práticos em `notes/pratica/02-projetos.md` Melhorias no **site** (visual, navegação, deploy) são feitas no repositório hub [labs](https://github.com/caramelotech/labs). @@ -50,13 +50,13 @@ As notas são **Markdown puro, sem frontmatter**: - Imagens ficam junto das notas (ex: `notes/secao/assets/img.png`) e são referenciadas com caminho relativo: `![descrição](./assets/img.png)` - Ao criar uma nova subpasta de tema, adicione a seção em `sidebar.json` -### Exercícios (`examples/exercises.md`) +### Exercícios (`notes/pratica/01-exercicios.md`) - Descreva claramente o objetivo - Indique o nível de dificuldade (iniciante / intermediário / avançado) - Inclua critérios de sucesso em formato de checklist -### Projetos (`examples/projects.md`) +### Projetos (`notes/pratica/02-projetos.md`) - Descreva o objetivo e o contexto - Liste os requisitos em formato de checklist diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 8f1cc5c..bdfce3d 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,8 +6,8 @@ - [ ] Nova anotação (`notes/`) - [ ] Novo exemplo (`examples/`) -- [ ] Novo exercício (`examples/exercises.md`) -- [ ] Novo projeto (`examples/projects.md`) +- [ ] Novo exercício (`notes/pratica/01-exercicios.md`) +- [ ] Novo projeto (`notes/pratica/02-projetos.md`) - [ ] Correção de conteúdo existente - [ ] Outro: diff --git a/.gitignore b/.gitignore index 0626409..ea0a7df 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ Thumbs.db # Claude & AI .claude/ +.codex/ bash.exe.stackdump # Personal diff --git a/AGENTS.md b/AGENTS.md index a42d099..2e9465e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,7 @@ As notas são publicadas no site do Caramelo Labs em `https://caramelotech.com.b notes/ # Notas em Markdown puro - cada arquivo vira uma página no site index.md # Página de entrada do lab no site fundamentos/ # Fundamentos de front-end: HTML e CSS + atomic-design/ # Arquitetura de componentes de interface: átomos, moléculas, organismos, templates e páginas frontend-avancado/ # Além do alicerce: JavaScript, React e padrões recentes de data fetching e renderização algoritmos-e-estruturas-de-dados/ # Base para resolver problemas: raciocínio, estruturas de dados, complexidade (Big O), paradigmas de algoritmos e padrões de resolução engenharia-de-software/ # Design e qualidade de código: princípios, padrões e testes @@ -37,7 +38,7 @@ ROADMAP.md # Backlog do que ainda falta cobrir (não publicado no site) O comentário ao lado de cada pasta é o **escopo** dela, não um índice das notas. Adicionar uma nota dentro de um escopo já descrito não exige atualizar esta lista - só mexa aqui quando criar uma seção nova ou quando o escopo de uma pasta mudar de fato. -A ordem das seções segue uma progressão de estudo pensada para entrevistas de backend: da escrita de código (Fundamentos, Algoritmos e Estruturas de Dados, Engenharia de Software, APIs, Databases) até sistemas distribuídos em escala (System Design, Escalabilidade, Sistemas Distribuídos, Transações Distribuídas, Mensageria, Microsserviços, Resiliência, Observabilidade, Entrega Contínua e System Design na Prática). +A ordem das seções segue uma progressão de estudo pensada para entrevistas de backend: da base de front-end (Fundamentos, Atomic Design, Front-end Avançado) e escrita de código (Algoritmos e Estruturas de Dados, Engenharia de Software, APIs, Databases) até sistemas distribuídos em escala (System Design, Escalabilidade, Sistemas Distribuídos, Transações Distribuídas, Mensageria, Microsserviços, Resiliência, Observabilidade, Entrega Contínua e System Design na Prática). ## Padrão de nomenclatura de pastas e arquivos diff --git a/README.md b/README.md index 23ff07d..14dbe72 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,60 @@ # Web Dev Labs -Base de conhecimento sobre **desenvolvimento web** do Caramelo Tech - do HTML ao system design. +Bem-vindo ao **Web Dev Labs**, a trilha aberta do Caramelo Tech sobre **desenvolvimento web**. + +Este repositório existe para ajudar pessoas curiosas a aprender, construir e compartilhar conhecimento em comunidade. A ideia é estudar com calma, praticar com exemplos reais e evoluir junto com outras pessoas que também gostam de tecnologia. As notas deste repositório são publicadas no site do [Caramelo Labs](https://caramelotech.com.br/labs/web-dev/). -## Conteúdo +## O que você vai encontrar -| Tópico | Descrição | -| ------------------------ | ------------------------------------------------------ | -| Fundamentos Web | HTML e CSS | -| Algoritmos e Estruturas de Dados | Big O, estruturas de dados, algoritmos e padrões de resolução | -| Engenharia de Software | Design de código, princípios SOLID | -| APIs | HTTP e REST | -| Databases | SQL e ACID | -| Escalabilidade | Escala vertical, horizontal e organizacional | -| Transações Distribuídas | Consistência entre microsserviços, Sagas, dual-write | -| System Design na Prática | Estudos de caso resolvidos (encurtador de URL) | -| Ferramentas | Git, Conventional Commits, Pull Requests, fluxos e GPG | +- Conteúdo didático em português, pensado para estudo progressivo +- Notas em Markdown publicadas no hub do Caramelo Labs +- Exemplos de código e projetos implementados em `examples/` +- Exercícios e ideias de projetos em `notes/pratica/` +- Espaço aberto para contribuições da comunidade + +## Conteúdo -A ordem das seções segue uma progressão pensada para entrevistas de backend: da escrita de código (Engenharia de Software) até sistemas distribuídos em escala (Transações Distribuídas e System Design na Prática). +| Seção | Escopo | +| -------------------- | ------------------------------------------------------------------------ | +| Fundamentos Web | HTML, CSS e base da plataforma web | +| Front-end e Design | Atomic Design, front-end avançado e organização de interfaces | +| Engenharia e Backend | Algoritmos, engenharia de software, APIs e bancos de dados | +| Arquitetura e Escala | System design, mensageria, microsserviços, resiliência e observabilidade | +| Ferramentas | Git, Conventional Commits, Pull Requests, fluxos e GPG | +| Prática | Exercícios e projetos para aplicar os conteúdos do lab | ## Estrutura do repositório -``` +```text web-dev-labs/ -├── notes/ → Anotações em Markdown puro (publicadas no site do Caramelo Labs) -├── sidebar.json → Seções da barra lateral no site -├── examples/ → Exemplos, exercícios e projetos práticos +├── notes/ -> Notas em Markdown puro publicadas no Caramelo Labs +│ └── pratica/ -> Exercícios e projetos propostos +├── examples/ -> Exemplos de código e projetos implementados de desenvolvimento web +├── sidebar.json -> Ordem das seções no hub +├── .github/ -> Templates e guias de contribuição └── LICENSE ``` -Este repositório contém **apenas conteúdo** - não há build, dependências ou configuração de site. A estrutura web (Astro + Starlight) vive no repositório hub [labs](https://github.com/caramelotech/labs), que busca as notas daqui a cada atualização e publica o site. +Este repositório contém conteúdo e exemplos. A estrutura web que publica os labs vive no repositório hub [labs](https://github.com/caramelotech/labs), que busca as notas daqui e monta o site. + +## Como estudar + +1. Comece pelo [site do lab](https://caramelotech.com.br/labs/web-dev/) ou pelas notas em `notes/` +2. Siga a ordem sugerida em `sidebar.json` +3. Use `examples/` para ver implementações prontas +4. Pratique com os [exercícios](notes/pratica/01-exercicios.md) +5. Aplique os aprendizados nos [projetos](notes/pratica/02-projetos.md) ## Escrevendo notas As notas em `notes/` são Markdown puro, sem frontmatter: - A primeira linha da nota deve ser o título: `# Título da Nota` -- Use prefixo numérico no nome do arquivo para controlar a ordem na barra lateral: `01-introducao.md`, `02-conceitos.md` -- Agrupe por tema em subpastas -- Imagens ficam junto das notas (ex: `notes/secao/assets/img.png`) e são referenciadas com caminho relativo: `![descrição](./assets/img.png)` -- Links para outras notas do site usam o caminho completo: `/labs/web-dev///` +- Use prefixo numérico no nome do arquivo para controlar a ordem: `01-introducao.md`, `02-conceitos.md` +- Agrupe conteúdos por tema em subpastas +- Imagens ficam junto das notas e usam caminho relativo +- Links internos publicados no hub usam o caminho completo: `/labs/web-dev///` Ao criar uma nova subpasta de tema, adicione a seção correspondente em `sidebar.json`. - -## Como usar - -1. Comece pelas anotações em `notes/` (ou pelo [site](https://caramelotech.com.br/labs/web-dev/)) -2. Explore os exemplos em `examples/` -3. Resolva os exercícios em `examples/exercises.md` -4. Construa os projetos em `examples/projects.md` - -## Contribuição - -Contribuições são bem-vindas! Veja o [Guia de Contribuição](.github/CONTRIBUTING.md) para detalhes. - -## Licença - -MIT diff --git a/examples/README.md b/examples/README.md index 82f3088..f751ff9 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,22 +1,17 @@ -# Exemplos +# Examples -Esta pasta concentra os materiais praticos do repositorio. - -## Indice - -| Caminho | Tipo | Descricao | -| --- | --- | --- | -| `exercises.md` | Exercicios | Lista de desafios para praticar os conceitos das notas | -| `projects.md` | Projetos | Propostas de mini projetos para consolidar o aprendizado | +Este diretório reúne exemplos de código e projetos já implementados para acompanhar o conteúdo do Web Dev Labs. ## Como usar -1. Leia a nota relacionada em `src/content/docs/` -2. Resolva um exercicio em `exercises.md` -3. Evolua para um projeto em `projects.md` +1. Escolha um exemplo implementado +2. Leia o README do exemplo, quando existir +3. Execute o código no ambiente indicado +4. Modifique, teste e experimente variações -## Observacao +## Prática guiada -Os exemplos executaveis ainda estao em expansao. Quando novos materiais forem adicionados, este indice deve ser atualizado. +As sugestões de exercícios e projetos ficam publicadas no hub: -Mais detalhes estao em [../.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md). +- [Exercícios](../notes/pratica/01-exercicios.md) +- [Projetos](../notes/pratica/02-projetos.md) diff --git a/notes/atomic-design/01-atomic-design.md b/notes/atomic-design/01-atomic-design.md new file mode 100644 index 0000000..fb91a2f --- /dev/null +++ b/notes/atomic-design/01-atomic-design.md @@ -0,0 +1,145 @@ +# Atomic Design: uma arquitetura para organização de componentes e interfaces + +Atomic Design é um método para organizar componentes de interface criado por Brad Frost, designer e consultor que trabalhou como desenvolvedor mobile na R/GA na época da explosão dos smartphones, e publicou o método em 2013. A ideia surgiu de um problema comum: conforme uma interface cresce, os componentes viram uma bagunça sem hierarquia clara, e fica difícil saber onde um componente novo deveria morar ou o que ele deveria reutilizar. + +A solução de Frost foi tomar emprestada a lógica da química. Átomos se combinam em moléculas, moléculas se agrupam em organismos, e a partir daí você monta a interface completa em templates e páginas. Não é uma metáfora decorativa: ela dá um critério objetivo de "qual o tamanho e a responsabilidade desse componente", que é justamente o que falta quando um projeto vira uma pasta `components/` com quarenta arquivos soltos. + +```mermaid +graph TD + A[Átomos] --> B[Moléculas] + B --> C[Organismos] + C --> D[Templates] + D --> E[Páginas] + + A -.->|"botão, label, input"| A + B -.->|"campo de busca = input + botão"| B + C -.->|"cabeçalho = logo + busca + menu"| C + D -.->|"layout com placeholders"| D + E -.->|"template + conteúdo real"| E +``` + +Referências para quem quiser ir na fonte: + +- [Atomic Design, pelo criador Brad Frost](https://atomicdesign.bradfrost.com/) +- [Atomic Design: o que é, como surgiu e sua importância, por Jéssica Araújo](https://medium.com/pretux/atomic-design-o-que-%C3%A9-como-surgiu-e-sua-import%C3%A2ncia-para-a-cria%C3%A7%C3%A3o-do-design-system-e3ac7b5aca2c) + +## A analogia com a química + +| - | Química | Frontend | +| --------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| Átomo | Possui propriedades distintas e não pode ser quebrado sem perder seu significado | Componentes simples como botões, labels, inputs | +| Molécula | Dois ou mais átomos mantidos juntos por ligações químicas | Combinação de átomos com função básica, como um campo de texto com label e validação | +| Organismo | Conjunto de moléculas que funcionam como uma unidade | Agrupamento de moléculas e/ou átomos formando seções complexas, como o cabeçalho de uma página | + +Essa tabela já dá o essencial dos três primeiros níveis. Os dois seguintes (templates e páginas) não têm um paralelo químico direto no método original, mas completam a arquitetura. + +## Átomos + +São os componentes mais básicos possíveis: um botão, um label, um input, um ícone. Um átomo não pode ser quebrado em pedaços menores sem deixar de fazer sentido como componente de interface isolado. + +Na prática, boa parte dos átomos de um projeto acaba sendo apenas o encapsulamento de um componente vindo de uma biblioteca (Radix, MUI, um design system interno). Isso é normal e não é "atomic design malfeito" - o valor está em ter um lugar único e previsível para essas peças. + +```jsx +// componentes/atomos/Button.jsx +export function Button({ children, variant = "primary", ...props }) { + return ( + + ); +} +``` + +Átomos tendem a nascer simples e ganhar propriedades novas conforme o projeto evolui - um `Button` que hoje só tem `variant` pode ganhar `size`, `loading`, `icon` depois. O cuidado aqui é manter o comportamento atual como padrão de qualquer prop nova, para que os lugares que já usam o átomo não quebrem quando ele ganhar uma funcionalidade. + +Se você está decidindo que tag HTML usar por trás de um átomo, a [tabela periódica dos elementos HTML do allthetags.com](https://allthetags.com/) é uma referência rápida para lembrar o que existe além de `div` e `span`. + +## Moléculas + +Uma molécula é a junção de dois ou mais átomos formando algo com uma função básica própria. Um campo de busca, por exemplo, não é só um `input`: é um `input` mais um `Button` de lupa, funcionando juntos. + +```jsx +// componentes/moleculas/InputComFeedback.jsx +import { Input } from "../atomos/Input"; +import { TextoDeErro } from "../atomos/TextoDeErro"; + +export function InputComFeedback({ label, erro, ...props }) { + return ( +
+ + + {erro && {erro}} +
+ ); +} +``` + +Repare que a molécula não inventa comportamento novo do zero - ela orquestra átomos que já existem. Se você perceber que está escrevendo lógica de negócio dentro de uma molécula (chamar uma API, validar uma regra específica do domínio), é sinal de que aquele componente já cresceu além do papel de molécula. + +## Organismos + +Um organismo agrupa moléculas (e às vezes átomos soltos) para formar uma seção complexa e reconhecível da interface, como um cabeçalho, um formulário completo ou um card de produto com todas as suas partes. + +```jsx +// componentes/organismos/FormularioDeLogin.jsx +import { InputComFeedback } from "../moleculas/InputComFeedback"; +import { Button } from "../atomos/Button"; + +export function FormularioDeLogin({ onSubmit, erros }) { + return ( +
+ + + + + ); +} +``` + +A linha entre molécula e organismo é onde a maioria das dúvidas aparece na prática. Não existe uma regra matemática, mas um critério que ajuda bastante: olhe para a complexidade. Organismos tendem a agrupar uma quantidade maior de moléculas e reúnem funcionalidades distintas que pertencem a um mesmo contexto (por exemplo, um cabeçalho que junta logo, busca e menu de navegação). Se o componente só está combinando duas ou três peças com uma função única e simples, provavelmente ainda é uma molécula. + +## Templates e páginas + +Esses dois níveis não vêm da analogia química, mas completam a arquitetura: + +**Template** é o layout que organiza os organismos, focado na estrutura da tela e não no conteúdo real. Ele tem placeholders que podem ser preenchidos - um exemplo seria a estrutura de uma página de blog sem nenhum texto real dentro. + +**Página** é a instância real de um template, com o conteúdo de verdade carregado (dados vindos de uma API, textos, imagens) e as regras de negócio necessárias para funcionar - por exemplo, a página inicial do produto com tudo já preenchido. + +Pense assim: o template é a planta baixa da casa, a página é a casa mobiliada e com gente morando dentro. + +## Estrutura de pastas + +Uma forma comum de refletir os cinco níveis no código é espelhar a hierarquia direto na árvore de pastas: + +``` +src/ +├── componentes/ +│ ├── atomos/ +│ ├── moleculas/ +│ ├── organismos/ +│ ├── templates/ +│ ├── paginas/ +``` + +Cada pasta guarda só componentes daquele nível, o que facilita achar onde um componente novo deveria entrar: se ele só combina dois ou três átomos com uma função simples, vai em `moleculas/`; se agrupa várias moléculas com funcionalidades distintas, vai em `organismos/`. + +## Vantagens e desvantagens + +Vantagens: + +- **Reutilização**: átomos e moléculas viram peças de lego que qualquer organismo pode reaproveitar, em vez de cada tela reinventar seu próprio botão ou campo de formulário +- **Escalabilidade**: adicionar uma tela nova geralmente significa compor peças que já existem, não escrever tudo do zero +- **Manutenção**: corrigir um bug visual ou de comportamento em um átomo propaga o conserto para todo lugar que o usa + +Desvantagens: + +- **Prop drilling**: como organismos compõem moléculas que compõem átomos, é comum precisar passar uma prop através de várias camadas até ela chegar no componente que realmente precisa dela. Context API, composição de componentes ou uma lib de estado ajudam a evitar isso quando o encadeamento fica grande demais +- **Confusão semântica entre moléculas e organismos**: como não existe um critério matemático exato, times diferentes classificam o mesmo componente de jeitos diferentes. Isso não quebra nada tecnicamente, mas vale alinhar um critério comum no time (como o de complexidade descrito acima) para a nomenclatura não virar debate infinito em code review + +Nenhuma dessas desvantagens é motivo para abandonar o método - só coisas que valem um ajuste conforme a necessidade do projeto, como qualquer decisão de arquitetura. diff --git a/notes/index.md b/notes/index.md index 775953b..a207b1c 100644 --- a/notes/index.md +++ b/notes/index.md @@ -5,6 +5,7 @@ Base de conhecimento sobre **desenvolvimento web** do Caramelo Tech - do HTML ao ## O que você vai encontrar - **Fundamentos Web** - o alicerce do front-end: HTML e CSS +- **Atomic Design** - arquitetura de componentes de interface: da metodologia à estrutura de pastas - **Front-end Avançado** - além do alicerce: JavaScript, React e os padrões mais recentes de data fetching e renderização - **Algoritmos e Estruturas de Dados** - a base para resolver problemas: raciocínio, estruturas de dados, complexidade (Big O) e padrões de resolução - **Engenharia de Software** - escrever código que dá para manter: princípios, padrões e testes @@ -24,7 +25,7 @@ Base de conhecimento sobre **desenvolvimento web** do Caramelo Tech - do HTML ao Navegue pelas seções na barra lateral. Se está começando, comece por Fundamentos Web. -As seções seguem uma progressão pensada para entrevistas de backend: da escrita de código (Algoritmos e Estruturas de Dados, Engenharia de Software, APIs, Databases) até sistemas distribuídos em escala (System Design, Escalabilidade, Sistemas Distribuídos, Transações Distribuídas, Mensageria, Microsserviços, Resiliência, Observabilidade e Entrega Contínua). +As seções seguem uma progressão pensada para entrevistas de backend: da base de frontend (Fundamentos Web, Atomic Design, Front-end Avançado) e escrita de código (Algoritmos e Estruturas de Dados, Engenharia de Software, APIs, Databases) até sistemas distribuídos em escala (System Design, Escalabilidade, Sistemas Distribuídos, Transações Distribuídas, Mensageria, Microsserviços, Resiliência, Observabilidade e Entrega Contínua). ## Além das notas diff --git a/examples/exercises.md b/notes/pratica/01-exercicios.md similarity index 99% rename from examples/exercises.md rename to notes/pratica/01-exercicios.md index 85d100b..d563512 100644 --- a/examples/exercises.md +++ b/notes/pratica/01-exercicios.md @@ -1,4 +1,4 @@ -# Exercicios +# Exercícios Pratique o que aprendeu nas anotacoes e exemplos. diff --git a/examples/projects.md b/notes/pratica/02-projetos.md similarity index 100% rename from examples/projects.md rename to notes/pratica/02-projetos.md diff --git a/sidebar.json b/sidebar.json index 3aef078..0ee199b 100644 --- a/sidebar.json +++ b/sidebar.json @@ -1,22 +1,85 @@ { "sections": [ - { "label": "Visão geral", "slug": "." }, - { "label": "Fundamentos Web", "directory": "fundamentos" }, - { "label": "Front-end Avançado", "directory": "frontend-avancado" }, - { "label": "Algoritmos e Estruturas de Dados", "directory": "algoritmos-e-estruturas-de-dados" }, - { "label": "Engenharia de Software", "directory": "engenharia-de-software"}, - { "label": "APIs", "directory": "apis" }, - { "label": "Databases", "directory": "banco-de-dados" }, - { "label": "System Design", "directory": "system-design" }, - { "label": "Escalabilidade e Infraestrutura", "directory": "escalabilidade" }, - { "label": "Sistemas Distribuídos", "directory": "sistemas-distribuidos" }, - { "label": "Transações Distribuídas", "directory": "transacoes-distribuidas"}, - { "label": "Mensageria", "directory": "mensageria" }, - { "label": "Microsserviços", "directory": "microsservicos" }, - { "label": "Resiliência", "directory": "resiliencia" }, - { "label": "Observabilidade", "directory": "observabilidade" }, - { "label": "Entrega Contínua", "directory": "entrega-continua" }, - { "label": "System Design na Prática", "directory": "estudos-de-caso" }, - { "label": "Ferramentas", "directory": "ferramentas" } + { + "label": "Visão geral", + "slug": "." + }, + { + "label": "Fundamentos Web", + "directory": "fundamentos" + }, + { + "label": "Atomic Design", + "directory": "atomic-design" + }, + { + "label": "Front-end Avançado", + "directory": "frontend-avancado" + }, + { + "label": "Algoritmos e Estruturas de Dados", + "directory": "algoritmos-e-estruturas-de-dados" + }, + { + "label": "Engenharia de Software", + "directory": "engenharia-de-software" + }, + { + "label": "APIs", + "directory": "apis" + }, + { + "label": "Databases", + "directory": "banco-de-dados" + }, + { + "label": "System Design", + "directory": "system-design" + }, + { + "label": "Escalabilidade e Infraestrutura", + "directory": "escalabilidade" + }, + { + "label": "Sistemas Distribuídos", + "directory": "sistemas-distribuidos" + }, + { + "label": "Transações Distribuídas", + "directory": "transacoes-distribuidas" + }, + { + "label": "Mensageria", + "directory": "mensageria" + }, + { + "label": "Microsserviços", + "directory": "microsservicos" + }, + { + "label": "Resiliência", + "directory": "resiliencia" + }, + { + "label": "Observabilidade", + "directory": "observabilidade" + }, + { + "label": "Entrega Contínua", + "directory": "entrega-continua" + }, + { + "label": "System Design na Prática", + "directory": "estudos-de-caso" + }, + { + "label": "Ferramentas", + "directory": "ferramentas" + }, + { + "label": "Prática", + "directory": "pratica" + } ] } +