An open source design system that's fully customizable and agent ready
TypeScript
docs(Badge, Card, Section): fix LLM overuse patterns (#2377)
Cindy Zhang79d3d1cb48b7
diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjsindex bf7b28de56..caad198523 100644--- a/packages/core/src/Badge/Badge.doc.mjs+++ b/packages/core/src/Badge/Badge.doc.mjs@@ -38,11 +38,17 @@ export const docs = {},usage: {description:- 'Badge shows a short label like a status, count, or category. Use it in table rows, list items, navigation, and anywhere you need to call out a state or group at a glance.',+ 'Badge highlights a status or category at a glance. Use it sparingly — only when a value represents a distinct state (Active, Failed) or a grouping tag (Engineering, Design). Most metadata (dates, durations, counts, descriptions) should be plain description text, not badges.',bestPractices: [- {guidance: true, description: 'Use success, warning, and error variants for system status like "Active", "Pending", or "Failed". Use color variants like blue, purple, or teal for categories and tags.'},+ {guidance: true, description: 'Every status badge steals attention. Only badge states where the user needs to notice or act — errors, warnings, items requiring follow-up. If no action is needed, plain text is fine.'},+ {guidance: true, description: 'Use success, warning, and error variants only for system status that demands attention — "Failed", "Degraded", "Action Required". These have bold solid backgrounds designed to stand out.'},+ {guidance: true, description: 'Use color variants (blue, purple, teal, etc.) for category tags that group or classify items — team names, content types, priority levels.'},{guidance: true, description: 'Keep labels to one or two words. If you need more detail, put it in surrounding text instead of the badge.'},{guidance: true, description: 'Add an icon when it helps identify the badge type quickly, but always include a text label alongside it.'},+ {guidance: false, description: 'Apply a "success" badge to every healthy/active/normal item. If all rows show green "Active" badges, none stand out — the badge adds noise, not information. Show only the states that need user attention (errors, warnings, pending actions).'},+ {guidance: false, description: 'Use badges for metadata. Durations ("6h window"), counts ("12 trigger types"), dates, and descriptions are not statuses or categories — use description text (XDSText with type="supporting") instead.'},+ {guidance: false, description: 'Use semantic status variants (success, warning, error, info) for categories or informational content. These are visually loud and should only indicate system state.'},+ {guidance: false, description: 'Repeat the same badge in every row of a table or list. If the same value appears in most rows, it\'s not adding information — use plain text for common states and reserve badges for the exceptional ones.'},{guidance: false, description: 'Make badges clickable — they are read-only indicators. Use a button or link if the user needs to take action.'},],anatomy: [@@ -57,11 +63,17 @@ export const docsZh = {name: 'Badge',usage: {description:- 'Badge shows a short label like a status, count, or category. Use it in table rows, list items, navigation, and anywhere you need to call out a state or group at a glance.',+ 'Badge highlights a status or category at a glance. Use it sparingly — only when a value represents a distinct state (Active, Failed) or a grouping tag (Engineering, Design). Most metadata (dates, durations, counts, descriptions) should be plain description text, not badges.',bestPractices: [- {guidance: true, description: 'Use success, warning, and error variants for system status like "Active", "Pending", or "Failed". Use color variants like blue, purple, or teal for categories and tags.'},+ {guidance: true, description: 'Every status badge steals attention. Only badge states where the user needs to notice or act — errors, warnings, items requiring follow-up. If no action is needed, plain text is fine.'},+ {guidance: true, description: 'Use success, warning, and error variants only for system status that demands attention — "Failed", "Degraded", "Action Required". These have bold solid backgrounds designed to stand out.'},+ {guidance: true, description: 'Use color variants (blue, purple, teal, etc.) for category tags that group or classify items — team names, content types, priority levels.'},{guidance: true, description: 'Keep labels to one or two words. If you need more detail, put it in surrounding text instead of the badge.'},{guidance: true, description: 'Add an icon when it helps identify the badge type quickly, but always include a text label alongside it.'},+ {guidance: false, description: 'Apply a "success" badge to every healthy/active/normal item. If all rows show green "Active" badges, none stand out — the badge adds noise, not information. Show only the states that need user attention (errors, warnings, pending actions).'},+ {guidance: false, description: 'Use badges for metadata. Durations ("6h window"), counts ("12 trigger types"), dates, and descriptions are not statuses or categories — use description text (XDSText with type="supporting") instead.'},+ {guidance: false, description: 'Use semantic status variants (success, warning, error, info) for categories or informational content. These are visually loud and should only indicate system state.'},+ {guidance: false, description: 'Repeat the same badge in every row of a table or list. If the same value appears in most rows, it\'s not adding information — use plain text for common states and reserve badges for the exceptional ones.'},{guidance: false, description: 'Make badges clickable — they are read-only indicators. Use a button or link if the user needs to take action.'},],anatomy: [@@ -94,13 +106,19 @@ export const docsZh = {/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'short label for status, counts, or categories',+ description: 'highlights a status or category tag — NOT for general metadata',usage: {description:- 'Badge shows a short label like a status, count, or category. Use in table rows, list items, navigation, or anywhere you need to call out a state or group.',+ 'Badge is for status (Active, Failed) and category tags (Engineering, Design). It is NOT for metadata like dates, durations, counts, or descriptions — use description text (XDSText type="supporting") for those.',bestPractices: [- {guidance: true, description: 'Use success/warning/error for system status. Use color variants for categories and tags.'},+ {guidance: true, description: 'Every badge steals attention. Only badge states where the user needs to act. If no follow-up is needed, use plain text.'},+ {guidance: true, description: 'Use success/warning/error ONLY for system status requiring attention (Failed, Degraded, Action Required). These are visually loud — solid colored backgrounds.'},+ {guidance: true, description: 'Use color variants (blue, purple, teal) for category tags that classify items — team names, content types, priority levels.'},{guidance: true, description: 'Keep labels to one or two words. Add an icon only when it helps identify the badge type.'},+ {guidance: false, description: 'Apply "success" badges to every healthy/normal item. If most rows are green "Active", none stand out. Skip the badge for the default state — only highlight exceptions that need attention.'},+ {guidance: false, description: 'Use badges for metadata. Durations, counts, dates, descriptions → use XDSText with type="supporting" instead.'},+ {guidance: false, description: 'Use status variants for non-status info. "6h window", "12 types", category names are NOT statuses.'},+ {guidance: false, description: 'Repeat loud badges in every row. Common/default states should be plain text; reserve badges for the exceptional.'},{guidance: false, description: 'Make badges clickable — they are read-only. Use a button or link for actions.'},],anatomy: [diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjsindex 05943d84e4..d2168fe091 100644--- a/packages/core/src/Card/Card.doc.mjs+++ b/packages/core/src/Card/Card.doc.mjs@@ -8,13 +8,17 @@ export const docs = {keywords: ["card","surface","panel","container","elevated","shadow","box","paper","tile","well"],usage: {description:- 'Card groups related content into a visually distinct container with a border and background. Use it for profile cards, settings panels, data summaries, or any content that needs to stand out from the page.',+ 'Card is a bordered, elevated container for discrete, self-contained items — things you could reorder, remove, or interact with independently. Cards are NOT the default layout tool. Most content groups don\'t need a container at all — spacing and alignment create visual grouping naturally. Only reach for a Card when items need clear interaction boundaries or visual comparison in a grid.',bestPractices: [- {guidance: true, description: 'Try a section first — only use a card when you need the visual separation of a border and elevated background.'},+ {guidance: true, description: 'Ask "could I reorder or remove this independently?" If yes, it\'s a card. If no, it\'s just a section of the page — use a heading + XDSStack or XDSSection.'},+ {guidance: true, description: 'Use cards for discrete items: a single user profile, a single notification, a single metric, a product in a grid. Each card represents one "thing" with clear interaction boundaries.'},+ {guidance: true, description: 'Spacing and alignment alone create visual grouping. Not everything needs a container — try removing the card and see if the grouping is still clear from whitespace and typography.'},{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},- {guidance: true, description: 'Use the muted variant for secondary content like tips, callouts, or background information.'},{guidance: true, description: 'Pair a card with XDSLayout when you need a structured header, scrollable content, and footer with actions.'},- {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use a section instead.'},+ {guidance: false, description: 'Default to cards for visual grouping. A heading + XDSStack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.'},+ {guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups — these are page regions, use XDSSection or heading + stack.'},+ {guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},+ {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use spacing and dividers instead.'},{guidance: false, description: 'Use color variants for status — use Banner or Badge for that. Color cards are for categorization.'},],anatomy: [@@ -95,13 +99,17 @@ export const docsZh = {name: 'Card',usage: {description:- 'Card groups related content into a visually distinct container with a border and background. Use it for profile cards, settings panels, data summaries, or any content that needs to stand out from the page.',+ 'Card is a bordered, elevated container for discrete, self-contained items — things you could reorder, remove, or interact with independently. Cards are NOT the default layout tool. Most content groups don\'t need a container at all — spacing and alignment create visual grouping naturally. Only reach for a Card when items need clear interaction boundaries or visual comparison in a grid.',bestPractices: [- {guidance: true, description: 'Try a section first — only use a card when you need the visual separation of a border and elevated background.'},+ {guidance: true, description: 'Ask "could I reorder or remove this independently?" If yes, it\'s a card. If no, it\'s just a section of the page — use a heading + XDSStack or XDSSection.'},+ {guidance: true, description: 'Use cards for discrete items: a single user profile, a single notification, a single metric, a product in a grid. Each card represents one "thing" with clear interaction boundaries.'},+ {guidance: true, description: 'Spacing and alignment alone create visual grouping. Not everything needs a container — try removing the card and see if the grouping is still clear from whitespace and typography.'},{guidance: true, description: 'Keep padding consistent across sibling cards so they align visually in a grid or list.'},- {guidance: true, description: 'Use the muted variant for secondary content like tips, callouts, or background information.'},{guidance: true, description: 'Pair a card with XDSLayout when you need a structured header, scrollable content, and footer with actions.'},- {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use a section instead.'},+ {guidance: false, description: 'Default to cards for visual grouping. A heading + XDSStack with proper spacing creates hierarchy without adding borders everywhere. Cards should be the exception, not the default.'},+ {guidance: false, description: 'Wrap page sections in cards. "General Settings", "Notification Preferences", form groups — these are page regions, use XDSSection or heading + stack.'},+ {guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). Vary the layout or question whether cards are needed at all.'},+ {guidance: false, description: 'Nest cards inside other cards — flatten the hierarchy or use spacing and dividers instead.'},{guidance: false, description: 'Use color variants for status — use Banner or Badge for that. Color cards are for categorization.'},],anatomy: [@@ -134,12 +142,17 @@ export const docsZh = {/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {- description: 'bordered container for grouping related content',+ description: 'bordered container for DISCRETE items — NOT the default layout tool. Most content doesn\'t need a card.',usage: {description:- 'Card groups related content with a border and background. Use for profile cards, settings panels, data summaries.',+ 'Card is for discrete items with clear interaction boundaries (one profile, one notification, one product). Cards are NOT the default. Spacing and alignment create visual grouping without borders. Ask: "could I reorder or remove this independently?" — if no, don\'t use a card.',bestPractices: [- {guidance: true, description: 'Try a section first. Use muted variant for secondary content. Pair with XDSLayout for header/content/footer.'},+ {guidance: true, description: 'Use cards ONLY for discrete items you could reorder/remove independently. Not every group of content needs a container.'},+ {guidance: true, description: 'Try spacing + headings first. If the grouping is clear from whitespace and typography alone, you don\'t need a card.'},+ {guidance: true, description: 'For page sections (settings, forms, sidebars), use heading + XDSStack or XDSSection — not a card.'},+ {guidance: false, description: 'Default to wrapping content in cards. Cards should be the exception, not the reflex. Borders everywhere = visual noise.'},+ {guidance: false, description: 'Wrap page sections in cards. "General Settings" or "Preferences" are not cards.'},+ {guidance: false, description: 'Create identical card grids (icon + heading + text, repeated). This is the lazy default — vary layout or skip cards entirely.'},{guidance: false, description: 'Nest cards. Use color variants for status — use Banner or Badge instead.'},],},diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjsindex f941075002..eae3b27c46 100644--- a/packages/core/src/Section/Section.doc.mjs+++ b/packages/core/src/Section/Section.doc.mjs@@ -68,10 +68,13 @@ export const docs = {},usage: {description:- 'Section is a container that is used to create visual separation. Use the default variant for standard content (white), muted to emphasize or group related content (gray), and transparent for no background while still using Section\'s padding and dividers.',+ 'Section is the correct way to create page regions and group related content on a page. Use it for settings groups, form sections, sidebar areas, or any time you need visual separation between parts of a page. If you are tempted to use a Card for a page section — use XDSSection instead.',bestPractices: [+ { guidance: true, description: 'Use Section for page-level grouping: settings panels, form groups, sidebar regions. These are sections of a page, not discrete items.' },{ guidance: true, description: 'Start with the default variant. Use muted only to call attention to a specific region.' },{ guidance: true, description: 'Add dividers between same-background sections that need separation.' },+ { guidance: true, description: 'Combine with a heading + XDSStack for a typical page section pattern.' },+ { guidance: false, description: 'Use Card when you mean Section. Cards are for discrete items (one notification, one profile). Sections are for page regions.' },],},};@@ -141,10 +144,13 @@ export const docsZh = {},usage: {description:- 'Section is a container that is used to create visual separation. Use the default variant for standard content (white), muted to emphasize or group related content (gray), and transparent for no background while still using Section\'s padding and dividers.',+ 'Section is the correct way to create page regions and group related content on a page. Use it for settings groups, form sections, sidebar areas, or any time you need visual separation between parts of a page. If you are tempted to use a Card for a page section — use XDSSection instead.',bestPractices: [+ { guidance: true, description: 'Use Section for page-level grouping: settings panels, form groups, sidebar regions. These are sections of a page, not discrete items.' },{ guidance: true, description: 'Start with the default variant. Use muted only to call attention to a specific region.' },{ guidance: true, description: 'Add dividers between same-background sections that need separation.' },+ { guidance: true, description: 'Combine with a heading + XDSStack for a typical page section pattern.' },+ { guidance: false, description: 'Use Card when you mean Section. Cards are for discrete items (one notification, one profile). Sections are for page regions.' },],},};@@ -152,13 +158,14 @@ export const docsZh = {/** @type {import('../docs-types').TranslationDoc} */export const docsDense = {description:- 'Container w/ background variants for creating visually distinct regions; auto-escapes parent container padding for edge-to-edge fills.',+ 'Page-level container for grouping content into regions. Use INSTEAD of Card for settings panels, form groups, and page sections.',usage: {description:- 'Section is a container that is used to create visual separation. Use the default variant for standard content (white), muted to emphasize or group related content (gray), and transparent for no background while still using Section\'s padding and dividers.',+ 'Section creates page regions. Use for settings groups, form sections, sidebar areas. If you want to visually separate a part of a page, use Section — not Card. Cards are for discrete items (one profile, one notification).',bestPractices: [- { guidance: true, description: 'Start with the default variant. Use muted only to call attention to a specific region.' },- { guidance: true, description: 'Add dividers between same-background sections that need separation.' },+ { guidance: true, description: 'Use Section for page-level grouping (settings, forms, sidebars). Use heading + XDSStack inside for content.' },+ { guidance: true, description: 'Default variant = white surface. Muted = gray for emphasis. Add dividers for separation.' },+ { guidance: false, description: 'Use Card for page sections. Cards = discrete items. Sections = page regions.' },],},propDescriptions: {