Building my blog, part 2: designing for clarity

Mon, 19 Oct 2026 04:15:50 -0300

The old terminal made sense to me, but it could ask too much of a visitor. Someone trying to learn about my work should not have to discover a command to find information. When adapting that area into a desktop, I wanted a more familiar language: open, explore, and close windows.

That did not solve the entire design. A desktop can also be confusing if everything depends on it. The website has dedicated pages for my background, projects, writing, and contact information; the interactive area is another way to explore. Conventional navigation remains available.

Getting this combination right was the hardest part of building the site. I wanted it to reflect me and help people understand what they were seeing. Its appearance needed to support that reading.

One reference for presentation, another for construction

With Zeno Rocha, I was interested in how he presents himself and gives his work visibility while keeping navigation intuitive. With Akita, the reference was mainly how he built his blog and the ideas around it. These were not two interfaces I intended to combine literally.

Through experiments with Claude, Antigravity, and then Codex with skills, I refined a direction that needed to fit the rest of my website. An interesting visual result could still have poor spacing, too much information in one place, or unclear interaction.

This was particularly noticeable with article covers. I wanted to retain the title, summary, author, date, reading time, and topics. When those elements were too close together, a large image did not compensate for the missing hierarchy. The gradient also needed revision: a transition that seemed acceptable in dark mode could form a heavy band in light mode.

Give each area a purpose

Featured articles present a selection of up to three pieces. Recent articles show the latest publications and can repeat a featured item. The Archive provides a way to explore more content and filter it.

Topics appear as small labels without a hashtag symbol. A label communicates a category; its appearance should still suggest that it is clickable. Similarly, a return link should explain its destination. A link promising to return to the Archive needs to go there.

These details can look minor in isolation. Together, they determine whether someone can predict the next step. I began looking at each element’s purpose as well as its position in a screenshot.

The published Archive in English, captured on October 19, 2026. Search, filters, and topics each serve a different navigation task.

View the full-size screenshot

Motion should follow the action

Featured images appear in grayscale on devices with a mouse and gain color on hover. The first transition felt too abrupt. We adjusted it to give the change time to register, with a slight enlargement of the image.

The table of contents needed similar attention. Clicking from the first topic to the last should not make the indicator compete for attention with every intermediate section during scrolling. Navigation began treating that movement as an action with a chosen destination.

These effects need alternatives. A phone does not have a reliable equivalent of mouse hover. Keyboard focus should appear without depending on a slow animation. For people who request reduced motion in their system settings, movement and transitions should be reduced or removed. The preference is read through the prefers-reduced-motion media query.

The goal is not to make visitors wait for an effect before using the site. Motion should explain what is changing and let navigation continue.

An actual screenshot of the English reading view. The table of contents keeps the selected section visible beside the text.

View the full-size screenshot

Reading in Portuguese or English

The Portuguese blog lives under /pt/blog/; the English version is under /blog/. Each article has one file per language. Both share a translationKey:

# In both files; the title and body are translated.
translationKey: building-blog-reading

The language selector opens the corresponding version when one exists. It does not automatically translate the text. Summaries, labels, image alternative text, and links between parts of a series also need review.

Search uses a local index containing text, titles, and other editorial fields. It helps find a word inside an article; Archive filters help narrow a collection by criteria. Those are related tasks, but they are not identical.

Real comments and the limits of testing

I kept the existing Disqus integration. Reaction buttons that only stored a choice in the browser did not provide a real interaction with me, so that proposal was left out.

Loading comments showed why an attractive screenshot does not prove something works. We had to review the domain authorized in Disqus and test automatic loading. Tool interference and changing browser tabs also affected some checks. Diagnosis needed to distinguish a service failure, website configuration, and a problem in the test itself.

In production, comments attempt to load automatically. The retry button is a recovery path for failures. Production integration is disabled in previews so experiments do not mix with real discussions.