@nationaldesignstudio/react 0.0.17 → 0.1.0

package/dist/component-registry.md

@@ -1,7 +1,7 @@
 # Component Registry
 
 > Auto-generated component metadata for AI/agent consumption.
-> Generated: 2026-01-08T20:44:48.781Z
+> Generated: 2026-01-12T21:40:10.008Z
 
 ---
 
@@ -35,23 +35,23 @@ className="text-alpha-white-90"
 
 ### Spacing
 
-Spacing tokens use the `spacing-` prefix with utility classes.
+Since `--spacing` is set to `1px`, standard Tailwind spacing utilities work directly with pixel values.
 
 ```tsx
 // Padding - use single p- when all sides are the same
-className="p-spacing-32"      // 32px all sides (PREFERRED)
-className="px-spacing-24"     // 24px horizontal
-className="py-spacing-64"     // 64px vertical
+className="p-32"      // 32px all sides
+className="px-24"     // 24px horizontal
+className="py-64"     // 64px vertical
 
 // Gap
-className="gap-spacing-24"    // 24px gap
+className="gap-24"    // 24px gap
 
 // Margin
-className="m-spacing-16"      // 16px margin
+className="m-16"      // 16px margin
 
 // Width/Height
-className="w-spacing-48"      // 48px width
-className="h-spacing-64"      // 64px height
+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
@@ -97,7 +97,7 @@ className="font-semibold"        // Font weight 600
 
 | Figma CSS Variable | Tailwind Equivalent |
 |-------------------|---------------------|
-| `var(--spacing/24,24px)` | `p-spacing-24` or `gap-spacing-24` |
+| `var(--spacing/24,24px)` | `p-24` or `gap-24` |
 | `var(--font-size/64,64px)` | `text-64` |
 | `var(--color/indigo/900,#...)` | `bg-indigo-900` or `text-indigo-900` |
 | `var(--global/line-height/16,24px)` | `leading-16` |
@@ -108,17 +108,17 @@ className="font-semibold"        // Font weight 600
 |----------------|----------------|
 | Direction: Vertical | `flex flex-col` |
 | Direction: Horizontal | `flex` |
-| Gap | `gap-spacing-{N}` |
+| Gap | `gap-{N}` |
 | Align items: Center | `items-center` |
 | Justify: Space between | `justify-between` |
 
 ### Debugging Tips
 
 1. **Colors not applying?** Use direct names like `bg-indigo-900` (no `color-` prefix)
-2. **Spacing not working?** Use `spacing-` prefix: `gap-spacing-24` (not `gap-24`)
+2. **Spacing:** Use standard Tailwind utilities directly: `gap-24`, `p-32`, `m-16`
 3. **Typography off?** Use composite classes `typography-brand-medium-headline-large`
 4. **Non-token values?** Use arbitrary values: `gap-[10px]`, `py-[18px]`
-5. **Width/Height with tokens?** Use `h-spacing-{size}` and `w-spacing-{size}`
+5. **Width/Height:** Use standard utilities: `h-64`, `w-48`
 
 ---
 
@@ -142,43 +142,86 @@ className="font-semibold"        // Font weight 600
 ```
 
 ```tsx
-<Button variant="primary">Primary</Button>
+<Button variant="solid">Solid</Button>
 ```
 
 ```tsx
-<Button variant="primaryOutline">Primary Outline</Button>
+<Button variant="outline">Outline</Button>
 ```
 
 ```tsx
-<Button variant="secondary">Secondary</Button>
+<Button variant="ghost">Ghost</Button>
 ```
 
 ```tsx
-<Button variant="charcoal">Charcoal</Button>
+<Button variant="subtle">Subtle</Button>
 ```
 
 ```tsx
-<Button variant="charcoalOutline">Charcoal Outline</Button>
+<DarkBackground>
+    <Button variant="solid" colorScheme="light">
+      Solid Light
+    </Button>
+  </DarkBackground>
 ```
 
 ```tsx
-<Button variant="charcoalOutlineQuiet">Charcoal Outline Quiet</Button>
+<DarkBackground>
+    <Button variant="outline" colorScheme="light">
+      Outline Light
+    </Button>
+  </DarkBackground>
 ```
 
 ```tsx
-<Button variant="ivory">Ivory</Button>
+<DarkBackground>
+    <Button variant="ghost" colorScheme="light">
+      Ghost Light
+    </Button>
+  </DarkBackground>
 ```
 
 ```tsx
-<Button variant="ivoryOutline">Ivory Outline</Button>
+<DarkBackground>
+    <Button variant="subtle" colorScheme="light">
+      Subtle Light
+    </Button>
+  </DarkBackground>
 ```
 
 ```tsx
-<Button variant="ivoryOutlineQuiet">Ivory Outline Quiet</Button>
-```
-
-```tsx
-<Button variant="gray">Gray</Button>
+<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>
+    <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
@@ -437,16 +480,20 @@ className="font-semibold"        // Font weight 600
 
 **Props:**
 
-- `title`: string (required)
-  The title text displayed in the hero
+- `title`: string
+  The title text displayed in the hero.
 - `titleClassName`: string
   Custom typography class for the title using primitive tokens.
+- `top`: React.ReactNode
+  Content for the top slot (full-width, no padding).
 - `background`: React.ReactNode | string
   Background for the hero. Can be:
 - `overlayOpacity`: number
   Opacity of the overlay (0-1, default: 0)
 - `overlayColor`: string
   Color of the overlay (default: "black")
+- `borderRadius`: string
+  Border radius for the hero container
 - `theme`: ComponentTheme
   Theme overrides for component styling via CSS custom properties
 
@@ -517,6 +564,70 @@ className="font-semibold"        // Font weight 600
     />
 ```
 
+```tsx
+<Hero
+      variant="A1"
+      title="Hero with Top Slot"
+      background="#1a1a1a"
+      top={<MockBanner />}
+    />
+```
+
+```tsx
+<div className="bg-bg-page p-spacing-32">
+      <Hero
+        variant="A1"
+        title="Rounded Corners"
+        background="#1a1a1a"
+        borderRadius="0 0 20px 20px"
+      />
+    </div>
+```
+
+```tsx
+<div className="bg-bg-page">
+      <Hero
+        variant="A1"
+        title="Full Composition"
+        background={
+          <HeroBackground.Image
+            src="https://images.unsplash.com/photo-1451187580459-43490279c0fa?w=1920&q=80"
+            position="center"
+          />
+        }
+        overlayOpacity={0.5}
+        borderRadius="0 0 20px 20px"
+        top={
+          <>
+            <MockBanner />
+            <MockNavigation />
+          </>
+        }
+      >
+        <p className="mt-spacing-16 max-w-[560px] text-20 text-text-inverted">
+          A subtitle or description can be added as children
+        </p>
+      </Hero>
+    </div>
+```
+
+```tsx
+<section className="relative flex min-h-[80vh] flex-col bg-gray-1200">
+      <HeroHeader>
+        <MockBanner />
+        <MockNavigation />
+      </HeroHeader>
+      <HeroContent className="flex-1 justify-end">
+        <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">
+          Using HeroHeader and HeroContent sub-components
+        </p>
+      </HeroContent>
+    </section>
+```
+
 ```tsx
 <Hero variant="A1" title="Hero A1" />
 ```
@@ -1013,6 +1124,13 @@ className="font-semibold"        // Font weight 600
 ```
 
 
+### Background
+
+**Import:** `import { Background } from "@nationaldesignstudio/react";`
+
+**Category:** Other
+
+
 ### Banner
 
 **Import:** `import { Banner } from "@nationaldesignstudio/react";`
@@ -1841,6 +1959,40 @@ className="font-semibold"        // Font weight 600
 ```
 
 
+### QuoteBlock
+
+**Import:** `import { QuoteBlock } from "@nationaldesignstudio/react";`
+
+**Category:** Other
+
+**Props:**
+
+- `quote`: string (required)
+  The quote text to display
+- `showQuoteMarks`: boolean
+  true
+- `signatureImage`: string
+  Signature image URL (optional)
+- `signatureAlt`: string
+  Alt text for signature image
+- `attributionName`: string
+  Attribution name (e.g., "Donald J. Trump")
+- `attributionTitle`: string
+  Attribution title (e.g., "45 & 47 President of the United States")
+- `background`: React.ReactNode
+  Background element - use BackgroundImage or similar
+- `overlayOpacity`: number
+  Overlay opacity (0-1)
+- `overlayColor`: string
+  Overlay color
+- `quoteClassName`: string
+  Custom class for the quote text
+- `bylineNameClassName`: string
+  Custom class for the byline name
+- `bylineTitleClassName`: string
+  Custom class for the byline title
+
+
 ### River
 
 **Import:** `import { River } from "@nationaldesignstudio/react";`
@@ -2401,5 +2553,5 @@ className="font-semibold"        // Font weight 600
 - **Action:** Button
 - **Display:** Card, Hero, UsGovBanner
 - **Navigation:** Navbar
-- **Other:** Accordion, Banner, CardGrid, DevToolbar, FaqSection, GridOverlay, NdstudioFooter, PagerControl, River, Tout, TwoColumnSection
+- **Other:** Accordion, Background, Banner, CardGrid, DevToolbar, FaqSection, GridOverlay, NdstudioFooter, PagerControl, QuoteBlock, River, Tout, TwoColumnSection
 - **Typography:** Prose

package/dist/components/atoms/accordion/accordion.d.ts

@@ -53,8 +53,8 @@ export interface AccordionProps extends React.HTMLAttributes<HTMLDivElement>, Va
  * Built on Base UI's Accordion primitive.
  *
  * Variants:
- * - dark: Dark theme styling (default)
- * - light: Light theme styling
+ * - light: Light theme styling (default)
+ * - dark: Dark theme styling
  *
  * @example
  * ```tsx

package/dist/components/atoms/background/background.d.ts

@@ -0,0 +1,158 @@
+import * as React from "react";
+declare const backgroundVariants: import('tailwind-variants').TVReturnType<{} | {} | {}, undefined, "absolute inset-0", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, {} | {}, undefined, import('tailwind-variants').TVReturnType<unknown, undefined, "absolute inset-0", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, unknown, unknown, undefined>>;
+/**
+ * Base container for background composition.
+ * Use as a wrapper to compose multiple background layers (image, video, overlay, gradient).
+ *
+ * @example
+ * ```tsx
+ * <Background>
+ *   <Background.Image src="/hero.jpg" />
+ *   <Background.Overlay opacity={0.4} />
+ *   <Background.Gradient direction="to-t" from="black" to="transparent" />
+ * </Background>
+ * ```
+ */
+export interface BackgroundProps extends React.HTMLAttributes<HTMLDivElement> {
+}
+declare const backgroundImageVariants: import('tailwind-variants').TVReturnType<{} | {} | {}, undefined, "absolute inset-0 size-full object-cover", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, {} | {}, undefined, import('tailwind-variants').TVReturnType<unknown, undefined, "absolute inset-0 size-full object-cover", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, unknown, unknown, undefined>>;
+export interface BackgroundImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src"> {
+    /**
+     * URL for the background image
+     */
+    src: string;
+    /**
+     * Object position (default: "center")
+     */
+    position?: string;
+    /**
+     * Custom render prop for element composition.
+     * Accepts a React element or render function.
+     * @example
+     * ```tsx
+     * // Element pattern
+     * <BackgroundImage render={<img className="custom" />} src="/bg.jpg" />
+     *
+     * // Callback pattern
+     * <BackgroundImage render={(props) => <img {...props} />} src="/bg.jpg" />
+     * ```
+     */
+    render?: React.ReactElement | ((props: React.ImgHTMLAttributes<HTMLImageElement>) => React.ReactElement);
+}
+/**
+ * Background image layer using an actual img element with object-cover.
+ * Supports native lazy loading, srcset, and better accessibility.
+ * Supports render prop for element composition.
+ */
+declare const BackgroundImage: React.ForwardRefExoticComponent<BackgroundImageProps & React.RefAttributes<HTMLImageElement>>;
+declare const backgroundVideoVariants: import('tailwind-variants').TVReturnType<{} | {} | {}, undefined, "absolute inset-0 size-full object-cover", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, {} | {}, undefined, import('tailwind-variants').TVReturnType<unknown, undefined, "absolute inset-0 size-full object-cover", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, unknown, unknown, undefined>>;
+export interface BackgroundVideoProps extends Omit<React.VideoHTMLAttributes<HTMLVideoElement>, "children"> {
+    /**
+     * URL for the video source
+     */
+    src: string;
+    /**
+     * Video MIME type (default: auto-detected from src)
+     */
+    type?: string;
+    /**
+     * Poster image URL shown before video loads
+     */
+    poster?: string;
+    /**
+     * Custom render prop for element composition.
+     * @example
+     * ```tsx
+     * <BackgroundVideo render={<video className="custom" />} src="/bg.mp4" />
+     * ```
+     */
+    render?: React.ReactElement | ((props: React.VideoHTMLAttributes<HTMLVideoElement>) => React.ReactElement);
+}
+/**
+ * Background video layer using HTML5 video element.
+ * Supports render prop for element composition.
+ */
+declare const BackgroundVideo: React.ForwardRefExoticComponent<BackgroundVideoProps & React.RefAttributes<HTMLVideoElement>>;
+declare const backgroundStreamVariants: import('tailwind-variants').TVReturnType<{} | {} | {}, undefined, "absolute inset-0 size-full border-0 scale-[1.5] object-cover", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, {} | {}, undefined, import('tailwind-variants').TVReturnType<unknown, undefined, "absolute inset-0 size-full border-0 scale-[1.5] object-cover", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, unknown, unknown, undefined>>;
+export interface BackgroundStreamProps extends React.IframeHTMLAttributes<HTMLIFrameElement> {
+    /**
+     * Cloudflare Stream video ID
+     */
+    videoId: string;
+    /**
+     * Poster image URL (Cloudflare Stream thumbnail or custom)
+     */
+    poster?: string;
+    /**
+     * Whether the video should autoplay (default: true)
+     */
+    autoplay?: boolean;
+    /**
+     * Whether the video should loop (default: true)
+     */
+    loop?: boolean;
+    /**
+     * Whether the video should be muted (default: true)
+     */
+    muted?: boolean;
+    /**
+     * Whether to show playback controls (default: false)
+     */
+    controls?: boolean;
+    /**
+     * Custom Cloudflare customer subdomain (if using custom domains)
+     */
+    customerSubdomain?: string;
+}
+/**
+ * Background video layer using Cloudflare Stream.
+ */
+declare const BackgroundStream: React.ForwardRefExoticComponent<BackgroundStreamProps & React.RefAttributes<HTMLIFrameElement>>;
+declare const backgroundOverlayVariants: import('tailwind-variants').TVReturnType<{} | {} | {}, undefined, "absolute inset-0 bg-bg-overlay", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, {} | {}, undefined, import('tailwind-variants').TVReturnType<unknown, undefined, "absolute inset-0 bg-bg-overlay", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, unknown, unknown, undefined>>;
+export interface BackgroundOverlayProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Overlay opacity (0-1)
+     */
+    opacity?: number;
+}
+/**
+ * Solid color overlay layer. Uses semantic bg-overlay token by default.
+ * Override with className for different colors.
+ */
+declare const BackgroundOverlay: React.ForwardRefExoticComponent<BackgroundOverlayProps & React.RefAttributes<HTMLDivElement>>;
+declare const backgroundGradientVariants: import('tailwind-variants').TVReturnType<{} | {} | {}, undefined, "absolute inset-0", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, {} | {}, undefined, import('tailwind-variants').TVReturnType<unknown, undefined, "absolute inset-0", import('tailwind-variants/dist/config.js').TVConfig<unknown, {} | {}>, unknown, unknown, undefined>>;
+export interface BackgroundGradientProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Gradient direction (Tailwind convention: to-t, to-b, to-l, to-r, etc.)
+     * Or CSS gradient direction (to top, to bottom, 45deg, etc.)
+     */
+    direction?: string;
+    /**
+     * Starting color (from)
+     */
+    from?: string;
+    /**
+     * Optional middle color (via)
+     */
+    via?: string;
+    /**
+     * Ending color (to)
+     */
+    to?: string;
+    /**
+     * Full custom gradient string (overrides from/via/to)
+     */
+    gradient?: string;
+}
+/**
+ * Gradient overlay layer. Use for fading backgrounds or creating depth.
+ */
+declare const BackgroundGradient: React.ForwardRefExoticComponent<BackgroundGradientProps & React.RefAttributes<HTMLDivElement>>;
+declare const BackgroundCompound: React.ForwardRefExoticComponent<BackgroundProps & React.RefAttributes<HTMLDivElement>> & {
+    Image: React.ForwardRefExoticComponent<BackgroundImageProps & React.RefAttributes<HTMLImageElement>>;
+    Video: React.ForwardRefExoticComponent<BackgroundVideoProps & React.RefAttributes<HTMLVideoElement>>;
+    Stream: React.ForwardRefExoticComponent<BackgroundStreamProps & React.RefAttributes<HTMLIFrameElement>>;
+    Overlay: React.ForwardRefExoticComponent<BackgroundOverlayProps & React.RefAttributes<HTMLDivElement>>;
+    Gradient: React.ForwardRefExoticComponent<BackgroundGradientProps & React.RefAttributes<HTMLDivElement>>;
+};
+export { BackgroundCompound as Background, BackgroundImage, BackgroundVideo, BackgroundStream, BackgroundOverlay, BackgroundGradient, backgroundVariants, backgroundImageVariants, backgroundVideoVariants, backgroundStreamVariants, backgroundOverlayVariants, backgroundGradientVariants, };