@auto-engineer/component-implementor-react 1.98.0 → 1.100.0

package/inputs/model-d/spec-deltas.json

@@ -0,0 +1,967 @@
+[
+  {
+    "componentId": "message-bubble",
+    "componentName": "MessageBubble",
+    "isNew": true,
+    "atomicType": "atom",
+    "composes": ["ui-components-avatar"],
+    "specDeltas": {
+      "structure": [
+        "Composes Avatar for sender image, with text content in a rounded bubble",
+        "Uses <article> semantic element for the message container",
+        "Sender name in <header> element",
+        "Message text in <p> element"
+      ],
+      "rendering": [
+        "Renders sender avatar if provided, otherwise a placeholder",
+        "Displays message text from data prop",
+        "Shows timestamp in muted text"
+      ],
+      "interaction": ["No interactive elements by default"],
+      "styling": [
+        "Message bubble container uses `flex items-start gap-3 p-3 rounded-lg bg-muted` for received messages, `flex items-start gap-3 p-3 rounded-lg bg-primary text-primary-foreground justify-end` for own messages with `flex-row-reverse`.",
+        "Sender avatar uses `h-8 w-8 rounded-full` from Avatar component, fallback to `bg-accent flex items-center justify-center text-accent-foreground font-medium text-sm` with tabular-nums if counts are displayed.",
+        "Sender name uses `text-sm font-semibold text-foreground`, timestamp uses `text-xs text-muted-foreground ml-auto` with `font-variant-numeric: tabular-nums` for consistent digit width.",
+        "Message text uses `text-sm text-foreground text-wrap balance` to prevent layout shifts in headings or short texts.",
+        "Hover effect on bubble wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-muted/80 }` with `transition: background-color 150ms ease`, respects `prefers-reduced-motion: reduce` by setting `transition: none`."
+      ]
+    },
+    "props": [
+      {
+        "name": "message",
+        "type": "{ id: string; sender: { name: string; avatar?: string }; text: string; timestamp: string }",
+        "required": true,
+        "description": "The message data to display.",
+        "category": "data"
+      },
+      {
+        "name": "isOwnMessage",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether this is the current user's message, affects alignment.",
+        "category": "state"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "A standard received message.",
+        "args": {
+          "message": {
+            "id": "1",
+            "sender": {
+              "name": "John Doe",
+              "avatar": "/avatar.jpg"
+            },
+            "text": "Hello!",
+            "timestamp": "2024-03-15T10:00:00Z"
+          },
+          "isOwnMessage": false
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "OwnMessage",
+        "description": "A message sent by the current user.",
+        "args": {
+          "message": {
+            "id": "2",
+            "sender": {
+              "name": "Me"
+            },
+            "text": "Hi there!",
+            "timestamp": "2024-03-15T10:01:00Z"
+          },
+          "isOwnMessage": true
+        },
+        "needsPlayFunction": false
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "message",
+      "fields": ["id", "sender.name", "sender.avatar", "text", "timestamp"]
+    }
+  },
+  {
+    "componentId": "multi-participant-selector",
+    "componentName": "MultiParticipantSelector",
+    "isNew": true,
+    "atomicType": "molecule",
+    "composes": ["ui-components-combobox", "ui-components-badge"],
+    "specDeltas": {
+      "structure": [
+        "Composes Combobox for searchable input, with selected participants as Badge list",
+        "Uses <section> for the selector container with role='group' and aria-label='Participant selection'",
+        "Selected badges in a horizontal flex wrap",
+        "Combobox for adding new participants"
+      ],
+      "rendering": [
+        "Renders list of selected participants as removable Badges",
+        "Combobox shows available participants not yet selected",
+        "In loading state (isLoading=true), shows Skeleton for input area",
+        "In error state (error non-null), shows Alert with error message and retry button"
+      ],
+      "interaction": [
+        "Selecting from Combobox adds to selected list and calls onChange with updated array",
+        "Clicking remove on a Badge removes it from selected and calls onChange",
+        "Calls onChange: (selected: Participant[]) => void on every selection change",
+        "On retry click in error state, calls onRetry: () => void"
+      ],
+      "styling": [
+        "Selector container uses `flex flex-col gap-4 p-4 border rounded-md bg-background`.",
+        "Selected badges list uses `flex flex-wrap gap-2`, each Badge with `variant=\"secondary\"` rendering as `bg-secondary text-secondary-foreground text-sm font-medium px-2.5 py-0.5 rounded` and remove X icon as `ml-1 h-4 w-4 inline-flex items-center justify-center rounded-full hover:bg-accent hover:text-accent-foreground transition: background-color 150ms ease` wrapped in `@media (hover: hover) and (pointer: fine)`, with min-h-11 min-w-11 for touch targets and touch-action: manipulation.",
+        "Combobox input uses `w-full h-10 px-3 py-2 rounded-md border border-input bg-background text-sm ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with `text-base` to prevent iOS zoom.",
+        "In loading state, skeleton uses `h-8 w-full bg-muted rounded-md` with CSS shimmer `background: linear-gradient(90deg, hsl(var(--muted)) 0%, hsl(var(--muted)/0.5) 50%, hsl(var(--muted)) 100%); background-size: 200% 100%; animation: shimmer 1.5s linear infinite` to match input dimensions for CLS prevention.",
+        "In error state, Alert uses `variant=\"destructive\"` rendering as `border border-destructive text-destructive p-4 rounded-md` with text-balance on title.",
+        "Badges use useTransition(selected, { from: { opacity: 0, transform: 'scale(0.95)' }, enter: { opacity: 1, transform: 'scale(1)' }, leave: { opacity: 0, transform: 'scale(0.95)' }, config: { tension: 400, friction: 22 } }) for enter/exit animations, respects useReducedMotion() by setting immediate: true when reduced.",
+        "Retry button in error uses `variant=\"default\"` with `bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-4 py-2 rounded-md` and CSS `active:scale-[0.97] transition: transform 100ms ease-out`, hover wrapped in `@media (hover: hover) and (pointer: fine)`.",
+        "Focus outlines use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` on all interactive elements, using neutral colors only."
+      ]
+    },
+    "props": [
+      {
+        "name": "participants",
+        "type": "Array<{ id: string; name: string; avatar?: string }>",
+        "required": true,
+        "description": "List of available participants.",
+        "category": "data"
+      },
+      {
+        "name": "selected",
+        "type": "Array<{ id: string; name: string; avatar?: string }>",
+        "required": true,
+        "description": "Currently selected participants.",
+        "category": "data"
+      },
+      {
+        "name": "onChange",
+        "type": "(selected: Array<{ id: string; name: string; avatar?: string }>) => void",
+        "required": true,
+        "description": "Callback when selection changes.",
+        "category": "callback"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether the selector is in loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message if failed to load participants.",
+        "category": "state"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback to retry loading participants.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Selector with some selected participants.",
+        "args": {
+          "participants": [
+            {
+              "id": "1",
+              "name": "Alice"
+            },
+            {
+              "id": "2",
+              "name": "Bob"
+            },
+            {
+              "id": "3",
+              "name": "Charlie"
+            }
+          ],
+          "selected": [
+            {
+              "id": "1",
+              "name": "Alice"
+            }
+          ],
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click the combobox input to open dropdown, 2. Type 'B' to filter, 3. Click 'Bob' option, 4. Verify new badge appears and onChange is called, 5. Click remove on Alice badge, 6. Verify badge removes and onChange called."
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state with skeleton.",
+        "args": {
+          "participants": [],
+          "selected": [],
+          "onChange": "fn()",
+          "isLoading": true
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state with retry button.",
+        "args": {
+          "participants": [],
+          "selected": [],
+          "onChange": "fn()",
+          "error": "Failed to load participants",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find the retry button with getByRole('button', { name: 'Retry' }), 2. userEvent.click(retryButton), 3. expect(onRetry).toHaveBeenCalled()."
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "participants",
+      "fields": ["id", "name", "avatar"]
+    }
+  },
+  {
+    "componentId": "message-composer",
+    "componentName": "MessageComposer",
+    "isNew": true,
+    "atomicType": "molecule",
+    "composes": ["ui-components-textarea", "ui-components-button"],
+    "specDeltas": {
+      "structure": [
+        "Composes Textarea for message input and Button for send",
+        "Uses <form> element to wrap input and button for native Enter-to-submit",
+        "Textarea with inputMode='text' and autocomplete='off'",
+        "Send button as Button with variant='default'"
+      ],
+      "rendering": [
+        "In ready state, shows enabled Textarea and Send button",
+        "In sending state (isSending=true), disables Textarea and Button, shows Spinner inside Button",
+        "In send-error state (error non-null), shows Alert with error message and retry Button, hides recent-messages region",
+        "In editing-invalid state (invalid=true), shows inline error text below Textarea: 'Message cannot be empty'"
+      ],
+      "interaction": [
+        "On Textarea change, calls onMessageChange: (text: string) => void",
+        "On form submit (Enter or Send click), validates text non-empty; if valid calls onSend: (text: string) => void, else transitions to editing-invalid",
+        "On retry click in send-error, calls onRetry: () => void, transitions back to sending",
+        "Supports Cmd+Enter submission for multi-line input",
+        "Submit button disables during isSending to prevent duplicates",
+        "Uses controlled value prop for text, clears value after successful send via parent"
+      ],
+      "styling": [
+        "Form container uses `flex items-center gap-2 p-4 border-t bg-background`.",
+        "Textarea uses `flex-1 min-h-[80px] px-3 py-2 rounded-md border border-input bg-background text-sm ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 text-base resize-none` to prevent iOS zoom and allow multi-line input.",
+        "Send button uses `variant=\"default\"` rendering as `bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-4 py-2 rounded-md` with CSS `active:scale-[0.97] transition: transform 100ms ease-out`, hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-primary/90 }` with `transition: background-color 150ms ease`, min-h-11 min-w-11 for touch targets, touch-action: manipulation.",
+        "In sending state, button adds `opacity-50 cursor-not-allowed` and replaces text with Spinner using `animate-spin h-5 w-5 text-primary-foreground`.",
+        "In error state, Alert uses `variant=\"destructive\"` rendering as `border border-destructive text-destructive p-4 rounded-md w-full mt-2` with retry button as `bg-destructive text-destructive-foreground hover:bg-destructive/90 h-10 px-4 py-2 rounded-md`.",
+        "Inline error text uses `text-sm text-destructive mt-1` with `text-wrap: balance`.",
+        "Retry button hover uses `transition: background-color 150ms ease` wrapped in `@media (hover: hover) and (pointer: fine)`, respects `prefers-reduced-motion: reduce` with `transition: none`.",
+        "Focus outlines on textarea and button use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with neutral colors."
+      ]
+    },
+    "props": [
+      {
+        "name": "value",
+        "type": "string",
+        "required": true,
+        "description": "Current message text (controlled).",
+        "category": "data"
+      },
+      {
+        "name": "onMessageChange",
+        "type": "(text: string) => void",
+        "required": true,
+        "description": "Callback on text change.",
+        "category": "callback"
+      },
+      {
+        "name": "onSend",
+        "type": "(text: string) => void",
+        "required": true,
+        "description": "Callback to send message.",
+        "category": "callback"
+      },
+      {
+        "name": "isSending",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether message is sending.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Send error message.",
+        "category": "state"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback to retry sending.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state with some text.",
+        "args": {
+          "value": "Hello",
+          "onMessageChange": "fn()",
+          "onSend": "fn()",
+          "isSending": false,
+          "error": null,
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find the textarea with getByRole('textbox'), 2. userEvent.type(textarea, ' world'), 3. expect(onMessageChange).toHaveBeenCalledWith('Hello world'), 4. Find submit button with getByRole('button', { name: 'Send' }), 5. userEvent.click(submitButton), 6. expect(onSend).toHaveBeenCalledWith('Hello world')."
+      },
+      {
+        "name": "Sending",
+        "description": "Sending state with disabled input.",
+        "args": {
+          "value": "Sending...",
+          "onMessageChange": "fn()",
+          "onSend": "fn()",
+          "isSending": true,
+          "error": null,
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state with retry.",
+        "args": {
+          "value": "",
+          "onMessageChange": "fn()",
+          "onSend": "fn()",
+          "isSending": false,
+          "error": "Failed to send",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find the retry button with getByRole('button', { name: 'Retry' }), 2. userEvent.click(retryButton), 3. expect(onRetry).toHaveBeenCalled()."
+      },
+      {
+        "name": "Invalid",
+        "description": "Invalid state with empty message.",
+        "args": {
+          "value": "",
+          "onMessageChange": "fn()",
+          "onSend": "fn()",
+          "isSending": false,
+          "error": null,
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find submit button with getByRole('button', { name: 'Send' }), 2. userEvent.click(submitButton), 3. await waitFor(() => expect(getByText('Message cannot be empty')).toBeVisible())."
+      }
+    ],
+    "dataContract": {
+      "source": "local-state",
+      "fields": ["messageText"]
+    }
+  },
+  {
+    "componentId": "message-list",
+    "componentName": "MessageList",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["message-bubble", "ui-components-scrollarea"],
+    "specDeltas": {
+      "structure": [
+        "Composes ScrollArea for scrollable container, with MessageBubble for each message",
+        "Uses <ul> semantic element for the list with role='log' and aria-live='polite'",
+        "Each MessageBubble as <li> with unique key"
+      ],
+      "rendering": [
+        "In loading state (isLoading=true), shows Skeleton placeholders for 3-5 message bubbles, hides message-composer region",
+        "In ready state, renders messages array as vertical list, scrolls to bottom on new messages",
+        "In error state (error non-null), shows Alert with error message and retry button, hides message-list region",
+        "When new messages received (real-time), appends to list and scrolls to bottom smoothly"
+      ],
+      "interaction": [
+        "On component mount or new messages, calls scrollToBottom using scrollIntoView({ behavior: 'smooth' }) on last message",
+        "On retry click in error state, calls onRetry: () => void, transitions to loading"
+      ],
+      "styling": [
+        "List container uses `flex flex-col gap-4 p-4 overflow-y-auto h-full` inside ScrollArea with custom scrollbar `w-2 bg-border rounded-full` and thumb `bg-primary rounded-full`.",
+        "Each message uses useTransition(messages, { from: { opacity: 0, transform: 'translateY(8px)' }, enter: { opacity: 1, transform: 'translateY(0)' }, leave: { opacity: 0, transform: 'translateY(8px)' }, config: { tension: 300, friction: 22 } }) for staggered entry with useTrail(messages.length, ...), respects useReducedMotion() by setting immediate: true.",
+        "In loading state, skeletons use `h-16 w-full bg-muted rounded-lg` with CSS shimmer `background: linear-gradient(90deg, hsl(var(--muted)) 0%, hsl(var(--muted)/0.5) 50%, hsl(var(--muted)) 100%); background-size: 200% 100%; animation: shimmer 1.5s linear infinite` repeated 5 times to match message dimensions for CLS prevention.",
+        "In error state, Alert uses `variant=\"destructive\"` rendering as `border border-destructive text-destructive p-4 rounded-md` centered with `m-4`.",
+        "Retry button uses `variant=\"default\"` with `bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-4 py-2 rounded-md` and CSS `active:scale-[0.97] transition: transform 100ms ease-out`, hover wrapped in `@media (hover: hover) and (pointer: fine)`.",
+        "Timestamp in messages uses `font-variant-numeric: tabular-nums` for consistent width, text-xs text-muted-foreground.",
+        "List uses `scroll-margin-top: 4rem` to account for sticky headers.",
+        "Error alert fades in using useTransition(error, { from: { opacity: 0, scale: 0.95 }, enter: { opacity: 1, scale: 1 }, config: { tension: 400, friction: 22 } }), same config for content, respects reduced motion with immediate: true.",
+        "Interactive elements like retry have min-h-11 min-w-11 for touch targets, touch-action: manipulation, hover behind `@media (hover: hover) and (pointer: fine)`.",
+        "Focus outlines use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with neutral colors."
+      ]
+    },
+    "props": [
+      {
+        "name": "messages",
+        "type": "Array<{ id: string; sender: { name: string; avatar?: string }; text: string; timestamp: string }>",
+        "required": true,
+        "description": "List of messages to display.",
+        "category": "data"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether messages are loading.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message if failed to load.",
+        "category": "state"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback to retry loading messages.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "List with sample messages.",
+        "args": {
+          "messages": [
+            {
+              "id": "1",
+              "sender": {
+                "name": "Alice"
+              },
+              "text": "Hi",
+              "timestamp": "2024-03-15T10:00:00Z"
+            },
+            {
+              "id": "2",
+              "sender": {
+                "name": "Bob"
+              },
+              "text": "Hello",
+              "timestamp": "2024-03-15T10:01:00Z"
+            }
+          ],
+          "isLoading": false,
+          "error": null,
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state with skeletons.",
+        "args": {
+          "messages": [],
+          "isLoading": true,
+          "error": null,
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state with retry.",
+        "args": {
+          "messages": [],
+          "isLoading": false,
+          "error": "Failed to load messages",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find the retry button with getByRole('button', { name: 'Retry' }), 2. userEvent.click(retryButton), 3. expect(onRetry).toHaveBeenCalled()."
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "messages",
+      "fields": ["id", "sender.name", "sender.avatar", "text", "timestamp"]
+    }
+  },
+  {
+    "componentId": "chat-form",
+    "componentName": "ChatForm",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-form", "ui-components-input", "multi-participant-selector", "ui-components-button"],
+    "specDeltas": {
+      "structure": [
+        "Composes Form with fields: Input for chat name, MultiParticipantSelector for participants, Button for submit and cancel",
+        "Uses <form> element with role='form' and aria-label='Create new chat'",
+        "Vertical stack layout with FormItems for name and participants"
+      ],
+      "rendering": [
+        "In loading state (isLoading=true), shows Skeleton for form fields and buttons, hides form region",
+        "In ready state, shows editable form fields and enabled buttons",
+        "In editing-invalid state, shows inline validation errors: for name 'Chat name is required', for participants 'At least one participant required'",
+        "In submitting state (isSubmitting=true), disables form fields and buttons, shows progress indicator in submit button",
+        "In error state (error non-null), shows Alert with error message and retry button, hides form region"
+      ],
+      "interaction": [
+        "On name change, calls onNameChange: (name: string) => void",
+        "On participants change, calls onParticipantsChange: (selected: Participant[]) => void",
+        "On submit click or Enter, validates name non-empty and participants >=1; if valid calls onSubmit: (data: { name: string; participants: Participant[] }) => void, transitions to submitting; else shows editing-invalid",
+        "On cancel click, checks for unsaved changes; if changes, shows confirmation AlertDialog: 'Unsaved changes will be lost. Continue?' with confirm calling onCancel: () => void",
+        "On retry in error, calls onRetry: () => void, transitions to loading",
+        "Validation on blur for name and on submit for all fields",
+        "Clear field-level errors when user starts editing that field"
+      ],
+      "styling": [
+        "Form container uses `flex flex-col gap-6 p-6 bg-background rounded-lg shadow-sm`.",
+        "Name input uses `h-10 w-full px-3 py-2 rounded-md border border-input bg-background text-sm ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 text-base` to prevent iOS zoom.",
+        "Participant selector uses `flex flex-col gap-2`, with badges `flex flex-wrap gap-2`.",
+        "Submit button uses `variant=\"default\"` rendering as `bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-4 py-2 rounded-md` with CSS `active:scale-[0.97] transition: transform 100ms ease-out`, min-h-11 min-w-11, touch-action: manipulation.",
+        "Cancel button uses `variant=\"ghost\"` rendering as `bg-transparent hover:bg-accent hover:text-accent-foreground h-10 px-4 py-2 rounded-md` with similar active and hover specs.",
+        "In submitting state, submit button adds `opacity-50 cursor-not-allowed` and shows Progress with useSpring({ width: '0%' to '100%', config: { tension: 120, friction: 14 } }), respects reduced motion with immediate: true.",
+        "Validation errors use `text-sm text-destructive mt-1` with `text-wrap: balance`.",
+        "In loading state, skeletons for input `h-10 w-full bg-muted rounded-md` and selector `h-32 w-full bg-muted rounded-md` with shimmer animation.",
+        "In error state, Alert uses `variant=\"destructive\"` with `border border-destructive text-destructive p-4 rounded-md`.",
+        "Buttons flex justify-end gap-4, hover effects wrapped in `@media (hover: hover) and (pointer: fine) { ... }` with `transition: background-color 150ms ease`.",
+        "Focus outlines on inputs and buttons use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with neutral colors."
+      ]
+    },
+    "props": [
+      {
+        "name": "name",
+        "type": "string",
+        "required": true,
+        "description": "Chat name value (controlled).",
+        "category": "data"
+      },
+      {
+        "name": "participants",
+        "type": "Array<{ id: string; name: string; avatar?: string }>",
+        "required": true,
+        "description": "Available participants.",
+        "category": "data"
+      },
+      {
+        "name": "selectedParticipants",
+        "type": "Array<{ id: string; name: string; avatar?: string }>",
+        "required": true,
+        "description": "Selected participants (controlled).",
+        "category": "data"
+      },
+      {
+        "name": "onNameChange",
+        "type": "(name: string) => void",
+        "required": true,
+        "description": "Callback on name change.",
+        "category": "callback"
+      },
+      {
+        "name": "onParticipantsChange",
+        "type": "(selected: Array<{ id: string; name: string; avatar?: string }>) => void",
+        "required": true,
+        "description": "Callback on participants change.",
+        "category": "callback"
+      },
+      {
+        "name": "onSubmit",
+        "type": "(data: { name: string; participants: Array<{ id: string; name: string; avatar?: string }> }) => void",
+        "required": true,
+        "description": "Callback to submit form.",
+        "category": "callback"
+      },
+      {
+        "name": "onCancel",
+        "type": "() => void",
+        "required": true,
+        "description": "Callback to cancel creation.",
+        "category": "callback"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Loading state.",
+        "category": "state"
+      },
+      {
+        "name": "isSubmitting",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Submitting state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Retry callback.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state with values.",
+        "args": {
+          "name": "New Chat",
+          "participants": [
+            {
+              "id": "1",
+              "name": "Alice"
+            },
+            {
+              "id": "2",
+              "name": "Bob"
+            }
+          ],
+          "selectedParticipants": [
+            {
+              "id": "1",
+              "name": "Alice"
+            }
+          ],
+          "onNameChange": "fn()",
+          "onParticipantsChange": "fn()",
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null,
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find name input with getByLabelText('Chat name'), 2. userEvent.type(nameInput, ' Group'), 3. expect(onNameChange).toHaveBeenCalledWith('New Chat Group'), 4. Find submit button with getByRole('button', { name: 'Create Chat' }), 5. userEvent.click(submitButton), 6. expect(onSubmit).toHaveBeenCalledWith({ name: 'New Chat Group', participants: [{id: '1', name: 'Alice'}] })."
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "name": "",
+          "participants": [],
+          "selectedParticipants": [],
+          "onNameChange": "fn()",
+          "onParticipantsChange": "fn()",
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "isLoading": true,
+          "isSubmitting": false,
+          "error": null,
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Submitting",
+        "description": "Submitting state.",
+        "args": {
+          "name": "New Chat",
+          "participants": [],
+          "selectedParticipants": [],
+          "onNameChange": "fn()",
+          "onParticipantsChange": "fn()",
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "isLoading": false,
+          "isSubmitting": true,
+          "error": null,
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "name": "",
+          "participants": [],
+          "selectedParticipants": [],
+          "onNameChange": "fn()",
+          "onParticipantsChange": "fn()",
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": "Failed to create chat",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find retry button with getByRole('button', { name: 'Retry' }), 2. userEvent.click(retryButton), 3. expect(onRetry).toHaveBeenCalled()."
+      },
+      {
+        "name": "Invalid",
+        "description": "Invalid state with errors.",
+        "args": {
+          "name": "",
+          "participants": [
+            {
+              "id": "1",
+              "name": "Alice"
+            }
+          ],
+          "selectedParticipants": [],
+          "onNameChange": "fn()",
+          "onParticipantsChange": "fn()",
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null,
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find submit button, 2. userEvent.click(submitButton), 3. await waitFor(() => expect(getByText('Chat name is required')).toBeVisible()), 4. expect(getByText('At least one participant required')).toBeVisible()."
+      }
+    ],
+    "dataContract": {
+      "source": "local-state",
+      "fields": ["chatName", "selectedParticipants.id", "selectedParticipants.name"]
+    }
+  },
+  {
+    "componentId": "create-chat-page",
+    "componentName": "CreateChatPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": ["chat-form"],
+    "specDeltas": {
+      "structure": [
+        "Page-level component with header region and form region using vertical stack layout",
+        "Header as <header> with title 'Create New Chat'",
+        "Form region occupies main content area composing ChatForm"
+      ],
+      "rendering": [
+        "In loading state, shows Skeleton in header (h-8 w-48) and form region (h-64 w-full), hides form region content",
+        "In ready state, shows header title and full ChatForm",
+        "In editing-invalid state, shows header and ChatForm with validation errors visible",
+        "In submitting state, shows header and ChatForm with submitting indicator, disables interactions",
+        "In error state, shows header and error Alert in form region with 'Failed to create chat' message and retry button, hides form fields and actions regions"
+      ],
+      "interaction": [
+        "On page load, fetches participant data via GraphQL query, transitions from loading to ready or error",
+        "On form submit from ChatForm, sends GraphQL mutation to create chat, transitions to submitting, then on success navigates to view-messages, on fail to error",
+        "On cancel from ChatForm, navigates to chat-list, with unsaved changes guard showing AlertDialog for confirmation",
+        "On retry in error state, re-fetches participants and transitions to loading"
+      ],
+      "styling": [
+        "Page container uses `max-w-md mx-auto p-6 flex flex-col gap-6 min-h-screen bg-background`.",
+        "Header uses `text-2xl font-semibold tracking-tight text-foreground text-wrap balance`.",
+        "Form region uses `flex-1` with ChatForm styling.",
+        "In loading state, header skeleton `h-8 w-48 bg-muted rounded-md`, form skeleton `h-64 w-full bg-muted rounded-md` with shimmer `background: linear-gradient(90deg, hsl(var(--muted)) 0%, hsl(var(--muted)/0.5) 50%, hsl(var(--muted)) 100%); background-size: 200% 100%; animation: shimmer 1.5s linear infinite`.",
+        "Page fade-in on load uses useSpring({ opacity: 0 to 1, config: { tension: 400, friction: 26 } }), respects useReducedMotion() with immediate: true.",
+        "In error state, Alert uses `variant=\"destructive\"` with `border border-destructive text-destructive p-4 rounded-md` and fade-in useTransition({ from: { opacity: 0, scale: 0.95 }, enter: { opacity: 1, scale: 1 }, config: { tension: 300, friction: 22 } }).",
+        "Retry button uses `variant=\"default\"` with `bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-4 py-2 rounded-md active:scale-[0.97] transition: transform 100ms ease-out`, hover in `@media (hover: hover) and (pointer: fine)`.",
+        "All interactive elements have min-h-11 min-w-11 for touch targets, touch-action: manipulation.",
+        "Focus outlines use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with neutral colors.",
+        "Z-index for error alert `z-[500]` from fixed scale for popover-like elevation.",
+        "Subtle separators between regions use `box-shadow: 0 0 0 1px rgba(0,0,0,0.08)` instead of border.",
+        "Dark mode adjusts shadows to lower opacity, borders to increased opacity for visibility."
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls loading state for stories.",
+        "category": "state"
+      },
+      {
+        "name": "isSubmitting",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls submitting state for stories.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Controls error state for stories.",
+        "category": "state"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find submit button with getByRole('button', { name: 'Create Chat' }), 2. userEvent.click(submitButton), 3. await waitFor(() => expect(getByText('Chat name is required')).toBeVisible())."
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "isLoading": true,
+          "isSubmitting": false,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Submitting",
+        "description": "Submitting state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": true,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": "Failed to create chat"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find retry button with getByRole('button', { name: 'Retry' }), 2. userEvent.click(retryButton), 3. await waitFor(() => expect(getByText('Loading...')).toBeVisible())."
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-mutation",
+      "operationName": "CreateChat",
+      "fields": ["name", "participants.id"]
+    }
+  },
+  {
+    "componentId": "chat-page",
+    "componentName": "ChatPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": ["message-list", "message-composer", "ui-components-card"],
+    "specDeltas": {
+      "structure": [
+        "Page-level component with chat-header region, message-list region, and message-composer region using vertical stack layout",
+        "Header as <header> with chat title and participants",
+        "MessageList in main <section> with role='log'",
+        "MessageComposer in <footer>"
+      ],
+      "rendering": [
+        "In loading state, shows Skeleton in chat-header (h-8 w-48) and message-list region (h-64 w-full), hides message-composer region",
+        "In ready state, shows full header, MessageList with messages, and MessageComposer",
+        "In error state, shows header and error Alert in message-list region with 'Failed to load messages' message and retry button, hides message-list and message-composer regions"
+      ],
+      "interaction": [
+        "On page load, fetches messages via GraphQL query using chatId param, transitions from loading to ready or error",
+        "On send from MessageComposer, sends GraphQL mutation, shows sending feedback, on success appends to messages and clears input, on fail shows send-error Alert with retry",
+        "On retry in error state, re-fetches messages and transitions to loading",
+        "Subscribes to real-time message updates via GraphQL subscription, appends new messages to list"
+      ],
+      "styling": [
+        "Page container uses `flex flex-col h-screen bg-background`.",
+        "Chat header uses `sticky top-0 z-[200] bg-background border-b p-4 flex items-center justify-between shadow-sm`.",
+        "Message list uses `flex-1` with MessageList styling.",
+        "Message composer uses `border-t p-4 bg-background`.",
+        "In loading state, header skeleton `h-8 w-48 bg-muted rounded-md`, list skeleton `h-full w-full bg-muted` with multiple message skeletons.",
+        "Page subtle fade-in uses useSpring({ opacity: 0 to 1, config: { tension: 400, friction: 26 } }), respects reduced motion.",
+        "In error state, Alert in list area `m-4 border border-destructive text-destructive p-4 rounded-md` with useTransition fade-in { tension: 300, friction: 22 }.",
+        "Retry button `variant=\"default\" bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-4 py-2 rounded-md active:scale-[0.97] transition: transform 100ms ease-out`, hover in media query.",
+        "Interactive elements min-h-11 min-w-11, touch-action: manipulation.",
+        "Focus outlines `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` neutral.",
+        "Z-index header 200 for sticky, error alert 500.",
+        "Separators use box-shadow ring for subtle effect.",
+        "Dark mode shadow reduction, border opacity increase.",
+        "Composer uses `env(safe-area-inset-bottom)` padding for mobile."
+      ]
+    },
+    "props": [
+      {
+        "name": "chatId",
+        "type": "string",
+        "required": true,
+        "description": "ID of the chat to display.",
+        "category": "config"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls loading state for stories.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Controls error state for stories.",
+        "category": "state"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state with messages.",
+        "args": {
+          "chatId": "123",
+          "isLoading": false,
+          "error": null
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find message input with getByRole('textbox'), 2. userEvent.type(input, 'Hello{enter}'), 3. await waitFor(() => expect(getByText('Sending...')).toBeVisible()), 4. await waitFor(() => expect(getByText('Hello')).toBeVisible())."
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "chatId": "123",
+          "isLoading": true,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "chatId": "123",
+          "isLoading": false,
+          "error": "Failed to load messages"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Find retry button with getByRole('button', { name: 'Retry' }), 2. userEvent.click(retryButton), 3. await waitFor(() => expect(getByText('Loading...')).toBeVisible())."
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-query",
+      "operationName": "GetChatMessages",
+      "fields": ["chatId", "messages.id", "messages.sender.name", "messages.text", "messages.timestamp"]
+    }
+  }
+]