@nationaldesignstudio/react 0.3.0 → 0.5.0

package/dist/component-registry.md

@@ -1,7 +1,7 @@
 # Component Registry
 
 > Auto-generated component metadata for AI/agent consumption.
-> Generated: 2026-01-13T20:09:44.586Z
+> Generated: 2026-01-16T16:52:21.427Z
 
 ---
 
@@ -54,7 +54,7 @@ className="w-48"      // 48px width
 className="h-64"      // 64px height
 ```
 
-**Available sizes:** 0, 2, 4, 6, 8, 10, 11, 12, 16, 20, 24, 28, 32, 36, 40, 48, 56, 64, 72, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 240, 256, 288, 320, 352, 384, 400
+**Available sizes:** 0, 1, 2, 4, 6, 8, 10, 11, 12, 16, 20, 24, 28, 32, 36, 40, 48, 56, 64, 72, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 240, 256, 288, 320, 352, 384, 400
 
 ### Typography
 
@@ -142,86 +142,53 @@ className="font-semibold"        // Font weight 600
 ```
 
 ```tsx
-<Button variant="solid">Solid</Button>
+<div className="flex flex-col gap-24">
+      <div className="flex items-center gap-16">
+        <Button variant="primary">Primary</Button>
+        <Button variant="default">Default</Button>
+        <Button variant="secondary">Secondary</Button>
+        <Button variant="destructive">Destructive</Button>
+        <Button variant="outline">Outline</Button>
+        <Button variant="ghost">Ghost</Button>
+        <Button variant="link">Link</Button>
+      </div>
+    </div>
 ```
 
 ```tsx
-<Button variant="outline">Outline</Button>
+<Button variant="primary">Primary</Button>
 ```
 
 ```tsx
-<Button variant="ghost">Ghost</Button>
+<Button variant="default">Default</Button>
 ```
 
 ```tsx
-<Button variant="subtle">Subtle</Button>
+<Button variant="secondary">Secondary</Button>
 ```
 
 ```tsx
-<DarkBackground>
-    <Button variant="solid" colorScheme="light">
-      Solid Light
-    </Button>
-  </DarkBackground>
+<Button variant="destructive">Destructive</Button>
 ```
 
 ```tsx
-<DarkBackground>
-    <Button variant="outline" colorScheme="light">
-      Outline Light
-    </Button>
-  </DarkBackground>
+<Button variant="outline">Outline</Button>
 ```
 
 ```tsx
-<DarkBackground>
-    <Button variant="ghost" colorScheme="light">
-      Ghost Light
-    </Button>
-  </DarkBackground>
+<Button variant="ghost">Ghost</Button>
 ```
 
 ```tsx
-<DarkBackground>
-    <Button variant="subtle" colorScheme="light">
-      Subtle Light
-    </Button>
-  </DarkBackground>
+<Button variant="link">Link</Button>
 ```
 
 ```tsx
-<div className="flex flex-col gap-spacing-32">
-    <div>
-      <h3 className="mb-spacing-16 text-14 font-medium text-text-secondary">
-        Dark Color Scheme (for light backgrounds)
-      </h3>
-      <div className="flex gap-spacing-16">
-        <Button variant="solid">Solid</Button>
-        <Button variant="outline">Outline</Button>
-        <Button variant="ghost">Ghost</Button>
-        <Button variant="subtle">Subtle</Button>
-      </div>
+<div className="flex items-center gap-16">
+      <Button size="sm">Small</Button>
+      <Button size="default">Default</Button>
+      <Button size="lg">Large</Button>
     </div>
-    <DarkBackground>
-      <h3 className="mb-spacing-16 text-14 font-medium text-gray-400">
-        Light Color Scheme (for dark backgrounds)
-      </h3>
-      <div className="flex gap-spacing-16">
-        <Button variant="solid" colorScheme="light">
-          Solid
-        </Button>
-        <Button variant="outline" colorScheme="light">
-          Outline
-        </Button>
-        <Button variant="ghost" colorScheme="light">
-          Ghost
-        </Button>
-        <Button variant="subtle" colorScheme="light">
-          Subtle
-        </Button>
-      </div>
-    </DarkBackground>
-  </div>
 ```
 
 ```tsx
@@ -229,7 +196,7 @@ className="font-semibold"        // Font weight 600
 ```
 
 ```tsx
-<Button size="default">Medium</Button>
+<Button size="default">Default</Button>
 ```
 
 ```tsx
@@ -240,6 +207,115 @@ className="font-semibold"        // Font weight 600
 <Button disabled>Disabled</Button>
 ```
 
+```tsx
+<div className="flex items-center gap-16">
+      <Button variant="primary" disabled>
+        Primary
+      </Button>
+      <Button variant="default" disabled>
+        Default
+      </Button>
+      <Button variant="secondary" disabled>
+        Secondary
+      </Button>
+      <Button variant="destructive" disabled>
+        Destructive
+      </Button>
+      <Button variant="outline" disabled>
+        Outline
+      </Button>
+      <Button variant="ghost" disabled>
+        Ghost
+      </Button>
+      <Button variant="link" disabled>
+        Link
+      </Button>
+    </div>
+```
+
+```tsx
+<div className="flex flex-col gap-24">
+      <div>
+        <h3 className="mb-12 text-14 font-medium text-gray-600">Small</h3>
+        <div className="flex items-center gap-12">
+          <Button variant="primary" size="sm">
+            Primary
+          </Button>
+          <Button variant="default" size="sm">
+            Default
+          </Button>
+          <Button variant="secondary" size="sm">
+            Secondary
+          </Button>
+          <Button variant="destructive" size="sm">
+            Destructive
+          </Button>
+          <Button variant="outline" size="sm">
+            Outline
+          </Button>
+          <Button variant="ghost" size="sm">
+            Ghost
+          </Button>
+          <Button variant="link" size="sm">
+            Link
+          </Button>
+        </div>
+      </div>
+      <div>
+        <h3 className="mb-12 text-14 font-medium text-gray-600">Default</h3>
+        <div className="flex items-center gap-12">
+          <Button variant="primary" size="default">
+            Primary
+          </Button>
+          <Button variant="default" size="default">
+            Default
+          </Button>
+          <Button variant="secondary" size="default">
+            Secondary
+          </Button>
+          <Button variant="destructive" size="default">
+            Destructive
+          </Button>
+          <Button variant="outline" size="default">
+            Outline
+          </Button>
+          <Button variant="ghost" size="default">
+            Ghost
+          </Button>
+          <Button variant="link" size="default">
+            Link
+          </Button>
+        </div>
+      </div>
+      <div>
+        <h3 className="mb-12 text-14 font-medium text-gray-600">Large</h3>
+        <div className="flex items-center gap-12">
+          <Button variant="primary" size="lg">
+            Primary
+          </Button>
+          <Button variant="default" size="lg">
+            Default
+          </Button>
+          <Button variant="secondary" size="lg">
+            Secondary
+          </Button>
+          <Button variant="destructive" size="lg">
+            Destructive
+          </Button>
+          <Button variant="outline" size="lg">
+            Outline
+          </Button>
+          <Button variant="ghost" size="lg">
+            Ghost
+          </Button>
+          <Button variant="link" size="lg">
+            Link
+          </Button>
+        </div>
+      </div>
+    </div>
+```
+
 
 ## Display
 
