Did you ever stop to think that the very tools designed to help AI replicate your brand’s visual identity might be getting the most basic elements wrong? It’s a question few developers likely considered until now, but the data suggests it’s a critical oversight. AI coding assistants are increasingly touted for their ability to generate on-brand UI components, relying on extracted design system information. Yet, a recent dive into how well this extraction works reveals a significant, and frankly, embarrassing, flaw: a startling number of websites have their primary brand font misidentified.
This isn’t a minor bug. We’re talking about AI agents tasked with crafting everything from marketing pages to user interfaces, potentially missing the mark on a fundamental visual cue that defines a brand. The tool in question, brandmd, an npm CLI built to distill a website’s design system into a usable DESIGN.md file for AI agents, recently discovered this widespread issue. After initial success with prominent sites like Stripe and GitHub, a user flagged a discrepancy: their primary font was reported as Inter, when in reality, it was Manrope, and crucially, it was only present on the hero section, not the main body text.
This triggered a broader audit. The creator of brandmd ran their tool against 100 popular design system sites. The results were stark: 9 out of 45 successfully-parsed sites—a full 20%—returned the incorrect primary font. That’s one in five. A quick look at the data reveals several failure modes.
When Code Overwhelms Branding
Some sites, like mantine.dev and remix.run, have significant amounts of code snippets on their homepages. This code, often styled with monospaced fonts like Menlo or JetBrains Mono, can numerically overpower the intended brand font in a simple frequency count. brandmd’s initial logic, const primaryFont = fontList[0]?.[0];, simply picked the most frequent font. If code fonts are more prevalent than the actual brand font, they win. It’s a simplistic approach that fails to grasp design intent.
The Body Text Deluge
Another common pitfall is when body text, styled with a ubiquitous font, drowns out a more distinctive brand font used sparingly on critical elements like the hero section. Valura.ai, for instance, uses Inter on over 700 elements but reserves Manrope for its hero. A frequency-based analysis would invariably pick Inter, missing the crucial brand differentiator.
Fallback Follies
Then there are the sites with no custom fonts, relying on browser fallbacks. Older versions of brandmd would incorrectly flag default fallbacks like Times as the primary font, even when actual brand fonts were present elsewhere on the page, albeit not as the most frequent. This isn’t just inaccurate; it’s misleading. When a site has a deliberate design language, surfacing a generic fallback as the primary brand font is fundamentally wrong.
Fair. So I ran brandmd against 100 popular design system sites to see how widespread the bug was. 9 of 45 successfully-extracted sites returned the wrong Primary font. 20%.
This data point is more than just a technical footnote. For AI agents trained on this kind of extracted data, it means they are learning from a flawed blueprint. Imagine an AI generating marketing copy for a company. If it misidentifies the primary font, the entire visual identity—the very essence of the brand’s personality conveyed through typography—is at risk of being misrepresented.
Revising the Recipe for Brand Font Detection
The fixes implemented in brandmd v0.8 are instructive. They move beyond a simple frequency count to incorporate design hierarchy and intent. The updated logic prioritizes: pickNonExcluded(displayFonts)—fonts larger than 40px, often found in hero sections—then heading fonts, and finally body fonts. Crucially, it now explicitly excludes monospaced fonts, default fallbacks like Times or Arial, and icon fonts. This refined approach better captures the intended primary brand font, not just the most numerically dominant one.
Beyond the core font detection, the update also enhances the font family parser to handle more complex CSS declarations like var(--font, 'Inter') and correctly processes backslash escapes—details that often trip up simpler parsers. A per-role cascade ensures headings can fall back gracefully to display fonts, and display fonts to body fonts, creating a more resilient system. Navigation timeouts were also increased to better handle slow single-page applications.
With these changes, brandmd now correctly identifies the primary brand font in 7 of the 9 previously misidentified cases. The remaining two, Railway.app and Workday.design, apparently lack a distinct brand font on their hero sections, so the tool now reports this honestly—a far better outcome than misrepresenting a fallback.
Why This Matters for AI-Driven Development
This revelation strikes at the heart of the promise of AI in design and development. If the foundational data fed to these AI models is flawed, their output will be too. The market for AI coding assistants is heating up, with players like Claude Code, Cursor, and Gemini CLI vying for developer attention. For these tools to truly deliver on the promise of smoothly, on-brand UI generation, they need accurate, reliable design system data. A tool like brandmd, by highlighting and fixing these fundamental data extraction issues, is not just improving a utility; it’s safeguarding the integrity of AI-driven brand representation.
It’s a clear signal: the race to empower AI with design intelligence is more nuanced than simply feeding it raw CSS. Understanding the hierarchy, intent, and specific context of design elements, like fonts, is paramount. The data from brandmd’s audit isn’t just about a font bug; it’s a wake-up call about the hidden complexities of translating visual identity into machine-readable formats and the critical role of well-engineered open-source tools in ensuring AI actually serves, rather than undermines, brand consistency.
Is Brandmd the Only Solution?
While brandmd offers a promising solution for extracting primary fonts, it’s unlikely to be the last word. The complexity of modern web design—with dynamic font loading, complex CSS variables, and frameworks that abstract away direct font definitions—means that font detection will remain a challenging problem. Future iterations might need to incorporate more advanced heuristics, perhaps even leveraging machine learning models trained on vast datasets of design systems to better discern brand fonts from utility or decorative ones. However, for now, brandmd’s focused approach and transparent methodology provide a valuable benchmark and a crucial improvement for AI coding agents.
What Does This Mean for AI Coding Agents?
This discovery directly impacts the reliability of AI coding agents that rely on design system data. If these agents are fed incorrect font information—whether it’s a monospaced font, a body font, or a fallback—their generated UI will inherently be off-brand. This could lead to inconsistent visual branding across different components or even across different AI-generated projects for the same company. Developers using these tools need to be aware of this potential pitfall and may need to supplement AI-generated code with manual verification or by providing more explicit design tokens to the AI. The goal is for AI to augment, not to arbitrarily redefine, a brand’s visual identity.
What is brandmd?
brandmd is an open-source npm CLI tool designed to extract a website’s design system into a DESIGN.md file. This file acts as a structured reference that AI coding agents can read to understand a brand’s visual language—including colors, typography, and spacing—enabling them to generate on-brand UI components. Its primary function is to bridge the gap between a live website and the data requirements of AI development tools, ensuring greater design consistency.
What are the main failure modes for font detection?
The primary failure modes for detecting a website’s brand font, as highlighted by the brandmd analysis, are:
- Code fonts winning: Monospaced fonts used for code snippets can numerically dominate the font frequency count.
- Body text drowning the brand: Ubiquitous body text fonts can overshadow more distinctive brand fonts used on hero sections or key headings.
- Fallback fonts being mistaken for brand fonts: Default browser fallback fonts (like Times or Arial) can be incorrectly identified as the primary brand font when no explicit custom font is detected or when the logic is too simplistic.
How did brandmd v0.8 improve font detection?
Brandmd v0.8 improved font detection by prioritizing fonts based on their design role rather than just frequency. It now looks for display fonts (larger than 40px) first, then heading fonts, and finally body fonts. It also explicitly excludes monospaced fonts, default fallbacks, and icon fonts, leading to a more accurate identification of the intended primary brand font.
