Ryanditko · Ryanditko · Jul 24, 2026 · Jul 24, 2026
@@ -1,34 +1,92 @@
 # To-do List App
 
-## Idea
-Build a simple to-do list application where users can add, complete, and delete tasks. Learn fundamentals of DOM manipulation, state management, and local storage.
+> 🌐 **English** · [Português](./README.pt-BR.md)
+
+**Domain:** Frontend · **Level:** Beginner · **Estimated time:** 3–6 hours
+
+## Overview
+
+Build the classic to-do list: a single screen where a user types a task, presses Enter, sees it appear, checks it off when done, and removes it when it no longer matters. It looks trivial, but it is the smallest complete example of the core frontend loop — user input changes state, and state re-renders the UI. Everything is driven by an in-memory array of task objects that you persist to `localStorage` so the list survives a page reload. There is no server and no framework requirement; the interesting work is keeping your data model and what the user sees perfectly in sync.
+
+## Prerequisites
+
+- Basic HTML, CSS, and JavaScript (variables, arrays, functions)
+- How to read from and write to the DOM, or a component framework of your choice
+- Familiarity with array methods (`map`, `filter`, `find`)
+- A code editor and a browser with dev tools
 
 ## Learning Objectives
-- Understand DOM manipulation
-- Implement state management basics
-- Use local storage for persistence
-- Build interactive UI
-- Handle user events
-
-## Implementation Tips
-- Create task objects with id, title, completed status
-- Store tasks in local storage
-- Implement add task functionality
-- Add complete/uncomplete toggle
-- Implement delete task
-- Add visual feedback for completed tasks
-- Create clear all completed tasks button
-- Add task count display
-- Implement filter (all/active/completed)
-- Add keyboard shortcuts (Enter to add)
-- Create animations for task operations
-- Add task editing capability
-- Implement due dates (optional)
-- Create themed styling
-
-## Key Challenges
-- Local storage synchronization
-- State consistency
-- UI responsiveness
-- Local storage size limits
-- Task ordering and sorting
+
+By the end, you should be able to:
+
+- Model UI as a function of a single source-of-truth state
+- Add, toggle, edit, and delete items immutably rather than mutating in place
+- Persist and rehydrate state with the `localStorage` API
+- Render a filtered view (all / active / completed) without losing the underlying data
+- Wire up keyboard and click interactions with accessible, labelled controls
+
+## Functional Requirements
+
+1. The user can type a task and add it by pressing Enter or clicking an Add button.
+2. Empty or whitespace-only tasks must be rejected without adding a blank row.
+3. Each task can be toggled between active and completed, with a clear visual difference.
+4. The user can delete any individual task.
+5. A live counter shows how many tasks remain active.
+6. The user can filter the list by all, active, or completed.
+7. The full list must survive a page refresh via `localStorage`.
+
+## Suggested Milestones
+
+1. **Milestone 1 — Add & render:** Capture input, push a task object to state, render the list.
+2. **Milestone 2 — Toggle & delete:** Mark tasks done and remove them, updating the counter.
+3. **Milestone 3 — Filter & persist:** Add the filter view and save/load from `localStorage`.
+
+## Data & Interface Sketch
+
+```text
+Task
+  id:        string   (crypto.randomUUID())
+  title:     string
+  completed: boolean
+  createdAt: number   (Date.now())
+
+Layout
++------------------------------------------+
+| [ new task input............ ] [ Add ]   |
++------------------------------------------+
+| [x] Buy milk                      (del)  |
+| [ ] Call dentist                  (del)  |
++------------------------------------------+
+| 1 item left   [All] [Active] [Completed] |
++------------------------------------------+
+```
+
+## Stretch Goals
+
+- Inline edit: double-click a task title to rename it.
+- Add a "Clear completed" button that removes all done tasks at once.
+- Allow reordering tasks by drag-and-drop.
+- Add a light/dark theme toggle stored alongside the tasks.
+
+## Definition of Done
+
+- [ ] Adding, toggling, and deleting update both the UI and stored state.
+- [ ] Blank tasks cannot be added.
+- [ ] The remaining-items counter is always accurate after any action.
+- [ ] Filters change the visible list without discarding hidden tasks.
+- [ ] Reloading the page restores the exact previous list.
+
+## Common Pitfalls
+
+- Mutating the state array directly instead of producing a new one, causing stale renders.
+- Storing rendered HTML strings instead of a clean data model, making filters and edits painful.
+- Forgetting to `JSON.parse` / `JSON.stringify` around `localStorage`, which only stores strings.
+- Using array index as a key/id, which breaks after deletion and reordering.
+- Skipping labels on the checkbox and buttons, leaving the app unusable with a screen reader.
+
+## Resources
+
+- [MDN: Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API) — how `localStorage` works and its limits.
+- [MDN: Introduction to the DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction) — reading and updating the page.
+- [web.dev: Learn Accessibility — Forms](https://web.dev/learn/accessibility/forms) — labelling inputs and controls.
+- [roadmap.sh: Frontend](https://roadmap.sh/frontend) — where these fundamentals sit in the bigger picture.
@@ -0,0 +1,92 @@
+# Aplicativo de Lista de Tarefas
+
+> 🌐 [English](./README.md) · **Português**
+
+**Domínio:** Frontend · **Nível:** Iniciante · **Tempo estimado:** 3–6 horas
+
+## Visão Geral
+
+Construa a clássica lista de tarefas: uma única tela onde o usuário digita uma tarefa, pressiona Enter, a vê aparecer, marca como concluída e a remove quando não importa mais. Parece trivial, mas é o menor exemplo completo do laço central do frontend — a entrada do usuário muda o estado, e o estado re-renderiza a UI. Tudo é conduzido por um array de objetos de tarefa em memória que você persiste no `localStorage` para que a lista sobreviva a um recarregamento. Não há servidor nem exigência de framework; o trabalho interessante é manter seu modelo de dados e o que o usuário vê perfeitamente sincronizados.
+
+## Pré-requisitos
+
+- HTML, CSS e JavaScript básicos (variáveis, arrays, funções)
+- Como ler e escrever no DOM, ou um framework de componentes à sua escolha
+- Familiaridade com métodos de array (`map`, `filter`, `find`)
+- Um editor de código e um navegador com ferramentas de desenvolvedor
+
+## Objetivos de Aprendizado
+
+Ao final, você deve ser capaz de:
+
+- Modelar a UI como uma função de um único estado como fonte da verdade
+- Adicionar, alternar, editar e excluir itens de forma imutável em vez de mutar no lugar
+- Persistir e reidratar o estado com a API `localStorage`
+- Renderizar uma visão filtrada (todas / ativas / concluídas) sem perder os dados subjacentes
+- Conectar interações de teclado e clique com controles acessíveis e rotulados
+
+## Requisitos Funcionais
+
+1. O usuário pode digitar uma tarefa e adicioná-la pressionando Enter ou clicando em um botão Adicionar.
+2. Tarefas vazias ou só com espaços devem ser rejeitadas sem adicionar uma linha em branco.
+3. Cada tarefa pode ser alternada entre ativa e concluída, com uma diferença visual clara.
+4. O usuário pode excluir qualquer tarefa individual.
+5. Um contador ao vivo mostra quantas tarefas permanecem ativas.
+6. O usuário pode filtrar a lista por todas, ativas ou concluídas.
+7. A lista completa deve sobreviver a um recarregamento da página via `localStorage`.
+
+## Marcos Sugeridos
+
+1. **Marco 1 — Adicionar e renderizar:** Capture a entrada, adicione um objeto de tarefa ao estado, renderize a lista.
+2. **Marco 2 — Alternar e excluir:** Marque tarefas como feitas e remova-as, atualizando o contador.
+3. **Marco 3 — Filtrar e persistir:** Adicione a visão de filtro e salve/carregue do `localStorage`.
+
+## Esboço de Dados e Interface
+
+```text
+Tarefa
+  id:        string   (crypto.randomUUID())
+  title:     string
+  completed: boolean
+  createdAt: number   (Date.now())
+
+Layout
++------------------------------------------+
+| [ nova tarefa............... ] [Adicionar]|
++------------------------------------------+
+| [x] Comprar leite                 (del)  |
+| [ ] Ligar para o dentista         (del)  |
++------------------------------------------+
+| 1 item restante  [Todas][Ativas][Feitas] |
++------------------------------------------+
+```
+
+## Desafios Extras
+
+- Edição em linha: dê um duplo clique no título de uma tarefa para renomeá-la.
+- Adicione um botão "Limpar concluídas" que remove todas as tarefas feitas de uma vez.
+- Permita reordenar tarefas com arrastar e soltar.
+- Adicione um alternador de tema claro/escuro armazenado junto com as tarefas.
+
+## Definição de Pronto
+
+- [ ] Adicionar, alternar e excluir atualizam tanto a UI quanto o estado armazenado.
+- [ ] Tarefas em branco não podem ser adicionadas.
+- [ ] O contador de itens restantes está sempre correto após qualquer ação.
+- [ ] Os filtros mudam a lista visível sem descartar tarefas ocultas.
+- [ ] Recarregar a página restaura exatamente a lista anterior.
+
+## Armadilhas Comuns
+
+- Mutar o array de estado diretamente em vez de produzir um novo, causando renderizações desatualizadas.
+- Armazenar strings de HTML renderizado em vez de um modelo de dados limpo, tornando filtros e edições penosos.
+- Esquecer o `JSON.parse` / `JSON.stringify` em torno do `localStorage`, que só armazena strings.
+- Usar o índice do array como chave/id, o que quebra após exclusão e reordenação.
+- Pular rótulos nas caixas de seleção e botões, deixando o app inutilizável com um leitor de tela.
+
+## Recursos
+
+- [MDN: Web Storage API](https://developer.mozilla.org/pt-BR/docs/Web/API/Web_Storage_API) — como o `localStorage` funciona e seus limites.
+- [MDN: Introdução ao DOM](https://developer.mozilla.org/pt-BR/docs/Web/API/Document_Object_Model/Introduction) — ler e atualizar a página.
+- [web.dev: Learn Accessibility — Forms](https://web.dev/learn/accessibility/forms) — rotular entradas e controles.
+- [roadmap.sh: Frontend](https://roadmap.sh/frontend) — onde esses fundamentos se encaixam no quadro maior.
@@ -1,34 +1,93 @@
 # Calculator UI
 
-## Idea
-Create a functional calculator UI with basic arithmetic operations. Learn about event handling, string manipulation, and UI state management.
+> 🌐 **English** · [Português](./README.pt-BR.md)
+
+**Domain:** Frontend · **Level:** Beginner · **Estimated time:** 3–6 hours
+
+## Overview
+
+Build a working calculator with a keypad, a display, and the four basic operations. The visual layout is the easy half; the real lesson is modelling calculator behaviour as a small state machine. A user taps `7`, `+`, `3`, `=` — each key means something different depending on what came before. You will track the current entry, the pending operator, and the accumulated value, and decide what every button does in every state. Get that model right and edge cases like chaining operations or pressing `=` twice stop being surprises.
+
+## Prerequisites
+
+- Basic HTML, CSS, and JavaScript
+- CSS Grid or Flexbox for laying out a button pad
+- Comfort with `switch`/conditional logic and number parsing
+- A code editor and a browser with dev tools
 
 ## Learning Objectives
-- Handle button click events
-- Manage calculator state
-- Implement operation logic
-- Format number display
-- Handle edge cases
-
-## Implementation Tips
-- Design calculator layout with buttons
-- Implement number input handling
-- Add arithmetic operations (+, -, *, /)
-- Implement equals functionality
-- Add clear/reset button
-- Display current calculation
-- Handle decimal numbers
-- Implement backspace functionality
-- Add operation chaining
-- Implement percentage calculation
-- Add keyboard support
-- Create responsive design
-- Add operation history (optional)
-- Implement memory functions (optional)
-
-## Key Challenges
-- Floating point precision
-- Operation chaining logic
-- State management during calculations
-- Keyboard vs mouse input
-- Error handling (division by zero)
+
+By the end, you should be able to:
+
+- Represent interactive behaviour as explicit state rather than reading the display back as data
+- Handle operator precedence for a simple left-to-right calculator and chained operations
+- Format numeric output and avoid raw floating-point artefacts
+- Support both mouse/touch and physical keyboard input for the same actions
+- Guard against invalid states like multiple decimals or division by zero
+
+## Functional Requirements
+
+1. The calculator performs addition, subtraction, multiplication, and division.
+2. The display shows the number being entered and the result after `=`.
+3. Pressing an operator after a result uses that result as the new left operand (chaining).
+4. A clear button resets all state; a backspace removes the last entered digit.
+5. Only one decimal point is allowed per number.
+6. Division by zero shows a clear error state rather than `Infinity` or `NaN`.
+7. Number and operator keys on the physical keyboard mirror the on-screen buttons.
+
+## Suggested Milestones
+
+1. **Milestone 1 — Entry & display:** Build the keypad and show digits, decimals, and backspace.
+2. **Milestone 2 — Single operation:** Store an operator and left operand, compute on `=`.
+3. **Milestone 3 — Chaining & guards:** Chain operations, handle clear, decimals, and divide-by-zero.
+
+## Data & Interface Sketch
+
+```text
+State
+  current:   string    (digits being typed, e.g. "12.5")
+  operator:  "+"|"-"|"*"|"/"|null
+  accumulator: number|null
+  justEvaluated: boolean
+
+Layout (4-column grid)
++-------------------------------+
+|            123.45             |  <- display
++-------------------------------+
+|  C  | +/- |  %  |   /         |
+|  7  |  8  |  9  |   *         |
+|  4  |  5  |  6  |   -         |
+|  1  |  2  |  3  |   +         |
+|    0      |  .  |   =         |
++-------------------------------+
+```
+
+## Stretch Goals
+
+- Add a running history/tape of previous calculations.
+- Add memory keys (M+, M-, MR, MC).
+- Support percentage relative to the current accumulator.
+- Add a keyboard-only mode with visible focus indicators on each key.
+
+## Definition of Done
+
+- [ ] All four operations produce correct results, including chained sequences.
+- [ ] The display never shows `NaN`, `Infinity`, or `undefined`.
+- [ ] Clear fully resets state; backspace edits the current entry only.
+- [ ] Keyboard and on-screen buttons behave identically.
+- [ ] Only one decimal point can be entered per number.
+
+## Common Pitfalls
+
+- Using the display text as your source of truth instead of a separate state model.
+- Concatenating strings for math and getting `"1" + "2" = "12"` instead of `3`.
+- Ignoring floating-point rounding, so `0.1 + 0.2` shows `0.30000000000000004`.
+- Forgetting the "just evaluated" flag, so the next digit appends to the result instead of starting fresh.
+- Leaving buttons as non-focusable `<div>`s, breaking keyboard access.
+
+## Resources
+
+- [MDN: Number.prototype.toFixed()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed) — controlling decimal display.
+- [MDN: CSS Grid Layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout) — laying out the keypad.
+- [0.30000000000000004.com](https://0.30000000000000004.com/) — why floating-point math misbehaves.
+- [MDN: KeyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key) — mapping physical keys to actions.