@@ -258,7 +334,7 @@ className="font-semibold"        // Font weight 600
         <CardContent>
           <CardBody>
             <CardEyebrow>Optional Eyebrow</CardEyebrow>
-            <div className="flex flex-col gap-[6px]">
+            <div className="flex flex-col gap-6">
               <CardTitle>Card Title</CardTitle>
               <CardDescription>
                 Use cards when citizens need to scan items at a glance, either
@@ -267,10 +343,10 @@ className="font-semibold"        // Font weight 600
             </div>
           </CardBody>
           <CardActions>
-            <Button size="default" variant="charcoal">
+            <Button size="md" variant="primary">
               Primary
             </Button>
-            <Button size="default" variant="charcoalOutline">
+            <Button size="md" variant="primary-outline">
               Secondary
             </Button>
           </CardActions>
@@ -286,7 +362,7 @@ className="font-semibold"        // Font weight 600
         <CardContent>
           <CardBody>
             <CardEyebrow>Optional Eyebrow</CardEyebrow>
-            <div className="flex flex-col gap-[6px]">
+            <div className="flex flex-col gap-6">
               <CardTitle>Card Title</CardTitle>
               <CardDescription>
                 Use cards when citizens need to scan items at a glance, either
@@ -295,10 +371,10 @@ className="font-semibold"        // Font weight 600
             </div>
           </CardBody>
           <CardActions>
-            <Button size="default" variant="charcoal">
+            <Button size="md" variant="primary">
               Primary
             </Button>
-            <Button size="default" variant="charcoalOutline">
+            <Button size="md" variant="primary-outline">
               Secondary
             </Button>
           </CardActions>
@@ -314,7 +390,7 @@ className="font-semibold"        // Font weight 600
         <CardContent>
           <CardBody>
             <CardEyebrow>Eyebrow</CardEyebrow>
-            <div className="flex flex-col gap-[9px]">
+            <div className="flex flex-col gap-8">
               <CardTitle>
                 Cards can support multi line headings easily.
               </CardTitle>
@@ -325,10 +401,10 @@ className="font-semibold"        // Font weight 600
             </div>
           </CardBody>
           <CardActions>
-            <Button size="sm" variant="charcoal">
+            <Button size="sm" variant="primary">
               Primary
             </Button>
-            <Button size="sm" variant="charcoalOutline">
+            <Button size="sm" variant="primary-outline">
               Secondary
             </Button>
           </CardActions>
@@ -343,7 +419,7 @@ className="font-semibold"        // Font weight 600
         <CardContent>
           <CardBody>
             <CardEyebrow>Category</CardEyebrow>
-            <div className="flex flex-col gap-[6px]">
+            <div className="flex flex-col gap-6">
               <CardTitle>Card Without Image</CardTitle>
               <CardDescription>
                 Cards can be used without images for text-focused content.
@@ -351,7 +427,7 @@ className="font-semibold"        // Font weight 600
             </div>
           </CardBody>
           <CardActions>
-            <Button size="default" variant="charcoal">
+            <Button size="md" variant="primary">
               Learn More
             </Button>
           </CardActions>
@@ -366,7 +442,7 @@ className="font-semibold"        // Font weight 600
         <CardImage />
         <CardContent>
           <CardBody>
-            <div className="flex flex-col gap-[6px]">
+            <div className="flex flex-col gap-6">
               <CardTitle>Card Title</CardTitle>
               <CardDescription>
                 The eyebrow is optional and can be omitted when not needed.
@@ -374,7 +450,7 @@ className="font-semibold"        // Font weight 600
             </div>
           </CardBody>
           <CardActions>
-            <Button size="default" variant="charcoal">
+            <Button size="md" variant="primary">
               Primary
             </Button>
           </CardActions>
@@ -390,7 +466,7 @@ className="font-semibold"        // Font weight 600
         <CardContent>
           <CardBody>
             <CardEyebrow>Information</CardEyebrow>
-            <div className="flex flex-col gap-[6px]">
+            <div className="flex flex-col gap-6">
               <CardTitle>Informational Card</CardTitle>
               <CardDescription>
                 Cards without actions can be used for purely informational
@@ -426,7 +502,7 @@ className="font-semibold"        // Font weight 600
           <CardContent>
             <CardBody>
               <CardEyebrow>Category {i}</CardEyebrow>
-              <div className="flex flex-col gap-[6px]">
+              <div className="flex flex-col gap-6">
                 <CardTitle>Card Title {i}</CardTitle>
                 <CardDescription>
                   Brief description of the card content goes here.
@@ -434,7 +510,7 @@ className="font-semibold"        // Font weight 600
               </div>
             </CardBody>
             <CardActions>
-              <Button size="sm" variant="charcoal">
+              <Button size="sm" variant="primary">
                 Action
               </Button>
             </CardActions>
@@ -451,7 +527,7 @@ className="font-semibold"        // Font weight 600
         <CardContent>
           <CardBody>
             <CardEyebrow>Eyebrow</CardEyebrow>
-            <div className="flex flex-col gap-[6px]">
+            <div className="flex flex-col gap-6">
               <CardTitle>Card Title</CardTitle>
               <CardDescription>
                 Use cards when citizens need to scan items at a glance.
@@ -459,10 +535,10 @@ className="font-semibold"        // Font weight 600
             </div>
           </CardBody>
           <CardActions>
-            <Button size="default" variant="charcoal">
+            <Button size="md" variant="primary">
               Primary
             </Button>
-            <Button size="default" variant="charcoalOutline">
+            <Button size="md" variant="primary-outline">
               Secondary
             </Button>
           </CardActions>
@@ -577,7 +653,7 @@ className="font-semibold"        // Font weight 600
 ```
 
 ```tsx
-<div className="bg-bg-page p-spacing-32">
+<div className="bg-bg-page p-32">
       <Hero
         variant="A1"
         title="Rounded Corners"
@@ -607,7 +683,7 @@ className="font-semibold"        // Font weight 600
           </>
         }
       >
-        <p className="mt-spacing-16 max-w-[560px] text-20 text-text-inverted">
+        <p className="mt-16 max-w-[560px] text-20 text-text-inverted">
           A subtitle or description can be added as children
         </p>
       </Hero>
