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
levelorvariantcomes from the scale, not from a class overlay -
Do not add
text-xl/font-boldon top ofHeadingto “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.
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
PageTitlewrapper that reimplementsHeading - Utility classes that override the component’s size or family
- An
h2used only because the last example the model saw was anh2
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)