Skip to content

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

TypeScript

docs(dense): add missing bestPractices to ChatLayout and FieldStatus overlays (#2822)

Joey79c1861bbd25
diff --git a/packages/core/src/Chat/ChatLayout.doc.mjs b/packages/core/src/Chat/ChatLayout.doc.mjs
index ef3b9121a2..49d79f1cdb 100644
--- a/packages/core/src/Chat/ChatLayout.doc.mjs
+++ b/packages/core/src/Chat/ChatLayout.doc.mjs
@@ -125,6 +125,15 @@ export const docsDense = {
name: 'ChatLayout',
displayName: 'Chat Layout',
description: 'layout shell for full chat; msgs in page flow, composer fixed bottom w/ frosted glass dock; auto density via container width; scrollRef delegates to parent/body',
+ usage: {
+ bestPractices: [
+ {guidance: true, description: 'Pass XDSChatMessageList as children and XDSChatComposer as composer prop for complete chat.'},
+ {guidance: true, description: 'Provide emptyState so new conversations show a prompt, not blank screen.'},
+ {guidance: true, description: 'Use scrollRef when chat is embedded in a page where a parent element handles scrolling.'},
+ {guidance: false, description: 'Apply fixed height on layout; let it fill container with flex: 1.'},
+ {guidance: false, description: 'Render multiple ChatLayout instances in same scroll container; each expects to own its scroll context.'},
+ ],
+ },
propDescriptions: {
children: 'msg content; typically XDSChatMessageList',
composer: 'composer element; typically XDSChatComposer; fixed bottom w/ frosted glass',
diff --git a/packages/core/src/FieldStatus/FieldStatus.doc.mjs b/packages/core/src/FieldStatus/FieldStatus.doc.mjs
index af05cfdc20..ca68c50705 100644
--- a/packages/core/src/FieldStatus/FieldStatus.doc.mjs
+++ b/packages/core/src/FieldStatus/FieldStatus.doc.mjs
@@ -67,6 +67,13 @@ export const docs = {
export const docsDense = {
description:
'Validation feedback message for fields/custom controls. Supports error, warning, success and attached/detached variants.',
+ usage: {
+ bestPractices: [
+ {guidance: true, description: 'Use attached status below bordered inputs when message belongs to that input.'},
+ {guidance: true, description: 'Use detached status for checkboxes, switches, and custom controls where overlap is visually awkward.'},
+ {guidance: false, description: 'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.'},
+ ],
+ },
propDescriptions: {
type: 'error/warning/success status tone',
message: 'visible validation feedback text',