Refining Visual Hierarchy: Optimizing Heading Consistency in React

In any front-end application, the visual rhythm created by typography is the unsung hero of user experience. Working on the alcaino-web project, I recently identified a discrepancy in heading sizing that disrupted the visual flow of our interface. Consistency in design systems is much like the rules of grammar; when followed, they make the document readable, but when ignored, they create unnecessary friction.

The Problem

Users often scan web pages rather than reading them. When headings lack a clear, consistent hierarchy, the brain struggles to group related information. In our application, we noticed that several components were using inconsistent font scales for titles, leading to a "jagged" look where nested headers were sometimes larger than top-level ones.

The Investigation

In a React-based architecture, styling inconsistencies often stem from hardcoded values or localized CSS classes that don't account for the broader component context. By reviewing our styles, I found that the title classes were applied with variable scaling factors instead of referencing a centralized design token.

// Before: Hardcoded sizing inconsistencies
const CardTitle = ({ children }) => (
  <h2 className="title-large">{children}</h2>
);

const PageHeader = ({ children }) => (
  <h1 className="title-medium">{children}</h1>
);

The Fix

To resolve this, we moved away from ad-hoc sizing and implemented a modular scaling approach. By centralizing our typography definitions, we ensure that the visual weight of each heading is predictable across all views.

// After: Centralized typography classes
const Heading = ({ level, children }) => {
  const Tag = `h${level}`;
  return <Tag className={`heading-level-${level}`}>{children}</Tag>
};

By decoupling the semantic h1-h6 tags from the specific styling classes, we regained control over the visual hierarchy.

The Outcome

The UI now feels much more intentional. Adjusting the heading sizes globally meant that every component inherited the fix automatically. By treating design as part of the code architecture, we avoid these "visual debt" issues and keep the codebase clean.

Generated with Gitvlg.com