Skip to content

Commit 0ab86bc

Browse files
cursoragentcursoragent
committed
Add comprehensive typography review for Next.js manual setup page
1 parent 93ba47e commit 0ab86bc

File tree

1 file changed

+284
-0
lines changed

1 file changed

+284
-0
lines changed

‎typography-review-recommendations.md‎

Lines changed: 284 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,284 @@
1+
# Typography Review: Next.js Manual Setup Page
2+
3+
## Overview
4+
5+
This document provides a comprehensive review of the typography and font sizing for the Sentry Next.js Manual Setup documentation page (`/platforms/javascript/guides/nextjs/manual-setup`) with specific recommendations to improve visual hierarchy and readability.
6+
7+
## Current Typography Analysis
8+
9+
### Current Font System
10+
- **Base Font**: Rubik (from `--font-rubik` in globals.css)
11+
- **Monospace**: Roboto Mono, SFMono-Regular, Consolas
12+
- **Current Sizing**: Uses a mix of Tailwind classes and CSS variables with inconsistent scaling
13+
14+
### Current Typography Issues Identified
15+
16+
1. **Inconsistent Heading Hierarchy**
17+
- H1 title size not prominently differentiated from H2 steps
18+
- No clear size distinction between main steps and subsections
19+
- Step numbers blend with content rather than standing out
20+
21+
2. **Poor Code Block Integration**
22+
- Code blocks use small font sizes (0.75rem, 0.8rem) making them hard to read
23+
- Insufficient contrast between code and explanatory text
24+
- Filename annotations too subtle
25+
26+
3. **Weak Information Hierarchy**
27+
- Important alerts and tips don't stand out sufficiently
28+
- Navigation steps lack visual prominence
29+
- Technical details have same weight as introductory content
30+
31+
4. **Readability Challenges**
32+
- Long code blocks without adequate line height
33+
- Dense technical content without breathing room
34+
- Small text in components (0.8rem in multiple places)
35+
36+
## Recommended Typography Improvements
37+
38+
### 1. Enhanced Heading Hierarchy
39+
40+
```css
41+
/* Primary Title */
42+
h1 {
43+
font-size: 2.5rem; /* 40px */
44+
font-weight: 600;
45+
line-height: 1.2;
46+
margin-bottom: 1.5rem;
47+
letter-spacing: -0.02em;
48+
}
49+
50+
/* Step Headers (Step 1, Step 2, etc.) */
51+
h2 {
52+
font-size: 1.875rem; /* 30px */
53+
font-weight: 600;
54+
line-height: 1.3;
55+
margin-top: 3rem;
56+
margin-bottom: 1.25rem;
57+
color: var(--accent-purple);
58+
border-bottom: 2px solid var(--accent-purple-light);
59+
padding-bottom: 0.5rem;
60+
}
61+
62+
/* Subsection Headers */
63+
h3 {
64+
font-size: 1.5rem; /* 24px */
65+
font-weight: 500;
66+
line-height: 1.4;
67+
margin-top: 2rem;
68+
margin-bottom: 1rem;
69+
}
70+
71+
/* Component Headers */
72+
h4 {
73+
font-size: 1.25rem; /* 20px */
74+
font-weight: 500;
75+
line-height: 1.4;
76+
margin-top: 1.5rem;
77+
margin-bottom: 0.75rem;
78+
}
79+
```
80+
81+
### 2. Improved Body Text Scaling
82+
83+
```css
84+
/* Base paragraph text */
85+
p, li {
86+
font-size: 1rem; /* 16px */
87+
line-height: 1.6;
88+
margin-bottom: 1rem;
89+
}
90+
91+
/* Large introductory text */
92+
.lead-text {
93+
font-size: 1.125rem; /* 18px */
94+
line-height: 1.6;
95+
color: var(--gray-11);
96+
margin-bottom: 1.5rem;
97+
}
98+
99+
/* Small supporting text */
100+
.caption, .note {
101+
font-size: 0.875rem; /* 14px */
102+
line-height: 1.5;
103+
color: var(--gray-10);
104+
}
105+
```
106+
107+
### 3. Enhanced Code Block Typography
108+
109+
```css
110+
/* Inline code */
111+
code {
112+
font-size: 0.9em;
113+
font-family: var(--font-family-monospace);
114+
background: var(--gray-a2);
115+
padding: 0.125rem 0.25rem;
116+
border-radius: 0.25rem;
117+
color: var(--codeColor);
118+
}
119+
120+
/* Code blocks */
121+
pre {
122+
font-size: 0.875rem; /* 14px */
123+
line-height: 1.6;
124+
padding: 1.5rem;
125+
border-radius: 0.5rem;
126+
background: var(--gray-1);
127+
overflow-x: auto;
128+
margin: 1.5rem 0;
129+
}
130+
131+
/* Filename annotations */
132+
.filename-annotation {
133+
font-size: 0.8125rem; /* 13px */
134+
font-weight: 500;
135+
color: var(--accent-purple);
136+
background: var(--accent-purple-light);
137+
padding: 0.25rem 0.75rem;
138+
border-radius: 0.25rem 0.25rem 0 0;
139+
margin-bottom: -1px;
140+
}
141+
142+
/* Tab titles */
143+
.tab-title {
144+
font-size: 0.875rem; /* 14px */
145+
font-weight: 500;
146+
padding: 0.5rem 1rem;
147+
}
148+
```
149+
150+
### 4. Alert and Component Typography
151+
152+
```css
153+
/* Alert components */
154+
.alert {
155+
font-size: 0.9375rem; /* 15px */
156+
line-height: 1.5;
157+
padding: 1rem 1.25rem;
158+
border-radius: 0.5rem;
159+
margin: 1.5rem 0;
160+
}
161+
162+
.alert-title {
163+
font-size: 1rem; /* 16px */
164+
font-weight: 600;
165+
margin-bottom: 0.5rem;
166+
}
167+
168+
/* Step indicators */
169+
.step-indicator {
170+
font-size: 1.125rem; /* 18px */
171+
font-weight: 700;
172+
color: var(--accent-purple);
173+
background: var(--accent-purple-light);
174+
padding: 0.5rem 1rem;
175+
border-radius: 2rem;
176+
display: inline-block;
177+
margin-bottom: 1rem;
178+
}
179+
```
180+
181+
### 5. List and Navigation Typography
182+
183+
```css
184+
/* Ordered and unordered lists */
185+
ul, ol {
186+
margin: 1rem 0;
187+
padding-left: 1.5rem;
188+
}
189+
190+
li {
191+
margin-bottom: 0.5rem;
192+
line-height: 1.6;
193+
}
194+
195+
/* Nested lists */
196+
li ul, li ol {
197+
margin: 0.5rem 0;
198+
}
199+
200+
/* Table of contents */
201+
.toc-item {
202+
font-size: 0.875rem; /* 14px */
203+
line-height: 1.4;
204+
margin-bottom: 0.25rem;
205+
}
206+
207+
.toc-item.active {
208+
font-weight: 500;
209+
color: var(--accent-purple);
210+
}
211+
```
212+
213+
## Specific Page Improvements
214+
215+
### 1. Header Section Enhancement
216+
- Increase main title from current size to 2.5rem (40px)
217+
- Add descriptive subtitle at 1.125rem (18px) with reduced opacity
218+
- Enhance the wizard installer alert with better typography contrast
219+
220+
### 2. Step Section Improvements
221+
- Style step headers with distinct color and border treatment
222+
- Add step number badges with proper contrast
223+
- Increase spacing between major sections
224+
225+
### 3. Code Block Enhancements
226+
- Increase code font size from 0.75rem to 0.875rem (14px)
227+
- Improve line height from 1.2 to 1.6 for better readability
228+
- Add better contrast for filename annotations
229+
- Enhance tab styling for package manager options
230+
231+
### 4. Content Flow Improvements
232+
- Add lead paragraphs for major sections at 1.125rem
233+
- Improve spacing between related elements
234+
- Enhance visual separation between configuration steps
235+
236+
## Implementation Priority
237+
238+
### High Priority (Immediate Impact)
239+
1. **Heading hierarchy improvements** - Most critical for navigation
240+
2. **Code block font size increase** - Essential for readability
241+
3. **Step indicator enhancements** - Key for user guidance
242+
243+
### Medium Priority (Quality of Life)
244+
1. **Body text line height improvements**
245+
2. **Alert component typography**
246+
3. **List spacing optimization**
247+
248+
### Low Priority (Polish)
249+
1. **Filename annotation styling**
250+
2. **Table of contents typography**
251+
3. **Micro-spacing adjustments**
252+
253+
## Accessibility Considerations
254+
255+
### WCAG Compliance
256+
- Maintain minimum 4.5:1 contrast ratio for all text
257+
- Ensure font sizes meet minimum requirements (16px base)
258+
- Provide sufficient line height (1.5+) for readability
259+
- Use relative units for scalability
260+
261+
### Screen Reader Optimization
262+
- Maintain proper heading hierarchy (h1 → h2 → h3)
263+
- Ensure code blocks have appropriate labels
264+
- Use semantic markup for all typography elements
265+
266+
## Measurement & Testing
267+
268+
### Key Metrics to Track
269+
1. **Reading time per section**
270+
2. **Scroll depth and engagement**
271+
3. **Code copy success rates**
272+
4. **User feedback on clarity**
273+
274+
### Testing Recommendations
275+
1. A/B testing on typography changes
276+
2. User testing with developers of varying experience levels
277+
3. Accessibility testing with screen readers
278+
4. Mobile responsiveness validation
279+
280+
## Conclusion
281+
282+
These typography improvements will significantly enhance the visual hierarchy and readability of the Next.js manual setup documentation. The focus on clear step differentiation, improved code readability, and proper information hierarchy will help developers more efficiently navigate and implement Sentry integration.
283+
284+
The recommendations prioritize developer experience while maintaining consistency with Sentry's design system and ensuring accessibility compliance.

0 commit comments

Comments
 (0)