felurye · Oct 12, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026 · Aug 26, 2026
diff --git 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
@@ -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: <!-- descreva -->
 

diff --git 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
@@ -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
@@ -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/<secao>/<nota>/`
+- 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/<secao>/<arquivo-com-prefixo>/`
 
 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
@@ -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
@@ -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 (
+    <button className={`btn btn-${variant}`} {...props}>
+      {children}
+    </button>
+  );
+}
+```
+
+Á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 (
+    <div>
+      <label>{label}</label>
+      <Input aria-invalid={!!erro} {...props} />
+      {erro && <TextoDeErro>{erro}</TextoDeErro>}
+    </div>
+  );
+}
+```
+
+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 (
+    <form onSubmit={onSubmit}>
+      <InputComFeedback label="E-mail" name="email" erro={erros?.email} />
+      <InputComFeedback
+        label="Senha"
+        name="senha"
+        type="password"
+        erro={erros?.senha}
+      />
+      <Button type="submit">Entrar</Button>
+    </form>
+  );
+}
+```
+
+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.