Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(text): add display types to XDSText for hero text and data callouts (#666)

Ernest8280c40f8563
diff --git a/packages/core/src/Text/XDSText.tsx b/packages/core/src/Text/XDSText.tsx
index 736c36bd67..5867857bef 100644
--- a/packages/core/src/Text/XDSText.tsx
+++ b/packages/core/src/Text/XDSText.tsx
@@ -158,10 +158,11 @@ export interface XDSTextProps {
children: ReactNode;
/**
- * HTML element to render
+ * HTML element to render.
+ * Includes h1-h3 for display types that need heading semantics.
* @default 'span'
*/
- as?: 'span' | 'p' | 'div' | 'label';
+ as?: 'span' | 'p' | 'div' | 'label' | 'h1' | 'h2' | 'h3';
'data-testid'?: string;
id?: string;
@@ -174,6 +175,9 @@ const defaultColorByType: Record<XDSTextType, XDSTextColor> = {
label: 'primary',
supporting: 'secondary',
code: 'primary',
+ 'display-1': 'primary',
+ 'display-2': 'primary',
+ 'display-3': 'primary',
};
/**
@@ -186,8 +190,9 @@ const defaultColorByType: Record<XDSTextType, XDSTextColor> = {
* <XDSText type="label">Form label</XDSText>
* <XDSText type="supporting">Helper text</XDSText>
* <XDSText type="code">{'const x = 1;'}</XDSText>
+ * <XDSText type="display-1" as="h1">Hero Title</XDSText>
+ * <XDSText type="display-2">$1.2M Revenue</XDSText>
* <XDSText type="body" maxLines={2}>Clamped text</XDSText>
- * <XDSText type="body" color="secondary" weight="bold">Styled text</XDSText>
* ```
*/
export function XDSText({
diff --git a/packages/core/src/theme/defineTheme.test.ts b/packages/core/src/theme/defineTheme.test.ts
index b7c6307d05..5f09bacf3c 100644
--- a/packages/core/src/theme/defineTheme.test.ts
+++ b/packages/core/src/theme/defineTheme.test.ts
@@ -255,7 +255,7 @@ describe('typeScale', () => {
const typeScaleKeys = Object.keys(theme.tokens).filter(
k => k.startsWith('--heading-') || k.startsWith('--text-'),
);
- expect(typeScaleKeys).toHaveLength(44);
+ expect(typeScaleKeys).toHaveLength(54);
});
it('explicit tokens override typeScale-generated values', () => {
diff --git a/packages/core/src/theme/expandTypeScale.test.ts b/packages/core/src/theme/expandTypeScale.test.ts
index 03a3015948..cac325fd3a 100644
--- a/packages/core/src/theme/expandTypeScale.test.ts
+++ b/packages/core/src/theme/expandTypeScale.test.ts
@@ -23,6 +23,7 @@ describe('expandTypeScale', () => {
'--text-2xl',
'--text-3xl',
'--text-4xl',
+ '--text-5xl',
];
for (const name of sizeTokens) {
expect(tokens[name]).toBeDefined();
@@ -93,6 +94,31 @@ describe('expandTypeScale', () => {
expect(tokens['--text-body-weight']).toBe('var(--font-weight-normal)');
expect(tokens['--text-large-weight']).toBe('var(--font-weight-semibold)');
expect(tokens['--text-label-weight']).toBe('var(--font-weight-medium)');
+ expect(tokens['--text-code-weight']).toBe('var(--font-weight-normal)');
+ expect(tokens['--text-supporting-weight']).toBe(
+ 'var(--font-weight-normal)',
+ );
+ });
+
+ it('computes display sizes continuing the progression above h1', () => {
+ // display-1 = 14 × 1.2⁶ ≈ 41.80 → 42px → 2.625rem (largest)
+ expect(tokens['--text-display-1-size']).toBe('var(--text-5xl)');
+ // display-2 = 14 × 1.2⁵ ≈ 34.84 → 35px → 2.1875rem
+ expect(tokens['--text-display-2-size']).toBe('var(--text-4xl)');
+ // display-3 = 14 × 1.2⁴ ≈ 29.03 → 29px → 1.8125rem (closest to h1)
+ expect(tokens['--text-display-3-size']).toBe('var(--text-3xl)');
+ });
+
+ it('assigns normal weight to display types by default', () => {
+ expect(tokens['--text-display-1-weight']).toBe(
+ 'var(--font-weight-normal)',
+ );
+ expect(tokens['--text-display-2-weight']).toBe(
+ 'var(--font-weight-normal)',
+ );
+ expect(tokens['--text-display-3-weight']).toBe(
+ 'var(--font-weight-normal)',
+ );
});
it('all line heights snap to 4px grid', () => {
@@ -146,8 +172,8 @@ describe('expandTypeScale', () => {
describe('total token count', () => {
const tokens = expandTypeScale({base: 14, ratio: 1.2});
- it('generates 44 tokens (11 size + 33 semantic)', () => {
- expect(Object.keys(tokens)).toHaveLength(44);
+ it('generates 54 tokens (12 size + 42 semantic)', () => {
+ expect(Object.keys(tokens)).toHaveLength(54);
});
});
@@ -212,6 +238,44 @@ describe('expandTypeScale', () => {
});
describe('generateTypeScaleComponents', () => {
+ it('generates heading and text component keys', () => {
+ const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
+ expect(components).toHaveProperty('heading');
+ expect(components).toHaveProperty('text');
+ });
+
+ it('generates rules for all 6 heading levels', () => {
+ const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
+ for (let level = 1; level <= 6; level++) {
+ expect(components.heading).toHaveProperty(`level:${level}`);
+ }
+ });
+
+ it('generates rules for all 8 text types (including display)', () => {
+ const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
+ for (const type of [
+ 'body',
+ 'large',
+ 'label',
+ 'code',
+ 'supporting',
+ 'display-1',
+ 'display-2',
+ 'display-3',
+ ]) {
+ expect(components.text).toHaveProperty(`type:${type}`);
+ }
+ });
+
+ it('heading rules include fontFamily, fontSize, fontWeight, lineHeight', () => {
+ const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
+ const h1 = components.heading['level:1'];
+ expect(h1.fontFamily).toBe('var(--font-heading)');
+ expect(h1.fontSize).toBe('var(--heading-1-size)');
+ expect(h1.fontWeight).toBe('var(--heading-1-weight)');
+ expect(h1.lineHeight).toBe('var(--heading-1-leading)');
+ });
+
it('generates heading and text component overrides', () => {
const components = generateTypeScaleComponents({base: 14, ratio: 1.2});
expect(components.heading).toBeDefined();
diff --git a/packages/core/src/theme/expandTypeScale.ts b/packages/core/src/theme/expandTypeScale.ts
index bbadf1d394..6886a9c6e2 100644
--- a/packages/core/src/theme/expandTypeScale.ts
+++ b/packages/core/src/theme/expandTypeScale.ts
@@ -65,7 +65,17 @@ export type HeadingWeightOverrides = Partial<
* Keys are text type names, values are CSS font-weight values.
*/
export type TextWeightOverrides = Partial<
- Record<'body' | 'large' | 'label' | 'code' | 'supporting', FontWeightValue>
+ Record<
+ | 'body'
+ | 'large'
+ | 'label'
+ | 'code'
+ | 'supporting'
+ | 'display-1'
+ | 'display-2'
+ | 'display-3',
+ FontWeightValue
+ >
>;
/**
@@ -145,6 +155,7 @@ const STEP_TO_SIZE_TOKEN: Record<number, string> = {
[3]: '--text-2xl',
[4]: '--text-3xl',
[5]: '--text-4xl',
+ [6]: '--text-5xl',
};
/**
@@ -170,6 +181,9 @@ const TEXT_STEPS: Record<string, number> = {
label: 0,
code: 0,
supporting: -1,
+ 'display-1': 6, // largest — continues progression above h1
+ 'display-2': 5,
+ 'display-3': 4, // closest to h1
};
/**
@@ -193,6 +207,24 @@ const DEFAULT_TEXT_WEIGHTS: Record<string, string> = {
label: 'var(--font-weight-medium)',
code: 'var(--font-weight-normal)',
supporting: 'var(--font-weight-normal)',
+ 'display-1': 'var(--font-weight-normal)',
+ 'display-2': 'var(--font-weight-normal)',
+ 'display-3': 'var(--font-weight-normal)',
+};
+
+/**
+ * Line-height target ratios. Headings are tighter, body text is more generous.
+ */
+const HEADING_LH_RATIO = 1.3;
+const TEXT_LH_RATIOS: Record<string, number> = {
+ body: 1.5,
+ large: 1.45,
+ label: 1.4,
+ code: 1.5,
+ supporting: 1.5,
+ 'display-1': 1.2, // tighter — large text reads better tight
+ 'display-2': 1.2,
+ 'display-3': 1.2,
};
// =============================================================================
@@ -244,9 +276,14 @@ function computeLeading(fontSize: number): number {
*
* Generates two layers of tokens:
* - Layer 1: 11 raw size tokens (--text-4xs … --text-4xl) in rem
- * - Layer 2: 33 semantic tokens using var() refs for sizes and
+ * - Layer 2: semantic tokens using var() refs for sizes and
* hardcoded computed values for line heights
*
+ * Includes 6 heading levels × 3 + 8 text types × 3 (body, large, label, code, supporting, display-1/2/3).
+ * Font sizes are emitted as rem values (e.g. '1.5rem') based on 16px root.
+ * Line heights are emitted as unitless ratios (e.g. '1.3333').
+ * Font weights are emitted as var() references (e.g. '''var(--font-weight-semibold)'''').
+ *
* @example
* ```
* const tokens = expandTypeScale({ base: 14, ratio: 1.2 });
@@ -276,7 +313,7 @@ export function expandTypeScale(config: XDSTypeScaleConfig): TypeScaleTokens {
};
// ── Layer 1: Raw size tokens (rem) ────────────────────────────────────────
- for (let step = -5; step <= 5; step++) {
+ for (let step = -5; step <= 6; step++) {
const size = computeSize(base, ratio, step);
tokens[STEP_TO_SIZE_TOKEN[step]] = pxToRem(size);
}
@@ -320,6 +357,9 @@ const TEXT_FONT_FAMILIES: Record<string, string> = {
label: 'var(--font-body)',
code: 'var(--font-code)',
supporting: 'var(--font-body)',
+ 'display-1': 'var(--font-heading)',
+ 'display-2': 'var(--font-heading)',
+ 'display-3': 'var(--font-heading)',
};
/**
@@ -342,7 +382,16 @@ export function generateTypeScaleComponents(
components.heading = headingRules;
const textRules: Record<string, Record<string, string>> = {};
- for (const type of ['body', 'large', 'label', 'code', 'supporting']) {
+ for (const type of [
+ 'body',
+ 'large',
+ 'label',
+ 'code',
+ 'supporting',
+ 'display-1',
+ 'display-2',
+ 'display-3',
+ ]) {
textRules[`type:${type}`] = {
fontFamily: TEXT_FONT_FAMILIES[type],
fontSize: `var(--text-${type}-size)`,
diff --git a/packages/core/src/theme/tokens.stylex.ts b/packages/core/src/theme/tokens.stylex.ts
index afd6d7622e..cc13b36e4f 100644
--- a/packages/core/src/theme/tokens.stylex.ts
+++ b/packages/core/src/theme/tokens.stylex.ts
@@ -310,6 +310,7 @@ export const textSizeDefaults = {
'--text-2xl': '1.5rem', // step +3: 24px (14 × 1.2³ ≈ 24.19 → 24)
'--text-3xl': '1.8125rem', // step +4: 29px (14 × 1.2⁴ ≈ 29.03 → 29)
'--text-4xl': '2.1875rem', // step +5: 35px (14 × 1.2⁵ ≈ 34.84 → 35)
+ '--text-5xl': '2.625rem', // step +6: 42px (14 × 1.2⁶ ≈ 41.80 → 42)
} as const;
/** @deprecated Use textSizeDefaults */
@@ -423,6 +424,20 @@ export const typeScaleDefaults = {
'--text-supporting-size': 'var(--text-sm)', // 12px
'--text-supporting-weight': 'var(--font-weight-normal)',
'--text-supporting-leading': '1.6667', // 12px → 20px
+
+ // Display tokens — continue the geometric progression above h1.
+ // Display 1 = step +6 (largest, 42px), Display 3 = step +4 (29px, closest to h1).
+ // Line heights are tighter (~1.2) than headings (~1.3) since large text reads better tight.
+ // Font weight is normal (400) to balance the visual presence of large sizes.
+ '--text-display-1-size': 'var(--text-5xl)', // 42px (14 × 1.2⁶, largest)
+ '--text-display-1-weight': 'var(--font-weight-normal)',
+ '--text-display-1-leading': '1.2381',
+ '--text-display-2-size': 'var(--text-4xl)', // 35px (14 × 1.2⁵)
+ '--text-display-2-weight': 'var(--font-weight-normal)',
+ '--text-display-2-leading': '1.2571',
+ '--text-display-3-size': 'var(--text-3xl)', // 29px (14 × 1.2⁴, closest to h1)
+ '--text-display-3-weight': 'var(--font-weight-normal)',
+ '--text-display-3-leading': '1.2414',
} as const;
export const typeScaleVars = stylex.defineVars(typeScaleDefaults);
diff --git a/packages/core/src/theme/types.ts b/packages/core/src/theme/types.ts
index 58616d4e17..baca767865 100644
--- a/packages/core/src/theme/types.ts
+++ b/packages/core/src/theme/types.ts
@@ -20,7 +20,15 @@ export type HeadingLevel = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
/**
* Semantic text types for XDSText
*/
-export type XDSTextType = 'body' | 'large' | 'label' | 'supporting' | 'code';
+export type XDSTextType =
+ | 'body'
+ | 'large'
+ | 'label'
+ | 'supporting'
+ | 'code'
+ | 'display-1'
+ | 'display-2'
+ | 'display-3';
/**
* Text size scale for XDSText size prop override