Skip to content

Commit 7640f30

Browse files
gbfonsecagbfonseca
committed
feat: add performance metrics documentation in English and Portuguese
1 parent c977811 commit 7640f30

4 files changed

Lines changed: 340 additions & 0 deletions

File tree

‎en/docs/concepts/.pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ nav:
66
- Eitri CLI: eitri-cli.md
77
- Eitri Luminus: eitri-luminus.md
88
- Eitri Play: eitri-play.md
9+
- Performance Metrics: performance-metrics.md

‎en/docs/concepts/performance-metrics.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Performance Metrics — Eitri App
2+
3+
> Metrics are collected automatically on every app load and displayed directly in the terminal during the development cycle.
4+
5+
---
6+
7+
## Captured Metrics
8+
9+
| Metric | Type | Description |
10+
| -------- | ---------------------- | -------------------------------------------- |
11+
| `cls` | Visual stability | Cumulative Layout Shift |
12+
| `fcp` | Loading speed | First Contentful Paint |
13+
| `lcp` | Loading speed | Largest Contentful Paint |
14+
| `load` | Navigation timing | Start of the page load event |
15+
| `score` | Calculated | Weighted performance score (0–100) |
16+
| `rating` | Calculated | Human-readable rating based on the score |
17+
18+
---
19+
20+
## CLS — Cumulative Layout Shift
21+
22+
**What it measures:** Quantifies how much visible content shifts unexpectedly during the page lifecycle. A layout shift occurs when an element changes position between rendered frames without user interaction.
23+
24+
**Formula:**
25+
26+
```
27+
layout shift score = impact fraction × distance fraction
28+
```
29+
30+
**Impact fraction** — portion of the viewport affected by the unstable element:
31+
32+
![CLS impact fraction example](https://web.dev/static/articles/cls/image/impact-fraction-example-164341c82ee76.png){ .off-glb }
33+
34+
**Distance fraction** — largest distance the element traveled relative to the viewport:
35+
36+
![CLS distance fraction example](https://web.dev/static/articles/cls/image/distance-fraction-example-9146d2a862482.png){ .off-glb }
37+
38+
CLS accumulates all unexpected layout shift scores throughout the entire page lifecycle.
39+
40+
**Thresholds (official Web Vitals):**
41+
42+
![CLS threshold chart](https://web.dev/static/articles/cls/image/good-cls-values-are-01-a42d66f2d0f42.svg){ .off-glb }
43+
44+
| Rating | Value |
45+
| ---------------- | ---------- |
46+
| Good | ≤ 0.1 |
47+
| Needs improvement| 0.1 – 0.25 |
48+
| Poor | > 0.25 |
49+
50+
**Eitri target (stricter — optimized for Eitri-App):**
51+
52+
| Rating | Value |
53+
| ------ | ------ |
54+
| Good | ≤ 0.05 |
55+
| Poor | > 0.1 |
56+
57+
**Why it matters:** Unexpected shifts cause users to lose their reading position, tap wrong buttons, or perform unintended actions (e.g., accidentally confirming a purchase). Especially critical in Eitri-App, where touch targets are smaller.
58+
59+
---
60+
61+
## FCP — First Contentful Paint
62+
63+
**What it measures:** Time from navigation start until any content (text, image, SVG, non-white canvas) is rendered on screen for the first time. It is the earliest signal that the page is responding.
64+
65+
![FCP timeline example](https://web.dev/static/articles/fcp/image/fcp-timeline-googlecom.png){ .off-glb }
66+
67+
**Thresholds (official Web Vitals):**
68+
69+
![FCP threshold chart](https://web.dev/static/articles/fcp/image/good-fcp-values-are-18-s-421f9e1a2cc56.svg){ .off-glb }
70+
71+
| Rating | Value |
72+
| ---------------- | ------------- |
73+
| Good | ≤ 1.8 s |
74+
| Needs improvement| 1.8 s – 3.0 s |
75+
| Poor | > 3.0 s |
76+
77+
**Eitri target (stricter — optimized for Eitri-App):**
78+
79+
| Rating | Value |
80+
| ------ | --------- |
81+
| Good | ≤ 800 ms |
82+
| Poor | > 1800 ms |
83+
84+
**Why it matters:** FCP is the user's first visual confirmation that something is happening. A slow FCP increases perceived wait time and abandonment rates, even if the page eventually loads fully.
85+
86+
---
87+
88+
## LCP — Largest Contentful Paint
89+
90+
**What it measures:** Render time of the largest visible element in the viewport (image, text block, video poster). Marks the point at which the page's main content has likely been loaded.
91+
92+
**Real-world examples of LCP elements across different sites:**
93+
94+
![LCP example — CNN](https://web.dev/static/articles/lcp/image/largest-contentful-paint-fc43128e011aa.png){ .off-glb }
95+
![LCP example — TechCrunch](https://web.dev/static/articles/lcp/image/largest-contentful-paint-3713e2f14970a.png){ .off-glb }
96+
97+
**Considered elements:**
98+
99+
- `<img>` (including the first frame of animated images)
100+
- `<image>` inside `<svg>`
101+
- `<video>` (poster or first frame, whichever comes first)
102+
- Elements with CSS `background-image: url()`
103+
- Block-level elements containing text content
104+
105+
**Thresholds (official Web Vitals):**
106+
107+
![LCP threshold chart](https://web.dev/static/articles/lcp/image/good-lcp-values-are-25-s-28836be83d1aa.svg){ .off-glb }
108+
109+
| Rating | Value |
110+
| ---------------- | ------------- |
111+
| Good | ≤ 2.5 s |
112+
| Needs improvement| 2.5 s – 4.0 s |
113+
| Poor | > 4.0 s |
114+
115+
**Eitri target (stricter — optimized for Eitri-App):**
116+
117+
| Rating | Value |
118+
| ------ | --------- |
119+
| Good | ≤ 1000 ms |
120+
| Poor | > 2500 ms |
121+
122+
**Why it matters:** A fast LCP signals to the user that the page is useful and ready for interaction. It directly correlates with perceived loading performance and is the Core Web Vital with the highest impact on user retention.
123+
124+
---
125+
126+
## LOAD — Page Load Event
127+
128+
**What it measures:** Time (in ms) from navigation start until the `load` event fires in the application. Indicates that all synchronous resources (scripts, stylesheets, images referenced in JSX) have finished loading.
129+
130+
> This is a **navigation timing metric**, not a Core Web Vital. It is captured for diagnostic purposes — a slow `load` combined with a fast `LCP` may indicate heavy deferred resources.
131+
132+
---
133+
134+
## Score (0–100)
135+
136+
The score is a single weighted number summarizing the three captured CWV metrics. It follows a **logarithmic scale** aligned with the Lighthouse scoring model, where the relationship between the raw metric value and the score is non-linear — improvements have more impact the closer values already are to the "good" threshold.
137+
138+
**Weights:**
139+
140+
| Metric | Weight |
141+
| ------ | ------ |
142+
| LCP | 35% |
143+
| CLS | 35% |
144+
| FCP | 30% |
145+
146+
**Per-metric formula:**
147+
148+
```
149+
metricScore = (log(poor) - log(value)) / (log(poor) - log(good))
150+
clamped to [0, 1] × 100
151+
```
152+
153+
Metrics that were not captured are excluded from the weighted average, with the remaining weights automatically renormalized.
154+
155+
**Final score:**
156+
157+
```
158+
score = round(Σ(metricScore × weight) / Σ(weight))
159+
```
160+
161+
---
162+
163+
## Rating
164+
165+
| Rating | Score range | Meaning |
166+
| ------------------- | ----------- | ---------------------------------------------------------- |
167+
| `good` | ≥ 90 | App meets high-performance targets |
168+
| `needs-improvement` | 50 – 89 | Noticeable issues affecting the user experience |
169+
| `poor` | < 50 | Significant performance problems |

‎pt/docs/conceitos/.pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ nav:
66
- Eitri CLI: eitri-cli.md
77
- Eitri Luminus: eitri-luminus.md
88
- Eitri Play: eitri-play.md
9+
- Métricas de Performance: performance-metrics.md

‎pt/docs/conceitos/performance-metrics.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Métricas de Performance — Eitri App
2+
3+
> As métricas são coletadas automaticamente a cada carregamento do app e exibidas diretamente no terminal durante o ciclo de desenvolvimento.
4+
5+
---
6+
7+
## Métricas Capturadas
8+
9+
| Métrica | Tipo | Descrição |
10+
| -------- | -------------------------- | ------------------------------------------ |
11+
| `cls` | Estabilidade visual | Cumulative Layout Shift |
12+
| `fcp` | Velocidade de carregamento | First Contentful Paint |
13+
| `lcp` | Velocidade de carregamento | Largest Contentful Paint |
14+
| `load` | Temporização de navegação | Início do evento de carregamento da página |
15+
| `score` | Calculado | Pontuação de performance ponderada (0–100) |
16+
| `rating` | Calculado | Classificação legível baseada no score |
17+
18+
---
19+
20+
## CLS — Cumulative Layout Shift
21+
22+
**O que mede:** Quantifica o quanto o conteúdo visível se desloca inesperadamente durante o ciclo de vida da página. Um layout shift ocorre quando um elemento muda de posição entre frames renderizados sem interação do usuário.
23+
24+
**Fórmula:**
25+
26+
```
27+
layout shift score = impact fraction × distance fraction
28+
```
29+
30+
**Impact fraction** — porção do viewport afetada pelo elemento instável:
31+
32+
![Exemplo de impact fraction do CLS](https://web.dev/static/articles/cls/image/impact-fraction-example-164341c82ee76.png){ .off-glb }
33+
34+
**Distance fraction** — maior distância que o elemento percorreu em relação ao viewport:
35+
36+
![Exemplo de distance fraction do CLS](https://web.dev/static/articles/cls/image/distance-fraction-example-9146d2a862482.png){ .off-glb }
37+
38+
O CLS acumula todos os scores de layout shift inesperados ao longo de todo o ciclo de vida da página.
39+
40+
**Limites (Web Vitals oficiais):**
41+
42+
![Gráfico de limites do CLS](https://web.dev/static/articles/cls/image/good-cls-values-are-01-a42d66f2d0f42.svg){ .off-glb }
43+
44+
| Classificação | Valor |
45+
| ------------------- | ---------- |
46+
| Bom | ≤ 0.1 |
47+
| Precisa de melhoria | 0.1 – 0.25 |
48+
| Ruim | > 0.25 |
49+
50+
**Meta Eitri (mais rigorosa — otimizada para o Eitri-App):**
51+
52+
| Classificação | Valor |
53+
| ------------- | ------ |
54+
| Bom | ≤ 0.05 |
55+
| Ruim | > 0.1 |
56+
57+
**Por que importa:** Deslocamentos inesperados fazem o usuário perder o ponto de leitura, tocar em botões errados ou realizar ações indesejadas (ex: confirmar uma compra por engano). Especialmente crítico no Eitri-App, onde os alvos de toque são menores.
58+
59+
---
60+
61+
## FCP — First Contentful Paint
62+
63+
**O que mede:** Tempo desde o início da navegação até que qualquer conteúdo (texto, imagem, SVG, canvas não-branco) seja renderizado pela primeira vez na tela. É o sinal mais precoce de que a página está respondendo.
64+
65+
![Exemplo de linha do tempo do FCP](https://web.dev/static/articles/fcp/image/fcp-timeline-googlecom.png){ .off-glb }
66+
67+
**Limites (Web Vitals oficiais):**
68+
69+
![Gráfico de limites do FCP](https://web.dev/static/articles/fcp/image/good-fcp-values-are-18-s-421f9e1a2cc56.svg){ .off-glb }
70+
71+
| Classificação | Valor |
72+
| ------------------- | ------------- |
73+
| Bom | ≤ 1.8 s |
74+
| Precisa de melhoria | 1.8 s – 3.0 s |
75+
| Ruim | > 3.0 s |
76+
77+
**Meta Eitri (mais rigorosa — otimizada para o Eitri-App):**
78+
79+
| Classificação | Valor |
80+
| ------------- | --------- |
81+
| Bom | ≤ 800 ms |
82+
| Ruim | > 1800 ms |
83+
84+
**Por que importa:** O FCP é a primeira confirmação visual do usuário de que algo está acontecendo. Um FCP lento aumenta o tempo de espera percebido e a taxa de abandono, mesmo que a página venha a carregar completamente.
85+
86+
---
87+
88+
## LCP — Largest Contentful Paint
89+
90+
**O que mede:** Tempo de renderização do maior elemento visível no viewport (imagem, bloco de texto, poster de vídeo). Marca o momento em que o conteúdo principal da página provavelmente foi carregado.
91+
92+
**Exemplos reais de elementos LCP em diferentes sites:**
93+
94+
![Exemplo de LCP — CNN](https://web.dev/static/articles/lcp/image/largest-contentful-paint-fc43128e011aa.png){ .off-glb }
95+
![Exemplo de LCP — TechCrunch](https://web.dev/static/articles/lcp/image/largest-contentful-paint-3713e2f14970a.png){ .off-glb }
96+
97+
**Elementos considerados:**
98+
99+
- `<img>` (incluindo o primeiro frame de imagens animadas)
100+
- `<image>` dentro de `<svg>`
101+
- `<video>` (poster ou primeiro frame, o que vier antes)
102+
- Elementos com CSS `background-image: url()`
103+
- Elementos em bloco com conteúdo de texto
104+
105+
**Limites (Web Vitals oficiais):**
106+
107+
![Gráfico de limites do LCP](https://web.dev/static/articles/lcp/image/good-lcp-values-are-25-s-28836be83d1aa.svg){ .off-glb }
108+
109+
| Classificação | Valor |
110+
| ------------------- | ------------- |
111+
| Bom | ≤ 2.5 s |
112+
| Precisa de melhoria | 2.5 s – 4.0 s |
113+
| Ruim | > 4.0 s |
114+
115+
**Meta Eitri (mais rigorosa — otimizada para o Eitri-App):**
116+
117+
| Classificação | Valor |
118+
| ------------- | --------- |
119+
| Bom | ≤ 1000 ms |
120+
| Ruim | > 2500 ms |
121+
122+
**Por que importa:** Um LCP rápido transmite ao usuário que a página é útil e está pronta para interação. Possui correlação direta com a performance de carregamento percebida e é o Core Web Vital de maior impacto na retenção de usuários.
123+
124+
---
125+
126+
## LOAD — Evento de Carregamento da Página
127+
128+
**O que mede:** Tempo (em ms) desde o início da navegação até o disparo do evento `load` pelo aplicativo. Indica que todos os recursos síncronos (scripts, folhas de estilo, imagens referenciadas no JSX) terminaram de carregar.
129+
130+
> Esta é uma **métrica de temporização de navegação**, não um Core Web Vital. É capturada para fins de diagnóstico — um `load` lento combinado com um `LCP` rápido pode indicar recursos diferidos pesados.
131+
132+
---
133+
134+
## Score (0–100)
135+
136+
O score é um número ponderado único que resume as três métricas CWV capturadas. Segue uma **escala logarítmica** alinhada ao modelo de pontuação do Lighthouse, onde a relação entre o valor bruto da métrica e o score é não-linear — melhorias têm mais impacto quanto mais próximos os valores já estiverem do limiar "bom".
137+
138+
**Pesos:**
139+
140+
| Métrica | Peso |
141+
| ------- | ---- |
142+
| LCP | 35% |
143+
| CLS | 35% |
144+
| FCP | 30% |
145+
146+
**Fórmula por métrica:**
147+
148+
```
149+
metricScore = (log(ruim) - log(valor)) / (log(ruim) - log(bom))
150+
limitado a [0, 1] × 100
151+
```
152+
153+
Métricas não capturadas são excluídas da média ponderada, com os pesos restantes renormalizados automaticamente.
154+
155+
**Score final:**
156+
157+
```
158+
score = round(Σ(metricScore × peso) / Σ(peso))
159+
```
160+
161+
---
162+
163+
## Rating
164+
165+
| Rating | Faixa de score | Significado |
166+
| ------------------- | -------------- | ---------------------------------------------------------- |
167+
| `good` | ≥ 90 | App atinge as metas de alta performance |
168+
| `needs-improvement` | 50 – 89 | Problemas perceptíveis que afetam a experiência do usuário |
169+
| `poor` | < 50 | Problemas significativos de performance |

0 commit comments

Comments
 (0)