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

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

@@ -0,0 +1,1460 @@
+[
+  {
+    "componentId": "exercise-selector",
+    "componentName": "ExerciseSelector",
+    "isNew": true,
+    "atomicType": "molecule",
+    "composes": ["ui-components-combobox"],
+    "specDeltas": {
+      "structure": [
+        "Composes Combobox to provide a searchable dropdown for selecting exercises",
+        "Renders as a Combobox with options prop passed from parent, where each option is { value: string, label: string }",
+        "Uses semantic <label> element associated with the input via htmlFor and id pairing",
+        "Root element is a <section> with role='region' and aria-label='Exercise Selector'"
+      ],
+      "rendering": [
+        "Renders the selected exercise label in the Combobox value display",
+        "In loading state (isLoading=true), renders a Skeleton inside the input area with dimensions matching the input height and width",
+        "In error state (error is truthy), renders an Alert with destructive variant below the Combobox, displaying the error message",
+        "Hides the dropdown list when disabled=true"
+      ],
+      "interaction": [
+        "Calls onSelect: (selected: { value: string, label: string }) => void when an exercise is selected from the dropdown",
+        "Typing in the input filters the options list case-insensitively, trimming whitespace, and shows all options when query is empty",
+        "Arrow down key opens the dropdown if closed, arrow keys navigate options, Enter selects the highlighted option",
+        "Escape closes the dropdown without changing selection",
+        "When disabled=true, prevents opening the dropdown and ignores input changes"
+      ],
+      "styling": [
+        "Root section uses `flex flex-col gap-2` for layout, with `p-4 bg-background rounded-md shadow-sm`.",
+        "Label uses `text-sm font-medium text-foreground` with `mb-1`.",
+        "Combobox input uses `h-10 px-3 py-2 border border-input bg-background text-sm text-foreground rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Dropdown list uses `mt-1 bg-popover text-popover-foreground shadow-md rounded-md overflow-hidden z-[500]` with `useTransition(isOpen, { from: { opacity: 0, scale: 0.95 }, enter: { opacity: 1, scale: 1 }, leave: { opacity: 0, scale: 0.95 }, config: { tension: 400, friction: 22 } })` for animation; respects `useReducedMotion()` by setting `immediate: true` when reduced motion is preferred.",
+        "Each option in dropdown uses `px-4 py-2 text-sm hover:bg-accent hover:text-accent-foreground cursor-pointer` with `@media (hover: hover) and (pointer: fine) { hover:bg-accent }`; selected option uses `bg-accent text-accent-foreground`.",
+        "In loading state, skeleton uses `h-10 w-full bg-muted animate-pulse rounded-md`.",
+        "In error state, alert uses `p-4 border border-destructive bg-destructive/10 text-destructive rounded-md flex items-center gap-2`.",
+        "When disabled, input uses `opacity-50 cursor-not-allowed`.",
+        "Touch targets for dropdown options are `min-h-11 min-w-11` with `touch-action: manipulation`.",
+        "Focus on input uses `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with `transition: ring-color 150ms ease`.",
+        "Numeric displays (if any) use `font-variant-numeric: tabular-nums`."
+      ]
+    },
+    "props": [
+      {
+        "name": "options",
+        "type": "Array<{ value: string; label: string }>",
+        "required": true,
+        "description": "List of available exercises to select from.",
+        "category": "data"
+      },
+      {
+        "name": "value",
+        "type": "string",
+        "required": false,
+        "default": "''",
+        "description": "Currently selected exercise value.",
+        "category": "state"
+      },
+      {
+        "name": "onSelect",
+        "type": "(selected: { value: string; label: string }) => void",
+        "required": true,
+        "description": "Callback when an exercise is selected.",
+        "category": "callback"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Indicates if options are loading.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message to display.",
+        "category": "state"
+      },
+      {
+        "name": "disabled",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Disables the selector.",
+        "category": "state"
+      },
+      {
+        "name": "placeholder",
+        "type": "string",
+        "required": false,
+        "default": "'Select exercise'",
+        "description": "Placeholder text for the input.",
+        "category": "config"
+      },
+      {
+        "name": "size",
+        "type": "\"sm\" | \"md\" | \"lg\"",
+        "required": false,
+        "default": "\"md\"",
+        "description": "Controls the size variant of the selector.",
+        "category": "visual"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state with options.",
+        "args": {
+          "options": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            },
+            {
+              "value": "squat",
+              "label": "Squat"
+            }
+          ],
+          "value": "",
+          "onSelect": "fn()",
+          "isLoading": false,
+          "error": null,
+          "disabled": false,
+          "placeholder": "Select exercise",
+          "size": "md"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "options": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            },
+            {
+              "value": "squat",
+              "label": "Squat"
+            }
+          ],
+          "value": "",
+          "onSelect": "fn()",
+          "isLoading": true,
+          "error": null,
+          "disabled": false,
+          "placeholder": "Select exercise",
+          "size": "md"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "options": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            },
+            {
+              "value": "squat",
+              "label": "Squat"
+            }
+          ],
+          "value": "",
+          "onSelect": "fn()",
+          "isLoading": false,
+          "error": "Failed to load exercises",
+          "disabled": false,
+          "placeholder": "Select exercise",
+          "size": "md"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Disabled",
+        "description": "Disabled state.",
+        "args": {
+          "options": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            },
+            {
+              "value": "squat",
+              "label": "Squat"
+            }
+          ],
+          "value": "bench-press",
+          "onSelect": "fn()",
+          "isLoading": false,
+          "error": null,
+          "disabled": true,
+          "placeholder": "Select exercise",
+          "size": "md"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "InteractiveSelection",
+        "description": "Selecting an option.",
+        "args": {
+          "options": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            },
+            {
+              "value": "squat",
+              "label": "Squat"
+            }
+          ],
+          "value": "",
+          "onSelect": "fn()",
+          "isLoading": false,
+          "error": null,
+          "disabled": false,
+          "placeholder": "Select exercise",
+          "size": "md"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click the combobox trigger to open dropdown, 2. userEvent.click(getByRole('option', { name: 'Bench Press' })), 3. await waitFor(() => expect(getByRole('combobox')).toHaveValue('Bench Press'))"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "options",
+      "fields": ["value", "label"]
+    }
+  },
+  {
+    "componentId": "time-period-selector",
+    "componentName": "TimePeriodSelector",
+    "isNew": true,
+    "atomicType": "molecule",
+    "composes": ["ui-components-select"],
+    "specDeltas": {
+      "structure": [
+        "Composes Select to provide a dropdown for selecting time periods",
+        "Options are predefined periods like 'Last Week', 'Last Month', etc., passed as { value: string, label: string }[]",
+        "Uses semantic <label> element associated with the select via htmlFor and id pairing",
+        "Root element is a <section> with role='region' and aria-label='Time Period Selector'"
+      ],
+      "rendering": [
+        "Renders the selected period label in the Select value display",
+        "In disabled state (disabled=true), renders the select as disabled"
+      ],
+      "interaction": [
+        "Calls onSelect: (selected: string) => void when a time period is selected",
+        "When disabled=true, prevents selection changes"
+      ],
+      "styling": [
+        "Root section uses `flex flex-col gap-2` for layout, with `p-4 bg-background rounded-md shadow-sm`.",
+        "Label uses `text-sm font-medium text-foreground` with `mb-1`.",
+        "Select trigger uses `h-10 px-3 py-2 border border-input bg-background text-sm text-foreground rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 flex items-center justify-between`.",
+        "Select content uses `bg-popover text-popover-foreground shadow-md rounded-md overflow-hidden z-[500]` with `useTransition(isOpen, { from: { opacity: 0, scale: 0.95 }, enter: { opacity: 1, scale: 1 }, leave: { opacity: 0, scale: 0.95 }, config: { tension: 400, friction: 22 } })` for animation; respects `useReducedMotion()` by setting `immediate: true` when reduced motion is preferred.",
+        "Each select item uses `px-4 py-2 text-sm hover:bg-accent hover:text-accent-foreground cursor-pointer` with `@media (hover: hover) and (pointer: fine) { hover:bg-accent }`; selected item uses `bg-accent text-accent-foreground`.",
+        "When disabled, trigger uses `opacity-50 cursor-not-allowed`.",
+        "Touch targets for select items are `min-h-11 min-w-11` with `touch-action: manipulation`.",
+        "Focus on trigger uses `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with `transition: ring-color 150ms ease`.",
+        "Chevron icon in trigger uses `h-4 w-4 text-muted-foreground`.",
+        "Text in items uses `text-balance` for balanced wrapping."
+      ]
+    },
+    "props": [
+      {
+        "name": "options",
+        "type": "Array<{ value: string; label: string }>",
+        "required": true,
+        "description": "List of time period options.",
+        "category": "data"
+      },
+      {
+        "name": "value",
+        "type": "string",
+        "required": false,
+        "default": "''",
+        "description": "Currently selected time period.",
+        "category": "state"
+      },
+      {
+        "name": "onSelect",
+        "type": "(selected: string) => void",
+        "required": true,
+        "description": "Callback when a time period is selected.",
+        "category": "callback"
+      },
+      {
+        "name": "disabled",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Disables the selector.",
+        "category": "state"
+      },
+      {
+        "name": "placeholder",
+        "type": "string",
+        "required": false,
+        "default": "'Select period'",
+        "description": "Placeholder text.",
+        "category": "config"
+      },
+      {
+        "name": "variant",
+        "type": "\"default\" | \"outline\"",
+        "required": false,
+        "default": "\"default\"",
+        "description": "Controls the visual variant of the selector.",
+        "category": "visual"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state with options.",
+        "args": {
+          "options": [
+            {
+              "value": "week",
+              "label": "Last Week"
+            },
+            {
+              "value": "month",
+              "label": "Last Month"
+            }
+          ],
+          "value": "",
+          "onSelect": "fn()",
+          "disabled": false,
+          "placeholder": "Select period",
+          "variant": "default"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Disabled",
+        "description": "Disabled state.",
+        "args": {
+          "options": [
+            {
+              "value": "week",
+              "label": "Last Week"
+            },
+            {
+              "value": "month",
+              "label": "Last Month"
+            }
+          ],
+          "value": "week",
+          "onSelect": "fn()",
+          "disabled": true,
+          "placeholder": "Select period",
+          "variant": "default"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "InteractiveSelection",
+        "description": "Selecting a period.",
+        "args": {
+          "options": [
+            {
+              "value": "week",
+              "label": "Last Week"
+            },
+            {
+              "value": "month",
+              "label": "Last Month"
+            }
+          ],
+          "value": "",
+          "onSelect": "fn()",
+          "disabled": false,
+          "placeholder": "Select period",
+          "variant": "default"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. Click the select trigger to open dropdown, 2. userEvent.click(getByRole('option', { name: 'Last Week' })), 3. await waitFor(() => expect(getByRole('combobox')).toHaveValue('Last Week'))"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "options",
+      "fields": ["value", "label"]
+    }
+  },
+  {
+    "componentId": "workout-log-form",
+    "componentName": "WorkoutLogForm",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-form", "exercise-selector", "ui-components-input", "ui-components-button"],
+    "specDeltas": {
+      "structure": [
+        "Composes Form to create a workout logging form with exercise selector, numeric inputs for sets, reps, weight, and action buttons",
+        "Form header region occupies the top with <header> element containing title and instructions",
+        "Exercise form region uses <main> with role='form' containing ExerciseSelector and three Input fields for sets, reps, weight, each wrapped in Field with labels",
+        "Actions region uses <footer> containing submit Button (variant='default') and cancel Button (variant='outline') in a horizontal row",
+        "Each Input is a numeric input with inputMode='numeric' and autocomplete='off'",
+        "Uses semantic landmarks: <header> for form-header, <main> for exercise-form, <footer> for actions"
+      ],
+      "rendering": [
+        "In loading state (isLoading=true), renders Skeleton placeholders in exercise-form region: one for selector (h-10 w-full), three for inputs (h-10 w-24 each); hides actions region",
+        "In ready state, renders all regions: form-header with title 'Log Workout Session' and instructions 'Enter your workout details', exercise-form with empty fields, actions with enabled buttons",
+        "In editing-invalid state, renders inline error messages below invalid fields using FormMessage with text-destructive, sets aria-invalid='true' and aria-describedby pointing to the error id on invalid inputs; submit button remains enabled",
+        "In submitting state (isSubmitting=true), disables all inputs and buttons, renders Spinner next to submit button with aria-busy='true' and aria-live='polite' announcing 'Saving workout session'",
+        "In error state (error is truthy), hides exercise-form and actions regions, renders Alert with destructive variant in form-header region displaying the error message and a retry Button",
+        "Renders field-level validation errors for sets/reps/weight: must be positive integers, shows 'Must be a positive number' below input when invalid"
+      ],
+      "interaction": [
+        "Calls onSubmit: (data: { exercise: string; sets: number; reps: number; weight: number }) => void when form is valid and submit button is clicked, after validating all fields",
+        "Calls onCancel: () => void when cancel button is clicked",
+        "On input change for sets/reps/weight, validates value > 0 and integer, sets internal error state if invalid, clears error when user edits the field again",
+        "Form submission uses <form> element for native Enter-to-submit on inputs",
+        "Submit button disables during submitting state to prevent duplicate submissions",
+        "Retry button in error state calls onRetry: () => void, which transitions back to loading state",
+        "Validation triggers on blur for each field and on submit for the whole form"
+      ],
+      "styling": [
+        "Root form uses `flex flex-col gap-6 p-6 bg-background rounded-lg shadow-md` with `max-w-md mx-auto`.",
+        "Header uses `text-2xl font-semibold tracking-tight text-foreground text-balance` for title, `text-sm text-muted-foreground` for instructions, with `space-y-2`.",
+        "Main exercise-form uses `flex flex-col gap-4`.",
+        "Each Field uses `flex flex-col gap-1`, label `text-sm font-medium text-foreground`, input `h-10 px-3 py-2 border border-input bg-background text-sm text-foreground rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`.",
+        "Numeric inputs (sets, reps, weight) use `text-right font-variant-numeric: tabular-nums` with `w-24`.",
+        "Footer actions uses `flex justify-end gap-4 mt-4`.",
+        "Submit button uses `bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-4 py-2 rounded-md font-medium text-sm` with `active:scale-[0.97] transition: transform 100ms ease-out`; hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-primary/90 transition: background-color 150ms ease }`.",
+        "Cancel button uses `border border-input bg-background hover:bg-accent hover:text-accent-foreground h-10 px-4 py-2 rounded-md font-medium text-sm` with `active:scale-[0.97] transition: transform 100ms ease-out`; hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent transition: background-color 150ms ease }`.",
+        "In loading state, skeletons use `h-10 w-full bg-muted animate-pulse rounded-md` for selector, `h-10 w-24 bg-muted animate-pulse rounded-md` for inputs.",
+        "In editing-invalid state, invalid inputs use `border-destructive focus-visible:ring-destructive`, error messages `text-sm text-destructive`.",
+        "In submitting state, disabled elements use `opacity-50 cursor-not-allowed`, spinner uses `h-5 w-5 animate-spin text-primary`.",
+        "In error state, alert uses `p-4 border border-destructive bg-destructive/10 text-destructive rounded-md flex items-center gap-2`, retry button `bg-destructive text-destructive-foreground hover:bg-destructive/90 h-10 px-4 py-2 rounded-md`.",
+        "Touch targets for buttons are `min-h-11 min-w-11` with `touch-action: manipulation`.",
+        "Focus on inputs uses `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with `transition: ring-color 150ms ease`.",
+        "Respects prefers-reduced-motion by using `motion-reduce:transition-none` for CSS transitions."
+      ]
+    },
+    "props": [
+      {
+        "name": "onSubmit",
+        "type": "(data: { exercise: string; sets: number; reps: number; weight: number }) => void",
+        "required": true,
+        "description": "Callback for form submission.",
+        "category": "callback"
+      },
+      {
+        "name": "onCancel",
+        "type": "() => void",
+        "required": true,
+        "description": "Callback for cancel action.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback for retry in error state.",
+        "category": "callback"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Indicates loading state.",
+        "category": "state"
+      },
+      {
+        "name": "isSubmitting",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Indicates submitting state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message for error state.",
+        "category": "state"
+      },
+      {
+        "name": "exerciseOptions",
+        "type": "Array<{ value: string; label: string }>",
+        "required": true,
+        "description": "Options for exercise selector.",
+        "category": "data"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state.",
+        "args": {
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()",
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null,
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            },
+            {
+              "value": "squat",
+              "label": "Squat"
+            }
+          ]
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()",
+          "isLoading": true,
+          "isSubmitting": false,
+          "error": null,
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            },
+            {
+              "value": "squat",
+              "label": "Squat"
+            }
+          ]
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "EditingInvalid",
+        "description": "Editing with validation errors.",
+        "args": {
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()",
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null,
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            },
+            {
+              "value": "squat",
+              "label": "Squat"
+            }
+          ]
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. userEvent.type(getByLabelText('Sets'), '-1'), 2. userEvent.tab(), 3. await waitFor(() => expect(getByText('Must be a positive number')).toBeVisible()), 4. userEvent.type(getByLabelText('Sets'), '3'), 5. await waitFor(() => expect(queryByText('Must be a positive number')).not.toBeInTheDocument())"
+      },
+      {
+        "name": "Submitting",
+        "description": "Submitting state.",
+        "args": {
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()",
+          "isLoading": false,
+          "isSubmitting": true,
+          "error": null,
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            },
+            {
+              "value": "squat",
+              "label": "Squat"
+            }
+          ]
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "onSubmit": "fn()",
+          "onCancel": "fn()",
+          "onRetry": "fn()",
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": "Failed to save",
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            },
+            {
+              "value": "squat",
+              "label": "Squat"
+            }
+          ]
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. userEvent.click(getByRole('button', { name: 'Retry' })), 2. expect(onRetry).toHaveBeenCalled()"
+      }
+    ],
+    "dataContract": {
+      "source": "local-state",
+      "fields": ["exercise", "sets", "reps", "weight"]
+    }
+  },
+  {
+    "componentId": "strength-progress-dashboard",
+    "componentName": "StrengthProgressDashboard",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-chart", "exercise-selector", "time-period-selector", "ui-components-button"],
+    "specDeltas": {
+      "structure": [
+        "Composes Chart for displaying progress, with ExerciseSelector and TimePeriodSelector in a horizontal row above, and actions in a footer row",
+        "Progress-charts region uses <main> with role='region' and aria-label='Progress Charts' containing the Chart",
+        "Exercise-selector and time-period-selector regions are <aside> elements in a flex row above the chart",
+        "Actions region uses <footer> containing 'Log Workout' (default variant) and 'View Leaderboards' (outline variant) buttons",
+        "Uses semantic landmarks: <main> for progress-charts, <aside> for selectors, <footer> for actions"
+      ],
+      "rendering": [
+        "In loading state (isLoading=true), renders Skeleton in progress-charts region (h-64 w-full), hides selectors and actions",
+        "In ready state, renders all regions: Chart with data from progressData, selectors with current values, enabled action buttons",
+        "In error state (error is truthy), hides selectors and actions, renders Alert with destructive variant in progress-charts region displaying error message and retry Button",
+        "Renders Chart as a line chart showing strength progress over time for the selected exercise and period"
+      ],
+      "interaction": [
+        "Calls onExerciseChange: (exercise: string) => void when exercise selector changes, triggering reload",
+        "Calls onPeriodChange: (period: string) => void when time period selector changes, triggering reload",
+        "Calls onLogWorkout: () => void when 'Log Workout' button is clicked",
+        "Calls onViewLeaderboards: () => void when 'View Leaderboards' button is clicked",
+        "Retry button in error state calls onRetry: () => void, transitioning to loading state"
+      ],
+      "styling": [
+        "Root container uses `flex flex-col gap-6 p-6 bg-background`.",
+        "Selectors row uses `flex flex-row gap-4 justify-start`.",
+        "Main progress-charts uses `h-64 w-full bg-card rounded-lg shadow-sm` with `overflow-hidden`.",
+        "Chart uses `w-full h-full` with CSS variables for colors, responsive sizing via `ResponsiveContainer`.",
+        "Footer actions uses `flex justify-end gap-4`.",
+        "Log Workout button uses `bg-primary text-primary-foreground hover:bg-primary/90 h-10 px-4 py-2 rounded-md font-medium text-sm` with `active:scale-[0.97] transition: transform 100ms ease-out`; hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-primary/90 transition: background-color 150ms ease }`.",
+        "View Leaderboards button uses `border border-input bg-background hover:bg-accent hover:text-accent-foreground h-10 px-4 py-2 rounded-md font-medium text-sm` with `active:scale-[0.97] transition: transform 100ms ease-out`; hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent transition: background-color 150ms ease }`.",
+        "In loading state, skeleton uses `h-64 w-full bg-muted animate-pulse rounded-lg`.",
+        "In error state, alert uses `p-4 border border-destructive bg-destructive/10 text-destructive rounded-md flex items-center gap-2`, retry button `bg-destructive text-destructive-foreground hover:bg-destructive/90 h-10 px-4 py-2 rounded-md`.",
+        "Chart lines use `stroke: var(--primary)` with `stroke-width: 2`, points `fill: var(--primary)`.",
+        "Touch targets for buttons are `min-h-11 min-w-11` with `touch-action: manipulation`.",
+        "Numeric values in chart use `font-variant-numeric: tabular-nums`.",
+        "Headings use `text-balance`."
+      ]
+    },
+    "props": [
+      {
+        "name": "progressData",
+        "type": "Array<{ date: string; value: number }>",
+        "required": true,
+        "description": "Data for the progress chart.",
+        "category": "data"
+      },
+      {
+        "name": "exerciseOptions",
+        "type": "Array<{ value: string; label: string }>",
+        "required": true,
+        "description": "Options for exercise selector.",
+        "category": "data"
+      },
+      {
+        "name": "periodOptions",
+        "type": "Array<{ value: string; label: string }>",
+        "required": true,
+        "description": "Options for time period selector.",
+        "category": "data"
+      },
+      {
+        "name": "selectedExercise",
+        "type": "string",
+        "required": false,
+        "default": "''",
+        "description": "Currently selected exercise.",
+        "category": "state"
+      },
+      {
+        "name": "selectedPeriod",
+        "type": "string",
+        "required": false,
+        "default": "''",
+        "description": "Currently selected period.",
+        "category": "state"
+      },
+      {
+        "name": "onExerciseChange",
+        "type": "(exercise: string) => void",
+        "required": true,
+        "description": "Callback for exercise change.",
+        "category": "callback"
+      },
+      {
+        "name": "onPeriodChange",
+        "type": "(period: string) => void",
+        "required": true,
+        "description": "Callback for period change.",
+        "category": "callback"
+      },
+      {
+        "name": "onLogWorkout",
+        "type": "() => void",
+        "required": true,
+        "description": "Callback for log workout action.",
+        "category": "callback"
+      },
+      {
+        "name": "onViewLeaderboards",
+        "type": "() => void",
+        "required": true,
+        "description": "Callback for view leaderboards action.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback for retry in error state.",
+        "category": "callback"
+      },
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Indicates loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Error message for error state.",
+        "category": "state"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state with data.",
+        "args": {
+          "progressData": [
+            {
+              "date": "2024-01-01",
+              "value": 100
+            },
+            {
+              "date": "2024-02-01",
+              "value": 120
+            }
+          ],
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            }
+          ],
+          "periodOptions": [
+            {
+              "value": "month",
+              "label": "Last Month"
+            }
+          ],
+          "selectedExercise": "bench-press",
+          "selectedPeriod": "month",
+          "onExerciseChange": "fn()",
+          "onPeriodChange": "fn()",
+          "onLogWorkout": "fn()",
+          "onViewLeaderboards": "fn()",
+          "onRetry": "fn()",
+          "isLoading": false,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "progressData": [
+            {
+              "date": "2024-01-01",
+              "value": 100
+            },
+            {
+              "date": "2024-02-01",
+              "value": 120
+            }
+          ],
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            }
+          ],
+          "periodOptions": [
+            {
+              "value": "month",
+              "label": "Last Month"
+            }
+          ],
+          "selectedExercise": "bench-press",
+          "selectedPeriod": "month",
+          "onExerciseChange": "fn()",
+          "onPeriodChange": "fn()",
+          "onLogWorkout": "fn()",
+          "onViewLeaderboards": "fn()",
+          "onRetry": "fn()",
+          "isLoading": true,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "progressData": [
+            {
+              "date": "2024-01-01",
+              "value": 100
+            },
+            {
+              "date": "2024-02-01",
+              "value": 120
+            }
+          ],
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            }
+          ],
+          "periodOptions": [
+            {
+              "value": "month",
+              "label": "Last Month"
+            }
+          ],
+          "selectedExercise": "bench-press",
+          "selectedPeriod": "month",
+          "onExerciseChange": "fn()",
+          "onPeriodChange": "fn()",
+          "onLogWorkout": "fn()",
+          "onViewLeaderboards": "fn()",
+          "onRetry": "fn()",
+          "isLoading": false,
+          "error": "Failed to load data"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. userEvent.click(getByRole('button', { name: 'Retry' })), 2. expect(onRetry).toHaveBeenCalled()"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "progressData",
+      "fields": ["date", "value"]
+    }
+  },
+  {
+    "componentId": "leaderboard",
+    "componentName": "Leaderboard",
+    "isNew": true,
+    "atomicType": "organism",
+    "composes": ["ui-components-table", "exercise-selector", "time-period-selector", "ui-components-badge"],
+    "specDeltas": {
+      "structure": [
+        "Composes Table for ranked list, with ExerciseSelector and TimePeriodSelector in a flex row above, and user-rank as a highlighted TableRow",
+        "Leaderboard-list region uses <main> with role='region' and aria-label='Leaderboard List' containing the Table",
+        "Filters region is <aside> with selectors in a horizontal row",
+        "User-rank region is a <section> with role='region' and aria-label='Your Rank' showing Badge with rank number and position text",
+        "Table structure: TableHeader with columns for rank, athlete, performance; TableBody with TableRow for each entry"
+      ],
+      "rendering": [
+        "In loading state (isLoading=true), renders Skeleton rows in leaderboard-list region (5 rows, each with h-10 w-full)",
+        "In ready state, renders Table with leaderboardData, highlights user's row with accent background if present",
+        "In error state (error is truthy), renders Alert with destructive variant in leaderboard-list region displaying error message and retry Button, hides filters and user-rank",
+        "Renders user rank as a Badge with variant='default' showing 'Rank #X' where X is from userRank prop"
+      ],
+      "interaction": [
+        "Calls onExerciseChange: (exercise: string) => void when exercise selector changes",
+        "Calls onPeriodChange: (period: string) => void when time period selector changes",
+        "Calls onViewProgress: () => void when 'View My Progress' button is clicked (secondary emphasis)",
+        "Retry button calls onRetry: () => void, transitioning to loading"
+      ],
+      "styling": [
+        "Root container uses `flex flex-col gap-6 p-6 bg-background`.",
+        "Filters row uses `flex flex-row gap-4 justify-start`.",
+        "Main leaderboard-list uses `overflow-auto border border-border rounded-md shadow-sm`.",
+        "Table uses `w-full border-collapse`, rows `border-b last:border-b-0 hover:bg-muted/50` with `@media (hover: hover) and (pointer: fine) { hover:bg-muted/50 transition: background-color 150ms ease }`.",
+        "TableHead uses `text-left font-medium text-muted-foreground text-sm p-4 bg-muted/50`.",
+        "TableCell uses `p-4 text-sm text-foreground`, rank `font-bold tabular-nums`, performance `text-right tabular-nums`.",
+        "User row uses `bg-accent text-accent-foreground font-semibold`.",
+        "User-rank section uses `flex items-center gap-2 p-4 bg-card rounded-md shadow-sm`, badge `bg-primary text-primary-foreground px-2 py-1 rounded-full text-sm font-medium`.",
+        "In loading state, skeleton rows use `h-10 w-full bg-muted animate-pulse` for 5 rows.",
+        "In error state, alert uses `p-4 border border-destructive bg-destructive/10 text-destructive rounded-md flex items-center gap-2`, retry button `bg-destructive text-destructive-foreground hover:bg-destructive/90 h-10 px-4 py-2 rounded-md`.",
+        "Touch targets for interactive elements are `min-h-11 min-w-11` with `touch-action: manipulation`.",
+        "Focus on filters uses `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with `transition: ring-color 150ms ease`.",
+        "View My Progress button uses `border border-input bg-background hover:bg-accent hover:text-accent-foreground h-10 px-4 py-2 rounded-md font-medium text-sm` with `active:scale-[0.97] transition: transform 100ms ease-out`; hover wrapped in `@media (hover: hover) and (pointer: fine) { hover:bg-accent transition: background-color 150ms ease }`."
+      ]
+    },
+    "props": [
+      {
+        "name": "leaderboardData",
+        "type": "Array<{ rank: number; athlete: string; performance: number }>",
+        "required": true,
+        "description": "Data for the leaderboard table.",
+        "category": "data"
+      },
+      {
+        "name": "exerciseOptions",
+        "type": "Array<{ value: string; label: string }>",
+        "required": true,
+        "description": "Options for exercise filter.",
+        "category": "data"
+      },
+      {
+        "name": "periodOptions",
+        "type": "Array<{ value: string; label: string }>",
+        "required": true,
+        "description": "Options for time period filter.",
+        "category": "data"
+      },
+      {
+        "name": "selectedExercise",
+        "type": "string",
+        "required": false,
+        "default": "''",
+        "description": "Selected exercise.",
+        "category": "state"
+      },
+      {
+        "name": "selectedPeriod",
+        "type": "string",
+        "required": false,
+        "default": "''",
+        "description": "Selected period.",
+        "category": "state"
+      },
+      {
+        "name": "userRank",
+        "type": "number | null",
+        "required": false,
+        "default": "null",
+        "description": "User's current rank.",
+        "category": "data"
+      },
+      {
+        "name": "onExerciseChange",
+        "type": "(exercise: string) => void",
+        "required": true,
+        "description": "Callback for exercise change.",
+        "category": "callback"
+      },
+      {
+        "name": "onPeriodChange",
+        "type": "(period: string) => void",
+        "required": true,
+        "description": "Callback for period change.",
+        "category": "callback"
+      },
+      {
+        "name": "onViewProgress",
+        "type": "() => void",
+        "required": true,
+        "description": "Callback for view progress action.",
+        "category": "callback"
+      },
+      {
+        "name": "onRetry",
+        "type": "() => void",
+        "required": false,
+        "description": "Callback for retry.",
+        "category": "callback"
+      },
+      {
+        "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": "Ready state with data.",
+        "args": {
+          "leaderboardData": [
+            {
+              "rank": 1,
+              "athlete": "John Doe",
+              "performance": 200
+            },
+            {
+              "rank": 2,
+              "athlete": "Jane Smith",
+              "performance": 180
+            }
+          ],
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            }
+          ],
+          "periodOptions": [
+            {
+              "value": "month",
+              "label": "Last Month"
+            }
+          ],
+          "selectedExercise": "bench-press",
+          "selectedPeriod": "month",
+          "userRank": 3,
+          "onExerciseChange": "fn()",
+          "onPeriodChange": "fn()",
+          "onViewProgress": "fn()",
+          "onRetry": "fn()",
+          "isLoading": false,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "leaderboardData": [
+            {
+              "rank": 1,
+              "athlete": "John Doe",
+              "performance": 200
+            },
+            {
+              "rank": 2,
+              "athlete": "Jane Smith",
+              "performance": 180
+            }
+          ],
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            }
+          ],
+          "periodOptions": [
+            {
+              "value": "month",
+              "label": "Last Month"
+            }
+          ],
+          "selectedExercise": "bench-press",
+          "selectedPeriod": "month",
+          "userRank": 3,
+          "onExerciseChange": "fn()",
+          "onPeriodChange": "fn()",
+          "onViewProgress": "fn()",
+          "onRetry": "fn()",
+          "isLoading": true,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "leaderboardData": [
+            {
+              "rank": 1,
+              "athlete": "John Doe",
+              "performance": 200
+            },
+            {
+              "rank": 2,
+              "athlete": "Jane Smith",
+              "performance": 180
+            }
+          ],
+          "exerciseOptions": [
+            {
+              "value": "bench-press",
+              "label": "Bench Press"
+            }
+          ],
+          "periodOptions": [
+            {
+              "value": "month",
+              "label": "Last Month"
+            }
+          ],
+          "selectedExercise": "bench-press",
+          "selectedPeriod": "month",
+          "userRank": 3,
+          "onExerciseChange": "fn()",
+          "onPeriodChange": "fn()",
+          "onViewProgress": "fn()",
+          "onRetry": "fn()",
+          "isLoading": false,
+          "error": "Failed to load leaderboard"
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. userEvent.click(getByRole('button', { name: 'Retry' })), 2. expect(onRetry).toHaveBeenCalled()"
+      }
+    ],
+    "dataContract": {
+      "source": "props",
+      "propsFieldName": "leaderboardData",
+      "fields": ["rank", "athlete", "performance"]
+    }
+  },
+  {
+    "componentId": "log-workout-session-page",
+    "componentName": "LogWorkoutSessionPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": ["workout-log-form"],
+    "specDeltas": {
+      "structure": [
+        "Page-level component with dedicated route '/log-workout-session'",
+        "Composes WorkoutLogForm in the main content area",
+        "Uses <main> for the form container with role='main'"
+      ],
+      "rendering": [
+        "In loading state, shows WorkoutLogForm with isLoading=true, rendering skeletons for form fields",
+        "In ready state, shows WorkoutLogForm with empty fields ready for input",
+        "In editing-invalid state, shows WorkoutLogForm with validation errors displayed inline",
+        "In submitting state, shows WorkoutLogForm with isSubmitting=true, disabling inputs and showing progress spinner",
+        "In error state, shows WorkoutLogForm with error='Failed to save workout session', rendering error banner with retry button; hides form fields"
+      ],
+      "interaction": [
+        "On submit, calls mutation to save workout data, transitions to submitting, on success navigates to view-strength-progress, on failure to error",
+        "On cancel, navigates to view-strength-progress without saving",
+        "On retry from error, re-attempts the submission or reloads form data"
+      ],
+      "styling": [
+        "Root page uses `min-h-screen bg-background flex items-center justify-center p-4`.",
+        "Main container uses `w-full max-w-md` with `useSpring({ opacity: isLoading ? 0 : 1, config: { tension: 400, friction: 26 } })` for subtle fade on load; respects `useReducedMotion()` by setting `immediate: true`.",
+        "In loading state, skeletons use `h-10 w-full bg-muted animate-pulse rounded-md` matching form structure.",
+        "In submitting state, progress spinner uses `h-5 w-5 animate-spin text-primary` with CSS `@keyframes spin { 0% { transform: rotate(0deg) } 100% { transform: rotate(360deg) } }` and `animation: spin 1s linear infinite`.",
+        "In error state, alert uses `p-4 border border-destructive bg-destructive/10 text-destructive rounded-md flex flex-col gap-2 items-center`, retry button `bg-destructive text-destructive-foreground hover:bg-destructive/90 h-10 px-4 py-2 rounded-md` with hover animation.",
+        "Page title (if present) uses `text-3xl font-bold tracking-tight text-foreground text-balance mb-6`.",
+        "Transitions between states use `useTransition(state, { from: { opacity: 0 }, enter: { opacity: 1 }, leave: { opacity: 0 }, config: { tension: 300, friction: 22 } })`; respects reduced motion.",
+        "All interactive elements have `min-h-11 min-w-11 touch-action: manipulation`.",
+        "Focus rings use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with `transition: ring-color 150ms ease`.",
+        "Numeric displays use `font-variant-numeric: tabular-nums`."
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls loading state.",
+        "category": "state"
+      },
+      {
+        "name": "isSubmitting",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls submitting state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Controls error state.",
+        "category": "state"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "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 save"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "InteractiveSubmit",
+        "description": "Submitting the form.",
+        "args": {
+          "isLoading": false,
+          "isSubmitting": false,
+          "error": null
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. userEvent.type(getByLabelText('Exercise'), 'Bench Press'), 2. userEvent.type(getByLabelText('Sets'), '3'), 3. userEvent.type(getByLabelText('Reps'), '10'), 4. userEvent.type(getByLabelText('Weight'), '100'), 5. userEvent.click(getByRole('button', { name: 'Log Workout' })), 6. await waitFor(() => expect(getByText('Saving workout session')).toBeVisible())"
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-mutation",
+      "operationName": "LogWorkoutSession",
+      "fields": ["exercise", "sets", "reps", "weight"]
+    }
+  },
+  {
+    "componentId": "view-strength-progress-page",
+    "componentName": "ViewStrengthProgressPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": ["strength-progress-dashboard"],
+    "specDeltas": {
+      "structure": [
+        "Page-level component with dedicated route '/view-strength-progress'",
+        "Composes StrengthProgressDashboard in the main content area",
+        "Uses <main> for the dashboard container with role='main'"
+      ],
+      "rendering": [
+        "In loading state, shows StrengthProgressDashboard with isLoading=true, rendering skeleton for chart",
+        "In ready state, shows StrengthProgressDashboard with fetched progressData",
+        "In error state, shows StrengthProgressDashboard with error='Failed to load strength progress data', rendering error banner with retry"
+      ],
+      "interaction": [
+        "On page load, fetches progress data via query, transitions to loading, on success to ready, on failure to error",
+        "On filter change (exercise or period), refetches data, transitions to loading",
+        "On log workout, navigates to log-workout-session",
+        "On view leaderboards, navigates to compete-on-leaderboards",
+        "On retry from error, refetches data"
+      ],
+      "styling": [
+        "Root page uses `min-h-screen bg-background p-4`.",
+        "Main container uses `max-w-7xl mx-auto` with `useSpring({ opacity: isLoading ? 0 : 1, config: { tension: 400, friction: 26 } })` for fade; respects `useReducedMotion()`.",
+        "In loading state, chart skeleton uses `h-64 w-full bg-muted animate-pulse rounded-lg`.",
+        "In error state, alert uses `p-4 border border-destructive bg-destructive/10 text-destructive rounded-md flex flex-col gap-2 items-center`, retry button `bg-destructive text-destructive-foreground hover:bg-destructive/90 h-10 px-4 py-2 rounded-md` with hover.",
+        "Page title uses `text-3xl font-bold tracking-tight text-foreground text-balance mb-6`.",
+        "State transitions use `useTransition(state, { from: { opacity: 0 }, enter: { opacity: 1 }, leave: { opacity: 0 }, config: { tension: 300, friction: 22 } })`; respects reduced motion.",
+        "Interactive buttons have `min-h-11 min-w-11 touch-action: manipulation`.",
+        "Focus rings use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with `transition: ring-color 150ms ease`.",
+        "Chart numeric labels use `font-variant-numeric: tabular-nums`.",
+        "Headings use `text-balance`.",
+        "Z-index for overlays (if any) uses `z-[400]` for modals."
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Controls error state.",
+        "category": "state"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state.",
+        "args": {
+          "isLoading": false,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "isLoading": true,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "isLoading": false,
+          "error": "Failed to load data"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "InteractiveFilter",
+        "description": "Changing filters.",
+        "args": {
+          "isLoading": false,
+          "error": null
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. userEvent.click(getByRole('combobox', { name: 'Exercise' })), 2. userEvent.click(getByRole('option', { name: 'Squat' })), 3. await waitFor(() => expect(getByText('Loading...')).toBeVisible())"
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-query",
+      "operationName": "GetStrengthProgress",
+      "fields": ["date", "value", "exercise"]
+    }
+  },
+  {
+    "componentId": "compete-on-leaderboards-page",
+    "componentName": "CompeteOnLeaderboardsPage",
+    "isNew": true,
+    "atomicType": "page",
+    "composes": ["leaderboard"],
+    "specDeltas": {
+      "structure": [
+        "Page-level component with dedicated route '/compete-on-leaderboards' accepting parameters exerciseId and timePeriod",
+        "Composes Leaderboard in the main content area",
+        "Uses <main> for the leaderboard container with role='main'"
+      ],
+      "rendering": [
+        "In loading state, shows Leaderboard with isLoading=true, rendering skeleton rows for table",
+        "In ready state, shows Leaderboard with fetched leaderboardData and userRank",
+        "In error state, shows Leaderboard with error='Failed to load leaderboard data', rendering error banner with retry"
+      ],
+      "interaction": [
+        "On page load, fetches leaderboard data via query using route parameters, transitions to loading, on success to ready, on failure to error",
+        "On filter change, updates route parameters and refetches",
+        "On view progress, navigates to view-strength-progress",
+        "On retry, refetches data"
+      ],
+      "styling": [
+        "Root page uses `min-h-screen bg-background p-4`.",
+        "Main container uses `max-w-7xl mx-auto` with `useSpring({ opacity: isLoading ? 0 : 1, config: { tension: 400, friction: 26 } })` for fade; respects `useReducedMotion()`.",
+        "In loading state, table skeletons use `h-10 w-full bg-muted animate-pulse` for multiple rows.",
+        "In error state, alert uses `p-4 border border-destructive bg-destructive/10 text-destructive rounded-md flex flex-col gap-2 items-center`, retry button `bg-destructive text-destructive-foreground hover:bg-destructive/90 h-10 px-4 py-2 rounded-md` with hover.",
+        "Page title uses `text-3xl font-bold tracking-tight text-foreground text-balance mb-6`.",
+        "State transitions use `useTransition(state, { from: { opacity: 0 }, enter: { opacity: 1 }, leave: { opacity: 0 }, config: { tension: 300, friction: 22 } })`; respects reduced motion.",
+        "Interactive elements have `min-h-11 min-w-11 touch-action: manipulation`.",
+        "Focus rings use `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` with `transition: ring-color 150ms ease`.",
+        "Rank numbers use `font-variant-numeric: tabular-nums`.",
+        "Table headings use `text-balance`."
+      ]
+    },
+    "props": [
+      {
+        "name": "isLoading",
+        "type": "boolean",
+        "required": false,
+        "default": "false",
+        "description": "Controls loading state.",
+        "category": "state"
+      },
+      {
+        "name": "error",
+        "type": "string | null",
+        "required": false,
+        "default": "null",
+        "description": "Controls error state.",
+        "category": "state"
+      }
+    ],
+    "storyVariants": [
+      {
+        "name": "Default",
+        "description": "Ready state.",
+        "args": {
+          "isLoading": false,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Loading",
+        "description": "Loading state.",
+        "args": {
+          "isLoading": true,
+          "error": null
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "Error",
+        "description": "Error state.",
+        "args": {
+          "isLoading": false,
+          "error": "Failed to load data"
+        },
+        "needsPlayFunction": false
+      },
+      {
+        "name": "InteractiveFilter",
+        "description": "Changing filters.",
+        "args": {
+          "isLoading": false,
+          "error": null
+        },
+        "needsPlayFunction": true,
+        "playDescription": "1. userEvent.click(getByRole('combobox', { name: 'Exercise' })), 2. userEvent.click(getByRole('option', { name: 'Squat' })), 3. await waitFor(() => expect(getByText('Loading...')).toBeVisible())"
+      }
+    ],
+    "dataContract": {
+      "source": "graphql-query",
+      "operationName": "GetLeaderboard",
+      "fields": ["rank", "athlete", "performance", "exerciseId", "timePeriod"]
+    }
+  }
+]