# @roadlittledawn/docs-design-system-react

> React components for documentation content and MDX-driven sites.

## Resources

- [npm package](https://www.npmjs.com/package/@roadlittledawn/docs-design-system-react)
- [GitHub](https://github.com/roadlittledawn/docs-design-system/tree/HEAD/packages/react)
- [Storybook](https://docs-design-system-storybook.netlify.app)

## Component Reference

---

## Button

The Button component provides a consistent way to trigger actions across your documentation.

### Import

```tsx
import { Button } from '@roadlittledawn/docs-design-system-react';
```

### Props

Extends `React.ButtonHTMLAttributes<HTMLButtonElement>`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `"primary" \| "secondary" \| "outline"` | `"primary"` | Visual style variant of the button |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the button |
| `children` | `React.ReactNode` | — | Button content |
| `disabled` | `boolean` | `false` | Whether the button is disabled (inherited from `ButtonHTMLAttributes`) |
| `className` | `string` | `""` | Additional CSS classes |

### Examples

#### Basic

```tsx
<Button variant="primary">Primary Button</Button>
<Button variant="secondary">Secondary Button</Button>
<Button variant="outline">Outline Button</Button>
```

#### Sizes

```tsx
<Button variant="primary" size="sm">Small</Button>
<Button variant="primary" size="md">Medium</Button>
<Button variant="primary" size="lg">Large</Button>
```

---

## Card

The Card component provides a flexible container for displaying content with visual hierarchy.

### Import

```tsx
import { Card } from '@roadlittledawn/docs-design-system-react';
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Optional title displayed at the top of the card |
| `titleColor` | `"blue" \| "green" \| "purple" \| "red" \| "yellow" \| "gray"` | `"gray"` | Color of the title text |
| `backgroundColor` | `"blue" \| "green" \| "purple" \| "red" \| "yellow" \| "gray" \| "white"` | `"white"` | Background color of the card |
| `href` | `string` | — | Optional link URL. When provided, the entire card becomes clickable |
| `icon` | `ReactNode` | — | Optional icon to display. Pass a rendered icon component. In MDX, the consuming site's component map resolves string names to rendered components before passing here. |
| `iconPlacement` | `"left" \| "top-left" \| "top-center"` | `"top-left"` | Where to place the icon: vertically centered on the left, above content flush left, or above content centered |
| `showArrow` | `boolean` | `false` | Show an animated arrow in the lower-right corner to signal the card is navigable. Best used with `href`. |
| `children` | `ReactNode` | — | Card content |
| `className` | `string` | `""` | Additional CSS classes |

### Examples

#### Basic

```tsx
<Card title="Getting Started">
  Learn the basics of using this documentation system.
</Card>
```

#### Clickable card with animated arrow

```tsx
<Card title="Get Started" href="/docs/quickstart" showArrow>
  Follow the quickstart guide to set up in minutes.
</Card>
```

#### Card with icon

```tsx
{/* Icon left — vertically centered beside content */}
<Card title="Documentation" icon={<YourIcon />} iconPlacement="left">
  Read guides, tutorials, and API references.
</Card>

{/* Icon top-center — centered above title and content */}
<Card title="Documentation" icon={<YourIcon />} iconPlacement="top-center">
  Read guides, tutorials, and API references.
</Card>
```

#### Colored background

```tsx
<Card title="New Feature" titleColor="blue" backgroundColor="blue">
  Check out our latest component additions.
</Card>
```

#### Icon usage in MDX

In MDX files the `icon` prop is typically a string name (`icon="book"`). The consuming site's MDX component map resolves strings to rendered icon components:

```tsx
Card: ({ icon, ...props }) => {
  const IconComp = typeof icon === 'string' ? iconMap[icon] : null;
  return <DdsCard icon={IconComp ? <IconComp /> : icon} {...props} />;
}
```

---

## CardGrid

The CardGrid component provides a responsive grid layout for displaying multiple cards.

### Import

```tsx
import { CardGrid } from '@roadlittledawn/docs-design-system-react';
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `2 \| 3 \| 4` | `3` | Number of columns in the grid |
| `equalHeight` | `boolean` | `true` | When true, all cards in each row expand to the height of the tallest card |
| `children` | `ReactNode` | — | Grid content (typically Card components) |
| `className` | `string` | `""` | Additional CSS classes |

### Examples

#### Basic

```tsx
<CardGrid columns={3}>
  <Card title="Tutorials">Step-by-step learning guides.</Card>
  <Card title="How-To Guides">Task-oriented instructions.</Card>
  <Card title="Reference">Technical reference documentation.</Card>
</CardGrid>
```

---

## Callout

The Callout component draws attention to important information within documentation pages.

### Import

```tsx
import { Callout } from '@roadlittledawn/docs-design-system-react';
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `"caution" \| "important" \| "tip" \| "course"` | — | Visual style variant that sets the color and icon |
| `title` | `string \| null` | Variant name | Optional title. Pass `null` to hide entirely |
| `children` | `ReactNode` | — | Callout content |
| `className` | `string` | `""` | Additional CSS classes |

### Examples

#### Caution

```tsx
<Callout variant="caution">
  This operation cannot be undone. Make sure you have a backup before proceeding.
</Callout>
```

#### Tip with custom title

```tsx
<Callout variant="tip" title="Pro Tip">
  You can use keyboard shortcuts (Cmd+K or Ctrl+K) to quickly search.
</Callout>
```

---

## Heading

The Heading component provides semantic HTML headings (h1–h4) with consistent styling and auto-generated IDs.

### Import

```tsx
import { Heading } from '@roadlittledawn/docs-design-system-react';
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `level` | `1 \| 2 \| 3 \| 4` | — | Heading level — renders as `<h1>` through `<h4>` |
| `id` | `string` | auto-generated from text | Override the auto-generated `id` attribute |
| `children` | `React.ReactNode` | — | Heading content |
| `className` | `string` | `""` | Additional CSS classes |

### Examples

#### Basic

```tsx
<Heading level={1}>Page Title</Heading>
<Heading level={2}>Section Title</Heading>
<Heading level={3}>Subsection Title</Heading>
<Heading level={4}>Sub-subsection Title</Heading>
```

---

## Typography

The Typography component renders text with predefined styles for consistency.

### Import

```tsx
import { Typography } from '@roadlittledawn/docs-design-system-react';
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `"h1" \| "h2" \| "h3" \| "h4" \| "p" \| "caption"` | `"p"` | Typography style variant. `h1`–`h4` render as heading elements; `p` and `caption` render as `<p>` |
| `children` | `React.ReactNode` | — | Text content |
| `className` | `string` | `""` | Additional CSS classes |

### Examples

#### Basic

```tsx
<Typography variant="h1">Heading 1 Style</Typography>
<Typography variant="p">This is a paragraph with the default typography style.</Typography>
<Typography variant="caption">Caption text for figure captions.</Typography>
```

---

## Link

The Link component provides consistent link styling and automatically handles external links.

### Import

```tsx
import { Link } from '@roadlittledawn/docs-design-system-react';
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `href` | `string` | — | URL to link to. External links (starting with `http://` or `https://`) open in a new tab with an external link icon |
| `children` | `React.ReactNode` | — | Link content (optional in types, but required for accessible usage) |
| `className` | `string` | `""` | Additional CSS classes |

### Examples

#### Internal link

```tsx
<Link href="/docs/components">View Components Documentation</Link>
```

#### External link (opens in new tab)

```tsx
<Link href="https://github.com/roadlittledawn/docs-design-system">View on GitHub</Link>
```

---

## List

A visually enhanced list component with numbered badges (ordered) or custom bullets (unordered) and connector lines.

### Import

```tsx
import { List } from '@roadlittledawn/docs-design-system-react';
```

### List Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | `List.Item` components to render |
| `className` | `string` | `""` | Additional CSS classes |
| `ordered` | `boolean` | `true` | Whether the list is ordered (numbered) or unordered (bullets) |
| `bullet` | `string` | — | Custom bullet character for unordered lists (e.g. `"✅"`). Only applies when `ordered` is false |
| `bulletIcon` | `ReactNode` | — | Custom bullet icon (React node). Takes precedence over `bullet`. Only applies when `ordered` is false |

### List.Item Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | List item content |
| `className` | `string` | `""` | Additional CSS classes |

### Examples

#### Ordered list

```tsx
<List>
  <List.Item>Run <code>npm install</code></List.Item>
  <List.Item>Configure your project settings.</List.Item>
  <List.Item>Start the development server.</List.Item>
</List>
```

#### Unordered list with emoji bullet

```tsx
<List ordered={false} bullet="✅">
  <List.Item>Beautifully designed components</List.Item>
  <List.Item>Accessible by default</List.Item>
</List>
```

---

## CodeBlock

The CodeBlock component provides syntax highlighting, copy functionality, and support for multiple tabs and languages.

### Import

```tsx
import { CodeBlock } from '@roadlittledawn/docs-design-system-react';
```

### CodeBlock Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `code` | `string` | — | Single code snippet string. Use `snippets` for multi-tab or multi-language layouts |
| `language` | `string` | — | Language for syntax highlighting (e.g. `"typescript"`, `"bash"`, `"python"`) |
| `filename` | `string` | — | Optional filename label shown in the header when there is only one snippet |
| `highlightLines` | `number[]` | — | Array of 1-indexed line numbers to highlight |
| `snippets` | `CodeSnippet[]` | — | Array of code snippets for multi-tab or multi-language display. Takes precedence over `code` |
| `path` | `string` | — | URL or path to a markdown file containing fenced code blocks to load as snippets |
| `className` | `string` | `""` | Additional CSS classes applied to the outer container |

### CodeSnippet Type

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `code` | `string` | — | The code content |
| `language` | `string` | — | Language for syntax highlighting |
| `filename` | `string` | — | Optional filename to display |
| `tabTitle` | `string` | — | Optional tab title (defaults to filename if not provided) |
| `highlightLines` | `number[]` | — | Optional line numbers to highlight (1-indexed) |

### Supported languages (bundled)

JavaScript, TypeScript, JSX, TSX, CSS, Markdown, JSON, Bash, Ruby, Python, Java, SQL, YAML, PHP.

For additional languages, use `registerLanguages`:

```ts
import { registerLanguages } from '@roadlittledawn/docs-design-system-react';

await registerLanguages(async () => {
  await import('prismjs/components/prism-go');
});
```

### Examples

#### Basic

```tsx
<CodeBlock language="typescript" code={`function greet(name: string) { return \`Hello, \${name}!\`; }`} />
```

#### Multiple tabs

```tsx
<CodeBlock
  snippets={[
    { code: `export const Button = () => <button>Click</button>;`, language: 'jsx', tabTitle: 'Button.jsx' },
    { code: `.button { padding: 0.5rem 1rem; }`, language: 'css', tabTitle: 'Button.css' },
  ]}
/>
```

---

## Tabs

Tabs organize and segment related content, reducing cognitive load by allowing users to toggle between views.

### Import

```tsx
import { Tabs, TabList, Tab, TabPanel } from '@roadlittledawn/docs-design-system-react';
```

### Tabs Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `defaultActiveTab` | `string` | — | ID of the tab that is active by default (uncontrolled mode) |
| `activeTab` | `string` | — | Controlled active tab ID. Use with `onTabChange` to manage state externally |
| `onTabChange` | `(id: string) => void` | — | Callback fired when the active tab changes |
| `children` | `React.ReactNode` | — | Tab content — typically `TabList` and `TabPanel` components |
| `className` | `string` | `""` | Additional CSS classes applied to the outer container |

### Tab Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | — | Unique identifier for this tab |
| `children` | `React.ReactNode` | — | Tab label |
| `className` | `string` | `""` | Additional CSS classes |

### TabPanel Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | — | ID matching the corresponding Tab |
| `children` | `React.ReactNode` | — | Panel content |
| `className` | `string` | `""` | Additional CSS classes |

### Examples

#### Basic

```tsx
<Tabs defaultActiveTab="overview">
  <TabList>
    <Tab id="overview">Overview</Tab>
    <Tab id="usage">Usage</Tab>
  </TabList>
  <TabPanel id="overview"><p>Overview content.</p></TabPanel>
  <TabPanel id="usage"><p>Usage content.</p></TabPanel>
</Tabs>
```

---

## Collapser

The Collapser component allows users to show and hide content sections to reduce visual clutter. Content height adjusts automatically to fit all children, including images and other media that load asynchronously.

### Import

```tsx
import { Collapser } from '@roadlittledawn/docs-design-system-react';
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string \| ReactNode` | — | Title text or element displayed in the collapsible header |
| `id` | `string` | — | Optional ID for the title element (useful for anchor links) |
| `defaultOpen` | `boolean` | `false` | Whether the collapser should be open by default (uncontrolled) |
| `open` | `boolean` | — | Controlled open state (used by CollapserGroup) |
| `onToggle` | `() => void` | — | Callback when toggle is clicked (used by CollapserGroup) |
| `children` | `ReactNode` | — | Content to show/hide when toggling |
| `className` | `string` | `""` | Additional CSS classes |
| `align` | `"left" \| "right"` | `"left"` | Alignment of the title within the header |
| `icon` | `ReactNode` | — | Optional icon rendered on the left side of the header |
| `stepNumber` | `number` | — | Numeric step label shown on the far left. Auto-injected by `CollapserGroup` when `numbered` is true |

### Examples

#### Basic

```tsx
<Collapser title="Click to expand">
  <p>This content is hidden by default.</p>
</Collapser>
```

---

## CollapserGroup

CollapserGroup provides a container for multiple Collapser components with built-in spacing and optional accordion behavior.

### Import

```tsx
import { CollapserGroup, Collapser } from '@roadlittledawn/docs-design-system-react';
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | — | Collapser components to render inside the group |
| `spacing` | `string` | `"0.5rem"` | CSS gap value between collapser items |
| `allowMultiple` | `boolean` | `true` | Allow multiple collapsers to be open simultaneously. When false, opening one closes the others (accordion mode) |
| `defaultOpen` | `number \| number[]` | — | Index or array of indexes of collapsers that should be open by default |
| `onChange` | `(openIndexes: number[]) => void` | — | Callback fired when the open state changes |
| `className` | `string` | `""` | Additional CSS classes |
| `numbered` | `boolean` | `false` | Automatically prefix each collapser header with a sequential step number (1, 2, 3…). Works in MDX and component-map contexts. |

### Examples

#### FAQ (accordion mode)

```tsx
<CollapserGroup allowMultiple={false}>
  <Collapser title="What is this documentation system?">
    <p>A comprehensive design system for documentation sites.</p>
  </Collapser>
  <Collapser title="How do I get started?">
    <p>Install the package and explore the components.</p>
  </Collapser>
</CollapserGroup>
```

---

## Popover

A hover/tap-activated popover for enriching inline content in documentation. Built on the native Popover API.

### Import

```tsx
import { Popover } from '@roadlittledawn/docs-design-system-react';
```

### Popover Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `content` | `ReactNode` | — | Arbitrary React content inside the popover |
| `glossary` | `GlossaryData` | — | Renders a styled glossary definition popover |
| `preview` | `PreviewData` | — | Renders a Wikipedia-style content preview |
| `placement` | `"auto" \| "top" \| "top-start" \| "top-end" \| "bottom" \| "bottom-start" \| "bottom-end"` | `"auto"` | Preferred placement relative to the trigger |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Popover width — `sm`=240px, `md`=320px, `lg`=480px |
| `showDelay` | `number` | `200` | Milliseconds before showing on hover |
| `hideDelay` | `number` | `150` | Milliseconds before hiding on hover-out |
| `children` | `ReactNode` | — | The trigger element — the text or content that reveals the popover |
| `className` | `string` | `""` | Additional CSS classes on the trigger wrapper |

### GlossaryData Type

| Prop | Type | Description |
|------|------|-------------|
| `term` | `string` | The canonical term |
| `title` | `string` | Display title shown in the popover header |
| `definition` | `ReactNode` | Definition content |

### PreviewData Type

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Page or article title |
| `excerpt` | `ReactNode` | — | Short excerpt or summary |
| `imageUrl` | `string` | — | Optional featured image URL |
| `href` | `string` | — | Optional URL to the full content |
| `linkText` | `string` | `"Read more"` | Link text |

### Examples

#### Glossary definition

```tsx
<Popover
  glossary={{
    term: "observability",
    title: "Observability",
    definition: "The ability to understand the internal state of a system by examining its external outputs.",
  }}
>
  observability
</Popover>
```

---

## Grid and Column

Layout primitive for multi-column documentation content.

### Import

```tsx
import { Grid, Column } from '@roadlittledawn/docs-design-system-react';
```

### Grid Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `number \| number[]` | `2` | Number of equal columns, or an array of fractional widths (e.g. `[1, 2]` for 1/3 + 2/3) |
| `gap` | `string` | `"md"` | Space between columns. Use `"sm"`, `"md"`, or `"lg"` for design tokens, or any CSS length (e.g. `"16px"`) |
| `stackAt` | `"sm" \| "md" \| "lg" \| "never"` | `"md"` | Breakpoint at which columns collapse to a single vertical stack |
| `columnDivider` | `BorderConfig` | — | Vertical dividing line between columns |
| `topBorder` | `BorderConfig` | — | Horizontal rule above the grid |
| `bottomBorder` | `BorderConfig` | — | Horizontal rule below the grid |
| `align` | `"start" \| "center" \| "end" \| "stretch"` | `"stretch"` | Vertical alignment of content in each column |
| `backgroundColor` | `string` | — | Background color of the grid container |
| `className` | `string` | `""` | Additional CSS classes |
| `children` | `ReactNode` | — | Grid content — typically `Column` components |

### Column Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `span` | `number` | `1` | How many grid columns this item should span |
| `sticky` | `boolean` | `false` | Makes the column sticky while adjacent columns scroll |
| `backgroundColor` | `string` | — | Background color applied to the column |
| `className` | `string` | `""` | Additional CSS classes |
| `children` | `ReactNode` | — | Column content |

### BorderConfig Type

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `thickness` | `number` | `1` | Line thickness in pixels |
| `color` | `string` | — | Line color (defaults to the `--dds-grid-divider-color` token) |

### Examples

#### Two equal columns

```tsx
<Grid columns={2}>
  <Column>Column 1 content</Column>
  <Column>Column 2 content</Column>
</Grid>
```

#### Tutorial with sticky code panel

```tsx
<Grid columns={2} stackAt="lg" gap="lg" columnDivider={{ thickness: 2 }}>
  <Column>
    <p>Step-by-step instructions here.</p>
  </Column>
  <Column sticky>
    <CodeBlock language="bash" code="npm install" />
  </Column>
</Grid>
```

---

## Table

Table displays structured, relational data in rows and columns.

### Import

```tsx
import {
  Table,
  TableHead,
  TableBody,
  TableRow,
  TableHeaderCell,
  TableCell,
} from '@roadlittledawn/docs-design-system-react';
```

### Table Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | — | Typically `TableHead` and `TableBody` |
| `variant` | `"default" \| "borderless"` | `"default"` | `"default"` renders all borders; `"borderless"` shows only row top/bottom borders |
| `stickyHeader` | `boolean` | `false` | Pin thead to top of the scroll container while scrolling. Use with `style={{ maxHeight: '...' }}` |
| `headerBg` | `string` | — | Background color for the header row |
| `onSort` | `(key: string, direction: "asc" \| "desc" \| null) => void` | — | Callback for server-side sorting |
| `className` | `string` | `""` | Additional CSS classes |
| `style` | `React.CSSProperties` | — | Inline styles; use `maxHeight` with `stickyHeader` |

### TableHeaderCell Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | — | Cell content / column label |
| `sortKey` | `string` | — | Unique key for this column. When provided the column becomes sortable |
| `align` | `"left" \| "center" \| "right"` | `"left"` | Text alignment |
| `className` | `string` | `""` | Additional CSS classes |

### TableCell Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | — | Cell content |
| `align` | `"left" \| "center" \| "right"` | `"left"` | Text alignment |
| `className` | `string` | `""` | Additional CSS classes |

### Examples

#### Basic table

```tsx
<Table>
  <TableHead>
    <TableRow>
      <TableHeaderCell>Name</TableHeaderCell>
      <TableHeaderCell>Role</TableHeaderCell>
    </TableRow>
  </TableHead>
  <TableBody>
    <TableRow>
      <TableCell>Alice Johnson</TableCell>
      <TableCell>Engineer</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

#### Sortable borderless table

```tsx
<Table variant="borderless" onSort={(key, direction) => { /* sort your data */ }}>
  <TableHead>
    <TableRow>
      <TableHeaderCell sortKey="name">Name</TableHeaderCell>
      <TableHeaderCell sortKey="role">Role</TableHeaderCell>
    </TableRow>
  </TableHead>
  <TableBody>
    {rows.map((row) => (
      <TableRow key={row.name}>
        <TableCell>{row.name}</TableCell>
        <TableCell>{row.role}</TableCell>
      </TableRow>
    ))}
  </TableBody>
</Table>
```

---

## Breadcrumb

Breadcrumb navigation component. Renders a `<nav aria-label="Breadcrumb">` with an ordered list of segments. The last item receives `aria-current="page"`. Delimiters are marked `aria-hidden` so screen readers skip them.

### Import

```tsx
import { Breadcrumb } from '@roadlittledawn/docs-design-system-react';
```

### Types

```ts
interface BreadcrumbItem {
  label: string;   // Display text for the segment
  href?: string;   // Optional URL; omit for the current (last) page
}
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `BreadcrumbItem[]` | — | Ordered list of path segments, root first |
| `delimiter` | `ReactNode` | `"/"` | Separator between segments |
| `size` | `"sm" \| "md"` | `"md"` | Font size variant |
| `collapseOnMobile` | `boolean` | `false` | Collapse middle segments behind an ellipsis on narrow viewports |
| `scrollOnMobile` | `boolean` | `false` | Scroll horizontally instead of wrapping on narrow viewports |
| `className` | `string` | `""` | Additional CSS classes |

### Example

```tsx
<Breadcrumb
  items={[
    { label: 'Home', href: '/' },
    { label: 'Docs', href: '/docs' },
    { label: 'Getting Started' },
  ]}
/>
```

---

## Icon

Renders an SVG icon without bundling any specific icon library. Accepts a React SVG component or a raw SVG string.

### Import

```tsx
import { Icon } from '@roadlittledawn/docs-design-system-react';
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `svg` | `React.ComponentType<React.SVGProps<SVGSVGElement>> \| string` | — | SVG to render |
| `size` | `number` | `16` | Width and height in pixels |
| `className` | `string` | `""` | Additional CSS class names |
| `aria-label` | `string` | — | Accessible label. When provided: `role="img"`. When omitted: `aria-hidden="true"` |

### Examples

```tsx
// React SVG component (spread props to forward size/className/aria-*)
const StarIcon = (props: React.SVGProps<SVGSVGElement>) => (
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" {...props}>
    <polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2" />
  </svg>
);

<Icon svg={StarIcon} size={24} />
<Icon svg={StarIcon} size={16} aria-label="Favorite" />

// Raw SVG string (do not include aria-hidden or other aria attributes in the string)
const closeIconSvg = `<svg viewBox="0 0 24 24" ...>...</svg>`;
<Icon svg={closeIconSvg} size={24} aria-label="Close" />
```

### Notes

- Do **not** include accessibility attributes (`aria-hidden`, `role`, `aria-label`) inside the SVG component or raw string — `Icon` owns all accessibility attributes.
- Raw SVG strings use `dangerouslySetInnerHTML` — only pass trusted content.