feat(Text): decouple visual heading variants from semantic HTML

[mattrothenberg]

Decouples visual heading variants from semantic HTML elements in the Text component. Previously, heading1/heading2/heading3 variants auto-rendered <h1>/<h2>/<h3> tags, which coupled visual presentation to semantic HTML and led to incorrect document outlines.

Changes:

• Heading variants now render as <span> by default
• The as prop is restricted to valid text elements: h1-h6, p, span
• Updated docs with "Semantic HTML" section and examples using the Text component

Migration:

// Before (implicit h1)
<Text variant="heading1">Title</Text>

// After (explicit semantic element)
<Text variant="heading1" as="h1">Title</Text>

---

• Reviews
• bonk has reviewed the change
• automated review not possible because: simple prop type change and documentation update - no complex logic to review
• Tests
• Tests included/updated
• Automated tests not possible - manual testing has been completed as follows:
• Additional testing not necessary because: This is a behavioral change with updated types; existing type system validates usage

[pkg-pr-new]

npm i https://pkg.pr.new/@cloudflare/kumo@393

commit: 7854ac3

[github-actions]

Docs Preview

View docs preview

Commit: 6a3f074

[github-actions]

Visual Regression Report — 15 changed, 21 unchanged

15 screenshot(s) with visual changes:

Button / Variant: Destructive

585 px (0.58%) changed

Before	After	Diff

Button / Loading State

204 px (0.2%) changed

Before	After	Diff

Dialog / Dialog Basic

114 px (0.11%) changed

Before	After	Diff

Dialog / Dialog Alert

862 px (0.85%) changed

Before	After	Diff

Dialog / Dialog Confirmation

352 px (0.35%) changed

Before	After	Diff

Dialog (Open)

0 px (0%) changed

Before	After	Diff

Select / Select Without Label

160 px (0.16%) changed

Before	After	Diff

Select / Select With Field

0 px (0%) changed

Before	After	Diff

Select / Select Loading

0 px (0%) changed

Before	After	Diff

Select / Select Multiple

801 px (0.79%) changed

Before	After	Diff

Select / Select Complex

1,190 px (1%) changed

Before	After	Diff

Select / Select Disabled Items

240 px (0.24%) changed

Before	After	Diff

Select / Select Grouped

362 px (0.36%) changed

Before	After	Diff

Select / Select Long List

1,538 px (1.3%) changed

Before	After	Diff

Select (Open)

183 px (0%) changed

Before	After	Diff

21 screenshot(s) unchanged

• Button / Basic
• Button / Variant: Primary
• Button / Variant: Secondary
• Button / Variant: Ghost
• Button / Variant: Outline
• Button / Variant: Secondary Destructive
• Button / Sizes
• Button / With Icon
• Button / Icon Only
• Button / Disabled State
• Button / Title
• Dialog / Dialog With Actions
• Dialog / Dialog With Select
• Dialog / Dialog With Combobox
• Dialog / Dialog With Dropdown
• Select / Select Basic
• Select / Select Placeholder
• Select / Select With Tooltip
• Select / Select Custom Rendering
• Select / Select Disabled Options
• Select / Select Grouped With Disabled

---

Generated by Kumo Visual Regression

[geoquant]

/bonk review pls

[ask-bonk]

Review of PR #393

This is a well-architected change that properly decouples visual presentation from semantic HTML structure. Here's my assessment:

✅ What's Good

1. Clean Implementation
The change in text.tsx correctly removes the implicit <h1>/<h2>/<h3> mapping and defaults heading variants to <span>. The useMemo logic is clean and the comment explains the rationale well.

2. Type Safety
Restricting the as prop to TextElement (h1-h6, p, span) prevents misuse while maintaining flexibility.

3. Documentation
The MDX page now includes a dedicated "Semantic HTML" section with clear examples showing:

• The default behavior (span rendering)
• How to use as for semantic elements
• That visual and semantic levels can be independent

4. Demo Updates
The TextDemo.tsx has been updated to use as="h1", as="h2", as="h3" with the heading variants, which serves as a visual example of the new pattern.

5. Changeset
Proper minor version bump with clear migration instructions.

⚠️ Visual Regression Results

The 19 screenshot changes are all minor pixel differences (0.07% - 1.18%) in components that use Text internally (Button titles, Dialog headers, Select labels). These are expected side effects from the rendering change and appear to be acceptable visual noise.

📝 Minor Suggestion

Consider updating the JSDoc example in text.tsx line 191:

// Current (slightly misleading since it doesn't show `as` prop)
 * <Text variant="heading1">Page Title</Text>

// Suggested (matches the new pattern)
 * <Text variant="heading1" as="h1">Page Title</Text>

This would align the inline documentation with the actual recommended usage pattern demonstrated in the component's docstring at lines 239-240.

Summary

Approve – This is a solid breaking change that improves accessibility by forcing explicit semantic choices. The migration path is clear, types enforce correct usage, and documentation is comprehensive.

github run