From 20757e8dbf61cdb36e55071bb97b08644f202f97 Mon Sep 17 00:00:00 2001
From: Troy Chaplin <troy.chaplin@gmail.com>
Date: Fri, 23 Jan 2026 10:47:04 -0500
Subject: [PATCH 1/3] add: docs

---
 docs/ARCHITECTURE.md | 398 +++++++++++++++++++
 docs/COMPONENTS.md   | 897 +++++++++++++++++++++++++++++++++++++++++++
 docs/CONTRIBUTING.md | 579 ++++++++++++++++++++++++++++
 docs/FORMS.md        | 891 ++++++++++++++++++++++++++++++++++++++++++
 docs/GUTENBERG.md    | 844 ++++++++++++++++++++++++++++++++++++++++
 docs/IMPROVEMENTS.md | 482 +++++++++++++++++++++++
 docs/LAYOUTS.md      | 601 +++++++++++++++++++++++++++++
 docs/MIGRATION.md    | 831 +++++++++++++++++++++++++++++++++++++++
 docs/README.md       | 124 ++++++
 docs/STYLING.md      | 632 ++++++++++++++++++++++++++++++
 docs/TESTING.md      | 854 ++++++++++++++++++++++++++++++++++++++++
 docs/UTILITIES.md    | 890 ++++++++++++++++++++++++++++++++++++++++++
 12 files changed, 8023 insertions(+)
 create mode 100644 docs/ARCHITECTURE.md
 create mode 100644 docs/COMPONENTS.md
 create mode 100644 docs/CONTRIBUTING.md
 create mode 100644 docs/FORMS.md
 create mode 100644 docs/GUTENBERG.md
 create mode 100644 docs/IMPROVEMENTS.md
 create mode 100644 docs/LAYOUTS.md
 create mode 100644 docs/MIGRATION.md
 create mode 100644 docs/README.md
 create mode 100644 docs/STYLING.md
 create mode 100644 docs/TESTING.md
 create mode 100644 docs/UTILITIES.md

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 000000000..b12cd5fdd
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,398 @@
+# Architecture
+
+This document describes the system architecture, project structure, and build process for the Raven Design System.
+
+## Table of Contents
+
+- [Project Structure](#project-structure)
+- [Build System](#build-system)
+- [Module System](#module-system)
+- [Component Architecture](#component-architecture)
+- [Dependency Management](#dependency-management)
+- [Configuration Files](#configuration-files)
+
+## Project Structure
+
+```
+rds/
+├── lib/                          # Source code
+│   ├── components/               # 51 UI components
+│   │   ├── Alert/
+│   │   │   ├── Alert.tsx         # Component implementation
+│   │   │   ├── Alert.stories.tsx # Storybook stories
+│   │   │   └── styles.css        # Component styles
+│   │   └── ...
+│   ├── layouts/                  # 10 layout components
+│   ├── data/                     # Sample data for stories (26 files)
+│   ├── helpers/                  # Validation schemas, utilities
+│   ├── hooks/                    # Custom React hooks (3 hooks)
+│   ├── styles/                   # Global CSS files
+│   ├── utils/                    # Utility functions and prop classes
+│   ├── docs/                     # Storybook MDX documentation
+│   ├── main.ts                   # Main export barrel file
+│   └── style.css                 # Primary CSS entry point
+│
+├── .storybook/                   # Storybook configuration
+│   ├── main.ts                   # Main config
+│   └── preview.ts                # Preview config
+│
+├── cypress/                      # E2E and component tests
+│   ├── e2e/                      # E2E test files
+│   ├── fixtures/                 # Test fixtures
+│   └── support/                  # Test helpers
+│
+├── public/                       # Static assets
+│   ├── assets/
+│   │   ├── font-awesome/         # Icons
+│   │   └── bg-images/            # Background images
+│   └── sample-imgs/              # Sample images for demos
+│
+├── dist/                         # Build output (generated)
+│   ├── rds.es.js                 # ES module bundle
+│   ├── rds.umd.js                # UMD bundle
+│   ├── main.d.ts                 # TypeScript declarations
+│   └── style.css                 # Compiled CSS
+│
+└── Configuration files
+    ├── vite.config.ts            # Vite/Rollup configuration
+    ├── tailwind.config.ts        # Tailwind CSS configuration
+    ├── tsconfig.json             # TypeScript configuration
+    ├── eslint.config.mjs         # ESLint configuration
+    ├── .prettierrc               # Prettier configuration
+    ├── cypress.config.ts         # Cypress configuration
+    └── package.json              # Dependencies and scripts
+```
+
+## Build System
+
+### Vite + Rollup
+
+The library uses Vite 6.3 with Rollup for production builds.
+
+**Key Configuration** (`vite.config.ts`):
+
+```typescript
+export default defineConfig({
+  plugins: [react(), dts({ rollupTypes: true })],
+  build: {
+    lib: {
+      entry: resolve(__dirname, 'lib/main.ts'),
+      name: 'rds',
+      formats: ['es', 'umd'],
+      fileName: (format) => `rds.${format}.js`,
+    },
+    rollupOptions: {
+      external: [/* all dependencies externalized */],
+      output: {
+        globals: {
+          react: 'React',
+          'react-dom': 'ReactDOM',
+          // ... other globals
+        },
+      },
+    },
+  },
+})
+```
+
+### Build Outputs
+
+| Output | Format | Use Case |
+|--------|--------|----------|
+| `dist/rds.es.js` | ES Modules | Modern bundlers (Vite, webpack 5+) |
+| `dist/rds.umd.js` | UMD | Browser `<script>` tags, older bundlers |
+| `dist/main.d.ts` | TypeScript | Type definitions |
+| `dist/style.css` | CSS | Compiled styles |
+
+### Bundle Size Limits
+
+Enforced via `size-limit` package:
+
+```json
+{
+  "size-limit": [
+    { "path": "dist/rds.es.js", "limit": "200 kB" },
+    { "path": "dist/rds.umd.js", "limit": "200 kB" }
+  ]
+}
+```
+
+### Build Scripts
+
+```bash
+# Full build (lint, format, compile, size check)
+npm run build
+
+# Storybook build
+npm run build:storybook
+
+# Generate asset lists
+npm run create-lists
+```
+
+### CSS Processing
+
+PostCSS pipeline with:
+1. **Tailwind CSS** - Utility-first styles
+2. **PostCSS Nesting** - CSS nesting support
+3. **Autoprefixer** - Browser prefixes
+
+## Module System
+
+### Export Pattern
+
+The library uses a **barrel export pattern** in `lib/main.ts`:
+
+```typescript
+// Components
+export { Alert } from './components/Alert/Alert'
+export { Button } from './components/Button/Button'
+export { Card } from './components/Card/Card'
+// ... 50+ more
+
+// Layouts
+export { Article } from './layouts/Article/Article'
+export { Column } from './layouts/Column/Column'
+// ... more layouts
+
+// Utilities
+export * as utils from './utils/propClasses'
+export { iconNames } from '../public/assets/font-awesome/icon-list.js'
+export { bgImageNames } from '../public/assets/bg-images/bg-image-list.js'
+
+// CSS (side effect)
+import './style.css'
+```
+
+### Package Exports
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "import": "./dist/rds.es.js",
+      "require": "./dist/rds.umd.js"
+    },
+    "./dist/style.css": "./dist/style.css"
+  }
+}
+```
+
+### External Dependencies
+
+All dependencies are externalized to avoid bundling:
+
+```typescript
+external: [
+  'react',
+  'react-dom',
+  'formik',
+  'yup',
+  'date-fns',
+  'react-select',
+  'react-player',
+  'dompurify',
+  '@react-google-maps/api',
+  // ... etc
+]
+```
+
+## Component Architecture
+
+### Standard Component Structure
+
+```
+ComponentName/
+├── ComponentName.tsx         # Main component
+├── ComponentName.stories.tsx # Storybook stories
+├── styles.css                # Component-scoped styles
+└── [SubComponents.tsx]       # Optional sub-components
+```
+
+### Composite Component Pattern
+
+Complex components use `Object.assign` for sub-component attachment:
+
+```typescript
+// Card.tsx
+const CardWrapper = ({ children, ...props }) => (
+  <div {...props}>{children}</div>
+)
+
+export const Card = Object.assign(CardWrapper, {
+  Figure: CardFigure,
+  Header: CardHeader,
+  Body: CardBody,
+  Content: CardContent,
+  Footer: CardFooter,
+  // ... more subcomponents
+})
+```
+
+**Usage:**
+```tsx
+<Card>
+  <Card.Figure src="/image.jpg" />
+  <Card.Body>
+    <Card.Header title="Card Title" />
+    <Card.Content>Content here</Card.Content>
+  </Card.Body>
+</Card>
+```
+
+### TypeScript Patterns
+
+**Props Interface Pattern:**
+```typescript
+export interface ButtonProps extends React.ComponentPropsWithoutRef<'button'> {
+  color?: 'red' | 'grey' | 'dark-grey' | 'black' | 'white'
+  isSmall?: boolean
+  isFull?: boolean
+  isDisabled?: boolean
+}
+```
+
+**Discriminated Union Pattern:**
+```typescript
+// Button with title
+interface ButtonTitleProps extends BaseButtonProps {
+  title: string
+  children?: never
+}
+
+// Button with children
+interface ButtonChildrenProps extends BaseButtonProps {
+  children: React.ReactNode
+  title?: never
+}
+
+type ButtonProps = ButtonTitleProps | ButtonChildrenProps
+```
+
+### Context Providers
+
+**LinkProvider** for customizable link components:
+
+```typescript
+// LinkContext.tsx
+export const LinkContext = createContext<React.ElementType>('a')
+export const useLinkContext = () => useContext(LinkContext)
+
+// Usage in component
+const Link = useLinkContext()
+return <Link href={url}>{children}</Link>
+
+// App-level customization
+import { Link } from 'next/link'
+<LinkProvider value={Link}>
+  <App />
+</LinkProvider>
+```
+
+## Dependency Management
+
+### Peer Dependencies
+
+```json
+{
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  }
+}
+```
+
+### Key Runtime Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `formik` | 2.4.9 | Form state management |
+| `yup` | 1.7.1 | Schema validation |
+| `date-fns` | 4.1.0 | Date utilities |
+| `react-select` | 5.10.2 | Enhanced select dropdown |
+| `react-player` | 3.4.0 | Video player |
+| `dompurify` | 3.3.1 | HTML sanitization |
+| `@react-google-maps/api` | 2.20.8 | Google Maps |
+
+### Styling Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `tailwindcss` | Utility CSS framework |
+| `rds-tailwind-theme` | Carleton custom theme preset |
+| `@tailwindcss/forms` | Form element styles |
+| `@tailwindcss/typography` | Prose styles |
+| `@tailwindcss/aspect-ratio` | Aspect ratio utilities |
+| `@tailwindcss/container-queries` | Container queries |
+
+## Configuration Files
+
+### TypeScript (`tsconfig.json`)
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  }
+}
+```
+
+### Tailwind (`tailwind.config.ts`)
+
+```typescript
+export default {
+  presets: [require('rds-tailwind-theme')],
+  content: ['./lib/**/*.{tsx,ts,jsx,js}'],
+  darkMode: 'selector', // .dark class-based
+  // Theme extensions...
+}
+```
+
+### ESLint (`eslint.config.mjs`)
+
+- Flat config format (ESLint 9+)
+- TypeScript support
+- React/React Hooks rules
+- Prettier integration
+- Storybook plugin
+- Cypress plugin
+
+### Prettier (`.prettierrc`)
+
+```json
+{
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 120,
+  "bracketSpacing": true
+}
+```
+
+## Areas for Improvement
+
+### Current Issues
+
+1. **Large bundle size** - CSS includes unused Tailwind utilities
+2. **No tree-shaking** - All components bundled together
+3. **Tight Tailwind coupling** - Hard to customize without Tailwind knowledge
+4. **Limited CSS isolation** - Global styles can leak
+
+### Planned Improvements
+
+1. **SCSS Migration** - Move to CSS modules for better isolation
+2. **Component-level exports** - Enable tree-shaking
+3. **CSS extraction** - Separate critical and non-critical CSS
+4. **Better TypeScript** - Stricter types for Gutenberg integration
+
+See [MIGRATION.md](./MIGRATION.md) for the Tailwind to SCSS migration plan.
diff --git a/docs/COMPONENTS.md b/docs/COMPONENTS.md
new file mode 100644
index 000000000..ce918b603
--- /dev/null
+++ b/docs/COMPONENTS.md
@@ -0,0 +1,897 @@
+# Component Catalog
+
+Complete reference for all RDS components organized by category.
+
+## Table of Contents
+
+- [Core UI Components](#core-ui-components)
+- [Banner & Hero Components](#banner--hero-components)
+- [Footer Components](#footer-components)
+- [Navigation](#navigation)
+- [Data Display](#data-display)
+- [Feedback Components](#feedback-components)
+- [Media Components](#media-components)
+- [Skeleton Loaders](#skeleton-loaders)
+- [Error Pages](#error-pages)
+
+---
+
+## Core UI Components
+
+### Alert
+
+Displays contextual feedback messages.
+
+```tsx
+import { Alert } from '@carletonuniversity/rds'
+
+<Alert type="success" title="Success!">
+  Your changes have been saved.
+</Alert>
+
+<Alert type="warning" title="Warning">
+  Please review before continuing.
+</Alert>
+
+<Alert type="error" title="Error">
+  Something went wrong.
+</Alert>
+
+<Alert type="info" title="Info">
+  Here's some helpful information.
+</Alert>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'success' \| 'warning' \| 'error' \| 'info'` | `'info'` | Alert style variant |
+| `title` | `string` | - | Alert heading |
+| `children` | `ReactNode` | - | Alert content |
+
+---
+
+### Avatar
+
+User profile images with fallback support.
+
+```tsx
+import { Avatar } from '@carletonuniversity/rds'
+
+<Avatar
+  src="/user.jpg"
+  alt="John Doe"
+  size="md"
+/>
+
+// With initials fallback
+<Avatar
+  initials="JD"
+  size="lg"
+/>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | - | Image URL |
+| `alt` | `string` | - | Alt text |
+| `initials` | `string` | - | Fallback initials |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar size |
+
+---
+
+### Badge / BadgeGroup
+
+Small status indicators and labels.
+
+```tsx
+import { Badge, BadgeGroup } from '@carletonuniversity/rds'
+
+<Badge color="red">New</Badge>
+<Badge color="grey">Draft</Badge>
+
+<BadgeGroup>
+  <Badge>Tag 1</Badge>
+  <Badge>Tag 2</Badge>
+  <Badge>Tag 3</Badge>
+</BadgeGroup>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `'red' \| 'grey' \| 'green' \| 'blue'` | `'grey'` | Badge color |
+| `children` | `ReactNode` | - | Badge content |
+
+---
+
+### Button / ButtonGroup
+
+Interactive buttons with multiple variants.
+
+```tsx
+import { Button, ButtonGroup } from '@carletonuniversity/rds'
+
+// Color variants
+<Button color="red">Primary Action</Button>
+<Button color="grey">Secondary</Button>
+<Button color="dark-grey">Tertiary</Button>
+<Button color="black">Dark</Button>
+<Button color="white">Light</Button>
+
+// Sizes and states
+<Button isSmall>Small Button</Button>
+<Button isFull>Full Width</Button>
+<Button isDisabled>Disabled</Button>
+
+// Button group
+<ButtonGroup>
+  <Button>One</Button>
+  <Button>Two</Button>
+  <Button>Three</Button>
+</ButtonGroup>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `'red' \| 'grey' \| 'dark-grey' \| 'black' \| 'white'` | `'red'` | Button color |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Button type |
+| `isSmall` | `boolean` | `false` | Small size variant |
+| `isFull` | `boolean` | `false` | Full width |
+| `isDisabled` | `boolean` | `false` | Disabled state |
+
+---
+
+### Card
+
+Versatile card component with 14 subcomponents for flexible composition.
+
+```tsx
+import { Card } from '@carletonuniversity/rds'
+
+// Basic card
+<Card>
+  <Card.Figure>
+    <img src="/image.jpg" alt="Card image" />
+  </Card.Figure>
+  <Card.Body>
+    <Card.Header title="Card Title" />
+    <Card.Excerpt text="Brief description of the card content." />
+    <Card.Footer>
+      <Button>Learn More</Button>
+    </Card.Footer>
+  </Card.Body>
+</Card>
+
+// Event card with date thumbnail
+<Card>
+  <Card.DateThumb date="2024-03-15" />
+  <Card.Body>
+    <Card.Header title="Event Title" />
+    <Card.EventMeta
+      startDate="2024-03-15"
+      endDate="2024-03-15"
+      location="Room 101"
+    />
+  </Card.Body>
+</Card>
+
+// People card
+<Card>
+  <Card.Initials initials="JD" />
+  <Card.Body>
+    <Card.Header title="John Doe" />
+    <Card.PeopleMeta
+      jobTitle="Professor"
+      department="Computer Science"
+    />
+  </Card.Body>
+</Card>
+```
+
+**Subcomponents:**
+| Component | Description |
+|-----------|-------------|
+| `Card.Figure` | Image container |
+| `Card.ImageThumb` | Small image thumbnail |
+| `Card.DateThumb` | Date display thumbnail |
+| `Card.IconThumb` | Icon thumbnail |
+| `Card.Initials` | Initials avatar |
+| `Card.Video` | Video embed |
+| `Card.Header` | Title and subtitle |
+| `Card.Body` | Content wrapper |
+| `Card.Content` | Main content area |
+| `Card.Footer` | Footer actions |
+| `Card.Excerpt` | Brief text excerpt |
+| `Card.EventMeta` | Event metadata |
+| `Card.PeopleMeta` | Person metadata |
+| `Card.Stats` | Statistics display |
+
+---
+
+### Listing
+
+List item component with similar structure to Card.
+
+```tsx
+import { Listing } from '@carletonuniversity/rds'
+
+<Listing>
+  <Listing.Figure>
+    <img src="/thumb.jpg" alt="" />
+  </Listing.Figure>
+  <Listing.Body>
+    <Listing.Header title="List Item Title" />
+    <Listing.Excerpt text="Description text" />
+  </Listing.Body>
+</Listing>
+```
+
+**Subcomponents:**
+| Component | Description |
+|-----------|-------------|
+| `Listing.Figure` | Image container |
+| `Listing.DateThumb` | Date thumbnail |
+| `Listing.IconThumb` | Icon thumbnail |
+| `Listing.Initials` | Initials avatar |
+| `Listing.Header` | Title area |
+| `Listing.Body` | Content wrapper |
+| `Listing.Content` | Main content |
+| `Listing.Footer` | Footer area |
+| `Listing.Excerpt` | Text excerpt |
+| `Listing.EventMeta` | Event metadata |
+| `Listing.PeopleMeta` | Person metadata |
+
+---
+
+### Description
+
+Descriptive text blocks, often used for definition lists.
+
+```tsx
+import { Description } from '@carletonuniversity/rds'
+
+<Description
+  title="Term"
+  content="Definition or explanation of the term."
+/>
+```
+
+---
+
+### Details
+
+Expandable/collapsible content section.
+
+```tsx
+import { Details } from '@carletonuniversity/rds'
+
+<Details summary="Click to expand">
+  <p>Hidden content revealed when expanded.</p>
+</Details>
+```
+
+---
+
+### Dialog / Modal
+
+Overlay dialogs and modals.
+
+```tsx
+import { Dialog, Modal } from '@carletonuniversity/rds'
+
+// Dialog
+<Dialog
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Dialog Title"
+>
+  <p>Dialog content here.</p>
+</Dialog>
+
+// Modal
+<Modal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+>
+  <Modal.Header title="Modal Title" />
+  <Modal.Body>
+    <p>Modal content</p>
+  </Modal.Body>
+  <Modal.Footer>
+    <Button onClick={() => setIsOpen(false)}>Close</Button>
+  </Modal.Footer>
+</Modal>
+```
+
+---
+
+### Icon
+
+Font Awesome icon wrapper.
+
+```tsx
+import { Icon } from '@carletonuniversity/rds'
+
+<Icon icon="fa-solid fa-check" />
+<Icon icon="fa-solid fa-times" size="lg" />
+<Icon icon="fa-brands fa-github" />
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `string` | - | Font Awesome class |
+| `size` | `number \| string` | - | Icon size (4-24) |
+
+---
+
+### Table
+
+Data table with sorting support.
+
+```tsx
+import { Table } from '@carletonuniversity/rds'
+
+<Table>
+  <Table.Header>
+    <Table.Row>
+      <Table.HeaderCell>Name</Table.HeaderCell>
+      <Table.HeaderCell>Email</Table.HeaderCell>
+      <Table.HeaderCell>Role</Table.HeaderCell>
+    </Table.Row>
+  </Table.Header>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>John Doe</Table.Cell>
+      <Table.Cell>john@example.com</Table.Cell>
+      <Table.Cell>Admin</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+```
+
+---
+
+### Pagination
+
+Page navigation component.
+
+```tsx
+import { Pagination } from '@carletonuniversity/rds'
+
+<Pagination
+  currentPage={1}
+  totalPages={10}
+  onPageChange={(page) => setCurrentPage(page)}
+/>
+```
+
+---
+
+### Calendar
+
+Date selection calendar.
+
+```tsx
+import { Calendar } from '@carletonuniversity/rds'
+
+<Calendar
+  selectedDate={selectedDate}
+  onDateSelect={(date) => setSelectedDate(date)}
+/>
+```
+
+---
+
+## Banner & Hero Components
+
+### Splash
+
+Full-screen hero banner with video/image support.
+
+```tsx
+import { Splash } from '@carletonuniversity/rds'
+
+<Splash>
+  <Splash.Background>
+    <Splash.Video src="/hero-video.mp4" />
+    {/* or */}
+    <Splash.Image src="/hero.jpg" alt="Hero" />
+  </Splash.Background>
+  <Splash.Content>
+    <h1>Welcome to RDS</h1>
+    <p>Your component library</p>
+    <Button>Get Started</Button>
+  </Splash.Content>
+</Splash>
+```
+
+**Subcomponents:**
+| Component | Description |
+|-----------|-------------|
+| `Splash.Background` | Background container |
+| `Splash.Video` | Background video |
+| `Splash.Image` | Background image |
+| `Splash.Content` | Overlay content |
+
+---
+
+### FullBanner / WideBanner
+
+Full-width banner sections.
+
+```tsx
+import { FullBanner, WideBanner } from '@carletonuniversity/rds'
+
+<FullBanner
+  title="Banner Title"
+  content="Banner description text"
+  image="/banner.jpg"
+/>
+
+<WideBanner
+  title="Wide Banner"
+  alignment="left"
+>
+  <p>Custom content</p>
+</WideBanner>
+```
+
+---
+
+### WideImage
+
+Full-width image section.
+
+```tsx
+import { WideImage } from '@carletonuniversity/rds'
+
+<WideImage
+  src="/wide-image.jpg"
+  alt="Description"
+  caption="Image caption"
+/>
+```
+
+---
+
+### PageHeader
+
+Page header with title and metadata.
+
+```tsx
+import { PageHeader } from '@carletonuniversity/rds'
+
+<PageHeader
+  title="Page Title"
+  subtitle="Page subtitle"
+  breadcrumbs={[
+    { label: 'Home', href: '/' },
+    { label: 'Section', href: '/section' },
+  ]}
+/>
+```
+
+---
+
+## Footer Components
+
+### FooterBasic
+
+Minimal footer with copyright.
+
+```tsx
+import { FooterBasic } from '@carletonuniversity/rds'
+
+<FooterBasic
+  copyrightYear={2024}
+  organization="Carleton University"
+/>
+```
+
+### FooterStandard
+
+Standard footer with navigation links.
+
+```tsx
+import { FooterStandard } from '@carletonuniversity/rds'
+
+<FooterStandard
+  links={footerLinks}
+  socialLinks={socialLinks}
+/>
+```
+
+### FooterAthletics
+
+Athletics-specific footer design.
+
+### FooterCookie
+
+Cookie consent footer.
+
+### FooterLogoLinks
+
+Footer with logos and links.
+
+---
+
+## Navigation
+
+### Nav
+
+Complex navigation component with responsive support.
+
+```tsx
+import { Nav } from '@carletonuniversity/rds'
+
+<Nav>
+  <Nav.Top>
+    <Nav.Logo src="/logo.svg" alt="Logo" />
+    <Nav.Buttons>
+      <Button>Login</Button>
+    </Nav.Buttons>
+  </Nav.Top>
+  <Nav.Bottom>
+    <Nav.Menu>
+      <Nav.MenuItem href="/" label="Home" />
+      <Nav.MenuItem href="/about" label="About">
+        <Nav.SubMenu>
+          <Nav.MenuItem href="/about/team" label="Team" />
+          <Nav.MenuItem href="/about/history" label="History" />
+        </Nav.SubMenu>
+      </Nav.MenuItem>
+    </Nav.Menu>
+  </Nav.Bottom>
+</Nav>
+```
+
+**Subcomponents:**
+| Component | Description |
+|-----------|-------------|
+| `Nav.Top` | Top navigation bar |
+| `Nav.Bottom` | Main navigation bar |
+| `Nav.Aside` | Sidebar navigation |
+| `Nav.Menu` | Menu container |
+| `Nav.SubMenu` | Dropdown submenu |
+| `Nav.MenuItem` | Menu item |
+| `Nav.MenuItemWrapper` | Menu item wrapper |
+| `Nav.Logo` | Logo component |
+| `Nav.Buttons` | Button group |
+
+---
+
+## Data Display
+
+### TextImage / TextMedia
+
+Side-by-side text and media layouts.
+
+```tsx
+import { TextImage, TextMedia } from '@carletonuniversity/rds'
+
+<TextImage
+  title="Section Title"
+  content="Description text"
+  image="/image.jpg"
+  imagePosition="right"
+/>
+
+<TextMedia
+  title="Video Section"
+  content="Watch our introduction"
+  media={{ type: 'video', src: '/video.mp4' }}
+/>
+```
+
+---
+
+### Quote
+
+Styled blockquotes.
+
+```tsx
+import { Quote } from '@carletonuniversity/rds'
+
+<Quote
+  text="This is a quoted statement."
+  author="John Doe"
+  citation="Source Publication"
+/>
+```
+
+---
+
+### Testimonial
+
+Testimonial/review blocks.
+
+```tsx
+import { Testimonial } from '@carletonuniversity/rds'
+
+<Testimonial
+  quote="Great experience working with RDS!"
+  author="Jane Smith"
+  role="Developer"
+  image="/jane.jpg"
+/>
+```
+
+---
+
+### Timeline
+
+Event timeline visualization.
+
+```tsx
+import { Timeline } from '@carletonuniversity/rds'
+
+<Timeline
+  items={[
+    { date: '2024-01', title: 'Project Started', description: '...' },
+    { date: '2024-03', title: 'Beta Release', description: '...' },
+    { date: '2024-06', title: 'v1.0 Launch', description: '...' },
+  ]}
+/>
+```
+
+---
+
+### FilterPanel
+
+Filter sidebar for search results.
+
+```tsx
+import { FilterPanel } from '@carletonuniversity/rds'
+
+<FilterPanel
+  filters={[
+    {
+      name: 'category',
+      label: 'Category',
+      options: [
+        { value: 'news', label: 'News' },
+        { value: 'events', label: 'Events' },
+      ],
+    },
+  ]}
+  onFilterChange={handleFilterChange}
+/>
+```
+
+---
+
+## Feedback Components
+
+### Toast
+
+Notification toasts.
+
+```tsx
+import { Toast } from '@carletonuniversity/rds'
+
+<Toast
+  type="success"
+  message="Action completed successfully!"
+  isVisible={showToast}
+  onClose={() => setShowToast(false)}
+/>
+```
+
+---
+
+### CallOut
+
+Highlighted callout boxes.
+
+```tsx
+import { CallOut } from '@carletonuniversity/rds'
+
+<CallOut type="info" title="Note">
+  Important information for the user.
+</CallOut>
+```
+
+---
+
+### Placeholder
+
+Skeleton loading placeholders.
+
+```tsx
+import { Placeholder } from '@carletonuniversity/rds'
+
+<Placeholder type="text" lines={3} />
+<Placeholder type="image" aspectRatio="16:9" />
+```
+
+---
+
+## Media Components
+
+### Figure
+
+Images with captions.
+
+```tsx
+import { Figure } from '@carletonuniversity/rds'
+
+<Figure
+  src="/image.jpg"
+  alt="Image description"
+  caption="Figure 1: Image caption"
+/>
+```
+
+---
+
+### Embed
+
+Embedded content (YouTube, Vimeo, HubSpot).
+
+```tsx
+import { Embed } from '@carletonuniversity/rds'
+
+<Embed
+  type="youtube"
+  videoId="dQw4w9WgXcQ"
+/>
+
+<Embed
+  type="vimeo"
+  videoId="123456789"
+/>
+```
+
+---
+
+### ImageGrid
+
+Grid layout for multiple images.
+
+```tsx
+import { ImageGrid } from '@carletonuniversity/rds'
+
+<ImageGrid
+  images={[
+    { src: '/img1.jpg', alt: 'Image 1' },
+    { src: '/img2.jpg', alt: 'Image 2' },
+    { src: '/img3.jpg', alt: 'Image 3' },
+  ]}
+  columns={3}
+/>
+```
+
+---
+
+### ImageSlider
+
+Image carousel/slider.
+
+```tsx
+import { ImageSlider } from '@carletonuniversity/rds'
+
+<ImageSlider
+  images={[
+    { src: '/slide1.jpg', alt: 'Slide 1' },
+    { src: '/slide2.jpg', alt: 'Slide 2' },
+  ]}
+  autoPlay
+  interval={5000}
+/>
+```
+
+---
+
+## Skeleton Loaders
+
+Pre-built loading states for components.
+
+```tsx
+import {
+  CardEventLoader,
+  CardNewsLoader,
+  CardPeopleLoader,
+  ListingEventLoader,
+  PageHeaderLoader,
+  TableLoader,
+} from '@carletonuniversity/rds'
+
+// Use while data is loading
+{isLoading ? <CardNewsLoader /> : <Card>...</Card>}
+```
+
+**Available Loaders:**
+- `CardEventLoader`, `CardIconLoader`, `CardNewsLoader`, `CardPageLoader`, `CardPeopleLoader`, `CardVideoLoader`
+- `ListingEventLoader`, `ListingIconLoader`, `ListingNewsLoader`, `ListingPageLoader`, `ListingPeopleLoader`, `ListingDescriptionLoader`
+- `CalendarLoader`, `DescriptionLoader`, `DescriptionLoaderAccordion`
+- `EventLoader`, `PageLoader`, `TopNavLoader`
+- `PageHeaderLoader`, `PageHeaderEventLoader`, `PageHeaderPeopleLoader`
+- `FormLoader`, `BlockLoader`, `ButtonLoader`, `TableLoader`, `PaginationLoader`
+
+---
+
+## Error Pages
+
+### Forbidden403
+
+403 Forbidden error page.
+
+```tsx
+import { Forbidden403 } from '@carletonuniversity/rds'
+
+<Forbidden403
+  message="You don't have permission to access this page."
+  homeLink="/"
+/>
+```
+
+### NotFound404
+
+404 Not Found error page.
+
+```tsx
+import { NotFound404 } from '@carletonuniversity/rds'
+
+<NotFound404
+  message="The page you're looking for doesn't exist."
+  homeLink="/"
+  searchLink="/search"
+/>
+```
+
+---
+
+## Additional Components
+
+### Login
+
+Login form component.
+
+### Location / LocationPicker
+
+Location display and Google Maps picker.
+
+### SearchInput
+
+Search bar component.
+
+### SocialIcons
+
+Social media icon links.
+
+### Carleton360
+
+Custom Carleton University 360 viewer component.
+
+---
+
+## Component Development Notes
+
+### Naming Conventions
+
+- PascalCase for component names
+- camelCase for props
+- Prefix boolean props with `is`, `has`, or `should`
+
+### File Structure
+
+```
+ComponentName/
+├── ComponentName.tsx         # Main export
+├── ComponentName.stories.tsx # Storybook
+├── styles.css                # Scoped styles
+└── SubComponent.tsx          # Subcomponents
+```
+
+### Testing Components
+
+Each component should have:
+1. Storybook stories covering all variants
+2. Cypress tests for interactive behavior
+3. Accessibility checks via Storybook a11y addon
+
+See [TESTING.md](./TESTING.md) for testing guidelines.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 000000000..d8a24e16b
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,579 @@
+# Contributing Guide
+
+Guidelines for contributing to the Raven Design System.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Code Standards](#code-standards)
+- [Component Guidelines](#component-guidelines)
+- [Commit Conventions](#commit-conventions)
+- [Pull Request Process](#pull-request-process)
+- [Documentation](#documentation)
+- [Testing Requirements](#testing-requirements)
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+- Git
+
+### Setup
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd rds
+
+# Install dependencies
+npm install
+
+# Start Storybook development server
+npm run storybook
+```
+
+### Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run storybook` | Start Storybook dev server on port 6006 |
+| `npm run build` | Build the library |
+| `npm run build:storybook` | Build Storybook for deployment |
+| `npm run lint` | Run ESLint |
+| `npm run prettier` | Format code with Prettier |
+| `npm run test` | Run Cypress tests |
+| `npm run test:ci` | Run tests in CI mode |
+
+---
+
+## Development Workflow
+
+### Branch Strategy
+
+```
+main              # Production-ready code
+├── develop       # Integration branch
+│   ├── feature/* # New features
+│   ├── fix/*     # Bug fixes
+│   ├── refactor/*# Refactoring
+│   └── docs/*    # Documentation updates
+```
+
+### Creating a Branch
+
+```bash
+# Feature
+git checkout -b feature/button-loading-state
+
+# Bug fix
+git checkout -b fix/card-overflow-issue
+
+# Refactor
+git checkout -b refactor/form-validation
+
+# Documentation
+git checkout -b docs/update-readme
+```
+
+### Workflow Steps
+
+1. **Create branch** from `develop`
+2. **Make changes** following code standards
+3. **Write tests** for new functionality
+4. **Update documentation** if needed
+5. **Run checks** (`npm run lint && npm run test`)
+6. **Commit** using conventional commits
+7. **Push** and create pull request
+
+---
+
+## Code Standards
+
+### TypeScript
+
+- Use strict TypeScript (`strict: true`)
+- Define explicit types for all props
+- Avoid `any` - use `unknown` if type is truly unknown
+- Export component interfaces
+
+```typescript
+// Good
+export interface ButtonProps {
+  color?: 'red' | 'grey' | 'dark-grey'
+  isDisabled?: boolean
+  children: React.ReactNode
+}
+
+// Bad
+export interface ButtonProps {
+  color?: string
+  isDisabled?: any
+  children: any
+}
+```
+
+### ESLint
+
+Configuration enforces:
+- React hooks rules
+- TypeScript best practices
+- Import ordering
+- Accessibility rules
+
+```bash
+# Check linting
+npm run lint
+
+# Fix auto-fixable issues
+npm run lint -- --fix
+```
+
+### Prettier
+
+Code formatting is automated:
+
+```json
+{
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 120
+}
+```
+
+```bash
+# Format all files
+npm run prettier
+
+# Check formatting
+npm run prettier -- --check
+```
+
+### File Naming
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Components | PascalCase | `Button.tsx` |
+| Stories | PascalCase + .stories | `Button.stories.tsx` |
+| Styles | PascalCase + .css | `Button.css` or `styles.css` |
+| Hooks | camelCase with use prefix | `usePagination.ts` |
+| Utilities | camelCase | `propClasses.tsx` |
+| Types | PascalCase | `ButtonTypes.ts` |
+
+---
+
+## Component Guidelines
+
+### Component Structure
+
+```
+ComponentName/
+├── ComponentName.tsx         # Main component
+├── ComponentName.stories.tsx # Storybook stories
+├── styles.css                # Component styles
+├── SubComponent.tsx          # Optional subcomponents
+└── index.ts                  # Optional barrel export
+```
+
+### Component Template
+
+```tsx
+// ComponentName.tsx
+import { ComponentPropsWithoutRef, forwardRef } from 'react'
+import './styles.css'
+
+export interface ComponentNameProps extends ComponentPropsWithoutRef<'div'> {
+  /** Description of the variant prop */
+  variant?: 'primary' | 'secondary'
+  /** Description of the children prop */
+  children: React.ReactNode
+}
+
+/**
+ * ComponentName description.
+ *
+ * @example
+ * <ComponentName variant="primary">Content</ComponentName>
+ */
+export const ComponentName = forwardRef<HTMLDivElement, ComponentNameProps>(
+  ({ variant = 'primary', children, className, ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={`cu-component-name cu-component-name--${variant} ${className || ''}`}
+        data-testid="component-name"
+        {...props}
+      >
+        {children}
+      </div>
+    )
+  }
+)
+
+ComponentName.displayName = 'ComponentName'
+```
+
+### Props Guidelines
+
+1. **Use descriptive names**
+   ```typescript
+   // Good
+   isDisabled, hasIcon, showLabel
+
+   // Bad
+   disabled, icon, label
+   ```
+
+2. **Provide sensible defaults**
+   ```typescript
+   color = 'red'
+   size = 'md'
+   ```
+
+3. **Use TypeScript unions for variants**
+   ```typescript
+   color?: 'red' | 'grey' | 'black'
+   size?: 'sm' | 'md' | 'lg'
+   ```
+
+4. **Extend HTML element props**
+   ```typescript
+   interface ButtonProps extends ComponentPropsWithoutRef<'button'> {
+     // Custom props
+   }
+   ```
+
+### Styling Guidelines
+
+1. **Use CSS classes, not inline styles**
+2. **Prefix classes with `cu-`**
+3. **Use BEM-like naming**: `cu-component`, `cu-component--variant`, `cu-component__element`
+4. **Support className prop** for customization
+5. **Use CSS custom properties** for theming
+
+```css
+/* styles.css */
+.cu-button {
+  /* Base styles */
+}
+
+.cu-button--primary {
+  background-color: var(--rds-color-primary);
+}
+
+.cu-button__icon {
+  /* Icon styles */
+}
+```
+
+### Accessibility
+
+All components must:
+
+- Support keyboard navigation
+- Include proper ARIA attributes
+- Have sufficient color contrast
+- Work with screen readers
+- Support reduced motion preferences
+
+```tsx
+<button
+  aria-label={ariaLabel}
+  aria-disabled={isDisabled}
+  tabIndex={isDisabled ? -1 : 0}
+>
+  {children}
+</button>
+```
+
+---
+
+## Commit Conventions
+
+### Conventional Commits
+
+Format: `<type>: <description>`
+
+### Commit Types
+
+| Type | Description |
+|------|-------------|
+| `add` | New component or feature |
+| `change` | Modification to existing code |
+| `deprecate` | Deprecation notice |
+| `doc` | Documentation updates |
+| `fix` | Bug fixes |
+| `finish` | Feature completion |
+| `refactor` | Code refactoring |
+| `release` | Release preparation |
+| `revert` | Revert previous commit |
+| `test` | Test-related changes |
+| `upgrade` | Package upgrades |
+
+### Examples
+
+```bash
+# New feature
+git commit -m "add: Button loading state"
+
+# Bug fix
+git commit -m "fix: Card overflow on mobile"
+
+# Documentation
+git commit -m "doc: Update Button props documentation"
+
+# Refactor
+git commit -m "refactor: Simplify form validation logic"
+
+# Dependency update
+git commit -m "upgrade: Update React to 19.2"
+```
+
+### Commit Message Guidelines
+
+- Use imperative mood ("Add feature" not "Added feature")
+- Keep first line under 72 characters
+- Reference issues when applicable
+- Include context in body if needed
+
+```bash
+git commit -m "fix: Resolve Card image overflow issue
+
+The Card component's figure element wasn't constraining
+images properly on mobile viewports. Added max-width
+and object-fit properties.
+
+Fixes #123"
+```
+
+---
+
+## Pull Request Process
+
+### Before Creating PR
+
+- [ ] Code follows style guidelines
+- [ ] All tests pass
+- [ ] Documentation is updated
+- [ ] Storybook stories are added/updated
+- [ ] No console errors or warnings
+- [ ] Changes are rebased on latest develop
+
+### PR Template
+
+```markdown
+## Description
+Brief description of changes
+
+## Type of Change
+- [ ] New feature
+- [ ] Bug fix
+- [ ] Refactor
+- [ ] Documentation
+- [ ] Other (describe)
+
+## Related Issues
+Fixes #123
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Storybook stories added/updated
+- [ ] Manual testing completed
+
+## Screenshots (if applicable)
+[Add screenshots]
+
+## Checklist
+- [ ] Code follows project standards
+- [ ] Self-reviewed code
+- [ ] Comments added for complex logic
+- [ ] Documentation updated
+- [ ] No breaking changes (or documented)
+```
+
+### Review Process
+
+1. **Create PR** against `develop`
+2. **Automated checks** run (lint, tests)
+3. **Code review** by maintainer
+4. **Address feedback** if needed
+5. **Approval and merge**
+
+### Merge Strategy
+
+- Squash and merge for feature branches
+- Keep commits atomic and meaningful
+- Delete branch after merge
+
+---
+
+## Documentation
+
+### Component Documentation
+
+Every component needs:
+
+1. **JSDoc comments** on the component
+2. **Storybook stories** with all variants
+3. **Props table** in Storybook
+4. **Usage examples**
+
+### Storybook Story Template
+
+```typescript
+// Button.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react'
+import { Button } from './Button'
+
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button',
+  component: Button,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Primary button component for user actions.',
+      },
+    },
+  },
+  argTypes: {
+    color: {
+      description: 'Button color variant',
+      control: 'select',
+      options: ['red', 'grey', 'dark-grey', 'black', 'white'],
+      table: {
+        defaultValue: { summary: 'red' },
+      },
+    },
+    isDisabled: {
+      description: 'Disable button interactions',
+      control: 'boolean',
+    },
+    children: {
+      description: 'Button content',
+      control: 'text',
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Button>
+
+export const Primary: Story = {
+  args: {
+    children: 'Primary Button',
+    color: 'red',
+  },
+}
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '1rem' }}>
+      <Button color="red">Red</Button>
+      <Button color="grey">Grey</Button>
+      <Button color="dark-grey">Dark Grey</Button>
+      <Button color="black">Black</Button>
+      <Button color="white">White</Button>
+    </div>
+  ),
+}
+```
+
+### Updating Documentation
+
+When making changes:
+
+1. Update component JSDoc
+2. Update Storybook stories
+3. Update relevant `/docs/*.md` files
+4. Update README if needed
+
+---
+
+## Testing Requirements
+
+### What to Test
+
+- Component renders correctly
+- All prop variants work
+- User interactions function
+- Accessibility requirements met
+- Edge cases handled
+
+### Test Coverage
+
+| Component Type | Minimum Coverage |
+|----------------|------------------|
+| Critical (Button, Form) | 90% |
+| Standard | 70% |
+| Layout | 60% |
+
+### Adding Tests
+
+```typescript
+// Button.cy.tsx
+import { Button } from './Button'
+
+describe('Button', () => {
+  it('renders with default props', () => {
+    cy.mount(<Button>Click Me</Button>)
+    cy.get('[data-testid="rds-button"]')
+      .should('exist')
+      .should('contain', 'Click Me')
+  })
+
+  it('applies color variant', () => {
+    cy.mount(<Button color="grey">Grey Button</Button>)
+    cy.get('[data-testid="rds-button"]')
+      .should('have.class', 'cu-button--grey')
+  })
+
+  it('handles click events', () => {
+    const onClick = cy.stub().as('click')
+    cy.mount(<Button onClick={onClick}>Click</Button>)
+    cy.get('[data-testid="rds-button"]').click()
+    cy.get('@click').should('have.been.called')
+  })
+
+  it('is disabled when isDisabled is true', () => {
+    cy.mount(<Button isDisabled>Disabled</Button>)
+    cy.get('[data-testid="rds-button"]').should('be.disabled')
+  })
+})
+```
+
+### Running Tests
+
+```bash
+# Open Cypress UI
+npm run test
+
+# Run headless (CI)
+npm run test:ci
+```
+
+---
+
+## Questions?
+
+If you have questions:
+
+1. Check existing documentation
+2. Search closed issues/PRs
+3. Ask in project discussions
+4. Create an issue with `question` label
+
+---
+
+## Related Documentation
+
+- [Architecture](./ARCHITECTURE.md) - System architecture
+- [Components](./COMPONENTS.md) - Component catalog
+- [Testing](./TESTING.md) - Testing guide
+- [Styling](./STYLING.md) - CSS guidelines
diff --git a/docs/FORMS.md b/docs/FORMS.md
new file mode 100644
index 000000000..6b09c741f
--- /dev/null
+++ b/docs/FORMS.md
@@ -0,0 +1,891 @@
+# Form System
+
+RDS provides a comprehensive form system built on Formik and Yup for state management and validation.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Core Components](#core-components)
+- [Field Components](#field-components)
+- [Validation](#validation)
+- [Form Patterns](#form-patterns)
+- [Gutenberg Integration](#gutenberg-integration)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+### Dependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `formik` | 2.4.9 | Form state management |
+| `yup` | 1.7.1 | Schema validation |
+| `react-select` | 5.10.2 | Enhanced select dropdowns |
+| `react-datepicker` | 9.1.0 | Date picker |
+
+### Import
+
+```tsx
+import {
+  Form,
+  Input,
+  TextArea,
+  Select,
+  Checkbox,
+  Radio,
+  DateTime,
+  FileUpload,
+  AutoSuggest,
+  PlacesAutoComplete,
+} from '@carletonuniversity/rds'
+```
+
+---
+
+## Core Components
+
+### Form
+
+Main form wrapper that provides Formik context.
+
+```tsx
+import { Form } from '@carletonuniversity/rds'
+import * as Yup from 'yup'
+
+const validationSchema = Yup.object({
+  name: Yup.string().required('Name is required'),
+  email: Yup.string().email('Invalid email').required('Email is required'),
+})
+
+const initialValues = {
+  name: '',
+  email: '',
+}
+
+function ContactForm() {
+  return (
+    <Form
+      initialValues={initialValues}
+      validationSchema={validationSchema}
+      onSubmit={(values) => {
+        console.log(values)
+      }}
+    >
+      <Form.Field name="name" label="Name">
+        <Input name="name" />
+      </Form.Field>
+
+      <Form.Field name="email" label="Email">
+        <Input name="email" type="email" />
+      </Form.Field>
+
+      <Form.Button type="submit">Submit</Form.Button>
+    </Form>
+  )
+}
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `initialValues` | `object` | - | Initial form values |
+| `validationSchema` | `Yup.Schema` | - | Yup validation schema |
+| `onSubmit` | `(values) => void` | - | Submit handler |
+| `enableReinitialize` | `boolean` | `false` | Reset on initialValues change |
+| `validateOnChange` | `boolean` | `true` | Validate on field change |
+| `validateOnBlur` | `boolean` | `true` | Validate on field blur |
+| `children` | `ReactNode` | - | Form content |
+
+### Form Subcomponents
+
+| Component | Description |
+|-----------|-------------|
+| `Form.Field` | Field wrapper with label and error |
+| `Form.FieldSet` | Group of related fields |
+| `Form.Button` | Styled form button |
+| `Form.FieldGroup` | Horizontal field group |
+| `Form.FieldControl` | Field control wrapper |
+| `Form.FieldArrayContainer` | Dynamic field arrays |
+| `Form.FieldWrapper` | Generic field wrapper |
+| `Form.Error` | Error message display |
+| `Form.UseError` | Hook for custom errors |
+
+---
+
+### Form.Field
+
+Wraps form inputs with label, helper text, and error display.
+
+```tsx
+<Form.Field
+  name="email"
+  label="Email Address"
+  helperText="We'll never share your email"
+  required
+>
+  <Input name="email" type="email" placeholder="Enter email" />
+</Form.Field>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Field name (matches Formik field) |
+| `label` | `string` | - | Field label |
+| `helperText` | `string` | - | Helper text below field |
+| `required` | `boolean` | `false` | Show required indicator |
+| `children` | `ReactNode` | - | Input component |
+
+---
+
+### Form.FieldSet
+
+Groups related fields with legend.
+
+```tsx
+<Form.FieldSet legend="Personal Information">
+  <Form.Field name="firstName" label="First Name">
+    <Input name="firstName" />
+  </Form.Field>
+  <Form.Field name="lastName" label="Last Name">
+    <Input name="lastName" />
+  </Form.Field>
+</Form.FieldSet>
+```
+
+---
+
+### Form.FieldGroup
+
+Horizontal layout for multiple fields.
+
+```tsx
+<Form.FieldGroup>
+  <Form.Field name="city" label="City">
+    <Input name="city" />
+  </Form.Field>
+  <Form.Field name="province" label="Province">
+    <Select name="province" options={provinces} />
+  </Form.Field>
+  <Form.Field name="postalCode" label="Postal Code">
+    <Input name="postalCode" />
+  </Form.Field>
+</Form.FieldGroup>
+```
+
+---
+
+### Form.FieldArrayContainer
+
+Dynamic field arrays for repeatable fields.
+
+```tsx
+import { FieldArray } from 'formik'
+
+<FieldArray name="addresses">
+  {({ push, remove }) => (
+    <Form.FieldArrayContainer>
+      {values.addresses.map((_, index) => (
+        <div key={index}>
+          <Form.Field name={`addresses.${index}.street`} label="Street">
+            <Input name={`addresses.${index}.street`} />
+          </Form.Field>
+          <button type="button" onClick={() => remove(index)}>
+            Remove
+          </button>
+        </div>
+      ))}
+      <button type="button" onClick={() => push({ street: '' })}>
+        Add Address
+      </button>
+    </Form.FieldArrayContainer>
+  )}
+</FieldArray>
+```
+
+---
+
+## Field Components
+
+### Input
+
+Text input field with various types.
+
+```tsx
+import { Input } from '@carletonuniversity/rds'
+
+// Text input
+<Input name="username" placeholder="Enter username" />
+
+// Email
+<Input name="email" type="email" />
+
+// Password
+<Input name="password" type="password" />
+
+// Number
+<Input name="age" type="number" min={0} max={120} />
+
+// With prefix/suffix via InputAddon
+<InputAddon prefix="$">
+  <Input name="price" type="number" />
+</InputAddon>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Field name |
+| `type` | `'text' \| 'email' \| 'password' \| 'number' \| 'tel' \| 'url'` | `'text'` | Input type |
+| `placeholder` | `string` | - | Placeholder text |
+| `disabled` | `boolean` | `false` | Disable input |
+| `readOnly` | `boolean` | `false` | Read-only mode |
+
+---
+
+### TextArea
+
+Multi-line text input.
+
+```tsx
+import { TextArea } from '@carletonuniversity/rds'
+
+<TextArea
+  name="description"
+  rows={5}
+  placeholder="Enter description..."
+/>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Field name |
+| `rows` | `number` | `4` | Number of rows |
+| `placeholder` | `string` | - | Placeholder text |
+| `maxLength` | `number` | - | Max character count |
+
+---
+
+### Select
+
+Dropdown select using react-select.
+
+```tsx
+import { Select } from '@carletonuniversity/rds'
+
+const options = [
+  { value: 'ca', label: 'Canada' },
+  { value: 'us', label: 'United States' },
+  { value: 'uk', label: 'United Kingdom' },
+]
+
+// Single select
+<Select
+  name="country"
+  options={options}
+  placeholder="Select country"
+/>
+
+// Multi-select
+<Select
+  name="countries"
+  options={options}
+  isMulti
+  placeholder="Select countries"
+/>
+
+// Searchable
+<Select
+  name="country"
+  options={options}
+  isSearchable
+/>
+
+// Clearable
+<Select
+  name="country"
+  options={options}
+  isClearable
+/>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Field name |
+| `options` | `Array<{value, label}>` | - | Select options |
+| `isMulti` | `boolean` | `false` | Allow multiple selections |
+| `isSearchable` | `boolean` | `false` | Enable search |
+| `isClearable` | `boolean` | `false` | Show clear button |
+| `placeholder` | `string` | - | Placeholder text |
+| `isDisabled` | `boolean` | `false` | Disable select |
+
+---
+
+### Checkbox
+
+Checkbox input for boolean values.
+
+```tsx
+import { Checkbox } from '@carletonuniversity/rds'
+
+// Single checkbox
+<Checkbox name="agreeToTerms" label="I agree to the terms" />
+
+// Checkbox group
+<Form.FieldSet legend="Interests">
+  <Checkbox name="interests" value="sports" label="Sports" />
+  <Checkbox name="interests" value="music" label="Music" />
+  <Checkbox name="interests" value="art" label="Art" />
+</Form.FieldSet>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Field name |
+| `value` | `string` | - | Value for checkbox groups |
+| `label` | `string` | - | Checkbox label |
+| `disabled` | `boolean` | `false` | Disable checkbox |
+
+---
+
+### Radio
+
+Radio button for single selection from options.
+
+```tsx
+import { Radio } from '@carletonuniversity/rds'
+
+<Form.FieldSet legend="Preferred Contact Method">
+  <Radio name="contactMethod" value="email" label="Email" />
+  <Radio name="contactMethod" value="phone" label="Phone" />
+  <Radio name="contactMethod" value="mail" label="Mail" />
+</Form.FieldSet>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Field name |
+| `value` | `string` | - | Radio value |
+| `label` | `string` | - | Radio label |
+| `disabled` | `boolean` | `false` | Disable radio |
+
+---
+
+### DateTime
+
+Date and time picker.
+
+```tsx
+import { DateTime } from '@carletonuniversity/rds'
+
+// Date only
+<DateTime
+  name="birthDate"
+  dateFormat="yyyy-MM-dd"
+/>
+
+// Date and time
+<DateTime
+  name="eventStart"
+  showTimeSelect
+  dateFormat="yyyy-MM-dd HH:mm"
+/>
+
+// Time only
+<DateTime
+  name="startTime"
+  showTimeSelect
+  showTimeSelectOnly
+  dateFormat="HH:mm"
+/>
+
+// With min/max dates
+<DateTime
+  name="appointmentDate"
+  minDate={new Date()}
+  maxDate={addDays(new Date(), 30)}
+/>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Field name |
+| `dateFormat` | `string` | `'yyyy-MM-dd'` | Date format string |
+| `showTimeSelect` | `boolean` | `false` | Show time picker |
+| `showTimeSelectOnly` | `boolean` | `false` | Time only mode |
+| `minDate` | `Date` | - | Minimum selectable date |
+| `maxDate` | `Date` | - | Maximum selectable date |
+| `placeholderText` | `string` | - | Placeholder text |
+
+---
+
+### FileUpload
+
+File upload with drag and drop.
+
+```tsx
+import { FileUpload } from '@carletonuniversity/rds'
+
+<FileUpload
+  name="documents"
+  accept=".pdf,.doc,.docx"
+  maxSize={5242880} // 5MB
+  multiple
+/>
+
+// Image upload
+<FileUpload
+  name="avatar"
+  accept="image/*"
+  maxSize={2097152} // 2MB
+/>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | - | Field name |
+| `accept` | `string` | - | Accepted file types |
+| `maxSize` | `number` | - | Max file size in bytes |
+| `multiple` | `boolean` | `false` | Allow multiple files |
+
+---
+
+### AutoSuggest
+
+Auto-suggestion input with custom suggestions.
+
+```tsx
+import { AutoSuggest } from '@carletonuniversity/rds'
+
+const suggestions = ['Apple', 'Banana', 'Cherry', 'Date']
+
+<AutoSuggest
+  name="fruit"
+  suggestions={suggestions}
+  placeholder="Type to search..."
+/>
+
+// With async suggestions
+<AutoSuggest
+  name="search"
+  onSuggestionsFetchRequested={async (query) => {
+    const results = await fetchSuggestions(query)
+    return results
+  }}
+/>
+```
+
+---
+
+### PlacesAutoComplete
+
+Google Places autocomplete for address input.
+
+```tsx
+import { PlacesAutoComplete } from '@carletonuniversity/rds'
+
+<PlacesAutoComplete
+  name="address"
+  placeholder="Enter address"
+  onPlaceSelected={(place) => {
+    setFieldValue('latitude', place.geometry.location.lat())
+    setFieldValue('longitude', place.geometry.location.lng())
+  }}
+/>
+```
+
+**Note:** Requires Google Maps API key configuration.
+
+---
+
+### InputAddon
+
+Input with prefix or suffix addon.
+
+```tsx
+import { InputAddon, Input } from '@carletonuniversity/rds'
+
+// Prefix
+<InputAddon prefix="$">
+  <Input name="price" type="number" />
+</InputAddon>
+
+// Suffix
+<InputAddon suffix=".ca">
+  <Input name="domain" />
+</InputAddon>
+
+// Both
+<InputAddon prefix="https://" suffix=".com">
+  <Input name="website" />
+</InputAddon>
+```
+
+---
+
+### HelperText
+
+Helper text display for additional field information.
+
+```tsx
+import { HelperText } from '@carletonuniversity/rds'
+
+<Form.Field name="password" label="Password">
+  <Input name="password" type="password" />
+  <HelperText>
+    Must be at least 8 characters with one uppercase letter
+  </HelperText>
+</Form.Field>
+```
+
+---
+
+## Validation
+
+### Yup Schema Validation
+
+RDS uses Yup for declarative validation schemas.
+
+```tsx
+import * as Yup from 'yup'
+
+const validationSchema = Yup.object({
+  // Required string
+  name: Yup.string()
+    .required('Name is required')
+    .min(2, 'Name must be at least 2 characters'),
+
+  // Email
+  email: Yup.string()
+    .email('Invalid email address')
+    .required('Email is required'),
+
+  // Phone (optional)
+  phone: Yup.string()
+    .matches(/^\d{10}$/, 'Phone must be 10 digits'),
+
+  // Number range
+  age: Yup.number()
+    .min(18, 'Must be at least 18')
+    .max(120, 'Must be under 120')
+    .required('Age is required'),
+
+  // Conditional validation
+  website: Yup.string()
+    .url('Must be a valid URL')
+    .when('hasWebsite', {
+      is: true,
+      then: (schema) => schema.required('Website is required'),
+    }),
+
+  // Array validation
+  tags: Yup.array()
+    .of(Yup.string())
+    .min(1, 'Select at least one tag'),
+
+  // Nested object
+  address: Yup.object({
+    street: Yup.string().required('Street is required'),
+    city: Yup.string().required('City is required'),
+    postalCode: Yup.string()
+      .matches(/^[A-Z]\d[A-Z] \d[A-Z]\d$/, 'Invalid postal code'),
+  }),
+})
+```
+
+### Built-in Validation Schemas
+
+RDS provides pre-built validation schemas in `/lib/helpers/`:
+
+```tsx
+import {
+  fileUploadValidationSchema,
+  imageUploadValidationSchema,
+} from '@carletonuniversity/rds'
+
+// File upload validation
+const schema = Yup.object({
+  document: fileUploadValidationSchema({
+    maxSize: 5242880, // 5MB
+    allowedTypes: ['application/pdf', 'application/msword'],
+  }),
+})
+
+// Image upload validation
+const schema = Yup.object({
+  avatar: imageUploadValidationSchema({
+    maxSize: 2097152, // 2MB
+    minWidth: 200,
+    minHeight: 200,
+  }),
+})
+```
+
+---
+
+## Form Patterns
+
+### Contact Form
+
+```tsx
+function ContactForm() {
+  const validationSchema = Yup.object({
+    name: Yup.string().required('Name is required'),
+    email: Yup.string().email().required('Email is required'),
+    message: Yup.string().required('Message is required').min(10),
+  })
+
+  return (
+    <Form
+      initialValues={{ name: '', email: '', message: '' }}
+      validationSchema={validationSchema}
+      onSubmit={async (values, { setSubmitting, resetForm }) => {
+        await submitContact(values)
+        resetForm()
+        setSubmitting(false)
+      }}
+    >
+      <Form.Field name="name" label="Name" required>
+        <Input name="name" />
+      </Form.Field>
+
+      <Form.Field name="email" label="Email" required>
+        <Input name="email" type="email" />
+      </Form.Field>
+
+      <Form.Field name="message" label="Message" required>
+        <TextArea name="message" rows={5} />
+      </Form.Field>
+
+      <Form.Button type="submit">Send Message</Form.Button>
+    </Form>
+  )
+}
+```
+
+### Registration Form
+
+```tsx
+function RegistrationForm() {
+  const validationSchema = Yup.object({
+    firstName: Yup.string().required(),
+    lastName: Yup.string().required(),
+    email: Yup.string().email().required(),
+    password: Yup.string().min(8).required(),
+    confirmPassword: Yup.string()
+      .oneOf([Yup.ref('password')], 'Passwords must match')
+      .required(),
+    agreeToTerms: Yup.boolean().oneOf([true], 'You must accept the terms'),
+  })
+
+  return (
+    <Form
+      initialValues={{
+        firstName: '',
+        lastName: '',
+        email: '',
+        password: '',
+        confirmPassword: '',
+        agreeToTerms: false,
+      }}
+      validationSchema={validationSchema}
+      onSubmit={handleRegister}
+    >
+      <Form.FieldGroup>
+        <Form.Field name="firstName" label="First Name" required>
+          <Input name="firstName" />
+        </Form.Field>
+        <Form.Field name="lastName" label="Last Name" required>
+          <Input name="lastName" />
+        </Form.Field>
+      </Form.FieldGroup>
+
+      <Form.Field name="email" label="Email" required>
+        <Input name="email" type="email" />
+      </Form.Field>
+
+      <Form.Field name="password" label="Password" required>
+        <Input name="password" type="password" />
+      </Form.Field>
+
+      <Form.Field name="confirmPassword" label="Confirm Password" required>
+        <Input name="confirmPassword" type="password" />
+      </Form.Field>
+
+      <Checkbox name="agreeToTerms" label="I agree to the terms and conditions" />
+
+      <Form.Button type="submit">Register</Form.Button>
+    </Form>
+  )
+}
+```
+
+### Event Form with Date/Time
+
+```tsx
+function EventForm() {
+  return (
+    <Form
+      initialValues={{
+        title: '',
+        startDate: null,
+        endDate: null,
+        location: '',
+        description: '',
+      }}
+      validationSchema={eventSchema}
+      onSubmit={handleCreateEvent}
+    >
+      <Form.Field name="title" label="Event Title" required>
+        <Input name="title" />
+      </Form.Field>
+
+      <Form.FieldGroup>
+        <Form.Field name="startDate" label="Start Date & Time" required>
+          <DateTime name="startDate" showTimeSelect />
+        </Form.Field>
+        <Form.Field name="endDate" label="End Date & Time" required>
+          <DateTime name="endDate" showTimeSelect />
+        </Form.Field>
+      </Form.FieldGroup>
+
+      <Form.Field name="location" label="Location">
+        <PlacesAutoComplete name="location" />
+      </Form.Field>
+
+      <Form.Field name="description" label="Description">
+        <TextArea name="description" rows={4} />
+      </Form.Field>
+
+      <Form.Button type="submit">Create Event</Form.Button>
+    </Form>
+  )
+}
+```
+
+---
+
+## Gutenberg Integration
+
+### Using Forms in Gutenberg Blocks
+
+When using RDS forms in WordPress Gutenberg blocks:
+
+```jsx
+// Block editor component
+import { Form, Input, Select } from '@carletonuniversity/rds'
+
+function MyBlockEdit({ attributes, setAttributes }) {
+  return (
+    <Form
+      initialValues={attributes}
+      onSubmit={(values) => setAttributes(values)}
+      enableReinitialize
+    >
+      <Form.Field name="title" label="Title">
+        <Input name="title" />
+      </Form.Field>
+
+      <Form.Field name="category" label="Category">
+        <Select
+          name="category"
+          options={categoryOptions}
+        />
+      </Form.Field>
+    </Form>
+  )
+}
+
+// Frontend component
+function MyBlockView({ attributes }) {
+  return (
+    <Form
+      initialValues={{}}
+      onSubmit={handleSubmit}
+    >
+      {/* Form fields */}
+    </Form>
+  )
+}
+```
+
+### Considerations
+
+1. **Server-side validation** - Always validate on the server
+2. **Nonce handling** - Use WordPress nonces for security
+3. **REST API** - Submit via WP REST API endpoints
+4. **Block attributes** - Map form values to block attributes
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**1. Field not updating**
+```tsx
+// Ensure name prop matches initialValues key
+<Input name="email" /> // Must have initialValues.email
+```
+
+**2. Validation not triggering**
+```tsx
+// Check schema field names match form field names
+const schema = Yup.object({
+  email: Yup.string().email() // Must match <Input name="email" />
+})
+```
+
+**3. Select not working with Formik**
+```tsx
+// Use the RDS Select component, not native <select>
+import { Select } from '@carletonuniversity/rds'
+```
+
+**4. Date values**
+```tsx
+// DateTime returns Date objects
+// Convert for API if needed
+onSubmit={(values) => {
+  const data = {
+    ...values,
+    startDate: values.startDate?.toISOString(),
+  }
+}}
+```
+
+### Debug Mode
+
+Enable Formik debug mode:
+
+```tsx
+import { useFormikContext } from 'formik'
+
+function FormDebug() {
+  const { values, errors, touched } = useFormikContext()
+
+  if (process.env.NODE_ENV !== 'development') return null
+
+  return (
+    <pre>
+      {JSON.stringify({ values, errors, touched }, null, 2)}
+    </pre>
+  )
+}
+```
+
+---
+
+## Related Documentation
+
+- [Components](./COMPONENTS.md) - UI components
+- [Validation Helpers](./UTILITIES.md) - Built-in validators
+- [Gutenberg Integration](./GUTENBERG.md) - WordPress blocks
diff --git a/docs/GUTENBERG.md b/docs/GUTENBERG.md
new file mode 100644
index 000000000..3f6d19b86
--- /dev/null
+++ b/docs/GUTENBERG.md
@@ -0,0 +1,844 @@
+# Gutenberg Integration Guide
+
+This guide covers how to use RDS components in WordPress Gutenberg blocks.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Setting Up a Block](#setting-up-a-block)
+- [Using RDS Components](#using-rds-components)
+- [Styling Considerations](#styling-considerations)
+- [Common Patterns](#common-patterns)
+- [Block Examples](#block-examples)
+- [Troubleshooting](#troubleshooting)
+- [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+RDS powers over 70 custom Gutenberg blocks for Carleton University websites. The component library is designed to be consumed by WordPress block plugins.
+
+### Integration Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    WordPress                         │
+│  ┌───────────────────────────────────────────────┐  │
+│  │              Gutenberg Editor                  │  │
+│  │  ┌─────────────────────────────────────────┐  │  │
+│  │  │         Custom Block Plugin              │  │  │
+│  │  │  ┌─────────────────────────────────┐    │  │  │
+│  │  │  │     RDS Components (React)       │    │  │  │
+│  │  │  └─────────────────────────────────┘    │  │  │
+│  │  └─────────────────────────────────────────┘  │  │
+│  └───────────────────────────────────────────────┘  │
+│  ┌───────────────────────────────────────────────┐  │
+│  │              Frontend (Theme)                  │  │
+│  │  ┌─────────────────────────────────────────┐  │  │
+│  │  │         RDS Styles (CSS)                 │  │  │
+│  │  └─────────────────────────────────────────┘  │  │
+│  └───────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────┘
+```
+
+### Key Concepts
+
+1. **Editor View** - React components in the block editor
+2. **Frontend View** - Rendered HTML on the public site
+3. **Block Attributes** - Data stored in the block
+4. **Block Controls** - Editor UI for configuring blocks
+
+---
+
+## Architecture
+
+### Package Distribution
+
+RDS is distributed via npm:
+
+```bash
+npm install @carletonuniversity/rds
+```
+
+### Export Formats
+
+| Format | File | Use Case |
+|--------|------|----------|
+| ES Modules | `dist/rds.es.js` | Modern bundlers |
+| UMD | `dist/rds.umd.js` | Script tags, older bundlers |
+| CSS | `dist/style.css` | Styles |
+| Types | `dist/main.d.ts` | TypeScript support |
+
+### Block Plugin Structure
+
+```
+my-blocks-plugin/
+├── src/
+│   ├── blocks/
+│   │   ├── alert/
+│   │   │   ├── index.js        # Block registration
+│   │   │   ├── edit.js         # Editor component
+│   │   │   ├── save.js         # Save component (or null for dynamic)
+│   │   │   └── block.json      # Block metadata
+│   │   └── card/
+│   │       └── ...
+│   └── index.js                # Entry point
+├── build/                      # Compiled assets
+├── package.json
+└── webpack.config.js           # or block.json build
+```
+
+---
+
+## Setting Up a Block
+
+### 1. Block Registration
+
+`block.json`:
+```json
+{
+  "$schema": "https://schemas.wp.org/trunk/block.json",
+  "apiVersion": 3,
+  "name": "cu/alert",
+  "version": "1.0.0",
+  "title": "Alert",
+  "category": "cu-blocks",
+  "icon": "warning",
+  "description": "Display an alert message",
+  "supports": {
+    "html": false
+  },
+  "attributes": {
+    "type": {
+      "type": "string",
+      "default": "info"
+    },
+    "title": {
+      "type": "string",
+      "default": ""
+    },
+    "content": {
+      "type": "string",
+      "default": ""
+    }
+  },
+  "textdomain": "cu-blocks",
+  "editorScript": "file:./index.js",
+  "editorStyle": "file:./index.css",
+  "style": "file:./style-index.css"
+}
+```
+
+### 2. Block Index
+
+`index.js`:
+```jsx
+import { registerBlockType } from '@wordpress/blocks'
+import Edit from './edit'
+import Save from './save'
+import metadata from './block.json'
+
+registerBlockType(metadata.name, {
+  edit: Edit,
+  save: Save,
+})
+```
+
+### 3. Edit Component
+
+`edit.js`:
+```jsx
+import { useBlockProps, InspectorControls } from '@wordpress/block-editor'
+import { PanelBody, SelectControl, TextControl } from '@wordpress/components'
+import { Alert } from '@carletonuniversity/rds'
+
+export default function Edit({ attributes, setAttributes }) {
+  const { type, title, content } = attributes
+  const blockProps = useBlockProps()
+
+  return (
+    <>
+      <InspectorControls>
+        <PanelBody title="Alert Settings">
+          <SelectControl
+            label="Alert Type"
+            value={type}
+            options={[
+              { label: 'Info', value: 'info' },
+              { label: 'Success', value: 'success' },
+              { label: 'Warning', value: 'warning' },
+              { label: 'Error', value: 'error' },
+            ]}
+            onChange={(value) => setAttributes({ type: value })}
+          />
+          <TextControl
+            label="Title"
+            value={title}
+            onChange={(value) => setAttributes({ title: value })}
+          />
+        </PanelBody>
+      </InspectorControls>
+
+      <div {...blockProps}>
+        <Alert type={type} title={title}>
+          {content || 'Enter alert content...'}
+        </Alert>
+      </div>
+    </>
+  )
+}
+```
+
+### 4. Save Component
+
+For static blocks:
+```jsx
+import { useBlockProps } from '@wordpress/block-editor'
+import { Alert } from '@carletonuniversity/rds'
+
+export default function Save({ attributes }) {
+  const { type, title, content } = attributes
+  const blockProps = useBlockProps.save()
+
+  return (
+    <div {...blockProps}>
+      <Alert type={type} title={title}>
+        {content}
+      </Alert>
+    </div>
+  )
+}
+```
+
+For dynamic blocks (PHP rendered):
+```jsx
+export default function Save() {
+  return null // Rendered by PHP
+}
+```
+
+---
+
+## Using RDS Components
+
+### Importing Components
+
+```jsx
+// Named imports (recommended)
+import { Button, Card, Alert } from '@carletonuniversity/rds'
+
+// Utilities
+import { utils } from '@carletonuniversity/rds'
+
+// Icons and assets
+import { iconNames, bgImageNames } from '@carletonuniversity/rds'
+```
+
+### Component Props to Block Attributes
+
+Map RDS component props to WordPress block attributes:
+
+```jsx
+// RDS Component
+<Button
+  color="red"
+  isSmall={false}
+  isFull={true}
+>
+  Click Me
+</Button>
+
+// Block Attributes
+{
+  "buttonColor": {
+    "type": "string",
+    "default": "red"
+  },
+  "isSmall": {
+    "type": "boolean",
+    "default": false
+  },
+  "isFull": {
+    "type": "boolean",
+    "default": true
+  },
+  "buttonText": {
+    "type": "string",
+    "default": "Click Me"
+  }
+}
+```
+
+### Composite Components
+
+For composite components like Card:
+
+```jsx
+import { Card } from '@carletonuniversity/rds'
+
+function CardBlock({ attributes }) {
+  const { imageUrl, title, excerpt, link } = attributes
+
+  return (
+    <Card>
+      {imageUrl && (
+        <Card.Figure>
+          <img src={imageUrl} alt={title} />
+        </Card.Figure>
+      )}
+      <Card.Body>
+        <Card.Header title={title} />
+        {excerpt && <Card.Excerpt text={excerpt} />}
+        {link && (
+          <Card.Footer>
+            <a href={link}>Read More</a>
+          </Card.Footer>
+        )}
+      </Card.Body>
+    </Card>
+  )
+}
+```
+
+---
+
+## Styling Considerations
+
+### Loading RDS Styles
+
+In your block plugin:
+
+```php
+// PHP: Enqueue RDS styles
+function enqueue_rds_styles() {
+    wp_enqueue_style(
+        'rds-styles',
+        plugins_url('node_modules/@carletonuniversity/rds/dist/style.css', __FILE__),
+        [],
+        '1.0.0'
+    );
+}
+add_action('wp_enqueue_scripts', 'enqueue_rds_styles');
+add_action('enqueue_block_editor_assets', 'enqueue_rds_styles');
+```
+
+Or in JavaScript:
+```jsx
+// Import styles in your block entry point
+import '@carletonuniversity/rds/dist/style.css'
+```
+
+### Style Conflicts
+
+RDS styles may conflict with WordPress defaults. Solutions:
+
+#### 1. Scoped Wrapper Class
+
+```jsx
+<div className="rds-scope">
+  <Alert type="info">Content</Alert>
+</div>
+```
+
+```css
+.rds-scope {
+  /* Reset WordPress styles */
+  all: initial;
+}
+
+.rds-scope * {
+  box-sizing: border-box;
+}
+```
+
+#### 2. Higher Specificity
+
+```css
+/* RDS overrides */
+.wp-block-cu-alert .cu-alert {
+  /* Increased specificity */
+}
+```
+
+#### 3. Important Flag (Use Sparingly)
+
+```css
+.cu-alert {
+  margin: 0 !important;
+}
+```
+
+### Editor vs Frontend Styles
+
+Some styles only apply in editor:
+
+```css
+/* Editor-only styles */
+.editor-styles-wrapper .cu-card {
+  /* Editor adjustments */
+}
+
+/* Frontend-only styles */
+.entry-content .cu-card {
+  /* Frontend adjustments */
+}
+```
+
+---
+
+## Common Patterns
+
+### Rich Text Integration
+
+```jsx
+import { RichText } from '@wordpress/block-editor'
+import { Alert } from '@carletonuniversity/rds'
+
+function AlertEdit({ attributes, setAttributes }) {
+  return (
+    <Alert type={attributes.type} title={attributes.title}>
+      <RichText
+        tagName="p"
+        value={attributes.content}
+        onChange={(content) => setAttributes({ content })}
+        placeholder="Enter alert content..."
+      />
+    </Alert>
+  )
+}
+```
+
+### Media Selection
+
+```jsx
+import { MediaUpload, MediaUploadCheck } from '@wordpress/block-editor'
+import { Button as WPButton } from '@wordpress/components'
+import { Card } from '@carletonuniversity/rds'
+
+function CardEdit({ attributes, setAttributes }) {
+  const { imageId, imageUrl } = attributes
+
+  return (
+    <Card>
+      <Card.Figure>
+        <MediaUploadCheck>
+          <MediaUpload
+            onSelect={(media) =>
+              setAttributes({ imageId: media.id, imageUrl: media.url })
+            }
+            allowedTypes={['image']}
+            value={imageId}
+            render={({ open }) => (
+              imageUrl ? (
+                <img src={imageUrl} onClick={open} alt="" />
+              ) : (
+                <WPButton onClick={open}>Select Image</WPButton>
+              )
+            )}
+          />
+        </MediaUploadCheck>
+      </Card.Figure>
+      <Card.Body>
+        {/* ... */}
+      </Card.Body>
+    </Card>
+  )
+}
+```
+
+### Link Controls
+
+```jsx
+import { __experimentalLinkControl as LinkControl } from '@wordpress/block-editor'
+import { Popover, Button as WPButton } from '@wordpress/components'
+import { useState } from '@wordpress/element'
+import { Button } from '@carletonuniversity/rds'
+
+function ButtonEdit({ attributes, setAttributes }) {
+  const [isLinkOpen, setIsLinkOpen] = useState(false)
+  const { url, text } = attributes
+
+  return (
+    <>
+      <Button
+        color="red"
+        onClick={() => setIsLinkOpen(true)}
+      >
+        {text || 'Add Text'}
+      </Button>
+
+      {isLinkOpen && (
+        <Popover onClose={() => setIsLinkOpen(false)}>
+          <LinkControl
+            value={{ url }}
+            onChange={({ url }) => setAttributes({ url })}
+          />
+        </Popover>
+      )}
+    </>
+  )
+}
+```
+
+### Inspector Controls Pattern
+
+```jsx
+import { InspectorControls } from '@wordpress/block-editor'
+import {
+  PanelBody,
+  PanelRow,
+  SelectControl,
+  ToggleControl,
+  RangeControl,
+  ColorPalette,
+} from '@wordpress/components'
+
+function BlockInspector({ attributes, setAttributes }) {
+  return (
+    <InspectorControls>
+      <PanelBody title="Display Settings" initialOpen={true}>
+        <SelectControl
+          label="Layout"
+          value={attributes.layout}
+          options={[
+            { label: 'Grid', value: 'grid' },
+            { label: 'List', value: 'list' },
+          ]}
+          onChange={(layout) => setAttributes({ layout })}
+        />
+
+        <RangeControl
+          label="Columns"
+          value={attributes.columns}
+          onChange={(columns) => setAttributes({ columns })}
+          min={1}
+          max={4}
+        />
+
+        <ToggleControl
+          label="Show Featured Image"
+          checked={attributes.showImage}
+          onChange={(showImage) => setAttributes({ showImage })}
+        />
+      </PanelBody>
+
+      <PanelBody title="Styling" initialOpen={false}>
+        <PanelRow>
+          <label>Background Color</label>
+        </PanelRow>
+        <ColorPalette
+          colors={[
+            { name: 'White', color: '#ffffff' },
+            { name: 'Light Gray', color: '#f3f4f6' },
+            { name: 'Red', color: '#bf112b' },
+          ]}
+          value={attributes.backgroundColor}
+          onChange={(color) => setAttributes({ backgroundColor: color })}
+        />
+      </PanelBody>
+    </InspectorControls>
+  )
+}
+```
+
+---
+
+## Block Examples
+
+### Alert Block
+
+```jsx
+// edit.js
+import { useBlockProps, InspectorControls, RichText } from '@wordpress/block-editor'
+import { PanelBody, SelectControl, TextControl } from '@wordpress/components'
+import { Alert } from '@carletonuniversity/rds'
+
+export default function Edit({ attributes, setAttributes }) {
+  const { type, title, content } = attributes
+
+  return (
+    <>
+      <InspectorControls>
+        <PanelBody title="Alert Settings">
+          <SelectControl
+            label="Type"
+            value={type}
+            options={[
+              { label: 'Info', value: 'info' },
+              { label: 'Success', value: 'success' },
+              { label: 'Warning', value: 'warning' },
+              { label: 'Error', value: 'error' },
+            ]}
+            onChange={(type) => setAttributes({ type })}
+          />
+          <TextControl
+            label="Title"
+            value={title}
+            onChange={(title) => setAttributes({ title })}
+          />
+        </PanelBody>
+      </InspectorControls>
+
+      <div {...useBlockProps()}>
+        <Alert type={type} title={title}>
+          <RichText
+            value={content}
+            onChange={(content) => setAttributes({ content })}
+            placeholder="Alert content..."
+          />
+        </Alert>
+      </div>
+    </>
+  )
+}
+```
+
+### Card Grid Block
+
+```jsx
+// edit.js
+import { useBlockProps, InspectorControls } from '@wordpress/block-editor'
+import { PanelBody, RangeControl, ToggleControl } from '@wordpress/components'
+import { useSelect } from '@wordpress/data'
+import { Card, Column } from '@carletonuniversity/rds'
+
+export default function Edit({ attributes, setAttributes }) {
+  const { columns, postType, count, showExcerpt, showImage } = attributes
+
+  const posts = useSelect((select) => {
+    return select('core').getEntityRecords('postType', postType, {
+      per_page: count,
+    })
+  }, [postType, count])
+
+  return (
+    <>
+      <InspectorControls>
+        <PanelBody title="Grid Settings">
+          <RangeControl
+            label="Columns"
+            value={columns}
+            onChange={(columns) => setAttributes({ columns })}
+            min={1}
+            max={4}
+          />
+          <RangeControl
+            label="Number of Posts"
+            value={count}
+            onChange={(count) => setAttributes({ count })}
+            min={1}
+            max={12}
+          />
+          <ToggleControl
+            label="Show Featured Image"
+            checked={showImage}
+            onChange={(showImage) => setAttributes({ showImage })}
+          />
+          <ToggleControl
+            label="Show Excerpt"
+            checked={showExcerpt}
+            onChange={(showExcerpt) => setAttributes({ showExcerpt })}
+          />
+        </PanelBody>
+      </InspectorControls>
+
+      <div {...useBlockProps()}>
+        <Column cols={String(columns)}>
+          {posts?.map((post) => (
+            <Card key={post.id}>
+              {showImage && post.featured_media && (
+                <Card.Figure>
+                  <img
+                    src={post._embedded?.['wp:featuredmedia']?.[0]?.source_url}
+                    alt={post.title.rendered}
+                  />
+                </Card.Figure>
+              )}
+              <Card.Body>
+                <Card.Header title={post.title.rendered} />
+                {showExcerpt && (
+                  <Card.Excerpt text={post.excerpt.rendered} />
+                )}
+              </Card.Body>
+            </Card>
+          ))}
+        </Column>
+      </div>
+    </>
+  )
+}
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Styles Not Loading
+
+```jsx
+// Ensure CSS is imported
+import '@carletonuniversity/rds/dist/style.css'
+
+// Or in PHP
+wp_enqueue_style('rds-styles', '...');
+```
+
+#### 2. React Version Mismatch
+
+```json
+// package.json - use WordPress's React
+{
+  "peerDependencies": {
+    "react": "*",
+    "react-dom": "*"
+  }
+}
+```
+
+```js
+// webpack.config.js
+externals: {
+  react: 'React',
+  'react-dom': 'ReactDOM',
+}
+```
+
+#### 3. Component Not Rendering
+
+```jsx
+// Check component import
+import { Alert } from '@carletonuniversity/rds' // Correct
+import Alert from '@carletonuniversity/rds/Alert' // May not work
+```
+
+#### 4. Block Validation Errors
+
+Block HTML must match exactly between edit and save:
+
+```jsx
+// If using dynamic rendering, save should return null
+export default function Save() {
+  return null
+}
+```
+
+#### 5. InnerBlocks Not Working
+
+```jsx
+import { InnerBlocks, useBlockProps } from '@wordpress/block-editor'
+
+// Edit
+function Edit() {
+  return (
+    <div {...useBlockProps()}>
+      <InnerBlocks allowedBlocks={['core/paragraph']} />
+    </div>
+  )
+}
+
+// Save
+function Save() {
+  return (
+    <div {...useBlockProps.save()}>
+      <InnerBlocks.Content />
+    </div>
+  )
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Use Block Attributes Wisely
+
+```json
+// Good: Specific, typed attributes
+{
+  "buttonColor": { "type": "string", "enum": ["red", "grey", "black"] },
+  "isFullWidth": { "type": "boolean", "default": false }
+}
+
+// Bad: Generic, unvalidated
+{
+  "settings": { "type": "object" }
+}
+```
+
+### 2. Provide Good Defaults
+
+```jsx
+// Block registration with defaults
+registerBlockType('cu/card', {
+  attributes: {
+    showImage: { type: 'boolean', default: true },
+    columns: { type: 'number', default: 3 },
+  },
+})
+```
+
+### 3. Use WordPress Controls
+
+```jsx
+// Use WordPress components for consistency
+import {
+  PanelBody,
+  SelectControl,
+  ToggleControl,
+} from '@wordpress/components'
+
+// Not RDS form components in editor
+```
+
+### 4. Handle Loading States
+
+```jsx
+function Edit({ attributes }) {
+  const posts = useSelect(/* ... */)
+
+  if (!posts) {
+    return <Spinner />
+  }
+
+  return <CardGrid posts={posts} />
+}
+```
+
+### 5. Accessibility
+
+```jsx
+// Include ARIA labels
+<div {...useBlockProps()} aria-label="Alert Block">
+  <Alert type={type} title={title}>
+    {content}
+  </Alert>
+</div>
+```
+
+### 6. Dynamic vs Static Blocks
+
+- **Static**: Content saved in post_content, no PHP needed
+- **Dynamic**: Rendered by PHP on each page load
+
+Choose dynamic for:
+- Frequently changing content
+- Content pulled from database
+- Complex logic
+
+Choose static for:
+- Simple content blocks
+- Better performance
+- Works without PHP
+
+---
+
+## Related Documentation
+
+- [Components](./COMPONENTS.md) - Component reference
+- [Forms](./FORMS.md) - Form components
+- [Styling](./STYLING.md) - CSS considerations
+- [WordPress Block Editor Handbook](https://developer.wordpress.org/block-editor/)
diff --git a/docs/IMPROVEMENTS.md b/docs/IMPROVEMENTS.md
new file mode 100644
index 000000000..088531b03
--- /dev/null
+++ b/docs/IMPROVEMENTS.md
@@ -0,0 +1,482 @@
+# Identified Issues and Improvements
+
+This document catalogs issues, inconsistencies, and improvement opportunities identified during the documentation review.
+
+## Table of Contents
+
+- [High Priority](#high-priority)
+- [Medium Priority](#medium-priority)
+- [Low Priority](#low-priority)
+- [Gutenberg-Specific Issues](#gutenberg-specific-issues)
+- [Technical Debt](#technical-debt)
+- [Documentation Gaps](#documentation-gaps)
+
+---
+
+## High Priority
+
+### 1. Large CSS Bundle Size
+
+**Issue:** The compiled CSS is ~150KB+ and includes many unused Tailwind utilities.
+
+**Impact:** Slower page loads, especially on mobile.
+
+**Recommendation:**
+- Implement SCSS migration (see [MIGRATION.md](./MIGRATION.md))
+- Use CSS-in-JS or CSS Modules for better tree-shaking
+- Extract critical CSS for above-the-fold content
+
+---
+
+### 2. No Component-Level Exports
+
+**Issue:** All components are bundled together in `rds.es.js`. Importing one component imports all.
+
+**Current:**
+```javascript
+// Imports entire library
+import { Button } from '@carletonuniversity/rds'
+```
+
+**Recommendation:**
+```javascript
+// Ideal: Import only what you need
+import { Button } from '@carletonuniversity/rds/components/Button'
+```
+
+**Action Items:**
+- [ ] Configure Vite/Rollup for per-component builds
+- [ ] Update package.json exports map
+- [ ] Test tree-shaking with different bundlers
+
+---
+
+### 3. Tailwind Class Conflicts in WordPress
+
+**Issue:** Tailwind's base styles conflict with WordPress core styles, causing:
+- Button styling inconsistencies
+- Form element conflicts
+- Typography issues in Gutenberg editor
+
+**Recommendation:**
+- Use CSS scoping with `.rds-scope` wrapper
+- Migrate to SCSS modules for better isolation
+- Document required CSS reset for WordPress
+
+---
+
+### 4. Missing TypeScript Strict Types for Some Components
+
+**Issue:** Some components have loose typing:
+- `any` types in event handlers
+- Missing return types
+- Optional props without explicit undefined
+
+**Files to Review:**
+- Form components
+- Card subcomponents
+- Navigation components
+
+**Recommendation:**
+- Enable `noImplicitAny` verification
+- Add explicit return types to all components
+- Use discriminated unions for variant props
+
+---
+
+## Medium Priority
+
+### 5. Inconsistent Prop Naming
+
+**Issue:** Props naming varies across components:
+
+| Component | Prop | Alternative |
+|-----------|------|-------------|
+| Button | `isDisabled` | `disabled` |
+| Input | `disabled` | `isDisabled` |
+| Card | `hasImage` | `showImage` |
+
+**Recommendation:**
+- Standardize on `is*` for boolean states
+- Standardize on `has*` for feature toggles
+- Document prop naming conventions
+
+---
+
+### 6. No Dark Mode Documentation
+
+**Issue:** Dark mode is supported via Tailwind's `selector` strategy but:
+- No documentation on how to enable
+- No Storybook stories showing dark variants
+- Some components may not have dark mode styles
+
+**Recommendation:**
+- Add dark mode toggle to Storybook
+- Create dark mode stories for all components
+- Document dark mode implementation
+
+---
+
+### 7. Missing Error Boundaries
+
+**Issue:** No error boundary components for graceful degradation.
+
+**Recommendation:**
+- Create `ErrorBoundary` component
+- Add error states to data-fetching components
+- Document error handling patterns
+
+---
+
+### 8. Accessibility Gaps
+
+**Issues Identified:**
+- Some interactive elements missing `aria-*` attributes
+- Focus management in modals/dialogs needs review
+- Color contrast not verified for all variants
+
+**Recommendation:**
+- Run full a11y audit with axe-core
+- Add keyboard navigation tests
+- Verify WCAG 2.1 AA compliance
+
+---
+
+### 9. No Loading/Skeleton Strategy Documentation
+
+**Issue:** 21 loader components exist but:
+- No documentation on when to use which
+- No loading state patterns documented
+- Inconsistent naming (`Loader` vs `Skeleton`)
+
+**Recommendation:**
+- Create loading state documentation
+- Standardize naming convention
+- Show loading state patterns in Storybook
+
+---
+
+### 10. Large Number of Dependencies
+
+**Issue:** Many runtime dependencies increase bundle size:
+- `formik` + `yup` for forms
+- `react-select` for dropdowns
+- `react-player` for video
+- `@react-google-maps/api` for maps
+
+**Recommendation:**
+- Audit dependency usage
+- Consider lighter alternatives
+- Make heavy dependencies optional/lazy-loaded
+
+---
+
+## Low Priority
+
+### 11. Storybook Organization
+
+**Issue:** Stories could be better organized:
+- No consistent story categories
+- Some components lack comprehensive stories
+- Missing interaction tests
+
+**Recommendation:**
+- Reorganize into clear categories
+- Add interaction tests to critical components
+- Create "Examples" section for complex use cases
+
+---
+
+### 12. Test Coverage Gaps
+
+**Issue:** Not all components have Cypress tests.
+
+**Recommendation:**
+- Set coverage targets per component type
+- Add tests for untested components
+- Set up coverage reporting in CI
+
+---
+
+### 13. Missing PropTypes for Runtime Validation
+
+**Issue:** TypeScript provides compile-time checks but no runtime validation for JavaScript consumers.
+
+**Recommendation:**
+- Consider adding PropTypes for critical components
+- Or document TypeScript requirement clearly
+
+---
+
+### 14. No Changelog Automation
+
+**Issue:** Changelog requires manual updates.
+
+**Recommendation:**
+- Implement conventional-changelog
+- Auto-generate changelog from commits
+- Add changelog CI step
+
+---
+
+### 15. Asset Management
+
+**Issue:** Icons and images are stored in `public/` but:
+- Large icon list impacts bundle
+- No lazy loading for images
+- Background images not documented
+
+**Recommendation:**
+- Lazy load icon list
+- Document available assets
+- Consider SVG sprite for icons
+
+---
+
+## Gutenberg-Specific Issues
+
+### G1. No Direct Gutenberg Integration
+
+**Issue:** RDS doesn't include WordPress-specific code. Blocks are in separate repository.
+
+**Impact:**
+- Duplicated effort in block plugins
+- Inconsistent implementation across 70+ blocks
+- Hard to maintain compatibility
+
+**Recommendation:**
+- Create `@carletonuniversity/rds-blocks` package
+- Provide block wrapper components
+- Share block registration patterns
+
+---
+
+### G2. WordPress Style Conflicts
+
+**Issue:** Tailwind reset conflicts with WordPress styles.
+
+**Specific Conflicts:**
+```css
+/* Tailwind resets buttons */
+button { background: transparent; }
+
+/* WordPress expects */
+.button { /* WordPress styles */ }
+
+/* Gutenberg editor */
+.block-editor { /* May override RDS */ }
+```
+
+**Recommendation:**
+- Document CSS reset requirements
+- Provide WordPress-specific stylesheet
+- Use higher specificity for RDS styles
+
+---
+
+### G3. React Version Mismatch
+
+**Issue:** RDS uses React 19, WordPress uses React 18.
+
+**Impact:** Potential compatibility issues in block editor.
+
+**Recommendation:**
+- Test with WordPress React version
+- Document React version requirements
+- Consider React 18 compatibility mode
+
+---
+
+### G4. Block Attribute Type Mismatches
+
+**Issue:** Component props don't always align with WordPress block attributes.
+
+**Example:**
+```typescript
+// RDS Component
+interface CardProps {
+  image: { src: string; alt: string }
+}
+
+// Block Attribute
+{
+  imageId: { type: 'number' },
+  imageUrl: { type: 'string' },
+}
+```
+
+**Recommendation:**
+- Create prop-to-attribute mapping utilities
+- Document common attribute patterns
+- Provide TypeScript types for block attributes
+
+---
+
+### G5. Server-Side Rendering Gaps
+
+**Issue:** Some components may not work with WordPress PHP rendering.
+
+**Components to Review:**
+- Components using browser APIs
+- Components with client-side state
+- Interactive components (forms, modals)
+
+**Recommendation:**
+- Document SSR compatibility per component
+- Provide PHP render alternatives
+- Mark client-only components clearly
+
+---
+
+## Technical Debt
+
+### T1. Legacy CSS Files
+
+**Files:**
+- `public/index.css` (151KB) - appears to be precompiled CSS
+- Multiple `styles.css` files with mixed approaches
+
+**Recommendation:**
+- Audit CSS file usage
+- Remove unused CSS files
+- Consolidate CSS architecture
+
+---
+
+### T2. Mixed Export Patterns
+
+**Issue:** Some files use default exports, others named exports.
+
+**Recommendation:**
+- Standardize on named exports
+- Update barrel exports in `main.ts`
+- Document export conventions
+
+---
+
+### T3. Utility Class Duplication
+
+**Issue:** `propClasses.tsx` duplicates Tailwind class definitions.
+
+**Recommendation:**
+- Use CSS custom properties instead
+- Remove after SCSS migration
+- Or generate from Tailwind config
+
+---
+
+### T4. No Build Caching
+
+**Issue:** Full rebuild on every change.
+
+**Recommendation:**
+- Enable Vite caching
+- Consider incremental TypeScript builds
+- Add Storybook build caching
+
+---
+
+### T5. Missing Code Splitting
+
+**Issue:** Heavy components loaded upfront.
+
+**Components to Split:**
+- Form components (Formik)
+- Map components (Google Maps)
+- Video components (react-player)
+
+**Recommendation:**
+- Implement React.lazy for heavy components
+- Document dynamic import patterns
+- Test loading states
+
+---
+
+## Documentation Gaps
+
+### D1. Missing API Reference
+
+**Issue:** No auto-generated API documentation from TypeScript.
+
+**Recommendation:**
+- Set up TypeDoc or similar
+- Generate prop tables automatically
+- Keep API docs in sync
+
+---
+
+### D2. No Migration Guide from Older Versions
+
+**Issue:** No upgrade path documentation.
+
+**Recommendation:**
+- Document breaking changes per version
+- Provide codemods for major changes
+- Create upgrade guide
+
+---
+
+### D3. Missing Troubleshooting Guide
+
+**Recommendation:** Create common issues and solutions doc covering:
+- Installation problems
+- Style conflicts
+- TypeScript errors
+- Build issues
+
+---
+
+### D4. No Performance Guide
+
+**Recommendation:** Document:
+- Bundle size optimization
+- Lazy loading patterns
+- Image optimization
+- Component memoization
+
+---
+
+## Action Plan
+
+### Immediate (Next Sprint)
+
+1. [ ] Document dark mode usage
+2. [ ] Add TypeScript strict checks review
+3. [ ] Create loading state documentation
+
+### Short Term (1-2 Months)
+
+1. [ ] Implement per-component exports
+2. [ ] Run accessibility audit
+3. [ ] Standardize prop naming
+
+### Medium Term (3-6 Months)
+
+1. [ ] Begin SCSS migration
+2. [ ] Create Gutenberg integration package
+3. [ ] Add comprehensive tests
+
+### Long Term (6+ Months)
+
+1. [ ] Complete SCSS migration
+2. [ ] Full Gutenberg compatibility
+3. [ ] Performance optimization
+
+---
+
+## Tracking
+
+Use issue labels to track:
+- `priority:high` / `priority:medium` / `priority:low`
+- `type:bug` / `type:enhancement` / `type:docs`
+- `component:*` for component-specific issues
+- `gutenberg` for WordPress-specific issues
+
+---
+
+## Related Documentation
+
+- [Migration Plan](./MIGRATION.md) - Tailwind to SCSS migration
+- [Gutenberg Guide](./GUTENBERG.md) - WordPress integration
+- [Testing](./TESTING.md) - Testing requirements
+- [Contributing](./CONTRIBUTING.md) - How to contribute fixes
diff --git a/docs/LAYOUTS.md b/docs/LAYOUTS.md
new file mode 100644
index 000000000..bce5a014c
--- /dev/null
+++ b/docs/LAYOUTS.md
@@ -0,0 +1,601 @@
+# Layout Components
+
+Layout components provide structural elements for building page layouts. They handle responsive behavior, spacing, and content organization.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Article](#article)
+- [Aside](#aside)
+- [Body](#body)
+- [Column](#column)
+- [FloatBox](#floatbox)
+- [ImageCover](#imagecover)
+- [Main](#main)
+- [Section](#section)
+- [StackedList](#stackedlist)
+- [WideWave](#widewave)
+- [Layout Patterns](#layout-patterns)
+
+---
+
+## Overview
+
+Layout components wrap content and provide:
+
+- **Responsive grid systems** - Adapt to different screen sizes
+- **Max-width constraints** - Control content width
+- **Spacing utilities** - Consistent padding and margins
+- **Semantic HTML** - Proper document structure
+
+### Import
+
+```tsx
+import {
+  Article,
+  Aside,
+  Body,
+  Column,
+  FloatBox,
+  ImageCover,
+  Main,
+  Section,
+  StackedList,
+  WideWave,
+} from '@carletonuniversity/rds'
+```
+
+---
+
+## Article
+
+Wrapper for article content, providing proper semantic HTML and typography styles.
+
+```tsx
+import { Article } from '@carletonuniversity/rds'
+
+<Article>
+  <h1>Article Title</h1>
+  <p>Article content with proper typography styling...</p>
+</Article>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Article content |
+| `className` | `string` | - | Additional CSS classes |
+
+**Use Cases:**
+- Blog posts
+- News articles
+- Documentation pages
+- Long-form content
+
+---
+
+## Aside
+
+Sidebar or complementary content area.
+
+```tsx
+import { Aside } from '@carletonuniversity/rds'
+
+<div className="flex">
+  <Main>
+    <p>Main content</p>
+  </Main>
+  <Aside>
+    <h3>Related Links</h3>
+    <ul>
+      <li><a href="#">Link 1</a></li>
+      <li><a href="#">Link 2</a></li>
+    </ul>
+  </Aside>
+</div>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Sidebar content |
+| `position` | `'left' \| 'right'` | `'right'` | Sidebar position |
+| `width` | `'narrow' \| 'wide'` | `'narrow'` | Sidebar width |
+| `className` | `string` | - | Additional CSS classes |
+
+**Use Cases:**
+- Navigation sidebars
+- Related content
+- Filter panels
+- Supplementary information
+
+---
+
+## Body
+
+Page body wrapper that provides base styling and layout constraints.
+
+```tsx
+import { Body } from '@carletonuniversity/rds'
+
+<Body>
+  <Nav>...</Nav>
+  <Main>...</Main>
+  <Footer>...</Footer>
+</Body>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Page content |
+| `className` | `string` | - | Additional CSS classes |
+
+**Use Cases:**
+- Root layout wrapper
+- Provides base typography
+- Sets up CSS custom properties
+
+---
+
+## Column
+
+Responsive grid column system for creating multi-column layouts.
+
+```tsx
+import { Column } from '@carletonuniversity/rds'
+
+// Two columns
+<Column cols="2">
+  <div>Column 1</div>
+  <div>Column 2</div>
+</Column>
+
+// Three columns with gap
+<Column cols="3" gap="lg">
+  <div>Column 1</div>
+  <div>Column 2</div>
+  <div>Column 3</div>
+</Column>
+
+// Responsive columns
+<Column cols="1" md="2" lg="3">
+  <div>Responsive columns</div>
+  <div>Stack on mobile</div>
+  <div>Grid on desktop</div>
+</Column>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `cols` | `'1' \| '2' \| '3' \| '4' \| '6' \| '12'` | `'1'` | Number of columns |
+| `sm` | `string` | - | Columns at sm breakpoint |
+| `md` | `string` | - | Columns at md breakpoint |
+| `lg` | `string` | - | Columns at lg breakpoint |
+| `xl` | `string` | - | Columns at xl breakpoint |
+| `gap` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Grid gap size |
+| `children` | `ReactNode` | - | Column content |
+| `className` | `string` | - | Additional CSS classes |
+
+**Grid Gap Sizes:**
+| Value | Size |
+|-------|------|
+| `none` | 0 |
+| `sm` | 0.5rem (8px) |
+| `md` | 1rem (16px) |
+| `lg` | 1.5rem (24px) |
+| `xl` | 2rem (32px) |
+
+**Use Cases:**
+- Card grids
+- Feature lists
+- Image galleries
+- Multi-column text
+
+---
+
+## FloatBox
+
+Floating content box that can be positioned within text content.
+
+```tsx
+import { FloatBox } from '@carletonuniversity/rds'
+
+<Article>
+  <p>Main article text...</p>
+
+  <FloatBox position="right" width="sm">
+    <img src="/sidebar-image.jpg" alt="Related" />
+    <p>Image caption or sidebar content</p>
+  </FloatBox>
+
+  <p>Text wraps around the floating box...</p>
+</Article>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `'left' \| 'right'` | `'right'` | Float direction |
+| `width` | `'sm' \| 'md' \| 'lg'` | `'md'` | Box width |
+| `children` | `ReactNode` | - | Box content |
+| `className` | `string` | - | Additional CSS classes |
+
+**Use Cases:**
+- Pull quotes
+- Sidebar images
+- Related content boxes
+- Quick facts
+
+---
+
+## ImageCover
+
+Full-screen image background with overlay content.
+
+```tsx
+import { ImageCover } from '@carletonuniversity/rds'
+
+<ImageCover
+  src="/hero-image.jpg"
+  alt="Hero background"
+  overlay="dark"
+>
+  <h1>Hero Title</h1>
+  <p>Hero description text</p>
+  <Button>Call to Action</Button>
+</ImageCover>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | - | Background image URL |
+| `alt` | `string` | - | Image alt text |
+| `overlay` | `'none' \| 'light' \| 'dark'` | `'dark'` | Overlay style |
+| `height` | `'full' \| 'half' \| 'auto'` | `'full'` | Section height |
+| `position` | `'center' \| 'top' \| 'bottom'` | `'center'` | Content position |
+| `children` | `ReactNode` | - | Overlay content |
+| `className` | `string` | - | Additional CSS classes |
+
+**Overlay Options:**
+| Value | Effect |
+|-------|--------|
+| `none` | No overlay |
+| `light` | White semi-transparent overlay |
+| `dark` | Black semi-transparent overlay |
+
+**Use Cases:**
+- Hero sections
+- Full-bleed images
+- Landing pages
+- Campaign pages
+
+---
+
+## Main
+
+Main content area wrapper with semantic `<main>` element.
+
+```tsx
+import { Main } from '@carletonuniversity/rds'
+
+<Body>
+  <Nav>...</Nav>
+  <Main>
+    <Section>
+      <h1>Page Title</h1>
+      <p>Main page content</p>
+    </Section>
+  </Main>
+  <Footer>...</Footer>
+</Body>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | - | Main content |
+| `className` | `string` | - | Additional CSS classes |
+
+**Use Cases:**
+- Primary content wrapper
+- Accessibility landmark
+- Skip-link target
+
+---
+
+## Section
+
+Content section with max-width constraints and spacing.
+
+```tsx
+import { Section } from '@carletonuniversity/rds'
+
+// Default section
+<Section>
+  <h2>Section Title</h2>
+  <p>Section content...</p>
+</Section>
+
+// Full width section
+<Section maxWidth="full">
+  <ImageGrid images={images} />
+</Section>
+
+// Narrow section
+<Section maxWidth="narrow">
+  <Article>
+    <p>Narrow content for readability...</p>
+  </Article>
+</Section>
+
+// With background
+<Section bgColor="grey-50">
+  <h2>Highlighted Section</h2>
+</Section>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `maxWidth` | `'narrow' \| 'small' \| 'base' \| 'large' \| 'full' \| '7xl'` | `'7xl'` | Max width constraint |
+| `bgColor` | `string` | - | Background color class |
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Vertical padding |
+| `children` | `ReactNode` | - | Section content |
+| `className` | `string` | - | Additional CSS classes |
+
+**Max Width Values:**
+| Value | Width |
+|-------|-------|
+| `narrow` | 640px |
+| `small` | 768px |
+| `base` | 1024px |
+| `large` | 1280px |
+| `7xl` | 1536px |
+| `full` | 100% |
+
+**Use Cases:**
+- Page sections
+- Content containers
+- Feature areas
+- Alternating backgrounds
+
+---
+
+## StackedList
+
+Vertical list layout with consistent spacing.
+
+```tsx
+import { StackedList } from '@carletonuniversity/rds'
+
+<StackedList>
+  <Listing>...</Listing>
+  <Listing>...</Listing>
+  <Listing>...</Listing>
+</StackedList>
+
+// With dividers
+<StackedList hasDividers>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</StackedList>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `hasDividers` | `boolean` | `false` | Show dividers between items |
+| `spacing` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Item spacing |
+| `children` | `ReactNode` | - | List items |
+| `className` | `string` | - | Additional CSS classes |
+
+**Use Cases:**
+- News listings
+- Search results
+- Event lists
+- Feed displays
+
+---
+
+## WideWave
+
+Wave decoration background layout for visual interest.
+
+```tsx
+import { WideWave } from '@carletonuniversity/rds'
+
+<WideWave color="red" position="top">
+  <Section>
+    <h2>Featured Content</h2>
+    <p>Content with wave decoration above</p>
+  </Section>
+</WideWave>
+```
+
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `color` | `'red' \| 'grey' \| 'white'` | `'red'` | Wave color |
+| `position` | `'top' \| 'bottom' \| 'both'` | `'top'` | Wave position |
+| `children` | `ReactNode` | - | Section content |
+| `className` | `string` | - | Additional CSS classes |
+
+**Use Cases:**
+- Section dividers
+- Call-to-action areas
+- Visual breaks
+- Brand elements
+
+---
+
+## Layout Patterns
+
+### Basic Page Layout
+
+```tsx
+import { Body, Main, Section, Nav, FooterStandard } from '@carletonuniversity/rds'
+
+function PageLayout({ children }) {
+  return (
+    <Body>
+      <Nav>...</Nav>
+      <Main>
+        <Section>
+          {children}
+        </Section>
+      </Main>
+      <FooterStandard>...</FooterStandard>
+    </Body>
+  )
+}
+```
+
+### Two-Column Layout
+
+```tsx
+import { Main, Section, Column, Aside } from '@carletonuniversity/rds'
+
+function TwoColumnLayout({ content, sidebar }) {
+  return (
+    <Main>
+      <Section>
+        <div className="flex gap-8">
+          <div className="flex-1">
+            {content}
+          </div>
+          <Aside width="narrow">
+            {sidebar}
+          </Aside>
+        </div>
+      </Section>
+    </Main>
+  )
+}
+```
+
+### Card Grid Layout
+
+```tsx
+import { Section, Column, Card } from '@carletonuniversity/rds'
+
+function CardGrid({ cards }) {
+  return (
+    <Section>
+      <Column cols="1" md="2" lg="3" gap="lg">
+        {cards.map((card) => (
+          <Card key={card.id}>
+            <Card.Figure>
+              <img src={card.image} alt={card.title} />
+            </Card.Figure>
+            <Card.Body>
+              <Card.Header title={card.title} />
+              <Card.Excerpt text={card.excerpt} />
+            </Card.Body>
+          </Card>
+        ))}
+      </Column>
+    </Section>
+  )
+}
+```
+
+### Hero + Content Layout
+
+```tsx
+import { ImageCover, Section, Article } from '@carletonuniversity/rds'
+
+function HeroPage({ hero, content }) {
+  return (
+    <>
+      <ImageCover
+        src={hero.image}
+        alt={hero.alt}
+        height="half"
+      >
+        <h1>{hero.title}</h1>
+      </ImageCover>
+
+      <Section maxWidth="narrow">
+        <Article>
+          {content}
+        </Article>
+      </Section>
+    </>
+  )
+}
+```
+
+### Alternating Sections
+
+```tsx
+import { Section, WideWave, TextImage } from '@carletonuniversity/rds'
+
+function AlternatingSections({ sections }) {
+  return (
+    <>
+      {sections.map((section, index) => (
+        <Section
+          key={index}
+          bgColor={index % 2 === 0 ? 'white' : 'grey-50'}
+        >
+          <TextImage
+            title={section.title}
+            content={section.content}
+            image={section.image}
+            imagePosition={index % 2 === 0 ? 'right' : 'left'}
+          />
+        </Section>
+      ))}
+    </>
+  )
+}
+```
+
+---
+
+## Responsive Behavior
+
+All layout components are responsive by default:
+
+| Breakpoint | Width | Typical Use |
+|------------|-------|-------------|
+| `sm` | 640px | Mobile landscape |
+| `md` | 768px | Tablets |
+| `lg` | 1024px | Small laptops |
+| `xl` | 1280px | Desktops |
+| `2xl` | 1536px | Large screens |
+
+### Mobile-First Approach
+
+Components use mobile-first responsive design:
+
+```tsx
+// Stacks on mobile, 2 columns on tablet, 3 on desktop
+<Column cols="1" md="2" lg="3">
+  ...
+</Column>
+```
+
+---
+
+## Accessibility
+
+Layout components include:
+
+- Semantic HTML elements (`<main>`, `<aside>`, `<article>`, `<section>`)
+- Proper heading hierarchy support
+- Skip-link compatibility
+- Screen reader landmarks
+- Keyboard navigation support
+
+---
+
+## Related Documentation
+
+- [Components](./COMPONENTS.md) - UI components
+- [Styling](./STYLING.md) - CSS and styling
+- [Gutenberg Integration](./GUTENBERG.md) - WordPress blocks
diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
new file mode 100644
index 000000000..3f3b10a3b
--- /dev/null
+++ b/docs/MIGRATION.md
@@ -0,0 +1,831 @@
+# Migration Plan: Tailwind CSS to SCSS
+
+This document outlines the strategy for migrating RDS from Tailwind CSS to SCSS modules.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Motivation](#motivation)
+- [Migration Strategy](#migration-strategy)
+- [Phase 1: Foundation](#phase-1-foundation)
+- [Phase 2: Design Tokens](#phase-2-design-tokens)
+- [Phase 3: Component Migration](#phase-3-component-migration)
+- [Phase 4: Cleanup](#phase-4-cleanup)
+- [Technical Details](#technical-details)
+- [Component Migration Guide](#component-migration-guide)
+- [Testing Strategy](#testing-strategy)
+- [Rollback Plan](#rollback-plan)
+
+---
+
+## Overview
+
+### Current State
+
+- **Tailwind CSS 3.4** with custom theme preset (`rds-tailwind-theme`)
+- **51 components** using Tailwind utility classes
+- **~150KB+ CSS** bundle (uncompressed)
+- Tight coupling between styling and `rds-tailwind-theme` package
+
+### Target State
+
+- **SCSS modules** with CSS custom properties
+- **Isolated component styles** that don't leak
+- **Smaller CSS bundle** through better tree-shaking
+- **Easier customization** without Tailwind knowledge
+- **Better Gutenberg compatibility**
+
+### Timeline Estimate
+
+| Phase | Duration | Components |
+|-------|----------|------------|
+| Foundation | 2-3 weeks | Setup, tokens |
+| Design Tokens | 1-2 weeks | Variables, mixins |
+| Component Migration | 8-12 weeks | 51 components |
+| Cleanup | 1-2 weeks | Remove Tailwind |
+| **Total** | **12-19 weeks** | |
+
+---
+
+## Motivation
+
+### Why Move Away from Tailwind?
+
+#### 1. Bundle Size
+```
+Current:  ~150KB+ (includes many unused utilities)
+Target:   ~50-80KB (only used styles)
+```
+
+#### 2. WordPress/Gutenberg Conflicts
+Tailwind's reset and utilities often conflict with WordPress core styles:
+- Button styling overrides
+- Form element conflicts
+- Typography clashes
+
+#### 3. Customization Difficulty
+Currently requires:
+- Understanding Tailwind config
+- Modifying `rds-tailwind-theme` package
+- Rebuilding entire library
+
+With SCSS:
+- Override CSS custom properties
+- No build step required
+- Standard CSS knowledge
+
+#### 4. Style Isolation
+Current issues:
+- Global styles can leak between components
+- Hard to scope styles in WordPress
+
+With CSS Modules:
+- Automatic class name scoping
+- No style leakage
+- Better encapsulation
+
+#### 5. Developer Experience
+- Standard SCSS is more widely known than Tailwind
+- Better IDE support and autocomplete
+- Easier debugging (readable class names)
+
+---
+
+## Migration Strategy
+
+### Approach: Gradual Migration
+
+**NOT** a big-bang rewrite. Instead:
+
+1. Add SCSS infrastructure alongside Tailwind
+2. Migrate components one at a time
+3. Maintain backward compatibility
+4. Remove Tailwind only after all components migrated
+
+### Migration Order
+
+Prioritize by:
+1. **Complexity** - Simple components first
+2. **Dependencies** - Components used by others first
+3. **Gutenberg usage** - High-usage blocks prioritized
+
+```
+Phase 1: Icon, Badge, Alert, Avatar
+Phase 2: Button, ButtonGroup
+Phase 3: Card (and all subcomponents)
+Phase 4: Listing (and all subcomponents)
+Phase 5: Form components
+Phase 6: Nav components
+Phase 7: Layout components
+Phase 8: Remaining components
+```
+
+---
+
+## Phase 1: Foundation
+
+### 1.1 Install Dependencies
+
+```bash
+npm install -D sass sass-loader
+```
+
+### 1.2 Configure Vite for SCSS
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  css: {
+    preprocessorOptions: {
+      scss: {
+        additionalData: `@import "./lib/styles/abstracts/_index.scss";`,
+      },
+    },
+    modules: {
+      localsConvention: 'camelCase',
+    },
+  },
+})
+```
+
+### 1.3 Create SCSS Directory Structure
+
+```
+lib/styles/
+├── abstracts/
+│   ├── _index.scss           # Forward all abstracts
+│   ├── _variables.scss       # Design tokens
+│   ├── _mixins.scss          # Reusable mixins
+│   ├── _functions.scss       # SCSS functions
+│   └── _breakpoints.scss     # Responsive breakpoints
+├── base/
+│   ├── _index.scss
+│   ├── _reset.scss           # CSS reset
+│   ├── _typography.scss      # Base typography
+│   └── _utilities.scss       # Utility classes
+├── components/
+│   └── (component SCSS files)
+└── main.scss                 # Main entry point
+```
+
+### 1.4 Create Initial Abstract Files
+
+```scss
+// abstracts/_variables.scss
+
+// Colors
+$cu-red: #bf112b;
+$cu-red-dark: #9a0e23;
+$cu-black: #262626;
+$cu-white: #ffffff;
+
+// Gray scale
+$gray-50: #f9fafb;
+$gray-100: #f3f4f6;
+$gray-200: #e5e7eb;
+$gray-300: #d1d5db;
+$gray-400: #9ca3af;
+$gray-500: #6b7280;
+$gray-600: #4b5563;
+$gray-700: #374151;
+$gray-800: #1f2937;
+$gray-900: #111827;
+
+// Semantic colors
+$color-success: #10b981;
+$color-warning: #f59e0b;
+$color-error: #ef4444;
+$color-info: #3b82f6;
+
+// Spacing
+$spacing-unit: 0.25rem; // 4px
+$spacing-1: $spacing-unit * 1;   // 4px
+$spacing-2: $spacing-unit * 2;   // 8px
+$spacing-3: $spacing-unit * 3;   // 12px
+$spacing-4: $spacing-unit * 4;   // 16px
+$spacing-5: $spacing-unit * 5;   // 20px
+$spacing-6: $spacing-unit * 6;   // 24px
+$spacing-8: $spacing-unit * 8;   // 32px
+$spacing-10: $spacing-unit * 10; // 40px
+$spacing-12: $spacing-unit * 12; // 48px
+$spacing-16: $spacing-unit * 16; // 64px
+
+// Typography
+$font-sans: 'Open Sans', system-ui, sans-serif;
+$font-serif: 'Georgia', serif;
+$font-mono: 'Fira Code', monospace;
+
+$text-xs: 0.75rem;
+$text-sm: 0.875rem;
+$text-base: 1rem;
+$text-lg: 1.125rem;
+$text-xl: 1.25rem;
+$text-2xl: 1.5rem;
+$text-3xl: 1.875rem;
+$text-4xl: 2.25rem;
+$text-5xl: 3rem;
+
+// Border radius
+$radius-sm: 0.125rem;
+$radius-md: 0.375rem;
+$radius-lg: 0.5rem;
+$radius-xl: 0.75rem;
+$radius-full: 9999px;
+
+// Shadows
+$shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+$shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+$shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+
+// Transitions
+$transition-fast: 150ms;
+$transition-base: 200ms;
+$transition-slow: 300ms;
+```
+
+```scss
+// abstracts/_breakpoints.scss
+
+$breakpoints: (
+  'sm': 640px,
+  'md': 768px,
+  'lg': 1024px,
+  'xl': 1280px,
+  '2xl': 1536px,
+);
+
+@mixin respond-to($breakpoint) {
+  @if map-has-key($breakpoints, $breakpoint) {
+    @media (min-width: map-get($breakpoints, $breakpoint)) {
+      @content;
+    }
+  } @else {
+    @warn "Breakpoint '#{$breakpoint}' not found.";
+  }
+}
+
+// Usage: @include respond-to('md') { ... }
+```
+
+```scss
+// abstracts/_mixins.scss
+
+// Flex center
+@mixin flex-center {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+// Visually hidden (accessible)
+@mixin visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+// Focus ring
+@mixin focus-ring($color: $cu-red) {
+  &:focus {
+    outline: none;
+    box-shadow: 0 0 0 3px rgba($color, 0.3);
+  }
+}
+
+// Button base
+@mixin button-base {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: $spacing-2 $spacing-4;
+  font-weight: 500;
+  font-size: $text-sm;
+  line-height: 1.5;
+  border-radius: $radius-md;
+  border: none;
+  cursor: pointer;
+  transition: all $transition-base ease-in-out;
+
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+// Truncate text
+@mixin truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+// Aspect ratio
+@mixin aspect-ratio($width, $height) {
+  aspect-ratio: #{$width} / #{$height};
+}
+```
+
+---
+
+## Phase 2: Design Tokens
+
+### 2.1 CSS Custom Properties
+
+Create CSS custom properties for runtime theming:
+
+```scss
+// base/_root.scss
+
+:root {
+  // Colors
+  --rds-color-primary: #{$cu-red};
+  --rds-color-primary-dark: #{$cu-red-dark};
+  --rds-color-black: #{$cu-black};
+  --rds-color-white: #{$cu-white};
+
+  // Gray scale
+  --rds-gray-50: #{$gray-50};
+  --rds-gray-100: #{$gray-100};
+  --rds-gray-200: #{$gray-200};
+  --rds-gray-300: #{$gray-300};
+  --rds-gray-400: #{$gray-400};
+  --rds-gray-500: #{$gray-500};
+  --rds-gray-600: #{$gray-600};
+  --rds-gray-700: #{$gray-700};
+  --rds-gray-800: #{$gray-800};
+  --rds-gray-900: #{$gray-900};
+
+  // Semantic
+  --rds-color-success: #{$color-success};
+  --rds-color-warning: #{$color-warning};
+  --rds-color-error: #{$color-error};
+  --rds-color-info: #{$color-info};
+
+  // Typography
+  --rds-font-sans: #{$font-sans};
+  --rds-font-serif: #{$font-serif};
+  --rds-font-mono: #{$font-mono};
+
+  // Spacing
+  --rds-spacing-1: #{$spacing-1};
+  --rds-spacing-2: #{$spacing-2};
+  --rds-spacing-3: #{$spacing-3};
+  --rds-spacing-4: #{$spacing-4};
+  --rds-spacing-6: #{$spacing-6};
+  --rds-spacing-8: #{$spacing-8};
+
+  // Border radius
+  --rds-radius-sm: #{$radius-sm};
+  --rds-radius-md: #{$radius-md};
+  --rds-radius-lg: #{$radius-lg};
+
+  // Shadows
+  --rds-shadow-sm: #{$shadow-sm};
+  --rds-shadow-md: #{$shadow-md};
+  --rds-shadow-lg: #{$shadow-lg};
+}
+
+// Dark mode
+.dark {
+  --rds-color-black: #{$cu-white};
+  --rds-color-white: #{$cu-black};
+  --rds-gray-50: #{$gray-900};
+  --rds-gray-100: #{$gray-800};
+  --rds-gray-200: #{$gray-700};
+  // ... invert other colors
+}
+```
+
+### 2.2 Theme Customization
+
+Users can override with CSS:
+
+```css
+/* Custom theme */
+:root {
+  --rds-color-primary: #0066cc;
+  --rds-color-primary-dark: #004499;
+  --rds-font-sans: 'Roboto', sans-serif;
+}
+```
+
+---
+
+## Phase 3: Component Migration
+
+### Migration Checklist per Component
+
+- [ ] Create `ComponentName.module.scss`
+- [ ] Define component styles using variables and mixins
+- [ ] Update component to use CSS module classes
+- [ ] Add data-testid attributes for testing
+- [ ] Update Storybook stories
+- [ ] Test all variants
+- [ ] Test responsive behavior
+- [ ] Test dark mode
+- [ ] Update component documentation
+- [ ] Visual regression test
+
+### Example: Button Migration
+
+**Before (Tailwind):**
+
+```tsx
+// Button.tsx
+export function Button({ color = 'red', isSmall, children }) {
+  const colorClasses = {
+    red: 'bg-cu-red text-white hover:bg-cu-red-dark',
+    grey: 'bg-gray-200 text-gray-800 hover:bg-gray-300',
+  }
+
+  return (
+    <button
+      className={clsx(
+        'inline-flex items-center justify-center',
+        'px-4 py-2 rounded-md font-medium text-sm',
+        'transition-colors duration-200',
+        colorClasses[color],
+        isSmall && 'px-3 py-1.5 text-xs'
+      )}
+    >
+      {children}
+    </button>
+  )
+}
+```
+
+**After (SCSS Module):**
+
+```scss
+// Button.module.scss
+@use '../../styles/abstracts' as *;
+
+.button {
+  @include button-base;
+  @include focus-ring;
+
+  &--red {
+    background-color: var(--rds-color-primary);
+    color: var(--rds-color-white);
+
+    &:hover:not(:disabled) {
+      background-color: var(--rds-color-primary-dark);
+    }
+  }
+
+  &--grey {
+    background-color: var(--rds-gray-200);
+    color: var(--rds-gray-800);
+
+    &:hover:not(:disabled) {
+      background-color: var(--rds-gray-300);
+    }
+  }
+
+  &--darkGrey {
+    background-color: var(--rds-gray-600);
+    color: var(--rds-color-white);
+
+    &:hover:not(:disabled) {
+      background-color: var(--rds-gray-700);
+    }
+  }
+
+  &--black {
+    background-color: var(--rds-color-black);
+    color: var(--rds-color-white);
+
+    &:hover:not(:disabled) {
+      background-color: var(--rds-gray-900);
+    }
+  }
+
+  &--white {
+    background-color: var(--rds-color-white);
+    color: var(--rds-gray-900);
+    border: 1px solid var(--rds-gray-300);
+
+    &:hover:not(:disabled) {
+      background-color: var(--rds-gray-50);
+    }
+  }
+
+  &--small {
+    padding: $spacing-1 $spacing-3;
+    font-size: $text-xs;
+  }
+
+  &--full {
+    width: 100%;
+  }
+}
+```
+
+```tsx
+// Button.tsx
+import styles from './Button.module.scss'
+import clsx from 'clsx'
+
+export interface ButtonProps {
+  color?: 'red' | 'grey' | 'dark-grey' | 'black' | 'white'
+  isSmall?: boolean
+  isFull?: boolean
+  isDisabled?: boolean
+  children: React.ReactNode
+}
+
+export function Button({
+  color = 'red',
+  isSmall = false,
+  isFull = false,
+  isDisabled = false,
+  children,
+  ...props
+}: ButtonProps) {
+  // Map color prop to style key
+  const colorKey = color === 'dark-grey' ? 'darkGrey' : color
+
+  return (
+    <button
+      className={clsx(
+        styles.button,
+        styles[`button--${colorKey}`],
+        isSmall && styles['button--small'],
+        isFull && styles['button--full']
+      )}
+      disabled={isDisabled}
+      data-testid="rds-button"
+      {...props}
+    >
+      {children}
+    </button>
+  )
+}
+```
+
+---
+
+## Phase 4: Cleanup
+
+### 4.1 Remove Tailwind Dependencies
+
+```bash
+npm uninstall tailwindcss @tailwindcss/forms @tailwindcss/typography
+npm uninstall @tailwindcss/aspect-ratio @tailwindcss/container-queries
+npm uninstall rds-tailwind-theme postcss-nesting
+```
+
+### 4.2 Update Configuration
+
+Remove Tailwind from:
+- `vite.config.ts`
+- `postcss.config.js`
+- Delete `tailwind.config.ts`
+
+### 4.3 Update Build Process
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  css: {
+    preprocessorOptions: {
+      scss: {
+        additionalData: `@use "./lib/styles/abstracts" as *;`,
+      },
+    },
+  },
+})
+```
+
+### 4.4 Update Documentation
+
+- Remove Tailwind references
+- Update component documentation
+- Update Gutenberg integration guide
+
+---
+
+## Technical Details
+
+### CSS Modules Configuration
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  css: {
+    modules: {
+      // Generate readable class names in dev
+      generateScopedName: process.env.NODE_ENV === 'production'
+        ? '[hash:base64:8]'
+        : '[name]__[local]___[hash:base64:5]',
+      localsConvention: 'camelCase',
+    },
+  },
+})
+```
+
+### SCSS Import Pattern
+
+```scss
+// In component SCSS files
+@use '../../styles/abstracts' as *;
+
+.component {
+  // Use variables directly
+  color: $cu-red;
+
+  // Or CSS custom properties for theming
+  color: var(--rds-color-primary);
+
+  // Use mixins
+  @include respond-to('md') {
+    // Tablet styles
+  }
+}
+```
+
+### TypeScript Support
+
+```typescript
+// src/styles.d.ts
+declare module '*.module.scss' {
+  const classes: { [key: string]: string }
+  export default classes
+}
+```
+
+---
+
+## Component Migration Guide
+
+### Order of Migration
+
+```
+1. Foundation components (no dependencies)
+   - Icon
+   - Badge
+   - Avatar
+   - Alert
+
+2. Interactive components
+   - Button
+   - ButtonGroup
+
+3. Composite components
+   - Card (+ all subcomponents)
+   - Listing (+ all subcomponents)
+
+4. Form components
+   - Input
+   - TextArea
+   - Select
+   - Checkbox
+   - Radio
+   - DateTime
+   - FileUpload
+   - Form wrapper
+
+5. Navigation
+   - Nav (+ all subcomponents)
+
+6. Layout components
+   - Section
+   - Column
+   - Article
+   - Aside
+   - Main
+   - Body
+
+7. Complex components
+   - Splash
+   - Modal
+   - Dialog
+   - Toast
+
+8. Remaining components
+   - All others
+```
+
+### Per-Component Steps
+
+1. **Create SCSS module**
+   ```
+   ComponentName/
+   ├── ComponentName.tsx
+   ├── ComponentName.module.scss  ← Add this
+   └── ComponentName.stories.tsx
+   ```
+
+2. **Write styles using design tokens**
+
+3. **Update component imports**
+   ```tsx
+   import styles from './ComponentName.module.scss'
+   ```
+
+4. **Replace Tailwind classes with module classes**
+
+5. **Test thoroughly**
+
+6. **Update Storybook**
+
+7. **Document any breaking changes**
+
+---
+
+## Testing Strategy
+
+### Visual Regression Testing
+
+Before migration:
+1. Capture screenshots of all component states
+2. Save as baseline
+
+After migration:
+1. Capture new screenshots
+2. Compare with baseline
+3. Fix any visual differences
+
+### Automated Tests
+
+```typescript
+// Ensure styles are applied
+it('applies correct color class', () => {
+  cy.mount(<Button color="red">Click</Button>)
+  cy.get('[data-testid="rds-button"]')
+    .should('have.css', 'background-color', 'rgb(191, 17, 43)') // $cu-red
+})
+```
+
+### Manual Testing Checklist
+
+- [ ] All color variants render correctly
+- [ ] Hover states work
+- [ ] Focus states work
+- [ ] Disabled states work
+- [ ] Responsive behavior matches
+- [ ] Dark mode works
+- [ ] No style leakage to other components
+- [ ] Works in Gutenberg editor
+- [ ] Works on WordPress frontend
+
+---
+
+## Rollback Plan
+
+### If Migration Fails
+
+1. **Git branches**: Each phase in separate branch
+2. **Feature flags**: Can disable SCSS per component
+3. **Parallel styles**: Keep Tailwind until fully migrated
+4. **Semantic versioning**: Major version for breaking changes
+
+### Rollback Steps
+
+```bash
+# Revert to last working state
+git checkout main
+git branch -D feature/scss-migration
+
+# Or selective revert
+git revert <commit-hash>
+```
+
+---
+
+## Success Criteria
+
+### Phase 1 Complete When:
+- [ ] SCSS infrastructure in place
+- [ ] Variables and mixins defined
+- [ ] Build process works
+
+### Phase 2 Complete When:
+- [ ] All design tokens as CSS custom properties
+- [ ] Theme customization documented
+
+### Phase 3 Complete When:
+- [ ] All 51 components migrated
+- [ ] All tests passing
+- [ ] Visual regression clean
+
+### Phase 4 Complete When:
+- [ ] Tailwind removed
+- [ ] Bundle size reduced
+- [ ] Documentation updated
+- [ ] Gutenberg compatibility verified
+
+---
+
+## Related Documentation
+
+- [Architecture](./ARCHITECTURE.md) - Current architecture
+- [Styling](./STYLING.md) - Current Tailwind setup
+- [Components](./COMPONENTS.md) - Component catalog
+- [Gutenberg](./GUTENBERG.md) - WordPress integration
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..46ff5c26b
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,124 @@
+# Raven Design System (RDS) Documentation
+
+Welcome to the documentation for the Raven Design System - Carleton University's React component library.
+
+## Quick Links
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](./ARCHITECTURE.md) | System architecture, build process, and project structure |
+| [Components](./COMPONENTS.md) | Complete component catalog with usage examples |
+| [Layouts](./LAYOUTS.md) | Layout components for page structure |
+| [Forms](./FORMS.md) | Form system with Formik integration |
+| [Styling](./STYLING.md) | Current Tailwind CSS implementation |
+| [Utilities](./UTILITIES.md) | Utility functions and helper classes |
+| [Gutenberg Integration](./GUTENBERG.md) | WordPress block development guide |
+| [Testing](./TESTING.md) | Testing with Cypress and Storybook |
+| [Migration Plan](./MIGRATION.md) | Tailwind to SCSS migration roadmap |
+| [Contributing](./CONTRIBUTING.md) | Contribution guidelines and standards |
+
+## Overview
+
+RDS is a production-ready, TypeScript-first React component library built with modern tooling. It powers over 70 custom Gutenberg blocks for Carleton University websites.
+
+### Key Statistics
+
+- **51 UI Components**
+- **10 Layout Components**
+- **21 Skeleton Loaders**
+- **27 Form Components**
+- **React 19** compatible
+- **TypeScript** with strict type checking
+- **Storybook 8.6** for component development
+
+### Tech Stack
+
+| Category | Technology |
+|----------|------------|
+| Framework | React 19, TypeScript 5.9 |
+| Build | Vite 6.3, Rollup |
+| Styling | Tailwind CSS 3.4 (migrating to SCSS) |
+| Forms | Formik 2.4, Yup 1.7 |
+| Testing | Cypress 15.8, Storybook 8.6 |
+| Linting | ESLint 9, Prettier 3.7 |
+| Git Hooks | Husky 9, Commitlint |
+
+## Installation
+
+```bash
+npm install @carletonuniversity/rds
+```
+
+## Basic Usage
+
+```tsx
+import { Button, Card, Alert } from '@carletonuniversity/rds'
+import '@carletonuniversity/rds/dist/style.css'
+
+function MyComponent() {
+  return (
+    <Card>
+      <Card.Header title="Welcome" />
+      <Card.Body>
+        <Card.Content>
+          <Alert type="success" title="Success!">
+            Your component is working.
+          </Alert>
+          <Button color="red">Click Me</Button>
+        </Card.Content>
+      </Card.Body>
+    </Card>
+  )
+}
+```
+
+## Package Exports
+
+The library provides multiple export formats:
+
+```json
+{
+  "main": "dist/rds.umd.js",      // CommonJS/UMD
+  "module": "dist/rds.es.js",     // ES Modules
+  "types": "dist/main.d.ts"       // TypeScript definitions
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start Storybook development server
+npm run storybook
+
+# Build library
+npm run build
+
+# Run tests
+npm run test
+
+# Lint and format
+npm run lint
+npm run prettier
+```
+
+## Project Goals
+
+### Current Focus
+1. Document existing components and patterns
+2. Identify inconsistencies and areas for improvement
+3. Improve Gutenberg block integration
+
+### Future Plans
+1. Migrate from Tailwind CSS to SCSS modules
+2. Improve bundle size and tree-shaking
+3. Add more comprehensive testing
+4. Create better TypeScript types for Gutenberg
+
+## Support
+
+- **Storybook**: Run `npm run storybook` for interactive component documentation
+- **Issues**: Report issues in the project repository
+- **Updates**: Check [CHANGELOG](../CHANGELOG.md) for version updates
diff --git a/docs/STYLING.md b/docs/STYLING.md
new file mode 100644
index 000000000..6120c7926
--- /dev/null
+++ b/docs/STYLING.md
@@ -0,0 +1,632 @@
+# Styling System
+
+This document covers the current Tailwind CSS implementation and styling patterns in RDS.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Tailwind Configuration](#tailwind-configuration)
+- [RDS Tailwind Theme](#rds-tailwind-theme)
+- [CSS Architecture](#css-architecture)
+- [Component Styling Patterns](#component-styling-patterns)
+- [Utility Classes](#utility-classes)
+- [Dark Mode](#dark-mode)
+- [Responsive Design](#responsive-design)
+- [Known Issues](#known-issues)
+
+---
+
+## Overview
+
+RDS currently uses Tailwind CSS with a custom theme preset (`rds-tailwind-theme`) for styling. This provides:
+
+- **Carleton University brand colors**
+- **Consistent spacing and typography**
+- **Responsive breakpoints**
+- **Dark mode support**
+
+### Current Stack
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `tailwindcss` | 3.4.17 | Utility CSS framework |
+| `rds-tailwind-theme` | 0.9.2 | Carleton custom theme |
+| `@tailwindcss/forms` | - | Form element styling |
+| `@tailwindcss/typography` | - | Prose/article styling |
+| `@tailwindcss/aspect-ratio` | - | Aspect ratio utilities |
+| `@tailwindcss/container-queries` | - | Container query support |
+| `postcss` | - | CSS processing |
+| `autoprefixer` | - | Browser prefixes |
+| `postcss-nesting` | - | CSS nesting support |
+
+---
+
+## Tailwind Configuration
+
+### Configuration File
+
+`tailwind.config.ts`:
+
+```typescript
+import type { Config } from 'tailwindcss'
+
+const config: Config = {
+  // Use Carleton's custom theme preset
+  presets: [require('rds-tailwind-theme')],
+
+  // Scan all component files for class usage
+  content: ['./lib/**/*.{tsx,ts,jsx,js}'],
+
+  // Selector-based dark mode (.dark class)
+  darkMode: 'selector',
+
+  theme: {
+    extend: {
+      // Project-specific extensions here
+    },
+  },
+
+  plugins: [
+    require('@tailwindcss/forms'),
+    require('@tailwindcss/typography'),
+    require('@tailwindcss/aspect-ratio'),
+    require('@tailwindcss/container-queries'),
+  ],
+}
+
+export default config
+```
+
+### PostCSS Configuration
+
+`postcss.config.js`:
+
+```javascript
+module.exports = {
+  plugins: {
+    'postcss-nesting': {},
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
+```
+
+---
+
+## RDS Tailwind Theme
+
+The `rds-tailwind-theme` package provides Carleton University's brand design tokens.
+
+### Brand Colors
+
+```css
+/* Primary */
+--cu-red: #bf112b;          /* Carleton Red */
+--cu-black: #262626;        /* Near black */
+--cu-white: #ffffff;
+
+/* Grays */
+--cu-gray-50: #f9fafb;
+--cu-gray-100: #f3f4f6;
+--cu-gray-200: #e5e7eb;
+--cu-gray-300: #d1d5db;
+--cu-gray-400: #9ca3af;
+--cu-gray-500: #6b7280;
+--cu-gray-600: #4b5563;
+--cu-gray-700: #374151;
+--cu-gray-800: #1f2937;
+--cu-gray-900: #111827;
+
+/* Semantic */
+--cu-success: #10b981;
+--cu-warning: #f59e0b;
+--cu-error: #ef4444;
+--cu-info: #3b82f6;
+```
+
+### Typography
+
+```css
+/* Font families */
+--font-sans: 'Open Sans', system-ui, sans-serif;
+--font-serif: 'Georgia', serif;
+--font-mono: 'Fira Code', monospace;
+
+/* Font sizes (rem) */
+--text-xs: 0.75rem;    /* 12px */
+--text-sm: 0.875rem;   /* 14px */
+--text-base: 1rem;     /* 16px */
+--text-lg: 1.125rem;   /* 18px */
+--text-xl: 1.25rem;    /* 20px */
+--text-2xl: 1.5rem;    /* 24px */
+--text-3xl: 1.875rem;  /* 30px */
+--text-4xl: 2.25rem;   /* 36px */
+--text-5xl: 3rem;      /* 48px */
+```
+
+### Spacing
+
+Based on 4px base unit:
+
+```css
+/* Spacing scale */
+--spacing-0: 0;
+--spacing-1: 0.25rem;  /* 4px */
+--spacing-2: 0.5rem;   /* 8px */
+--spacing-3: 0.75rem;  /* 12px */
+--spacing-4: 1rem;     /* 16px */
+--spacing-5: 1.25rem;  /* 20px */
+--spacing-6: 1.5rem;   /* 24px */
+--spacing-8: 2rem;     /* 32px */
+--spacing-10: 2.5rem;  /* 40px */
+--spacing-12: 3rem;    /* 48px */
+--spacing-16: 4rem;    /* 64px */
+--spacing-20: 5rem;    /* 80px */
+--spacing-24: 6rem;    /* 96px */
+```
+
+### Breakpoints
+
+```css
+/* Responsive breakpoints */
+--screen-sm: 640px;
+--screen-md: 768px;
+--screen-lg: 1024px;
+--screen-xl: 1280px;
+--screen-2xl: 1536px;
+```
+
+---
+
+## CSS Architecture
+
+### File Structure
+
+```
+lib/
+├── style.css           # Main CSS entry point
+├── styles/
+│   ├── spacing.css     # Spacing utilities
+│   ├── max-width.css   # Max-width constraints
+│   └── utilities.css   # Custom utilities
+└── components/
+    └── Component/
+        └── styles.css  # Component-scoped styles
+```
+
+### Main CSS Entry Point
+
+`lib/style.css`:
+
+```css
+/* Tailwind layers */
+@import 'tailwindcss/base';
+@import 'tailwindcss/components';
+@import 'tailwindcss/utilities';
+
+/* Global styles */
+@import './styles/spacing.css';
+@import './styles/max-width.css';
+@import './styles/utilities.css';
+
+/* Component styles */
+@import './components/Alert/styles.css';
+@import './components/Button/styles.css';
+@import './components/Card/styles.css';
+/* ... more component imports */
+```
+
+### Component CSS Pattern
+
+Each component has a `styles.css` file for custom styles:
+
+```css
+/* components/Button/styles.css */
+
+/* Base button styles */
+.cu-button {
+  @apply inline-flex items-center justify-center;
+  @apply px-4 py-2 rounded-md;
+  @apply font-medium text-sm;
+  @apply transition-colors duration-200;
+  @apply focus:outline-none focus:ring-2 focus:ring-offset-2;
+}
+
+/* Color variants */
+.cu-button--red {
+  @apply bg-cu-red text-white;
+  @apply hover:bg-cu-red-dark;
+  @apply focus:ring-cu-red;
+}
+
+.cu-button--grey {
+  @apply bg-gray-200 text-gray-800;
+  @apply hover:bg-gray-300;
+  @apply focus:ring-gray-400;
+}
+
+/* Size variants */
+.cu-button--small {
+  @apply px-3 py-1.5 text-xs;
+}
+
+.cu-button--full {
+  @apply w-full;
+}
+
+/* States */
+.cu-button:disabled,
+.cu-button--disabled {
+  @apply opacity-50 cursor-not-allowed;
+}
+```
+
+---
+
+## Component Styling Patterns
+
+### Pattern 1: Tailwind Classes in JSX
+
+Direct utility classes in components:
+
+```tsx
+// Button.tsx
+export function Button({ color, isSmall, children }) {
+  const classes = clsx(
+    'inline-flex items-center justify-center',
+    'px-4 py-2 rounded-md font-medium',
+    'transition-colors duration-200',
+    {
+      'bg-cu-red text-white hover:bg-cu-red-dark': color === 'red',
+      'bg-gray-200 text-gray-800 hover:bg-gray-300': color === 'grey',
+      'px-3 py-1.5 text-xs': isSmall,
+    }
+  )
+
+  return <button className={classes}>{children}</button>
+}
+```
+
+### Pattern 2: CSS Classes + @apply
+
+Custom CSS classes using Tailwind's @apply:
+
+```tsx
+// Button.tsx
+export function Button({ color, isSmall, children }) {
+  const classes = clsx(
+    'cu-button',
+    `cu-button--${color}`,
+    { 'cu-button--small': isSmall }
+  )
+
+  return <button className={classes}>{children}</button>
+}
+```
+
+```css
+/* styles.css */
+.cu-button {
+  @apply inline-flex items-center justify-center;
+  @apply px-4 py-2 rounded-md font-medium;
+}
+
+.cu-button--red {
+  @apply bg-cu-red text-white hover:bg-cu-red-dark;
+}
+```
+
+### Pattern 3: Utility Class Maps
+
+Centralized class definitions:
+
+```tsx
+// utils/propClasses.tsx
+export const buttonColorClasses = {
+  red: 'bg-cu-red text-white hover:bg-cu-red-dark',
+  grey: 'bg-gray-200 text-gray-800 hover:bg-gray-300',
+  'dark-grey': 'bg-gray-600 text-white hover:bg-gray-700',
+  black: 'bg-black text-white hover:bg-gray-900',
+  white: 'bg-white text-gray-900 hover:bg-gray-50 border border-gray-300',
+}
+
+// Button.tsx
+import { buttonColorClasses } from '../../utils/propClasses'
+
+export function Button({ color = 'red', children }) {
+  return (
+    <button className={clsx('cu-button', buttonColorClasses[color])}>
+      {children}
+    </button>
+  )
+}
+```
+
+---
+
+## Utility Classes
+
+### Exported Utilities
+
+From `lib/utils/propClasses.tsx`:
+
+```typescript
+// Max width constraints
+export const maxWidthClasses = {
+  narrow: 'max-w-2xl',    // 672px
+  small: 'max-w-3xl',     // 768px
+  base: 'max-w-4xl',      // 896px
+  large: 'max-w-5xl',     // 1024px
+  full: 'max-w-full',     // 100%
+  '7xl': 'max-w-7xl',     // 1280px
+}
+
+// Grid columns
+export const gridColumnClasses = {
+  '1': 'grid-cols-1',
+  '2': 'grid-cols-2',
+  '3': 'grid-cols-3',
+  '4': 'grid-cols-4',
+  '6': 'grid-cols-6',
+  '12': 'grid-cols-12',
+}
+
+// Grid gaps
+export const gridGapClasses = {
+  none: 'gap-0',
+  sm: 'gap-2',
+  md: 'gap-4',
+  lg: 'gap-6',
+  xl: 'gap-8',
+}
+
+// Aspect ratios
+export const aspectRatioClasses = {
+  square: 'aspect-square',      // 1:1
+  landscape: 'aspect-video',    // 16:9
+  portrait: 'aspect-[3/4]',     // 3:4
+  wide: 'aspect-[21/9]',        // 21:9
+}
+
+// Text colors
+export const textColorClasses = {
+  black: 'text-black',
+  white: 'text-white',
+  red: 'text-cu-red',
+  grey: 'text-gray-600',
+}
+
+// Icon sizes
+export const iconSizeClasses = {
+  4: 'w-4 h-4',
+  5: 'w-5 h-5',
+  6: 'w-6 h-6',
+  8: 'w-8 h-8',
+  10: 'w-10 h-10',
+  12: 'w-12 h-12',
+  16: 'w-16 h-16',
+  20: 'w-20 h-20',
+  24: 'w-24 h-24',
+}
+```
+
+### Using Utilities
+
+```tsx
+import { utils } from '@carletonuniversity/rds'
+
+function MyComponent({ maxWidth, columns }) {
+  return (
+    <div className={utils.maxWidthClasses[maxWidth]}>
+      <div className={`grid ${utils.gridColumnClasses[columns]}`}>
+        {/* content */}
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+## Dark Mode
+
+### Configuration
+
+Dark mode uses Tailwind's selector strategy:
+
+```typescript
+// tailwind.config.ts
+{
+  darkMode: 'selector', // Uses .dark class
+}
+```
+
+### Implementation
+
+```tsx
+// Toggle dark mode
+document.documentElement.classList.toggle('dark')
+
+// Component with dark mode
+function Card({ children }) {
+  return (
+    <div className="bg-white dark:bg-gray-800 text-gray-900 dark:text-white">
+      {children}
+    </div>
+  )
+}
+```
+
+### Dark Mode Classes
+
+```css
+/* Light mode (default) */
+.card {
+  @apply bg-white text-gray-900;
+}
+
+/* Dark mode */
+.dark .card {
+  @apply bg-gray-800 text-white;
+}
+
+/* Or using Tailwind dark: prefix */
+.card {
+  @apply bg-white text-gray-900;
+  @apply dark:bg-gray-800 dark:text-white;
+}
+```
+
+---
+
+## Responsive Design
+
+### Mobile-First Approach
+
+Components use mobile-first responsive design:
+
+```tsx
+// Stacks on mobile, grid on larger screens
+<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
+  {items.map(item => <Card key={item.id} {...item} />)}
+</div>
+```
+
+### Breakpoint Usage
+
+| Prefix | Min Width | Use Case |
+|--------|-----------|----------|
+| (none) | 0px | Mobile (default) |
+| `sm:` | 640px | Large phones |
+| `md:` | 768px | Tablets |
+| `lg:` | 1024px | Laptops |
+| `xl:` | 1280px | Desktops |
+| `2xl:` | 1536px | Large screens |
+
+### Common Patterns
+
+```css
+/* Stack to grid */
+.card-grid {
+  @apply grid grid-cols-1;
+  @apply sm:grid-cols-2;
+  @apply lg:grid-cols-3;
+  @apply xl:grid-cols-4;
+}
+
+/* Hide/show */
+.mobile-only {
+  @apply block md:hidden;
+}
+
+.desktop-only {
+  @apply hidden md:block;
+}
+
+/* Responsive spacing */
+.section {
+  @apply py-8 md:py-12 lg:py-16;
+  @apply px-4 md:px-6 lg:px-8;
+}
+
+/* Responsive text */
+.heading {
+  @apply text-2xl md:text-3xl lg:text-4xl;
+}
+```
+
+---
+
+## Known Issues
+
+### 1. Large CSS Bundle Size
+
+**Problem:** The compiled CSS includes all Tailwind utilities, even unused ones.
+
+**Current Size:** ~150KB+ (compressed)
+
+**Impact:** Longer initial page loads, especially on slower connections.
+
+**Mitigation:**
+- PurgeCSS configured but may miss dynamic classes
+- Some classes built from variables can't be purged
+
+### 2. Tailwind Class Conflicts
+
+**Problem:** Tailwind classes can conflict with WordPress/Gutenberg styles.
+
+**Example:**
+```css
+/* Tailwind reset */
+button { background: transparent; }
+
+/* WordPress expects default styling */
+```
+
+**Mitigation:**
+- Use `important: true` in Tailwind config (not recommended)
+- Prefix all Tailwind classes with `tw-` (requires config change)
+- Use scoped CSS classes instead
+
+### 3. Dynamic Class Generation
+
+**Problem:** Dynamically generated classes aren't purged.
+
+```tsx
+// This class won't be purged correctly
+const color = 'red'
+return <div className={`bg-${color}-500`} />
+```
+
+**Mitigation:**
+- Use complete class names in safelist
+- Map values to full class strings
+
+### 4. Theme Customization Difficulty
+
+**Problem:** Overriding theme values requires deep Tailwind knowledge.
+
+**Mitigation:**
+- Document theme extension patterns
+- Consider CSS custom properties for easier overrides
+
+### 5. No CSS Isolation
+
+**Problem:** Styles can leak between components.
+
+**Current State:** Most styles are global.
+
+**Future Plan:** Migrate to CSS Modules or scoped SCSS.
+
+---
+
+## Recommendations for Improvement
+
+### Short Term
+
+1. **Audit unused styles** - Identify and remove dead CSS
+2. **Safelist dynamic classes** - Ensure dynamic classes are preserved
+3. **Document dark mode** - Improve dark mode documentation
+4. **CSS organization** - Better organize component styles
+
+### Medium Term
+
+1. **CSS Modules pilot** - Test CSS Modules on one component
+2. **CSS custom properties** - Use CSS variables for theming
+3. **Critical CSS extraction** - Split critical and non-critical CSS
+
+### Long Term
+
+1. **SCSS migration** - Full migration to SCSS modules
+2. **Design tokens** - Implement design token system
+3. **Component-level CSS** - Isolate styles per component
+
+See [MIGRATION.md](./MIGRATION.md) for the Tailwind to SCSS migration plan.
+
+---
+
+## Related Documentation
+
+- [Architecture](./ARCHITECTURE.md) - Build system and structure
+- [Migration Plan](./MIGRATION.md) - Tailwind to SCSS roadmap
+- [Components](./COMPONENTS.md) - Component catalog
diff --git a/docs/TESTING.md b/docs/TESTING.md
new file mode 100644
index 000000000..96e23d578
--- /dev/null
+++ b/docs/TESTING.md
@@ -0,0 +1,854 @@
+# Testing Guide
+
+This document covers testing practices for RDS components using Cypress and Storybook.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Test Stack](#test-stack)
+- [Running Tests](#running-tests)
+- [Cypress Testing](#cypress-testing)
+- [Storybook Testing](#storybook-testing)
+- [Writing Tests](#writing-tests)
+- [Testing Patterns](#testing-patterns)
+- [Accessibility Testing](#accessibility-testing)
+- [CI/CD Integration](#cicd-integration)
+- [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+RDS uses a multi-layered testing approach:
+
+1. **Storybook** - Visual component documentation and interactive testing
+2. **Cypress** - E2E and component testing
+3. **TypeScript** - Static type checking
+
+### Coverage Goals
+
+| Category | Coverage Target |
+|----------|-----------------|
+| Critical components | 90%+ |
+| Form components | 85%+ |
+| Layout components | 70%+ |
+| Utility functions | 95%+ |
+
+---
+
+## Test Stack
+
+### Dependencies
+
+```json
+{
+  "devDependencies": {
+    "@storybook/react": "^8.6.14",
+    "@storybook/addon-a11y": "^8.6.14",
+    "@storybook/addon-interactions": "^8.6.14",
+    "@storybook/test": "^8.6.14",
+    "cypress": "^15.8.1",
+    "@testing-library/cypress": "^10.0.0"
+  }
+}
+```
+
+### Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `cypress.config.ts` | Cypress configuration |
+| `.storybook/main.ts` | Storybook configuration |
+| `.storybook/preview.ts` | Storybook preview settings |
+
+---
+
+## Running Tests
+
+### Development Commands
+
+```bash
+# Start Storybook (required for Cypress)
+npm run storybook
+
+# Open Cypress test runner
+npm run test
+
+# Run Cypress headless
+npm run test:ci
+
+# Build Storybook for deployment
+npm run build:storybook
+```
+
+### Test Scripts
+
+```json
+{
+  "scripts": {
+    "storybook": "storybook dev -p 6006",
+    "build:storybook": "storybook build",
+    "test": "concurrently \"npm run storybook --quiet --ci -p 6006\" \"npx cypress open\"",
+    "test:ci": "concurrently \"npm run storybook --quiet --ci -p 6006\" \"npx cypress run --headless\""
+  }
+}
+```
+
+---
+
+## Cypress Testing
+
+### Configuration
+
+`cypress.config.ts`:
+
+```typescript
+import { defineConfig } from 'cypress'
+
+export default defineConfig({
+  viewportWidth: 1280,
+  viewportHeight: 800,
+  video: false,
+  screenshotOnRunFailure: true,
+
+  e2e: {
+    baseUrl: 'http://localhost:6006',
+    specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}',
+    supportFile: 'cypress/support/e2e.ts',
+  },
+
+  component: {
+    devServer: {
+      framework: 'react',
+      bundler: 'vite',
+    },
+    specPattern: 'cypress/component/**/*.cy.{js,jsx,ts,tsx}',
+  },
+})
+```
+
+### Directory Structure
+
+```
+cypress/
+├── e2e/
+│   ├── button.cy.ts
+│   ├── card.cy.ts
+│   ├── form.cy.ts
+│   └── navigation.cy.ts
+├── component/
+│   ├── Button.cy.tsx
+│   └── Card.cy.tsx
+├── fixtures/
+│   └── test-data.json
+├── support/
+│   ├── commands.ts
+│   ├── e2e.ts
+│   └── component.ts
+└── downloads/
+```
+
+### E2E Test Example
+
+```typescript
+// cypress/e2e/button.cy.ts
+describe('Button Component', () => {
+  beforeEach(() => {
+    // Navigate to Storybook
+    cy.visit('/iframe.html?id=components-button--primary')
+  })
+
+  it('renders with correct text', () => {
+    cy.get('button').should('contain', 'Button')
+  })
+
+  it('has correct color class', () => {
+    cy.get('button').should('have.class', 'bg-cu-red')
+  })
+
+  it('is clickable', () => {
+    cy.get('button').click()
+    // Verify action was triggered
+  })
+
+  it('can be disabled', () => {
+    cy.visit('/iframe.html?id=components-button--disabled')
+    cy.get('button').should('be.disabled')
+  })
+})
+```
+
+### Component Test Example
+
+```typescript
+// cypress/component/Button.cy.tsx
+import { Button } from '../../lib/components/Button/Button'
+
+describe('Button Component', () => {
+  it('renders with default props', () => {
+    cy.mount(<Button>Click Me</Button>)
+    cy.get('button').should('contain', 'Click Me')
+  })
+
+  it('applies color variant', () => {
+    cy.mount(<Button color="grey">Grey Button</Button>)
+    cy.get('button').should('have.class', 'bg-gray-200')
+  })
+
+  it('handles click events', () => {
+    const onClick = cy.stub().as('clickHandler')
+    cy.mount(<Button onClick={onClick}>Click</Button>)
+
+    cy.get('button').click()
+    cy.get('@clickHandler').should('have.been.calledOnce')
+  })
+
+  it('renders as disabled', () => {
+    cy.mount(<Button isDisabled>Disabled</Button>)
+    cy.get('button')
+      .should('be.disabled')
+      .should('have.class', 'opacity-50')
+  })
+})
+```
+
+### Custom Commands
+
+```typescript
+// cypress/support/commands.ts
+import '@testing-library/cypress/add-commands'
+
+declare global {
+  namespace Cypress {
+    interface Chainable {
+      visitStory(storyId: string): Chainable<void>
+      getByTestId(testId: string): Chainable<JQuery<HTMLElement>>
+    }
+  }
+}
+
+// Visit a Storybook story
+Cypress.Commands.add('visitStory', (storyId: string) => {
+  cy.visit(`/iframe.html?id=${storyId}`)
+})
+
+// Get element by data-testid
+Cypress.Commands.add('getByTestId', (testId: string) => {
+  return cy.get(`[data-testid="${testId}"]`)
+})
+```
+
+---
+
+## Storybook Testing
+
+### Story Structure
+
+```typescript
+// Button.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react'
+import { within, userEvent, expect } from '@storybook/test'
+import { Button } from './Button'
+
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button',
+  component: Button,
+  tags: ['autodocs'],
+  argTypes: {
+    color: {
+      control: 'select',
+      options: ['red', 'grey', 'dark-grey', 'black', 'white'],
+    },
+    isSmall: { control: 'boolean' },
+    isFull: { control: 'boolean' },
+    isDisabled: { control: 'boolean' },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Button>
+
+// Default story
+export const Primary: Story = {
+  args: {
+    children: 'Primary Button',
+    color: 'red',
+  },
+}
+
+// Variant stories
+export const Secondary: Story = {
+  args: {
+    children: 'Secondary Button',
+    color: 'grey',
+  },
+}
+
+export const Small: Story = {
+  args: {
+    children: 'Small Button',
+    isSmall: true,
+  },
+}
+
+export const Disabled: Story = {
+  args: {
+    children: 'Disabled Button',
+    isDisabled: true,
+  },
+}
+
+// Interactive test
+export const ClickTest: Story = {
+  args: {
+    children: 'Click Me',
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const button = canvas.getByRole('button')
+
+    // Verify initial state
+    await expect(button).toBeInTheDocument()
+
+    // Simulate click
+    await userEvent.click(button)
+
+    // Verify click was registered
+    await expect(button).toHaveFocus()
+  },
+}
+
+// Form submission test
+export const FormSubmit: Story = {
+  render: () => (
+    <form onSubmit={(e) => e.preventDefault()}>
+      <Button type="submit">Submit</Button>
+    </form>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const button = canvas.getByRole('button')
+
+    await userEvent.click(button)
+  },
+}
+```
+
+### Interaction Testing
+
+```typescript
+// Card.stories.tsx
+import { within, userEvent, expect } from '@storybook/test'
+
+export const InteractiveCard: Story = {
+  render: () => (
+    <Card>
+      <Card.Body>
+        <Card.Header title="Interactive Card" />
+        <Card.Content>
+          <button data-testid="card-button">Click Me</button>
+        </Card.Content>
+      </Card.Body>
+    </Card>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+
+    // Find and click button
+    const button = canvas.getByTestId('card-button')
+    await userEvent.click(button)
+
+    // Verify interaction
+    await expect(button).toHaveFocus()
+  },
+}
+```
+
+### Accessibility Testing
+
+```typescript
+// Storybook automatically runs a11y checks with addon-a11y
+// Configure in .storybook/preview.ts
+
+export const parameters = {
+  a11y: {
+    // Axe configuration
+    config: {
+      rules: [
+        { id: 'color-contrast', enabled: true },
+        { id: 'label', enabled: true },
+        { id: 'button-name', enabled: true },
+      ],
+    },
+    // Elements to check
+    element: '#storybook-root',
+    // Manual run mode (vs automatic)
+    manual: false,
+  },
+}
+```
+
+---
+
+## Writing Tests
+
+### Component Test Checklist
+
+For each component, test:
+
+- [ ] Renders without errors
+- [ ] Displays correct content
+- [ ] Applies correct CSS classes
+- [ ] Handles all prop variants
+- [ ] Responds to user interactions
+- [ ] Handles edge cases (empty, null, undefined)
+- [ ] Accessible (keyboard, screen reader)
+
+### Test Template
+
+```typescript
+// ComponentName.cy.tsx
+import { ComponentName } from './ComponentName'
+
+describe('ComponentName', () => {
+  // Rendering tests
+  describe('Rendering', () => {
+    it('renders without errors', () => {
+      cy.mount(<ComponentName />)
+      cy.get('[data-testid="component-name"]').should('exist')
+    })
+
+    it('displays provided content', () => {
+      cy.mount(<ComponentName>Content</ComponentName>)
+      cy.get('[data-testid="component-name"]').should('contain', 'Content')
+    })
+  })
+
+  // Props tests
+  describe('Props', () => {
+    it('applies variant prop correctly', () => {
+      cy.mount(<ComponentName variant="secondary" />)
+      cy.get('[data-testid="component-name"]')
+        .should('have.class', 'variant-secondary')
+    })
+
+    it('handles disabled state', () => {
+      cy.mount(<ComponentName disabled />)
+      cy.get('[data-testid="component-name"]')
+        .should('have.attr', 'disabled')
+    })
+  })
+
+  // Interaction tests
+  describe('Interactions', () => {
+    it('calls onClick when clicked', () => {
+      const onClick = cy.stub().as('click')
+      cy.mount(<ComponentName onClick={onClick} />)
+
+      cy.get('[data-testid="component-name"]').click()
+      cy.get('@click').should('have.been.called')
+    })
+
+    it('supports keyboard navigation', () => {
+      cy.mount(<ComponentName />)
+      cy.get('[data-testid="component-name"]')
+        .focus()
+        .type('{enter}')
+    })
+  })
+
+  // Edge cases
+  describe('Edge Cases', () => {
+    it('handles empty content', () => {
+      cy.mount(<ComponentName>{null}</ComponentName>)
+      cy.get('[data-testid="component-name"]').should('exist')
+    })
+
+    it('handles long content', () => {
+      const longText = 'A'.repeat(1000)
+      cy.mount(<ComponentName>{longText}</ComponentName>)
+      cy.get('[data-testid="component-name"]').should('exist')
+    })
+  })
+})
+```
+
+---
+
+## Testing Patterns
+
+### Form Testing
+
+```typescript
+// Form.cy.tsx
+import { Form, Input, Select } from '@carletonuniversity/rds'
+
+describe('Form Component', () => {
+  const initialValues = { email: '', category: '' }
+
+  it('submits form with valid data', () => {
+    const onSubmit = cy.stub().as('submit')
+
+    cy.mount(
+      <Form
+        initialValues={initialValues}
+        onSubmit={onSubmit}
+      >
+        <Form.Field name="email" label="Email">
+          <Input name="email" type="email" />
+        </Form.Field>
+        <Form.Button type="submit">Submit</Form.Button>
+      </Form>
+    )
+
+    cy.get('input[name="email"]').type('test@example.com')
+    cy.get('button[type="submit"]').click()
+
+    cy.get('@submit').should('have.been.calledWith', {
+      email: 'test@example.com',
+      category: '',
+    })
+  })
+
+  it('shows validation errors', () => {
+    cy.mount(
+      <Form
+        initialValues={initialValues}
+        validationSchema={validationSchema}
+        onSubmit={cy.stub()}
+      >
+        <Form.Field name="email" label="Email">
+          <Input name="email" type="email" />
+        </Form.Field>
+        <Form.Button type="submit">Submit</Form.Button>
+      </Form>
+    )
+
+    cy.get('button[type="submit"]').click()
+    cy.contains('Email is required').should('be.visible')
+  })
+})
+```
+
+### Async Testing
+
+```typescript
+// AsyncComponent.cy.tsx
+describe('Async Component', () => {
+  it('shows loading state', () => {
+    cy.intercept('/api/data', { delay: 1000 }).as('getData')
+
+    cy.mount(<AsyncComponent />)
+    cy.get('[data-testid="loader"]').should('be.visible')
+
+    cy.wait('@getData')
+    cy.get('[data-testid="loader"]').should('not.exist')
+    cy.get('[data-testid="content"]').should('be.visible')
+  })
+
+  it('handles error state', () => {
+    cy.intercept('/api/data', { statusCode: 500 }).as('getData')
+
+    cy.mount(<AsyncComponent />)
+    cy.wait('@getData')
+
+    cy.get('[data-testid="error"]').should('be.visible')
+  })
+})
+```
+
+### Modal Testing
+
+```typescript
+// Modal.cy.tsx
+describe('Modal Component', () => {
+  it('opens and closes', () => {
+    cy.mount(
+      <div>
+        <button data-testid="open">Open Modal</button>
+        <Modal isOpen={false} onClose={cy.stub()}>
+          <p>Modal Content</p>
+        </Modal>
+      </div>
+    )
+
+    // Initially closed
+    cy.get('[data-testid="modal"]').should('not.exist')
+
+    // Open modal
+    cy.get('[data-testid="open"]').click()
+    cy.get('[data-testid="modal"]').should('be.visible')
+
+    // Close with escape key
+    cy.get('body').type('{esc}')
+    cy.get('[data-testid="modal"]').should('not.exist')
+  })
+
+  it('traps focus within modal', () => {
+    cy.mount(
+      <Modal isOpen={true} onClose={cy.stub()}>
+        <button>First</button>
+        <button>Second</button>
+        <button>Close</button>
+      </Modal>
+    )
+
+    // Tab through elements
+    cy.get('body').tab()
+    cy.focused().should('contain', 'First')
+
+    cy.get('body').tab()
+    cy.focused().should('contain', 'Second')
+
+    cy.get('body').tab()
+    cy.focused().should('contain', 'Close')
+
+    // Should wrap back to first
+    cy.get('body').tab()
+    cy.focused().should('contain', 'First')
+  })
+})
+```
+
+---
+
+## Accessibility Testing
+
+### Automated Checks
+
+Storybook's a11y addon runs automated accessibility checks:
+
+```typescript
+// .storybook/preview.ts
+export const parameters = {
+  a11y: {
+    config: {
+      rules: [
+        { id: 'color-contrast', enabled: true },
+        { id: 'label', enabled: true },
+        { id: 'button-name', enabled: true },
+        { id: 'image-alt', enabled: true },
+        { id: 'link-name', enabled: true },
+        { id: 'heading-order', enabled: true },
+      ],
+    },
+  },
+}
+```
+
+### Manual Checks
+
+```typescript
+// Cypress a11y testing with axe
+import 'cypress-axe'
+
+describe('Accessibility', () => {
+  beforeEach(() => {
+    cy.visit('/iframe.html?id=components-button--primary')
+    cy.injectAxe()
+  })
+
+  it('has no accessibility violations', () => {
+    cy.checkA11y()
+  })
+
+  it('has no critical violations', () => {
+    cy.checkA11y(null, {
+      includedImpacts: ['critical', 'serious'],
+    })
+  })
+})
+```
+
+### Keyboard Navigation
+
+```typescript
+describe('Keyboard Navigation', () => {
+  it('buttons are keyboard accessible', () => {
+    cy.mount(<Button>Click Me</Button>)
+
+    cy.get('button')
+      .focus()
+      .should('have.focus')
+      .type('{enter}')
+  })
+
+  it('tab order is correct', () => {
+    cy.mount(
+      <div>
+        <Button>First</Button>
+        <Button>Second</Button>
+        <Button>Third</Button>
+      </div>
+    )
+
+    cy.get('body').tab()
+    cy.focused().should('contain', 'First')
+
+    cy.get('body').tab()
+    cy.focused().should('contain', 'Second')
+
+    cy.get('body').tab()
+    cy.focused().should('contain', 'Third')
+  })
+})
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/test.yml
+name: Test
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run Cypress tests
+        uses: cypress-io/github-action@v6
+        with:
+          start: npm run storybook -- --ci
+          wait-on: 'http://localhost:6006'
+          wait-on-timeout: 120
+
+      - name: Upload test artifacts
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: cypress-screenshots
+          path: cypress/screenshots
+```
+
+### Test Reports
+
+```typescript
+// cypress.config.ts
+export default defineConfig({
+  reporter: 'mochawesome',
+  reporterOptions: {
+    reportDir: 'cypress/reports',
+    overwrite: false,
+    html: true,
+    json: true,
+  },
+})
+```
+
+---
+
+## Best Practices
+
+### 1. Test Behavior, Not Implementation
+
+```typescript
+// Good: Tests user-visible behavior
+it('shows error when form is invalid', () => {
+  cy.mount(<Form />)
+  cy.get('button[type="submit"]').click()
+  cy.contains('Required field').should('be.visible')
+})
+
+// Bad: Tests implementation details
+it('sets error state to true', () => {
+  // Testing internal state
+})
+```
+
+### 2. Use Meaningful Test IDs
+
+```tsx
+// Good
+<button data-testid="submit-form">Submit</button>
+
+// Bad
+<button data-testid="btn1">Submit</button>
+```
+
+### 3. Keep Tests Independent
+
+```typescript
+// Good: Each test is independent
+describe('Button', () => {
+  it('test 1', () => {
+    cy.mount(<Button />)
+    // ...
+  })
+
+  it('test 2', () => {
+    cy.mount(<Button />)
+    // ...
+  })
+})
+
+// Bad: Tests depend on each other
+```
+
+### 4. Test Error States
+
+```typescript
+it('handles API error gracefully', () => {
+  cy.intercept('/api/data', { statusCode: 500 })
+  cy.mount(<DataComponent />)
+  cy.contains('Something went wrong').should('be.visible')
+})
+```
+
+### 5. Avoid Flaky Tests
+
+```typescript
+// Good: Wait for specific element
+cy.get('[data-testid="loaded"]').should('be.visible')
+
+// Bad: Arbitrary wait
+cy.wait(1000)
+```
+
+### 6. Test Responsiveness
+
+```typescript
+describe('Responsive', () => {
+  const viewports = ['iphone-6', 'ipad-2', [1280, 720]]
+
+  viewports.forEach((viewport) => {
+    it(`renders correctly on ${viewport}`, () => {
+      cy.viewport(viewport)
+      cy.mount(<Component />)
+      cy.get('[data-testid="component"]').should('be.visible')
+    })
+  })
+})
+```
+
+---
+
+## Related Documentation
+
+- [Components](./COMPONENTS.md) - Component catalog
+- [Contributing](./CONTRIBUTING.md) - Contribution guidelines
+- [Storybook Docs](https://storybook.js.org/docs)
+- [Cypress Docs](https://docs.cypress.io)
diff --git a/docs/UTILITIES.md b/docs/UTILITIES.md
new file mode 100644
index 000000000..367ca19f3
--- /dev/null
+++ b/docs/UTILITIES.md
@@ -0,0 +1,890 @@
+# Utilities and Helpers
+
+This document covers the utility functions, helper classes, and hooks available in RDS.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Prop Classes](#prop-classes)
+- [Validation Schemas](#validation-schemas)
+- [Custom Hooks](#custom-hooks)
+- [Helper Functions](#helper-functions)
+- [Asset Lists](#asset-lists)
+- [Context Providers](#context-providers)
+
+---
+
+## Overview
+
+RDS exports utilities via the `utils` namespace:
+
+```tsx
+import { utils } from '@carletonuniversity/rds'
+
+// Access utility classes
+const widthClass = utils.maxWidthClasses['7xl']
+```
+
+### File Locations
+
+```
+lib/
+├── utils/
+│   └── propClasses.tsx      # CSS class mappings
+├── helpers/
+│   ├── functions.js         # Helper functions
+│   ├── optionClasses.tsx    # Option styling
+│   ├── fileUploadValidationSchema.tsx
+│   └── imageUploadValidationSchema.tsx
+└── hooks/
+    ├── usePagination.ts
+    ├── useSortableTable.tsx
+    └── useVideoBanner.tsx
+```
+
+---
+
+## Prop Classes
+
+### Max Width Classes
+
+Control maximum width of containers:
+
+```tsx
+import { utils } from '@carletonuniversity/rds'
+
+export const maxWidthClasses = {
+  narrow: 'max-w-2xl',    // 672px
+  small: 'max-w-3xl',     // 768px
+  base: 'max-w-4xl',      // 896px
+  large: 'max-w-5xl',     // 1024px
+  full: 'max-w-full',     // 100%
+  '7xl': 'max-w-7xl',     // 1280px
+}
+
+// Usage
+<div className={utils.maxWidthClasses['7xl']}>
+  Content with max width
+</div>
+```
+
+### Small Width Classes
+
+Narrower width constraints:
+
+```tsx
+export const smallWidthClasses = {
+  xs: 'max-w-xs',     // 320px
+  sm: 'max-w-sm',     // 384px
+  md: 'max-w-md',     // 448px
+  lg: 'max-w-lg',     // 512px
+  xl: 'max-w-xl',     // 576px
+  '2xl': 'max-w-2xl', // 672px
+}
+```
+
+### Grid Column Classes
+
+Grid layout utilities:
+
+```tsx
+export const gridColumnClasses = {
+  '1': 'grid-cols-1',
+  '2': 'grid-cols-2',
+  '3': 'grid-cols-3',
+  '4': 'grid-cols-4',
+  '6': 'grid-cols-6',
+  '12': 'grid-cols-12',
+}
+
+// Usage
+<div className={`grid ${utils.gridColumnClasses['3']} gap-4`}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
+
+### Grid Gap Classes
+
+Spacing between grid items:
+
+```tsx
+export const gridGapClasses = {
+  none: 'gap-0',
+  sm: 'gap-2',    // 8px
+  md: 'gap-4',    // 16px
+  lg: 'gap-6',    // 24px
+  xl: 'gap-8',    // 32px
+}
+```
+
+### Margin Auto Classes
+
+Centering and alignment:
+
+```tsx
+export const marginAutoClasses = {
+  auto: 'mx-auto',
+  left: 'mr-auto',
+  right: 'ml-auto',
+  none: '',
+}
+```
+
+### Flex Direction Classes
+
+Flexbox layouts:
+
+```tsx
+export const flexColClasses = {
+  col: 'flex-col',
+  'col-reverse': 'flex-col-reverse',
+}
+
+export const flexRowClasses = {
+  row: 'flex-row',
+  'row-reverse': 'flex-row-reverse',
+}
+```
+
+### Grid Span Classes
+
+Column and row spanning:
+
+```tsx
+export const colSpanClasses = {
+  '1': 'col-span-1',
+  '2': 'col-span-2',
+  '3': 'col-span-3',
+  '4': 'col-span-4',
+  '6': 'col-span-6',
+  '12': 'col-span-12',
+  full: 'col-span-full',
+}
+
+export const rowSpanClasses = {
+  '1': 'row-span-1',
+  '2': 'row-span-2',
+  '3': 'row-span-3',
+  '4': 'row-span-4',
+  '6': 'row-span-6',
+  full: 'row-span-full',
+}
+```
+
+### Aspect Ratio Classes
+
+Image and video aspect ratios:
+
+```tsx
+export const aspectRatioClasses = {
+  square: 'aspect-square',    // 1:1
+  landscape: 'aspect-video',  // 16:9
+  portrait: 'aspect-[3/4]',   // 3:4
+  wide: 'aspect-[21/9]',      // 21:9
+}
+
+// Usage
+<div className={utils.aspectRatioClasses.landscape}>
+  <img src="/image.jpg" className="object-cover w-full h-full" />
+</div>
+```
+
+### Header Size Classes
+
+Responsive heading sizes:
+
+```tsx
+export const headerSizeClasses = {
+  xs: 'text-lg md:text-xl',
+  sm: 'text-xl md:text-2xl',
+  md: 'text-2xl md:text-3xl',
+  lg: 'text-3xl md:text-4xl',
+  xl: 'text-4xl md:text-5xl',
+}
+```
+
+### Text Color Classes
+
+Text color options:
+
+```tsx
+export const textColorClasses = {
+  black: 'text-black',
+  white: 'text-white',
+  red: 'text-cu-red',
+  grey: 'text-gray-600',
+  'dark-grey': 'text-gray-800',
+}
+```
+
+### Alignment Classes
+
+Flex alignment:
+
+```tsx
+export const justifyContentClasses = {
+  start: 'justify-start',
+  end: 'justify-end',
+  center: 'justify-center',
+  between: 'justify-between',
+  around: 'justify-around',
+  evenly: 'justify-evenly',
+}
+
+export const alignItemsClasses = {
+  start: 'items-start',
+  end: 'items-end',
+  center: 'items-center',
+  baseline: 'items-baseline',
+  stretch: 'items-stretch',
+}
+```
+
+### Figure Classes
+
+Image figure sizing and alignment:
+
+```tsx
+export const figureSizeClasses = {
+  xs: 'w-16',
+  sm: 'w-24',
+  md: 'w-32',
+  lg: 'w-48',
+  xl: 'w-64',
+  full: 'w-full',
+}
+
+export const figureAlignClasses = {
+  left: 'float-left mr-4',
+  right: 'float-right ml-4',
+  center: 'mx-auto',
+  none: '',
+}
+```
+
+### Background Opacity Classes
+
+Overlay opacity levels:
+
+```tsx
+export const bgOpacityClasses = {
+  0: 'bg-opacity-0',
+  10: 'bg-opacity-10',
+  20: 'bg-opacity-20',
+  30: 'bg-opacity-30',
+  40: 'bg-opacity-40',
+  50: 'bg-opacity-50',
+  60: 'bg-opacity-60',
+  70: 'bg-opacity-70',
+  80: 'bg-opacity-80',
+  90: 'bg-opacity-90',
+  100: 'bg-opacity-100',
+}
+```
+
+### Border Classes
+
+Border styling:
+
+```tsx
+export const borderRadiusClasses = {
+  none: 'rounded-none',
+  sm: 'rounded-sm',
+  md: 'rounded-md',
+  lg: 'rounded-lg',
+  xl: 'rounded-xl',
+  full: 'rounded-full',
+}
+
+export const borderWidthClasses = {
+  0: 'border-0',
+  1: 'border',
+  2: 'border-2',
+  4: 'border-4',
+  8: 'border-8',
+}
+
+export const borderColorClasses = {
+  transparent: 'border-transparent',
+  black: 'border-black',
+  white: 'border-white',
+  grey: 'border-gray-300',
+  red: 'border-cu-red',
+}
+```
+
+### Icon Size Classes
+
+Icon dimensions:
+
+```tsx
+export const iconSizeClasses = {
+  4: 'w-4 h-4',
+  5: 'w-5 h-5',
+  6: 'w-6 h-6',
+  8: 'w-8 h-8',
+  10: 'w-10 h-10',
+  12: 'w-12 h-12',
+  16: 'w-16 h-16',
+  20: 'w-20 h-20',
+  24: 'w-24 h-24',
+}
+
+// Usage
+<Icon icon="fa-solid fa-check" className={utils.iconSizeClasses[6]} />
+```
+
+---
+
+## Validation Schemas
+
+### File Upload Validation
+
+```tsx
+import * as Yup from 'yup'
+
+// lib/helpers/fileUploadValidationSchema.tsx
+export const fileUploadValidationSchema = (options = {}) => {
+  const {
+    maxSize = 5242880, // 5MB default
+    allowedTypes = [],
+    required = false,
+  } = options
+
+  let schema = Yup.mixed()
+
+  if (required) {
+    schema = schema.required('File is required')
+  }
+
+  schema = schema.test('fileSize', 'File is too large', (value) => {
+    if (!value) return true
+    return value.size <= maxSize
+  })
+
+  if (allowedTypes.length > 0) {
+    schema = schema.test('fileType', 'Invalid file type', (value) => {
+      if (!value) return true
+      return allowedTypes.includes(value.type)
+    })
+  }
+
+  return schema
+}
+
+// Usage
+const validationSchema = Yup.object({
+  document: fileUploadValidationSchema({
+    maxSize: 10485760, // 10MB
+    allowedTypes: ['application/pdf', 'application/msword'],
+    required: true,
+  }),
+})
+```
+
+### Image Upload Validation
+
+```tsx
+// lib/helpers/imageUploadValidationSchema.tsx
+export const imageUploadValidationSchema = (options = {}) => {
+  const {
+    maxSize = 2097152, // 2MB default
+    minWidth = 0,
+    minHeight = 0,
+    maxWidth = Infinity,
+    maxHeight = Infinity,
+    required = false,
+  } = options
+
+  return Yup.mixed()
+    .test('required', 'Image is required', (value) => {
+      if (!required) return true
+      return !!value
+    })
+    .test('fileSize', 'Image is too large', (value) => {
+      if (!value) return true
+      return value.size <= maxSize
+    })
+    .test('fileType', 'Only images are allowed', (value) => {
+      if (!value) return true
+      return value.type.startsWith('image/')
+    })
+    .test('dimensions', 'Invalid image dimensions', async (value) => {
+      if (!value) return true
+
+      return new Promise((resolve) => {
+        const img = new Image()
+        img.onload = () => {
+          const valid =
+            img.width >= minWidth &&
+            img.height >= minHeight &&
+            img.width <= maxWidth &&
+            img.height <= maxHeight
+          resolve(valid)
+        }
+        img.onerror = () => resolve(false)
+        img.src = URL.createObjectURL(value)
+      })
+    })
+}
+
+// Usage
+const validationSchema = Yup.object({
+  avatar: imageUploadValidationSchema({
+    maxSize: 1048576, // 1MB
+    minWidth: 200,
+    minHeight: 200,
+  }),
+})
+```
+
+---
+
+## Custom Hooks
+
+### usePagination
+
+Pagination logic hook:
+
+```tsx
+import { usePagination } from '@carletonuniversity/rds'
+
+function PaginatedList({ items, itemsPerPage = 10 }) {
+  const {
+    currentPage,
+    totalPages,
+    paginatedItems,
+    goToPage,
+    nextPage,
+    prevPage,
+    hasNextPage,
+    hasPrevPage,
+  } = usePagination(items, itemsPerPage)
+
+  return (
+    <div>
+      {paginatedItems.map((item) => (
+        <div key={item.id}>{item.name}</div>
+      ))}
+
+      <div className="pagination">
+        <button onClick={prevPage} disabled={!hasPrevPage}>
+          Previous
+        </button>
+        <span>
+          Page {currentPage} of {totalPages}
+        </span>
+        <button onClick={nextPage} disabled={!hasNextPage}>
+          Next
+        </button>
+      </div>
+    </div>
+  )
+}
+```
+
+**Return Values:**
+| Property | Type | Description |
+|----------|------|-------------|
+| `currentPage` | `number` | Current page number (1-indexed) |
+| `totalPages` | `number` | Total number of pages |
+| `paginatedItems` | `T[]` | Items for current page |
+| `goToPage` | `(page: number) => void` | Navigate to specific page |
+| `nextPage` | `() => void` | Go to next page |
+| `prevPage` | `() => void` | Go to previous page |
+| `hasNextPage` | `boolean` | Has more pages after current |
+| `hasPrevPage` | `boolean` | Has pages before current |
+
+### useSortableTable
+
+Table sorting logic:
+
+```tsx
+import { useSortableTable } from '@carletonuniversity/rds'
+
+function SortableTable({ data, columns }) {
+  const { sortedData, sortConfig, requestSort, getSortDirection } =
+    useSortableTable(data)
+
+  return (
+    <table>
+      <thead>
+        <tr>
+          {columns.map((column) => (
+            <th
+              key={column.key}
+              onClick={() => requestSort(column.key)}
+              className={getSortDirection(column.key)}
+            >
+              {column.label}
+              {sortConfig.key === column.key && (
+                <span>{sortConfig.direction === 'asc' ? '▲' : '▼'}</span>
+              )}
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {sortedData.map((row) => (
+          <tr key={row.id}>
+            {columns.map((column) => (
+              <td key={column.key}>{row[column.key]}</td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  )
+}
+```
+
+**Return Values:**
+| Property | Type | Description |
+|----------|------|-------------|
+| `sortedData` | `T[]` | Data sorted by current config |
+| `sortConfig` | `{ key: string, direction: 'asc' \| 'desc' }` | Current sort state |
+| `requestSort` | `(key: string) => void` | Toggle sort on column |
+| `getSortDirection` | `(key: string) => string` | Get CSS class for column |
+
+### useVideoBanner
+
+Video banner management:
+
+```tsx
+import { useVideoBanner } from '@carletonuniversity/rds'
+
+function HeroBanner({ videoSrc, imageSrc }) {
+  const {
+    isVideoLoaded,
+    isVideoPlaying,
+    videoRef,
+    playVideo,
+    pauseVideo,
+    toggleVideo,
+  } = useVideoBanner()
+
+  return (
+    <div className="relative">
+      {/* Fallback image */}
+      <img
+        src={imageSrc}
+        className={isVideoLoaded ? 'hidden' : 'block'}
+        alt=""
+      />
+
+      {/* Video */}
+      <video
+        ref={videoRef}
+        src={videoSrc}
+        className={isVideoLoaded ? 'block' : 'hidden'}
+        muted
+        loop
+        playsInline
+      />
+
+      <button onClick={toggleVideo}>
+        {isVideoPlaying ? 'Pause' : 'Play'}
+      </button>
+    </div>
+  )
+}
+```
+
+**Return Values:**
+| Property | Type | Description |
+|----------|------|-------------|
+| `isVideoLoaded` | `boolean` | Video has loaded |
+| `isVideoPlaying` | `boolean` | Video is currently playing |
+| `videoRef` | `RefObject<HTMLVideoElement>` | Ref to attach to video |
+| `playVideo` | `() => void` | Start playing |
+| `pauseVideo` | `() => void` | Pause playback |
+| `toggleVideo` | `() => void` | Toggle play/pause |
+
+---
+
+## Helper Functions
+
+### Option Classes
+
+Styling for select options:
+
+```tsx
+// lib/helpers/optionClasses.tsx
+export const optionClasses = {
+  // React Select customization
+  control: (state) => ({
+    ...baseControlStyles,
+    borderColor: state.isFocused ? '#bf112b' : '#d1d5db',
+  }),
+  option: (state) => ({
+    ...baseOptionStyles,
+    backgroundColor: state.isSelected ? '#bf112b' : 'white',
+    color: state.isSelected ? 'white' : '#374151',
+  }),
+  // ... more customizations
+}
+```
+
+### General Functions
+
+```tsx
+// lib/helpers/functions.js
+
+// Format date for display
+export function formatDate(date, format = 'MMM d, yyyy') {
+  // Implementation using date-fns
+}
+
+// Sanitize HTML content
+export function sanitizeHtml(html) {
+  // Implementation using DOMPurify
+}
+
+// Generate unique ID
+export function generateId(prefix = 'rds') {
+  return `${prefix}-${Math.random().toString(36).substr(2, 9)}`
+}
+
+// Debounce function
+export function debounce(func, wait) {
+  let timeout
+  return function executedFunction(...args) {
+    const later = () => {
+      clearTimeout(timeout)
+      func(...args)
+    }
+    clearTimeout(timeout)
+    timeout = setTimeout(later, wait)
+  }
+}
+
+// Truncate text
+export function truncateText(text, maxLength, suffix = '...') {
+  if (text.length <= maxLength) return text
+  return text.substring(0, maxLength - suffix.length) + suffix
+}
+```
+
+---
+
+## Asset Lists
+
+### Icon Names
+
+Available Font Awesome icons:
+
+```tsx
+import { iconNames } from '@carletonuniversity/rds'
+
+// iconNames is an array of available icon class names
+// ['fa-solid fa-check', 'fa-solid fa-times', 'fa-brands fa-github', ...]
+
+function IconPicker({ value, onChange }) {
+  return (
+    <select value={value} onChange={(e) => onChange(e.target.value)}>
+      {iconNames.map((icon) => (
+        <option key={icon} value={icon}>
+          {icon}
+        </option>
+      ))}
+    </select>
+  )
+}
+```
+
+### Background Image Names
+
+Available background images:
+
+```tsx
+import { bgImageNames } from '@carletonuniversity/rds'
+
+// bgImageNames is an array of background image file names
+// ['pattern-1.svg', 'pattern-2.svg', 'gradient-1.jpg', ...]
+
+function BackgroundPicker({ value, onChange }) {
+  return (
+    <select value={value} onChange={(e) => onChange(e.target.value)}>
+      {bgImageNames.map((bg) => (
+        <option key={bg} value={bg}>
+          {bg}
+        </option>
+      ))}
+    </select>
+  )
+}
+```
+
+### Video Lists
+
+Available video resources:
+
+```tsx
+import { videoBanner, videoSplash } from '@carletonuniversity/rds'
+
+// videoBanner - list of banner video options
+// videoSplash - list of splash/hero video options
+```
+
+---
+
+## Context Providers
+
+### LinkProvider
+
+Customize link component across all RDS components:
+
+```tsx
+import { LinkProvider } from '@carletonuniversity/rds'
+import Link from 'next/link'
+
+// Use Next.js Link component
+function App({ children }) {
+  return (
+    <LinkProvider value={Link}>
+      {children}
+    </LinkProvider>
+  )
+}
+
+// Use React Router Link
+import { Link as RouterLink } from 'react-router-dom'
+
+function App({ children }) {
+  return (
+    <LinkProvider value={RouterLink}>
+      {children}
+    </LinkProvider>
+  )
+}
+```
+
+### useLinkContext
+
+Access link component in custom components:
+
+```tsx
+import { useLinkContext } from '@carletonuniversity/rds'
+
+function MyComponent({ href, children }) {
+  const Link = useLinkContext()
+
+  return (
+    <Link href={href} className="my-link">
+      {children}
+    </Link>
+  )
+}
+```
+
+---
+
+## Usage Examples
+
+### Building a Responsive Card Grid
+
+```tsx
+import { utils, Card, Column } from '@carletonuniversity/rds'
+
+function CardGrid({ cards, columns = '3', gap = 'lg' }) {
+  return (
+    <div className={utils.maxWidthClasses['7xl']}>
+      <Column cols={columns} gap={gap}>
+        {cards.map((card) => (
+          <Card key={card.id}>
+            <Card.Figure className={utils.aspectRatioClasses.landscape}>
+              <img src={card.image} alt={card.title} />
+            </Card.Figure>
+            <Card.Body>
+              <Card.Header
+                title={card.title}
+                className={utils.headerSizeClasses.sm}
+              />
+              <Card.Excerpt text={card.excerpt} />
+            </Card.Body>
+          </Card>
+        ))}
+      </Column>
+    </div>
+  )
+}
+```
+
+### Form with Validation
+
+```tsx
+import { Form, Input, FileUpload } from '@carletonuniversity/rds'
+import { fileUploadValidationSchema } from '@carletonuniversity/rds'
+import * as Yup from 'yup'
+
+const schema = Yup.object({
+  name: Yup.string().required('Name is required'),
+  document: fileUploadValidationSchema({
+    maxSize: 5242880,
+    allowedTypes: ['application/pdf'],
+    required: true,
+  }),
+})
+
+function ApplicationForm() {
+  return (
+    <Form
+      initialValues={{ name: '', document: null }}
+      validationSchema={schema}
+      onSubmit={handleSubmit}
+    >
+      <Form.Field name="name" label="Name" required>
+        <Input name="name" />
+      </Form.Field>
+
+      <Form.Field name="document" label="Upload PDF" required>
+        <FileUpload name="document" accept=".pdf" />
+      </Form.Field>
+
+      <Form.Button type="submit">Submit</Form.Button>
+    </Form>
+  )
+}
+```
+
+### Paginated List
+
+```tsx
+import { usePagination, Listing, Pagination } from '@carletonuniversity/rds'
+
+function NewsList({ news }) {
+  const {
+    currentPage,
+    totalPages,
+    paginatedItems,
+    goToPage,
+  } = usePagination(news, 10)
+
+  return (
+    <div>
+      {paginatedItems.map((item) => (
+        <Listing key={item.id}>
+          <Listing.Header title={item.title} />
+          <Listing.Excerpt text={item.excerpt} />
+        </Listing>
+      ))}
+
+      <Pagination
+        currentPage={currentPage}
+        totalPages={totalPages}
+        onPageChange={goToPage}
+      />
+    </div>
+  )
+}
+```
+
+---
+
+## Related Documentation
+
+- [Components](./COMPONENTS.md) - Component catalog
+- [Forms](./FORMS.md) - Form system
+- [Styling](./STYLING.md) - CSS utilities

From 9753c327e45c29c9d14ddeb2008218349278b760 Mon Sep 17 00:00:00 2001
From: Troy Chaplin <troy.chaplin@gmail.com>
Date: Fri, 23 Jan 2026 11:00:19 -0500
Subject: [PATCH 2/3] add: docs

---
 docs/ARCHITECTURE.md |  54 +++++++++--------
 docs/COMPONENTS.md   |  92 +++++++++-------------------
 docs/CONTRIBUTING.md |  92 +++++++++++++++-------------
 docs/FORMS.md        | 115 ++++++++++++-----------------------
 docs/GUTENBERG.md    | 105 ++++++++++++--------------------
 docs/IMPROVEMENTS.md |  69 ++++++++++++++++++---
 docs/LAYOUTS.md      |  77 +++++++++++------------
 docs/MIGRATION.md    |  57 +++++++++++------
 docs/README.md       |  50 +++++++--------
 docs/STYLING.md      | 141 +++++++++++++++++++++----------------------
 docs/TESTING.md      |  20 +++---
 docs/UTILITIES.md    | 114 ++++++++--------------------------
 12 files changed, 449 insertions(+), 537 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index b12cd5fdd..fb7180864 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -82,7 +82,9 @@ export default defineConfig({
       fileName: (format) => `rds.${format}.js`,
     },
     rollupOptions: {
-      external: [/* all dependencies externalized */],
+      external: [
+        /* all dependencies externalized */
+      ],
       output: {
         globals: {
           react: 'React',
@@ -97,12 +99,12 @@ export default defineConfig({
 
 ### Build Outputs
 
-| Output | Format | Use Case |
-|--------|--------|----------|
-| `dist/rds.es.js` | ES Modules | Modern bundlers (Vite, webpack 5+) |
-| `dist/rds.umd.js` | UMD | Browser `<script>` tags, older bundlers |
-| `dist/main.d.ts` | TypeScript | Type definitions |
-| `dist/style.css` | CSS | Compiled styles |
+| Output            | Format     | Use Case                                |
+| ----------------- | ---------- | --------------------------------------- |
+| `dist/rds.es.js`  | ES Modules | Modern bundlers (Vite, webpack 5+)      |
+| `dist/rds.umd.js` | UMD        | Browser `<script>` tags, older bundlers |
+| `dist/main.d.ts`  | TypeScript | Type definitions                        |
+| `dist/style.css`  | CSS        | Compiled styles                         |
 
 ### Bundle Size Limits
 
@@ -133,6 +135,7 @@ npm run create-lists
 ### CSS Processing
 
 PostCSS pipeline with:
+
 1. **Tailwind CSS** - Utility-first styles
 2. **PostCSS Nesting** - CSS nesting support
 3. **Autoprefixer** - Browser prefixes
@@ -231,6 +234,7 @@ export const Card = Object.assign(CardWrapper, {
 ```
 
 **Usage:**
+
 ```tsx
 <Card>
   <Card.Figure src="/image.jpg" />
@@ -244,6 +248,7 @@ export const Card = Object.assign(CardWrapper, {
 ### TypeScript Patterns
 
 **Props Interface Pattern:**
+
 ```typescript
 export interface ButtonProps extends React.ComponentPropsWithoutRef<'button'> {
   color?: 'red' | 'grey' | 'dark-grey' | 'black' | 'white'
@@ -254,6 +259,7 @@ export interface ButtonProps extends React.ComponentPropsWithoutRef<'button'> {
 ```
 
 **Discriminated Union Pattern:**
+
 ```typescript
 // Button with title
 interface ButtonTitleProps extends BaseButtonProps {
@@ -305,26 +311,26 @@ import { Link } from 'next/link'
 
 ### Key Runtime Dependencies
 
-| Package | Version | Purpose |
-|---------|---------|---------|
-| `formik` | 2.4.9 | Form state management |
-| `yup` | 1.7.1 | Schema validation |
-| `date-fns` | 4.1.0 | Date utilities |
-| `react-select` | 5.10.2 | Enhanced select dropdown |
-| `react-player` | 3.4.0 | Video player |
-| `dompurify` | 3.3.1 | HTML sanitization |
-| `@react-google-maps/api` | 2.20.8 | Google Maps |
+| Package                  | Version | Purpose                  |
+| ------------------------ | ------- | ------------------------ |
+| `formik`                 | 2.4.9   | Form state management    |
+| `yup`                    | 1.7.1   | Schema validation        |
+| `date-fns`               | 4.1.0   | Date utilities           |
+| `react-select`           | 5.10.2  | Enhanced select dropdown |
+| `react-player`           | 3.4.0   | Video player             |
+| `dompurify`              | 3.3.1   | HTML sanitization        |
+| `@react-google-maps/api` | 2.20.8  | Google Maps              |
 
 ### Styling Dependencies
 
-| Package | Purpose |
-|---------|---------|
-| `tailwindcss` | Utility CSS framework |
-| `rds-tailwind-theme` | Carleton custom theme preset |
-| `@tailwindcss/forms` | Form element styles |
-| `@tailwindcss/typography` | Prose styles |
-| `@tailwindcss/aspect-ratio` | Aspect ratio utilities |
-| `@tailwindcss/container-queries` | Container queries |
+| Package                          | Purpose                      |
+| -------------------------------- | ---------------------------- |
+| `tailwindcss`                    | Utility CSS framework        |
+| `rds-tailwind-theme`             | Carleton custom theme preset |
+| `@tailwindcss/forms`             | Form element styles          |
+| `@tailwindcss/typography`        | Prose styles                 |
+| `@tailwindcss/aspect-ratio`      | Aspect ratio utilities       |
+| `@tailwindcss/container-queries` | Container queries            |
 
 ## Configuration Files
 
diff --git a/docs/COMPONENTS.md b/docs/COMPONENTS.md
index ce918b603..a20ae2e75 100644
--- a/docs/COMPONENTS.md
+++ b/docs/COMPONENTS.md
@@ -218,7 +218,7 @@ List item component with similar structure to Card.
 ```tsx
 import { Listing } from '@carletonuniversity/rds'
 
-<Listing>
+;<Listing>
   <Listing.Figure>
     <img src="/thumb.jpg" alt="" />
   </Listing.Figure>
@@ -253,10 +253,7 @@ Descriptive text blocks, often used for definition lists.
 ```tsx
 import { Description } from '@carletonuniversity/rds'
 
-<Description
-  title="Term"
-  content="Definition or explanation of the term."
-/>
+;<Description title="Term" content="Definition or explanation of the term." />
 ```
 
 ---
@@ -268,7 +265,7 @@ Expandable/collapsible content section.
 ```tsx
 import { Details } from '@carletonuniversity/rds'
 
-<Details summary="Click to expand">
+;<Details summary="Click to expand">
   <p>Hidden content revealed when expanded.</p>
 </Details>
 ```
@@ -335,7 +332,7 @@ Data table with sorting support.
 ```tsx
 import { Table } from '@carletonuniversity/rds'
 
-<Table>
+;<Table>
   <Table.Header>
     <Table.Row>
       <Table.HeaderCell>Name</Table.HeaderCell>
@@ -362,11 +359,7 @@ Page navigation component.
 ```tsx
 import { Pagination } from '@carletonuniversity/rds'
 
-<Pagination
-  currentPage={1}
-  totalPages={10}
-  onPageChange={(page) => setCurrentPage(page)}
-/>
+;<Pagination currentPage={1} totalPages={10} onPageChange={(page) => setCurrentPage(page)} />
 ```
 
 ---
@@ -378,10 +371,7 @@ Date selection calendar.
 ```tsx
 import { Calendar } from '@carletonuniversity/rds'
 
-<Calendar
-  selectedDate={selectedDate}
-  onDateSelect={(date) => setSelectedDate(date)}
-/>
+;<Calendar selectedDate={selectedDate} onDateSelect={(date) => setSelectedDate(date)} />
 ```
 
 ---
@@ -395,7 +385,7 @@ Full-screen hero banner with video/image support.
 ```tsx
 import { Splash } from '@carletonuniversity/rds'
 
-<Splash>
+;<Splash>
   <Splash.Background>
     <Splash.Video src="/hero-video.mp4" />
     {/* or */}
@@ -449,11 +439,7 @@ Full-width image section.
 ```tsx
 import { WideImage } from '@carletonuniversity/rds'
 
-<WideImage
-  src="/wide-image.jpg"
-  alt="Description"
-  caption="Image caption"
-/>
+;<WideImage src="/wide-image.jpg" alt="Description" caption="Image caption" />
 ```
 
 ---
@@ -465,7 +451,7 @@ Page header with title and metadata.
 ```tsx
 import { PageHeader } from '@carletonuniversity/rds'
 
-<PageHeader
+;<PageHeader
   title="Page Title"
   subtitle="Page subtitle"
   breadcrumbs={[
@@ -486,10 +472,7 @@ Minimal footer with copyright.
 ```tsx
 import { FooterBasic } from '@carletonuniversity/rds'
 
-<FooterBasic
-  copyrightYear={2024}
-  organization="Carleton University"
-/>
+;<FooterBasic copyrightYear={2024} organization="Carleton University" />
 ```
 
 ### FooterStandard
@@ -499,10 +482,7 @@ Standard footer with navigation links.
 ```tsx
 import { FooterStandard } from '@carletonuniversity/rds'
 
-<FooterStandard
-  links={footerLinks}
-  socialLinks={socialLinks}
-/>
+;<FooterStandard links={footerLinks} socialLinks={socialLinks} />
 ```
 
 ### FooterAthletics
@@ -528,7 +508,7 @@ Complex navigation component with responsive support.
 ```tsx
 import { Nav } from '@carletonuniversity/rds'
 
-<Nav>
+;<Nav>
   <Nav.Top>
     <Nav.Logo src="/logo.svg" alt="Logo" />
     <Nav.Buttons>
@@ -596,11 +576,7 @@ Styled blockquotes.
 ```tsx
 import { Quote } from '@carletonuniversity/rds'
 
-<Quote
-  text="This is a quoted statement."
-  author="John Doe"
-  citation="Source Publication"
-/>
+;<Quote text="This is a quoted statement." author="John Doe" citation="Source Publication" />
 ```
 
 ---
@@ -612,12 +588,7 @@ Testimonial/review blocks.
 ```tsx
 import { Testimonial } from '@carletonuniversity/rds'
 
-<Testimonial
-  quote="Great experience working with RDS!"
-  author="Jane Smith"
-  role="Developer"
-  image="/jane.jpg"
-/>
+;<Testimonial quote="Great experience working with RDS!" author="Jane Smith" role="Developer" image="/jane.jpg" />
 ```
 
 ---
@@ -629,7 +600,7 @@ Event timeline visualization.
 ```tsx
 import { Timeline } from '@carletonuniversity/rds'
 
-<Timeline
+;<Timeline
   items={[
     { date: '2024-01', title: 'Project Started', description: '...' },
     { date: '2024-03', title: 'Beta Release', description: '...' },
@@ -647,7 +618,7 @@ Filter sidebar for search results.
 ```tsx
 import { FilterPanel } from '@carletonuniversity/rds'
 
-<FilterPanel
+;<FilterPanel
   filters={[
     {
       name: 'category',
@@ -673,7 +644,7 @@ Notification toasts.
 ```tsx
 import { Toast } from '@carletonuniversity/rds'
 
-<Toast
+;<Toast
   type="success"
   message="Action completed successfully!"
   isVisible={showToast}
@@ -690,7 +661,7 @@ Highlighted callout boxes.
 ```tsx
 import { CallOut } from '@carletonuniversity/rds'
 
-<CallOut type="info" title="Note">
+;<CallOut type="info" title="Note">
   Important information for the user.
 </CallOut>
 ```
@@ -719,11 +690,7 @@ Images with captions.
 ```tsx
 import { Figure } from '@carletonuniversity/rds'
 
-<Figure
-  src="/image.jpg"
-  alt="Image description"
-  caption="Figure 1: Image caption"
-/>
+;<Figure src="/image.jpg" alt="Image description" caption="Figure 1: Image caption" />
 ```
 
 ---
@@ -755,7 +722,7 @@ Grid layout for multiple images.
 ```tsx
 import { ImageGrid } from '@carletonuniversity/rds'
 
-<ImageGrid
+;<ImageGrid
   images={[
     { src: '/img1.jpg', alt: 'Image 1' },
     { src: '/img2.jpg', alt: 'Image 2' },
@@ -774,7 +741,7 @@ Image carousel/slider.
 ```tsx
 import { ImageSlider } from '@carletonuniversity/rds'
 
-<ImageSlider
+;<ImageSlider
   images={[
     { src: '/slide1.jpg', alt: 'Slide 1' },
     { src: '/slide2.jpg', alt: 'Slide 2' },
@@ -801,10 +768,13 @@ import {
 } from '@carletonuniversity/rds'
 
 // Use while data is loading
-{isLoading ? <CardNewsLoader /> : <Card>...</Card>}
+{
+  isLoading ? <CardNewsLoader /> : <Card>...</Card>
+}
 ```
 
 **Available Loaders:**
+
 - `CardEventLoader`, `CardIconLoader`, `CardNewsLoader`, `CardPageLoader`, `CardPeopleLoader`, `CardVideoLoader`
 - `ListingEventLoader`, `ListingIconLoader`, `ListingNewsLoader`, `ListingPageLoader`, `ListingPeopleLoader`, `ListingDescriptionLoader`
 - `CalendarLoader`, `DescriptionLoader`, `DescriptionLoaderAccordion`
@@ -823,10 +793,7 @@ import {
 ```tsx
 import { Forbidden403 } from '@carletonuniversity/rds'
 
-<Forbidden403
-  message="You don't have permission to access this page."
-  homeLink="/"
-/>
+;<Forbidden403 message="You don't have permission to access this page." homeLink="/" />
 ```
 
 ### NotFound404
@@ -836,11 +803,7 @@ import { Forbidden403 } from '@carletonuniversity/rds'
 ```tsx
 import { NotFound404 } from '@carletonuniversity/rds'
 
-<NotFound404
-  message="The page you're looking for doesn't exist."
-  homeLink="/"
-  searchLink="/search"
-/>
+;<NotFound404 message="The page you're looking for doesn't exist." homeLink="/" searchLink="/search" />
 ```
 
 ---
@@ -890,6 +853,7 @@ ComponentName/
 ### Testing Components
 
 Each component should have:
+
 1. Storybook stories covering all variants
 2. Cypress tests for interactive behavior
 3. Accessibility checks via Storybook a11y addon
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index d8a24e16b..f088aa0a4 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -39,15 +39,15 @@ npm run storybook
 
 ### Available Scripts
 
-| Script | Description |
-|--------|-------------|
-| `npm run storybook` | Start Storybook dev server on port 6006 |
-| `npm run build` | Build the library |
-| `npm run build:storybook` | Build Storybook for deployment |
-| `npm run lint` | Run ESLint |
-| `npm run prettier` | Format code with Prettier |
-| `npm run test` | Run Cypress tests |
-| `npm run test:ci` | Run tests in CI mode |
+| Script                    | Description                             |
+| ------------------------- | --------------------------------------- |
+| `npm run storybook`       | Start Storybook dev server on port 6006 |
+| `npm run build`           | Build the library                       |
+| `npm run build:storybook` | Build Storybook for deployment          |
+| `npm run lint`            | Run ESLint                              |
+| `npm run prettier`        | Format code with Prettier               |
+| `npm run test`            | Run Cypress tests                       |
+| `npm run test:ci`         | Run tests in CI mode                    |
 
 ---
 
@@ -120,6 +120,7 @@ export interface ButtonProps {
 ### ESLint
 
 Configuration enforces:
+
 - React hooks rules
 - TypeScript best practices
 - Import ordering
@@ -157,14 +158,14 @@ npm run prettier -- --check
 
 ### File Naming
 
-| Type | Convention | Example |
-|------|------------|---------|
-| Components | PascalCase | `Button.tsx` |
-| Stories | PascalCase + .stories | `Button.stories.tsx` |
-| Styles | PascalCase + .css | `Button.css` or `styles.css` |
-| Hooks | camelCase with use prefix | `usePagination.ts` |
-| Utilities | camelCase | `propClasses.tsx` |
-| Types | PascalCase | `ButtonTypes.ts` |
+| Type       | Convention                | Example                      |
+| ---------- | ------------------------- | ---------------------------- |
+| Components | PascalCase                | `Button.tsx`                 |
+| Stories    | PascalCase + .stories     | `Button.stories.tsx`         |
+| Styles     | PascalCase + .css         | `Button.css` or `styles.css` |
+| Hooks      | camelCase with use prefix | `usePagination.ts`           |
+| Utilities  | camelCase                 | `propClasses.tsx`            |
+| Types      | PascalCase                | `ButtonTypes.ts`             |
 
 ---
 
@@ -213,7 +214,7 @@ export const ComponentName = forwardRef<HTMLDivElement, ComponentNameProps>(
         {children}
       </div>
     )
-  }
+  },
 )
 
 ComponentName.displayName = 'ComponentName'
@@ -222,21 +223,24 @@ ComponentName.displayName = 'ComponentName'
 ### Props Guidelines
 
 1. **Use descriptive names**
+
    ```typescript
    // Good
-   isDisabled, hasIcon, showLabel
+   ;(isDisabled, hasIcon, showLabel)
 
    // Bad
-   disabled, icon, label
+   ;(disabled, icon, label)
    ```
 
 2. **Provide sensible defaults**
+
    ```typescript
    color = 'red'
    size = 'md'
    ```
 
 3. **Use TypeScript unions for variants**
+
    ```typescript
    color?: 'red' | 'grey' | 'black'
    size?: 'sm' | 'md' | 'lg'
@@ -283,11 +287,7 @@ All components must:
 - Support reduced motion preferences
 
 ```tsx
-<button
-  aria-label={ariaLabel}
-  aria-disabled={isDisabled}
-  tabIndex={isDisabled ? -1 : 0}
->
+<button aria-label={ariaLabel} aria-disabled={isDisabled} tabIndex={isDisabled ? -1 : 0}>
   {children}
 </button>
 ```
@@ -302,19 +302,19 @@ Format: `<type>: <description>`
 
 ### Commit Types
 
-| Type | Description |
-|------|-------------|
-| `add` | New component or feature |
-| `change` | Modification to existing code |
-| `deprecate` | Deprecation notice |
-| `doc` | Documentation updates |
-| `fix` | Bug fixes |
-| `finish` | Feature completion |
-| `refactor` | Code refactoring |
-| `release` | Release preparation |
-| `revert` | Revert previous commit |
-| `test` | Test-related changes |
-| `upgrade` | Package upgrades |
+| Type        | Description                   |
+| ----------- | ----------------------------- |
+| `add`       | New component or feature      |
+| `change`    | Modification to existing code |
+| `deprecate` | Deprecation notice            |
+| `doc`       | Documentation updates         |
+| `fix`       | Bug fixes                     |
+| `finish`    | Feature completion            |
+| `refactor`  | Code refactoring              |
+| `release`   | Release preparation           |
+| `revert`    | Revert previous commit        |
+| `test`      | Test-related changes          |
+| `upgrade`   | Package upgrades              |
 
 ### Examples
 
@@ -369,9 +369,11 @@ Fixes #123"
 
 ```markdown
 ## Description
+
 Brief description of changes
 
 ## Type of Change
+
 - [ ] New feature
 - [ ] Bug fix
 - [ ] Refactor
@@ -379,17 +381,21 @@ Brief description of changes
 - [ ] Other (describe)
 
 ## Related Issues
+
 Fixes #123
 
 ## Testing
+
 - [ ] Unit tests added/updated
 - [ ] Storybook stories added/updated
 - [ ] Manual testing completed
 
 ## Screenshots (if applicable)
+
 [Add screenshots]
 
 ## Checklist
+
 - [ ] Code follows project standards
 - [ ] Self-reviewed code
 - [ ] Comments added for complex logic
@@ -508,11 +514,11 @@ When making changes:
 
 ### Test Coverage
 
-| Component Type | Minimum Coverage |
-|----------------|------------------|
-| Critical (Button, Form) | 90% |
-| Standard | 70% |
-| Layout | 60% |
+| Component Type          | Minimum Coverage |
+| ----------------------- | ---------------- |
+| Critical (Button, Form) | 90%              |
+| Standard                | 70%              |
+| Layout                  | 60%              |
 
 ### Adding Tests
 
diff --git a/docs/FORMS.md b/docs/FORMS.md
index 6b09c741f..5e64f4708 100644
--- a/docs/FORMS.md
+++ b/docs/FORMS.md
@@ -18,12 +18,12 @@ RDS provides a comprehensive form system built on Formik and Yup for state manag
 
 ### Dependencies
 
-| Package | Version | Purpose |
-|---------|---------|---------|
-| `formik` | 2.4.9 | Form state management |
-| `yup` | 1.7.1 | Schema validation |
-| `react-select` | 5.10.2 | Enhanced select dropdowns |
-| `react-datepicker` | 9.1.0 | Date picker |
+| Package            | Version | Purpose                   |
+| ------------------ | ------- | ------------------------- |
+| `formik`           | 2.4.9   | Form state management     |
+| `yup`              | 1.7.1   | Schema validation         |
+| `react-select`     | 5.10.2  | Enhanced select dropdowns |
+| `react-datepicker` | 9.1.0   | Date picker               |
 
 ### Import
 
@@ -100,17 +100,17 @@ function ContactForm() {
 
 ### Form Subcomponents
 
-| Component | Description |
-|-----------|-------------|
-| `Form.Field` | Field wrapper with label and error |
-| `Form.FieldSet` | Group of related fields |
-| `Form.Button` | Styled form button |
-| `Form.FieldGroup` | Horizontal field group |
-| `Form.FieldControl` | Field control wrapper |
-| `Form.FieldArrayContainer` | Dynamic field arrays |
-| `Form.FieldWrapper` | Generic field wrapper |
-| `Form.Error` | Error message display |
-| `Form.UseError` | Hook for custom errors |
+| Component                  | Description                        |
+| -------------------------- | ---------------------------------- |
+| `Form.Field`               | Field wrapper with label and error |
+| `Form.FieldSet`            | Group of related fields            |
+| `Form.Button`              | Styled form button                 |
+| `Form.FieldGroup`          | Horizontal field group             |
+| `Form.FieldControl`        | Field control wrapper              |
+| `Form.FieldArrayContainer` | Dynamic field arrays               |
+| `Form.FieldWrapper`        | Generic field wrapper              |
+| `Form.Error`               | Error message display              |
+| `Form.UseError`            | Hook for custom errors             |
 
 ---
 
@@ -119,12 +119,7 @@ function ContactForm() {
 Wraps form inputs with label, helper text, and error display.
 
 ```tsx
-<Form.Field
-  name="email"
-  label="Email Address"
-  helperText="We'll never share your email"
-  required
->
+<Form.Field name="email" label="Email Address" helperText="We'll never share your email" required>
   <Input name="email" type="email" placeholder="Enter email" />
 </Form.Field>
 ```
@@ -184,7 +179,7 @@ Dynamic field arrays for repeatable fields.
 ```tsx
 import { FieldArray } from 'formik'
 
-<FieldArray name="addresses">
+;<FieldArray name="addresses">
   {({ push, remove }) => (
     <Form.FieldArrayContainer>
       {values.addresses.map((_, index) => (
@@ -252,11 +247,7 @@ Multi-line text input.
 ```tsx
 import { TextArea } from '@carletonuniversity/rds'
 
-<TextArea
-  name="description"
-  rows={5}
-  placeholder="Enter description..."
-/>
+;<TextArea name="description" rows={5} placeholder="Enter description..." />
 ```
 
 **Props:**
@@ -360,7 +351,7 @@ Radio button for single selection from options.
 ```tsx
 import { Radio } from '@carletonuniversity/rds'
 
-<Form.FieldSet legend="Preferred Contact Method">
+;<Form.FieldSet legend="Preferred Contact Method">
   <Radio name="contactMethod" value="email" label="Email" />
   <Radio name="contactMethod" value="phone" label="Phone" />
   <Radio name="contactMethod" value="mail" label="Mail" />
@@ -492,7 +483,7 @@ Google Places autocomplete for address input.
 ```tsx
 import { PlacesAutoComplete } from '@carletonuniversity/rds'
 
-<PlacesAutoComplete
+;<PlacesAutoComplete
   name="address"
   placeholder="Enter address"
   onPlaceSelected={(place) => {
@@ -538,11 +529,9 @@ Helper text display for additional field information.
 ```tsx
 import { HelperText } from '@carletonuniversity/rds'
 
-<Form.Field name="password" label="Password">
+;<Form.Field name="password" label="Password">
   <Input name="password" type="password" />
-  <HelperText>
-    Must be at least 8 characters with one uppercase letter
-  </HelperText>
+  <HelperText>Must be at least 8 characters with one uppercase letter</HelperText>
 </Form.Field>
 ```
 
@@ -559,24 +548,16 @@ import * as Yup from 'yup'
 
 const validationSchema = Yup.object({
   // Required string
-  name: Yup.string()
-    .required('Name is required')
-    .min(2, 'Name must be at least 2 characters'),
+  name: Yup.string().required('Name is required').min(2, 'Name must be at least 2 characters'),
 
   // Email
-  email: Yup.string()
-    .email('Invalid email address')
-    .required('Email is required'),
+  email: Yup.string().email('Invalid email address').required('Email is required'),
 
   // Phone (optional)
-  phone: Yup.string()
-    .matches(/^\d{10}$/, 'Phone must be 10 digits'),
+  phone: Yup.string().matches(/^\d{10}$/, 'Phone must be 10 digits'),
 
   // Number range
-  age: Yup.number()
-    .min(18, 'Must be at least 18')
-    .max(120, 'Must be under 120')
-    .required('Age is required'),
+  age: Yup.number().min(18, 'Must be at least 18').max(120, 'Must be under 120').required('Age is required'),
 
   // Conditional validation
   website: Yup.string()
@@ -587,16 +568,13 @@ const validationSchema = Yup.object({
     }),
 
   // Array validation
-  tags: Yup.array()
-    .of(Yup.string())
-    .min(1, 'Select at least one tag'),
+  tags: Yup.array().of(Yup.string()).min(1, 'Select at least one tag'),
 
   // Nested object
   address: Yup.object({
     street: Yup.string().required('Street is required'),
     city: Yup.string().required('City is required'),
-    postalCode: Yup.string()
-      .matches(/^[A-Z]\d[A-Z] \d[A-Z]\d$/, 'Invalid postal code'),
+    postalCode: Yup.string().matches(/^[A-Z]\d[A-Z] \d[A-Z]\d$/, 'Invalid postal code'),
   }),
 })
 ```
@@ -606,10 +584,7 @@ const validationSchema = Yup.object({
 RDS provides pre-built validation schemas in `/lib/helpers/`:
 
 ```tsx
-import {
-  fileUploadValidationSchema,
-  imageUploadValidationSchema,
-} from '@carletonuniversity/rds'
+import { fileUploadValidationSchema, imageUploadValidationSchema } from '@carletonuniversity/rds'
 
 // File upload validation
 const schema = Yup.object({
@@ -785,20 +760,13 @@ import { Form, Input, Select } from '@carletonuniversity/rds'
 
 function MyBlockEdit({ attributes, setAttributes }) {
   return (
-    <Form
-      initialValues={attributes}
-      onSubmit={(values) => setAttributes(values)}
-      enableReinitialize
-    >
+    <Form initialValues={attributes} onSubmit={(values) => setAttributes(values)} enableReinitialize>
       <Form.Field name="title" label="Title">
         <Input name="title" />
       </Form.Field>
 
       <Form.Field name="category" label="Category">
-        <Select
-          name="category"
-          options={categoryOptions}
-        />
+        <Select name="category" options={categoryOptions} />
       </Form.Field>
     </Form>
   )
@@ -807,10 +775,7 @@ function MyBlockEdit({ attributes, setAttributes }) {
 // Frontend component
 function MyBlockView({ attributes }) {
   return (
-    <Form
-      initialValues={{}}
-      onSubmit={handleSubmit}
-    >
+    <Form initialValues={{}} onSubmit={handleSubmit}>
       {/* Form fields */}
     </Form>
   )
@@ -831,26 +796,30 @@ function MyBlockView({ attributes }) {
 ### Common Issues
 
 **1. Field not updating**
+
 ```tsx
 // Ensure name prop matches initialValues key
 <Input name="email" /> // Must have initialValues.email
 ```
 
 **2. Validation not triggering**
+
 ```tsx
 // Check schema field names match form field names
 const schema = Yup.object({
-  email: Yup.string().email() // Must match <Input name="email" />
+  email: Yup.string().email(), // Must match <Input name="email" />
 })
 ```
 
 **3. Select not working with Formik**
+
 ```tsx
 // Use the RDS Select component, not native <select>
 import { Select } from '@carletonuniversity/rds'
 ```
 
 **4. Date values**
+
 ```tsx
 // DateTime returns Date objects
 // Convert for API if needed
@@ -874,11 +843,7 @@ function FormDebug() {
 
   if (process.env.NODE_ENV !== 'development') return null
 
-  return (
-    <pre>
-      {JSON.stringify({ values, errors, touched }, null, 2)}
-    </pre>
-  )
+  return <pre>{JSON.stringify({ values, errors, touched }, null, 2)}</pre>
 }
 ```
 
diff --git a/docs/GUTENBERG.md b/docs/GUTENBERG.md
index 3f6d19b86..84199989f 100644
--- a/docs/GUTENBERG.md
+++ b/docs/GUTENBERG.md
@@ -64,12 +64,12 @@ npm install @carletonuniversity/rds
 
 ### Export Formats
 
-| Format | File | Use Case |
-|--------|------|----------|
-| ES Modules | `dist/rds.es.js` | Modern bundlers |
-| UMD | `dist/rds.umd.js` | Script tags, older bundlers |
-| CSS | `dist/style.css` | Styles |
-| Types | `dist/main.d.ts` | TypeScript support |
+| Format     | File              | Use Case                    |
+| ---------- | ----------------- | --------------------------- |
+| ES Modules | `dist/rds.es.js`  | Modern bundlers             |
+| UMD        | `dist/rds.umd.js` | Script tags, older bundlers |
+| CSS        | `dist/style.css`  | Styles                      |
+| Types      | `dist/main.d.ts`  | TypeScript support          |
 
 ### Block Plugin Structure
 
@@ -97,6 +97,7 @@ my-blocks-plugin/
 ### 1. Block Registration
 
 `block.json`:
+
 ```json
 {
   "$schema": "https://schemas.wp.org/trunk/block.json",
@@ -134,6 +135,7 @@ my-blocks-plugin/
 ### 2. Block Index
 
 `index.js`:
+
 ```jsx
 import { registerBlockType } from '@wordpress/blocks'
 import Edit from './edit'
@@ -149,6 +151,7 @@ registerBlockType(metadata.name, {
 ### 3. Edit Component
 
 `edit.js`:
+
 ```jsx
 import { useBlockProps, InspectorControls } from '@wordpress/block-editor'
 import { PanelBody, SelectControl, TextControl } from '@wordpress/components'
@@ -173,11 +176,7 @@ export default function Edit({ attributes, setAttributes }) {
             ]}
             onChange={(value) => setAttributes({ type: value })}
           />
-          <TextControl
-            label="Title"
-            value={title}
-            onChange={(value) => setAttributes({ title: value })}
-          />
+          <TextControl label="Title" value={title} onChange={(value) => setAttributes({ title: value })} />
         </PanelBody>
       </InspectorControls>
 
@@ -194,6 +193,7 @@ export default function Edit({ attributes, setAttributes }) {
 ### 4. Save Component
 
 For static blocks:
+
 ```jsx
 import { useBlockProps } from '@wordpress/block-editor'
 import { Alert } from '@carletonuniversity/rds'
@@ -213,6 +213,7 @@ export default function Save({ attributes }) {
 ```
 
 For dynamic blocks (PHP rendered):
+
 ```jsx
 export default function Save() {
   return null // Rendered by PHP
@@ -325,6 +326,7 @@ add_action('enqueue_block_editor_assets', 'enqueue_rds_styles');
 ```
 
 Or in JavaScript:
+
 ```jsx
 // Import styles in your block entry point
 import '@carletonuniversity/rds/dist/style.css'
@@ -425,24 +427,16 @@ function CardEdit({ attributes, setAttributes }) {
       <Card.Figure>
         <MediaUploadCheck>
           <MediaUpload
-            onSelect={(media) =>
-              setAttributes({ imageId: media.id, imageUrl: media.url })
-            }
+            onSelect={(media) => setAttributes({ imageId: media.id, imageUrl: media.url })}
             allowedTypes={['image']}
             value={imageId}
-            render={({ open }) => (
-              imageUrl ? (
-                <img src={imageUrl} onClick={open} alt="" />
-              ) : (
-                <WPButton onClick={open}>Select Image</WPButton>
-              )
-            )}
+            render={({ open }) =>
+              imageUrl ? <img src={imageUrl} onClick={open} alt="" /> : <WPButton onClick={open}>Select Image</WPButton>
+            }
           />
         </MediaUploadCheck>
       </Card.Figure>
-      <Card.Body>
-        {/* ... */}
-      </Card.Body>
+      <Card.Body>{/* ... */}</Card.Body>
     </Card>
   )
 }
@@ -462,19 +456,13 @@ function ButtonEdit({ attributes, setAttributes }) {
 
   return (
     <>
-      <Button
-        color="red"
-        onClick={() => setIsLinkOpen(true)}
-      >
+      <Button color="red" onClick={() => setIsLinkOpen(true)}>
         {text || 'Add Text'}
       </Button>
 
       {isLinkOpen && (
         <Popover onClose={() => setIsLinkOpen(false)}>
-          <LinkControl
-            value={{ url }}
-            onChange={({ url }) => setAttributes({ url })}
-          />
+          <LinkControl value={{ url }} onChange={({ url }) => setAttributes({ url })} />
         </Popover>
       )}
     </>
@@ -486,14 +474,7 @@ function ButtonEdit({ attributes, setAttributes }) {
 
 ```jsx
 import { InspectorControls } from '@wordpress/block-editor'
-import {
-  PanelBody,
-  PanelRow,
-  SelectControl,
-  ToggleControl,
-  RangeControl,
-  ColorPalette,
-} from '@wordpress/components'
+import { PanelBody, PanelRow, SelectControl, ToggleControl, RangeControl, ColorPalette } from '@wordpress/components'
 
 function BlockInspector({ attributes, setAttributes }) {
   return (
@@ -573,21 +554,13 @@ export default function Edit({ attributes, setAttributes }) {
             ]}
             onChange={(type) => setAttributes({ type })}
           />
-          <TextControl
-            label="Title"
-            value={title}
-            onChange={(title) => setAttributes({ title })}
-          />
+          <TextControl label="Title" value={title} onChange={(title) => setAttributes({ title })} />
         </PanelBody>
       </InspectorControls>
 
       <div {...useBlockProps()}>
         <Alert type={type} title={title}>
-          <RichText
-            value={content}
-            onChange={(content) => setAttributes({ content })}
-            placeholder="Alert content..."
-          />
+          <RichText value={content} onChange={(content) => setAttributes({ content })} placeholder="Alert content..." />
         </Alert>
       </div>
     </>
@@ -607,11 +580,14 @@ import { Card, Column } from '@carletonuniversity/rds'
 export default function Edit({ attributes, setAttributes }) {
   const { columns, postType, count, showExcerpt, showImage } = attributes
 
-  const posts = useSelect((select) => {
-    return select('core').getEntityRecords('postType', postType, {
-      per_page: count,
-    })
-  }, [postType, count])
+  const posts = useSelect(
+    (select) => {
+      return select('core').getEntityRecords('postType', postType, {
+        per_page: count,
+      })
+    },
+    [postType, count],
+  )
 
   return (
     <>
@@ -650,17 +626,12 @@ export default function Edit({ attributes, setAttributes }) {
             <Card key={post.id}>
               {showImage && post.featured_media && (
                 <Card.Figure>
-                  <img
-                    src={post._embedded?.['wp:featuredmedia']?.[0]?.source_url}
-                    alt={post.title.rendered}
-                  />
+                  <img src={post._embedded?.['wp:featuredmedia']?.[0]?.source_url} alt={post.title.rendered} />
                 </Card.Figure>
               )}
               <Card.Body>
                 <Card.Header title={post.title.rendered} />
-                {showExcerpt && (
-                  <Card.Excerpt text={post.excerpt.rendered} />
-                )}
+                {showExcerpt && <Card.Excerpt text={post.excerpt.rendered} />}
               </Card.Body>
             </Card>
           ))}
@@ -684,7 +655,7 @@ export default function Edit({ attributes, setAttributes }) {
 import '@carletonuniversity/rds/dist/style.css'
 
 // Or in PHP
-wp_enqueue_style('rds-styles', '...');
+wp_enqueue_style('rds-styles', '...')
 ```
 
 #### 2. React Version Mismatch
@@ -785,11 +756,7 @@ registerBlockType('cu/card', {
 
 ```jsx
 // Use WordPress components for consistency
-import {
-  PanelBody,
-  SelectControl,
-  ToggleControl,
-} from '@wordpress/components'
+import { PanelBody, SelectControl, ToggleControl } from '@wordpress/components'
 
 // Not RDS form components in editor
 ```
@@ -825,11 +792,13 @@ function Edit({ attributes }) {
 - **Dynamic**: Rendered by PHP on each page load
 
 Choose dynamic for:
+
 - Frequently changing content
 - Content pulled from database
 - Complex logic
 
 Choose static for:
+
 - Simple content blocks
 - Better performance
 - Works without PHP
diff --git a/docs/IMPROVEMENTS.md b/docs/IMPROVEMENTS.md
index 088531b03..21c820f94 100644
--- a/docs/IMPROVEMENTS.md
+++ b/docs/IMPROVEMENTS.md
@@ -22,6 +22,7 @@ This document catalogs issues, inconsistencies, and improvement opportunities id
 **Impact:** Slower page loads, especially on mobile.
 
 **Recommendation:**
+
 - Implement SCSS migration (see [MIGRATION.md](./MIGRATION.md))
 - Use CSS-in-JS or CSS Modules for better tree-shaking
 - Extract critical CSS for above-the-fold content
@@ -33,18 +34,21 @@ This document catalogs issues, inconsistencies, and improvement opportunities id
 **Issue:** All components are bundled together in `rds.es.js`. Importing one component imports all.
 
 **Current:**
+
 ```javascript
 // Imports entire library
 import { Button } from '@carletonuniversity/rds'
 ```
 
 **Recommendation:**
+
 ```javascript
 // Ideal: Import only what you need
 import { Button } from '@carletonuniversity/rds/components/Button'
 ```
 
 **Action Items:**
+
 - [ ] Configure Vite/Rollup for per-component builds
 - [ ] Update package.json exports map
 - [ ] Test tree-shaking with different bundlers
@@ -54,11 +58,13 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 ### 3. Tailwind Class Conflicts in WordPress
 
 **Issue:** Tailwind's base styles conflict with WordPress core styles, causing:
+
 - Button styling inconsistencies
 - Form element conflicts
 - Typography issues in Gutenberg editor
 
 **Recommendation:**
+
 - Use CSS scoping with `.rds-scope` wrapper
 - Migrate to SCSS modules for better isolation
 - Document required CSS reset for WordPress
@@ -68,16 +74,19 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 ### 4. Missing TypeScript Strict Types for Some Components
 
 **Issue:** Some components have loose typing:
+
 - `any` types in event handlers
 - Missing return types
 - Optional props without explicit undefined
 
 **Files to Review:**
+
 - Form components
 - Card subcomponents
 - Navigation components
 
 **Recommendation:**
+
 - Enable `noImplicitAny` verification
 - Add explicit return types to all components
 - Use discriminated unions for variant props
@@ -90,13 +99,14 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 
 **Issue:** Props naming varies across components:
 
-| Component | Prop | Alternative |
-|-----------|------|-------------|
-| Button | `isDisabled` | `disabled` |
-| Input | `disabled` | `isDisabled` |
-| Card | `hasImage` | `showImage` |
+| Component | Prop         | Alternative  |
+| --------- | ------------ | ------------ |
+| Button    | `isDisabled` | `disabled`   |
+| Input     | `disabled`   | `isDisabled` |
+| Card      | `hasImage`   | `showImage`  |
 
 **Recommendation:**
+
 - Standardize on `is*` for boolean states
 - Standardize on `has*` for feature toggles
 - Document prop naming conventions
@@ -106,11 +116,13 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 ### 6. No Dark Mode Documentation
 
 **Issue:** Dark mode is supported via Tailwind's `selector` strategy but:
+
 - No documentation on how to enable
 - No Storybook stories showing dark variants
 - Some components may not have dark mode styles
 
 **Recommendation:**
+
 - Add dark mode toggle to Storybook
 - Create dark mode stories for all components
 - Document dark mode implementation
@@ -122,6 +134,7 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 **Issue:** No error boundary components for graceful degradation.
 
 **Recommendation:**
+
 - Create `ErrorBoundary` component
 - Add error states to data-fetching components
 - Document error handling patterns
@@ -131,11 +144,13 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 ### 8. Accessibility Gaps
 
 **Issues Identified:**
+
 - Some interactive elements missing `aria-*` attributes
 - Focus management in modals/dialogs needs review
 - Color contrast not verified for all variants
 
 **Recommendation:**
+
 - Run full a11y audit with axe-core
 - Add keyboard navigation tests
 - Verify WCAG 2.1 AA compliance
@@ -145,11 +160,13 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 ### 9. No Loading/Skeleton Strategy Documentation
 
 **Issue:** 21 loader components exist but:
+
 - No documentation on when to use which
 - No loading state patterns documented
 - Inconsistent naming (`Loader` vs `Skeleton`)
 
 **Recommendation:**
+
 - Create loading state documentation
 - Standardize naming convention
 - Show loading state patterns in Storybook
@@ -159,12 +176,14 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 ### 10. Large Number of Dependencies
 
 **Issue:** Many runtime dependencies increase bundle size:
+
 - `formik` + `yup` for forms
 - `react-select` for dropdowns
 - `react-player` for video
 - `@react-google-maps/api` for maps
 
 **Recommendation:**
+
 - Audit dependency usage
 - Consider lighter alternatives
 - Make heavy dependencies optional/lazy-loaded
@@ -176,11 +195,13 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 ### 11. Storybook Organization
 
 **Issue:** Stories could be better organized:
+
 - No consistent story categories
 - Some components lack comprehensive stories
 - Missing interaction tests
 
 **Recommendation:**
+
 - Reorganize into clear categories
 - Add interaction tests to critical components
 - Create "Examples" section for complex use cases
@@ -192,6 +213,7 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 **Issue:** Not all components have Cypress tests.
 
 **Recommendation:**
+
 - Set coverage targets per component type
 - Add tests for untested components
 - Set up coverage reporting in CI
@@ -203,6 +225,7 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 **Issue:** TypeScript provides compile-time checks but no runtime validation for JavaScript consumers.
 
 **Recommendation:**
+
 - Consider adding PropTypes for critical components
 - Or document TypeScript requirement clearly
 
@@ -213,6 +236,7 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 **Issue:** Changelog requires manual updates.
 
 **Recommendation:**
+
 - Implement conventional-changelog
 - Auto-generate changelog from commits
 - Add changelog CI step
@@ -222,11 +246,13 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 ### 15. Asset Management
 
 **Issue:** Icons and images are stored in `public/` but:
+
 - Large icon list impacts bundle
 - No lazy loading for images
 - Background images not documented
 
 **Recommendation:**
+
 - Lazy load icon list
 - Document available assets
 - Consider SVG sprite for icons
@@ -240,11 +266,13 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 **Issue:** RDS doesn't include WordPress-specific code. Blocks are in separate repository.
 
 **Impact:**
+
 - Duplicated effort in block plugins
 - Inconsistent implementation across 70+ blocks
 - Hard to maintain compatibility
 
 **Recommendation:**
+
 - Create `@carletonuniversity/rds-blocks` package
 - Provide block wrapper components
 - Share block registration patterns
@@ -256,18 +284,26 @@ import { Button } from '@carletonuniversity/rds/components/Button'
 **Issue:** Tailwind reset conflicts with WordPress styles.
 
 **Specific Conflicts:**
+
 ```css
 /* Tailwind resets buttons */
-button { background: transparent; }
+button {
+  background: transparent;
+}
 
 /* WordPress expects */
-.button { /* WordPress styles */ }
+.button {
+  /* WordPress styles */
+}
 
 /* Gutenberg editor */
-.block-editor { /* May override RDS */ }
+.block-editor {
+  /* May override RDS */
+}
 ```
 
 **Recommendation:**
+
 - Document CSS reset requirements
 - Provide WordPress-specific stylesheet
 - Use higher specificity for RDS styles
@@ -281,6 +317,7 @@ button { background: transparent; }
 **Impact:** Potential compatibility issues in block editor.
 
 **Recommendation:**
+
 - Test with WordPress React version
 - Document React version requirements
 - Consider React 18 compatibility mode
@@ -292,6 +329,7 @@ button { background: transparent; }
 **Issue:** Component props don't always align with WordPress block attributes.
 
 **Example:**
+
 ```typescript
 // RDS Component
 interface CardProps {
@@ -306,6 +344,7 @@ interface CardProps {
 ```
 
 **Recommendation:**
+
 - Create prop-to-attribute mapping utilities
 - Document common attribute patterns
 - Provide TypeScript types for block attributes
@@ -317,11 +356,13 @@ interface CardProps {
 **Issue:** Some components may not work with WordPress PHP rendering.
 
 **Components to Review:**
+
 - Components using browser APIs
 - Components with client-side state
 - Interactive components (forms, modals)
 
 **Recommendation:**
+
 - Document SSR compatibility per component
 - Provide PHP render alternatives
 - Mark client-only components clearly
@@ -333,10 +374,12 @@ interface CardProps {
 ### T1. Legacy CSS Files
 
 **Files:**
+
 - `public/index.css` (151KB) - appears to be precompiled CSS
 - Multiple `styles.css` files with mixed approaches
 
 **Recommendation:**
+
 - Audit CSS file usage
 - Remove unused CSS files
 - Consolidate CSS architecture
@@ -348,6 +391,7 @@ interface CardProps {
 **Issue:** Some files use default exports, others named exports.
 
 **Recommendation:**
+
 - Standardize on named exports
 - Update barrel exports in `main.ts`
 - Document export conventions
@@ -359,6 +403,7 @@ interface CardProps {
 **Issue:** `propClasses.tsx` duplicates Tailwind class definitions.
 
 **Recommendation:**
+
 - Use CSS custom properties instead
 - Remove after SCSS migration
 - Or generate from Tailwind config
@@ -370,6 +415,7 @@ interface CardProps {
 **Issue:** Full rebuild on every change.
 
 **Recommendation:**
+
 - Enable Vite caching
 - Consider incremental TypeScript builds
 - Add Storybook build caching
@@ -381,11 +427,13 @@ interface CardProps {
 **Issue:** Heavy components loaded upfront.
 
 **Components to Split:**
+
 - Form components (Formik)
 - Map components (Google Maps)
 - Video components (react-player)
 
 **Recommendation:**
+
 - Implement React.lazy for heavy components
 - Document dynamic import patterns
 - Test loading states
@@ -399,6 +447,7 @@ interface CardProps {
 **Issue:** No auto-generated API documentation from TypeScript.
 
 **Recommendation:**
+
 - Set up TypeDoc or similar
 - Generate prop tables automatically
 - Keep API docs in sync
@@ -410,6 +459,7 @@ interface CardProps {
 **Issue:** No upgrade path documentation.
 
 **Recommendation:**
+
 - Document breaking changes per version
 - Provide codemods for major changes
 - Create upgrade guide
@@ -419,6 +469,7 @@ interface CardProps {
 ### D3. Missing Troubleshooting Guide
 
 **Recommendation:** Create common issues and solutions doc covering:
+
 - Installation problems
 - Style conflicts
 - TypeScript errors
@@ -429,6 +480,7 @@ interface CardProps {
 ### D4. No Performance Guide
 
 **Recommendation:** Document:
+
 - Bundle size optimization
 - Lazy loading patterns
 - Image optimization
@@ -467,6 +519,7 @@ interface CardProps {
 ## Tracking
 
 Use issue labels to track:
+
 - `priority:high` / `priority:medium` / `priority:low`
 - `type:bug` / `type:enhancement` / `type:docs`
 - `component:*` for component-specific issues
diff --git a/docs/LAYOUTS.md b/docs/LAYOUTS.md
index bce5a014c..d084e6a2b 100644
--- a/docs/LAYOUTS.md
+++ b/docs/LAYOUTS.md
@@ -54,7 +54,7 @@ Wrapper for article content, providing proper semantic HTML and typography style
 ```tsx
 import { Article } from '@carletonuniversity/rds'
 
-<Article>
+;<Article>
   <h1>Article Title</h1>
   <p>Article content with proper typography styling...</p>
 </Article>
@@ -67,6 +67,7 @@ import { Article } from '@carletonuniversity/rds'
 | `className` | `string` | - | Additional CSS classes |
 
 **Use Cases:**
+
 - Blog posts
 - News articles
 - Documentation pages
@@ -81,15 +82,19 @@ Sidebar or complementary content area.
 ```tsx
 import { Aside } from '@carletonuniversity/rds'
 
-<div className="flex">
+;<div className="flex">
   <Main>
     <p>Main content</p>
   </Main>
   <Aside>
     <h3>Related Links</h3>
     <ul>
-      <li><a href="#">Link 1</a></li>
-      <li><a href="#">Link 2</a></li>
+      <li>
+        <a href="#">Link 1</a>
+      </li>
+      <li>
+        <a href="#">Link 2</a>
+      </li>
     </ul>
   </Aside>
 </div>
@@ -104,6 +109,7 @@ import { Aside } from '@carletonuniversity/rds'
 | `className` | `string` | - | Additional CSS classes |
 
 **Use Cases:**
+
 - Navigation sidebars
 - Related content
 - Filter panels
@@ -118,7 +124,7 @@ Page body wrapper that provides base styling and layout constraints.
 ```tsx
 import { Body } from '@carletonuniversity/rds'
 
-<Body>
+;<Body>
   <Nav>...</Nav>
   <Main>...</Main>
   <Footer>...</Footer>
@@ -132,6 +138,7 @@ import { Body } from '@carletonuniversity/rds'
 | `className` | `string` | - | Additional CSS classes |
 
 **Use Cases:**
+
 - Root layout wrapper
 - Provides base typography
 - Sets up CSS custom properties
@@ -188,6 +195,7 @@ import { Column } from '@carletonuniversity/rds'
 | `xl` | 2rem (32px) |
 
 **Use Cases:**
+
 - Card grids
 - Feature lists
 - Image galleries
@@ -202,7 +210,7 @@ Floating content box that can be positioned within text content.
 ```tsx
 import { FloatBox } from '@carletonuniversity/rds'
 
-<Article>
+;<Article>
   <p>Main article text...</p>
 
   <FloatBox position="right" width="sm">
@@ -223,6 +231,7 @@ import { FloatBox } from '@carletonuniversity/rds'
 | `className` | `string` | - | Additional CSS classes |
 
 **Use Cases:**
+
 - Pull quotes
 - Sidebar images
 - Related content boxes
@@ -237,11 +246,7 @@ Full-screen image background with overlay content.
 ```tsx
 import { ImageCover } from '@carletonuniversity/rds'
 
-<ImageCover
-  src="/hero-image.jpg"
-  alt="Hero background"
-  overlay="dark"
->
+;<ImageCover src="/hero-image.jpg" alt="Hero background" overlay="dark">
   <h1>Hero Title</h1>
   <p>Hero description text</p>
   <Button>Call to Action</Button>
@@ -267,6 +272,7 @@ import { ImageCover } from '@carletonuniversity/rds'
 | `dark` | Black semi-transparent overlay |
 
 **Use Cases:**
+
 - Hero sections
 - Full-bleed images
 - Landing pages
@@ -281,7 +287,7 @@ Main content area wrapper with semantic `<main>` element.
 ```tsx
 import { Main } from '@carletonuniversity/rds'
 
-<Body>
+;<Body>
   <Nav>...</Nav>
   <Main>
     <Section>
@@ -300,6 +306,7 @@ import { Main } from '@carletonuniversity/rds'
 | `className` | `string` | - | Additional CSS classes |
 
 **Use Cases:**
+
 - Primary content wrapper
 - Accessibility landmark
 - Skip-link target
@@ -357,6 +364,7 @@ import { Section } from '@carletonuniversity/rds'
 | `full` | 100% |
 
 **Use Cases:**
+
 - Page sections
 - Content containers
 - Feature areas
@@ -394,6 +402,7 @@ import { StackedList } from '@carletonuniversity/rds'
 | `className` | `string` | - | Additional CSS classes |
 
 **Use Cases:**
+
 - News listings
 - Search results
 - Event lists
@@ -408,7 +417,7 @@ Wave decoration background layout for visual interest.
 ```tsx
 import { WideWave } from '@carletonuniversity/rds'
 
-<WideWave color="red" position="top">
+;<WideWave color="red" position="top">
   <Section>
     <h2>Featured Content</h2>
     <p>Content with wave decoration above</p>
@@ -425,6 +434,7 @@ import { WideWave } from '@carletonuniversity/rds'
 | `className` | `string` | - | Additional CSS classes |
 
 **Use Cases:**
+
 - Section dividers
 - Call-to-action areas
 - Visual breaks
@@ -444,9 +454,7 @@ function PageLayout({ children }) {
     <Body>
       <Nav>...</Nav>
       <Main>
-        <Section>
-          {children}
-        </Section>
+        <Section>{children}</Section>
       </Main>
       <FooterStandard>...</FooterStandard>
     </Body>
@@ -464,12 +472,8 @@ function TwoColumnLayout({ content, sidebar }) {
     <Main>
       <Section>
         <div className="flex gap-8">
-          <div className="flex-1">
-            {content}
-          </div>
-          <Aside width="narrow">
-            {sidebar}
-          </Aside>
+          <div className="flex-1">{content}</div>
+          <Aside width="narrow">{sidebar}</Aside>
         </div>
       </Section>
     </Main>
@@ -511,18 +515,12 @@ import { ImageCover, Section, Article } from '@carletonuniversity/rds'
 function HeroPage({ hero, content }) {
   return (
     <>
-      <ImageCover
-        src={hero.image}
-        alt={hero.alt}
-        height="half"
-      >
+      <ImageCover src={hero.image} alt={hero.alt} height="half">
         <h1>{hero.title}</h1>
       </ImageCover>
 
       <Section maxWidth="narrow">
-        <Article>
-          {content}
-        </Article>
+        <Article>{content}</Article>
       </Section>
     </>
   )
@@ -538,10 +536,7 @@ function AlternatingSections({ sections }) {
   return (
     <>
       {sections.map((section, index) => (
-        <Section
-          key={index}
-          bgColor={index % 2 === 0 ? 'white' : 'grey-50'}
-        >
+        <Section key={index} bgColor={index % 2 === 0 ? 'white' : 'grey-50'}>
           <TextImage
             title={section.title}
             content={section.content}
@@ -561,13 +556,13 @@ function AlternatingSections({ sections }) {
 
 All layout components are responsive by default:
 
-| Breakpoint | Width | Typical Use |
-|------------|-------|-------------|
-| `sm` | 640px | Mobile landscape |
-| `md` | 768px | Tablets |
-| `lg` | 1024px | Small laptops |
-| `xl` | 1280px | Desktops |
-| `2xl` | 1536px | Large screens |
+| Breakpoint | Width  | Typical Use      |
+| ---------- | ------ | ---------------- |
+| `sm`       | 640px  | Mobile landscape |
+| `md`       | 768px  | Tablets          |
+| `lg`       | 1024px | Small laptops    |
+| `xl`       | 1280px | Desktops         |
+| `2xl`      | 1536px | Large screens    |
 
 ### Mobile-First Approach
 
diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
index 3f3b10a3b..163f037a3 100644
--- a/docs/MIGRATION.md
+++ b/docs/MIGRATION.md
@@ -37,13 +37,13 @@ This document outlines the strategy for migrating RDS from Tailwind CSS to SCSS
 
 ### Timeline Estimate
 
-| Phase | Duration | Components |
-|-------|----------|------------|
-| Foundation | 2-3 weeks | Setup, tokens |
-| Design Tokens | 1-2 weeks | Variables, mixins |
-| Component Migration | 8-12 weeks | 51 components |
-| Cleanup | 1-2 weeks | Remove Tailwind |
-| **Total** | **12-19 weeks** | |
+| Phase               | Duration        | Components        |
+| ------------------- | --------------- | ----------------- |
+| Foundation          | 2-3 weeks       | Setup, tokens     |
+| Design Tokens       | 1-2 weeks       | Variables, mixins |
+| Component Migration | 8-12 weeks      | 51 components     |
+| Cleanup             | 1-2 weeks       | Remove Tailwind   |
+| **Total**           | **12-19 weeks** |                   |
 
 ---
 
@@ -52,39 +52,49 @@ This document outlines the strategy for migrating RDS from Tailwind CSS to SCSS
 ### Why Move Away from Tailwind?
 
 #### 1. Bundle Size
+
 ```
 Current:  ~150KB+ (includes many unused utilities)
 Target:   ~50-80KB (only used styles)
 ```
 
 #### 2. WordPress/Gutenberg Conflicts
+
 Tailwind's reset and utilities often conflict with WordPress core styles:
+
 - Button styling overrides
 - Form element conflicts
 - Typography clashes
 
 #### 3. Customization Difficulty
+
 Currently requires:
+
 - Understanding Tailwind config
 - Modifying `rds-tailwind-theme` package
 - Rebuilding entire library
 
 With SCSS:
+
 - Override CSS custom properties
 - No build step required
 - Standard CSS knowledge
 
 #### 4. Style Isolation
+
 Current issues:
+
 - Global styles can leak between components
 - Hard to scope styles in WordPress
 
 With CSS Modules:
+
 - Automatic class name scoping
 - No style leakage
 - Better encapsulation
 
 #### 5. Developer Experience
+
 - Standard SCSS is more widely known than Tailwind
 - Better IDE support and autocomplete
 - Easier debugging (readable class names)
@@ -105,6 +115,7 @@ With CSS Modules:
 ### Migration Order
 
 Prioritize by:
+
 1. **Complexity** - Simple components first
 2. **Dependencies** - Components used by others first
 3. **Gutenberg usage** - High-usage blocks prioritized
@@ -199,13 +210,13 @@ $color-info: #3b82f6;
 
 // Spacing
 $spacing-unit: 0.25rem; // 4px
-$spacing-1: $spacing-unit * 1;   // 4px
-$spacing-2: $spacing-unit * 2;   // 8px
-$spacing-3: $spacing-unit * 3;   // 12px
-$spacing-4: $spacing-unit * 4;   // 16px
-$spacing-5: $spacing-unit * 5;   // 20px
-$spacing-6: $spacing-unit * 6;   // 24px
-$spacing-8: $spacing-unit * 8;   // 32px
+$spacing-1: $spacing-unit * 1; // 4px
+$spacing-2: $spacing-unit * 2; // 8px
+$spacing-3: $spacing-unit * 3; // 12px
+$spacing-4: $spacing-unit * 4; // 16px
+$spacing-5: $spacing-unit * 5; // 20px
+$spacing-6: $spacing-unit * 6; // 24px
+$spacing-8: $spacing-unit * 8; // 32px
 $spacing-10: $spacing-unit * 10; // 40px
 $spacing-12: $spacing-unit * 12; // 48px
 $spacing-16: $spacing-unit * 16; // 64px
@@ -451,7 +462,7 @@ export function Button({ color = 'red', isSmall, children }) {
         'px-4 py-2 rounded-md font-medium text-sm',
         'transition-colors duration-200',
         colorClasses[color],
-        isSmall && 'px-3 py-1.5 text-xs'
+        isSmall && 'px-3 py-1.5 text-xs',
       )}
     >
       {children}
@@ -557,7 +568,7 @@ export function Button({
         styles.button,
         styles[`button--${colorKey}`],
         isSmall && styles['button--small'],
-        isFull && styles['button--full']
+        isFull && styles['button--full'],
       )}
       disabled={isDisabled}
       data-testid="rds-button"
@@ -584,6 +595,7 @@ npm uninstall rds-tailwind-theme postcss-nesting
 ### 4.2 Update Configuration
 
 Remove Tailwind from:
+
 - `vite.config.ts`
 - `postcss.config.js`
 - Delete `tailwind.config.ts`
@@ -621,9 +633,8 @@ export default defineConfig({
   css: {
     modules: {
       // Generate readable class names in dev
-      generateScopedName: process.env.NODE_ENV === 'production'
-        ? '[hash:base64:8]'
-        : '[name]__[local]___[hash:base64:5]',
+      generateScopedName:
+        process.env.NODE_ENV === 'production' ? '[hash:base64:8]' : '[name]__[local]___[hash:base64:5]',
       localsConvention: 'camelCase',
     },
   },
@@ -715,6 +726,7 @@ declare module '*.module.scss' {
 ### Per-Component Steps
 
 1. **Create SCSS module**
+
    ```
    ComponentName/
    ├── ComponentName.tsx
@@ -725,6 +737,7 @@ declare module '*.module.scss' {
 2. **Write styles using design tokens**
 
 3. **Update component imports**
+
    ```tsx
    import styles from './ComponentName.module.scss'
    ```
@@ -744,10 +757,12 @@ declare module '*.module.scss' {
 ### Visual Regression Testing
 
 Before migration:
+
 1. Capture screenshots of all component states
 2. Save as baseline
 
 After migration:
+
 1. Capture new screenshots
 2. Compare with baseline
 3. Fix any visual differences
@@ -802,20 +817,24 @@ git revert <commit-hash>
 ## Success Criteria
 
 ### Phase 1 Complete When:
+
 - [ ] SCSS infrastructure in place
 - [ ] Variables and mixins defined
 - [ ] Build process works
 
 ### Phase 2 Complete When:
+
 - [ ] All design tokens as CSS custom properties
 - [ ] Theme customization documented
 
 ### Phase 3 Complete When:
+
 - [ ] All 51 components migrated
 - [ ] All tests passing
 - [ ] Visual regression clean
 
 ### Phase 4 Complete When:
+
 - [ ] Tailwind removed
 - [ ] Bundle size reduced
 - [ ] Documentation updated
diff --git a/docs/README.md b/docs/README.md
index 46ff5c26b..824729b8e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,18 +4,18 @@ Welcome to the documentation for the Raven Design System - Carleton University's
 
 ## Quick Links
 
-| Document | Description |
-|----------|-------------|
-| [Architecture](./ARCHITECTURE.md) | System architecture, build process, and project structure |
-| [Components](./COMPONENTS.md) | Complete component catalog with usage examples |
-| [Layouts](./LAYOUTS.md) | Layout components for page structure |
-| [Forms](./FORMS.md) | Form system with Formik integration |
-| [Styling](./STYLING.md) | Current Tailwind CSS implementation |
-| [Utilities](./UTILITIES.md) | Utility functions and helper classes |
-| [Gutenberg Integration](./GUTENBERG.md) | WordPress block development guide |
-| [Testing](./TESTING.md) | Testing with Cypress and Storybook |
-| [Migration Plan](./MIGRATION.md) | Tailwind to SCSS migration roadmap |
-| [Contributing](./CONTRIBUTING.md) | Contribution guidelines and standards |
+| Document                                | Description                                               |
+| --------------------------------------- | --------------------------------------------------------- |
+| [Architecture](./ARCHITECTURE.md)       | System architecture, build process, and project structure |
+| [Components](./COMPONENTS.md)           | Complete component catalog with usage examples            |
+| [Layouts](./LAYOUTS.md)                 | Layout components for page structure                      |
+| [Forms](./FORMS.md)                     | Form system with Formik integration                       |
+| [Styling](./STYLING.md)                 | Current Tailwind CSS implementation                       |
+| [Utilities](./UTILITIES.md)             | Utility functions and helper classes                      |
+| [Gutenberg Integration](./GUTENBERG.md) | WordPress block development guide                         |
+| [Testing](./TESTING.md)                 | Testing with Cypress and Storybook                        |
+| [Migration Plan](./MIGRATION.md)        | Tailwind to SCSS migration roadmap                        |
+| [Contributing](./CONTRIBUTING.md)       | Contribution guidelines and standards                     |
 
 ## Overview
 
@@ -33,15 +33,15 @@ RDS is a production-ready, TypeScript-first React component library built with m
 
 ### Tech Stack
 
-| Category | Technology |
-|----------|------------|
-| Framework | React 19, TypeScript 5.9 |
-| Build | Vite 6.3, Rollup |
-| Styling | Tailwind CSS 3.4 (migrating to SCSS) |
-| Forms | Formik 2.4, Yup 1.7 |
-| Testing | Cypress 15.8, Storybook 8.6 |
-| Linting | ESLint 9, Prettier 3.7 |
-| Git Hooks | Husky 9, Commitlint |
+| Category  | Technology                           |
+| --------- | ------------------------------------ |
+| Framework | React 19, TypeScript 5.9             |
+| Build     | Vite 6.3, Rollup                     |
+| Styling   | Tailwind CSS 3.4 (migrating to SCSS) |
+| Forms     | Formik 2.4, Yup 1.7                  |
+| Testing   | Cypress 15.8, Storybook 8.6          |
+| Linting   | ESLint 9, Prettier 3.7               |
+| Git Hooks | Husky 9, Commitlint                  |
 
 ## Installation
 
@@ -78,9 +78,9 @@ The library provides multiple export formats:
 
 ```json
 {
-  "main": "dist/rds.umd.js",      // CommonJS/UMD
-  "module": "dist/rds.es.js",     // ES Modules
-  "types": "dist/main.d.ts"       // TypeScript definitions
+  "main": "dist/rds.umd.js", // CommonJS/UMD
+  "module": "dist/rds.es.js", // ES Modules
+  "types": "dist/main.d.ts" // TypeScript definitions
 }
 ```
 
@@ -107,11 +107,13 @@ npm run prettier
 ## Project Goals
 
 ### Current Focus
+
 1. Document existing components and patterns
 2. Identify inconsistencies and areas for improvement
 3. Improve Gutenberg block integration
 
 ### Future Plans
+
 1. Migrate from Tailwind CSS to SCSS modules
 2. Improve bundle size and tree-shaking
 3. Add more comprehensive testing
diff --git a/docs/STYLING.md b/docs/STYLING.md
index 6120c7926..0c8f5ff36 100644
--- a/docs/STYLING.md
+++ b/docs/STYLING.md
@@ -27,17 +27,17 @@ RDS currently uses Tailwind CSS with a custom theme preset (`rds-tailwind-theme`
 
 ### Current Stack
 
-| Package | Version | Purpose |
-|---------|---------|---------|
-| `tailwindcss` | 3.4.17 | Utility CSS framework |
-| `rds-tailwind-theme` | 0.9.2 | Carleton custom theme |
-| `@tailwindcss/forms` | - | Form element styling |
-| `@tailwindcss/typography` | - | Prose/article styling |
-| `@tailwindcss/aspect-ratio` | - | Aspect ratio utilities |
-| `@tailwindcss/container-queries` | - | Container query support |
-| `postcss` | - | CSS processing |
-| `autoprefixer` | - | Browser prefixes |
-| `postcss-nesting` | - | CSS nesting support |
+| Package                          | Version | Purpose                 |
+| -------------------------------- | ------- | ----------------------- |
+| `tailwindcss`                    | 3.4.17  | Utility CSS framework   |
+| `rds-tailwind-theme`             | 0.9.2   | Carleton custom theme   |
+| `@tailwindcss/forms`             | -       | Form element styling    |
+| `@tailwindcss/typography`        | -       | Prose/article styling   |
+| `@tailwindcss/aspect-ratio`      | -       | Aspect ratio utilities  |
+| `@tailwindcss/container-queries` | -       | Container query support |
+| `postcss`                        | -       | CSS processing          |
+| `autoprefixer`                   | -       | Browser prefixes        |
+| `postcss-nesting`                | -       | CSS nesting support     |
 
 ---
 
@@ -101,8 +101,8 @@ The `rds-tailwind-theme` package provides Carleton University's brand design tok
 
 ```css
 /* Primary */
---cu-red: #bf112b;          /* Carleton Red */
---cu-black: #262626;        /* Near black */
+--cu-red: #bf112b; /* Carleton Red */
+--cu-black: #262626; /* Near black */
 --cu-white: #ffffff;
 
 /* Grays */
@@ -133,15 +133,15 @@ The `rds-tailwind-theme` package provides Carleton University's brand design tok
 --font-mono: 'Fira Code', monospace;
 
 /* Font sizes (rem) */
---text-xs: 0.75rem;    /* 12px */
---text-sm: 0.875rem;   /* 14px */
---text-base: 1rem;     /* 16px */
---text-lg: 1.125rem;   /* 18px */
---text-xl: 1.25rem;    /* 20px */
---text-2xl: 1.5rem;    /* 24px */
---text-3xl: 1.875rem;  /* 30px */
---text-4xl: 2.25rem;   /* 36px */
---text-5xl: 3rem;      /* 48px */
+--text-xs: 0.75rem; /* 12px */
+--text-sm: 0.875rem; /* 14px */
+--text-base: 1rem; /* 16px */
+--text-lg: 1.125rem; /* 18px */
+--text-xl: 1.25rem; /* 20px */
+--text-2xl: 1.5rem; /* 24px */
+--text-3xl: 1.875rem; /* 30px */
+--text-4xl: 2.25rem; /* 36px */
+--text-5xl: 3rem; /* 48px */
 ```
 
 ### Spacing
@@ -151,18 +151,18 @@ Based on 4px base unit:
 ```css
 /* Spacing scale */
 --spacing-0: 0;
---spacing-1: 0.25rem;  /* 4px */
---spacing-2: 0.5rem;   /* 8px */
---spacing-3: 0.75rem;  /* 12px */
---spacing-4: 1rem;     /* 16px */
---spacing-5: 1.25rem;  /* 20px */
---spacing-6: 1.5rem;   /* 24px */
---spacing-8: 2rem;     /* 32px */
---spacing-10: 2.5rem;  /* 40px */
---spacing-12: 3rem;    /* 48px */
---spacing-16: 4rem;    /* 64px */
---spacing-20: 5rem;    /* 80px */
---spacing-24: 6rem;    /* 96px */
+--spacing-1: 0.25rem; /* 4px */
+--spacing-2: 0.5rem; /* 8px */
+--spacing-3: 0.75rem; /* 12px */
+--spacing-4: 1rem; /* 16px */
+--spacing-5: 1.25rem; /* 20px */
+--spacing-6: 1.5rem; /* 24px */
+--spacing-8: 2rem; /* 32px */
+--spacing-10: 2.5rem; /* 40px */
+--spacing-12: 3rem; /* 48px */
+--spacing-16: 4rem; /* 64px */
+--spacing-20: 5rem; /* 80px */
+--spacing-24: 6rem; /* 96px */
 ```
 
 ### Breakpoints
@@ -280,7 +280,7 @@ export function Button({ color, isSmall, children }) {
       'bg-cu-red text-white hover:bg-cu-red-dark': color === 'red',
       'bg-gray-200 text-gray-800 hover:bg-gray-300': color === 'grey',
       'px-3 py-1.5 text-xs': isSmall,
-    }
+    },
   )
 
   return <button className={classes}>{children}</button>
@@ -294,11 +294,7 @@ Custom CSS classes using Tailwind's @apply:
 ```tsx
 // Button.tsx
 export function Button({ color, isSmall, children }) {
-  const classes = clsx(
-    'cu-button',
-    `cu-button--${color}`,
-    { 'cu-button--small': isSmall }
-  )
+  const classes = clsx('cu-button', `cu-button--${color}`, { 'cu-button--small': isSmall })
 
   return <button className={classes}>{children}</button>
 }
@@ -334,11 +330,7 @@ export const buttonColorClasses = {
 import { buttonColorClasses } from '../../utils/propClasses'
 
 export function Button({ color = 'red', children }) {
-  return (
-    <button className={clsx('cu-button', buttonColorClasses[color])}>
-      {children}
-    </button>
-  )
+  return <button className={clsx('cu-button', buttonColorClasses[color])}>{children}</button>
 }
 ```
 
@@ -353,12 +345,12 @@ From `lib/utils/propClasses.tsx`:
 ```typescript
 // Max width constraints
 export const maxWidthClasses = {
-  narrow: 'max-w-2xl',    // 672px
-  small: 'max-w-3xl',     // 768px
-  base: 'max-w-4xl',      // 896px
-  large: 'max-w-5xl',     // 1024px
-  full: 'max-w-full',     // 100%
-  '7xl': 'max-w-7xl',     // 1280px
+  narrow: 'max-w-2xl', // 672px
+  small: 'max-w-3xl', // 768px
+  base: 'max-w-4xl', // 896px
+  large: 'max-w-5xl', // 1024px
+  full: 'max-w-full', // 100%
+  '7xl': 'max-w-7xl', // 1280px
 }
 
 // Grid columns
@@ -382,10 +374,10 @@ export const gridGapClasses = {
 
 // Aspect ratios
 export const aspectRatioClasses = {
-  square: 'aspect-square',      // 1:1
-  landscape: 'aspect-video',    // 16:9
-  portrait: 'aspect-[3/4]',     // 3:4
-  wide: 'aspect-[21/9]',        // 21:9
+  square: 'aspect-square', // 1:1
+  landscape: 'aspect-video', // 16:9
+  portrait: 'aspect-[3/4]', // 3:4
+  wide: 'aspect-[21/9]', // 21:9
 }
 
 // Text colors
@@ -418,9 +410,7 @@ import { utils } from '@carletonuniversity/rds'
 function MyComponent({ maxWidth, columns }) {
   return (
     <div className={utils.maxWidthClasses[maxWidth]}>
-      <div className={`grid ${utils.gridColumnClasses[columns]}`}>
-        {/* content */}
-      </div>
+      <div className={`grid ${utils.gridColumnClasses[columns]}`}>{/* content */}</div>
     </div>
   )
 }
@@ -449,11 +439,7 @@ document.documentElement.classList.toggle('dark')
 
 // Component with dark mode
 function Card({ children }) {
-  return (
-    <div className="bg-white dark:bg-gray-800 text-gray-900 dark:text-white">
-      {children}
-    </div>
-  )
+  return <div className="bg-white dark:bg-gray-800 text-gray-900 dark:text-white">{children}</div>
 }
 ```
 
@@ -488,20 +474,22 @@ Components use mobile-first responsive design:
 ```tsx
 // Stacks on mobile, grid on larger screens
 <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
-  {items.map(item => <Card key={item.id} {...item} />)}
+  {items.map((item) => (
+    <Card key={item.id} {...item} />
+  ))}
 </div>
 ```
 
 ### Breakpoint Usage
 
-| Prefix | Min Width | Use Case |
-|--------|-----------|----------|
-| (none) | 0px | Mobile (default) |
-| `sm:` | 640px | Large phones |
-| `md:` | 768px | Tablets |
-| `lg:` | 1024px | Laptops |
-| `xl:` | 1280px | Desktops |
-| `2xl:` | 1536px | Large screens |
+| Prefix | Min Width | Use Case         |
+| ------ | --------- | ---------------- |
+| (none) | 0px       | Mobile (default) |
+| `sm:`  | 640px     | Large phones     |
+| `md:`  | 768px     | Tablets          |
+| `lg:`  | 1024px    | Laptops          |
+| `xl:`  | 1280px    | Desktops         |
+| `2xl:` | 1536px    | Large screens    |
 
 ### Common Patterns
 
@@ -548,6 +536,7 @@ Components use mobile-first responsive design:
 **Impact:** Longer initial page loads, especially on slower connections.
 
 **Mitigation:**
+
 - PurgeCSS configured but may miss dynamic classes
 - Some classes built from variables can't be purged
 
@@ -556,14 +545,18 @@ Components use mobile-first responsive design:
 **Problem:** Tailwind classes can conflict with WordPress/Gutenberg styles.
 
 **Example:**
+
 ```css
 /* Tailwind reset */
-button { background: transparent; }
+button {
+  background: transparent;
+}
 
 /* WordPress expects default styling */
 ```
 
 **Mitigation:**
+
 - Use `important: true` in Tailwind config (not recommended)
 - Prefix all Tailwind classes with `tw-` (requires config change)
 - Use scoped CSS classes instead
@@ -579,6 +572,7 @@ return <div className={`bg-${color}-500`} />
 ```
 
 **Mitigation:**
+
 - Use complete class names in safelist
 - Map values to full class strings
 
@@ -587,6 +581,7 @@ return <div className={`bg-${color}-500`} />
 **Problem:** Overriding theme values requires deep Tailwind knowledge.
 
 **Mitigation:**
+
 - Document theme extension patterns
 - Consider CSS custom properties for easier overrides
 
diff --git a/docs/TESTING.md b/docs/TESTING.md
index 96e23d578..54ab766d8 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -27,12 +27,12 @@ RDS uses a multi-layered testing approach:
 
 ### Coverage Goals
 
-| Category | Coverage Target |
-|----------|-----------------|
-| Critical components | 90%+ |
-| Form components | 85%+ |
-| Layout components | 70%+ |
-| Utility functions | 95%+ |
+| Category            | Coverage Target |
+| ------------------- | --------------- |
+| Critical components | 90%+            |
+| Form components     | 85%+            |
+| Layout components   | 70%+            |
+| Utility functions   | 95%+            |
 
 ---
 
@@ -55,10 +55,10 @@ RDS uses a multi-layered testing approach:
 
 ### Configuration Files
 
-| File | Purpose |
-|------|---------|
-| `cypress.config.ts` | Cypress configuration |
-| `.storybook/main.ts` | Storybook configuration |
+| File                    | Purpose                    |
+| ----------------------- | -------------------------- |
+| `cypress.config.ts`     | Cypress configuration      |
+| `.storybook/main.ts`    | Storybook configuration    |
 | `.storybook/preview.ts` | Storybook preview settings |
 
 ---
diff --git a/docs/UTILITIES.md b/docs/UTILITIES.md
index 367ca19f3..8d0de4ab7 100644
--- a/docs/UTILITIES.md
+++ b/docs/UTILITIES.md
@@ -74,11 +74,11 @@ Narrower width constraints:
 
 ```tsx
 export const smallWidthClasses = {
-  xs: 'max-w-xs',     // 320px
-  sm: 'max-w-sm',     // 384px
-  md: 'max-w-md',     // 448px
-  lg: 'max-w-lg',     // 512px
-  xl: 'max-w-xl',     // 576px
+  xs: 'max-w-xs', // 320px
+  sm: 'max-w-sm', // 384px
+  md: 'max-w-md', // 448px
+  lg: 'max-w-lg', // 512px
+  xl: 'max-w-xl', // 576px
   '2xl': 'max-w-2xl', // 672px
 }
 ```
@@ -112,10 +112,10 @@ Spacing between grid items:
 ```tsx
 export const gridGapClasses = {
   none: 'gap-0',
-  sm: 'gap-2',    // 8px
-  md: 'gap-4',    // 16px
-  lg: 'gap-6',    // 24px
-  xl: 'gap-8',    // 32px
+  sm: 'gap-2', // 8px
+  md: 'gap-4', // 16px
+  lg: 'gap-6', // 24px
+  xl: 'gap-8', // 32px
 }
 ```
 
@@ -418,10 +418,7 @@ export const imageUploadValidationSchema = (options = {}) => {
         const img = new Image()
         img.onload = () => {
           const valid =
-            img.width >= minWidth &&
-            img.height >= minHeight &&
-            img.width <= maxWidth &&
-            img.height <= maxHeight
+            img.width >= minWidth && img.height >= minHeight && img.width <= maxWidth && img.height <= maxHeight
           resolve(valid)
         }
         img.onerror = () => resolve(false)
@@ -452,16 +449,8 @@ Pagination logic hook:
 import { usePagination } from '@carletonuniversity/rds'
 
 function PaginatedList({ items, itemsPerPage = 10 }) {
-  const {
-    currentPage,
-    totalPages,
-    paginatedItems,
-    goToPage,
-    nextPage,
-    prevPage,
-    hasNextPage,
-    hasPrevPage,
-  } = usePagination(items, itemsPerPage)
+  const { currentPage, totalPages, paginatedItems, goToPage, nextPage, prevPage, hasNextPage, hasPrevPage } =
+    usePagination(items, itemsPerPage)
 
   return (
     <div>
@@ -505,23 +494,16 @@ Table sorting logic:
 import { useSortableTable } from '@carletonuniversity/rds'
 
 function SortableTable({ data, columns }) {
-  const { sortedData, sortConfig, requestSort, getSortDirection } =
-    useSortableTable(data)
+  const { sortedData, sortConfig, requestSort, getSortDirection } = useSortableTable(data)
 
   return (
     <table>
       <thead>
         <tr>
           {columns.map((column) => (
-            <th
-              key={column.key}
-              onClick={() => requestSort(column.key)}
-              className={getSortDirection(column.key)}
-            >
+            <th key={column.key} onClick={() => requestSort(column.key)} className={getSortDirection(column.key)}>
               {column.label}
-              {sortConfig.key === column.key && (
-                <span>{sortConfig.direction === 'asc' ? '▲' : '▼'}</span>
-              )}
+              {sortConfig.key === column.key && <span>{sortConfig.direction === 'asc' ? '▲' : '▼'}</span>}
             </th>
           ))}
         </tr>
@@ -556,37 +538,17 @@ Video banner management:
 import { useVideoBanner } from '@carletonuniversity/rds'
 
 function HeroBanner({ videoSrc, imageSrc }) {
-  const {
-    isVideoLoaded,
-    isVideoPlaying,
-    videoRef,
-    playVideo,
-    pauseVideo,
-    toggleVideo,
-  } = useVideoBanner()
+  const { isVideoLoaded, isVideoPlaying, videoRef, playVideo, pauseVideo, toggleVideo } = useVideoBanner()
 
   return (
     <div className="relative">
       {/* Fallback image */}
-      <img
-        src={imageSrc}
-        className={isVideoLoaded ? 'hidden' : 'block'}
-        alt=""
-      />
+      <img src={imageSrc} className={isVideoLoaded ? 'hidden' : 'block'} alt="" />
 
       {/* Video */}
-      <video
-        ref={videoRef}
-        src={videoSrc}
-        className={isVideoLoaded ? 'block' : 'hidden'}
-        muted
-        loop
-        playsInline
-      />
-
-      <button onClick={toggleVideo}>
-        {isVideoPlaying ? 'Pause' : 'Play'}
-      </button>
+      <video ref={videoRef} src={videoSrc} className={isVideoLoaded ? 'block' : 'hidden'} muted loop playsInline />
+
+      <button onClick={toggleVideo}>{isVideoPlaying ? 'Pause' : 'Play'}</button>
     </div>
   )
 }
@@ -742,22 +704,14 @@ import Link from 'next/link'
 
 // Use Next.js Link component
 function App({ children }) {
-  return (
-    <LinkProvider value={Link}>
-      {children}
-    </LinkProvider>
-  )
+  return <LinkProvider value={Link}>{children}</LinkProvider>
 }
 
 // Use React Router Link
 import { Link as RouterLink } from 'react-router-dom'
 
 function App({ children }) {
-  return (
-    <LinkProvider value={RouterLink}>
-      {children}
-    </LinkProvider>
-  )
+  return <LinkProvider value={RouterLink}>{children}</LinkProvider>
 }
 ```
 
@@ -798,10 +752,7 @@ function CardGrid({ cards, columns = '3', gap = 'lg' }) {
               <img src={card.image} alt={card.title} />
             </Card.Figure>
             <Card.Body>
-              <Card.Header
-                title={card.title}
-                className={utils.headerSizeClasses.sm}
-              />
+              <Card.Header title={card.title} className={utils.headerSizeClasses.sm} />
               <Card.Excerpt text={card.excerpt} />
             </Card.Body>
           </Card>
@@ -830,11 +781,7 @@ const schema = Yup.object({
 
 function ApplicationForm() {
   return (
-    <Form
-      initialValues={{ name: '', document: null }}
-      validationSchema={schema}
-      onSubmit={handleSubmit}
-    >
+    <Form initialValues={{ name: '', document: null }} validationSchema={schema} onSubmit={handleSubmit}>
       <Form.Field name="name" label="Name" required>
         <Input name="name" />
       </Form.Field>
@@ -855,12 +802,7 @@ function ApplicationForm() {
 import { usePagination, Listing, Pagination } from '@carletonuniversity/rds'
 
 function NewsList({ news }) {
-  const {
-    currentPage,
-    totalPages,
-    paginatedItems,
-    goToPage,
-  } = usePagination(news, 10)
+  const { currentPage, totalPages, paginatedItems, goToPage } = usePagination(news, 10)
 
   return (
     <div>
@@ -871,11 +813,7 @@ function NewsList({ news }) {
         </Listing>
       ))}
 
-      <Pagination
-        currentPage={currentPage}
-        totalPages={totalPages}
-        onPageChange={goToPage}
-      />
+      <Pagination currentPage={currentPage} totalPages={totalPages} onPageChange={goToPage} />
     </div>
   )
 }

From 7988ce6a1fe5c738845dc02aec984766e24084fe Mon Sep 17 00:00:00 2001
From: Troy Chaplin <troy.chaplin@gmail.com>
Date: Fri, 23 Jan 2026 11:01:38 -0500
Subject: [PATCH 3/3] change: docs

---
 docs/COMPONENTS.md | 23 -----------------------
 docs/FORMS.md      |  5 -----
 docs/LAYOUTS.md    |  7 -------
 3 files changed, 35 deletions(-)

diff --git a/docs/COMPONENTS.md b/docs/COMPONENTS.md
index a20ae2e75..90264d85e 100644
--- a/docs/COMPONENTS.md
+++ b/docs/COMPONENTS.md
@@ -217,7 +217,6 @@ List item component with similar structure to Card.
 
 ```tsx
 import { Listing } from '@carletonuniversity/rds'
-
 ;<Listing>
   <Listing.Figure>
     <img src="/thumb.jpg" alt="" />
@@ -252,7 +251,6 @@ Descriptive text blocks, often used for definition lists.
 
 ```tsx
 import { Description } from '@carletonuniversity/rds'
-
 ;<Description title="Term" content="Definition or explanation of the term." />
 ```
 
@@ -264,7 +262,6 @@ Expandable/collapsible content section.
 
 ```tsx
 import { Details } from '@carletonuniversity/rds'
-
 ;<Details summary="Click to expand">
   <p>Hidden content revealed when expanded.</p>
 </Details>
@@ -331,7 +328,6 @@ Data table with sorting support.
 
 ```tsx
 import { Table } from '@carletonuniversity/rds'
-
 ;<Table>
   <Table.Header>
     <Table.Row>
@@ -358,7 +354,6 @@ Page navigation component.
 
 ```tsx
 import { Pagination } from '@carletonuniversity/rds'
-
 ;<Pagination currentPage={1} totalPages={10} onPageChange={(page) => setCurrentPage(page)} />
 ```
 
@@ -370,7 +365,6 @@ Date selection calendar.
 
 ```tsx
 import { Calendar } from '@carletonuniversity/rds'
-
 ;<Calendar selectedDate={selectedDate} onDateSelect={(date) => setSelectedDate(date)} />
 ```
 
@@ -384,7 +378,6 @@ Full-screen hero banner with video/image support.
 
 ```tsx
 import { Splash } from '@carletonuniversity/rds'
-
 ;<Splash>
   <Splash.Background>
     <Splash.Video src="/hero-video.mp4" />
@@ -438,7 +431,6 @@ Full-width image section.
 
 ```tsx
 import { WideImage } from '@carletonuniversity/rds'
-
 ;<WideImage src="/wide-image.jpg" alt="Description" caption="Image caption" />
 ```
 
@@ -450,7 +442,6 @@ Page header with title and metadata.
 
 ```tsx
 import { PageHeader } from '@carletonuniversity/rds'
-
 ;<PageHeader
   title="Page Title"
   subtitle="Page subtitle"
@@ -471,7 +462,6 @@ Minimal footer with copyright.
 
 ```tsx
 import { FooterBasic } from '@carletonuniversity/rds'
-
 ;<FooterBasic copyrightYear={2024} organization="Carleton University" />
 ```
 
@@ -481,7 +471,6 @@ Standard footer with navigation links.
 
 ```tsx
 import { FooterStandard } from '@carletonuniversity/rds'
-
 ;<FooterStandard links={footerLinks} socialLinks={socialLinks} />
 ```
 
@@ -507,7 +496,6 @@ Complex navigation component with responsive support.
 
 ```tsx
 import { Nav } from '@carletonuniversity/rds'
-
 ;<Nav>
   <Nav.Top>
     <Nav.Logo src="/logo.svg" alt="Logo" />
@@ -575,7 +563,6 @@ Styled blockquotes.
 
 ```tsx
 import { Quote } from '@carletonuniversity/rds'
-
 ;<Quote text="This is a quoted statement." author="John Doe" citation="Source Publication" />
 ```
 
@@ -587,7 +574,6 @@ Testimonial/review blocks.
 
 ```tsx
 import { Testimonial } from '@carletonuniversity/rds'
-
 ;<Testimonial quote="Great experience working with RDS!" author="Jane Smith" role="Developer" image="/jane.jpg" />
 ```
 
@@ -599,7 +585,6 @@ Event timeline visualization.
 
 ```tsx
 import { Timeline } from '@carletonuniversity/rds'
-
 ;<Timeline
   items={[
     { date: '2024-01', title: 'Project Started', description: '...' },
@@ -617,7 +602,6 @@ Filter sidebar for search results.
 
 ```tsx
 import { FilterPanel } from '@carletonuniversity/rds'
-
 ;<FilterPanel
   filters={[
     {
@@ -643,7 +627,6 @@ Notification toasts.
 
 ```tsx
 import { Toast } from '@carletonuniversity/rds'
-
 ;<Toast
   type="success"
   message="Action completed successfully!"
@@ -660,7 +643,6 @@ Highlighted callout boxes.
 
 ```tsx
 import { CallOut } from '@carletonuniversity/rds'
-
 ;<CallOut type="info" title="Note">
   Important information for the user.
 </CallOut>
@@ -689,7 +671,6 @@ Images with captions.
 
 ```tsx
 import { Figure } from '@carletonuniversity/rds'
-
 ;<Figure src="/image.jpg" alt="Image description" caption="Figure 1: Image caption" />
 ```
 
@@ -721,7 +702,6 @@ Grid layout for multiple images.
 
 ```tsx
 import { ImageGrid } from '@carletonuniversity/rds'
-
 ;<ImageGrid
   images={[
     { src: '/img1.jpg', alt: 'Image 1' },
@@ -740,7 +720,6 @@ Image carousel/slider.
 
 ```tsx
 import { ImageSlider } from '@carletonuniversity/rds'
-
 ;<ImageSlider
   images={[
     { src: '/slide1.jpg', alt: 'Slide 1' },
@@ -792,7 +771,6 @@ import {
 
 ```tsx
 import { Forbidden403 } from '@carletonuniversity/rds'
-
 ;<Forbidden403 message="You don't have permission to access this page." homeLink="/" />
 ```
 
@@ -802,7 +780,6 @@ import { Forbidden403 } from '@carletonuniversity/rds'
 
 ```tsx
 import { NotFound404 } from '@carletonuniversity/rds'
-
 ;<NotFound404 message="The page you're looking for doesn't exist." homeLink="/" searchLink="/search" />
 ```
 
diff --git a/docs/FORMS.md b/docs/FORMS.md
index 5e64f4708..a812a510b 100644
--- a/docs/FORMS.md
+++ b/docs/FORMS.md
@@ -178,7 +178,6 @@ Dynamic field arrays for repeatable fields.
 
 ```tsx
 import { FieldArray } from 'formik'
-
 ;<FieldArray name="addresses">
   {({ push, remove }) => (
     <Form.FieldArrayContainer>
@@ -246,7 +245,6 @@ Multi-line text input.
 
 ```tsx
 import { TextArea } from '@carletonuniversity/rds'
-
 ;<TextArea name="description" rows={5} placeholder="Enter description..." />
 ```
 
@@ -350,7 +348,6 @@ Radio button for single selection from options.
 
 ```tsx
 import { Radio } from '@carletonuniversity/rds'
-
 ;<Form.FieldSet legend="Preferred Contact Method">
   <Radio name="contactMethod" value="email" label="Email" />
   <Radio name="contactMethod" value="phone" label="Phone" />
@@ -482,7 +479,6 @@ Google Places autocomplete for address input.
 
 ```tsx
 import { PlacesAutoComplete } from '@carletonuniversity/rds'
-
 ;<PlacesAutoComplete
   name="address"
   placeholder="Enter address"
@@ -528,7 +524,6 @@ Helper text display for additional field information.
 
 ```tsx
 import { HelperText } from '@carletonuniversity/rds'
-
 ;<Form.Field name="password" label="Password">
   <Input name="password" type="password" />
   <HelperText>Must be at least 8 characters with one uppercase letter</HelperText>
diff --git a/docs/LAYOUTS.md b/docs/LAYOUTS.md
index d084e6a2b..1ca98e51b 100644
--- a/docs/LAYOUTS.md
+++ b/docs/LAYOUTS.md
@@ -53,7 +53,6 @@ Wrapper for article content, providing proper semantic HTML and typography style
 
 ```tsx
 import { Article } from '@carletonuniversity/rds'
-
 ;<Article>
   <h1>Article Title</h1>
   <p>Article content with proper typography styling...</p>
@@ -81,7 +80,6 @@ Sidebar or complementary content area.
 
 ```tsx
 import { Aside } from '@carletonuniversity/rds'
-
 ;<div className="flex">
   <Main>
     <p>Main content</p>
@@ -123,7 +121,6 @@ Page body wrapper that provides base styling and layout constraints.
 
 ```tsx
 import { Body } from '@carletonuniversity/rds'
-
 ;<Body>
   <Nav>...</Nav>
   <Main>...</Main>
@@ -209,7 +206,6 @@ Floating content box that can be positioned within text content.
 
 ```tsx
 import { FloatBox } from '@carletonuniversity/rds'
-
 ;<Article>
   <p>Main article text...</p>
 
@@ -245,7 +241,6 @@ Full-screen image background with overlay content.
 
 ```tsx
 import { ImageCover } from '@carletonuniversity/rds'
-
 ;<ImageCover src="/hero-image.jpg" alt="Hero background" overlay="dark">
   <h1>Hero Title</h1>
   <p>Hero description text</p>
@@ -286,7 +281,6 @@ Main content area wrapper with semantic `<main>` element.
 
 ```tsx
 import { Main } from '@carletonuniversity/rds'
-
 ;<Body>
   <Nav>...</Nav>
   <Main>
@@ -416,7 +410,6 @@ Wave decoration background layout for visual interest.
 
 ```tsx
 import { WideWave } from '@carletonuniversity/rds'
-
 ;<WideWave color="red" position="top">
   <Section>
     <h2>Featured Content</h2>