@@ -73,10 +73,21 @@ const findTypography = (
7373
7474export type TypographyProps = {
7575 /** Typography variants, specifies which variant to use.
76+ *
77+ * Quick variants can be used without providing `group`.
78+ * These are the variants merged into `quickVariants` from the `heading`,
79+ * `paragraph`, `marks`, and `plain` groups in `variants.ts`.
80+ *
81+ * Variants that only exist in grouped collections, such as `display` or `card`,
82+ * should be paired with the matching `group` prop so the class lookup resolves correctly.
7683 * @default body
7784 */
7885 variant ?: TypographyVariants
79- /** Typography groups, specifies which group to use. */
86+ /** Typography groups, specifies which group to use.
87+ *
88+ * Optional when `variant` is a quick variant.
89+ * Required in practice for grouped-only variants such as `h1_base`, `h2_lg`, or card-specific styles.
90+ */
8091 group ?: TypographyGroups
8192 /** Override the element type */
8293 as ?: ElementType
@@ -96,12 +107,31 @@ export type TypographyProps = {
96107
97108/**
98109 * Typography used for common text styles
110+ *
111+ * When `group` is omitted, the component first resolves `variant` against the shared
112+ * quick variant map. That supports the common heading, paragraph, marks, and plain variants
113+ * without extra configuration.
114+ *
115+ * Use `group` when selecting a variant that belongs to a specific collection such as
116+ * `display`, `card`, or `article`.
117+ *
99118 * @example
100119 * ```jsx
101120 * <Typography variant="h6" as="h2" className="text-moss-green-100">
102121 * I am a h2 heading with h6 styling with classname override
103122 * </Typography>
104123 * ```
124+ *
125+ * @example
126+ * ```jsx
127+ * <Typography variant="body">
128+ * Quick variants like body resolve without a group.
129+ * </Typography>
130+ *
131+ * <Typography variant="h2_base" group="display">
132+ * Display variants should be used with their group.
133+ * </Typography>
134+ * ```
105135 */
106136export const Typography : OverridableComponent < TypographyProps , HTMLElement > =
107137 forwardRef ( function Typography (
@@ -123,9 +153,7 @@ export const Typography: OverridableComponent<TypographyProps, HTMLElement> =
123153
124154 if ( typeof typography === 'undefined' ) {
125155 console . warn (
126- `Typography variant not found for variant "${ variant } " ("${ variant } ") & group "${
127- group || ''
128- } "`,
156+ `Typography variant not found for variant "${ variant } " & group "${ group ?? '' } "` ,
129157 )
130158 }
131159 const TypographyTag = as ?? ( `p` as React . ElementType )
0 commit comments