Flagsmith / Flagsmith/flagsmith

Create Typography components: <Heading> and <Text>

Open
#7,077 1 comment 0 reactions 0 assignees View on GitHub
design-system front-end tech-debt
Dominant language
Python
Stars
6.6k
Forks
567
Avg merge
1d 13h
Merged PRs (30d)
121

Description

## Problem

The codebase has no typography components. Developers use raw `h1`–`h6` tags with inconsistent sizing, inline `fontSize` in style props (49 occurrences), and guess font weights from nearby code.

### Known issues

- **`h5` used 64 times** — more than all other headings combined (h1: 1, h2: 6, h3: 15, h4: 10, h6: 12). Most are labels or card headers that need bold 18px text, not semantic subsections.
- **49 inline font sizes in JSX** — `style={{ fontSize: 13 }}` bypasses the type scale and is invisible to the design system.
- **No font-weight tokens** — weights defined per-component (`$btn-font-weight: 700`, `$input-font-weight: 500`) with no shared tokens. Font weight tokens now exist (`--font-weight-regular/medium/semibold/bold`) but no component enforces them.
- **Fragmented naming** — `$font-sm` (14px) vs `$font-caption` (13px) — unclear relationship.
- **Non-standard sizes** — 11px and 13px are off the industry base-4 grid (12, 14, 16, 18, 20, 24, 30, 36, 48).

## Solution

### `` component

Replaces raw `h1`–`h6` tags. Visual size decoupled from HTML element:

```tsx
Page title // 24px, renders h1
Section title // 18px, renders h2
Subsection // 16px, renders h3
Card title // 14px, renders h3
```

### `` component

Replaces `fs-small`, `text-muted`, inline `fontSize`, and raw `

`/`` with font styling:

```tsx
Body text (14px, default)
Small text (12px)
Muted text
Medium weight (500)
```

### Migration path

1. Build components using current scale values (no visual change)
2. Use in new code — stop writing raw heading tags and inline font sizes
3. Migrate existing code opportunistically when touching files
4. Adjust scale if needed once adoption is high

## Acceptance criteria

- [ ] `` component with `size` and `as` props, using `--font-h*` tokens
- [ ] `` component with `size`, `color`, `weight`, and `as` props
- [ ] Both components handle dark mode via semantic colour tokens
- [ ] Storybook stories covering all variants
- [ ] No visual regression on existing pages

---
Part of the Design System Audit (#6606) · Epic: #6882

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.