@@ -624,7 +700,7 @@ className="font-semibold"        // Font weight 600
         <h1 className="text-64 font-medium text-text-inverted lg:text-128">
           Custom Layout
         </h1>
-        <p className="mt-spacing-16 text-20 text-text-inverted">
+        <p className="mt-16 text-20 text-text-inverted">
           Using HeroHeader and HeroContent sub-components
         </p>
       </HeroContent>
@@ -1206,11 +1282,7 @@ className="font-semibold"        // Font weight 600
 <Banner
       heading="Custom Styled Banner"
       description="This banner has a custom background color applied via className."
-      action={
-        <Button variant="outline" colorScheme="light">
-          Action
-        </Button>
-      }
+      action={<Button variant="secondary-outline">Action</Button>}
       className="bg-gray-1000 text-gray-50 [&_h2]:text-gray-50 [&_p]:text-gray-200"
     />
 ```
@@ -1813,6 +1885,159 @@ className="font-semibold"        // Font weight 600
 - `visible`: boolean
 
 
+### Input
+
+**Import:** `import { Input } from "@nationaldesignstudio/react";`
+
+**Category:** Other
+
+**Props:**
+
+- `error`: boolean
+  Whether the input is in an error state
+
+**Examples:**
+
+```tsx
+<Input {...args} />
+```
+
+```tsx
+<Input placeholder="Enter text..." />
+```
+
+```tsx
+<Input defaultValue="Filled content" />
+```
+
+```tsx
+<Input error placeholder="Invalid input" />
+```
+
+```tsx
+<Input disabled placeholder="Disabled input" />
+```
+
+```tsx
+<div className="flex flex-col gap-16 max-w-[320px]">
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Default</p>
+      <Input placeholder="Enter text..." />
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Hover (hover the input)</p>
+      <Input placeholder="Hover me..." />
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Focus (click the input)</p>
+      <Input placeholder="Click to focus..." />
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Filled</p>
+      <Input defaultValue="Filled content" />
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Error</p>
+      <Input error placeholder="Invalid input" />
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Disabled</p>
+      <Input disabled placeholder="Disabled input" />
+    </div>
+  </div>
+```
+
+```tsx
+<Input size="sm" placeholder="Small input" />
+```
+
+```tsx
+<Input size="default" placeholder="Default input" />
+```
+
+```tsx
+<Input size="lg" placeholder="Large input" />
+```
+
+```tsx
+<div className="flex flex-col gap-16 max-w-[320px]">
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Small (36px)</p>
+      <Input size="sm" placeholder="Small input" />
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Default (48px)</p>
+      <Input size="default" placeholder="Default input" />
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Large (56px)</p>
+      <Input size="lg" placeholder="Large input" />
+    </div>
+  </div>
+```
+
+```tsx
+<Input type="email" placeholder="Enter your email" />
+```
+
+```tsx
+<Input type="password" placeholder="Enter your password" />
+```
+
+```tsx
+<Input type="number" placeholder="Enter a number" />
+```
+
+```tsx
+<Input type="search" placeholder="Search..." />
+```
+
+```tsx
+<div className="flex flex-col gap-8 max-w-[320px]">
+    <label
+      htmlFor="email-input"
+      className="text-14 font-medium text-text-primary"
+    >
+      Email Address
+    </label>
+    <Input id="email-input" type="email" placeholder="you@example.com" />
+  </div>
+```
+
+```tsx
+<div className="flex flex-col gap-8 max-w-[320px]">
+    <label
+      htmlFor="email-error"
+      className="text-14 font-medium text-text-primary"
+    >
+      Email Address
+    </label>
+    <Input
+      id="email-error"
+      type="email"
+      error
+      placeholder="you@example.com"
+      defaultValue="invalid-email"
+    />
+    <p className="text-12 text-ui-error-color">
+      Please enter a valid email address
+    </p>
+  </div>
+```
+
+```tsx
+<div className="flex flex-col gap-8 max-w-[320px]">
+    <label
+      htmlFor="required-input"
+      className="text-14 font-medium text-text-primary"
+    >
+      Full Name <span className="text-ui-error-color">*</span>
+    </label>
+    <Input id="required-input" required placeholder="John Doe" />
+  </div>
+```
+
+
 ### NdstudioFooter
 
 **Import:** `import { NdstudioFooter } from "@nationaldesignstudio/react";`
@@ -1907,28 +2132,26 @@ className="font-semibold"        // Font weight 600
 ```
 
 ```tsx
-<div className="flex flex-col items-center gap-spacing-24">
+<div className="flex flex-col items-center gap-24">
       <PagerControl
         count={4}
         activeIndex={activeIndex}
         onChange={setActiveIndex}
         autoPlay={false}
       />
-      <div className="flex gap-spacing-10">
+      <div className="flex gap-10">
         <button
           type="button"
           onClick={() => setActiveIndex((prev) => Math.max(0, prev - 1))}
-          className="rounded bg-gray-200 px-spacing-12 py-spacing-6"
+          className="rounded bg-gray-200 px-12 py-6"
         >
           Previous
         </button>
-        <span className="px-spacing-12 py-spacing-6">
-          Page {activeIndex + 1} of 4
-        </span>
+        <span className="px-12 py-6">Page {activeIndex + 1} of 4</span>
         <button
           type="button"
           onClick={() => setActiveIndex((prev) => Math.min(3, prev + 1))}
-          className="rounded bg-gray-200 px-spacing-12 py-spacing-6"
+          className="rounded bg-gray-200 px-12 py-6"
         >
           Next
         </button>
@@ -1937,7 +2160,7 @@ className="font-semibold"        // Font weight 600
 ```
 
 ```tsx
-<div className="flex w-[400px] flex-col gap-spacing-16">
+<div className="flex w-[400px] flex-col gap-16">
       <div className="relative h-[200px] overflow-hidden rounded-radius-12">
         {slides.map((slide, index) => (
           <div
@@ -1966,6 +2189,405 @@ className="font-semibold"        // Font weight 600
 ```
 
 
