Heading

Heading text with configurable size and semantic HTML level, suitable for page titles, section headers, and establishing content hierarchy.

Use Cases

• Page titles (H1, size: ‘xxl’ or ‘xxxl’)
• Section headers (H2, size: ‘xl’ or ‘xxl’)
• Subsection headers (H3, size: ‘lg’ or ‘xl’)
• Card titles (H3/H4, size: ‘md’ or ‘lg’)
• Form section headers

Properties

text

Heading text content. Type: string.

size

Visual size of heading text (independent of semantic level). Type: string. Options: xxxl, xxl, xl, l, m, s, xs. Default: m.

Tip: Visual impact per size – xxxl: 72px (Extra large page titles), xxl: 60px (Large page titles, hero headings), xl: 48px (Section headers, H2 headings), l: 36px (Subsection headers, H3 headings), m: 30px (Card titles, H4 headings, default), s: 24px (Small headings), xs: 20px (Tiny headings).

Tip: Recommendations – page-titles: Use ‘xxl’ or ‘xxxl’ for page titles (H1); sections: Use ‘xl’ for main section headers (H2); subsections: Use ‘l’ for subsections (H3); cards: Use ‘m’ for card titles (default).

level

Semantic HTML heading level for accessibility and SEO. Should follow document hierarchy. Type: number. Options: 1, 2, 3, 4, 5, 6. Default: 2.

Tip: Recommendations – page-title: Use level: 1 for page title (only one H1 per page); sections: Use level: 2 for main sections; subsections: Use level: 3 for subsections; cards: Use level: 3 or 4 for card titles.

align

Text alignment. Type: string. Options: left, center, right. Default: left.

Tip: Recommendations – page-titles: Use ‘center’ for centered page titles and hero headings; sections: Use ‘left’ for most section headers (standard alignment); special-cases: Use ‘right’ sparingly for specific design needs.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property-value pairs. Type: string.

Tip: Examples – “background-color: #f9fafb; padding: 16px; border-radius: 8px;”, “color: #3b82f6; font-weight: bold; text-transform: uppercase;”.

Tip: Security note – Parsed by cssParser utility. Tenants only affect their own pages (multi-tenant isolation enforced).

Best Practices

• Use only ONE H1 per page (typically page title with size: ‘xxl’ or ‘xxxl’)
• Follow semantic hierarchy: H1 → H2 → H3 → H4 (don’t skip levels)
• Match size to visual prominence: H1 = ‘xxl’/‘xxxl’, H2 = ‘xl’/‘xxl’, H3 = ‘lg’/‘xl’
• Use align: ‘center’ for page titles and hero headings, align: ‘left’ for section headers
• Keep heading text concise (3-8 words typically)

Common Mistakes

Multiple H1 headings on same page

Why it's a problem: Violates HTML semantics and SEO best practices - confuses search engines about page structure

Fix: Use only ONE heading with level: 1 per page (page title). Use level: 2-6 for other headings.

Skipping heading levels (H1 → H3, skipping H2)

Why it's a problem: Breaks semantic document hierarchy - accessibility tools and screen readers rely on proper nesting

Fix: Follow hierarchy: H1 → H2 → H3 → H4. Don’t skip levels.

Using heading level only for size (e.g., H5 for small text in hero section)

Why it's a problem: Confuses semantic structure with visual styling - breaks accessibility

Fix: Use level for semantic hierarchy, size for visual appearance. Can have H2 with size: ‘xxxl’ for large section header.

Not setting size to match visual prominence

Why it's a problem: H1 page title looks same size as H3 subsection - no visual hierarchy

Fix: Match size to importance: H1 = ‘xxl’/‘xxxl’, H2 = ‘xl’, H3 = ‘l’, H4 = ‘m’