DEV Community

Sherotree
Sherotree

Posted on

Make the agent use the existing typography components, not raw heading tags

The agent adds a section title as <h2 className="text-xl font-semibold">Preferences</h2>. The design system already has <Heading level={2}> (or Text variant="title") that maps to the type scale, the weight, the spacing, and the heading font. The raw tag is close, then a later token change misses it, and the page now has a one-off size.

I’ve started treating a raw heading or paragraph with ad-hoc size classes as a missed design-system use, not as a finished title. The typography components exist so the scale stays in one place.

This is the other half of “pin the agent to the existing typography scale.” The scale is not only a list of pixel values. It is the component that applies them.

Why the raw tag shows up

HTML headings are easy to generate. The model will pick an h2 and a familiar utility class and move on. It will not open Heading.tsx unless you point at it. On a page that already mixes a few raw tags, the new one looks consistent with the wrong local pattern.

Raw tags also drift semantically. You get an h2 in a slot that should be an h3, or a div with a large class that is not in the heading outline at all.

A simple typography-component policy

  • Titles, body, captions, and labels use the shared typography components
  • The level or variant comes from the scale, not from a class overlay
  • Do not add text-xl / font-bold on top of Heading to “make it pop”
  • A raw <h*> or <p> is allowed only in surfaces the design system does not cover (an email template, a legal snapshot), and the PR should say why

If the design system documents when to use Heading vs Text, paste that page. Do not rely on the model to guess from the component name.

What to put in the prompt

Use the existing typography components (Heading, Text — see src/components/typography) for titles and body copy.
Do not add a raw <h2> or <p> with ad-hoc size or weight classes.
Pick a level/variant from the existing scale. Do not override font-size on the component.
Do not invent a new Title or SectionHeader component.
Enter fullscreen mode Exit fullscreen mode

In review, search the diff for raw <h1>–<h6>, <p className="text-, and font-size utilities next to new copy. Those should be rare.

Reject / send back

Reject

  • A raw <h2 className="text-xl font-semibold"> in a design-system page
  • A new PageTitle wrapper that reimplements Heading
  • Utility classes that override the component’s size or family
  • An h2 used only because the last example the model saw was an h2

Accept

  • Heading / Text (or the repo’s named typography components) with an existing variant
  • A raw tag in a non-design-system surface, explained in the PR
  • A genuine new variant added to the typography component, with a token and a Storybook story

Top comments (0)