+### Popover
+
+**Import:** `import { Popover } from "@nationaldesignstudio/react";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: React.ReactNode (required)
+  The content to show in the popover */
+- `trigger`: React.ReactNode (required)
+  The element that triggers the popover */
+- `title`: React.ReactNode
+  Title for the popover (optional) */
+- `side`: "top" | "bottom" | "left" | "right"
+  Side of the trigger to show the popover */
+  Values: `top`, `bottom`, `left`, `right`
+- `sideOffset`: number
+  Offset from the trigger */
+- `align`: "start" | "center" | "end"
+  Alignment along the side */
+  Values: `start`, `center`, `end`
+- `showArrow`: boolean
+  Whether to show an arrow */
+- `showClose`: boolean
+  Whether to show a close button */
+- `open`: boolean
+  Controlled open state */
+- `defaultOpen`: boolean
+  Default open state */
+- `onOpenChange`: (open: boolean) => void
+  Callback when open state changes */
+- `className`: string
+  Additional className for the popup */
+
+**Examples:**
+
+```tsx
+<Popover
+      {...args}
+      trigger={<Button>Click me</Button>}
+      title="Popover Title"
+    >
+      This is the popover content. You can put any content here including text,
+      forms, or other components.
+    </Popover>
+```
+
+```tsx
+<Popover trigger={<Button>Open Popover</Button>} title="Information">
+      This popover provides additional context about the action.
+    </Popover>
+```
+
+```tsx
+<Popover trigger={<Button>Open Popover</Button>}>
+      <p className="typography-body-sm-md">
+        Simple popover content without a title.
+      </p>
+    </Popover>
+```
+
+```tsx
+<Popover
+      trigger={<Button>Open Popover</Button>}
+      title="No Arrow"
+      showArrow={false}
+    >
+      This popover has no arrow pointing to the trigger.
+    </Popover>
+```
+
+```tsx
+<Popover
+      trigger={<Button>Open Popover</Button>}
+      title="Closeable"
+      showClose={true}
+    >
+      Click the X button or click outside to close.
+    </Popover>
+```
+
+```tsx
+<div className="flex flex-col items-center gap-48">
+      <Popover
+        trigger={<Button variant="outline">Top</Button>}
+        side="top"
+        title="Top Position"
+      >
+        Popover above the trigger
+      </Popover>
+      <div className="flex items-center gap-48">
+        <Popover
+          trigger={<Button variant="outline">Left</Button>}
+          side="left"
+          title="Left Position"
+        >
+          Popover to the left
+        </Popover>
+        <Popover
+          trigger={<Button variant="outline">Right</Button>}
+          side="right"
+          title="Right Position"
+        >
+          Popover to the right
+        </Popover>
+      </div>
+      <Popover
+        trigger={<Button variant="outline">Bottom</Button>}
+        side="bottom"
+        title="Bottom Position"
+      >
+        Popover below the trigger
+      </Popover>
+    </div>
+```
+
+```tsx
+<Popover
+      trigger={<Button>Top Position</Button>}
+      side="top"
+      title="Top Popover"
+    >
+      This popover appears above the trigger.
+    </Popover>
+```
+
+```tsx
+<Popover
+      trigger={<Button>Bottom Position</Button>}
+      side="bottom"
+      title="Bottom Popover"
+    >
+      This popover appears below the trigger.
+    </Popover>
+```
+
+```tsx
+<Popover
+      trigger={<Button>Left Position</Button>}
+      side="left"
+      title="Left Popover"
+    >
+      This popover appears to the left.
+    </Popover>
+```
+
+```tsx
+<Popover
+      trigger={<Button>Right Position</Button>}
+      side="right"
+      title="Right Popover"
+    >
+      This popover appears to the right.
+    </Popover>
+```
+
+```tsx
+<div className="flex flex-col gap-24">
+      <div className="flex items-center gap-24">
+        <Popover
+          trigger={
+            <Button variant="secondary" className="w-144">
+              Start
+            </Button>
+          }
+          side="bottom"
+          align="start"
+          title="Start Aligned"
+        >
+          Popover aligned to start
+        </Popover>
+        <Popover
+          trigger={
+            <Button variant="secondary" className="w-144">
+              Center
+            </Button>
+          }
+          side="bottom"
+          align="center"
+          title="Center Aligned"
+        >
+          Popover aligned to center
+        </Popover>
+        <Popover
+          trigger={
+            <Button variant="secondary" className="w-144">
+              End
+            </Button>
+          }
+          side="bottom"
+          align="end"
+          title="End Aligned"
+        >
+          Popover aligned to end
+        </Popover>
+      </div>
+    </div>
+```
+
+```tsx
+<Popover trigger={<Button>Edit Settings</Button>} showClose={true}>
+      <div className="flex flex-col gap-spatial-component-overlay-gap">
+        <h3 className="typography-body-md-md font-semibold">Quick Settings</h3>
+        <div className="flex flex-col gap-8">
+          <label className="typography-body-sm-md">
+            Name
+            <input
+              type="text"
+              placeholder="Enter name"
+              className="mt-4 w-full rounded-surface-ui-small border border-overlay-border bg-overlay-background px-12 py-8 typography-body-sm-md focus:outline-none focus:ring-2 focus:ring-border-focus"
+            />
+          </label>
+          <label className="typography-body-sm-md">
+            Email
+            <input
+              type="email"
+              placeholder="Enter email"
+              className="mt-4 w-full rounded-surface-ui-small border border-overlay-border bg-overlay-background px-12 py-8 typography-body-sm-md focus:outline-none focus:ring-2 focus:ring-border-focus"
+            />
+          </label>
+        </div>
+        <div className="flex justify-end gap-8">
+          <Button variant="secondary" size="sm">
+            Cancel
+          </Button>
+          <Button size="sm">Save</Button>
+        </div>
+      </div>
+    </Popover>
+```
+
+```tsx
+<Popover trigger={<Button variant="outline">Options</Button>}>
+      <div className="flex flex-col gap-4">
+        <button
+          type="button"
+          className="w-full rounded-surface-ui-small px-12 py-8 text-left typography-body-sm-md hover:bg-bg-section"
+        >
+          Edit profile
+        </button>
+        <button
+          type="button"
+          className="w-full rounded-surface-ui-small px-12 py-8 text-left typography-body-sm-md hover:bg-bg-section"
+        >
+          Settings
+        </button>
+        <button
+          type="button"
+          className="w-full rounded-surface-ui-small px-12 py-8 text-left typography-body-sm-md hover:bg-bg-section"
+        >
+          Help & support
+        </button>
+        <hr className="border-overlay-border" />
+        <button
+          type="button"
+          className="w-full rounded-surface-ui-small px-12 py-8 text-left typography-body-sm-md text-button-destructive-bg hover:bg-bg-section"
+        >
+          Sign out
+        </button>
+      </div>
+    </Popover>
+```
+
+```tsx
+<Popover trigger={<Button>View Profile</Button>} showClose={true}>
+      <div className="flex gap-16">
+        <div className="size-48 shrink-0 rounded-full bg-bg-section-secondary" />
+        <div className="flex flex-col gap-4">
+          <h3 className="typography-body-md-md font-semibold">Jane Smith</h3>
+          <p className="typography-body-sm-md text-overlay-text-muted">
+            Product Designer
+          </p>
+          <p className="typography-body-sm-md text-overlay-text-muted">
+            San Francisco, CA
+          </p>
+        </div>
+      </div>
+    </Popover>
+```
+
+```tsx
+<PopoverParts>
+      <PopoverTrigger>
+        <Button variant="primary">Custom Popover</Button>
+      </PopoverTrigger>
+      <PopoverPortal>
+        <PopoverPositioner side="bottom" sideOffset={12}>
+          <PopoverPopup>
+            <PopoverArrow />
+            <PopoverClose>
+              <svg
+                width="12"
+                height="12"
+                viewBox="0 0 12 12"
+                fill="none"
+                aria-hidden="true"
+              >
+                <path
+                  d="M1.5 1.5L10.5 10.5M1.5 10.5L10.5 1.5"
+                  stroke="currentColor"
+                  strokeWidth="1.5"
+                  strokeLinecap="round"
+                />
+              </svg>
+              <span className="sr-only">Close</span>
+            </PopoverClose>
+            <PopoverTitle>Custom Title</PopoverTitle>
+            <PopoverDescription>
+              Built with compound components for maximum flexibility.
+            </PopoverDescription>
+          </PopoverPopup>
+        </PopoverPositioner>
+      </PopoverPortal>
+    </PopoverParts>
+```
+
+```tsx
+<PopoverParts>
+      <PopoverTrigger>
+        <Button>With Backdrop</Button>
+      </PopoverTrigger>
+      <PopoverPortal>
+        <PopoverBackdrop className="bg-alpha-black-20" />
+        <PopoverPositioner side="bottom">
+          <PopoverPopup>
+            <PopoverArrow />
+            <PopoverTitle>Modal-like Popover</PopoverTitle>
+            <PopoverDescription>
+              This popover has a backdrop that dims the background.
+            </PopoverDescription>
+          </PopoverPopup>
+        </PopoverPositioner>
+      </PopoverPortal>
+    </PopoverParts>
+```
+
+```tsx
+<div className="flex flex-col items-center gap-16">
+        <Popover
+          trigger={<Button>Controlled Popover</Button>}
+          title="Controlled"
+          open={open}
+          onOpenChange={setOpen}
+        >
+          This popover is controlled externally.
+        </Popover>
+        <Button variant="outline" onClick={() => setOpen(!open)}>
+          {open ? "Close popover" : "Open popover"}
+        </Button>
+      </div>
+```
+
+```tsx
+<div className="flex items-center gap-24">
+      <Popover trigger={<Button>Button</Button>} title="Button Trigger">
+        Triggered by a button
+      </Popover>
+      <Popover
+        trigger={
+          <button
+            type="button"
+            className="flex size-36 items-center justify-center rounded-surface-ui-small bg-bg-section text-text-primary hover:bg-bg-section-secondary"
+          >
+            <svg
+              className="size-20"
+              fill="none"
+              viewBox="0 0 24 24"
+              stroke="currentColor"
+              aria-hidden="true"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M12 5v.01M12 12v.01M12 19v.01M12 6a1 1 0 110-2 1 1 0 010 2zm0 7a1 1 0 110-2 1 1 0 010 2zm0 7a1 1 0 110-2 1 1 0 010 2z"
+              />
+            </svg>
+            <span className="sr-only">More options</span>
+          </button>
+        }
+        title="Icon Trigger"
+      >
+        Triggered by an icon button
+      </Popover>
+      <Popover
+        trigger={
+          <span className="cursor-pointer border-b border-dashed border-fg-muted text-text-secondary">
+            Click this text
+          </span>
+        }
+        title="Text Trigger"
+      >
+        Triggered by text
+      </Popover>
+    </div>
+```
+
+
 ### QuoteBlock
 
 **Import:** `import { QuoteBlock } from "@nationaldesignstudio/react";`
@@ -2031,7 +2653,7 @@ className="font-semibold"        // Font weight 600
       headline="Text Left, Media Right"
       body="Variant A places the text content on the left (9 columns) and media on the right (15 columns) on desktop viewports. On mobile and tablet, they stack vertically."
       primaryAction={<Button>Primary Action</Button>}
-      secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+      secondaryAction={<Button variant="outline">Secondary</Button>}
       media={<PlaceholderImage />}
     />
 ```
