@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Message/Message.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Message",
-  "description": "Individual chat message display with role-based styling",
+  "description": "Shows one chat message, styled by who sent it.",
   "category": "ai",
-  "tags": [
-    "message",
-    "chat",
-    "ai",
-    "conversation",
-    "bubble"
-  ],
+  "tags": ["message", "chat", "ai", "conversation", "bubble"],
   "status": "stable",
   "sourcePath": "src/components/Message/index.tsx",
   "exportName": "Message",
@@ -26,11 +20,7 @@
       "type": "enum",
       "description": "Message role determines styling and alignment",
       "required": true,
-      "values": [
-        "user",
-        "assistant",
-        "system"
-      ]
+      "values": ["user", "assistant", "system"]
     },
     "children": {
       "type": "node",
@@ -42,12 +32,7 @@
       "description": "Message state",
       "default": "complete",
       "required": false,
-      "values": [
-        "sending",
-        "streaming",
-        "complete",
-        "error"
-      ]
+      "values": ["sending", "streaming", "complete", "error"]
     },
     "timestamp": {
       "type": "object",
@@ -67,24 +52,24 @@
   },
   "usage": {
     "when": [
-      "Displaying individual messages in a chat interface",
-      "Building AI assistant or chatbot UIs",
-      "Need role-based message styling (user vs assistant)",
-      "Messages need actions like copy, regenerate, or feedback"
+      "Individual turns in a chat transcript",
+      "AI assistant and chatbot interfaces",
+      "User and assistant turns that must read differently",
+      "Turns carrying copy, regenerate, or feedback actions"
     ],
     "whenNot": [
-      "Simple text display without chat context (use Text)",
-      "Notification-style messages (use Alert or Toast)",
-      "Comment threads with nested replies (use Card with custom layout)"
+      "Plain text with no chat context (use Text)",
+      "Notifications (use Alert or Toast)",
+      "Threads with nested replies (use Card with a custom layout)"
     ],
     "guidelines": [
-      "Always provide a role prop to determine styling",
-      "Use status prop to show message state (sending, streaming, error)",
-      "Pass avatar={null}, or set showAvatars={false} on the parent ConversationList, to hide avatars; avatarless assistant content is flush while the user's own bubble keeps compact space-1/space-2 padding",
-      "User message bubbles are capped at 80% of the available inline measure so they remain visually distinct from assistant responses",
-      "User and assistant message chrome uses neutral surface tokens with the primary text foreground; reserve brand accent for actions or semantic state",
-      "Consider showing timestamps for longer conversations",
-      "Provide hover actions for assistant messages (copy, regenerate)"
+      "Always set role — it drives alignment, avatar, and chrome",
+      "status covers sending, streaming, and error",
+      "Hide avatars with avatar={null}, or showAvatars={false} on ConversationList",
+      "User bubbles cap at 80% of the inline measure so the two sides stay distinct",
+      "Chrome stays on neutral surfaces; reserve accent for actions and semantic state",
+      "Add timestamps once a conversation runs long",
+      "Give assistant turns hover actions such as copy and regenerate"
     ],
     "accessibility": [
       "Uses semantic HTML for message structure",
@@ -96,43 +81,43 @@
   "examples": [
     {
       "name": "User Message",
-      "description": "Message from the user (right-aligned)",
+      "description": "Right-aligned and capped at 80% of the available width.",
       "code": "<Message role=\"user\">\n  <Message.Content>\n    Hello! Can you help me with a coding question?\n  </Message.Content>\n</Message>"
     },
     {
       "name": "Assistant Message",
-      "description": "Response from the AI assistant",
+      "description": "Left-aligned with an avatar and a wider measure.",
       "code": "<Message role=\"assistant\">\n  <Message.Content>\n    Of course! I'd be happy to help. What would you like to know?\n  </Message.Content>\n</Message>"
     },
     {
       "name": "System Message",
-      "description": "System notification or context",
+      "description": "Centred and quiet, for context rather than conversation.",
       "code": "<Message role=\"system\">\n  <Message.Content>\n    Conversation started. Model: GPT-4\n  </Message.Content>\n</Message>"
     },
     {
       "name": "Streaming",
-      "description": "Message being streamed (with cursor)",
+      "description": "A blinking caret trails the text as it arrives.",
       "code": "<Message role=\"assistant\" status=\"streaming\">\n  <Message.Content>\n    I'm currently generating a response for you\n  </Message.Content>\n</Message>"
     },
     {
       "name": "With Timestamp",
-      "description": "Message with timestamp display",
+      "description": "A relative send time sits beneath the bubble.",
       "code": "<Message role=\"assistant\" timestamp={new Date(Date.now() - 300000)}>\n  <Message.Content>\n    This message was sent 5 minutes ago.\n  </Message.Content>\n  <Message.Timestamp />\n</Message>"
     },
     {
       "name": "Error State",
-      "description": "Message that failed to send",
+      "description": "A failed send turns the bubble and its border red.",
       "code": "<Message role=\"user\" status=\"error\">\n  <Message.Content>\n    This message failed to send.\n  </Message.Content>\n</Message>"
     },
     {
       "name": "Custom Avatars",
-      "description": "Messages with image-based avatars",
+      "description": "Photos replace the default glyphs on both sides.",
       "code": "<>\n  <Message\n    role=\"user\"\n    avatar={<Message.Avatar src=\"https://i.pravatar.cc/64?u=user\" alt=\"Jane\" />}\n  >\n    <Message.Content>\n      Can you help me understand this error?\n    </Message.Content>\n  </Message>\n  <Message\n    role=\"assistant\"\n    avatar={<Message.Avatar src=\"https://i.pravatar.cc/64?u=bot\" alt=\"AI Assistant\" />}\n  >\n    <Message.Content>\n      Sure! Let me take a look at that for you.\n    </Message.Content>\n  </Message>\n</>"
     },
     {
       "name": "With Actions",
-      "description": "Message with hover actions",
-      "code": "<Message\n  role=\"assistant\"\n  actions={\n    <>\n      <button style={{ padding: '4px 8px', fontSize: '12px' }}>Copy</button>\n      <button style={{ padding: '4px 8px', fontSize: '12px' }}>Regenerate</button>\n    </>\n  }\n>\n  <Message.Content>\n    Hover over this message to see the actions.\n  </Message.Content>\n</Message>"
+      "description": "Controls stay hidden until the pointer enters the row.",
+      "code": "<Message\n  role=\"assistant\"\n  actions={\n    <>\n      <Button variant=\"ghost\" size=\"xs\">\n        Copy\n      </Button>\n      <Button variant=\"ghost\" size=\"xs\">\n        Regenerate\n      </Button>\n    </>\n  }\n>\n  <Message.Content>\n    Hover over this message to see the actions.\n  </Message.Content>\n</Message>"
     }
   ],
   "relations": [
@@ -163,19 +148,11 @@
       "Avatar.src: string - image URL for avatar",
       "Avatar.alt: string - alt text for image avatar"
     ],
-    "a11yRules": [
-      "A11Y_COLOR_CONTRAST",
-      "A11Y_MOTION_PREFERENCE"
-    ]
+    "a11yRules": ["A11Y_COLOR_CONTRAST", "A11Y_MOTION_PREFERENCE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Content",
-      "Actions",
-      "Timestamp",
-      "Avatar"
-    ]
+    "subComponents": ["Content", "Actions", "Timestamp", "Avatar"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/Message/Message.module.scss

@@ -1,83 +1,58 @@
 @use "../../tokens/variables" as *;
-@use "../../tokens/mixins" as *;
-
-// ============================================
-// Message Root
-// ============================================
+@use "../../recipes/layout" as layout;
+@use "../../recipes/prose" as prose;
+@use "../../recipes/typography" as typography;
 
 .message {
   display: flex;
-  gap: var(--fui-space-2, $fui-space-2);
-  padding: var(--fui-space-2, $fui-space-2);
+  gap: layout.gap("md");
+  padding: layout.gap("md");
   border-radius: var(--fui-radius-lg, $fui-radius-lg);
   transition: background-color var(--fui-transition-fast, $fui-transition-fast);
 
-  &:hover {
-    .actions {
-      opacity: 1;
-    }
-  }
-
-  &:focus-within {
-    .actions {
-      opacity: 1;
-    }
+  &:hover .actions,
+  &:focus-within .actions {
+    opacity: 1;
   }
 }
 
 .withoutAvatar {
-  padding-inline: 0;
-
-  // Avatarless assistant prose is part of the transcript rather than a bubble,
-  // so it should sit flush with the shared measure. The user's own turn remains
-  // a compact bubble to preserve authorship and alignment at a glance.
-  &.assistant {
-    .content {
-      padding: 0;
-    }
-  }
-
-  &.user {
-    .content {
-      padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
-    }
+  &.assistant .content {
+    background: transparent;
   }
 }
 
-// Role-based styles
 .user {
   flex-direction: row-reverse;
-  margin-left: auto;
+  margin-inline-start: auto;
+
+  // Cap against the conversation width, not the bubble's own shrink-wrapped
+  // width. On .content the percentage resolves against an already-collapsed
+  // parent and squeezes short messages until they break mid-word.
+  max-inline-size: 80%;
 
   .body {
     align-items: flex-end;
   }
 
-  // Alignment, measure and the neutral surface distinguish the user's turn.
-  // Brand accent is reserved for actions and semantic state, not transcript
-  // chrome.
   .content {
-    max-inline-size: 80%;
     background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
     color: var(--fui-text-primary, $fui-text-primary);
   }
 }
 
-.assistant {
-  .content {
-    background-color: var(--fui-bg-secondary, $fui-bg-secondary);
-    color: var(--fui-text-primary, $fui-text-primary);
-  }
+.assistant .content {
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  color: var(--fui-text-primary, $fui-text-primary);
 }
 
 .system {
-  max-width: 100%;
+  max-inline-size: 100%;
   justify-content: center;
 
   .content {
     background-color: var(--fui-color-info-bg, $fui-color-info-bg);
     color: var(--fui-text-secondary, $fui-text-secondary);
-    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
     text-align: center;
   }
 
@@ -86,45 +61,22 @@
   }
 }
 
-// Status styles
-.error {
-  .content {
-    background: var(--fui-color-danger-bg, $fui-color-danger-bg);
-    border: 1px solid var(--fui-color-danger-border, $fui-color-danger-border);
-    color: var(--fui-color-danger-text, $fui-color-danger-text);
-  }
+.error .content {
+  border: var(--fui-stroke-hairline, 1px) solid
+    var(--fui-color-danger-border, $fui-color-danger-border);
+  background: var(--fui-color-danger-bg, $fui-color-danger-bg);
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
 }
 
 .sending {
   opacity: 0.7;
 }
 
-// ============================================
-// Avatar
-// ============================================
-
 .avatar {
   flex-shrink: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 2rem;
-  height: 2rem;
-  border-radius: var(--fui-radius-full, $fui-radius-full);
-  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
-  color: var(--fui-text-secondary, $fui-text-secondary);
-
-  svg {
-    width: 1rem;
-    height: 1rem;
-  }
-}
-
-.avatarUser {
-  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
-  color: var(--fui-text-primary, $fui-text-primary);
 }
 
+.avatarUser,
 .avatarAssistant {
   background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
   color: var(--fui-text-primary, $fui-text-primary);
@@ -137,91 +89,67 @@
 
 .avatarImage {
   padding: 0;
-  overflow: hidden;
-}
-
-.avatarImg {
-  width: 100%;
-  height: 100%;
-  object-fit: cover;
 }
 
-// ============================================
-// Body (content container)
-// ============================================
-
 .body {
   display: flex;
-  flex-direction: column;
-  gap: var(--fui-space-1, $fui-space-1);
-  min-width: 0;
   flex: 1;
+  flex-direction: column;
+  gap: layout.gap("xs");
+  min-inline-size: 0;
 }
 
-// ============================================
-// Content
-// ============================================
-
 .content {
-  @include text-base;
-  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
-  border-radius: var(--fui-radius-lg, $fui-radius-lg);
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
-  word-wrap: break-word;
+  @include prose.root;
 
-  // A bubble sets its own foreground per role — primary text for the user, the
-  // danger ramp for an error. Anything rendered inside it has to take that
-  // colour rather than the page's, so a Markdown body dropped in here inherits
-  // instead of holding on to the prose grey.
   --fui-markdown-text: currentColor;
 
-  // Prose styling for markdown content
-  p {
-    margin: 0;
+  padding-block: layout.gap("sm");
+  padding-inline: layout.gap("md");
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+  // break-word, not anywhere: `anywhere` drops min-content to a single
+  // character, collapsing every shrink-to-fit ancestor around the bubble.
+  overflow-wrap: break-word;
 
-    & + p {
-      margin-top: var(--fui-space-2, $fui-space-2);
-    }
+  p {
+    @include prose.paragraph;
   }
 
   code {
-    font-family: var(--fui-font-mono, $fui-font-mono);
-    font-size: 0.9em;
-    padding: 0.125em 0.375em;
-    border-radius: var(--fui-radius-sm, $fui-radius-sm);
-    background-color: var(--fui-bg-subtle, $fui-bg-subtle);
+    @include prose.inline-code;
   }
 
   pre {
-    margin: var(--fui-space-2, $fui-space-2) 0;
-    padding: var(--fui-space-2, $fui-space-2);
+    @include prose.code-block("compact");
+
     border-radius: var(--fui-radius-md, $fui-radius-md);
     background-color: var(--fui-bg-subtle, $fui-bg-subtle);
-    overflow-x: auto;
 
     code {
       padding: 0;
       background: none;
+      font: inherit;
+      letter-spacing: inherit;
     }
   }
 
-  ul,
+  ul {
+    @include prose.list("disc");
+  }
+
   ol {
-    margin: var(--fui-space-2, $fui-space-2) 0;
-    padding-left: var(--fui-space-4, $fui-space-4);
+    @include prose.list("decimal");
   }
 }
 
-.streaming {
-  &::after {
-    content: "";
-    display: inline-block;
-    width: 0.5em;
-    height: 1em;
-    margin-left: 2px;
-    background-color: currentColor;
-    animation: blink 1s step-end infinite;
-  }
+.streaming::after {
+  content: "";
+  display: inline-block;
+  inline-size: 0.5em;
+  block-size: 1em;
+  margin-inline-start: var(--fui-raw-space-2, 2px);
+  background-color: currentColor;
+  animation: blink var(--fui-duration-pulse, $fui-duration-pulse) step-end infinite;
 }
 
 @keyframes blink {
@@ -229,37 +157,26 @@
   100% {
     opacity: 1;
   }
+
   50% {
     opacity: 0;
   }
 }
 
-// ============================================
-// Actions
-// ============================================
-
 .actions {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-1, $fui-space-1);
+  gap: layout.gap("xs");
   opacity: 0;
   transition: opacity var(--fui-transition-fast, $fui-transition-fast);
 }
 
-// ============================================
-// Timestamp
-// ============================================
-
 .timestamp {
-  @include helper-text;
-  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+  @include typography.role("caption");
+
   color: var(--fui-text-secondary, $fui-text-secondary);
 }
 
-// ============================================
-// Reduced Motion
-// ============================================
-
 @media (prefers-reduced-motion: reduce) {
   .streaming::after {
     animation: none;

package/src/components/Message/index.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import styles from './Message.module.scss';
+import { Avatar } from '../Avatar';
 import { useOptionalConversationList } from '../ConversationList';
 import { Markdown } from '../Markdown';
 
@@ -215,14 +216,23 @@ function MessageAvatar({ children, src, alt, className, ...htmlProps }: MessageA
       ? <AssistantIcon />
       : <SystemIcon />;
 
-  const content = children ?? (src
-    ? <img src={src} alt={alt ?? role} className={styles.avatarImg} />
-    : defaultIcon);
+  if (children !== undefined) {
+    return (
+      <div {...htmlProps} className={classes}>
+        {children}
+      </div>
+    );
+  }
 
   return (
-    <div {...htmlProps} className={classes}>
-      {content}
-    </div>
+    <Avatar
+      {...htmlProps}
+      src={src}
+      alt={alt ?? role}
+      size="sm"
+      fallback={defaultIcon}
+      className={classes}
+    />
   );
 }