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

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

@@ -0,0 +1,2292 @@
+[
+  {
+    "componentId": "photo-upload",
+    "componentName": "PhotoUpload",
+    "isNew": true,
+    "atomicType": "molecule",
+    "composes": ["ui-components-input", "ui-components-button", "ui-components-aspectratio"],
+    "specDeltas": {
+      "structure": [
+        "Composes Input (type='file' for image upload) and Button for upload trigger",
+        "Uses AspectRatio to display uploaded photo preview in a constrained ratio (e.g., 1:1 for square posts)",
+        "Wrapper div with semantic section role='group' aria-label='Photo upload'",
+        "Button as trigger with text 'Upload Photo' and icon (upload cloud)",
+        "After upload, replaces button with image preview using img element inside AspectRatio",
+        "Hidden file input associated with button via htmlFor/id pairing"
+      ],
+      "rendering": [
+        "In initial state (no photo), renders upload Button",
+        "When photo is uploaded (previewUrl prop is set), renders img with src=previewUrl inside AspectRatio, alt='Uploaded post photo'",
+        "If isUploading=true, renders Spinner overlay on the preview area",
+        "If error prop is truthy, renders Alert below the preview with error message",
+        "Uses role='img' on preview container with aria-label='Post photo preview'"
+      ],
+      "interaction": [
+        "Clicking upload Button triggers file selection dialog via hidden Input click",
+        "On file selection, calls onUpload: (file: File) => void with the selected file",
+        "Supports drag-and-drop: on drop, calls onUpload with dropped file if it's an image",
+        "Calls onChange: (previewUrl: string) => void when preview is generated",
+        "On error during upload, sets internal error state and shows Alert"
+      ],
+      "styling": [
+        "Upload button uses `variant=\"default\"` which renders as `bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-4 py-2 rounded-md font-medium`, with additional `w-full flex items-center justify-center gap-2` and icon `h-4 w-4`",
+        "Preview container uses `relative` with AspectRatio `aspect-square` (ratio=1), img uses `object-cover w-full h-full rounded-md`",
+        "Uploading overlay uses `absolute inset-0 flex items-center justify-center bg-background/80` with Spinner `animate-spin h-8 w-8 text-primary`",
+        "Error alert uses `variant=\"destructive\"` which renders as `border-destructive/50 text-destructive dark:border-destructive p-4 rounded-md mt-2`, with AlertTitle `font-semibold` and AlertDescription `text-sm`",
+        "Button hover effect wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-primary/90 }`, with CSS `transition: background-color 150ms ease`",
+        "Button active state uses CSS `active:scale-[0.97]` with `transition: transform 100ms ease-out`",
+        "Preview enter animation uses `useTransition(previewUrl, { from: { opacity: 0, scale: 0.95 }, enter: { opacity: 1, scale: 1 }, config: { tension: 300, friction: 22 } })`, respects `useReducedMotion()` with `immediate: true` when reduced",
+        "Touch targets for button use `min-h-11 min-w-11 touch-action: manipulation`",
+        "Focus visible on button uses `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`",
+        "Skeleton for preview uses `h-64 w-full bg-muted animate-pulse rounded-md` to match content dimensions",
+        "Dark mode adjusts overlay to `bg-background/80` with Spinner `text-primary`"
+      ]
+    },
+    "props": [
+      {
+        "name": "previewUrl",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "URL of the uploaded photo preview.",
+        "category": "data"
+      },
+      {
+        "name": "isUploading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether the upload is in progress.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message to display.",
+        "category": "state"
+      },
+      {
+        "name": "onUpload",
+        "type": "(file: File) => void",
+        "required": true,
+        "description": "Callback when a file is selected or dropped.",
+        "category": "callback"
+      },
+      {
+        "name": "onChange",
+        "type": "(previewUrl: string) => void",
+        "required": false,
+        "description": "Callback when preview URL changes.",
+        "category": "callback"
+      },
+      {
+        "name": "accept",
+        "type": "string",
+        "required": false,
+        "default": "'image/*'",
+        "description": "Accepted file types for input.",
+        "category": "config"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Initial state with upload button.",
+        "args": {
+          "previewUrl": null,
+          "isUploading": false,
+          "error": null,
+          "onUpload": "fn()",
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "WithPreview",
+        "description": "State with uploaded photo preview.",
+        "args": {
+          "previewUrl": "https://example.com/photo.jpg",
+          "isUploading": false,
+          "error": null,
+          "onUpload": "fn()",
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Uploading",
+        "description": "Uploading state with spinner.",
+        "args": {
+          "previewUrl": null,
+          "isUploading": true,
+          "error": null,
+          "onUpload": "fn()",
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state with alert.",
+        "args": {
+          "previewUrl": null,
+          "isUploading": false,
+          "error": "Upload failed. Please try again.",
+          "onUpload": "fn()",
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Interactive",
+        "description": "For testing file upload interaction.",
+        "args": {
+          "previewUrl": null,
+          "isUploading": false,
+          "error": null,
+          "onUpload": "fn()",
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click the upload button using userEvent.click(getByRole('button', { name: 'Upload Photo' })), 2. Simulate file selection (cannot fully simulate in Storybook, but assert onUpload called), 3. Wait for preview to appear using await waitFor(() => expect(getByRole('img', { name: 'Post photo preview' })).toBeVisible())"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "previewUrl",
+      "fields": ["previewUrl"]
+    }
+  },
+  {
+    "componentId": "caption-input",
+    "componentName": "CaptionInput",
+    "isNew": true,
+    "atomicType": "molecule",
+    "composes": ["ui-components-textarea", "ui-components-label"],
+    "specDeltas": {
+      "structure": [
+        "Composes Textarea for caption input and Label for 'Caption' label",
+        "Wrapper section with role='group' aria-label='Post caption input'",
+        "Label associated with Textarea via htmlFor/id",
+        "Textarea with placeholder 'Write a caption...'"
+      ],
+      "rendering": [
+        "In valid state, renders Textarea without error",
+        "In invalid state (error prop truthy), renders error message below Textarea with aria-describedby linking to error id",
+        "Sets aria-invalid='true' on Textarea when error is present",
+        "Renders character count below Textarea showing length / maxLength"
+      ],
+      "interaction": [
+        "On Textarea change, calls onChange: (value: string) => void",
+        "Validates on blur: if value is empty and required, sets internal error 'Caption is required'",
+        "Clears error when user starts typing if error was present"
+      ],
+      "styling": [
+        "Wrapper uses `flex flex-col gap-1`",
+        "Label uses `text-sm font-medium leading-none peer-disabled:opacity-70`",
+        "Textarea uses `min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50`",
+        "Error message uses `text-sm text-destructive mt-1`",
+        "Character count uses `text-sm text-muted-foreground self-end mt-1` with `font-variant-numeric: tabular-nums`",
+        "Focus visible on textarea uses `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`",
+        "Hover effect on textarea wrapped in `@media (hover: hover) and (pointer: fine) { hover:border-input/80 }` with CSS `transition: border-color 150ms ease`",
+        "Invalid state on textarea adds `border-destructive focus-visible:ring-destructive`",
+        "Touch targets for textarea use `touch-action: manipulation`, with `text-base` to prevent iOS zoom",
+        "Skeleton for textarea uses `h-20 w-full bg-muted animate-pulse rounded-md`",
+        "Dark mode uses `bg-background text-foreground border-input` for textarea"
+      ]
+    },
+    "props": [
+      {
+        "name": "value",
+        "type": "string",
+        "required": false,
+        "default": "''",
+        "description": "Current caption text.",
+        "category": "data"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message to display.",
+        "category": "state"
+      },
+      {
+        "name": "onChange",
+        "type": "(value: string) => void",
+        "required": true,
+        "description": "Callback on caption change.",
+        "category": "callback"
+      },
+      {
+        "name": "maxLength",
+        "type": "number",
+        "required": false,
+        "default": "280",
+        "description": "Maximum caption length.",
+        "category": "config"
+      },
+      {
+        "name": "required",
+        "type": "boolean",
+        "required": false,
+        "default": "true",
+        "description": "Whether caption is required.",
+        "category": "config"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Empty caption input.",
+        "args": {
+          "value": "",
+          "error": null,
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Filled",
+        "description": "With caption text.",
+        "args": {
+          "value": "This is a sample caption.",
+          "error": null,
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "With validation error.",
+        "args": {
+          "value": "",
+          "error": "Caption is required",
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Interactive",
+        "description": "For testing input and validation.",
+        "args": {
+          "value": "",
+          "error": null,
+          "onChange": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Type 'Test' into textarea using userEvent.type(getByLabelText('Caption'), 'Test'), 2. Blur the textarea using userEvent.tab(), 3. Assert no error visible since not empty, 4. Clear text using userEvent.clear(getByLabelText('Caption')), 5. Blur again, 6. Await waitFor(() => expect(getByText('Caption is required')).toBeVisible())"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "value",
+      "fields": ["value"]
+    }
+  },
+  {
+    "componentId": "post-preview",
+    "componentName": "PostPreview",
+    "isNew": true,
+    "atomicType": "molecule",
+    "composes": ["ui-components-card", "ui-components-aspectratio"],
+    "specDeltas": {
+      "structure": [
+        "Composes Card to wrap preview content",
+        "Uses AspectRatio for photo display",
+        "Includes CardContent with caption text",
+        "Semantic article role with aria-label='Post preview'"
+      ],
+      "rendering": [
+        "If photoUrl prop is set, renders img with src=photoUrl inside AspectRatio, alt='Post photo'",
+        "Renders caption prop as paragraph text below photo",
+        "If no photoUrl, renders placeholder Skeleton in AspectRatio",
+        "If no caption, renders empty paragraph or nothing"
+      ],
+      "interaction": ["No interactive callbacks, display-only"],
+      "styling": [
+        "Card wrapper uses `rounded-lg border bg-card text-card-foreground shadow-sm`",
+        "AspectRatio for photo uses `aspect-square` with img `object-cover w-full h-full rounded-t-lg`",
+        "Caption paragraph uses `p-4 text-sm text-foreground` with `text-wrap: balance`",
+        "Skeleton for photo uses `h-64 w-full bg-muted animate-pulse rounded-t-lg` to match content",
+        "Skeleton for caption uses `h-4 w-3/4 bg-muted animate-pulse mx-4 mb-4`",
+        "Enter animation for content uses `useTransition(true, { from: { opacity: 0 }, enter: { opacity: 1 }, config: { tension: 400, friction: 26 } })`, respects `useReducedMotion()` with `immediate: true`",
+        "No interactive elements, but decorative img has `pointer-events: none`",
+        "Dark mode uses `bg-card text-card-foreground border-border`",
+        "Subtle separator between photo and caption uses `box-shadow: 0 0 0 1px rgba(0,0,0,0.08)` instead of border",
+        "Heading (if any) uses `text-balance` for short text"
+      ]
+    },
+    "props": [
+      {
+        "name": "photoUrl",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "URL of the post photo.",
+        "category": "data"
+      },
+      {
+        "name": "caption",
+        "type": "string",
+        "required": false,
+        "default": "''",
+        "description": "Post caption text.",
+        "category": "data"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Empty preview with skeletons.",
+        "args": {
+          "photoUrl": null,
+          "caption": ""
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "WithContent",
+        "description": "Preview with photo and caption.",
+        "args": {
+          "photoUrl": "https://example.com/photo.jpg",
+          "caption": "Sample caption"
+        },
+        "needsPlayFunction": false
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "photoUrl",
+      "fields": ["photoUrl", "caption"]
+    }
+  },
+  {
+    "componentId": "like-button",
+    "componentName": "LikeButton",
+    "isNew": true,
+    "atomicType": "molecule",
+    "composes": ["ui-components-toggle"],
+    "specDeltas": {
+      "structure": [
+        "Composes Toggle with heart icon",
+        "Includes span for like count",
+        "Wrapper button with role='button' aria-label='Like post'"
+      ],
+      "rendering": [
+        "When liked (pressed=true), renders filled heart icon",
+        "When not liked (pressed=false), renders outline heart icon",
+        "Renders likeCount prop as text next to icon",
+        "If isLoading=true, disables toggle and shows Spinner"
+      ],
+      "interaction": [
+        "Clicking toggles pressed state and calls onToggle: (liked: boolean) => void",
+        "Optimistically updates likeCount before callback resolves",
+        "On error, rolls back likeCount and shows toast error"
+      ],
+      "styling": [
+        "Toggle button uses `variant=\"ghost\"` which renders as `bg-transparent hover:bg-accent hover:text-accent-foreground h-10 px-4 py-2`, with `flex items-center gap-1`",
+        "Heart icon uses `h-5 w-5` with conditional `fill-current text-red-500` when pressed, else `text-muted-foreground`",
+        "Like count uses `text-sm font-medium` with `font-variant-numeric: tabular-nums`",
+        "Loading spinner uses `animate-spin h-5 w-5 text-muted-foreground` replacing icon when isLoading",
+        "Hover effect wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent }` with CSS `transition: background-color 150ms ease`",
+        "Active state uses CSS `active:scale-[0.97]` with `transition: transform 100ms ease-out`",
+        "Focus visible uses `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`",
+        "Disabled state adds `opacity-50 cursor-not-allowed`",
+        "Toggle animation uses `useSpring({ scale: pressed ? 1.1 : 1, config: { tension: 400, friction: 22 } })` for icon, respects `useReducedMotion()` with `immediate: true`",
+        "Touch targets use `min-h-11 min-w-11 touch-action: manipulation`",
+        "Dark mode uses `hover:bg-accent hover:text-accent-foreground`"
+      ]
+    },
+    "props": [
+      {
+        "name": "pressed",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether the post is liked.",
+        "category": "state"
+      },
+      {
+        "name": "likeCount",
+        "type": "number",
+        "required": false,
+        "default": "0",
+        "description": "Number of likes.",
+        "category": "data"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether like action is in progress.",
+        "category": "state"
+      },
+      {
+        "name": "onToggle",
+        "type": "(liked: boolean) => void",
+        "required": true,
+        "description": "Callback on like toggle.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Unliked state.",
+        "args": {
+          "pressed": false,
+          "likeCount": 0,
+          "isLoading": false,
+          "onToggle": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Liked",
+        "description": "Liked state with count.",
+        "args": {
+          "pressed": true,
+          "likeCount": 5,
+          "isLoading": false,
+          "onToggle": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "pressed": false,
+          "likeCount": 0,
+          "isLoading": true,
+          "onToggle": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Interactive",
+        "description": "For testing toggle.",
+        "args": {
+          "pressed": false,
+          "likeCount": 0,
+          "isLoading": false,
+          "onToggle": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click the button using userEvent.click(getByRole('button', { name: 'Like post' })), 2. Await waitFor(() => expect(getByRole('button')).toHaveAttribute('aria-pressed', 'true')), 3. Assert like count increased to 1"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "likeCount",
+      "fields": ["likeCount"]
+    }
+  },
+  {
+    "componentId": "comment-input",
+    "componentName": "CommentInput",
+    "isNew": true,
+    "atomicType": "molecule",
+    "composes": ["ui-components-textarea", "ui-components-button"],
+    "specDeltas": {
+      "structure": [
+        "Composes Textarea for comment text and Button for submit",
+        "Wrapper div with role='group' aria-label='Add comment'",
+        "Button with text 'Post' positioned after Textarea"
+      ],
+      "rendering": [
+        "Renders Textarea with placeholder 'Add a comment...'",
+        "If error prop truthy, renders error text below Textarea with aria-describedby",
+        "Disables Button when value is empty or isSubmitting=true",
+        "Sets aria-invalid on Textarea when error present"
+      ],
+      "interaction": [
+        "On Textarea change, calls onChange: (value: string) => void",
+        "Clicking Button calls onSubmit: (comment: string) => void if value not empty",
+        "On submit, sets isSubmitting=true, clears value on success",
+        "Validates on submit: if empty, shows 'Comment cannot be empty' error"
+      ],
+      "styling": [
+        "Wrapper uses `flex items-end gap-2`",
+        "Textarea uses `flex-1 min-h-[40px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50`",
+        "Submit button uses `variant=\"default\" size=\"sm\"` which renders as `bg-primary text-primary-foreground hover:bg-primary/90 h-9 px-3 rounded-md`",
+        "Error message uses `text-sm text-destructive mt-1 w-full`",
+        "Focus visible on textarea and button uses `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`",
+        "Hover on button wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-primary/90 }` with CSS `transition: background-color 150ms ease`",
+        "Disabled button adds `opacity-50 cursor-not-allowed`",
+        "Submitting state on button replaces text with Spinner `animate-spin h-4 w-4`",
+        "Touch targets for button use `min-h-11 min-w-11 touch-action: manipulation`, textarea `text-base`",
+        "Skeleton for textarea uses `h-10 w-full bg-muted animate-pulse rounded-md`, for button `h-9 w-20 bg-muted animate-pulse rounded-md`",
+        "Dark mode uses `bg-background text-foreground border-input` for textarea"
+      ]
+    },
+    "props": [
+      {
+        "name": "value",
+        "type": "string",
+        "required": false,
+        "default": "''",
+        "description": "Current comment text.",
+        "category": "data"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      },
+      {
+        "name": "isSubmitting",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether comment is submitting.",
+        "category": "state"
+      },
+      {
+        "name": "onChange",
+        "type": "(value: string) => void",
+        "required": true,
+        "description": "Callback on text change.",
+        "category": "callback"
+      },
+      {
+        "name": "onSubmit",
+        "type": "(comment: string) => void",
+        "required": true,
+        "description": "Callback on submit.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Empty comment input.",
+        "args": {
+          "value": "",
+          "error": null,
+          "isSubmitting": false,
+          "onChange": "fn()",
+          "onSubmit": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Filled",
+        "description": "With comment text.",
+        "args": {
+          "value": "Great post!",
+          "error": null,
+          "isSubmitting": false,
+          "onChange": "fn()",
+          "onSubmit": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Submitting",
+        "description": "Submitting state.",
+        "args": {
+          "value": "Great post!",
+          "error": null,
+          "isSubmitting": true,
+          "onChange": "fn()",
+          "onSubmit": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "With error.",
+        "args": {
+          "value": "",
+          "error": "Comment cannot be empty",
+          "isSubmitting": false,
+          "onChange": "fn()",
+          "onSubmit": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Interactive",
+        "description": "For testing submit.",
+        "args": {
+          "value": "",
+          "error": null,
+          "isSubmitting": false,
+          "onChange": "fn()",
+          "onSubmit": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Type 'Test comment' into textarea using userEvent.type(getByPlaceholderText('Add a comment...'), 'Test comment'), 2. Click submit button using userEvent.click(getByRole('button', { name: 'Post' })), 3. Await waitFor(() => expect(getByRole('button')).toBeDisabled()), 4. Assert onSubmit called with 'Test comment'"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "value",
+      "fields": ["value"]
+    }
+  },
+  {
+    "componentId": "comments-list",
+    "componentName": "CommentsList",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-avatar", "ui-components-separator"],
+    "specDeltas": {
+      "structure": [
+        "Uses ul with role='list' for comments",
+        "Each comment as li composing Avatar for user, p for text, time for timestamp",
+        "Separator between comments"
+      ],
+      "rendering": [
+        "Renders comments prop as list items",
+        "Each item shows user avatar, name, comment text, timestamp",
+        "If isLoading=true, renders Skeleton for 3 placeholder comments",
+        "If error prop truthy, renders Alert with error message",
+        "If comments.length === 0, renders empty message 'No comments yet'"
+      ],
+      "interaction": [
+        "No direct interactions, but supports onReply: (commentId: string) => void for reply buttons if provided"
+      ],
+      "styling": [
+        "List wrapper uses `flex flex-col gap-4` with role='list'",
+        "Each comment li uses `flex gap-3` with Separator `h-px bg-border my-4` between items",
+        "Avatar uses `h-8 w-8 rounded-full`",
+        "User name uses `text-sm font-semibold`",
+        "Comment text uses `text-sm text-foreground` with `text-wrap: balance`",
+        "Timestamp uses `text-xs text-muted-foreground` with `font-variant-numeric: tabular-nums`",
+        "Skeleton comment uses `flex gap-3` with avatar `h-8 w-8 bg-muted animate-pulse rounded-full`, text lines `h-4 w-32 bg-muted animate-pulse`, `h-4 w-48 bg-muted animate-pulse`",
+        "Empty message uses `text-center text-sm text-muted-foreground py-4`",
+        "Error alert uses `variant=\"destructive\" p-4 rounded-md`",
+        "List enter animation uses `useTrail(comments.length, { opacity: 1, transform: 'translateY(0)', from: { opacity: 0, transform: 'translateY(8px)' }, config: { tension: 300, friction: 22 } })` for staggered items, respects `useReducedMotion()`",
+        "Dark mode uses `bg-card text-card-foreground` for comments"
+      ]
+    },
+    "props": [
+      {
+        "name": "comments",
+        "type": "Array<{ id: string; user: { name: string; avatar: string }; text: string; timestamp: string }>",
+        "required": true,
+        "description": "List of comments.",
+        "category": "data"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether comments are loading.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      },
+      {
+        "name": "onReply",
+        "type": "(commentId: string) => void",
+        "required": false,
+        "description": "Callback for replying to a comment.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "List with comments.",
+        "args": {
+          "comments": [
+            {
+              "id": "1",
+              "user": {
+                "name": "User1",
+                "avatar": "https://example.com/avatar1.jpg"
+              },
+              "text": "Nice post!",
+              "timestamp": "2024-03-15T12:00:00Z"
+            },
+            {
+              "id": "2",
+              "user": {
+                "name": "User2",
+                "avatar": "https://example.com/avatar2.jpg"
+              },
+              "text": "Agreed!",
+              "timestamp": "2024-03-15T12:05:00Z"
+            }
+          ],
+          "isLoading": false,
+          "error": null,
+          "onReply": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state with skeletons.",
+        "args": {
+          "comments": [],
+          "isLoading": true,
+          "error": null,
+          "onReply": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "comments": [],
+          "isLoading": false,
+          "error": "Failed to load comments",
+          "onReply": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Empty",
+        "description": "Empty list.",
+        "args": {
+          "comments": [],
+          "isLoading": false,
+          "error": null,
+          "onReply": "fn()"
+        },
+        "needsPlayFunction": false
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "comments",
+      "fields": ["comments.id", "comments.user.name", "comments.user.avatar", "comments.text", "comments.timestamp"]
+    }
+  },
+  {
+    "componentId": "post-card",
+    "componentName": "PostCard",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-card", "ui-components-aspectratio", "ui-components-avatar", "ui-components-button"],
+    "specDeltas": {
+      "structure": [
+        "Composes Card with header (user Avatar and name), media (img in AspectRatio), footer (caption, like count, comment count)",
+        "Button for view details or navigate"
+      ],
+      "rendering": [
+        "Renders user avatar and name in CardHeader",
+        "Renders post photo in AspectRatio with alt='Post photo'",
+        "Renders caption in CardContent",
+        "Renders like and comment icons with counts in CardFooter",
+        "If isLoading=true, renders Skeleton for media and text"
+      ],
+      "interaction": ["Clicking the card calls onClick: (postId: string) => void to navigate to detail"],
+      "styling": [
+        "Card wrapper uses `rounded-lg border bg-card text-card-foreground shadow-sm hover:shadow-md` with CSS `transition: box-shadow 150ms ease`",
+        "Header uses `flex items-center gap-2 p-4` with Avatar `h-8 w-8`, name `text-sm font-semibold`",
+        "Media uses AspectRatio `aspect-video` with img `object-cover w-full h-full rounded-md`",
+        "Caption uses `p-4 text-sm text-foreground` with `text-wrap: balance`",
+        "Footer uses `flex justify-between p-4 text-sm text-muted-foreground` with icons `h-4 w-4` and counts `font-variant-numeric: tabular-nums`",
+        "Hover effect wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent/10 }` with CSS `transition: background-color 150ms ease`",
+        "Focus visible uses `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`",
+        "Skeleton for media uses `h-48 w-full bg-muted animate-pulse rounded-md`",
+        "Skeleton for caption uses `h-4 w-3/4 bg-muted animate-pulse mx-4`",
+        "Enter animation uses `useTransition(true, { from: { opacity: 0, transform: 'translateY(8px)' }, enter: { opacity: 1, transform: 'translateY(0)' }, config: { tension: 300, friction: 22 } })`, respects `useReducedMotion()`",
+        "Touch targets for card use `touch-action: manipulation`",
+        "Dark mode uses `bg-card text-card-foreground border-border`"
+      ]
+    },
+    "props": [
+      {
+        "name": "post",
+        "type": "{ id: string; user: { name: string; avatar: string }; photoUrl: string; caption: string; likeCount: number; commentCount: number }",
+        "required": true,
+        "description": "Post data.",
+        "category": "data"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether post is loading.",
+        "category": "state"
+      },
+      {
+        "name": "onClick",
+        "type": "(postId: string) => void",
+        "required": false,
+        "description": "Callback on card click.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Post card with data.",
+        "args": {
+          "post": {
+            "id": "1",
+            "user": {
+              "name": "User1",
+              "avatar": "https://example.com/avatar.jpg"
+            },
+            "photoUrl": "https://example.com/photo.jpg",
+            "caption": "Sample post",
+            "likeCount": 10,
+            "commentCount": 2
+          },
+          "isLoading": false,
+          "onClick": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click the card using userEvent.click(getByRole('article')), 2. Assert onClick called with post id '1'"
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "post": {
+            "id": "",
+            "user": {
+              "name": "",
+              "avatar": ""
+            },
+            "photoUrl": "",
+            "caption": "",
+            "likeCount": 0,
+            "commentCount": 0
+          },
+          "isLoading": true,
+          "onClick": "fn()"
+        },
+        "needsPlayFunction": false
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "post",
+      "fields": [
+        "post.id",
+        "post.user.name",
+        "post.user.avatar",
+        "post.photoUrl",
+        "post.caption",
+        "post.likeCount",
+        "post.commentCount"
+      ]
+    }
+  },
+  {
+    "componentId": "posts-list",
+    "componentName": "PostsList",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["post-card", "ui-components-scrollarea"],
+    "specDeltas": {
+      "structure": [
+        "Uses ScrollArea for infinite scroll list",
+        "Renders array of PostCard for each post",
+        "Includes load more trigger at bottom"
+      ],
+      "rendering": [
+        "In ready state, renders posts prop as PostCard list",
+        "In loading state, renders Skeleton PostCard placeholders (e.g., 5 items)",
+        "In error state, renders Alert with retry Button",
+        "In empty state, renders empty message with create Button",
+        "If hasMore=true, renders load more Button or auto-triggers on scroll"
+      ],
+      "interaction": [
+        "On scroll to bottom, calls onLoadMore: () => void if hasMore",
+        "Clicking retry in error state calls onRetry: () => void",
+        "Pull-to-refresh gesture calls onRefresh: () => void"
+      ],
+      "styling": [
+        "ScrollArea uses `h-full w-full` with vertical scrollbar `w-2` thumb `bg-border rounded-full`",
+        "List uses `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 p-4`",
+        "Load more button uses `variant=\"ghost\" w-full py-4 text-center text-muted-foreground hover:bg-accent`",
+        "Error alert uses `variant=\"destructive\" p-4 rounded-md m-4` with retry button `variant=\"default\" mt-2`",
+        "Empty message uses `text-center text-muted-foreground py-8` with create button `variant=\"primary\" mt-4`",
+        "Skeleton list uses 5 items each `h-64 w-full bg-muted animate-pulse rounded-lg` with `grid` layout",
+        "Infinite scroll trigger uses `h-px w-full` at bottom",
+        "Pull-to-refresh indicator uses `absolute top-0 left-0 right-0 flex justify-center py-2` with Spinner `animate-spin h-6 w-6` when pulling",
+        "Item enter animation uses `useTrail(posts.length, { opacity: 1, transform: 'translateY(0)', from: { opacity: 0, transform: 'translateY(20px)' }, config: { tension: 170, friction: 26 } })` for gentle stagger, respects `useReducedMotion()`",
+        "Hover on load more wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent }` with CSS `transition: background-color 150ms ease`",
+        "Touch targets for buttons use `min-h-11 touch-action: manipulation`",
+        "Dark mode uses `bg-background` for list"
+      ]
+    },
+    "props": [
+      {
+        "name": "posts",
+        "type": "Array<{ id: string; user: { name: string; avatar: string }; photoUrl: string; caption: string; likeCount: number; commentCount: number }>",
+        "required": true,
+        "description": "List of posts.",
+        "category": "data"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      },
+      {
+        "name": "hasMore",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Whether more posts available.",
+        "category": "state"
+      },
+      {
+        "name": "onLoadMore",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback to load more.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback to retry load.",
+        "category": "callback"
+      },
+      {
+        "name": "onRefresh",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback on pull-to-refresh.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "List with posts.",
+        "args": {
+          "posts": [
+            {
+              "id": "1",
+              "user": {
+                "name": "User1",
+                "avatar": "avatar1"
+              },
+              "photoUrl": "photo1",
+              "caption": "Cap1",
+              "likeCount": 10,
+              "commentCount": 2
+            }
+          ],
+          "isLoading": false,
+          "error": null,
+          "hasMore": false,
+          "onLoadMore": "fn()",
+          "onRetry": "fn()",
+          "onRefresh": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "posts": [],
+          "isLoading": true,
+          "error": null,
+          "hasMore": false,
+          "onLoadMore": "fn()",
+          "onRetry": "fn()",
+          "onRefresh": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "posts": [],
+          "isLoading": false,
+          "error": "Failed to load posts",
+          "hasMore": false,
+          "onLoadMore": "fn()",
+          "onRetry": "fn()",
+          "onRefresh": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click retry button using userEvent.click(getByRole('button', { name: 'Retry' })), 2. Assert onRetry called"
+      },
+      {
+        "name": "Empty",
+        "description": "Empty state.",
+        "args": {
+          "posts": [],
+          "isLoading": false,
+          "error": null,
+          "hasMore": false,
+          "onLoadMore": "fn()",
+          "onRetry": "fn()",
+          "onRefresh": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "WithMore",
+        "description": "With more posts available.",
+        "args": {
+          "posts": [
+            {
+              "id": "1",
+              "user": {
+                "name": "User1",
+                "avatar": "avatar1"
+              },
+              "photoUrl": "photo1",
+              "caption": "Cap1",
+              "likeCount": 10,
+              "commentCount": 2
+            }
+          ],
+          "isLoading": false,
+          "error": null,
+          "hasMore": true,
+          "onLoadMore": "fn()",
+          "onRetry": "fn()",
+          "onRefresh": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Scroll to bottom using userEvent.keyboard('{ArrowDown}'), 2. Await waitFor(() => expect(onLoadMore).toHaveBeenCalled())"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "posts",
+      "fields": [
+        "posts[].id",
+        "posts[].user.name",
+        "posts[].user.avatar",
+        "posts[].photoUrl",
+        "posts[].caption",
+        "posts[].likeCount",
+        "posts[].commentCount"
+      ]
+    }
+  },
+  {
+    "componentId": "feed-stream",
+    "componentName": "FeedStream",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["post-card", "ui-components-scrollarea"],
+    "specDeltas": {
+      "structure": ["Similar to PostsList but for feed, with infinite scroll", "Renders PostCard for each feed item"],
+      "rendering": [
+        "In ready state, renders feedItems as PostCard list",
+        "In loading state, renders Skeleton placeholders",
+        "In error state, renders Alert with retry",
+        "In empty state, renders 'Follow users to see posts' message",
+        "Supports pull-to-refresh indicator"
+      ],
+      "interaction": [
+        "Pull-to-refresh gesture calls onRefresh: () => void",
+        "Infinite scroll calls onLoadMore: () => void"
+      ],
+      "styling": [
+        "ScrollArea uses `h-full w-full overflow-y-auto` with scrollbar `w-2 thumb:bg-border`",
+        "Stream uses `flex flex-col gap-6 p-4 max-w-2xl mx-auto` for centered feed",
+        "Load more trigger uses `h-px w-full`",
+        "Error banner uses `variant=\"destructive\" p-4 m-4 rounded-md` with retry `variant=\"default\"`",
+        "Empty message uses `text-center py-12 text-lg text-muted-foreground` with icon `h-16 w-16 mb-4`",
+        "Skeleton stream uses 10 items each `h-96 w-full bg-muted animate-pulse rounded-lg`",
+        "Pull-to-refresh uses `absolute top-0 inset-x-0 flex justify-center py-4 bg-background` with progress bar `h-1 bg-primary` animating width via `useSpring({ width: `${pullProgress}%`, config: { tension: 120, friction: 14 } })`",
+        "Item animation uses `useTransition(feedItems, { from: { opacity: 0, transform: 'translateY(20px)' }, enter: { opacity: 1, transform: 'translateY(0)' }, leave: { opacity: 0, transform: 'translateY(-20px)' }, config: { tension: 300, friction: 22 } })`, respects `useReducedMotion()`",
+        "Refreshing spinner uses `animate-spin h-8 w-8 text-primary` in pull area",
+        "Touch targets use `touch-action: manipulation` for refresh gesture",
+        "Dark mode adjusts skeletons to `bg-muted`"
+      ]
+    },
+    "props": [
+      {
+        "name": "feedItems",
+        "type": "Array<{ id: string; user: { name: string; avatar: string }; photoUrl: string; caption: string; likeCount: number; commentCount: number }>",
+        "required": true,
+        "description": "Feed items.",
+        "category": "data"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      },
+      {
+        "name": "hasMore",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "More items available.",
+        "category": "state"
+      },
+      {
+        "name": "onLoadMore",
+        "type": "() => void",
+        "required": false,
+        "description": "Load more callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onRefresh",
+        "type": "() => void",
+        "required": false,
+        "description": "Refresh callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Retry callback.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Feed with items.",
+        "args": {
+          "feedItems": [
+            {
+              "id": "1",
+              "user": {
+                "name": "User1",
+                "avatar": "avatar1"
+              },
+              "photoUrl": "photo1",
+              "caption": "Cap1",
+              "likeCount": 10,
+              "commentCount": 2
+            }
+          ],
+          "isLoading": false,
+          "error": null,
+          "hasMore": false,
+          "onLoadMore": "fn()",
+          "onRefresh": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "feedItems": [],
+          "isLoading": true,
+          "error": null,
+          "hasMore": false,
+          "onLoadMore": "fn()",
+          "onRefresh": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "feedItems": [],
+          "isLoading": false,
+          "error": "Failed to load feed",
+          "hasMore": false,
+          "onLoadMore": "fn()",
+          "onRefresh": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click retry using userEvent.click(getByRole('button', { name: 'Retry' })), 2. Assert onRetry called"
+      },
+      {
+        "name": "Empty",
+        "description": "Empty feed.",
+        "args": {
+          "feedItems": [],
+          "isLoading": false,
+          "error": null,
+          "hasMore": false,
+          "onLoadMore": "fn()",
+          "onRefresh": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "feedItems",
+      "fields": [
+        "feedItems[].id",
+        "feedItems[].user.name",
+        "feedItems[].user.avatar",
+        "feedItems[].photoUrl",
+        "feedItems[].caption",
+        "feedItems[].likeCount",
+        "feedItems[].commentCount"
+      ]
+    }
+  },
+  {
+    "componentId": "follow-suggestions",
+    "componentName": "FollowSuggestions",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-avatar", "ui-components-button", "ui-components-carousel"],
+    "specDeltas": {
+      "structure": ["Uses Carousel for suggested users", "Each slide as Card with Avatar, name, Follow Button"],
+      "rendering": [
+        "Renders users prop as carousel items",
+        "If isLoading=true, renders Skeleton cards",
+        "If error, renders Alert"
+      ],
+      "interaction": [
+        "Clicking Follow Button calls onFollow: (userId: string) => void",
+        "Button disables during follow action"
+      ],
+      "styling": [
+        "Carousel uses `w-full` with content `flex gap-4 overflow-x-auto pb-4`",
+        "Each card uses `min-w-[200px] rounded-lg border bg-card p-4 flex flex-col items-center gap-2 shadow-sm`",
+        "Avatar uses `h-16 w-16 rounded-full`",
+        "Name uses `text-sm font-semibold`",
+        "Follow button uses `variant=\"default\" size=\"sm\" mt-2` rendering `bg-primary text-primary-foreground h-9 px-4 rounded-md`",
+        "Skeleton card uses `h-48 w-48 bg-muted animate-pulse rounded-lg`",
+        "Error alert uses `variant=\"destructive\" p-4 rounded-md`",
+        "Carousel navigation buttons use `variant=\"outline\" size=\"icon\" absolute top-1/2` with chevron icons `h-4 w-4`",
+        "Slide animation uses `useTransition(true, { from: { transform: 'translateX(100%)' }, enter: { transform: 'translateX(0%)' }, config: { tension: 280, friction: 24 } })` for smooth enter, respects `useReducedMotion()`",
+        "Hover on card wrapped in `@media (hover: hover) and (pointer: fine) { hover:shadow-md }` with CSS `transition: box-shadow 150ms ease`",
+        "Touch targets for buttons use `min-h-11 min-w-11 touch-action: manipulation`",
+        "Dark mode uses `bg-card text-card-foreground border-border` for cards"
+      ]
+    },
+    "props": [
+      {
+        "name": "users",
+        "type": "Array<{ id: string; name: string; avatar: string }>",
+        "required": true,
+        "description": "Suggested users.",
+        "category": "data"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      },
+      {
+        "name": "onFollow",
+        "type": "(userId: string) => void",
+        "required": true,
+        "description": "Callback to follow user.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "With suggestions.",
+        "args": {
+          "users": [
+            {
+              "id": "1",
+              "name": "User1",
+              "avatar": "avatar1"
+            },
+            {
+              "id": "2",
+              "name": "User2",
+              "avatar": "avatar2"
+            }
+          ],
+          "isLoading": false,
+          "error": null,
+          "onFollow": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click follow button for first user using userEvent.click(getByRole('button', { name: /Follow User1/ })), 2. Assert onFollow called with '1'"
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "users": [],
+          "isLoading": true,
+          "error": null,
+          "onFollow": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "users": [],
+          "isLoading": false,
+          "error": "Failed to load suggestions",
+          "onFollow": "fn()"
+        },
+        "needsPlayFunction": false
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "users",
+      "fields": ["users[].id", "users[].name", "users[].avatar"]
+    }
+  },
+  {
+    "componentId": "post-form",
+    "componentName": "PostForm",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["photo-upload", "caption-input", "ui-components-button", "ui-components-alertdialog"],
+    "specDeltas": {
+      "structure": [
+        "Vertical stack with PhotoUpload, CaptionInput, submit Button",
+        "Uses AlertDialog for unsaved changes confirmation"
+      ],
+      "rendering": [
+        "In editing state, renders form fields and submit Button",
+        "In submitting state, disables fields and Button, shows progress spinner",
+        "In error state, shows Alert with error message and retry Button",
+        "In invalid state, shows inline errors from child components"
+      ],
+      "interaction": [
+        "On submit Button click, validates form, calls onSubmit: (data: { photo: File; caption: string }) => void if valid",
+        "On cancel, if form dirty, shows confirmation AlertDialog; on confirm calls onCancel: () => void",
+        "Handles photo upload via PhotoUpload's onUpload",
+        "Validates caption not empty before submit"
+      ],
+      "styling": [
+        "Form wrapper uses `flex flex-col gap-6 p-6 bg-background rounded-lg shadow-sm`",
+        "Submit button uses `variant=\"default\"` rendering `bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-4 py-2 rounded-md`",
+        "Cancel button uses `variant=\"ghost\"` rendering `bg-transparent hover:bg-accent hover:text-accent-foreground h-10 px-4 py-2`",
+        "Progress spinner during submitting uses `animate-spin h-6 w-6 text-primary mx-auto`",
+        "Error alert uses `variant=\"destructive\" p-4 rounded-md mb-4` with retry button `variant=\"outline\" mt-2`",
+        "Confirmation dialog uses modal `useTransition(isOpen, { overlay: { opacity: 0 to 1 }, content: { opacity: 0 to 1, scale: 0.95 to 1 }, config: { tension: 300, friction: 22 } })`, overlay and content share config, respects `useReducedMotion()` with `immediate: true`",
+        "Dialog content uses `bg-background p-6 rounded-lg shadow-xl max-w-md` with z-[400]",
+        "Dialog title uses `text-lg font-semibold`, description `text-sm text-muted-foreground`",
+        "Dialog buttons use `variant=\"destructive\" for discard, variant=\"ghost\" for cancel`",
+        "Hover on buttons wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-primary/90 }` with CSS `transition: background-color 150ms ease`",
+        "Touch targets use `min-h-11 touch-action: manipulation` for buttons",
+        "Skeleton for form uses PhotoUpload skeleton `h-64`, CaptionInput `h-20`, button `h-10 w-32 bg-muted animate-pulse`",
+        "Dark mode uses `bg-background text-foreground`"
+      ]
+    },
+    "props": [
+      {
+        "name": "isSubmitting",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Submitting state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Submission error.",
+        "category": "state"
+      },
+      {
+        "name": "onSubmit",
+        "type": "(data: { photo: File; caption: string }) => void",
+        "required": true,
+        "description": "Submit callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onCancel",
+        "type": "() => void",
+        "required": true,
+        "description": "Cancel callback.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Editing form.",
+        "args": {
+          "isSubmitting": false,
+          "error": null,
+          "onSubmit": "fn()",
+          "onCancel": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Submitting",
+        "description": "Submitting state.",
+        "args": {
+          "isSubmitting": true,
+          "error": null,
+          "onSubmit": "fn()",
+          "onCancel": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "isSubmitting": false,
+          "error": "Failed to create post",
+          "onSubmit": "fn()",
+          "onCancel": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Interactive",
+        "description": "For testing submit.",
+        "args": {
+          "isSubmitting": false,
+          "error": null,
+          "onSubmit": "fn()",
+          "onCancel": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Simulate photo upload and caption input, 2. Click submit using userEvent.click(getByRole('button', { name: 'Post' })), 3. Assert onSubmit called with data"
+      }
+    ],
+    "dataContract": {
+      "source": "local-state",
+      "fields": ["photo", "caption"]
+    }
+  },
+  {
+    "componentId": "post-detail-media",
+    "componentName": "PostDetailMedia",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-aspectratio"],
+    "specDeltas": {
+      "structure": ["Uses AspectRatio for full-size media display", "img element with loading='lazy'"],
+      "rendering": [
+        "Renders img with src=photoUrl, alt='Post media'",
+        "If isLoading=true, renders Skeleton in AspectRatio",
+        "If error, renders Alert"
+      ],
+      "interaction": ["No interactions"],
+      "styling": [
+        "AspectRatio uses `aspect-[4/3]` with img `object-cover w-full h-full rounded-lg`",
+        "Skeleton uses `h-[500px] w-full bg-muted animate-pulse rounded-lg` to reserve space",
+        "Error alert uses `variant=\"destructive\" p-4 rounded-md h-[500px] flex items-center justify-center`",
+        "Enter animation for img uses `useSpring({ opacity: 1, from: { opacity: 0 }, config: { tension: 400, friction: 26 } })`, respects `useReducedMotion()`",
+        "Img has `pointer-events: none` as decorative",
+        "Focus visible not applicable, but container uses `focus-visible:ring-2 ring-ring ring-offset-2` if interactive",
+        "Dark mode no change needed",
+        "Use `aspect-ratio: 4/3` on container to prevent shift",
+        "Subtle shadow uses `box-shadow: 0 0 0 1px rgba(0,0,0,0.08)`",
+        "Hover no effect, but if added wrap in media query",
+        "Touch ready not applicable"
+      ]
+    },
+    "props": [
+      {
+        "name": "photoUrl",
+        "type": "string",
+        "required": true,
+        "description": "Media URL.",
+        "category": "data"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "With media.",
+        "args": {
+          "photoUrl": "https://example.com/photo.jpg",
+          "isLoading": false,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "photoUrl": "",
+          "isLoading": true,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "photoUrl": "",
+          "isLoading": false,
+          "error": "Failed to load media"
+        },
+        "needsPlayFunction": false
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "photoUrl",
+      "fields": ["photoUrl"]
+    }
+  },
+  {
+    "componentId": "post-actions",
+    "componentName": "PostActions",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["like-button", "ui-components-button"],
+    "specDeltas": {
+      "structure": ["Horizontal group with LikeButton, comment Button, share Button"],
+      "rendering": [
+        "Renders LikeButton with current like state and count",
+        "Renders comment Button with comment count",
+        "Renders share Button"
+      ],
+      "interaction": [
+        "LikeButton handles toggle",
+        "Comment Button calls onComment: () => void to focus input",
+        "Share Button calls onShare: (postId: string) => void"
+      ],
+      "styling": [
+        "Wrapper uses `flex justify-around border-t border-border py-4 bg-background`",
+        "Each action uses `flex flex-col items-center gap-1 text-muted-foreground`",
+        "Icons use `h-6 w-6`",
+        "Counts use `text-xs font-medium` with `font-variant-numeric: tabular-nums`",
+        "Like button when pressed uses `text-red-500` for icon",
+        "Hover on actions wrapped in `@media (hover: hover) and (pointer: fine) { hover:text-foreground }` with CSS `transition: color 150ms ease`",
+        "Active state for buttons uses CSS `active:scale-[0.97]` with `transition: transform 100ms ease-out`",
+        "Focus visible uses `focus-visible:ring-2 ring-ring ring-offset-2 rounded-full p-2`",
+        "Touch targets use `min-h-11 min-w-11 touch-action: manipulation` for each action",
+        "Dark mode uses `bg-background text-muted-foreground border-border`",
+        "Separator uses `box-shadow: 0 0 0 1px rgba(0,0,0,0.08)`"
+      ]
+    },
+    "props": [
+      {
+        "name": "postId",
+        "type": "string",
+        "required": true,
+        "description": "Post ID.",
+        "category": "data"
+      },
+      {
+        "name": "liked",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Liked state.",
+        "category": "state"
+      },
+      {
+        "name": "likeCount",
+        "type": "number",
+        "required": false,
+        "default": "0",
+        "description": "Like count.",
+        "category": "data"
+      },
+      {
+        "name": "commentCount",
+        "type": "number",
+        "required": false,
+        "default": "0",
+        "description": "Comment count.",
+        "category": "data"
+      },
+      {
+        "name": "onToggleLike",
+        "type": "(liked: boolean) => void",
+        "required": true,
+        "description": "Toggle like callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onComment",
+        "type": "() => void",
+        "required": true,
+        "description": "Comment callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onShare",
+        "type": "(postId: string) => void",
+        "required": true,
+        "description": "Share callback.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Actions bar.",
+        "args": {
+          "postId": "1",
+          "liked": false,
+          "likeCount": 0,
+          "commentCount": 0,
+          "onToggleLike": "fn()",
+          "onComment": "fn()",
+          "onShare": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click like button, assert onToggleLike called; 2. Click comment, assert onComment called; 3. Click share, assert onShare called with '1'"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "postId",
+      "fields": ["postId", "liked", "likeCount", "commentCount"]
+    }
+  },
+  {
+    "componentId": "create-post-page",
+    "componentName": "CreatePostPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": ["post-form", "post-preview", "ui-components-button"],
+    "specDeltas": {
+      "structure": [
+        "Two-region layout: form-area (left/main) with PostForm, preview-area (right/secondary) with PostPreview",
+        "Header region with Cancel Button and title 'Create Post'"
+      ],
+      "rendering": [
+        "In editing state, shows form-area and preview-area, hides nothing",
+        "In editing-invalid state, shows form-area and preview-area with inline validation errors from PostForm",
+        "In submitting state, shows form-area disabled with progress indicator in form-area, hides preview-area",
+        "In ready state, hides form-area and preview-area, shows success toast 'Post created successfully'",
+        "In error state, shows form-area and preview-area, shows error banner in form-area with 'Failed to create post. Please try again.' and retry Button",
+        "In loading state, shows header, hides form-area and preview-area, shows skeleton in form-area (PhotoUpload skeleton, CaptionInput skeleton, Button skeleton) and preview-area (PostPreview skeleton)"
+      ],
+      "interaction": [
+        "Calls onSubmit: (data: { photo: File; caption: string }) => void from PostForm submit, transitions to submitting state",
+        "Clicking Cancel Button, if form dirty shows confirmation AlertDialog 'Discard changes?', on confirm navigates to view-posts calling onCancel: () => void, transitions to ready if success",
+        "On retry in error state, calls onRetry: () => void, transitions to submitting",
+        "Escape key triggers cancel action with confirmation if dirty"
+      ],
+      "styling": [
+        "Page layout uses `grid grid-cols-1 md:grid-cols-2 gap-8 p-8 max-w-7xl mx-auto` for form-area and preview-area",
+        "Header uses `col-span-full flex items-center justify-between mb-6` with title `text-2xl font-bold tracking-tight text-wrap: balance`",
+        "Form-area uses `flex flex-col gap-6`",
+        "Preview-area uses `sticky top-8` with z-[200]",
+        "Submitting overlay uses `absolute inset-0 bg-background/80 flex items-center justify-center` with progress `useSpring({ width: '0%' to '100%', config: { tension: 120, friction: 14 } })` for bar `h-1 bg-primary`",
+        "Error banner uses `variant=\"destructive\" p-4 rounded-md mb-6`",
+        "Skeleton layout matches grid with form skeletons `h-64 bg-muted animate-pulse` etc.",
+        "Confirmation modal uses `z-[400]` with overlay `bg-black/80` and content `bg-background p-6 rounded-lg` animation `useTransition(isOpen, { overlay: { opacity: 0 to 1 }, content: { opacity: 0 to 1, transform: 'scale(0.95)' to 'scale(1)' }, config: { tension: 300, friction: 22 } })`, same config for paired elements, respects `useReducedMotion()`",
+        "Hover on cancel button wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent }`",
+        "Touch targets for buttons use `min-h-11`",
+        "Dark mode uses `bg-background text-foreground`",
+        "Use `text-balance` for title"
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Page 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": "onSubmit",
+        "type": "(data: { photo: File; caption: string }) => void",
+        "required": true,
+        "description": "Submit callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onCancel",
+        "type": "() => void",
+        "required": true,
+        "description": "Cancel callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Retry callback.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Editing state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null,
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "isLoading": true,
+          "isSubmitting": false,
+          "error": null,
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Submitting",
+        "description": "Submitting state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": true,
+          "error": null,
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": "Failed to create post",
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click retry button using userEvent.click(getByRole('button', { name: 'Retry' })), 2. Assert onRetry called"
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-mutation",
+      "operationName": "CreatePost",
+      "fields": ["photo", "caption"]
+    }
+  },
+  {
+    "componentId": "view-posts-page",
+    "componentName": "ViewPostsPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": ["posts-list", "ui-components-button"],
+    "specDeltas": {
+      "structure": [
+        "Main region with PostsList, floating create Button in create-fab region, header with title 'My Posts'"
+      ],
+      "rendering": [
+        "In loading state, shows header, hides posts-list and create-fab, shows skeleton in posts-list region (5 PostCard skeletons)",
+        "In ready state, shows header, posts-list, create-fab",
+        "In error state, shows header, hides posts-list and create-fab, shows error banner in posts-list region with 'Failed to load posts' and retry Button",
+        "In empty state, shows header, create-fab, shows empty message 'No posts yet. Create your first post!' in posts-list region"
+      ],
+      "interaction": [
+        "Clicking create Button navigates to create-post, calls onCreate: () => void",
+        "Clicking refresh Button in ready state transitions to loading, calls onRefresh: () => void",
+        "On retry in error state calls onRetry: () => void, transitions to loading"
+      ],
+      "styling": [
+        "Page uses `flex flex-col h-full`",
+        "Header uses `flex items-center justify-between p-6 border-b bg-background` with title `text-2xl font-bold tracking-tight` and refresh button `variant=\"ghost\" size=\"icon\"`",
+        "Posts-list region uses `flex-1 overflow-auto`",
+        "Create fab uses `fixed bottom-6 right-6 z-[500]` with button `variant=\"default\" size=\"lg\" rounded-full shadow-lg` animation `useSpring({ scale: 1, config: { tension: 400, friction: 22 } })` on hover",
+        "Error banner uses `p-6 text-center` with retry `variant=\"default\" mt-4`",
+        "Empty message uses `flex flex-col items-center justify-center h-full text-muted-foreground` with icon `h-16 w-16 mb-4`, text `text-lg`",
+        "Skeleton uses full height with grid skeletons",
+        "Hover on refresh wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent }`",
+        "Touch targets for fab use `h-14 w-14 min-h-11 touch-action: manipulation`",
+        "Fab press animation uses CSS `active:scale-[0.97] transition: transform 100ms ease-out`",
+        "Dark mode uses `bg-background border-border`",
+        "Z-index for fab 500, header 200"
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      },
+      {
+        "name": "isEmpty",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Empty state.",
+        "category": "state"
+      },
+      {
+        "name": "onCreate",
+        "type": "() => void",
+        "required": true,
+        "description": "Create post callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onRefresh",
+        "type": "() => void",
+        "required": true,
+        "description": "Refresh callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Retry callback.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state.",
+        "args": {
+          "isLoading": false,
+          "error": null,
+          "isEmpty": false,
+          "onCreate": "fn()",
+          "onRefresh": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "isLoading": true,
+          "error": null,
+          "isEmpty": false,
+          "onCreate": "fn()",
+          "onRefresh": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "isLoading": false,
+          "error": "Failed to load posts",
+          "isEmpty": false,
+          "onCreate": "fn()",
+          "onRefresh": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click retry using userEvent.click(getByRole('button', { name: 'Retry' })), 2. Assert onRetry called"
+      },
+      {
+        "name": "Empty",
+        "description": "Empty state.",
+        "args": {
+          "isLoading": false,
+          "error": null,
+          "isEmpty": true,
+          "onCreate": "fn()",
+          "onRefresh": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-query",
+      "operationName": "GetMyPosts",
+      "fields": ["posts[].id", "posts[].photoUrl", "posts[].caption", "posts[].likeCount", "posts[].commentCount"]
+    }
+  },
+  {
+    "componentId": "post-detail-page",
+    "componentName": "PostDetailPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": ["post-detail-media", "post-actions", "comments-list", "comment-input"],
+    "specDeltas": {
+      "structure": [
+        "Vertical layout: header, post-media, post-actions, comments-section with CommentsList and CommentInput"
+      ],
+      "rendering": [
+        "In loading state, shows header, hides other regions, shows skeleton in post-media (AspectRatio skeleton), post-actions (Button skeletons), comments-section (3 comment skeletons + input skeleton)",
+        "In ready state, shows all regions",
+        "In error state, shows header, hides other regions, shows error banner in main region with 'Failed to load post' and retry Button"
+      ],
+      "interaction": [
+        "Toggle like via PostActions, calls onToggleLike: (postId: string, liked: boolean) => void, shows success toast 'Like status updated'",
+        "Add comment via CommentInput, calls onAddComment: (postId: string, comment: string) => void, shows success toast 'Comment added' on success, inline warning if empty"
+      ],
+      "styling": [
+        "Page uses `flex flex-col max-w-3xl mx-auto`",
+        "Header uses `flex items-center gap-4 p-4 border-b` with back button `variant=\"ghost\" size=\"icon\"`, metadata `text-sm text-muted-foreground`",
+        "Post-media uses `bg-black` for full-width",
+        "Post-actions uses `border-b py-2`",
+        "Comments-section uses `flex-1 overflow-auto p-4`",
+        "Loading skeleton uses media `h-[500px] bg-muted animate-pulse`, actions `h-12 bg-muted`, comments 3 `h-16 bg-muted` + input `h-10`",
+        "Error banner uses `p-8 text-center` with retry `variant=\"default\"`",
+        "Comment enter uses `useTransition(comments, { from: { opacity: 0, transform: 'translateY(8px)' }, enter: { opacity: 1, transform: 'translateY(0)' }, config: { tension: 300, friction: 22 } })`",
+        "Hover on back button wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent }`",
+        "Touch targets for buttons use `min-h-11`",
+        "Dark mode uses `bg-background`",
+        "Z-index for header 200"
+      ]
+    },
+    "props": [
+      {
+        "name": "postId",
+        "type": "string",
+        "required": true,
+        "description": "Post ID from route param.",
+        "category": "data"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      },
+      {
+        "name": "onToggleLike",
+        "type": "(postId: string, liked: boolean) => void",
+        "required": true,
+        "description": "Toggle like callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onAddComment",
+        "type": "(postId: string, comment: string) => void",
+        "required": true,
+        "description": "Add comment callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Retry load callback.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state.",
+        "args": {
+          "postId": "1",
+          "isLoading": false,
+          "error": null,
+          "onToggleLike": "fn()",
+          "onAddComment": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "postId": "1",
+          "isLoading": true,
+          "error": null,
+          "onToggleLike": "fn()",
+          "onAddComment": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "postId": "1",
+          "isLoading": false,
+          "error": "Failed to load post",
+          "onToggleLike": "fn()",
+          "onAddComment": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click retry using userEvent.click(getByRole('button', { name: 'Retry' })), 2. Assert onRetry called"
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-query",
+      "operationName": "GetPostDetail",
+      "fields": [
+        "post.id",
+        "post.photoUrl",
+        "post.caption",
+        "post.likes",
+        "post.comments[].id",
+        "post.comments[].user.name",
+        "post.comments[].user.avatar",
+        "post.comments[].text",
+        "post.comments[].timestamp"
+      ]
+    }
+  },
+  {
+    "componentId": "feed-page",
+    "componentName": "FeedPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": ["feed-stream", "follow-suggestions"],
+    "specDeltas": {
+      "structure": [
+        "Main feed-stream with FeedStream, secondary follow-suggestions with FollowSuggestions, header with title 'Feed'"
+      ],
+      "rendering": [
+        "In loading state, shows header, hides feed-stream and follow-suggestions, shows skeleton in feed-stream (10 PostCard skeletons) and follow-suggestions (3 user card skeletons)",
+        "In ready state, shows all regions",
+        "In error state, shows header, hides other regions, shows error banner in feed-stream with 'Failed to load feed' and retry Button",
+        "In empty state, shows header and follow-suggestions, shows empty message 'Follow users to see posts in your feed' in feed-stream region"
+      ],
+      "interaction": [
+        "Refresh action transitions to loading, calls onRefresh: () => void",
+        "Follow user via FollowSuggestions, calls onFollow: (userId: string) => void, shows success toast 'Now following user'"
+      ],
+      "styling": [
+        "Page uses `flex flex-col h-full`",
+        "Header uses `p-4 border-b bg-background` with title `text-2xl font-bold`",
+        "Feed-stream uses `flex-1`",
+        "Follow-suggestions uses `p-4 border-t`",
+        "Loading skeleton uses stream 10 `h-96 bg-muted`, suggestions 3 `h-48 w-48 bg-muted`",
+        "Error banner in stream `p-8 text-center` with retry `variant=\"default\"`",
+        "Empty message in stream `flex flex-col items-center justify-center h-full` with text `text-lg`",
+        "Suggestions animation uses `useTransition(true, { from: { opacity: 0 }, enter: { opacity: 1 }, config: { tension: 400, friction: 26 } })`",
+        "Hover no specific, but buttons follow media query",
+        "Touch targets for interactions use `min-h-11`",
+        "Dark mode uses `bg-background border-border`",
+        "Z-index for header 200"
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message.",
+        "category": "state"
+      },
+      {
+        "name": "isEmpty",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Empty state.",
+        "category": "state"
+      },
+      {
+        "name": "onRefresh",
+        "type": "() => void",
+        "required": true,
+        "description": "Refresh callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onFollow",
+        "type": "(userId: string) => void",
+        "required": true,
+        "description": "Follow callback.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Retry callback.",
+        "category": "callback"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state.",
+        "args": {
+          "isLoading": false,
+          "error": null,
+          "isEmpty": false,
+          "onRefresh": "fn()",
+          "onFollow": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "isLoading": true,
+          "error": null,
+          "isEmpty": false,
+          "onRefresh": "fn()",
+          "onFollow": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "isLoading": false,
+          "error": "Failed to load feed",
+          "isEmpty": false,
+          "onRefresh": "fn()",
+          "onFollow": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click retry using userEvent.click(getByRole('button', { name: 'Retry' })), 2. Assert onRetry called"
+      },
+      {
+        "name": "Empty",
+        "description": "Empty state.",
+        "args": {
+          "isLoading": false,
+          "error": null,
+          "isEmpty": true,
+          "onRefresh": "fn()",
+          "onFollow": "fn()",
+          "onRetry": "fn()"
+        },
+        "needsPlayFunction": false
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-query",
+      "operationName": "GetFeed",
+      "fields": [
+        "feedItems[].id",
+        "feedItems[].user.name",
+        "feedItems[].user.avatar",
+        "feedItems[].photoUrl",
+        "feedItems[].caption",
+        "feedItems[].likeCount",
+        "feedItems[].commentCount",
+        "suggestedUsers[].id",
+        "suggestedUsers[].name",
+        "suggestedUsers[].avatar"
+      ]
+    }
+  }
+]