diff --git a/docs/src/pages/components/NumberInput.svx b/docs/src/pages/components/NumberInput.svx
index 7c4c7317..93e89ea3 100644
--- a/docs/src/pages/components/NumberInput.svx
+++ b/docs/src/pages/components/NumberInput.svx
@@ -7,74 +7,100 @@ components: ["NumberInput", "NumberInputSkeleton"]
   import Preview from "../../components/Preview.svelte";
 </script>
 
+The `NumberInput` component provides a controlled input for numerical values. It supports validation, step values, and various states to ensure accurate data entry.
+
 ## Default
 
-This component requires a numerical value for `value`.
-
-See [#no-value](#no-value) to allow for an empty value.
+Create a basic number input with increment and decrement controls. The input accepts numerical values and provides visual feedback.
 
 <NumberInput label="Clusters" value={0} />
 
-## With helper text
+## No value
+
+Allow empty values by setting both `allowEmpty` to `true` and `value` to `null`. The `allowEmpty` prop enables the empty state, while `value={null}` represents no value.
+
+<FileSource src="/framed/NumberInput/NumberInputEmpty" />
+
+## Helper text
+
+Add descriptive text below the input using the `helperText` prop. This helps users understand the expected input.
 
 <NumberInput label="Clusters" value={0} helperText="Clusters provisioned in your region" />
 
 ## Minimum and maximum values
 
+Constrain input values using `min` and `max` props. This example limits values between 4 and 20.
+
 <NumberInput min="{4}" max="{20}" value="{4}" invalidText="Number must be between 4 and 20." helperText="Clusters provisioned in your region" label="Clusters (4 min, 20 max)" />
 
-## With step value
+## Step value
+
+Control the increment/decrement step size using the `step` prop. This example uses a step of 0.1.
 
 <NumberInput value="{1}" helperText="Step of 0.1" step={0.1} label="Clusters" />
 
-## No value
-
-Set `allowEmpty` to `true` to allow for no value.
-
-Set `value` to `null` to denote "no value."
-
-<FileSource src="/framed/NumberInput/NumberInputEmpty" />
-
 ## Hidden label
 
+Hide the label visually while maintaining accessibility by setting `hideLabel` to `true`. The label is still available to screen readers.
+
 <NumberInput hideLabel label="Clusters" value={0} />
 
-## Hidden steppers
-
-<NumberInput hideSteppers label="Clusters" value={0} />
-
-## Light variant
-
-<NumberInput light label="Clusters" value={0} />
-
-## Read-only variant
-
-<NumberInput readonly label="Clusters" value={0} />
-
 ## Extra-large size
 
+Use the extra-large size for prominent inputs by setting `size` to `"xl"`. This provides more visual emphasis.
+
 <NumberInput size="xl" label="Clusters" value={0} />
 
 ## Small size
 
+Use the small size for compact layouts by setting `size` to `"sm"`. This is ideal for secondary inputs.
+
 <NumberInput size="sm" label="Clusters" value={0} />
 
+## Light variant
+
+Use the light variant for dark backgrounds by setting `light` to `true`. This provides better contrast in dark themes.
+
+<NumberInput light label="Clusters" value={0} />
+
 ## Invalid state
 
+Indicate an invalid value by setting `invalid` to `true`. This example shows a validation error.
+
 <NumberInput invalid invalidText="Invalid value" label="Clusters" value={0} />
 
 ## Warning state
 
+Indicate a warning state by setting `warn` to `true`. This example shows a warning about the input value.
+
 <NumberInput warn warnText="A high number may impact initial rollout" label="Clusters" value={25} />
 
 ## Disabled state
 
+Disable the input by setting `disabled` to `true`. This prevents all user interaction.
+
 <NumberInput disabled label="Clusters" value={0} />
 
+## Read-only state
+
+Make the input read-only by setting `readonly` to `true`. This allows viewing but prevents editing.
+
+<NumberInput readonly label="Clusters" value={0} />
+
+## Hidden steppers
+
+Hide the increment/decrement controls by setting `hideSteppers` to `true`. This provides a simpler input interface.
+
+<NumberInput hideSteppers label="Clusters" value={0} />
+
 ## Skeleton
 
+Show a loading state using the `NumberInputSkeleton` component. This is useful while data is being fetched.
+
 <NumberInputSkeleton />
 
 ## Skeleton without label
 
+Show a loading state without a label by setting `hideLabel` to `true`. This maintains layout consistency.
+
 <NumberInputSkeleton hideLabel />
\ No newline at end of file