@@ -2042,7 +2664,7 @@ className="font-semibold"        // Font weight 600
       headline="Media Left, Text Right"
       body="Variant B places the media on the left (15 columns) and text content on the right (9 columns) on desktop viewports. On mobile and tablet, they stack vertically with text first."
       primaryAction={<Button>Primary Action</Button>}
-      secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+      secondaryAction={<Button variant="outline">Secondary</Button>}
       media={<PlaceholderImage />}
     />
 ```
@@ -2053,7 +2675,7 @@ className="font-semibold"        // Font weight 600
       headline="Desktop View"
       body="On desktop (lg, 1440px), the content spans 9 columns and the media spans 15 columns in a horizontal layout."
       primaryAction={<Button>Primary</Button>}
-      secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+      secondaryAction={<Button variant="outline">Secondary</Button>}
       media={<PlaceholderImage />}
     />
 ```
@@ -2064,7 +2686,7 @@ className="font-semibold"        // Font weight 600
       headline="Tablet View"
       body="On tablet (md, 768px), the content and media stack vertically with the text above the media."
       primaryAction={<Button>Primary</Button>}
-      secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+      secondaryAction={<Button variant="outline">Secondary</Button>}
       media={<PlaceholderImage />}
     />
 ```
@@ -2076,7 +2698,7 @@ className="font-semibold"        // Font weight 600
       body="On mobile (sm, 320px), content is stacked with smaller button sizing."
       primaryAction={<Button size="sm">Primary</Button>}
       secondaryAction={
-        <Button size="sm" variant="charcoalOutline">
+        <Button size="sm" variant="outline">
           Secondary
         </Button>
       }
@@ -2090,7 +2712,7 @@ className="font-semibold"        // Font weight 600
       headline="Desktop View - Reversed"
       body="Variant B reverses the layout, placing media on the left and content on the right."
       primaryAction={<Button>Primary</Button>}
-      secondaryAction={<Button variant="charcoalOutline">Secondary</Button>}
+      secondaryAction={<Button variant="outline">Secondary</Button>}
       media={<PlaceholderImage />}
     />
 ```
@@ -2138,7 +2760,7 @@ className="font-semibold"        // Font weight 600
       headline="Real World Example"
       body="Rivers work great with actual images, videos, or any media content. The media column is designed to accommodate various aspect ratios."
       primaryAction={<Button>Get Started</Button>}
