A technical article can be perfectly well written and still ask too much mental work from the reader. Architecture, puzzle generation, solvers and editorial systems are rarely linear ideas. They contain layers, dependencies, loops, states, comparisons and spatial relationships. Prose has to describe those things one sentence after another even when the system itself exists all at once. In September 2026, when Blupoli's publication was still called the Journal and the product still carried the Blupoli Puzzles name, that gap became increasingly obvious.
The easy response would have been “add more images.” But generic screenshots and decorative illustrations do not automatically reduce cognitive load. The useful question was different: which relationship is the reader being forced to reconstruct mentally, and can we draw that relationship without turning the article into a slide deck? That is the idea behind semantic infographics: visuals where position, shape, connection and grouping stand for something real in the subject.
An image can improve pacing without explaining anything
There is nothing wrong with an atmospheric image when the goal is aesthetic. A cover needs to attract attention, establish tone and survive as a social card. An illustration can give the eye a break. The problem begins when that function is mistaken for explanation. A colourful block between two sections does not make a generation pipeline easier to understand.
We therefore started separating two visual responsibilities. The cover introduces the story: theme, identity and a composition that works at small sizes. The interior infographic teaches: it compresses complexity, compares states or reveals structure. Both are visuals, but they succeed by different criteria.
The simplest test: remove the labels and ask whether an idea remains
A semantic infographic does not need to be fully self-explanatory without its caption, but a relationship should survive. If it is a flow, direction should still be visible. If it compares layers, hierarchy should remain. If it explains a puzzle, the geometry should resemble the mechanic. If deleting the words leaves only attractive boxes, we probably designed decoration.
This test helped us avoid a familiar pattern: using the same “three cards in a row” template for every topic. Visual consistency is useful, but semantic equivalence cannot be invented. Three blocks should appear because the concept actually has three meaningful parts, not because a component library makes three blocks easy to draw.
The visual grammar can be shared without sharing the diagram
To produce many articles without redesigning everything from zero, we needed a small visual grammar: nodes, connectors, containers, layers, state markers, accent treatment, spacing and typographic rules. That vocabulary makes the figures feel like part of one publication and reduces production time.
Shared grammar does not mean cloned composition. An architecture article may need stacked layers. A generation article may need a funnel with rejection paths. Slitherlink needs edges and vertices. Kropki needs dots that encode relationships. The system supplies primitives; the topic decides how those primitives are arranged.
Puzzle diagrams have to respect the mechanics they represent
An editorial Sudoku diagram can simplify the board, but it should not invent a structure that contradicts rows, columns and boxes. In Aquarium, height matters. In Slant, diagonals and cycles matter. In Kropki, white and black dots are not interchangeable decoration. When the article is explaining the mechanic, the visual must preserve enough semantics to avoid teaching a different game.
That made puzzle illustrations a special case in our editorial system. They are not playable engines and do not need every possible state, but they do need the essential visual rules. A screenshot shows one session. A strong diagram can show the pattern that produces many sessions.
The infographic should appear where it resolves a real comprehension problem
Putting every visual at the top creates a gallery. Saving every visual for the end creates an appendix. The useful location is usually near the point where the text introduces the relationship being compressed. The reader can encounter the idea, inspect the map and then return to detail with a stronger mental model.
This means the article has to be structured before the asset is produced. An infographic is not a file we attach because a checklist says every post needs one. It begins with an editorial question: which part of this argument is hardest to understand through prose alone? If there is no good answer, a second visual may not be necessary.
A cover should not try to summarize the entire article
Covers have a different set of constraints. They appear small, get cropped, live in listings and social cards, and compete with the headline. Packing every concept into the asset turns it into an unreadable thumbnail. We prefer a simple visual metaphor, enough contrast and shapes that survive reduction.
We also avoid embedding essential copy when we can. The H1 and surrounding metadata can carry the localized title. If the pipeline generates a cover that includes headline text, we need locale-specific variants so an English article does not end up sharing a Spanish card.
Language changes how assets should be designed
A wordless SVG can often be shared by Spanish and English while each page supplies its own alt text and caption. That reduces duplication and makes the editorial archive easier to maintain. When an infographic needs internal labels, we have to decide whether to produce localized variants or move that explanatory language into HTML.
Internationalization turns this into an architectural decision. It is not enough for an image to exist. The build needs to know which asset belongs to which locale, how the URL is rewritten and what happens when a localized version is missing. The broader problem is explored in our article on internationalizing Blupoli.
Alt text and captions should not duplicate each other
Alternative text describes what a reader needs when the image cannot be perceived visually. A caption can interpret, contextualize or call attention to the conclusion we want the reader to carry forward. Copying the same sentence into both wastes one of the layers.
For a complex infographic, alt text does not need to narrate every coordinate. It can explain the structure and the central relationship while the article body contains the detailed argument. Accessibility improves when the graphic is a support for information rather than the only place where essential information exists.
A visual that works only on desktop is unfinished
Wide diagrams are seductive because horizontal space makes systems easy to arrange. On a phone, the same composition may shrink until labels and connectors become noise. Editorial graphics need to be tested at small sizes, not merely opened successfully as SVG files.
There are several responses: reduce the number of elements, strengthen hierarchy, allow controlled horizontal scrolling when it genuinely helps, or design a layout whose meaning survives scale. The requirement is simple: a reader should not need pinch-zoom just to discover what the picture is saying.
SVG is a strong fit when the information is structural
For many Blupoli diagrams, SVG has practical advantages. It scales without losing sharpness, versions as text, supports precise geometry and can remain lightweight. It can also contain its own title and description to give the asset basic internal semantics.
That does not make SVG mandatory. A real screenshot, photograph or raster illustration can be the right choice. We choose the format according to the nature of the information. When the subject is made of nodes, lines, boards and states, vector graphics are often especially effective.
Versioning the visual beside the article keeps it from becoming an orphan
An image stored in an external service can outlive the page that explains it or disappear when an account changes. Keeping editorial assets in the repository ties them to the article's history. An architecture change can update prose and diagram in one pull request.
This proximity also improves review. The diff makes it obvious that a new entry includes its cover and semantic graphic. Quality gates can check paths and presence. Visual publishing stops being a manual step outside the build.
The build can protect visual coverage
Once the editorial contract says an entry requires a cover, remembering that requirement should not depend on a human checklist. The pipeline can verify that the asset exists, that its route is valid and that generated pages actually reference it. The same can apply to graphics required by the writing workflow.
Automation cannot decide whether an image is good. It can prevent a simpler failure: shipping a post without the visual package the publication expects. Human review can then focus on semantics, composition and legibility.
Asset paths are boring until they break an entire section
As the Blog and Devlog architecture evolved, we hit a very concrete failure. A post moved to a different public route could retain a relative reference such as ./infographic.svg. The HTML existed at the new route while the asset was still published under the old editorial tree. Both files existed, yet the browser saw a broken image.
The fix was to normalize editorial references so shared assets use route-stable URLs after migration. It is a useful reminder that design and build are not separate systems. A perfect infographic returning 404 is not a published infographic.
Localization adds another way to break the same asset
A localization pass can correctly prefix navigation and accidentally apply the same prefix to an image that is actually shared across locales. The result is a localized URL that has no corresponding file. The symptom looks similar, but the cause is a route transformation rather than a content move.
That is why the current pipeline includes specific normalization for localized editorial links and assets. These steps are not glamorous, but they are part of the editorial product because they ensure the designed artifact reaches the reader.
A consistent palette should not turn every diagram into the same diagram
The visual identity can share background treatment, accents, radii, density and line language. That helps an architecture article and a puzzle-engine article feel like they belong to Blupoli. The danger is using consistency as an excuse to repeat the same layout regardless of meaning.
We prefer to treat tokens as vocabulary, not as a rigid template. The accent treatment can remain recognizable while geometry responds to the subject. The publication should feel coherent because it handles information consistently, not because every figure contains the same three boxes.
Colour should never carry the only meaning
If two states are distinguished only by green and red, the diagram loses information for some readers and may also degrade in print or under different display conditions. Shape, position, icons or patterns can reinforce the distinction.
This rule comes directly from product design. Accessibility principles that apply to a board also apply to an infographic. Editorial content does not get an exemption simply because it is static.
Architecture diagrams should avoid false precision
A simplified figure is useful because it removes detail. The danger is drawing an arrow that implies a direct dependency when the real system is more nuanced, or presenting a conceptual layer as if it were a physical module. The surrounding copy and caption need to make the abstraction level clear.
We do not need to draw every file. We need the relationships shown to be true at the level being explained. Honest simplification teaches. Simplification that changes causality misleads.
An infographic can act as an index for the argument
In a long article, a strong visual can do more than clarify one local section. It can map the rest of the piece. A flow showing generation, verification and publication prepares the reader for deeper sections about each stage.
This supports non-linear reading. Someone scanning the piece can understand the overall structure and choose where to stop. Someone reading in order has a reference for connecting details. The graphic becomes cognitive navigation.
Quantities need different visuals from processes
Not every idea belongs in a flowchart. Quantitative comparisons may need bars or tables. Taxonomies may need groups. A chronology may need a timeline. Choosing the visual form before understanding the relationship produces diagrams that feel forced.
The first question should be what relationship we need to show: sequence, hierarchy, amount, comparison, membership or space. Only then do we select the grammar. That keeps semantics above decoration.
Code screenshots are often worse than they look
Code can be relevant in a Devlog, but screenshots have costs: they are not selectable, age quickly, often include irrelevant detail and become hard to read on mobile. If the idea is conceptual, a diagram usually explains it better.
When an exact snippet is the subject, real formatted text can be more accessible and useful than an image. We reserve visuals for information that gains something by becoming spatial.
AI can accelerate visual production, but it still needs a contract
Generating a “nice image about puzzles” is easy and not very useful. For an AI system to produce a meaningful editorial diagram, it needs constraints: which relationship must be shown, which elements are factual, what it must not invent and which format the pipeline expects. The quality of that contract matters more than surface polish.
Programmatic visuals have another advantage in our workflow: we can inspect exactly what they draw and keep them versioned beside the article. Other tools may be better for illustrative scenes. The criterion remains the same: the image should serve the story, not merely demonstrate that we can generate images.
Covers and infographics also participate in SEO
Open Graph cards and social previews use images to present an article outside the site. A strong cover can make the subject understandable before the click. The metadata still has to point to the correct asset and respect the language of the page.
Visual SEO is less about putting keywords inside an SVG and more about stable URLs, sensible dimensions, correct metadata, useful alt text on the page and coherence between headline and representation. Technical signals should reinforce the story rather than contradict it.
Light mode becomes another test for the editorial system
A graphic with its own dark background can remain perfectly readable inside a light page if the contrast and boundaries are intentional. Other visuals may need to respond to site variables. The important part is testing them in both contexts.
An asset can work across themes when its composition is sufficiently self-contained. If it depends on the surrounding page colour, integration needs more care. Once again, a second theme exposes hidden assumptions.
Visual review needs concrete questions
“Does it look good?” is too subjective to be a useful checklist. We can ask whether the figure communicates the central idea without reading the full article, whether any connector suggests a false relationship, whether it survives at mobile width, whether contrast is sufficient, whether alt text covers the essential information and whether the caption adds context.
These questions turn taste into reviewable criteria. They do not remove judgment — design still needs judgment — but they make systematic failures easier to identify before the conversation becomes purely about preference.
The visual should evolve when the idea evolves
A technical article can remain published for years while its underlying architecture changes. If the text is updated but the diagram still shows a layer that no longer exists, the image becomes misinformation. Versioning article and visual together makes that drift easier to catch.
There are also cases where the historical graphic should remain and the article should clearly explain that it represents a specific stage. Not every old post needs to be rewritten as if it always described the present. Date and context let us preserve memory without confusing current state.
The Blog and Devlog split made the shared visual system more valuable
A few days after this work, Blupoli reorganized its publishing into clearer Blog and Devlog surfaces. The full story appears in our article about the editorial architecture change. Separating editorial intent did not mean creating two incompatible visual identities.
A shared language of covers, diagrams and components lets both surfaces remain recognizably Blupoli while telling different kinds of stories. The Blog can lean more toward product and public value. The Devlog can go deeper into architecture and process. Common grammar keeps continuity.
Designing semantic visuals changes how we write
Trying to draw an explanation exposes gaps in the prose. If you cannot decide which boxes exist or what connects to what, the idea itself may not yet be clear enough. The diagram becomes a thinking tool before it becomes an asset.
This is one of the less obvious benefits of the workflow. The visual does not only help the reader. It forces the author to distinguish sequence from causality, layers from components, examples from rules and measurements from opinions. Drawing can improve the precision of the article itself.
The right image can reduce words without replacing them
A good infographic may eliminate three repetitive paragraphs, but it should not become the only place where a conclusion exists. The article still needs to make sense for someone who cannot see the visual, for search engines and for future transformations of the content.
The ideal relationship is complementary. Prose provides nuance, exceptions and narrative. The image compresses structure. The caption connects the two. When those layers do different jobs, the result is much stronger than a page that simply contains “more images.”
A visual system needs explicit maintenance debt too
Not every graphic ages at the same rate. An abstract metaphor may remain useful for years, while an architecture diagram can become stale as soon as a dependency changes. Treating that difference as editorial maintenance is healthier than assuming static images remain correct forever.
In practice, that means knowing which visuals describe durable principles and which document a concrete implementation. The second group should be discoverable when architecture changes, just like affected technical documentation. The asset becomes versioned knowledge rather than frozen decoration.
Visual quality can still be observed after publication
Pre-publication review catches a lot, but real usage reveals additional problems. A cover may crop badly in a card, a diagram may prove too dense on a phone, or contrast may fail in a context we did not test. Shipping should not eliminate the possibility of refinement.
The key is to preserve semantics during those refinements. Adjusting scale or spacing to improve legibility is healthy. Redrawing connections until they imply a different system should trigger a review of the article as well. Visual and prose form one explanatory contract.
The real objective is to lower the cost of understanding
The reason to invest in an editorial visual system is not to make articles look more expensive or modern. It is to ask less cognitive work from the reader. If a diagram lets someone understand the shape of an architecture in thirty seconds before they read the details, the image has done real work.
That remains the standard we care about in Blupoli. A cover can attract. An infographic should teach. When a visual has no idea to defend, we probably do not need to produce it. When it does, it belongs inside the same quality pipeline as the text around it.