-      secondaryAction={<Button variant="charcoalOutline">Learn More</Button>}
+      secondaryAction={<Button variant="outline">Learn More</Button>}
       media={
         <img
           src="https://images.unsplash.com/photo-1551434678-e076c223a692?w=800&h=600&fit=crop"
@@ -2150,6 +2772,587 @@ className="font-semibold"        // Font weight 600
 ```
 
 
+### Select
+
+**Import:** `import { Select } from "@nationaldesignstudio/react";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: React.ReactNode (required)
+
+**Examples:**
+
+```tsx
+<Select {...args}>
+      <SelectTrigger placeholder="Select a state..." />
+      <SelectPopup>
+        {states.map((state) => (
+          <SelectOption key={state.value} value={state.value}>
+            {state.label}
+          </SelectOption>
+        ))}
+      </SelectPopup>
+    </Select>
+```
+
+```tsx
+<div className="w-[320px]">
+    <Select>
+      <SelectTrigger placeholder="Select option..." />
+      <SelectPopup>
+        <SelectOption value="option1">Option 1</SelectOption>
+        <SelectOption value="option2">Option 2</SelectOption>
+        <SelectOption value="option3">Option 3</SelectOption>
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="w-[320px]">
+    <Select defaultValue="option2">
+      <SelectTrigger placeholder="Select option..." />
+      <SelectPopup>
+        <SelectOption value="option1">Option 1</SelectOption>
+        <SelectOption value="option2">Option 2</SelectOption>
+        <SelectOption value="option3">Option 3</SelectOption>
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="w-[320px]">
+    <Select disabled>
+      <SelectTrigger placeholder="Select option..." />
+      <SelectPopup>
+        <SelectOption value="option1">Option 1</SelectOption>
+        <SelectOption value="option2">Option 2</SelectOption>
+        <SelectOption value="option3">Option 3</SelectOption>
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="w-[320px]">
+    <Select>
+      <SelectTrigger placeholder="Select option..." error />
+      <SelectPopup>
+        <SelectOption value="option1">Option 1</SelectOption>
+        <SelectOption value="option2">Option 2</SelectOption>
+        <SelectOption value="option3">Option 3</SelectOption>
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="flex flex-col gap-16 max-w-[320px]">
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Default</p>
+      <Select>
+        <SelectTrigger placeholder="Select option..." />
+        <SelectPopup>
+          <SelectOption value="option1">Option 1</SelectOption>
+          <SelectOption value="option2">Option 2</SelectOption>
+          <SelectOption value="option3">Option 3</SelectOption>
+        </SelectPopup>
+      </Select>
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">With Value</p>
+      <Select defaultValue="option2">
+        <SelectTrigger placeholder="Select option..." />
+        <SelectPopup>
+          <SelectOption value="option1">Option 1</SelectOption>
+          <SelectOption value="option2">Option 2</SelectOption>
+          <SelectOption value="option3">Option 3</SelectOption>
+        </SelectPopup>
+      </Select>
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Error</p>
+      <Select>
+        <SelectTrigger placeholder="Select option..." error />
+        <SelectPopup>
+          <SelectOption value="option1">Option 1</SelectOption>
+          <SelectOption value="option2">Option 2</SelectOption>
+          <SelectOption value="option3">Option 3</SelectOption>
+        </SelectPopup>
+      </Select>
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Disabled</p>
+      <Select disabled>
+        <SelectTrigger placeholder="Select option..." />
+        <SelectPopup>
+          <SelectOption value="option1">Option 1</SelectOption>
+          <SelectOption value="option2">Option 2</SelectOption>
+          <SelectOption value="option3">Option 3</SelectOption>
+        </SelectPopup>
+      </Select>
+    </div>
+  </div>
+```
+
+```tsx
+<div className="w-[320px]">
+    <Select>
+      <SelectTrigger size="sm" placeholder="Select option..." />
+      <SelectPopup>
+        <SelectOption value="option1">Option 1</SelectOption>
+        <SelectOption value="option2">Option 2</SelectOption>
+        <SelectOption value="option3">Option 3</SelectOption>
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="w-[320px]">
+    <Select>
+      <SelectTrigger size="default" placeholder="Select option..." />
+      <SelectPopup>
+        <SelectOption value="option1">Option 1</SelectOption>
+        <SelectOption value="option2">Option 2</SelectOption>
+        <SelectOption value="option3">Option 3</SelectOption>
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="w-[320px]">
+    <Select>
+      <SelectTrigger size="lg" placeholder="Select option..." />
+      <SelectPopup>
+        <SelectOption value="option1">Option 1</SelectOption>
+        <SelectOption value="option2">Option 2</SelectOption>
+        <SelectOption value="option3">Option 3</SelectOption>
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="flex flex-col gap-16 max-w-[320px]">
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Small (36px)</p>
+      <Select>
+        <SelectTrigger size="sm" placeholder="Select option..." />
+        <SelectPopup>
+          <SelectOption value="option1">Option 1</SelectOption>
+          <SelectOption value="option2">Option 2</SelectOption>
+          <SelectOption value="option3">Option 3</SelectOption>
+        </SelectPopup>
+      </Select>
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Default (48px)</p>
+      <Select>
+        <SelectTrigger size="default" placeholder="Select option..." />
+        <SelectPopup>
+          <SelectOption value="option1">Option 1</SelectOption>
+          <SelectOption value="option2">Option 2</SelectOption>
+          <SelectOption value="option3">Option 3</SelectOption>
+        </SelectPopup>
+      </Select>
+    </div>
+    <div>
+      <p className="mb-8 text-12 text-text-muted">Large (56px)</p>
+      <Select>
+        <SelectTrigger size="lg" placeholder="Select option..." />
+        <SelectPopup>
+          <SelectOption value="option1">Option 1</SelectOption>
+          <SelectOption value="option2">Option 2</SelectOption>
+          <SelectOption value="option3">Option 3</SelectOption>
+        </SelectPopup>
+      </Select>
+    </div>
+  </div>
+```
+
+```tsx
+<div className="flex flex-col gap-8 max-w-[320px]">
+    <label
+      htmlFor="state-select"
+      className="text-14 font-medium text-text-primary"
+    >
+      State / Territory
+    </label>
+    <Select>
+      <SelectTrigger placeholder="Select a state..." />
+      <SelectPopup>
+        {states.map((state) => (
+          <SelectOption key={state.value} value={state.value}>
+            {state.label}
+          </SelectOption>
+        ))}
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="flex flex-col gap-8 max-w-[320px]">
+    <label
+      htmlFor="state-error"
+      className="text-14 font-medium text-text-primary"
+    >
+      State / Territory
+    </label>
+    <Select>
+      <SelectTrigger placeholder="Select a state..." error />
+      <SelectPopup>
+        {states.map((state) => (
+          <SelectOption key={state.value} value={state.value}>
+            {state.label}
+          </SelectOption>
+        ))}
+      </SelectPopup>
+    </Select>
+    <p className="text-12 text-ui-error-color">Please select a state</p>
+  </div>
+```
+
+```tsx
+<div className="flex flex-col gap-8 max-w-[320px]">
+    <label
+      htmlFor="required-select"
+      className="text-14 font-medium text-text-primary"
+    >
+      State / Territory <span className="text-ui-error-color">*</span>
+    </label>
+    <Select required>
+      <SelectTrigger placeholder="Select a state..." />
+      <SelectPopup>
+        {states.map((state) => (
+          <SelectOption key={state.value} value={state.value}>
+            {state.label}
+          </SelectOption>
+        ))}
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="w-[320px]">
+    <Select>
+      <SelectTrigger placeholder="Select option..." />
+      <SelectPopup>
+        <SelectOption value="option1">Option 1</SelectOption>
+        <SelectOption value="option2" disabled>
+          Option 2 (Disabled)
+        </SelectOption>
+        <SelectOption value="option3">Option 3</SelectOption>
+        <SelectOption value="option4" disabled>
+          Option 4 (Disabled)
+        </SelectOption>
+        <SelectOption value="option5">Option 5</SelectOption>
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="w-[320px]">
+    <Select>
+      <SelectTrigger placeholder="Select a state..." />
+      <SelectPopup>
+        {states.map((state) => (
+          <SelectOption key={state.value} value={state.value}>
+            {state.label}
+          </SelectOption>
+        ))}
+      </SelectPopup>
+    </Select>
+  </div>
+```
+
+```tsx
+<div className="flex flex-col gap-16 max-w-[500px]">
+      <p className="text-14 text-text-muted">
+        Select and Input share the same base styling for consistent forms
+      </p>
+      <div className="flex gap-12">
+        <div className="flex-1">
+          <p className="block mb-8 text-12 text-text-muted">Input</p>
+          <Input placeholder="Enter text..." />
+        </div>
+        <div className="flex-1">
+          <p className="block mb-8 text-12 text-text-muted">Select</p>
+          <Select>
+            <SelectTrigger placeholder="Select option..." />
+            <SelectPopup>
+              <SelectOption value="option1">Option 1</SelectOption>
+              <SelectOption value="option2">Option 2</SelectOption>
+            </SelectPopup>
+          </Select>
+        </div>
+      </div>
+      <div className="flex gap-12">
+        <div className="flex-1">
+          <p className="block mb-8 text-12 text-text-muted">Input (Error)</p>
+          <Input error placeholder="Enter text..." />
+        </div>
+        <div className="flex-1">
+          <p className="block mb-8 text-12 text-text-muted">Select (Error)</p>
+          <Select>
+            <SelectTrigger error placeholder="Select option..." />
+            <SelectPopup>
+              <SelectOption value="option1">Option 1</SelectOption>
+              <SelectOption value="option2">Option 2</SelectOption>
+            </SelectPopup>
+          </Select>
+        </div>
+      </div>
+      <div className="flex gap-12">
+        <div className="flex-1">
+          <p className="block mb-8 text-12 text-text-muted">Input (Disabled)</p>
+          <Input disabled placeholder="Enter text..." />
+        </div>
+        <div className="flex-1">
+          <p className="block mb-8 text-12 text-text-muted">
+            Select (Disabled)
+          </p>
+          <Select disabled>
+            <SelectTrigger placeholder="Select option..." />
+            <SelectPopup>
+              <SelectOption value="option1">Option 1</SelectOption>
+              <SelectOption value="option2">Option 2</SelectOption>
+            </SelectPopup>
+          </Select>
+        </div>
+      </div>
+    </div>
+```
+
+
+### Tooltip
+
+**Import:** `import { Tooltip } from "@nationaldesignstudio/react";`
+
+**Category:** Other
+
+**Props:**
+
+- `content`: React.ReactNode (required)
+  The content to show in the tooltip */
+- `children`: React.ReactNode (required)
+  The element that triggers the tooltip */
+- `side`: "top" | "bottom" | "left" | "right"
+  Side of the trigger to show the tooltip */
+  Values: `top`, `bottom`, `left`, `right`
+- `sideOffset`: number
+  Offset from the trigger */
+- `align`: "start" | "center" | "end"
+  Alignment along the side */
+  Values: `start`, `center`, `end`
+- `delay`: number
+  Delay before showing the tooltip (ms) */
+- `closeDelay`: number
+  Delay before hiding the tooltip (ms) */
+- `showArrow`: boolean
+  Whether to show an arrow */
+- `open`: boolean
+  Controlled open state */
+- `defaultOpen`: boolean
+  Default open state */
+- `onOpenChange`: (open: boolean) => void
+  Callback when open state changes */
+- `className`: string
+  Additional className for the popup */
+
+**Examples:**
+
+```tsx
+<Tooltip {...args} content="This is a tooltip">
+      <Button>Hover me</Button>
+    </Tooltip>
+```
+
+```tsx
+<Tooltip content="Save your changes">
+      <Button>Save</Button>
+    </Tooltip>
+```
+
+```tsx
+<Tooltip content="No arrow here" showArrow={false}>
+      <Button>Hover me</Button>
+    </Tooltip>
+```
+
+```tsx
+<Tooltip content="This is a longer tooltip that provides more detailed information about the element.">
+      <Button>Hover for details</Button>
+    </Tooltip>
+```
+
+```tsx
+<div className="flex flex-col items-center gap-48">
+      <Tooltip content="Top tooltip" side="top">
+        <Button variant="outline">Top</Button>
+      </Tooltip>
+      <div className="flex items-center gap-48">
+        <Tooltip content="Left tooltip" side="left">
+          <Button variant="outline">Left</Button>
+        </Tooltip>
+        <Tooltip content="Right tooltip" side="right">
+          <Button variant="outline">Right</Button>
+        </Tooltip>
+      </div>
+      <Tooltip content="Bottom tooltip" side="bottom">
+        <Button variant="outline">Bottom</Button>
+      </Tooltip>
+    </div>
+```
+
+```tsx
+<Tooltip content="Top position" side="top">
+      <Button>Top</Button>
+    </Tooltip>
+```
+
+```tsx
+<Tooltip content="Bottom position" side="bottom">
+      <Button>Bottom</Button>
+    </Tooltip>
+```
+
+```tsx
+<Tooltip content="Left position" side="left">
+      <Button>Left</Button>
+    </Tooltip>
+```
+
+```tsx
+<Tooltip content="Right position" side="right">
+      <Button>Right</Button>
+    </Tooltip>
+```
+
+```tsx
+<div className="flex flex-col gap-24">
+      <div className="flex items-center gap-24">
+        <Tooltip content="Aligned to start" side="bottom" align="start">
+          <Button variant="secondary" className="w-144">
+            Start
+          </Button>
+        </Tooltip>
+        <Tooltip content="Aligned to center" side="bottom" align="center">
+          <Button variant="secondary" className="w-144">
+            Center
+          </Button>
+        </Tooltip>
+        <Tooltip content="Aligned to end" side="bottom" align="end">
+          <Button variant="secondary" className="w-144">
+            End
+          </Button>
+        </Tooltip>
+      </div>
+    </div>
+```
+
+```tsx
+<Tooltip content="Appears after 1 second" delay={1000}>
+      <Button>1s delay</Button>
+    </Tooltip>
+```
+
+```tsx
+<Tooltip content="Stays visible for 500ms" closeDelay={500}>
+      <Button>Close delay</Button>
+    </Tooltip>
+```
+
+```tsx
+<TooltipProvider delay={300} closeDelay={0}>
+      <div className="flex items-center gap-16">
+        <Tooltip content="First tooltip">
+          <Button variant="outline">First</Button>
+        </Tooltip>
+        <Tooltip content="Second tooltip">
+          <Button variant="outline">Second</Button>
+        </Tooltip>
+        <Tooltip content="Third tooltip">
+          <Button variant="outline">Third</Button>
+        </Tooltip>
+      </div>
+    </TooltipProvider>
+```
+
+```tsx
+<TooltipParts>
+      <TooltipTrigger>
+        <Button variant="primary">Custom Tooltip</Button>
+      </TooltipTrigger>
+      <TooltipPortal>
+        <TooltipPositioner side="bottom" sideOffset={12}>
+          <TooltipPopup>
+            <TooltipArrow />
+            Built with compound components
+          </TooltipPopup>
+        </TooltipPositioner>
+      </TooltipPortal>
+    </TooltipParts>
+```
+
+```tsx
+<div className="flex items-center gap-24">
+      <Tooltip content="Button tooltip">
+        <Button>Button</Button>
+      </Tooltip>
+      <Tooltip content="Icon tooltip">
+        <button
+          type="button"
+          className="flex size-36 items-center justify-center rounded-surface-ui-small bg-bg-section text-text-primary hover:bg-bg-section-secondary"
+        >
+          <svg
+            className="size-20"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            aria-hidden="true"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+            />
+          </svg>
+          <span className="sr-only">Info</span>
+        </button>
+      </Tooltip>
+      <Tooltip content="Text tooltip">
+        <span className="cursor-help border-b border-dashed border-fg-muted text-text-secondary">
+          Hover this text
+        </span>
+      </Tooltip>
+    </div>
+```
+
+```tsx
+<div className="flex flex-col items-center gap-16">
+        <Tooltip
+          content="Controlled tooltip"
+          open={open}
+          onOpenChange={setOpen}
+        >
+          <Button>Hover or click button below</Button>
+        </Tooltip>
+        <Button variant="outline" onClick={() => setOpen(!open)}>
+          {open ? "Close tooltip" : "Open tooltip"}
+        </Button>
+      </div>
+```
+
+
 ### Tout
 
 **Import:** `import { Tout } from "@nationaldesignstudio/react";`
@@ -2184,11 +3387,7 @@ className="font-semibold"        // Font weight 600
       headline="Brand-Large/Headline/Small"
       body="A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action."
       primaryAction={<Button>Primary</Button>}
-      secondaryAction={
-        <Button variant="outline" colorScheme="light">
-          Secondary
-        </Button>
-      }
+      secondaryAction={<Button variant="secondary-outline">Secondary</Button>}
       backgroundMedia={<PlaceholderBackground />}
     />
 ```
@@ -2198,11 +3397,7 @@ className="font-semibold"        // Font weight 600
       headline="Brand-Large/Headline/Small"
       body="A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action."
       primaryAction={<Button>Primary</Button>}
-      secondaryAction={
-        <Button variant="outline" colorScheme="light">
-          Secondary
-        </Button>
-      }
+      secondaryAction={<Button variant="secondary-outline">Secondary</Button>}
       backgroundMedia={<PlaceholderBackground />}
     />
 ```
@@ -2213,7 +3408,7 @@ className="font-semibold"        // Font weight 600
       body="A river pattern stacks content in a simple vertical flow: one clear heading, a short block of copy, then the next step. It's ideal for guiding citizens through a process or story, keeping focus moving straight down the page with minimal choices and well-timed calls to action."
       primaryAction={<Button size="sm">Primary</Button>}
       secondaryAction={
-        <Button size="sm" variant="outline" colorScheme="light">
+        <Button size="sm" variant="secondary-outline">
           Secondary
         </Button>
       }
@@ -2226,11 +3421,7 @@ className="font-semibold"        // Font weight 600
       headline="Work with Purpose"
       body="Join a team that's building the future of government services. We're looking for passionate individuals who want to make a difference."
       primaryAction={<Button>View Careers</Button>}
-      secondaryAction={
-        <Button variant="outline" colorScheme="light">
-          Learn More
-        </Button>
-      }
+      secondaryAction={<Button variant="secondary-outline">Learn More</Button>}
       backgroundMedia={<ImageBackground />}
     />
 ```
@@ -2249,11 +3440,7 @@ className="font-semibold"        // Font weight 600
       headline="Experience Innovation"
       body="See how modern technology is transforming the way government serves its citizens."
       primaryAction={<Button>Watch Video</Button>}
-      secondaryAction={
-        <Button variant="outline" colorScheme="light">
-          Learn More
-        </Button>
-      }
+      secondaryAction={<Button variant="secondary-outline">Learn More</Button>}
       backgroundMedia={
         <div className="absolute inset-0 bg-gray-800 flex items-center justify-center">
           <span className="text-gray-400 typography-body-small">
@@ -2269,11 +3456,7 @@ className="font-semibold"        // Font weight 600
       headline="Work with Purpose"
       body="Join a team that's building the future of government services. We're looking for passionate individuals who want to make a difference."
       primaryAction={<Button>View Careers</Button>}
-      secondaryAction={
-        <Button variant="outline" colorScheme="light">
-          Learn More
-        </Button>
-      }
+      secondaryAction={<Button variant="secondary-outline">Learn More</Button>}
       backgroundMedia={<ImageBackground />}
       footer={<NdstudioFooter />}
     />
@@ -2580,5 +3763,5 @@ className="font-semibold"        // Font weight 600
 - **Action:** Button
 - **Display:** Card, Hero, UsGovBanner
 - **Navigation:** Navbar
-- **Other:** Accordion, Background, Banner, CardGrid, DevToolbar, FaqSection, GridOverlay, NdstudioFooter, PagerControl, QuoteBlock, River, Tout, TwoColumnSection
+- **Other:** Accordion, Background, Banner, CardGrid, DevToolbar, FaqSection, GridOverlay, Input, NdstudioFooter, PagerControl, Popover, QuoteBlock, River, Select, Tooltip, Tout, TwoColumnSection
 - **Typography:** Prose