diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 71f8a264..8e95a515 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - alpha
 
 permissions:
   contents: write # to be able to publish a GitHub release
diff --git a/.releaserc.json b/.releaserc.json
index 0acfe82b..fcd57804 100644
--- a/.releaserc.json
+++ b/.releaserc.json
@@ -1,5 +1,5 @@
 {
-  "branches": ["main"],
+  "branches": ["main", { "name": "alpha", "prerelease": true }],
   "plugins": [
     "@semantic-release/commit-analyzer",
     "@semantic-release/release-notes-generator",
diff --git a/.storybook/fonts.css b/.storybook/fonts.css
new file mode 100644
index 00000000..8cd6127a
--- /dev/null
+++ b/.storybook/fonts.css
@@ -0,0 +1,47 @@
+/*
+ * Custom Fonts for Storybook
+ * Fonts are loaded from .storybook/public/fonts/
+ */
+
+/* Diatype Font Family */
+@font-face {
+  font-family: "Diatype";
+  src: url("/fonts/diatype/ABCDiatype-Regular.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Diatype";
+  src: url("/fonts/diatype/ABCDiatype-Light.woff2") format("woff2");
+  font-weight: 300;
+  font-style: normal;
+  font-display: block;
+}
+
+/* Diatype Mono Font Family */
+@font-face {
+  font-family: "Diatype Mono";
+  src: url("/fonts/diatype-mono/ABCDiatypeMono-Regular.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Diatype Mono";
+  src: url("/fonts/diatype-mono/ABCDiatypeMono-Light.woff2") format("woff2");
+  font-weight: 300;
+  font-style: normal;
+  font-display: block;
+}
+
+/* Tobias Font Family */
+@font-face {
+  font-family: "Tobias";
+  src: url("/fonts/tobias/Tobias-Thin.woff2") format("woff2");
+  font-weight: 100;
+  font-style: normal;
+  font-display: block;
+}
\ No newline at end of file
diff --git a/.storybook/main.ts b/.storybook/main.ts
index ce35df8d..755380f4 100644
--- a/.storybook/main.ts
+++ b/.storybook/main.ts
@@ -13,6 +13,7 @@ const config: StorybookConfig = {
     name: '@storybook/react-vite',
     options: {},
   },
+  staticDirs: ['./public'],
   core: {
     builder: '@storybook/builder-vite',
   },
diff --git a/.storybook/manager.ts b/.storybook/manager.ts
index eba56228..f9e96291 100644
--- a/.storybook/manager.ts
+++ b/.storybook/manager.ts
@@ -1,4 +1,3 @@
-import { addons } from '@storybook/manager-api'
 import { create } from '@storybook/theming'
 
 // Define the colors and styles for the theme
@@ -36,6 +35,6 @@ export const speakeasyTheme = create({
   brandUrl: 'https://speakeasy.com',
 })
 
-addons.setConfig({
-  theme: speakeasyTheme,
-})
+// addons.setConfig({
+//   theme: speakeasyTheme,
+// })
diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
index 6fe202ca..5df5983e 100644
--- a/.storybook/preview.tsx
+++ b/.storybook/preview.tsx
@@ -1,5 +1,6 @@
 import type { Preview } from '@storybook/react'
 import '../src/global.css'
+import './fonts.css'
 import React from 'react'
 import { allModes } from './modes'
 import { withThemeByClassName } from '@storybook/addon-themes'
diff --git a/.storybook/public/fonts/diatype-mono/ABCDiatypeMono-Light.woff2 b/.storybook/public/fonts/diatype-mono/ABCDiatypeMono-Light.woff2
new file mode 100644
index 00000000..7dc0e8f7
Binary files /dev/null and b/.storybook/public/fonts/diatype-mono/ABCDiatypeMono-Light.woff2 differ
diff --git a/.storybook/public/fonts/diatype-mono/ABCDiatypeMono-Regular.woff2 b/.storybook/public/fonts/diatype-mono/ABCDiatypeMono-Regular.woff2
new file mode 100644
index 00000000..2c9c5e8e
Binary files /dev/null and b/.storybook/public/fonts/diatype-mono/ABCDiatypeMono-Regular.woff2 differ
diff --git a/.storybook/public/fonts/diatype/ABCDiatype-Light.woff2 b/.storybook/public/fonts/diatype/ABCDiatype-Light.woff2
new file mode 100644
index 00000000..aa6bc4ad
Binary files /dev/null and b/.storybook/public/fonts/diatype/ABCDiatype-Light.woff2 differ
diff --git a/.storybook/public/fonts/diatype/ABCDiatype-Regular.woff2 b/.storybook/public/fonts/diatype/ABCDiatype-Regular.woff2
new file mode 100644
index 00000000..891068ff
Binary files /dev/null and b/.storybook/public/fonts/diatype/ABCDiatype-Regular.woff2 differ
diff --git a/.storybook/public/fonts/tobias/Tobias-Thin.woff2 b/.storybook/public/fonts/tobias/Tobias-Thin.woff2
new file mode 100644
index 00000000..ac6e7650
Binary files /dev/null and b/.storybook/public/fonts/tobias/Tobias-Thin.woff2 differ
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..ad375e7f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,1375 @@
+# Moonshine CSS Architecture - Technical Guide
+
+This document provides technical details about Moonshine's CSS architecture for AI assistants and developers working on the design system.
+
+## Overview
+
+Moonshine is a utility-first design system built on Tailwind CSS v4 that enforces design consistency through constrained, semantic utilities rather than arbitrary values.
+
+## File Structure
+
+```
+src/
+├── global.css      # Entry point and orchestration
+├── base.css        # Design tokens and primitives
+└── utilities.css   # Public utility classes
+```
+
+## Architecture Details
+
+### base.css - Design Tokens
+
+This file contains four main sections:
+
+1. **Primitive Tokens** - Raw design values (should not be used directly)
+   ```css
+   --color-neutral-200: hsl(0, 0%, 92%);
+   --font-diatype: 'Diatype', -apple-system, ...;
+   ```
+
+2. **Semantic/Utility Tokens** - Theme-aware variables that map to utilities
+   ```css
+   /* Light mode */
+   --text-warning: var(--color-feedback-orange-700);
+   --bg-warning: var(--color-feedback-orange-100);
+   
+   /* Automatically switches in dark mode */
+   ```
+
+3. **Component Tokens** - Higher-level semantic tokens
+   ```css
+   --radius: 0.625rem;
+   --shadow: hsl(0 0% 50%);
+   ```
+
+4. **Deprecated Tokens** - Shadcn compatibility (to be removed)
+
+### utilities.css - Public API
+
+Contains the utility classes that developers should use:
+
+- **Typography utilities**: `text-heading-xl`, `text-body-sm` (enforced combinations)
+- **Semantic colors**: `bg-warning`, `text-error`, `border-success`
+- **Surface utilities**: `bg-surface-primary`, `bg-surface-secondary`
+- **Component utilities**: `container`, `bg-mask`
+
+### global.css - Configuration
+
+Handles Tailwind configuration and imports:
+
+- Imports core dependencies in correct order
+- Defines custom variants (`dark`, `interact`)
+- Configures responsive utility generation via `@source`
+- Maps fonts to Tailwind's theme
+
+## Key Design Decisions
+
+### Why Custom Typography Utilities?
+
+Instead of allowing arbitrary combinations like:
+```css
+/* ❌ Bad - leads to inconsistency */
+.heading {
+  @apply text-[1.813rem] leading-[1.5] tracking-[0.0015em] font-light;
+}
+```
+
+We provide semantic utilities:
+```css
+/* ✅ Good - enforces design system */
+.heading {
+  @apply text-heading-lg;
+}
+```
+
+### Theme-Aware Semantic Tokens
+
+The "utility tokens" pattern in base.css enables automatic theme switching:
+
+```css
+/* Developers use this */
+.warning-banner {
+  @apply bg-warning text-warning border-warning;
+}
+
+/* It automatically adapts to light/dark mode */
+```
+
+### Preventing Design System Escape Hatches
+
+We intentionally:
+- Don't expose raw color values as utilities
+- Provide complete typography utilities (not individual properties)
+- Use semantic naming to guide correct usage
+
+## Common Tasks
+
+### Adding a New Color Utility
+
+1. Add primitive colors to base.css if needed
+2. Create semantic tokens in base.css (both light and dark variants)
+3. Create utility classes in utilities.css that reference the tokens
+
+### Adding a New Typography Scale
+
+1. Define the complete set of properties in a single `@utility` in utilities.css
+2. Use semantic naming (e.g., `text-label-sm` not `text-13`)
+3. Ensure it works with all font families
+
+### Extending Responsive Utilities
+
+Add new `@source` declarations in global.css:
+```css
+@source inline("{,sm:,md:,lg:,xl:,2xl:}your-utility-{value1,value2}");
+```
+
+## Available Utility Classes
+
+This section is auto-generated from the CSS files. Last updated: 2025-07-16T17:53:27.862Z
+
+### Typography Utilities
+
+#### `typography-heading-xl`
+
+```css
+.typography-heading-xl {
+  font-size: 2.063rem;
+  font-weight: 300;
+  line-height: 1.375;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `typography-heading-lg`
+
+```css
+.typography-heading-lg {
+  font-size: 1.813rem;
+  font-weight: 300;
+  line-height: 1.5;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `typography-heading-md`
+
+```css
+.typography-heading-md {
+  font-size: 1.625rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `typography-heading-sm`
+
+```css
+.typography-heading-sm {
+  font-size: 1.438rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `typography-heading-xs`
+
+```css
+.typography-heading-xs {
+  font-size: 1.25rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `typography-heading-xxs`
+
+```css
+.typography-heading-xxs {
+  font-size: 1.125rem;
+  font-weight: 300;
+  line-height: 1.778;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `typography-body-lg`
+
+```css
+.typography-body-lg {
+  font-size: 1.125rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `typography-body-md`
+
+```css
+.typography-body-md {
+  font-size: 1rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `typography-body-sm`
+
+```css
+.typography-body-sm {
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `typography-body-xs`
+
+```css
+.typography-body-xs {
+  font-size: 0.75rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `text-display-2xl`
+
+```css
+.text-display-2xl {
+  font-size: 11.375rem;
+  font-weight: 100;
+  line-height: 1;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+```
+
+#### `text-display-xl`
+
+```css
+.text-display-xl {
+  font-size: 5.625rem;
+  font-weight: 100;
+  line-height: 1.1;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+```
+
+#### `text-display-lg`
+
+```css
+.text-display-lg {
+  font-size: 4.188rem;
+  font-weight: 100;
+  line-height: 1.2;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+```
+
+#### `text-display-md`
+
+```css
+.text-display-md {
+  font-size: 3.188rem;
+  font-weight: 100;
+  line-height: 1.3;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+```
+
+#### `text-display-sm`
+
+```css
+.text-display-sm {
+  font-size: 2.375rem;
+  font-weight: 100;
+  line-height: 1.375;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+```
+
+#### `text-display-xs`
+
+```css
+.text-display-xs {
+  font-size: 1.75rem;
+  font-weight: 100;
+  line-height: 1.4;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+```
+
+#### `text-heading-xl`
+
+```css
+.text-heading-xl {
+  font-size: 2.063rem;
+  font-weight: 300;
+  line-height: 1.375;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+  color: var(--text-heading-xl);
+}
+```
+
+#### `text-heading-lg`
+
+```css
+.text-heading-lg {
+  font-size: 1.813rem;
+  font-weight: 300;
+  line-height: 1.5;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+  color: var(--text-heading-lg);
+}
+```
+
+#### `text-heading-md`
+
+```css
+.text-heading-md {
+  font-size: 1.625rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+  color: var(--text-heading-md);
+}
+```
+
+#### `text-heading-sm`
+
+```css
+.text-heading-sm {
+  font-size: 1.438rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+  color: var(--text-heading-sm);
+}
+```
+
+#### `text-heading-xs`
+
+```css
+.text-heading-xs {
+  font-size: 1.25rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+  color: var(--text-heading-xs);
+}
+```
+
+#### `text-body-lg`
+
+```css
+.text-body-lg {
+  font-size: 1.125rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+  color: var(--text-default);
+}
+```
+
+#### `text-body-md`
+
+```css
+.text-body-md {
+  font-size: 1rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+  color: var(--text-default);
+}
+```
+
+#### `text-body-sm`
+
+```css
+.text-body-sm {
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+}
+```
+
+#### `text-body-xs`
+
+```css
+.text-body-xs {
+  font-size: 0.75rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+  color: var(--text-default);
+}
+```
+
+#### `text-codeline-md`
+
+```css
+.text-codeline-md {
+  font-size: 1rem;
+  font-weight: 300;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype-mono);
+  color: var(--text-default);
+}
+```
+
+#### `text-codeline-sm`
+
+```css
+.text-codeline-sm {
+  font-size: 0.875rem;
+  font-weight: 300;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype-mono);
+  color: var(--text-default);
+}
+```
+
+#### `text-codeline-xs`
+
+```css
+.text-codeline-xs {
+  font-size: 0.75rem;
+  font-weight: 300;
+  line-height: 1.7;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype-mono);
+  color: var(--text-default);
+}
+```
+
+#### `text-hightlight`
+
+```css
+.text-hightlight {
+  color: var(--text-highlight);
+}
+```
+
+#### `text-text-default`
+
+```css
+.text-text-default {
+  color: var(--text-default);
+}
+```
+
+#### `text-muted`
+
+```css
+.text-muted {
+  color: var(--text-muted);
+}
+```
+
+#### `text-placeholder`
+
+```css
+.text-placeholder {
+  color: var(--text-placeholder);
+}
+```
+
+#### `text-disabled`
+
+```css
+.text-disabled {
+  color: var(--text-disabled);
+}
+```
+
+#### `text-dark-light-highlight`
+
+```css
+.text-dark-light-highlight {
+  color: var(--text-dark-light-highlight);
+}
+```
+
+#### `text-dark-light-default`
+
+```css
+.text-dark-light-default {
+  color: var(--text-dark-light-default);
+}
+```
+
+#### `text-dark-light-muted`
+
+```css
+.text-dark-light-muted {
+  color: var(--text-dark-light-muted);
+}
+```
+
+#### `text-light-dark-highlight`
+
+```css
+.text-light-dark-highlight {
+  color: var(--text-light-dark-highlight);
+}
+```
+
+#### `text-light-dark-default`
+
+```css
+.text-light-dark-default {
+  color: var(--text-light-dark-default);
+}
+```
+
+#### `text-light-dark-muted`
+
+```css
+.text-light-dark-muted {
+  color: var(--text-light-dark-muted);
+}
+```
+
+#### `text-link-primary`
+
+```css
+.text-link-primary {
+  color: var(--text-link-primary);
+}
+```
+
+#### `text-link-secondary`
+
+```css
+.text-link-secondary {
+  color: var(--text-link-secondary);
+}
+```
+
+#### `text-link-visited`
+
+```css
+.text-link-visited {
+  color: var(--text-link-visited);
+}
+```
+
+#### `text-default-destructive`
+
+```css
+.text-default-destructive {
+  color: var(--text-default-destructive);
+}
+```
+
+#### `text-link-destructive`
+
+```css
+.text-link-destructive {
+  color: var(--text-link-destructive);
+}
+```
+
+#### `text-default-information`
+
+```css
+.text-default-information {
+  color: var(--text-default-information);
+}
+```
+
+#### `text-link-information`
+
+```css
+.text-link-information {
+  color: var(--text-link-information);
+}
+```
+
+#### `text-default-success`
+
+```css
+.text-default-success {
+  color: var(--text-default-success);
+}
+```
+
+#### `text-link-success`
+
+```css
+.text-link-success {
+  color: var(--text-link-success);
+}
+```
+
+#### `text-default-warning`
+
+```css
+.text-default-warning {
+  color: var(--text-default-warning);
+}
+```
+
+#### `text-link-warning`
+
+```css
+.text-link-warning {
+  color: var(--text-link-warning);
+}
+```
+
+#### `text-warning`
+
+```css
+.text-warning {
+  color: var(--text-warning);
+}
+```
+
+### Background Utilities
+
+#### `bg-mask`
+
+```css
+.bg-mask {
+  background-image: linear-gradient(
+    to bottom,
+    var(--background) 0%,
+    var(--color-transparent) 5%,
+    var(--color-transparent) 95%,
+    var(--background) 100%
+  );
+}
+```
+
+#### `bg-gradient-primary`
+
+```css
+.bg-gradient-primary {
+  background: var(--gradient-brand-primary);
+}
+```
+
+#### `bg-surface-primary`
+
+```css
+.bg-surface-primary {
+  background-color: var(--color-base-white);
+
+  /* dark variant */
+    background-color: var(--color-base-black);
+}
+```
+
+#### `bg-surface-secondary`
+
+```css
+.bg-surface-secondary {
+  background-color: var(--color-neutral-100);
+}
+```
+
+#### `bg-warning`
+
+```css
+.bg-warning {
+  background-color: var(--bg-warning);
+}
+```
+
+#### `bg-highlight`
+
+```css
+.bg-highlight {
+  background-color: var(--bg-highlight);
+}
+```
+
+#### `bg-active`
+
+```css
+.bg-active {
+  background-color: var(--bg-active);
+}
+```
+
+#### `bg-default`
+
+```css
+.bg-default {
+  background-color: var(--bg-default);
+}
+```
+
+#### `bg-muted`
+
+```css
+.bg-muted {
+  background-color: var(--bg-muted);
+}
+```
+
+#### `bg-inset`
+
+```css
+.bg-inset {
+  background-color: var(--bg-inset);
+}
+```
+
+#### `bg-light-dark-primary`
+
+```css
+.bg-light-dark-primary {
+  background-color: var(--bg-light-dark-primary);
+}
+```
+
+#### `bg-light-dark-secondary`
+
+```css
+.bg-light-dark-secondary {
+  background-color: var(--bg-light-dark-secondary);
+}
+```
+
+#### `bg-light-dark-tertiary`
+
+```css
+.bg-light-dark-tertiary {
+  background-color: var(--bg-light-dark-tertiary);
+}
+```
+
+#### `bg-dark-light-primary`
+
+```css
+.bg-dark-light-primary {
+  background-color: var(--bg-dark-light-primary);
+}
+```
+
+#### `bg-dark-light-secondary`
+
+```css
+.bg-dark-light-secondary {
+  background-color: var(--bg-dark-light-secondary);
+}
+```
+
+#### `bg-dark-light-tertiary`
+
+```css
+.bg-dark-light-tertiary {
+  background-color: var(--bg-dark-light-tertiary);
+}
+```
+
+#### `bg-destructive-highlight`
+
+```css
+.bg-destructive-highlight {
+  background-color: var(--bg-destructive-highlight);
+}
+```
+
+#### `bg-destructive-default`
+
+```css
+.bg-destructive-default {
+  background-color: var(--bg-destructive-default);
+}
+```
+
+#### `bg-destructive-muted`
+
+```css
+.bg-destructive-muted {
+  background-color: var(--bg-destructive-muted);
+}
+```
+
+#### `bg-destructive-softest`
+
+```css
+.bg-destructive-softest {
+  background-color: var(--bg-destructive-softest);
+}
+```
+
+#### `bg-information-highlight`
+
+```css
+.bg-information-highlight {
+  background-color: var(--bg-information-highlight);
+}
+```
+
+#### `bg-information-default`
+
+```css
+.bg-information-default {
+  background-color: var(--bg-information-default);
+}
+```
+
+#### `bg-information-muted`
+
+```css
+.bg-information-muted {
+  background-color: var(--bg-information-muted);
+}
+```
+
+#### `bg-information-softest`
+
+```css
+.bg-information-softest {
+  background-color: var(--bg-information-softest);
+}
+```
+
+#### `bg-success-highlight`
+
+```css
+.bg-success-highlight {
+  background-color: var(--bg-success-highlight);
+}
+```
+
+#### `bg-success-default`
+
+```css
+.bg-success-default {
+  background-color: var(--bg-success-default);
+}
+```
+
+#### `bg-success-muted`
+
+```css
+.bg-success-muted {
+  background-color: var(--bg-success-muted);
+}
+```
+
+#### `bg-success-softest`
+
+```css
+.bg-success-softest {
+  background-color: var(--bg-success-softest);
+}
+```
+
+#### `bg-warning-highlight`
+
+```css
+.bg-warning-highlight {
+  background-color: var(--bg-warning-highlight);
+}
+```
+
+#### `bg-warning-default`
+
+```css
+.bg-warning-default {
+  background-color: var(--bg-warning-default);
+}
+```
+
+#### `bg-warning-muted`
+
+```css
+.bg-warning-muted {
+  background-color: var(--bg-warning-muted);
+}
+```
+
+#### `bg-warning-softest`
+
+```css
+.bg-warning-softest {
+  background-color: var(--bg-warning-softest);
+}
+```
+
+### Border Utilities
+
+#### `border-gradient-primary`
+
+```css
+.border-gradient-primary {
+  border-image: var(--gradient-brand-primary) 1;
+}
+```
+
+#### `border-warning`
+
+```css
+.border-warning {
+  border-color: var(--border-warning);
+  border-width: 1px;
+  border-style: solid;
+}
+```
+
+#### `border-neutral-active`
+
+```css
+.border-neutral-active {
+  border-color: var(--border-neutral-active);
+}
+```
+
+#### `border-neutral-hover`
+
+```css
+.border-neutral-hover {
+  border-color: var(--border-neutral-hover);
+}
+```
+
+#### `border-neutral-default`
+
+```css
+.border-neutral-default {
+  border-color: var(--border-neutral-default);
+}
+```
+
+#### `border-neutral-disabled`
+
+```css
+.border-neutral-disabled {
+  border-color: var(--border-neutral-disabled);
+  opacity: 0.4;
+}
+```
+
+#### `border-neutral-softest`
+
+```css
+.border-neutral-softest {
+  border-color: var(--border-neutral-softest);
+}
+```
+
+#### `border-neutral-inset`
+
+```css
+.border-neutral-inset {
+  border-color: var(--border-neutral-inset);
+}
+```
+
+#### `border-neutral-alpha`
+
+```css
+.border-neutral-alpha {
+  border-color: var(--border-neutral-alpha);
+}
+```
+
+#### `border-destructive-highlight`
+
+```css
+.border-destructive-highlight {
+  border-color: var(--border-destructive-highlight);
+}
+```
+
+#### `border-destructive-default`
+
+```css
+.border-destructive-default {
+  border-color: var(--border-destructive-default);
+}
+```
+
+#### `border-destructive-muted`
+
+```css
+.border-destructive-muted {
+  border-color: var(--border-destructive-muted);
+}
+```
+
+#### `border-destructive-softest`
+
+```css
+.border-destructive-softest {
+  border-color: var(--border-destructive-softest);
+}
+```
+
+#### `border-information-highlight`
+
+```css
+.border-information-highlight {
+  border-color: var(--border-information-highlight);
+}
+```
+
+#### `border-information-default`
+
+```css
+.border-information-default {
+  border-color: var(--border-information-default);
+}
+```
+
+#### `border-information-muted`
+
+```css
+.border-information-muted {
+  border-color: var(--border-information-muted);
+}
+```
+
+#### `border-information-softest`
+
+```css
+.border-information-softest {
+  border-color: var(--border-information-softest);
+}
+```
+
+#### `border-success-highlight`
+
+```css
+.border-success-highlight {
+  border-color: var(--border-success-highlight);
+}
+```
+
+#### `border-success-default`
+
+```css
+.border-success-default {
+  border-color: var(--border-success-default);
+}
+```
+
+#### `border-success-muted`
+
+```css
+.border-success-muted {
+  border-color: var(--border-success-muted);
+}
+```
+
+#### `border-success-softest`
+
+```css
+.border-success-softest {
+  border-color: var(--border-success-softest);
+}
+```
+
+#### `border-focus`
+
+```css
+.border-focus {
+  border-color: var(--border-focus);
+}
+```
+
+### Other Utilities
+
+#### `container`
+
+```css
+.container {
+  padding-inline: 1rem;
+  margin-inline: auto;
+}
+```
+
+#### `underline-link-primary`
+
+```css
+.underline-link-primary {
+  color: var(--underline-link-primary);
+  text-decoration: underline;
+  text-underline-offset: 0.125rem;
+}
+```
+
+#### `underline-link-secondary`
+
+```css
+.underline-link-secondary {
+  color: var(--underline-link-secondary);
+  text-decoration: underline;
+  text-underline-offset: 0.125rem;
+}
+```
+
+#### `underline-link-visited`
+
+```css
+.underline-link-visited {
+  color: var(--underline-link-visited);
+  text-decoration: underline;
+  text-underline-offset: 0.125rem;
+}
+```
+
+#### `fill-neutral-highlight`
+
+```css
+.fill-neutral-highlight {
+  fill: var(--fill-neutral-highlight);
+}
+```
+
+#### `fill-neutral-active`
+
+```css
+.fill-neutral-active {
+  fill: var(--fill-neutral-active);
+}
+```
+
+#### `fill-neutral-default`
+
+```css
+.fill-neutral-default {
+  fill: var(--fill-neutral-default);
+}
+```
+
+#### `fill-neutral-muted`
+
+```css
+.fill-neutral-muted {
+  fill: var(--fill-neutral-muted);
+}
+```
+
+#### `fill-onColor-dark-highlight`
+
+```css
+.fill-onColor-dark-highlight {
+  fill: var(--fill-onColor-dark-highlight);
+}
+```
+
+#### `fill-onColor-dark-default`
+
+```css
+.fill-onColor-dark-default {
+  fill: var(--fill-onColor-dark-default);
+}
+```
+
+#### `fill-onColor-dark-muted`
+
+```css
+.fill-onColor-dark-muted {
+  fill: var(--fill-onColor-dark-muted);
+}
+```
+
+#### `fill-onColor-light-highlight`
+
+```css
+.fill-onColor-light-highlight {
+  fill: var(--fill-onColor-light-highlight);
+}
+```
+
+#### `fill-onColor-light-default`
+
+```css
+.fill-onColor-light-default {
+  fill: var(--fill-onColor-light-default);
+}
+```
+
+#### `fill-onColor-light-muted`
+
+```css
+.fill-onColor-light-muted {
+  fill: var(--fill-onColor-light-muted);
+}
+```
+
+#### `fill-link-primary`
+
+```css
+.fill-link-primary {
+  fill: var(--fill-link-primary);
+}
+```
+
+#### `fill-link-secondary`
+
+```css
+.fill-link-secondary {
+  fill: var(--fill-link-secondary);
+}
+```
+
+#### `fill-link-visited`
+
+```css
+.fill-link-visited {
+  fill: var(--fill-link-visited);
+}
+```
+
+#### `fill-destructive-highlight`
+
+```css
+.fill-destructive-highlight {
+  fill: var(--fill-destructive-highlight);
+}
+```
+
+#### `fill-destructive-default`
+
+```css
+.fill-destructive-default {
+  fill: var(--fill-destructive-default);
+}
+```
+
+#### `fill-destructive-muted`
+
+```css
+.fill-destructive-muted {
+  fill: var(--fill-destructive-muted);
+}
+```
+
+#### `fill-information-highlight`
+
+```css
+.fill-information-highlight {
+  fill: var(--fill-information-highlight);
+}
+```
+
+#### `fill-information-default`
+
+```css
+.fill-information-default {
+  fill: var(--fill-information-default);
+}
+```
+
+#### `fill-information-muted`
+
+```css
+.fill-information-muted {
+  fill: var(--fill-information-muted);
+}
+```
+
+#### `fill-success-highlight`
+
+```css
+.fill-success-highlight {
+  fill: var(--fill-success-highlight);
+}
+```
+
+#### `fill-success-default`
+
+```css
+.fill-success-default {
+  fill: var(--fill-success-default);
+}
+```
+
+#### `fill-success-muted`
+
+```css
+.fill-success-muted {
+  fill: var(--fill-success-muted);
+}
+```
+
+#### `fill-warning-highlight`
+
+```css
+.fill-warning-highlight {
+  fill: var(--fill-warning-highlight);
+}
+```
+
+#### `fill-warning-default`
+
+```css
+.fill-warning-default {
+  fill: var(--fill-warning-default);
+}
+```
+
+#### `fill-warning-muted`
+
+```css
+.fill-warning-muted {
+  fill: var(--fill-warning-muted);
+}
+```
+
+## Migration Notes
+
+- **Shadcn components**: Currently using deprecated tokens, will need updates
+- **Typography consolidation**: `typography-*` utilities should be removed in favor of `text-*`
+- **Raw color usage**: Audit and replace any `var(--color-neutral-*)` usage with semantic utilities
+
+## Performance Considerations
+
+- Use `@source inline` for utilities that need responsive variants
+- Avoid creating too many custom `@utility` declarations
+- Leverage Tailwind's built-in utilities where they align with the design system
+
+## Future Improvements
+
+1. **Type generation**: Generate TypeScript types for all utilities
+2. **Custom properties API**: Expose some CSS variables for component libraries
+3. **Animation utilities**: Add semantic animation classes
+4. **Layout utilities**: More sophisticated grid/flexbox patterns
diff --git a/README.md b/README.md
index c4b191fa..588a98f4 100644
--- a/README.md
+++ b/README.md
@@ -4,19 +4,40 @@
 
 Speakeasy's design system.
 
-## Installing the NPM package
+## Installation & Setup
+
+### 1. Install the package and dependencies
 
 ```bash
 pnpm add @speakeasy-api/moonshine
+pnpm add -D tw-animate-css @tailwindcss/typography
 ```
 
-Reference the CSS file in your project:
+### 2. Configure Tailwind CSS
+
+Add this to the top of your project's CSS file where you configure Tailwind:
+
+```css
+/* This must come BEFORE your Tailwind imports */
+@reference "../node_modules/@speakeasy-api/moonshine/src/global.css";
+
+/* Your Tailwind setup */
+@import 'tailwindcss';
+```
+
+**Note:** The `@reference` directive is required for Tailwind v4 to recognize Moonshine's custom utilities and make them available in your project.
+
+### 3. Import Moonshine's Compiled CSS
+
+In your main app file (or root layout):
 
 ```ts
 import '@speakeasy-api/moonshine/moonshine.css'
 ```
 
-Wrap your application in the `MoonshineConfigProvider` component, passing in the HTML element where the tailwind dark/light class is applied:
+### 4. Set up the Provider
+
+Wrap your application in the `MoonshineConfigProvider` component:
 
 ```tsx
 import { MoonshineConfigProvider } from '@speakeasy-api/moonshine'
@@ -26,14 +47,149 @@ import { MoonshineConfigProvider } from '@speakeasy-api/moonshine'
 </MoonshineConfigProvider>
 ```
 
-Then you can import components from the package:
+### 5. Configure Custom Fonts (Optional)
+
+Moonshine uses custom fonts (Diatype, Tobias). If you have licenses for these fonts, add them to your project:
+
+```css
+/* In your global CSS */
+@font-face {
+  font-family: "Diatype";
+  src: url("/fonts/diatype/ABCDiatype-Regular.woff2") format("woff2");
+  font-weight: 400;
+  font-style: normal;
+  font-display: block;
+}
+
+@font-face {
+  font-family: "Diatype";
+  src: url("/fonts/diatype/ABCDiatype-Light.woff2") format("woff2");
+  font-weight: 300;
+  font-style: normal;
+  font-display: block;
+}
+
+/* Add other font weights and Tobias font-face declarations as needed */
+```
+
+If you don't have these fonts, the design system will fall back to system fonts.
+
+### 6. Use Components and Utilities
 
 ```tsx
 import { Grid } from '@speakeasy-api/moonshine'
+
+// Use semantic utility classes
+<div className="text-heading-lg bg-surface-primary">
+  Hello Moonshine!
+</div>
 ```
 
+### TypeScript Support for Utility Classes
+
+Moonshine provides TypeScript types for all available utility classes to improve your development experience:
+
+```tsx
+import type { MoonshineClasses } from '@speakeasy-api/moonshine/types/utilities'
+
+// Use for type-safe className props
+interface MyComponentProps {
+  className?: MoonshineClasses
+}
+
+// Get autocomplete for all available utilities
+const styles: MoonshineClasses = 'text-heading-lg' // ✅ Autocompletes!
+```
+
+The types are automatically generated during the build process and include:
+- All custom utilities (`text-heading-xl`, `bg-surface-primary`, etc.)
+- All semantic color utilities (`bg-warning`, `text-success`, etc.)
+- Full IntelliSense support in your IDE
+
+💡 **Tip**: This prevents typos and helps you discover available utilities without leaving your editor!
+
 The package is built with [vite](https://vitejs.dev/), and is distributed in both [ESM](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs) formats.
 
+### Using Tailwind Merge
+
+Moonshine exports a custom wrapper for Tailwind Merge to avoid unexpected clashes between semantic class names. This version should be used in favour of using tailwind merge directly.
+
+```tsx
+import { cn } from '@speakeasy-api/moonshine'
+
+return (
+  <span
+    className={cn('text-body-md', props.muted ? 'text-muted' : 'text-default')}
+  >
+    Lorem Ipsum
+  </span>
+)
+
+```
+
+
+
+## Design System Architecture
+
+Moonshine is a utility-first design system built on top of [Tailwind CSS v4](https://tailwindcss.com/). It provides a curated set of design tokens and utilities that enforce consistency while preventing common pitfalls.
+
+### CSS Architecture
+
+Our CSS is organized into three main files:
+
+1. **`base.css`** - Primitive design tokens (colors, fonts, spacing scales)
+   - Contains raw values that should **not** be used directly in components
+   - Defines theme-aware semantic tokens that adapt to light/dark mode
+   - Houses base element styles and resets
+
+2. **`utilities.css`** - The public API of our design system
+   - Exposes carefully crafted utility classes like `text-heading-xl`, `bg-surface-primary`
+   - Enforces typography combinations to prevent arbitrary text styling
+   - Provides semantic color utilities that automatically handle theming
+
+3. **`global.css`** - Orchestration and configuration
+   - Imports Tailwind and configures plugins
+   - Defines custom variants (dark mode, interaction states)
+   - Sets up responsive utility generation
+
+### Design Principles
+
+- **Constrained, not restrictive**: We provide a curated set of utilities that make the right thing easy
+- **Semantic, not arbitrary**: Use `text-heading-lg` not `text-[29px] leading-[1.5]`
+- **Theme-aware by default**: Colors and styles automatically adapt to light/dark mode
+- **Type-safe when possible**: Utilities are designed to work with TypeScript autocomplete
+
+### Usage Guidelines
+
+✅ **Do:**
+- Use semantic utilities: `bg-warning`, `text-body`, `border-error`
+- Leverage pre-defined typography scales: `text-heading-xl`, `text-body-sm`
+- Stick to the exposed utility classes in `utilities.css`
+
+❌ **Don't:**
+- Access raw color values: `bg-[var(--color-neutral-200)]`
+- Create arbitrary combinations: `text-[1.813rem] leading-[1.5]`
+- Override the design system without discussing with the team
+
+For more technical details about the CSS architecture, see [CLAUDE.md](./CLAUDE.md).
+
+## Troubleshooting
+
+### Utilities not working
+Make sure you've added the `@reference` directive to your global CSS file. This is required for Tailwind v4 to pick up Moonshine's utility classes.
+
+### Fonts not loading
+The custom fonts (Diatype, Tobias) require licenses. If you don't have them, the system will use fallback fonts. Ensure your font files are in the correct path if you do have licenses.
+
+### Dark mode not working
+Ensure the `themeElement` prop in `MoonshineConfigProvider` points to the element where your `dark` class is applied (usually `document.documentElement`).
+
+### TypeScript types not found
+Make sure you're importing from the correct path:
+```tsx
+import type { MoonshineClasses } from '@speakeasy-api/moonshine/types/utilities'
+```
+
 ## Contributing
 
 ### Setup
diff --git a/package.json b/package.json
index 5b93c233..54729906 100644
--- a/package.json
+++ b/package.json
@@ -15,6 +15,10 @@
     "./moonshine.css": {
       "require": "./dist/style.css",
       "import": "./dist/style.css"
+    },
+    "./src/global.css": {
+      "require": "./src/global.css",
+      "import": "./src/global.css"
     }
   },
   "repository": {
@@ -22,7 +26,11 @@
     "url": "https://github.com/speakeasy-api/moonshine.git"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/global.css",
+    "src/base.css",
+    "src/utilities.css",
+    "types"
   ],
   "scripts": {
     "clean": "rimraf dist",
@@ -36,7 +44,9 @@
     "lint": "eslint",
     "lint:fix": "eslint --fix",
     "test": "vitest",
-    "visualize": "npx vite-bundle-visualizer"
+    "visualize": "npx vite-bundle-visualizer",
+    "generate:docs": "node scripts/generate-utility-docs.js",
+    "postbuild": "pnpm generate:docs"
   },
   "author": "Speakeasy",
   "license": "ISC",
diff --git a/scripts/generate-utility-docs.js b/scripts/generate-utility-docs.js
new file mode 100644
index 00000000..1d75be52
--- /dev/null
+++ b/scripts/generate-utility-docs.js
@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+const fs = require('fs')
+const path = require('path')
+const postcss = require('postcss')
+
+// Paths
+const UTILITIES_CSS = path.join(__dirname, '../src/utilities.css')
+const BASE_CSS = path.join(__dirname, '../src/base.css')
+const CLAUDE_MD = path.join(__dirname, '../CLAUDE.md')
+const TYPES_DIR = path.join(__dirname, '../types')
+const UTILITIES_TYPES = path.join(TYPES_DIR, 'utilities.d.ts')
+
+// Ensure types directory exists
+if (!fs.existsSync(TYPES_DIR)) {
+  fs.mkdirSync(TYPES_DIR)
+}
+
+// Parse CSS and extract utilities
+async function extractUtilities(cssPath) {
+  if (!fs.existsSync(cssPath)) {
+    console.error(`CSS file not found: ${cssPath}`)
+    return []
+  }
+
+  const css = fs.readFileSync(cssPath, 'utf8')
+
+  let ast
+  try {
+    ast = postcss.parse(css)
+  } catch (error) {
+    console.error(`Error parsing CSS file ${cssPath}:`, error.message)
+    return []
+  }
+
+  const utilities = []
+
+  ast.walkAtRules('utility', (rule) => {
+    const name = rule.params.trim()
+
+    // Extract the CSS properties
+    const properties = []
+    rule.walkDecls((decl) => {
+      // Skip nested rules (like @variant)
+      if (decl.parent === rule) {
+        properties.push(`  ${decl.prop}: ${decl.value};`)
+      }
+    })
+
+    // Check for variant rules (like dark mode)
+    const variants = []
+    rule.walkAtRules('variant', (variantRule) => {
+      const variantProps = []
+      variantRule.walkDecls((decl) => {
+        variantProps.push(`    ${decl.prop}: ${decl.value};`)
+      })
+      variants.push({
+        name: variantRule.params.trim(),
+        properties: variantProps,
+      })
+    })
+
+    utilities.push({
+      name,
+      properties,
+      variants,
+      raw: rule.toString(),
+    })
+  })
+
+  return utilities
+}
+
+// Extract theme colors that are exposed as utilities
+async function extractThemeColors(cssPath) {
+  const css = fs.readFileSync(cssPath, 'utf8')
+  const ast = postcss.parse(css)
+  const colors = new Set()
+
+  ast.walkAtRules('theme', (rule) => {
+    rule.walkDecls((decl) => {
+      if (decl.prop.startsWith('--color-') && !decl.prop.includes('*')) {
+        const colorName = decl.prop.replace('--color-', '')
+        // Only include semantic colors, not raw values
+        if (
+          !colorName.match(
+            /^(brand|neutral|destructive|warning|success|info)-\d+$/
+          )
+        ) {
+          colors.add(colorName)
+        }
+      }
+    })
+  })
+
+  return Array.from(colors)
+}
+
+// Generate TypeScript definitions
+function generateTypeDefinitions(utilities, themeColors) {
+  const utilityTypes = utilities.map((u) => `  | '${u.name}'`).join('\n')
+
+  // Generate color utility types
+  const colorPrefixes = ['bg', 'text', 'border', 'ring', 'divide']
+  const colorUtilities = themeColors
+    .flatMap((color) =>
+      colorPrefixes.map((prefix) => `  | '${prefix}-${color}'`)
+    )
+    .join('\n')
+
+  return `/**
+ * Auto-generated TypeScript definitions for Moonshine utilities
+ * Generated on: ${new Date().toISOString()}
+ *
+ * DO NOT EDIT THIS FILE DIRECTLY
+ * Run 'pnpm generate:docs' to update
+ */
+
+/**
+ * Custom utility classes defined in utilities.css
+ */
+export type MoonshineUtilities =
+${utilityTypes};
+
+/**
+ * Semantic color utilities available from theme
+ * These are auto-generated from theme colors with standard prefixes
+ */
+export type MoonshineColorUtilities =
+${colorUtilities};
+
+/**
+ * All available Moonshine utility classes
+ */
+export type MoonshineClasses = MoonshineUtilities | MoonshineColorUtilities;
+
+/**
+ * Helper type for className props
+ */
+export type MoonshineClassName = MoonshineClasses | MoonshineClasses[] | undefined | null | false;
+`
+}
+
+// Generate documentation section for CLAUDE.md
+function generateDocSection(utilities) {
+  const sections = []
+
+  // Group utilities by type
+  const typography = utilities.filter(
+    (u) => u.name.startsWith('text-') || u.name.startsWith('typography-')
+  )
+  const backgrounds = utilities.filter((u) => u.name.startsWith('bg-'))
+  const borders = utilities.filter((u) => u.name.startsWith('border-'))
+  const other = utilities.filter(
+    (u) =>
+      !u.name.startsWith('text-') &&
+      !u.name.startsWith('typography-') &&
+      !u.name.startsWith('bg-') &&
+      !u.name.startsWith('border-')
+  )
+
+  sections.push('## Available Utility Classes\n')
+  sections.push(
+    'This section is auto-generated from the CSS files. Last updated: ' +
+      new Date().toISOString() +
+      '\n'
+  )
+
+  // Typography
+  if (typography.length > 0) {
+    sections.push('### Typography Utilities\n')
+    typography.forEach((u) => {
+      sections.push(`#### \`${u.name}\`\n`)
+      sections.push('```css')
+      sections.push(`.${u.name} {`)
+      sections.push(u.properties.join('\n'))
+
+      if (u.variants.length > 0) {
+        u.variants.forEach((v) => {
+          sections.push(`\n  /* ${v.name} variant */`)
+          sections.push(v.properties.join('\n'))
+        })
+      }
+
+      sections.push('}')
+      sections.push('```\n')
+    })
+  }
+
+  // Backgrounds
+  if (backgrounds.length > 0) {
+    sections.push('### Background Utilities\n')
+    backgrounds.forEach((u) => {
+      sections.push(`#### \`${u.name}\`\n`)
+      sections.push('```css')
+      sections.push(`.${u.name} {`)
+      sections.push(u.properties.join('\n'))
+
+      if (u.variants.length > 0) {
+        u.variants.forEach((v) => {
+          sections.push(`\n  /* ${v.name} variant */`)
+          sections.push(v.properties.join('\n'))
+        })
+      }
+
+      sections.push('}')
+      sections.push('```\n')
+    })
+  }
+
+  // Borders
+  if (borders.length > 0) {
+    sections.push('### Border Utilities\n')
+    borders.forEach((u) => {
+      sections.push(`#### \`${u.name}\`\n`)
+      sections.push('```css')
+      sections.push(`.${u.name} {`)
+      sections.push(u.properties.join('\n'))
+      sections.push('}')
+      sections.push('```\n')
+    })
+  }
+
+  // Other
+  if (other.length > 0) {
+    sections.push('### Other Utilities\n')
+    other.forEach((u) => {
+      sections.push(`#### \`${u.name}\`\n`)
+      sections.push('```css')
+      sections.push(`.${u.name} {`)
+      sections.push(u.properties.join('\n'))
+      sections.push('}')
+      sections.push('```\n')
+    })
+  }
+
+  return sections.join('\n')
+}
+
+// Update CLAUDE.md with generated content
+function updateClaudeMd(newContent) {
+  const claudeMd = fs.readFileSync(CLAUDE_MD, 'utf8')
+
+  // Find the section to replace
+  const startMarker = '## Available Utility Classes'
+  const endMarker = '## Migration Notes'
+
+  const startIndex = claudeMd.indexOf(startMarker)
+  let endIndex = claudeMd.indexOf(endMarker)
+
+  // If end marker not found, look for the next ## heading
+  if (endIndex === -1) {
+    const afterStart = claudeMd.substring(startIndex + startMarker.length)
+    const nextHeadingMatch = afterStart.match(/\n## /)
+    if (nextHeadingMatch) {
+      endIndex = startIndex + startMarker.length + nextHeadingMatch.index + 1
+    }
+  }
+
+  if (startIndex === -1) {
+    console.error(
+      'Could not find "## Available Utility Classes" section in CLAUDE.md'
+    )
+    console.error(
+      'Please ensure CLAUDE.md contains this section for auto-generation to work'
+    )
+    return
+  }
+
+  if (endIndex === -1 || endIndex <= startIndex) {
+    // No end marker found, append to end of file
+    const updated = claudeMd + '\n\n' + newContent
+    fs.writeFileSync(CLAUDE_MD, updated, 'utf8')
+    console.log('   Appended to end of CLAUDE.md (no end marker found)')
+  } else {
+    const before = claudeMd.substring(0, startIndex)
+    const after = claudeMd.substring(endIndex)
+    const updated = before + newContent + '\n' + after
+    fs.writeFileSync(CLAUDE_MD, updated, 'utf8')
+  }
+}
+
+// Main function
+async function main() {
+  console.log('🎨 Generating Moonshine utility documentation...\n')
+
+  try {
+    // Extract utilities
+    console.log('📖 Reading utilities.css...')
+    const utilities = await extractUtilities(UTILITIES_CSS)
+    console.log(`   Found ${utilities.length} utility classes`)
+
+    // Extract theme colors
+    console.log('🎨 Reading theme colors from utilities.css...')
+    const themeColors = await extractThemeColors(UTILITIES_CSS)
+    console.log(`   Found ${themeColors.length} theme colors`)
+
+    // Generate TypeScript definitions
+    console.log('\n📝 Generating TypeScript definitions...')
+    const typeDefs = generateTypeDefinitions(utilities, themeColors)
+    fs.writeFileSync(UTILITIES_TYPES, typeDefs, 'utf8')
+    console.log(
+      `   Written to ${path.relative(process.cwd(), UTILITIES_TYPES)}`
+    )
+
+    // Generate documentation
+    console.log('\n📚 Generating documentation...')
+    const docSection = generateDocSection(utilities)
+    updateClaudeMd(docSection)
+    console.log(`   Updated ${path.relative(process.cwd(), CLAUDE_MD)}`)
+
+    console.log('\n✅ Documentation generation complete!')
+    console.log('\n💡 Tip: Import the types in your components:')
+    console.log(
+      '   import type { MoonshineClasses } from "@speakeasy-api/moonshine/types/utilities"'
+    )
+  } catch (error) {
+    console.error('\n❌ Error generating documentation:', error)
+    process.exit(1)
+  }
+}
+
+// Run the script
+main()
diff --git a/src/base.css b/src/base.css
new file mode 100644
index 00000000..2f5b0e67
--- /dev/null
+++ b/src/base.css
@@ -0,0 +1,914 @@
+/*
+ * Base CSS - Design Tokens and CSS Variables
+ *
+ * ⚠️  WARNING: DO NOT IMPORT THIS FILE DIRECTLY IN YOUR PROJECT!
+ * This file is only exposed for Tailwind's @reference directive to work.
+ * Use the utility classes from utilities.css instead of these raw tokens.
+ *
+ * Structure:
+ * 1. Primitive Tokens - Raw values (colors, fonts, etc.)
+ * 2. Semantic/Utility Tokens - Theme-aware variables that map to utilities
+ * 3. Component Tokens - Higher-level semantic tokens
+ * 4. Deprecated Tokens - Shadcn compatibility (to be removed)
+ */
+
+:root,
+:root.light {
+  /* ============================================
+   * 1. PRIMITIVE TOKENS
+   * Raw design values - do not use directly in components
+   * ============================================ */
+
+  /* Font Families */
+  --font-diatype: 'Diatype', -apple-system, BlinkMacSystemFont, 'Segoe UI',
+    Roboto, Helvetica, Arial, sans-serif;
+  --font-diatype-mono: 'Diatype Mono', SFMono-Regular, Menlo, Monaco, Consolas,
+    'Liberation Mono', 'Courier New', monospace;
+  --font-tobias: 'Tobias', 'Cormorant', Georgia, Cambria, 'Times New Roman',
+    Times, serif;
+
+  --color-base-white: hsl(0 0% 100%);
+  --color-base-black: hsl(0 0% 0%);
+
+  /* Neutrals */
+  --color-neutral-100: hsl(0, 0%, 98%);
+  --color-neutral-200: hsl(0, 0%, 92%);
+  --color-neutral-300: hsl(0, 0%, 86%);
+  --color-neutral-400: hsl(0, 0%, 73%);
+  --color-neutral-500: hsl(0, 0%, 59%);
+  --color-neutral-600: hsl(0, 0%, 46%);
+  --color-neutral-700: hsl(0, 0%, 33%);
+  --color-neutral-800: hsl(0, 0%, 20%);
+  --color-neutral-900: hsl(0, 0%, 7%);
+
+  --color-neutral-100-40: hsl(from var(--color-neutral-100) h s l / 40%);
+  --color-neutral-100-56: hsl(from var(--color-neutral-100) h s l / 56%);
+  --color-neutral-100-64: hsl(from var(--color-neutral-100) h s l / 64%);
+
+  --color-neutral-200-56: hsl(from var(--color-neutral-200) h s l / 56%);
+
+  --color-neutral-400-40: hsl(from var(--color-neutral-400) h s l / 40%);
+
+  --color-neutral-600-40: hsl(from var(--color-neutral-600) h s l / 40%);
+
+  --color-neutral-800-56: hsl(from var(--color-neutral-800) h s l / 56%);
+
+  --color-neutral-900-40: hsl(from var(--color-neutral-900) h s l / 40%);
+  --color-neutral-900-56: hsl(from var(--color-neutral-900) h s l / 56%);
+  --color-neutral-900-64: hsl(from var(--color-neutral-900) h s l / 64%);
+
+  /* Brand red */
+  --color-brand-red-100: hsl(23, 96%, 62%);
+  --color-brand-red-200: hsl(19, 84%, 58%);
+  --color-brand-red-300: hsl(14, 74%, 54%);
+  --color-brand-red-400: hsl(9, 67%, 51%);
+  --color-brand-red-500: hsl(4, 67%, 47%);
+  --color-brand-red-600: hsl(1, 62%, 39%);
+  --color-brand-red-700: hsl(359, 58%, 31%);
+  --color-brand-red-800: hsl(352, 57%, 22%);
+  --color-brand-red-900: hsl(334, 54%, 13%);
+
+  --gradient-brand-red: radial-gradient(
+    138.34% 138.34% at 0% 4.4%,
+    var(--color-destructive-900) 0%,
+    var(--color-destructive-800) 12.5%,
+    var(--color-destructive-700) 25%,
+    var(--color-destructive-600) 37.5%,
+    var(--color-destructive-500) 50%,
+    var(--color-destructive-400) 62.5%,
+    var(--color-destructive-300) 75%,
+    var(--color-destructive-200) 87.5%,
+    var(--color-destructive-100) 100%
+  );
+
+  /* Brand green */
+  --color-brand-green-100: hsl(68, 52%, 72%);
+  --color-brand-green-200: hsl(75, 37%, 64%);
+  --color-brand-green-300: hsl(84, 28%, 56%);
+  --color-brand-green-400: hsl(95, 23%, 49%);
+  --color-brand-green-500: hsl(108, 24%, 41%);
+  --color-brand-green-600: hsl(116, 24%, 34%);
+  --color-brand-green-700: hsl(128, 30%, 25%);
+  --color-brand-green-800: hsl(140, 44%, 16%);
+  --color-brand-green-900: hsl(154, 100%, 7%);
+
+  --gradient-brand-green: radial-gradient(
+    137.26% 137.26% at 0% 0%,
+    var(--color-brand-green-900) 0%,
+    var(--color-brand-green-800) 12.5%,
+    var(--color-brand-green-700) 25%,
+    var(--color-brand-green-600) 37.5%,
+    var(--color-brand-green-500) 50%,
+    var(--color-brand-green-400) 62.5%,
+    var(--color-brand-green-300) 75%,
+    var(--color-brand-green-200) 87.5%,
+    var(--color-brand-green-100) 100%
+  );
+
+  /* Brand blue */
+  --color-brand-blue-100: hsl(216, 100%, 100%);
+  --color-brand-blue-200: hsl(215, 86%, 73%);
+  --color-brand-blue-300: hsl(215, 77%, 65%);
+  --color-brand-blue-400: hsl(215, 72%, 58%);
+  --color-brand-blue-500: hsl(214, 69%, 50%);
+  --color-brand-blue-600: hsl(215, 71%, 40%);
+  --color-brand-blue-700: hsl(215, 75%, 31%);
+  --color-brand-blue-800: hsl(217, 82%, 21%);
+  --color-brand-blue-900: hsl(220, 100%, 12%);
+
+  --gradient-brand-blue: radial-gradient(
+    141.42% 141.42% at 0% 0%,
+    var(--color-brand-blue-900) 0%,
+    var(--color-brand-blue-800) 12.5%,
+    var(--color-brand-blue-700) 25%,
+    var(--color-brand-blue-600) 37.5%,
+    var(--color-brand-blue-500) 50%,
+    var(--color-brand-blue-400) 62.5%,
+    var(--color-brand-blue-300) 75%,
+    var(--color-brand-blue-200) 87.5%,
+    var(--color-brand-blue-100) 100%
+  );
+
+  /* Tech colors */
+  --color-brand-typescript: hsl(0, 0%, 0%);
+  --color-brand-go: hsl(220, 100%, 12%);
+  --color-brand-java: hsl(214, 69%, 50%);
+  --color-brand-python: hsl(216, 100%, 80%);
+  --color-brand-c: hsl(154, 100%, 7%);
+  --color-brand-terraform: hsl(108, 24%, 41%);
+  --color-brand-unity: hsl(68, 52%, 72%);
+  --color-brand-php: hsl(334, 54%, 13%);
+  --color-brand-swift: hsl(4, 67%, 47%);
+  --color-brand-ruby: hsl(23, 96%, 62%);
+  --color-brand-postman: hsl(0, 0%, 83%);
+
+  --gradient-brand-primary-colors: var(--color-brand-php) 0%,
+    var(--color-brand-swift) 12.56%, var(--color-brand-ruby) 25.06%,
+    var(--color-brand-unity) 37.56%, var(--color-brand-terraform) 50.06%,
+    var(--color-brand-c) 62.06%, var(--color-brand-go) 74.06%,
+    var(--color-brand-java) 86.06%, var(--color-brand-python) 97.06%;
+
+  --gradient-brand-primary: linear-gradient(
+    90deg,
+    var(--gradient-brand-primary-colors)
+  );
+
+  --gradient-brand-primary-y: linear-gradient(
+    180deg,
+    var(--gradient-brand-primary-colors)
+  );
+
+  /* Feedback colors */
+
+  /* Red */
+  --color-feedback-red-100: hsl(0, 100%, 97%);
+  --color-feedback-red-200: hsl(3, 84%, 85%);
+  --color-feedback-red-300: hsl(3, 78%, 71%);
+  --color-feedback-red-400: hsl(2, 74%, 58%);
+  --color-feedback-red-500: hsl(4, 67%, 47%);
+  --color-feedback-red-600: hsl(2, 65%, 39%);
+  --color-feedback-red-700: hsl(1, 64%, 32%);
+  --color-feedback-red-800: hsl(1, 63%, 24%);
+  --color-feedback-red-900: hsl(0, 62%, 17%);
+
+  --color-feedback-red-400-56: hsl(from var(--color-feedback-red-400) h s l / 56%);
+  --color-feedback-red-500-56: hsl(from var(--color-feedback-red-500) h s l / 56%);
+  --color-feedback-red-600-56: hsl(from var(--color-feedback-red-600) h s l / 56%);
+
+
+  /* Orange */
+  --color-feedback-orange-100: hsl(29, 100%, 95%);
+  --color-feedback-orange-200: hsl(30, 100%, 85%);
+  --color-feedback-orange-300: hsl(28, 100%, 74%);
+  --color-feedback-orange-400: hsl(27, 100%, 66%);
+  --color-feedback-orange-500: hsl(23, 96%, 62%);
+  --color-feedback-orange-600: hsl(22, 70%, 53%);
+  --color-feedback-orange-700: hsl(21, 64%, 43%);
+  --color-feedback-orange-800: hsl(19, 66%, 33%);
+  --color-feedback-orange-900: hsl(18, 69%, 24%);
+
+  --color-feedback-orange-400-56: hsl(from var(--color-feedback-orange-400) h s l / 56%);
+  --color-feedback-orange-500-56: hsl(from var(--color-feedback-orange-500) h s l / 56%);
+
+  /* Green */
+  --color-feedback-green-100: hsl(102, 35%, 93%);
+  --color-feedback-green-200: hsl(99, 33%, 83%);
+  --color-feedback-green-300: hsl(99, 30%, 73%);
+  --color-feedback-green-400: hsl(101, 28%, 62%);
+  --color-feedback-green-500: hsl(108, 24%, 41%);
+  --color-feedback-green-600: hsl(107, 24%, 34%);
+  --color-feedback-green-700: hsl(105, 24%, 27%);
+  --color-feedback-green-800: hsl(104, 24%, 20%);
+  --color-feedback-green-900: hsl(105, 24%, 13%);
+
+  --color-feedback-green-400-56: hsl(from var(--color-feedback-green-400) h s l / 56%);
+  --color-feedback-green-500-56: hsl(from var(--color-feedback-green-500) h s l / 56%);
+
+  /* Blue */
+  --color-feedback-blue-100: hsl(212, 100%, 95%);
+  --color-feedback-blue-200: hsl(214, 100%, 86%);
+  --color-feedback-blue-300: hsl(214, 100%, 77%);
+  --color-feedback-blue-400: hsl(214, 89%, 67%);
+  --color-feedback-blue-500: hsl(214, 69%, 50%);
+  --color-feedback-blue-600: hsl(215, 70%, 41%);
+  --color-feedback-blue-700: hsl(215, 71%, 32%);
+  --color-feedback-blue-800: hsl(217, 73%, 23%);
+  --color-feedback-blue-900: hsl(218, 73%, 15%);
+
+  --color-feedback-blue-400-56: hsl(from var(--color-feedback-blue-400) h s l / 56%);
+  --color-feedback-blue-500-56: hsl(from var(--color-feedback-blue-500) h s l / 56%);
+
+  /* Violet */
+  --color-feedback-violet-300: hsl(265, 77%, 65%);
+  --color-feedback-violet-600: 	hsl(268, 75%, 31%);
+
+  --color-link-default: var(--color-brand-blue-600);
+  --color-link-visited-primary: var(--color-feedback-violet-600);
+  --color-link-secondary: var(--color-base-black);
+  --color-link-visited-secondary: var(--color-feedback-violet-600);
+
+  /* ============================================
+   * 2. SEMANTIC/UTILITY TOKENS
+   * Theme-aware variables that map directly to utility classes
+   * These change based on light/dark mode
+   * ============================================ */
+
+  /* Text Colors */
+  /* TODO: These should use our skimmable colors for headings */
+  --text-heading-xl: var(--color-neutral-900);
+  --text-heading-lg: var(--color-neutral-900);
+  --text-heading-md: var(--color-neutral-900);
+  --text-heading-sm: var(--color-neutral-800);
+  --text-heading-xs: var(--color-neutral-800);
+
+  --text-display: var(--color-base-black);
+
+  --text-highlight: var(--color-neutral-900);
+  --text-default: var(--color-neutral-700);
+  --text-muted: var(--color-neutral-900-64);
+  --text-placeholder: var(--color-neutral-900-56);
+  --text-disabled: var(--color-neutral-900-40);
+
+  --text-dark-light-highlight: var(--color-base-black);
+  --text-dark-light-default: var(--color-neutral-900);
+  --text-dark-light-muted: var(--color-neutral-900-64);
+
+  --text-light-dark-highlight: var(--color-base-white);
+  --text-light-dark-default: var(--color-neutral-100);
+  --text-light-dark-muted: var(--color-neutral-100-64);
+
+  --text-link-primary: var(--color-brand-blue-600);
+  --text-link-secondary: var(--color-base-black);
+  --text-link-visited: var(--color-feedback-violet-600);
+
+  --text-default-destructive: var(--color-feedback-red-700);
+  --text-link-destructive: var(--color-feedback-red-900);
+
+  --text-default-information: var(--color-feedback-blue-700);
+  --text-link-information: var(--color-feedback-blue-900);
+
+  --text-default-success: var(--color-feedback-green-700);
+  --text-link-success: var(--color-feedback-green-900);
+
+  --text-default-warning: var(--color-feedback-orange-700);
+  --text-link-warning: var(--color-feedback-orange-900);
+
+
+  --text-body: var(--color-neutral-900);
+  --text-body-muted: var(--color-neutral-400);
+
+  /* Warning State */
+  --bg-warning: var(--color-feedback-orange-100);
+  --text-warning: var(--color-feedback-orange-700);
+  --border-warning: var(--color-feedback-orange-300);
+
+
+    /* Link utilities */
+  --underline-link-primary: var(--color-brand-blue-600);
+  --underline-link-secondary: var(--color-base-black);
+  --underline-link-visited: var(--color-feedback-violet-600);
+
+
+  /* ============================================
+   * BORDER TOKENS
+   * ============================================ */
+
+  /* Border utilities - neutral states */
+  --border-neutral-active: var(--color-neutral-600);
+  --border-neutral-hover: var(--color-neutral-500);
+  --border-neutral-default: var(--color-neutral-400);
+  --border-neutral-disabled: var(--color-neutral-400-40);
+  --border-neutral-softest: var(--color-neutral-300);
+  --border-neutral-inset: var(--color-base-black);
+  --border-neutral-alpha: hsla(
+    0,
+    0%,
+    0%,
+    0.2
+  ); /* Black with 20% opacity for light mode */
+
+
+  /* Border Destructive utilities */
+  --border-destructive-highlight: var(--color-feedback-red-600);
+  --border-destructive-default: var(--color-feedback-red-500);
+  --border-destructive-muted: var(--color-feedback-red-500-56);
+  --border-destructive-softest: var(--color-feedback-red-300);
+
+  /* Border Information utilities */
+  --border-information-highlight: var(--color-feedback-blue-600);
+  --border-information-default: var(--color-feedback-blue-500);
+  --border-information-muted: var(--color-feedback-blue-500-56);
+  --border-information-softest: var(--color-feedback-blue-300);
+
+  /* Border Success utilities */
+  --border-success-highlight: var(--color-feedback-green-600);
+  --border-success-default: var(--color-feedback-green-500);
+  --border-success-muted: var(--color-feedback-green-500-56);
+  --border-success-softest: var(--color-feedback-green-300);
+
+  /* Border Warning utilities */
+  --border-warning-highlight: var(--color-feedback-orange-600);
+  --border-warning-default: var(--color-feedback-orange-500);
+  --border-warning-muted: var(--color-feedback-orange-500-56);
+  --border-warning-softest: var(--color-feedback-orange-300);
+
+  /* Border Focus utilities */
+  --border-focus: var(--color-brand-blue-600);
+
+
+  /* ============================================
+   * FILLS
+   * ============================================ */
+
+   /* Neutrals */
+   --fill-neutral-highlight: var(--color-base-black);
+   --fill-neutral-active: var(--color-neutral-900);
+   --fill-neutral-default: var(--color-neutral-800);
+   --fill-neutral-muted: var(--color-neutral-800-56);
+
+   /* onColor / Dark */
+   --fill-onColor-dark-highlight: var(--color-base-black);
+   --fill-onColor-dark-default: var(--color-neutral-800);
+   --fill-onColor-dark-muted: var(--color-neutral-900-56);
+
+   /* onColor / Light */
+   --fill-onColor-light-highlight: var(--color-base-white);
+   --fill-onColor-light-default: var(--color-neutral-100);
+   --fill-onColor-light-muted: var(--color-neutral-100-56);
+
+   /* Links */
+   --fill-link-primary: var(--color-brand-blue-600);
+   --fill-link-secondary: var(--color-base-black);
+   --fill-link-visited: var(--color-feedback-violet-600);
+
+   /* Destructive */
+   --fill-destructive-highlight: var(--color-feedback-red-600);
+   --fill-destructive-default: var(--color-feedback-red-500);
+   --fill-destructive-muted: var(--color-feedback-red-600-56);
+
+   /* Information */
+   --fill-information-highlight: var(--color-feedback-blue-600);
+   --fill-information-default: var(--color-feedback-blue-500);
+   --fill-information-muted: var(--color-feedback-blue-500-56);
+
+   /* Success */
+   --fill-success-highlight: var(--color-feedback-green-600);
+   --fill-success-default: var(--color-feedback-green-500);
+   --fill-success-muted: var(--color-feedback-green-500-56);
+
+   /* Warning */
+   --fill-warning-highlight: var(--color-feedback-orange-600);
+   --fill-warning-default: var(--color-feedback-orange-500);
+   --fill-warning-muted: var(--color-feedback-orange-500-56);
+
+   /* ============================================
+   * Strokes
+   * ============================================ */
+
+   /* Neutrals */
+   --stroke-neutral-highlight: var(--color-base-black);
+   --stroke-neutral-active: var(--color-neutral-900);
+   --stroke-neutral-default: var(--color-neutral-800);
+   --stroke-neutral-muted: var(--color-neutral-800-56);
+
+   /* onColor / Dark */
+   --stroke-onColor-dark-highlight: var(--color-base-black);
+   --stroke-onColor-dark-default: var(--color-neutral-800);
+   --stroke-onColor-dark-muted: var(--color-neutral-900-56);
+
+   /* onColor / Light */
+   --stroke-onColor-light-highlight: var(--color-base-white);
+   --stroke-onColor-light-default: var(--color-neutral-100);
+   --stroke-onColor-light-muted: var(--color-neutral-100-56);
+
+   /* Links */
+   --stroke-link-primary: var(--color-brand-blue-600);
+   --stroke-link-secondary: var(--color-base-black);
+   --stroke-link-visited: var(--color-feedback-violet-600);
+
+   /* Destructive */
+   --stroke-destructive-highlight: var(--color-feedback-red-600);
+   --stroke-destructive-default: var(--color-feedback-red-500);
+   --stroke-destructive-muted: var(--color-feedback-red-600-56);
+
+   /* Information */
+   --stroke-information-highlight: var(--color-feedback-blue-600);
+   --stroke-information-default: var(--color-feedback-blue-500);
+   --stroke-information-muted: var(--color-feedback-blue-500-56);
+
+   /* Success */
+   --stroke-success-highlight: var(--color-feedback-green-600);
+   --stroke-success-default: var(--color-feedback-green-500);
+   --stroke-success-muted: var(--color-feedback-green-500-56);
+
+   /* Warning */
+   --stroke-warning-highlight: var(--color-feedback-orange-600);
+   --stroke-warning-default: var(--color-feedback-orange-500);
+   --stroke-warning-muted: var(--color-feedback-orange-500-56);
+
+  /* ============================================
+   * BACKGROUNDS
+   * ============================================ */
+   --bg-primary: var(--color-base-white);
+   --bg-secondary: var(--color-neutral-100);
+   --bg-tertiary: var(--color-neutral-200);
+
+   /* State */
+   --bg-highlight: var(--color-neutral-300);
+   --bg-active: var(--color-neutral-200);
+   --bg-default: var(--color-neutral-100);
+   --bg-muted: var(--color-neutral-100-56);
+   --bg-inset: var(--color-base-white);
+
+   /* Light background in dark mode */
+   --bg-light-dark-primary: var(--color-base-white);
+   --bg-light-dark-secondary: var(--color-neutral-100);
+   --bg-light-dark-tertiary: var(--color-neutral-200);
+
+   /* Dark background in light mode */
+   --bg-dark-light-primary: var(--color-base-black);
+   --bg-dark-light-secondary: var(--color-neutral-900);
+   --bg-dark-light-tertiary: var(--color-neutral-800);
+
+   /* Destructive */
+   --bg-destructive-highlight: var(--color-feedback-red-600);
+   --bg-destructive-default: var(--color-feedback-red-500);
+   --bg-destructive-muted: var(--color-feedback-red-500-56);
+   --bg-destructive-softest: var(--color-feedback-red-100);
+
+   /* Information */
+   --bg-information-highlight: var(--color-feedback-blue-600);
+   --bg-information-default: var(--color-feedback-blue-500);
+   --bg-information-muted: var(--color-feedback-blue-500-56);
+   --bg-information-softest: var(--color-feedback-blue-100);
+
+   /* Success */
+   --bg-success-highlight: var(--color-feedback-green-600);
+   --bg-success-default: var(--color-feedback-green-500);
+   --bg-success-muted: var(--color-feedback-green-500-56);
+   --bg-success-softest: var(--color-feedback-green-100);
+
+   /* Warning */
+   --bg-warning-highlight: var(--color-feedback-orange-600);
+   --bg-warning-default: var(--color-feedback-orange-500);
+   --bg-warning-muted: var(--color-feedback-orange-500-56);
+   --bg-warning-softest: var(--color-feedback-orange-100);
+
+
+
+
+  /* ============================================
+   * 3. COMPONENT TOKENS
+   * Higher-level semantic tokens for specific use cases
+   * ============================================ */
+
+  /* Border Radius */
+  --radius: 0.625rem;
+  /* ============================================
+   * 4. DEPRECATED TOKENS - SHADCN COMPATIBILITY
+   * These will be removed in future versions
+   * DO NOT use in new code
+   * ============================================ */
+
+  --background-pure: var(--color-base-white);
+  --background: var(--color-neutral-100);
+  --foreground: var(--color-neutral-900);
+  --card: var(--color-base-white);
+  --card-foreground: var(--color-neutral-900);
+  --popover: var(--color-base-white);
+  --popover-foreground: var(--color-neutral-900);
+  --primary: var(--color-base-black);
+  --primary-foreground: var(--color-base-white);
+  --secondary: var(--color-neutral-100);
+  --secondary-foreground: var(--color-neutral-900);
+  --muted: var(--color-neutral-200);
+  --muted-foreground: var(--color-neutral-900-64);
+  --accent: var(--color-neutral-200);
+  --accent-foreground: var(--color-neutral-900);
+  --destructive: var(
+    --color-feedback-red-700
+  ); /* Note: conflicts with semantic token above */
+  --border: var(--color-neutral-300);
+  --input: var(--color-neutral-400);
+  --ring: var(--color-brand-blue-600);
+  --chart-1: var(--color-brand-red-600);
+  --chart-2: var(--color-brand-green-600);
+  --chart-3: var(--color-brand-red-600);
+  --chart-4: var(--color-brand-blue-600);
+  --chart-5: var(--color-brand-green-600);
+  --sidebar: var(--color-neutral-100);
+  --sidebar-foreground: var(--color-neutral-900);
+  --sidebar-primary: var(--color-base-black);
+  --sidebar-primary-foreground: var(--color-neutral-300);
+  --sidebar-accent: var(--color-neutral-300);
+  --sidebar-accent-foreground: var(--color-neutral-900);
+  --sidebar-border: var(--color-neutral-300);
+  --sidebar-ring: var(--color-brand-blue-600);
+
+  /* Feedback States */
+  --success: var(--color-feedback-green-100);
+  --success-foreground: var(--color-feedback-green-700);
+  --warning: var(--color-feedback-orange-100);
+  --warning-foreground: var(--color-feedback-orange-700);
+  --info: var(--color-info-100);
+  --info-foreground: var(--color-info-700);
+  /* This is a dupe of a shadcn token, may need to rename*/
+  --destructive: var(--color-destructive-100);
+  --destructive-foreground: var(--color-destructive-700);
+  --feature: var(--color-info-100);
+  --feature-foreground: var(--color-info-700);
+
+  /* UI Elements */
+  --shadow: hsl(0 0% 50%);
+
+  /* Custom Scrollbar */
+  --sb-size: 0.5rem;
+  --sb-track-color: var(--color-background);
+  --sb-thumb-color: var(--color-background);
+  --sb-track-border: var(--color-neutral-300);
+
+  /* Score Colors */
+  --score-low: var(--color-destructive-500);
+  --score-mid: var(--color-feedback-orange-500);
+  --score-high: var(--color-feedback-green-500);
+  --score-track: var(--color-neutral-700);
+
+  /* Animation Easing Functions */
+  --ease-in-quad: cubic-bezier(0.55, 0.085, 0.68, 0.53);
+  --ease-in-cubic: cubic-bezier(0.55, 0.055, 0.675, 0.19);
+  --ease-in-quart: cubic-bezier(0.895, 0.03, 0.685, 0.22);
+  --ease-in-quint: cubic-bezier(0.755, 0.05, 0.855, 0.06);
+  --ease-in-expo: cubic-bezier(0.95, 0.05, 0.795, 0.035);
+  --ease-in-circ: cubic-bezier(0.6, 0.04, 0.98, 0.335);
+
+  --ease-out-quad: cubic-bezier(0.25, 0.46, 0.45, 0.94);
+  --ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
+  --ease-out-quart: cubic-bezier(0.165, 0.84, 0.44, 1);
+  --ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);
+  --ease-out-expo: cubic-bezier(0.19, 1, 0.22, 1);
+  --ease-out-circ: cubic-bezier(0.075, 0.82, 0.165, 1);
+
+  --ease-in-out-quad: cubic-bezier(0.455, 0.03, 0.515, 0.955);
+  --ease-in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1);
+  --ease-in-out-quart: cubic-bezier(0.77, 0, 0.175, 1);
+  --ease-in-out-quint: cubic-bezier(0.86, 0, 0.07, 1);
+  --ease-in-out-expo: cubic-bezier(1, 0, 0, 1);
+  --ease-in-out-circ: cubic-bezier(0.785, 0.135, 0.15, 0.86);
+}
+
+/* ============================================
+ * BASE ELEMENT STYLES
+ * Default styles for HTML elements
+ * ============================================ */
+
+/*
+ * Tailwind v4 Compatibility Layer
+ * The default border color has changed to `currentColor` in Tailwind CSS v4.
+ * These styles maintain v3 behavior until we can audit all border usage.
+ */
+@layer base {
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--border-neutral-default, currentColor);
+  }
+
+  button:not(:disabled),
+  [role='button']:not(:disabled) {
+    cursor: pointer;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+:root.dark {
+  /* ============================================
+   * DARK MODE OVERRIDES
+   * Only define values that change in dark mode
+   * ============================================ */
+
+  --color-link-default: var(--color-brand-blue-300);
+  --color-link-visited-primary: var(--color-feedback-violet-300);
+  --color-link-secondary: var(--color-base-white);
+  --color-link-visited-secondary: var(--color-feedback-violet-300);
+
+  /* ============================================
+   * 2. SEMANTIC/UTILITY TOKENS (Dark Mode)
+   * ============================================ */
+
+  /* Text Colors */
+  --text-heading-xl: var(--color-neutral-100);
+  --text-heading-lg: var(--color-neutral-100);
+  --text-heading-md: var(--color-neutral-100);
+  --text-heading-sm: var(--color-neutral-200);
+  --text-heading-xs: var(--color-neutral-200);
+
+  --text-display: var(--color-base-white);
+
+  --text-highlight: var(--color-neutral-100);
+  --text-default: var(--color-neutral-300);
+  --text-muted: var(--color-neutral-100-64);
+  --text-placeholder: var(--color-neutral-100-56);
+  --text-disabled: var(--color-neutral-100-40);
+
+  --text-link-primary: var(--color-brand-blue-300);
+  --text-link-secondary: var(--color-base-white);
+  --text-link-visited: var(--color-feedback-violet-300);
+
+  --text-default-destructive: var(--color-feedback-red-300);
+  --text-link-destructive: var(--color-feedback-red-100);
+
+  --text-default-information: var(--color-feedback-blue-300);
+  --text-link-information: var(--color-feedback-blue-100);
+
+  --text-default-success: var(--color-feedback-green-300);
+  --text-link-success: var(--color-feedback-green-100);
+
+  --text-default-warning: var(--color-feedback-orange-300);
+  --text-link-warning: var(--color-feedback-orange-100);
+
+  --text-body: var(--color-neutral-200);
+  --text-body-muted: var(--color-neutral-600);
+
+  /* Warning State */
+  --bg-warning: var(--color-feedback-orange-900);
+  --text-warning: var(--color-feedback-orange-300);
+  --border-warning: var(--color-feedback-orange-700);
+
+    /* Link utilities (dark mode) */
+  --underline-link-primary: var(--color-brand-blue-300);
+  --underline-link-secondary: var(--color-base-white);
+  --underline-link-visited: var(--color-feedback-violet-300);
+
+  /* ============================================
+   * BORDER TOKENS
+   * ============================================ */
+
+  /* Border utilities - neutral states (dark mode) */
+  --border-neutral-active: var(--color-neutral-400);
+  --border-neutral-hover: var(--color-neutral-500);
+  --border-neutral-default: var(--color-neutral-600);
+  --border-neutral-disabled: var(--color-neutral-600-40);
+  --border-neutral-softest: var(--color-neutral-700);
+  --border-neutral-inset: var(--color-base-white);
+  --border-neutral-alpha: hsla(
+    255,
+    255%,
+    255%,
+    0.2
+  ); /* White with 20% opacity */
+
+  /* Border destructive utilities */
+  --border-destructive-highlight: var(--color-feedback-red-300);
+  --border-destructive-default: var(--color-feedback-red-500);
+  --border-destructive-muted: var(--color-feedback-red-500-56);
+  --border-destructive-softest: var(--color-feedback-red-700);
+
+  /* Border Information utilities */
+  --border-information-highlight: var(--color-feedback-blue-300);
+  --border-information-default: var(--color-feedback-blue-500);
+  --border-information-muted: var(--color-feedback-blue-500-56);
+  --border-information-softest: var(--color-feedback-blue-700);
+
+  /* Border Success utilities */
+  --border-success-highlight: var(--color-feedback-green-300);
+  --border-success-default: var(--color-feedback-green-500);
+  --border-success-muted: var(--color-feedback-green-500-56);
+  --border-success-softest: var(--color-feedback-green-700);
+
+  /* Border Warning utilities */
+  --border-warning-highlight: var(--color-feedback-orange-300);
+  --border-warning-default: var(--color-feedback-orange-500);
+  --border-warning-muted: var(--color-feedback-orange-500-56);
+  --border-warning-softest: var(--color-feedback-orange-700);
+
+    /* Border Focus utilities */
+  --border-focus: var(--color-brand-blue-300);
+
+
+   /* ============================================
+   * FILLS
+   * ============================================ */
+
+   /* Neutrals */
+  --fill-neutral-highlight: var(--color-base-white);
+  --fill-neutral-active: var(--color-neutral-100);
+  --fill-neutral-default: var(--color-neutral-200);
+  --fill-neutral-muted: var(--color-neutral-200-56);
+
+  /* onColor / Dark */
+   --fill-onColor-dark-highlight: var(--color-base-black);
+   --fill-onColor-dark-default: var(--color-neutral-800);
+   --fill-onColor-dark-muted: var(--color-neutral-900-56);
+
+   /* onColor / Light */
+   --fill-onColor-light-highlight: var(--color-base-white);
+   --fill-onColor-light-default: var(--color-neutral-100);
+   --fill-onColor-light-muted: var(--color-neutral-100-56);
+
+   /* Links */
+   --fill-link-primary: var(--color-brand-blue-300);
+   --fill-link-secondary: var(--color-base-white);
+   --fill-link-visited: var(--color-feedback-violet-300);
+
+    /* Destructive */
+   --fill-destructive-highlight: var(--color-feedback-red-300);
+   --fill-destructive-default: var(--color-feedback-red-400);
+   --fill-destructive-muted: var(--color-feedback-red-400-56);
+
+   /* Information */
+   --fill-information-highlight: var(--color-feedback-blue-300);
+   --fill-information-default: var(--color-feedback-blue-400);
+   --fill-information-muted: var(--color-feedback-blue-400-56);
+
+   /* Success */
+   --fill-success-highlight: var(--color-feedback-green-300);
+   --fill-success-default: var(--color-feedback-green-400);
+   --fill-success-muted: var(--color-feedback-green-400-56);
+
+   /* Warning */
+   --fill-warning-highlight: var(--color-feedback-orange-300);
+   --fill-warning-default: var(--color-feedback-orange-400);
+   --fill-warning-muted: var(--color-feedback-orange-400-56);
+
+   /* ============================================
+   * Strokes
+   * ============================================ */
+
+   /* Neutrals */
+  --stroke-neutral-highlight: var(--color-base-white);
+  --stroke-neutral-active: var(--color-neutral-100);
+  --stroke-neutral-default: var(--color-neutral-200);
+  --stroke-neutral-muted: var(--color-neutral-200-56);
+
+  /* onColor / Dark */
+   --stroke-onColor-dark-highlight: var(--color-base-black);
+   --stroke-onColor-dark-default: var(--color-neutral-800);
+   --stroke-onColor-dark-muted: var(--color-neutral-900-56);
+
+   /* onColor / Light */
+   --stroke-onColor-light-highlight: var(--color-base-white);
+   --stroke-onColor-light-default: var(--color-neutral-100);
+   --stroke-onColor-light-muted: var(--color-neutral-100-56);
+
+   /* Links */
+   --stroke-link-primary: var(--color-brand-blue-300);
+   --stroke-link-secondary: var(--color-base-white);
+   --stroke-link-visited: var(--color-feedback-violet-300);
+
+    /* Destructive */
+   --stroke-destructive-highlight: var(--color-feedback-red-300);
+   --stroke-destructive-default: var(--color-feedback-red-400);
+   --stroke-destructive-muted: var(--color-feedback-red-400-56);
+
+   /* Information */
+   --stroke-information-highlight: var(--color-feedback-blue-300);
+   --stroke-information-default: var(--color-feedback-blue-400);
+   --stroke-information-muted: var(--color-feedback-blue-400-56);
+
+   /* Success */
+   --stroke-success-highlight: var(--color-feedback-green-300);
+   --stroke-success-default: var(--color-feedback-green-400);
+   --stroke-success-muted: var(--color-feedback-green-400-56);
+
+   /* Warning */
+   --stroke-warning-highlight: var(--color-feedback-orange-300);
+   --stroke-warning-default: var(--color-feedback-orange-400);
+   --stroke-warning-muted: var(--color-feedback-orange-400-56);
+
+   /* ============================================
+   * BACKGROUNDS
+   * ============================================ */
+   --bg-primary: var(--color-base-black);
+   --bg-secondary: var(--color-neutral-900);
+   --bg-tertiary: var(--color-neutral-800);
+
+   /* State */
+   --bg-highlight: var(--color-neutral-700);
+   --bg-active: var(--color-neutral-800);
+   --bg-default: var(--color-neutral-900);
+   --bg-muted: var(--color-neutral-900-56);
+   --bg-inset: var(--color-base-black);
+
+   /* Light background in dark mode */
+
+   /* Dark background in light mode */
+
+   /* Destructive */
+   --bg-destructive-highlight: var(--color-feedback-red-300);
+   --bg-destructive-default: var(--color-feedback-red-500);
+   --bg-destructive-muted: var(--color-feedback-red-500-56);
+   --bg-destructive-softest: var(--color-feedback-red-900);
+
+   /* Information */
+   --bg-information-highlight: var(--color-feedback-blue-300);
+   --bg-information-default: var(--color-feedback-blue-500);
+   --bg-information-muted: var(--color-feedback-blue-500-56);
+   --bg-information-softest: var(--color-feedback-blue-900);
+
+   /* Success */
+   --bg-success-highlight: var(--color-feedback-green-300);
+   --bg-success-default: var(--color-feedback-green-500);
+   --bg-success-muted: var(--color-feedback-green-500-56);
+   --bg-success-softest: var(--color-feedback-green-900);
+
+   /* Warning */
+   --bg-warning-highlight: var(--color-feedback-orange-300);
+   --bg-warning-default: var(--color-feedback-orange-500);
+   --bg-warning-muted: var(--color-feedback-orange-500-56);
+   --bg-warning-softest: var(--color-feedback-orange-900);
+
+
+  /* ============================================
+   * 3. COMPONENT TOKENS (Dark Mode)
+   * ============================================ */
+
+  /* Feedback States */
+  --success: var(--color-feedback-green-500);
+  --success-foreground: var(--color-feedback-green-100);
+  --warning: var(--color-feedback-orange-500);
+  --warning-foreground: var(--color-feedback-orange-100);
+  --info: var(--color-info-500);
+  --info-foreground: var(--color-info-100);
+  --destructive: var(--color-destructive-500);
+  --destructive-foreground: var(--color-destructive-100);
+  --feature: var(--color-info-500);
+  --feature-foreground: var(--color-info-100);
+
+  /* Score Colors */
+  --score-low: hsl(350 89% 60%);
+  --score-mid: hsl(38 92% 50%);
+  --score-high: hsl(160 84% 39%);
+  --score-track: hsl(48 4% 28%);
+
+  /* Custom Scrollbar */
+  --sb-track-color: var(--color-neutral-800);
+  --sb-thumb-color: var(--color-neutral-900);
+  --sb-track-border: var(--color-neutral-800);
+
+  /* Misc */
+  --header-border: 0 0% 14.9%;
+
+  /* ============================================
+   * 4. DEPRECATED TOKENS - SHADCN (Dark Mode)
+   * ============================================ */
+
+  --background-pure: var(--color-base-black);
+  --background: var(--color-base-black);
+  --foreground: var(--color-neutral-300);
+  --card: var(--color-neutral-900);
+  --card-foreground: var(--color-neutral-300);
+  --popover: var(--color-base-black);
+  --popover-foreground: var(--color-neutral-100);
+  --primary: var(--color-base-white);
+  --primary-foreground: var(--color-base-black);
+  --secondary: var(--color-neutral-900);
+  --secondary-foreground: var(--color-neutral-300);
+  --muted: var(--color-neutral-900);
+  --muted-foreground: var(--color-neutral-100-64);
+  --accent: var(--color-neutral-800);
+  --accent-foreground: var(--color-base-white);
+  --destructive: var(
+    --color-feedback-red-500
+  ); /* Note: conflicts with semantic token above */
+  --border: var(--color-neutral-700);
+  --input: var(--color-neutral-700);
+  --ring: var(--color-brand-blue-600);
+  --chart-1: var(--color-brand-red-600);
+  --chart-2: var(--color-brand-green-600);
+  --chart-3: var(--color-brand-red-600);
+  --chart-4: var(--color-brand-blue-600);
+  --chart-5: var(--color-brand-green-600);
+  --sidebar: var(--color-neutral-900);
+  --sidebar-foreground: var(--color-base-white);
+  --sidebar-primary: var(--color-brand-red-600);
+  --sidebar-primary-foreground: var(--color-neutral-300);
+  --sidebar-accent: var(--color-neutral-700);
+  --sidebar-accent-foreground: var(--color-base-white);
+  --sidebar-border: var(--color-neutral-700);
+  --sidebar-ring: var(--color-brand-blue-600);
+}
diff --git a/src/components/AIChat/AIChatContainer.stories.tsx b/src/components/AIChat/AIChatContainer.stories.tsx
index 7f41c015..07b81943 100644
--- a/src/components/AIChat/AIChatContainer.stories.tsx
+++ b/src/components/AIChat/AIChatContainer.stories.tsx
@@ -10,9 +10,6 @@ const meta: Meta<typeof AIChatContainer> = {
   tags: ['autodocs'],
   parameters: {
     layout: 'fullscreen',
-    backgrounds: {
-      default: 'dark',
-    },
   },
   decorators: [
     (Story) => (
@@ -250,6 +247,96 @@ export const Loading: Story = {
   },
 }
 
+// Demonstrates the immediate avatar showing with loading state
+export const ImmediateLoading: Story = {
+  args: {
+    messages: [
+      {
+        id: '1',
+        role: 'user',
+        parts: [{ type: 'text', text: 'Hello, can you help me?' }],
+      },
+      {
+        id: '2',
+        role: 'assistant',
+        parts: [], // Empty parts - will show loading indicator
+      },
+    ],
+    isLoading: true,
+    onSendMessage: (message) => console.log('Sending message:', message),
+  },
+}
+
+// Interactive demo that shows the loading behavior in action
+const LoadingSimulationComponent = () => {
+  const [messages, setMessages] = useState<ChatMessage[]>([
+    {
+      id: '1',
+      role: 'user',
+      parts: [{ type: 'text', text: 'Can you explain how React hooks work?' }],
+    },
+  ])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const simulateAIResponse = async () => {
+    setIsLoading(true)
+    
+    // Step 1: Add empty assistant message immediately (shows avatar + loading dots)
+    const assistantMessage: ChatMessage = {
+      id: Date.now().toString(),
+      role: 'assistant',
+      parts: [], // Empty parts
+    }
+    setMessages((prev) => [...prev, assistantMessage])
+    
+    // Step 2: After a short delay, start "streaming" content
+    await new Promise((resolve) => setTimeout(resolve, 800))
+    
+    // Step 3: Add content to the assistant message
+    setMessages((prev) =>
+      prev.map((msg) =>
+        msg.id === assistantMessage.id
+          ? {
+              ...msg,
+              parts: [
+                {
+                  type: 'text',
+                  text: 'React hooks are functions that let you use state and lifecycle features in functional components...',
+                },
+              ],
+            }
+          : msg
+      )
+    )
+    
+    setIsLoading(false)
+  }
+
+  const handleSendMessage = (message: string) => {
+    const userMessage: ChatMessage = {
+      id: Date.now().toString(),
+      role: 'user',
+      parts: [{ type: 'text', text: message }],
+    }
+    setMessages((prev) => [...prev, userMessage])
+    
+    // Simulate the response after a brief moment
+    setTimeout(simulateAIResponse, 100)
+  }
+
+  return (
+    <AIChatContainer
+      messages={messages}
+      isLoading={isLoading}
+      onSendMessage={handleSendMessage}
+    />
+  )
+}
+
+export const LoadingSimulation: Story = {
+  render: () => <LoadingSimulationComponent />,
+}
+
 export const Customized: Story = {
   args: {
     messages: openApiEditingMessages.slice(0, 3),
diff --git a/src/components/AIChat/AIChatMessage.tsx b/src/components/AIChat/AIChatMessage.tsx
index eaf3b8b4..26f4ffba 100644
--- a/src/components/AIChat/AIChatMessage.tsx
+++ b/src/components/AIChat/AIChatMessage.tsx
@@ -19,6 +19,7 @@ export interface AIChatMessageProps {
   message: ChatMessage
   className?: string
   components?: Partial<AIChatMessageComponents>
+  isLoading?: boolean
 }
 
 interface AvatarComponents extends BaseComponents {
@@ -36,7 +37,7 @@ const defaultAvatars: DefaultComponents<AvatarComponents> = {
   user: ({ className }) => (
     <div
       className={cn(
-        'h-6 w-6 overflow-hidden rounded-full ring-1 ring-neutral-400 ring-inset',
+        'h-6 w-6 overflow-hidden rounded-full ring-1 ring-inset',
         className
       )}
     >
@@ -50,7 +51,7 @@ const defaultAvatars: DefaultComponents<AvatarComponents> = {
   assistant: ({ className }) => (
     <div
       className={cn(
-        'flex h-6 w-6 items-center justify-center rounded border border-neutral-800 bg-neutral-900 text-[10px] font-medium text-neutral-400',
+        'flex h-6 w-6 items-center justify-center rounded border text-[10px] font-medium',
         className
       )}
     >
@@ -60,7 +61,7 @@ const defaultAvatars: DefaultComponents<AvatarComponents> = {
   system: ({ className }) => (
     <svg
       xmlns="http://www.w3.org/2000/svg"
-      className={cn('h-6 w-6 text-neutral-400', className)}
+      className={cn('h-6 w-6', className)}
       fill="none"
       viewBox="0 0 24 24"
       stroke="currentColor"
@@ -79,6 +80,7 @@ export function AIChatMessage({
   message,
   className,
   components,
+  isLoading = false,
 }: AIChatMessageProps) {
   return (
     <li role="listitem" className={cn('px-4 py-3', className)}>
@@ -92,42 +94,57 @@ export function AIChatMessage({
           )}
         </div>
         <div className="flex flex-1 flex-col gap-4">
-          {message.parts.map((part, index) => {
-            switch (part.type) {
-              case 'text':
-                return <AIChatMessageTextPart key={index} text={part.text} />
-              case 'reasoning':
-                return (
-                  <AIChatMessageReasoningPart
-                    key={index}
-                    reasoning={part.reasoning}
-                  />
-                )
-              case 'tool-invocation':
-                return (
-                  <AIChatMessageToolPart
-                    key={index}
-                    toolInvocation={part.toolInvocation}
-                    components={components?.toolCall}
-                  />
-                )
-              case 'file':
-                return (
-                  <AIChatMessageFilePart
-                    key={index}
-                    mimeType={part.mimeType}
-                    data={part.data}
-                    fileName={part.fileName}
-                  />
-                )
-              case 'source':
-                return (
-                  <AIChatMessageSourcePart key={index} source={part.source} />
-                )
-              default:
-                return null
-            }
-          })}
+          {message.parts.length > 0
+            ? message.parts.map((part, index) => {
+                switch (part.type) {
+                  case 'text':
+                    return (
+                      <AIChatMessageTextPart
+                        key={index}
+                        text={part.text}
+                        isLoading={isLoading}
+                      />
+                    )
+                  case 'reasoning':
+                    return (
+                      <AIChatMessageReasoningPart
+                        key={index}
+                        reasoning={part.reasoning}
+                      />
+                    )
+                  case 'tool-invocation':
+                    return (
+                      <AIChatMessageToolPart
+                        key={index}
+                        toolInvocation={part.toolInvocation}
+                        components={components?.toolCall}
+                      />
+                    )
+                  case 'file':
+                    return (
+                      <AIChatMessageFilePart
+                        key={index}
+                        mimeType={part.mimeType}
+                        data={part.data}
+                        fileName={part.fileName}
+                      />
+                    )
+                  case 'source':
+                    return (
+                      <AIChatMessageSourcePart
+                        key={index}
+                        source={part.source}
+                      />
+                    )
+                  default:
+                    return null
+                }
+              })
+            : // Show loading state for empty assistant messages
+              isLoading &&
+              message.role === 'assistant' && (
+                <AIChatMessageTextPart text="" isLoading={true} />
+              )}
         </div>
       </div>
     </li>
diff --git a/src/components/AIChat/AIChatMessageComposer.tsx b/src/components/AIChat/AIChatMessageComposer.tsx
index ec358d05..2446207f 100644
--- a/src/components/AIChat/AIChatMessageComposer.tsx
+++ b/src/components/AIChat/AIChatMessageComposer.tsx
@@ -113,8 +113,8 @@ export function AIChatMessageComposer({
       <div className="flex flex-col">
         <div
           className={cn(
-            'flex flex-col overflow-hidden rounded-lg border border-neutral-600 transition-shadow',
-            isFocused && 'ring-1 ring-white ring-offset-1'
+            'flex flex-col overflow-hidden rounded-lg border transition-shadow',
+            isFocused && 'ring-1 ring-offset-1'
           )}
         >
           <textarea
@@ -128,7 +128,7 @@ export function AIChatMessageComposer({
             rows={1}
             className={cn(
               'max-h-[300px] min-h-[44px] w-full resize-none bg-transparent px-4 pt-3',
-              'text-neutral-50 placeholder:text-neutral-400',
+              // 'text-neutral-50 placeholder:text-neutral-400',
               'focus:outline-none',
               'text-sm'
             )}
diff --git a/src/components/AIChat/AIChatMessageList.tsx b/src/components/AIChat/AIChatMessageList.tsx
index 33c17f6e..fae12e75 100644
--- a/src/components/AIChat/AIChatMessageList.tsx
+++ b/src/components/AIChat/AIChatMessageList.tsx
@@ -12,7 +12,7 @@ export function AIChatMessageList({
   components,
   className,
 }: AIChatMessageListProps) {
-  const { messages } = useAIChat()
+  const { messages, isLoading } = useAIChat()
   const messagesEndRef = useRef<HTMLDivElement>(null)
 
   useEffect(() => {
@@ -21,11 +21,16 @@ export function AIChatMessageList({
 
   return (
     <ul role="log" className={cn('h-full overflow-y-auto', className)}>
-      {messages.map((message) => (
+      {messages.map((message, index) => (
         <AIChatMessage
           key={message.id}
           message={message}
           components={components}
+          isLoading={
+            isLoading &&
+            index === messages.length - 1 &&
+            message.role === 'assistant'
+          }
         />
       ))}
       <div ref={messagesEndRef} />
diff --git a/src/components/AIChat/AIChatModelSelector.tsx b/src/components/AIChat/AIChatModelSelector.tsx
index a711a853..94b3288c 100644
--- a/src/components/AIChat/AIChatModelSelector.tsx
+++ b/src/components/AIChat/AIChatModelSelector.tsx
@@ -97,8 +97,7 @@ export function AIChatModelSelector({
         <button
           type="button"
           className={cn(
-            'flex h-8 items-center rounded-md px-1 text-xs text-neutral-400',
-            'hover:bg-neutral-800 hover:text-neutral-200',
+            'flex h-8 items-center rounded-md px-1 text-xs',
             className
           )}
         >
@@ -132,7 +131,7 @@ export function AIChatModelSelector({
 
       <PopoverContent
         align="start"
-        className="w-[220px] rounded-[7px] border border-neutral-700 p-0 shadow-lg"
+        className="w-[220px] rounded-[7px] border p-0 shadow-lg"
         side="top"
         sideOffset={8}
       >
@@ -146,10 +145,7 @@ export function AIChatModelSelector({
                 setOpen(false)
               }}
               className={cn(
-                'flex items-center justify-between gap-2 px-5 py-2 text-xs transition-colors',
-                m.value === model
-                  ? 'bg-neutral-800 font-semibold text-white'
-                  : 'hover:bg-neutral-800 hover:text-neutral-200'
+                'flex items-center justify-between gap-2 px-5 py-2 text-xs transition-colors'
               )}
             >
               <span>{m.label}</span>
diff --git a/src/components/AIChat/parts/AIChatMessageTextPart.tsx b/src/components/AIChat/parts/AIChatMessageTextPart.tsx
index b179712e..60d34a28 100644
--- a/src/components/AIChat/parts/AIChatMessageTextPart.tsx
+++ b/src/components/AIChat/parts/AIChatMessageTextPart.tsx
@@ -5,24 +5,32 @@ import remarkGfm from 'remark-gfm'
 
 export interface AIChatMessageTextPartProps extends BasePartProps {
   text: string
+  isLoading?: boolean
 }
 
 // The line-heights here have been left as the prose defaults for now, ideally they should be adjusted to match the design system
 export function AIChatMessageTextPart({
   text,
   className,
+  isLoading = false,
 }: AIChatMessageTextPartProps) {
+  // Don't render anything when loading with no text content
+  // This just shows the avatar, which is the main goal
+  if (isLoading && !text) {
+    return null
+  }
+
   return (
     <div
       className={cn(
-        'prose prose-sm prose-zinc dark:prose-invert min-w-0 break-words',
+        'prose prose-sm dark:prose-invert min-w-0 break-words',
         'prose-headings:font-light prose-headings:tracking-[0.0015em]',
         'prose-h1:text-heading-xl',
         'prose-h2:text-heading-lg',
         'prose-h3:text-heading-md',
         'prose-h4:text-heading-sm',
         'prose-h5:text-heading-xs',
-        'prose-p:text-body prose-p:font-normal prose-p:tracking-[0.0025em]',
+        'prose-p:font-normal prose-p:tracking-[0.0025em]',
         'prose-a:text-link prose-a:font-normal prose-a:underline-offset-4 prose-a:decoration-1 prose-a:tracking-[0.0025em]',
         className
       )}
diff --git a/src/components/AIChat/parts/AIChatMessageToolPart.tsx b/src/components/AIChat/parts/AIChatMessageToolPart.tsx
index b1d3d50c..3aabc23e 100644
--- a/src/components/AIChat/parts/AIChatMessageToolPart.tsx
+++ b/src/components/AIChat/parts/AIChatMessageToolPart.tsx
@@ -44,13 +44,13 @@ export interface AIChatMessageToolPartComponents extends BaseComponents {
 }
 
 const inputResultClassName =
-  'typography-body-xs max-h-48 overflow-auto rounded bg-neutral-900 p-2 break-all whitespace-pre-wrap text-neutral-300'
+  'typography-body-xs max-h-48 overflow-auto rounded p-2 break-all whitespace-pre-wrap text-foreground bg-muted'
 
 const defaultComponents: DefaultComponents<AIChatMessageToolPartComponents> = {
   toolName: ({ toolName, confirmMessage, className }) => (
     <Text
       variant="xs"
-      className={cn('flex-1 py-1 font-medium text-neutral-100', className)}
+      className={cn('text-foreground flex-1 py-1 font-medium', className)}
     >
       {confirmMessage || toolName}
     </Text>
@@ -60,7 +60,7 @@ const defaultComponents: DefaultComponents<AIChatMessageToolPartComponents> = {
   ),
   input: ({ args, className }) => (
     <>
-      <Text variant="xs" className="mb-1 font-medium text-neutral-300">
+      <Text variant="xs" className="text-foreground mb-1 font-medium">
         Input
       </Text>
       <pre className={cn(inputResultClassName, className)}>{args}</pre>
@@ -68,7 +68,7 @@ const defaultComponents: DefaultComponents<AIChatMessageToolPartComponents> = {
   ),
   result: ({ result, className }) => (
     <>
-      <Text variant="xs" className="mb-1 font-medium text-neutral-300">
+      <Text variant="xs" className="text-foreground mb-1 font-medium">
         Result
       </Text>
       <pre className={cn(inputResultClassName, className)}>{result}</pre>
@@ -125,7 +125,7 @@ export function AIChatMessageToolPart({
     <MotionConfig transition={{ duration: 0.2 }}>
       <motion.div
         className={cn(
-          'overflow-hidden rounded-lg border border-neutral-600 transition-all duration-300',
+          'overflow-hidden rounded-lg border transition-all duration-300',
           className
         )}
         initial={false}
@@ -133,12 +133,9 @@ export function AIChatMessageToolPart({
       >
         {/* Header */}
         <div
-          className={cn(
-            'flex items-center gap-3 border-neutral-600 bg-neutral-900 px-4 py-2',
-            {
-              'border-b': isExpanded,
-            }
-          )}
+          className={cn('bg-muted flex items-center gap-3 px-4 py-2', {
+            'border-b': isExpanded,
+          })}
         >
           {/* Status Indicator */}
           <div className="relative flex h-6 w-6 items-center justify-center">
@@ -158,7 +155,7 @@ export function AIChatMessageToolPart({
               size="icon"
               variant="ghost"
               onClick={() => setIsExpanded(!isExpanded)}
-              className="h-6 w-6 text-neutral-300 hover:bg-neutral-800 hover:text-neutral-100"
+              className="h-6 w-6"
               aria-label={isExpanded ? 'Collapse' : 'Expand'}
             >
               <motion.svg
@@ -262,13 +259,13 @@ export function AIChatMessageToolPart({
 
         {/* Approve / Reject Footer */}
         {isPending && (
-          <div className="flex justify-end border-t border-neutral-600 bg-neutral-900 px-4 py-2">
+          <div className="bg-muted flex justify-end border-t px-4 py-2">
             <div className="flex items-center gap-1.5">
               <Button
                 variant="ghost"
                 size="sm"
                 onClick={toolCallApproval?.pendingToolCall?.reject}
-                className="hover:bg-background hover:text-foreground h-7 border border-transparent px-3 text-sm text-neutral-300 hover:border-neutral-600"
+                className="hover:bg-background hover:text-foreground h-7 border border-transparent px-3 text-sm"
               >
                 Reject
               </Button>
@@ -276,7 +273,7 @@ export function AIChatMessageToolPart({
               <Button
                 size="sm"
                 onClick={toolCallApproval?.pendingToolCall?.approve}
-                className="bg-foreground text-background h-7 border border-transparent px-3 text-sm hover:border-neutral-200 hover:bg-neutral-200"
+                className="bg-foreground text-background h-7 border border-transparent px-3 text-sm"
               >
                 Accept
               </Button>
@@ -302,23 +299,23 @@ const StatusIndicator = ({
     case 'success':
       return (
         <motion.div
-          className={cn(baseClassName, 'bg-success-fill', className)}
+          className={cn(baseClassName, 'bg-success', className)}
           initial={{ scale: 0.8 }}
           animate={{ scale: 1 }}
           transition={{ type: 'spring', stiffness: 500, damping: 15 }}
         >
-          <CheckIcon className="h-full w-full text-neutral-100" />
+          <CheckIcon className="h-full w-full" />
         </motion.div>
       )
     case 'error':
       return (
         <motion.div
-          className={cn(baseClassName, 'bg-danger-fill', className)}
+          className={cn(baseClassName, 'bg-destructive', className)}
           initial={{ scale: 0.8 }}
           animate={{ scale: 1 }}
           transition={{ type: 'spring', stiffness: 500, damping: 15 }}
         >
-          <XIcon className="h-full w-full text-neutral-100" />
+          <XIcon className="h-full w-full" />
         </motion.div>
       )
     case 'pending':
@@ -326,7 +323,7 @@ const StatusIndicator = ({
         <>
           {/* Track */}
           <motion.div
-            className="absolute inset-0 rounded-full bg-neutral-500/20"
+            className="absolute inset-0 rounded-full"
             initial={{ opacity: 0 }}
             animate={{ opacity: 1 }}
             transition={{ duration: 0.2 }}
@@ -339,22 +336,19 @@ const StatusIndicator = ({
             transition={{ duration: 0.2 }}
           >
             <div
-              className="h-full w-full rounded-full border-2 border-neutral-500 [border-top-color:transparent] [border-left-color:transparent]"
+              className="h-full w-full rounded-full border-2 [border-top-color:transparent] [border-left-color:transparent]"
               style={{
                 animation: 'spin 3s linear infinite',
               }}
             />
           </motion.div>
           <motion.div
-            className={cn(
-              'relative h-4 w-4 rounded-full bg-neutral-500',
-              className
-            )}
+            className={cn('relative h-4 w-4 rounded-full', className)}
             initial={{ scale: 0.8 }}
             animate={{ scale: 1 }}
             transition={{ type: 'spring', stiffness: 500, damping: 15 }}
           >
-            <UserCheck className="h-full w-full text-neutral-100" />
+            <UserCheck className="h-full w-full" />
           </motion.div>
         </>
       )
diff --git a/src/components/Badge/index.tsx b/src/components/Badge/index.tsx
index fe897c38..2f73cf07 100644
--- a/src/components/Badge/index.tsx
+++ b/src/components/Badge/index.tsx
@@ -39,9 +39,9 @@ const badgeVariants = cva<BadgeVariantsCva>(
         tertiary: 'bg-primary/10 text-primary',
         destructive: 'bg-destructive text-destructive-foreground',
         outline: 'text-foreground',
-        success: 'bg-green-600 text-green-100',
-        warning: 'bg-yellow-600 text-yellow-100',
-        danger: 'bg-red-600 text-red-100',
+        success: 'bg-success text-success-foreground',
+        warning: 'bg-warning text-warning-foreground',
+        danger: 'bg-destructive text-destructive-foreground',
       },
       size: {
         xs: 'text-[11px]',
diff --git a/src/components/Breadcrumb/index.stories.tsx b/src/components/Breadcrumb/index.stories.tsx
deleted file mode 100644
index e42a7bc2..00000000
--- a/src/components/Breadcrumb/index.stories.tsx
+++ /dev/null
@@ -1,41 +0,0 @@
-import { Icon } from '@/index'
-import { Breadcrumb } from '.'
-import { StoryObj, Meta } from '@storybook/react'
-
-const meta: Meta<typeof Breadcrumb> = {
-  component: Breadcrumb,
-  tags: ['autodocs'],
-}
-
-export default meta
-
-type Story = StoryObj<typeof Breadcrumb>
-
-export const Default: Story = {
-  args: {
-    children: [
-      <Breadcrumb.Item key="1">Home</Breadcrumb.Item>,
-      <Breadcrumb.Item key="2">Products</Breadcrumb.Item>,
-      <Breadcrumb.Item key="3">T-Shirts</Breadcrumb.Item>,
-      <Breadcrumb.Item key="4">Cotton Crewneck T-Shirt</Breadcrumb.Item>,
-      <Breadcrumb.Item key="5">Edit Details</Breadcrumb.Item>,
-    ],
-  },
-}
-
-export const WithCustomSeparator: Story = {
-  args: {
-    ...Default.args,
-    separator: <Icon name="chevron-right" />,
-  },
-}
-
-export const WithInvalidChildren: Story = {
-  args: {
-    ...Default.args,
-    children: [
-      <div key="1">Will be omitted</div>,
-      ...(Default.args?.children || []),
-    ],
-  },
-}
diff --git a/src/components/Breadcrumb/index.tsx b/src/components/Breadcrumb/index.tsx
deleted file mode 100644
index 75a6f7a5..00000000
--- a/src/components/Breadcrumb/index.tsx
+++ /dev/null
@@ -1,49 +0,0 @@
-import { cn } from '@/lib/utils'
-import { isValidElement, ReactElement, ReactNode, Children } from 'react'
-
-export interface BreadcrumbProps {
-  children: ReactElement<typeof BreadcrumbItem>[]
-  separator?: ReactNode
-  className?: string
-}
-
-const defaultSeparator = '/'
-
-const isValidBreadcrumbChild = (child: ReactElement) =>
-  isValidElement(child) && child.type === BreadcrumbItem
-
-const Breadcrumb = ({
-  children,
-  separator = defaultSeparator,
-  className,
-}: BreadcrumbProps) => {
-  const validChildren = children.filter(isValidBreadcrumbChild)
-
-  return (
-    <div className={cn('flex items-center gap-4', className)}>
-      {Children.map(validChildren, (child, index) => {
-        return (
-          <>
-            {child}
-            {index < validChildren.length - 1 && (
-              <div className="text-body-muted">{separator}</div>
-            )}
-          </>
-        )
-      })}
-    </div>
-  )
-}
-
-interface BreadcrumbItemProps {
-  children: ReactNode
-  className?: string
-}
-
-const BreadcrumbItem = ({ children, className }: BreadcrumbItemProps) => {
-  return <div className={className}>{children}</div>
-}
-
-Breadcrumb.Item = BreadcrumbItem
-
-export { Breadcrumb }
diff --git a/src/components/Card/index.stories.tsx b/src/components/Card/index.stories.tsx
index 0068fb7d..7fcfbcee 100644
--- a/src/components/Card/index.stories.tsx
+++ b/src/components/Card/index.stories.tsx
@@ -104,7 +104,7 @@ export const WithHref: Story = {
         Interact with me!
       </Card.Header>,
       <Card.Content key="content">
-        <Badge variant="secondary">Something went wrong</Badge>
+        <Badge>Something went wrong</Badge>
       </Card.Content>,
     ],
     href: '/test',
diff --git a/src/components/CodeEditorLayout/index.stories.tsx b/src/components/CodeEditorLayout/index.stories.tsx
index 0dca7e74..f143d1f5 100644
--- a/src/components/CodeEditorLayout/index.stories.tsx
+++ b/src/components/CodeEditorLayout/index.stories.tsx
@@ -1,8 +1,9 @@
-import { CodeEditor } from '.'
+import { CodeEditor, CodeEditorTabProps } from '.'
 import { Meta, StoryObj } from '@storybook/react'
 import { faker } from '@faker-js/faker'
 import { Icon } from '@/components/Icon'
 import { Key } from '../KeyHint'
+import { useState } from 'react'
 
 faker.seed(123)
 
@@ -281,17 +282,16 @@ export const TabStates: Story = {
         tabs={
           <CodeEditor.Tabs>
             <CodeEditor.Tab
-              id="active-not-dirty-and-invalid"
+              id="active"
               active
-              invalid
-              title="openapi.yml"
+              title="active.yml"
               closable
               icon={<Icon name="file" className="h-3 w-3" />}
             />
             <CodeEditor.Tab
-              id="dirty-not-active-and-invalid"
+              id="dirty-and-invalid"
               dirty
-              title="README.md"
+              title="dirty-and-invalid.md"
               icon={<Icon name="file" className="h-3 w-3" />}
               closable
             />
@@ -316,17 +316,6 @@ export const TabStates: Story = {
               icon={<Icon name="file" className="h-3 w-3" />}
               disabled
             />
-            <CodeEditor.Tab
-              id="loading"
-              title={
-                <div className="flex w-full items-center gap-1">
-                  <span>https://foo.com/file.json</span>
-                  <Icon name="loader-circle" className="h-4 w-4 animate-spin" />
-                </div>
-              }
-              disabled
-              className="cursor-progress"
-            />
           </CodeEditor.Tabs>
         }
       >
@@ -383,6 +372,7 @@ export const CustomTabElement: Story = {
   args: {
     children: [
       <CodeEditor.Pane
+        className="border"
         minSize={100}
         tabs={
           <CodeEditor.Tabs className="flex items-center">
@@ -429,3 +419,95 @@ export const CustomTabElement: Story = {
     ],
   },
 }
+
+const Stateful = () => {
+  const handleTabOpen = (id: string) => {
+    const newOpenTab = tabs.find((tab) => tab.id === id)
+
+    if (!newOpenTab) {
+      return
+    }
+
+    setTabs(
+      tabs.map((tab) =>
+        tab.id === id ? { ...tab, active: true } : { ...tab, active: false }
+      )
+    )
+  }
+
+  const handleTabClose = (id: string) => {
+    setTabs(tabs.filter((tab) => tab.id !== id))
+  }
+
+  const [tabs, setTabs] = useState<CodeEditorTabProps[]>([
+    {
+      id: 'openapi.yml',
+      active: true,
+      title: 'openapi.yml',
+    },
+    {
+      id: 'README.md',
+      title: 'README.md',
+    },
+    {
+      id: 'src/index.ts',
+      title: 'src/index.ts',
+    },
+    {
+      id: 'src/auth.ts',
+      title: 'src/auth.ts',
+    },
+  ])
+
+  return (
+    <CodeEditor className="overflow-hidden border">
+      <CodeEditor.CommandBar className="border-t border-r border-l py-2">
+        <div className="flex flex-row items-center justify-between text-sm">
+          <div className="flex items-center gap-2">
+            <Icon
+              name="circle"
+              className="h-3.5 w-3.5 rounded-full fill-red-500 stroke-red-500"
+            />
+            <Icon
+              name="circle"
+              className="h-3.5 w-3.5 rounded-full fill-yellow-500 stroke-yellow-500"
+            />
+            <Icon
+              name="circle"
+              className="h-3.5 w-3.5 rounded-full fill-green-500 stroke-green-500"
+            />
+          </div>
+        </div>
+      </CodeEditor.CommandBar>
+      <CodeEditor.Pane
+        minSize={100}
+        tabs={
+          <CodeEditor.Tabs className="flex items-center rounded-md border-t">
+            {tabs.map((tab, index) => (
+              <CodeEditor.Tab
+                key={tab.id}
+                closable
+                dirty={index % 2 === 0}
+                {...tab}
+                onClick={() => handleTabOpen(tab.id)}
+                onClose={() => handleTabClose(tab.id)}
+              />
+            ))}
+          </CodeEditor.Tabs>
+        }
+      >
+        <div className="px-2 py-1">
+          {Array.from({ length: 40 }).map((_, index) => (
+            <div key={index} className="mb-4">
+              {faker.lorem.paragraph()}
+            </div>
+          ))}
+        </div>
+      </CodeEditor.Pane>
+    </CodeEditor>
+  )
+}
+
+export const Interactive: Story = {
+  render: () => <Stateful />,
+}
diff --git a/src/components/CodeEditorLayout/index.tsx b/src/components/CodeEditorLayout/index.tsx
index 21c60061..1afe4666 100644
--- a/src/components/CodeEditorLayout/index.tsx
+++ b/src/components/CodeEditorLayout/index.tsx
@@ -17,7 +17,7 @@ import {
 } from 'react-resizable-panels'
 
 export interface CodeEditorLayoutProps {
-  children: ReactNode[]
+  children: ReactNode[] | ReactNode
   className?: string
 }
 
@@ -70,7 +70,7 @@ const CodeEditorLayout = ({ children, className }: CodeEditorLayoutProps) => {
             <>
               {pane}
 
-              <PanelResizeHandle className="bg-muted" />
+              <PanelResizeHandle className="bg-background" />
             </>
           ) : (
             pane
@@ -113,7 +113,7 @@ const CodeEditorPane = ({
       {tabs}
       <div
         className={cn(
-          'bg-background [&::-webkit-scrollbar-thumb]:bg-foreground/10 [&::-webkit-scrollbar-thumb]:hover:bg-foreground/20 [&::-webkit-scrollbar-track]:bg-card h-full flex-1 overflow-x-hidden overflow-y-scroll border',
+          'bg-background [&::-webkit-scrollbar-thumb]:bg-foreground/10 [&::-webkit-scrollbar-thumb]:hover:bg-foreground/20 [&::-webkit-scrollbar-track]:bg-card border-neutral-softest h-full flex-1 overflow-x-hidden overflow-y-scroll border',
           className
         )}
         ref={containerRef}
@@ -149,7 +149,7 @@ const CodeEditorTabs = ({
     <div
       {...props}
       className={cn(
-        'code-editor-tabs bg-background flex w-full flex-row overflow-x-scroll overflow-y-hidden border-b [&::-webkit-scrollbar]:hidden',
+        'code-editor-tabs bg-background border-neutral-softest flex w-full flex-row overflow-x-scroll overflow-y-hidden border-b [&::-webkit-scrollbar]:hidden',
         className
       )}
     >
@@ -178,6 +178,33 @@ export interface CodeEditorTabProps
    * Useful for loading states
    */
   disabled?: boolean
+
+  /**
+   * Custom styles for the tab
+   */
+  customStyles?: CodeEditorTabStateCustomStyles
+}
+
+/**
+ * Allows for custom styles to be applied to the tab based on its state
+ *
+ * @example
+ * <CodeEditor.Tab
+ *   customStyles={{
+ *     active: 'text-foreground bg-background',
+ *     inactive: 'text-body-muted bg-muted',
+ *     dirty: 'text-yellow-700/90 italic dark:text-yellow-300/70',
+ *     invalid: 'text-red-700 dark:text-red-400',
+ *     disabled: 'cursor-not-allowed opacity-75',
+ *   }}
+ * />
+ */
+type CodeEditorTabStateCustomStyles = {
+  active?: string
+  inactive?: string
+  dirty?: string
+  invalid?: string
+  disabled?: string
 }
 
 const CodeEditorTab = ({
@@ -193,6 +220,7 @@ const CodeEditorTab = ({
   onClose,
   icon,
   disabled,
+  customStyles,
   ...props
 }: CodeEditorTabProps) => {
   const [hoveredCloseIntent, setHoveredCloseIntent] = useState(false)
@@ -206,8 +234,11 @@ const CodeEditorTab = ({
     () => (
       <button
         className={cn(
-          'text-body-muted hover:text-foreground ml-auto h-full rounded-sm px-0.5',
-          hoveredCloseIntent && 'bg-background/80'
+          'text-body-muted hover:bg-muted hover:dark:bg-foreground/15 hover:text-foreground ml-auto h-full rounded-sm p-0.5',
+          hoveredCloseIntent && 'bg-background/80',
+          hoveredCloseIntent &&
+            dirty &&
+            `!bg-foreground/5 dark:!bg-foreground/10`
         )}
         onMouseEnter={() => setHoveredCloseIntent(true)}
         onMouseLeave={() => setHoveredCloseIntent(false)}
@@ -216,20 +247,28 @@ const CodeEditorTab = ({
         <Icon name="x" className="h-3.5 w-3.5" />
       </button>
     ),
-    [hoveredCloseIntent, onClose, id]
+    [hoveredCloseIntent, onClose, id, active]
   )
+
   return (
     <div
       {...props}
       className={cn(
-        'code-editor-tab bg-background hover:bg-muted/50 flex w-fit cursor-pointer items-center justify-center gap-2.5 rounded-sm rounded-t-none border-r py-2 pr-2 pl-3 text-sm select-none first-of-type:border-l-0',
-        active && 'text-foreground bg-foreground/5 hover:bg-foreground/10',
-        !active && 'text-body-muted',
+        'code-editor-tab bg-background border-neutral-softest flex w-fit cursor-pointer items-center justify-start gap-2.5 rounded-sm rounded-t-none border-r py-2 pr-2 pl-3 text-sm whitespace-nowrap select-none first-of-type:border-l-0',
         grow && 'flex-1',
-        dirty && 'italic',
-        invalid && 'text-red-700 dark:text-red-400',
+        active && 'text-foreground bg-background',
+        !active && 'text-body-muted bg-muted',
+        dirty && 'text-warning',
+        invalid && 'text-destructive-foreground dark:text-destructive',
         disabled && 'cursor-not-allowed opacity-75',
-        className
+        className,
+
+        // Override styles
+        customStyles && customStyles.active,
+        customStyles && customStyles.inactive,
+        customStyles && customStyles.dirty,
+        customStyles && customStyles.invalid,
+        customStyles && customStyles.disabled
       )}
       key={id}
       onClick={() => onClick?.(id)}
diff --git a/src/components/CodePlayground/index.tsx b/src/components/CodePlayground/index.tsx
index b032c126..0b12f1e2 100644
--- a/src/components/CodePlayground/index.tsx
+++ b/src/components/CodePlayground/index.tsx
@@ -283,7 +283,7 @@ const CodePlayground = ({
         <div className="select-none">{header && header}</div>
         <div className="ml-auto">
           <Select value={selectedLanguage} onValueChange={handleChangeLanguage}>
-            <SelectTrigger className="text-body-muted gap-1.5 !border-none !bg-transparent !p-0 !shadow-none !ring-0 select-none">
+            <SelectTrigger className="text-body gap-1.5 !border-none !bg-transparent !p-0 !shadow-none !ring-0 select-none">
               <SelectValue />
             </SelectTrigger>
             <SelectContent side="bottom" align="start" alignOffset={-30}>
diff --git a/src/components/CodePlayground/lineNumbers.tsx b/src/components/CodePlayground/lineNumbers.tsx
index 5a523fe8..2be036d3 100644
--- a/src/components/CodePlayground/lineNumbers.tsx
+++ b/src/components/CodePlayground/lineNumbers.tsx
@@ -6,7 +6,7 @@ export const lineNumbers: AnnotationHandler = {
     const { lineNumber } = props
     return (
       <div className="flex flex-row gap-2 py-0.5">
-        <div className="text-body-muted/50 pr-3 select-none">{lineNumber}</div>
+        <div className="text-body-muted pr-3 select-none">{lineNumber}</div>
         <InnerLine merge={props} className="inline-block" />
       </div>
     )
diff --git a/src/components/CodeSnippet/index.tsx b/src/components/CodeSnippet/index.tsx
index eb69cf73..ae4d24d9 100644
--- a/src/components/CodeSnippet/index.tsx
+++ b/src/components/CodeSnippet/index.tsx
@@ -1,13 +1,12 @@
 import { useCallback, useState, useEffect, useRef, useMemo } from 'react'
 import { cn } from '@/lib/utils'
 import { ProgrammingLanguage, Size } from '@/types'
-import useTailwindTheme from '@/hooks/useTailwindTheme'
+import { useTheme } from '@/hooks/useTheme'
 import { AnnotationHandler, HighlightedCode, Pre } from 'codehike/code'
 import { AnimatePresence, motion } from 'framer-motion'
 import '@/styles/codeSyntax.css'
 import './codeSnippet.css'
 import { Icon } from '../Icon'
-import { useConfig } from '@/hooks/useConfig'
 import { highlightCode, getCodeHandlers } from '@/lib/codeUtils'
 
 export interface CodeSnippetProps {
@@ -115,8 +114,7 @@ export function CodeSnippet({
     HighlightedCode | undefined
   >(undefined)
   const isMultiline = code.split('\n').length > 1
-  const { themeElement } = useConfig()
-  const theme = useTailwindTheme(themeElement)
+  const theme = useTheme()
 
   // Get the code handlers for line numbers and animations, then add custom handlers
   const preHandlers = useMemo<AnnotationHandler[]>(() => {
diff --git a/src/components/Heading/index.tsx b/src/components/Heading/index.tsx
index 41766da5..63aadb00 100644
--- a/src/components/Heading/index.tsx
+++ b/src/components/Heading/index.tsx
@@ -13,11 +13,11 @@ export interface HeadingProps {
 }
 
 const variantStyles: Record<HeadingVariant, string> = {
-  xl: 'typography-heading-xl text-heading-xl',
-  lg: 'typography-heading-lg text-heading-lg',
-  md: 'typography-heading-md text-heading-md',
-  sm: 'typography-heading-sm text-heading-sm',
-  xs: 'typography-heading-xs text-heading-xs',
+  xl: 'text-heading-xl',
+  lg: 'text-heading-lg',
+  md: 'text-heading-md',
+  sm: 'text-heading-sm',
+  xs: 'text-heading-xs',
 }
 
 const variantToElement: Record<HeadingVariant, HeadingElement> = {
diff --git a/src/components/Icon/index.tsx b/src/components/Icon/index.tsx
index ffe2d5de..b0bbbe20 100644
--- a/src/components/Icon/index.tsx
+++ b/src/components/Icon/index.tsx
@@ -1,3 +1,5 @@
+'use client'
+
 import { lazy, Suspense } from 'react'
 import { LucideProps } from 'lucide-react'
 import dynamicIconImports from 'lucide-react/dynamicIconImports'
diff --git a/src/components/Link/index.tsx b/src/components/Link/index.tsx
index 1ed197ac..5826c723 100644
--- a/src/components/Link/index.tsx
+++ b/src/components/Link/index.tsx
@@ -12,16 +12,14 @@ const linkVariants = cva(
   {
     variants: {
       variant: {
-        primary:
-          'text-link visited:text-link-visited-primary visited:hover:text-link-visited-primary',
-        secondary:
-          'text-link-secondary visited:text-link-visited-secondary visited:hover:text-link-visited-secondary',
+        primary: 'text-link-primary visited:text-link-visited',
+        secondary: 'text-link-secondary visited:text-link-visited',
       },
       size: {
-        xs: 'typography-body-xs gap-1',
-        sm: 'typography-body-sm gap-1',
-        md: 'typography-body-md gap-2',
-        lg: 'typography-body-lg gap-2',
+        xs: 'text-body-xs gap-1',
+        sm: 'text-body-sm gap-1',
+        md: 'text-body-md gap-2',
+        lg: 'text-body-lg gap-2',
       },
     },
   }
@@ -33,7 +31,7 @@ const linkTextVariants = cva(
     variants: {
       variant: {
         primary: '',
-        secondary: '[&:not(:visited)]:decoration-link-secondary/40',
+        secondary: '',
       },
       underline: {
         false: 'no-underline group-hover/link:underline',
@@ -95,7 +93,7 @@ export const Link: React.FC<LinkProps> = forwardRef<
         ref={ref}
         target={target}
         rel={rel}
-        className={cn(linkVariants({ variant, size }), className)}
+        className={cn(linkVariants({ size, variant }), className)}
         onClick={onClick}
         {...rest}
       >
diff --git a/src/components/Logo/svgs/index.tsx b/src/components/Logo/svgs/index.tsx
index 40cf3d48..fb42de60 100644
--- a/src/components/Logo/svgs/index.tsx
+++ b/src/components/Logo/svgs/index.tsx
@@ -9,7 +9,7 @@ export function Wordmark({ className, muted, ...props }: SvgProps) {
     <svg
       aria-label="Speakeasy Logo"
       xmlns="http://www.w3.org/2000/svg"
-      viewBox={`0 0 166 20`}
+      viewBox={`0 0 166 24`}
       preserveAspectRatio="xMidYMid meet"
       className={cn(
         muted ? 'text-foreground/80' : 'text-foreground dark:text-primary',
@@ -19,55 +19,62 @@ export function Wordmark({ className, muted, ...props }: SvgProps) {
     >
       <g opacity="1">
         <path
-          d="M142.736 9.10949L139.764 8.0584C138.954 7.76642 138.353 7.41606 137.963 6.9781C137.573 6.54015 137.363 5.95621 137.363 5.22628C137.363 4.40876 137.663 3.73723 138.233 3.21168C138.804 2.68613 139.584 2.42336 140.485 2.42336C141.505 2.42336 142.316 2.71533 142.916 3.29928C143.516 3.88321 143.817 4.64234 143.817 5.54744V5.83942H146.578V5.54744C146.578 4.46715 146.338 3.50365 145.828 2.65694C145.318 1.81022 144.597 1.16788 143.697 0.700728C142.766 0.233582 141.715 0 140.515 0C139.374 0 138.323 0.233582 137.423 0.700728C136.522 1.16788 135.832 1.81022 135.322 2.59854C134.811 3.41606 134.571 4.35037 134.571 5.37227C134.571 6.54015 134.901 7.56205 135.532 8.46715C136.162 9.37226 137.243 10.073 138.744 10.5985L141.385 11.5037C142.256 11.8248 142.886 12.2336 143.276 12.7007C143.697 13.1679 143.907 13.8102 143.907 14.5985C143.907 15.1533 143.757 15.6788 143.486 16.1168C143.216 16.5839 142.826 16.9343 142.316 17.1971C141.805 17.4599 141.265 17.5766 140.665 17.5766C139.674 17.5766 138.864 17.2847 138.233 16.7007C137.603 16.1168 137.303 15.3577 137.303 14.3942V14.073H134.571V14.3358C134.571 15.4453 134.811 16.4088 135.322 17.2847C135.832 18.1314 136.552 18.8029 137.483 19.2701C138.413 19.7372 139.464 19.9708 140.665 19.9708C141.865 19.9708 142.916 19.7372 143.817 19.2701C144.747 18.8029 145.438 18.1314 145.948 17.2847C146.458 16.438 146.698 15.4453 146.698 14.365C146.698 13.1679 146.398 12.0876 145.768 11.1825C145.167 10.3358 144.147 9.63504 142.736 9.10949Z"
+          d="M16.0663 19.6857L1.58654 17.6882L0.476562 18.6229L16.0663 20.7728L22.4539 15.3926L21.3453 15.2402L16.0663 19.6857Z"
           fill="currentColor"
-        ></path>
-        <path
-          d="M5.16311 8.0584L8.13489 9.10949C9.57578 9.63504 10.5964 10.3358 11.1967 11.2117C11.8271 12.1168 12.1273 13.1971 12.1273 14.3942C12.1273 15.4745 11.8872 16.4672 11.3769 17.3139C10.8665 18.1606 10.1761 18.8321 9.24557 19.2993C8.34502 19.7664 7.29439 20 6.09367 20C4.89294 20 3.84231 19.7664 2.91176 19.2993C1.98119 18.8321 1.26076 18.1606 0.750452 17.3139C0.240141 16.438 0 15.4745 0 14.365V14.1022H2.73164V14.4234C2.73164 15.3869 3.03182 16.146 3.66221 16.7299C4.29258 17.3139 5.10307 17.6058 6.09367 17.6058C6.69403 17.6058 7.23435 17.4891 7.74466 17.2263C8.25497 16.9635 8.6452 16.6131 8.91537 16.146C9.18553 15.708 9.33562 15.1825 9.33562 14.6277C9.33562 13.8394 9.15551 13.1971 8.73525 12.7299C8.34502 12.2628 7.71465 11.854 6.84412 11.5328L4.20253 10.6277C2.70163 10.1022 1.62098 9.37226 0.960582 8.49635C0.330192 7.59124 0 6.56934 0 5.40146C0 4.37956 0.240141 3.44526 0.750452 2.62774C1.26076 1.83942 1.95118 1.19708 2.85172 0.729927C3.75226 0.262772 4.80289 0.0291989 5.94358 0.0291989C7.1443 0.0291989 8.19493 0.262772 9.1255 0.700728C10.026 1.16788 10.7465 1.81022 11.2568 2.65694C11.7671 3.50365 12.0072 4.46715 12.0072 5.54744V5.83942H9.21556V5.54744C9.21556 4.64234 8.91537 3.88321 8.31501 3.29928C7.71465 2.71533 6.90416 2.42336 5.88354 2.42336C4.98299 2.42336 4.20253 2.68613 3.63218 3.21168C3.06185 3.73723 2.76167 4.40876 2.76167 5.22628C2.76167 5.95621 2.9718 6.54015 3.36203 6.9781C3.75226 7.41606 4.35262 7.76642 5.16311 8.0584Z"
-          fill="currentColor"
-        ></path>
-        <path
-          d="M128.417 13.7226L127.487 11.2701H122.714L121.783 13.7226H125.145L127.427 19.7664H129.828L129.798 17.4015L128.417 13.7226Z"
-          fill="currentColor"
-        ></path>
-        <path
-          fillRule="evenodd"
-          clipRule="evenodd"
-          d="M27.9769 1.0803C27.0463 0.583942 25.9656 0.32117 24.7349 0.32117H18.8514V19.7664H21.613V12.2336H24.6749C25.9056 12.2336 27.0163 12 27.9468 11.5037C28.9074 11.0073 29.6279 10.3066 30.1682 9.40146C30.6785 8.49635 30.9486 7.47445 30.9486 6.30657C30.9486 5.13869 30.6785 4.11679 30.1682 3.21168C29.6279 2.30657 28.9074 1.57664 27.9769 1.0803ZM27.1063 8.87591C26.4459 9.48905 25.5454 9.81022 24.4047 9.81022H21.613V2.74452H24.4047C25.5454 2.74452 26.4459 3.06569 27.1063 3.70803C27.7667 4.35037 28.0969 5.19708 28.0969 6.30657C28.0969 7.38686 27.7667 8.23358 27.1063 8.87591Z"
-          fill="currentColor"
-        ></path>
-        <path
-          d="M37.7327 19.7664V0.32117H49.74V2.74452H40.4944V8.78832H47.9089V11.2409H40.4944V17.3431H49.74V19.7664H37.7327Z"
-          fill="currentColor"
-        ></path>
+        />
         <path
-          d="M82.5797 8.78832V8.81752H79.638V0.32117H76.8763V19.7664H79.638V11.2701H82.6698L87.3226 19.7664H89.7541V18.511L84.8911 9.95621L89.7541 1.57664V0.32117H87.3226L82.5797 8.78832Z"
+          d="M16.0663 16.4252L22.4539 11.045L21.3453 10.8926L16.0663 15.3367L10.8998 14.6246L3.80372 13.6467L1.58654 13.3406L0.476563 14.2753L2.69513 14.5801L0.476562 16.4481L16.0663 18.598L22.4539 13.2192L21.3453 13.0668L16.0677 17.5123L8.68123 16.4926L9.78982 15.5593L16.0663 16.4252Z"
           fill="currentColor"
-        ></path>
+        />
         <path
-          d="M96.1479 19.7664V0.32117H108.155V2.74452H98.9096V8.78832H106.324V11.2409H98.9096V17.3431H108.155V19.7664H96.1479Z"
+          d="M16.0663 13.161L1.58654 11.1634L0.476562 12.0981L16.0663 14.248L22.4539 8.86921L21.3453 8.7168L16.0663 13.161Z"
           fill="currentColor"
-        ></path>
+        />
         <path
-          d="M159.696 8.40876L163.539 0.32117H166V1.54745L160.867 11.854V19.7664H158.105V11.9124L152.942 1.51825V0.32117H155.404L159.246 8.40876H159.696Z"
+          d="M21.3453 4.36719L19.1267 6.23522L16.0663 8.81269L10.0816 7.98725L1.58654 6.81518L0.476562 7.74987L8.97158 8.92059L7.86299 9.85528L1.58515 8.98938L0.476563 9.92406L16.0663 12.074L22.4539 6.69514L20.2353 6.38897L22.4539 4.5196L21.3453 4.36719Z"
           fill="currentColor"
-        ></path>
+        />
         <path
-          d="M68.9816 11.2701L69.9121 13.7226L71.2929 17.4015V19.7664H68.9215L66.6401 13.7226H63.2781L64.2087 11.2701H68.9816Z"
+          d="M22.4539 2.34523L6.86415 0.195312L0.476562 5.57415L16.0663 7.72542L22.4539 2.34523Z"
           fill="currentColor"
-        ></path>
+        />
+
+        {/* Text part - hidden on mobile */}
+        <g>
+          <path
+            d="M134.145 4.5619L130.755 13.5675L127.255 4.5619H124.961L129.598 16.1329L129.023 17.4425C128.86 17.831 128.719 18.1061 128.606 18.2572L128.597 18.2707C128.505 18.4244 128.384 18.5296 128.227 18.5917C128.062 18.6591 127.802 18.6928 127.455 18.6928H125.643V20.6323H128.028C128.584 20.6323 129.037 20.5447 129.377 20.372C129.719 20.198 130.008 19.9269 130.233 19.5655C130.45 19.2188 130.701 18.6955 130.978 18.009L136.439 4.56055H134.144L134.145 4.5619Z"
+            fill="currentColor"
+          />
+          <path
+            d="M122.859 9.75602C122.197 9.54697 121.339 9.37972 120.311 9.26103C119.585 9.17336 119.035 9.09109 118.674 9.01825C118.348 8.94947 118.078 8.81864 117.868 8.62846C117.666 8.44638 117.568 8.18742 117.568 7.83674C117.568 7.36198 117.787 6.99107 118.242 6.70109C118.704 6.39222 119.326 6.23577 120.088 6.23577C120.849 6.23577 121.459 6.42055 121.952 6.78606C122.445 7.15292 122.72 7.60341 122.793 8.16449L122.808 8.28318H124.96L124.949 8.13752C124.854 6.94521 124.35 6.01322 123.45 5.36987C122.573 4.7319 121.42 4.4082 120.02 4.4082C119.164 4.4082 118.38 4.56196 117.694 4.86408C117.002 5.15407 116.444 5.57353 116.033 6.11168C115.635 6.65253 115.434 7.27701 115.434 7.97027C115.434 8.74311 115.646 9.36488 116.067 9.82076C116.48 10.2524 117.025 10.5707 117.687 10.7703C118.333 10.9645 119.175 11.1237 120.186 11.2424C120.896 11.33 121.446 11.419 121.823 11.5067C122.192 11.589 122.494 11.7427 122.719 11.9599C122.944 12.177 123.045 12.4819 123.045 12.8878C123.045 13.3626 122.811 13.7403 122.33 14.0424C121.851 14.3378 121.205 14.4888 120.41 14.4888C119.513 14.4888 118.769 14.2811 118.201 13.8711C117.65 13.4624 117.368 12.9499 117.339 12.3038L117.333 12.1743H115.18V12.3106C115.198 13.5649 115.685 14.5589 116.636 15.2657C117.587 15.963 118.857 16.3164 120.41 16.3164C121.28 16.3164 122.084 16.1707 122.801 15.8834C123.523 15.5934 124.105 15.1753 124.532 14.6399C124.961 14.099 125.179 13.4651 125.179 12.7543C125.179 11.9383 124.96 11.2801 124.528 10.7973C124.115 10.3198 123.554 9.96913 122.861 9.75467L122.859 9.75602Z"
+            fill="currentColor"
+          />
+          <path
+            d="M113.81 14.0814C113.705 13.9708 113.652 13.7928 113.652 13.5554V8.65939C113.652 7.30524 113.22 6.25186 112.368 5.53297C111.536 4.80194 110.34 4.42969 108.815 4.42969C107.385 4.42969 106.202 4.75339 105.295 5.39C104.396 6.03336 103.868 6.94107 103.726 8.08617L103.708 8.23723H105.857L105.879 8.12933C105.995 7.58173 106.291 7.15822 106.785 6.83317C107.294 6.49463 107.947 6.32334 108.725 6.32334C109.604 6.32334 110.29 6.52161 110.768 6.91545C111.258 7.30793 111.497 7.84204 111.497 8.54744V9.1908H108.198C106.645 9.1908 105.436 9.50776 104.617 10.1241L104.604 10.1309C103.778 10.7634 103.359 11.682 103.359 12.8635C103.359 13.9263 103.771 14.7773 104.583 15.3964C105.399 16.0061 106.484 16.3149 107.808 16.3149C109.425 16.3149 110.706 15.7565 111.62 14.6533C111.688 15.093 111.86 15.445 112.135 15.6986C112.481 16.0182 113.053 16.1814 113.835 16.1814H115.005V14.2419H114.294C114.073 14.2419 113.915 14.1893 113.812 14.08L113.81 14.0814ZM111.495 10.9981V11.4189C111.495 12.3401 111.178 13.0928 110.554 13.6565C109.926 14.2095 109.048 14.4887 107.944 14.4887C107.199 14.4887 106.603 14.3255 106.171 14.0045C105.745 13.6876 105.538 13.2789 105.538 12.7542C105.538 12.1635 105.734 11.7346 106.135 11.4432C106.543 11.1478 107.176 10.9968 108.012 10.9968H111.495V10.9981Z"
+            fill="currentColor"
+          />
+          <path
+            d="M99.7186 5.09058C98.8768 4.65223 97.8988 4.42969 96.811 4.42969C95.7233 4.42969 94.7105 4.68325 93.852 5.18229C92.9935 5.66785 92.3114 6.3665 91.8279 7.26073C91.3612 8.15226 91.125 9.19889 91.125 10.3723C91.125 11.5457 91.3695 12.5775 91.8529 13.4852C92.3517 14.3781 93.056 15.0849 93.9465 15.5853C94.8342 16.0695 95.883 16.3149 97.0639 16.3149C98.4197 16.3149 99.5825 15.9373 100.523 15.1928C101.461 14.4334 102.055 13.4488 102.29 12.266L102.322 12.1055H100.145L100.117 12.2053C99.9284 12.8972 99.545 13.4488 98.9796 13.844C98.4253 14.2257 97.7349 14.4199 96.9277 14.4199C95.8872 14.4199 95.0328 14.0962 94.391 13.4596C93.7478 12.8203 93.4061 11.9531 93.3755 10.8821V10.8619H102.442L102.453 10.7378C102.483 10.3737 102.498 10.116 102.498 9.94475C102.468 8.83068 102.207 7.84339 101.725 7.01121C101.24 6.17633 100.566 5.53027 99.7214 5.08923L99.7186 5.09058ZM100.255 9.08155H93.5061C93.6186 8.28309 93.9826 7.62219 94.5869 7.11506C95.2301 6.57556 95.9858 6.30176 96.8347 6.30176C97.789 6.30176 98.5837 6.56072 99.1963 7.07055C99.7881 7.55206 100.144 8.22779 100.253 9.08155H100.255Z"
+            fill="currentColor"
+          />
+          <path
+            d="M91.4683 4.56429H88.8413L83.1025 10.4584V0.335938H80.9451V14.2443H79.3614C79.1405 14.2443 78.9821 14.1917 78.8793 14.0825C78.7737 13.9719 78.7209 13.7938 78.7209 13.5565V8.66046C78.7209 7.30631 78.2889 6.25293 77.4373 5.53405C76.6052 4.80302 75.4091 4.43076 73.8837 4.43076C72.4542 4.43076 71.2706 4.75446 70.3635 5.39108C69.4646 6.03443 68.9367 6.94215 68.795 8.08724L68.777 8.2383H70.9261L70.9483 8.1304C71.0636 7.58281 71.3595 7.1593 71.8541 6.83425C72.3625 6.49571 73.0155 6.32307 73.7934 6.32307C74.6728 6.32307 75.3591 6.52134 75.837 6.91517C76.3273 7.30766 76.5663 7.84042 76.5663 8.54717V9.19053H73.2669C71.7138 9.19053 70.5052 9.50748 69.6744 10.132C68.8478 10.7645 68.4297 11.683 68.4297 12.8645C68.4297 13.9274 68.8409 14.7784 69.6536 15.3975C70.469 16.0071 71.554 16.316 72.8779 16.316C74.495 16.316 75.7758 15.7576 76.6899 14.6543C76.758 15.094 76.9303 15.4447 77.2053 15.6996C77.5512 16.0193 78.1236 16.1825 78.9057 16.1825H80.9478H83.1053V13.0965L85.2877 10.8738L89.0872 16.1245L89.1289 16.1825H91.7364L86.8353 9.36182L91.4711 4.56294L91.4683 4.56429ZM71.2039 11.4443C71.6124 11.1489 72.2445 10.9979 73.0808 10.9979H76.5635V11.4187C76.5635 12.3399 76.2468 13.0925 75.623 13.6563C74.9951 14.2092 74.1171 14.4884 73.0127 14.4884C72.2681 14.4884 71.6721 14.3252 71.2401 14.0042C70.8136 13.6873 70.6066 13.2786 70.6066 12.7539C70.6066 12.1632 70.8025 11.7343 71.2039 11.4429V11.4443Z"
+            fill="currentColor"
+          />
+          <path
+            d="M64.7851 5.09058C63.9432 4.65223 62.9652 4.42969 61.8774 4.42969C60.7897 4.42969 59.777 4.68325 58.9184 5.18229C58.0585 5.66785 57.3778 6.3665 56.8943 7.26073C56.4276 8.15226 56.1914 9.19889 56.1914 10.3723C56.1914 11.5457 56.4359 12.5775 56.9194 13.4852C57.4181 14.3781 58.1224 15.0849 59.0129 15.5853C59.9006 16.0695 60.9495 16.3149 62.1289 16.3149C63.4848 16.3149 64.6489 15.9373 65.588 15.1928C66.5257 14.4334 67.1203 13.4488 67.3551 12.266L67.387 12.1055H65.2102L65.1824 12.2053C64.9934 12.8972 64.61 13.4488 64.0446 13.844C63.4903 14.2257 62.7999 14.4199 61.9927 14.4199C60.9522 14.4199 60.0979 14.0962 59.456 13.4596C58.8128 12.8203 58.4711 11.9531 58.4419 10.8821V10.8619H67.5079L67.519 10.7378C67.5496 10.3737 67.5649 10.116 67.5649 9.94475C67.5343 8.82933 67.2731 7.84339 66.7911 7.01121C66.3062 6.17633 65.6325 5.53027 64.7878 5.08923L64.7851 5.09058ZM65.3213 9.08155H58.5725C58.685 8.28309 59.049 7.62219 59.6533 7.11506C60.2965 6.57556 61.0522 6.30176 61.9011 6.30176C62.8554 6.30176 63.6501 6.56072 64.2627 7.07055C64.8545 7.55206 65.2102 8.22779 65.3199 9.08155H65.3213Z"
+            fill="currentColor"
+          />
+          <path
+            d="M52.5088 5.13644C51.6517 4.66707 50.657 4.42969 49.5526 4.42969C47.9328 4.42969 46.6158 5.02044 45.635 6.18442L45.4114 4.56321H43.5234V20.6337H45.6809V14.7301C46.0449 15.1685 46.5075 15.5313 47.059 15.8118H47.0617C47.7508 16.1477 48.5885 16.3163 49.554 16.3163C50.6445 16.3163 51.6392 16.0627 52.513 15.5637C53.3868 15.0633 54.0759 14.3565 54.5593 13.4637C55.0566 12.5721 55.3095 11.5322 55.3095 10.3737C55.3095 9.15438 55.0566 8.08482 54.5593 7.19464C54.0745 6.30041 53.3854 5.60715 52.5102 5.13778L52.5088 5.13644ZM53.1034 10.3737C53.1034 11.566 52.7533 12.5533 52.0615 13.3113C51.3891 14.049 50.4834 14.4226 49.3692 14.4226C48.6496 14.4226 47.9953 14.25 47.4257 13.9088C46.87 13.5675 46.4324 13.0847 46.1254 12.4737C45.8156 11.8425 45.6573 11.1209 45.6573 10.3292C45.6573 9.53743 45.8142 8.85361 46.124 8.25206C46.431 7.64108 46.8687 7.16497 47.4243 6.83857C47.9953 6.49733 48.6496 6.32469 49.3692 6.32469C50.4834 6.32469 51.3891 6.70639 52.0629 7.46034C52.7533 8.20216 53.1048 9.18271 53.1048 10.3737H53.1034Z"
+            fill="currentColor"
+          />
+          <path
+            d="M39.9217 9.75602C39.2591 9.54697 38.4019 9.37972 37.3739 9.26103C36.6488 9.17336 36.0972 9.09109 35.7361 9.01825C35.411 8.94947 35.1401 8.81864 34.9303 8.62846C34.7289 8.44638 34.6302 8.18742 34.6302 7.83674C34.6302 7.36198 34.8497 6.99107 35.304 6.70109C35.7666 6.39222 36.389 6.23577 37.1503 6.23577C37.9116 6.23577 38.5214 6.42055 39.0146 6.78606C39.5078 7.15157 39.7828 7.60341 39.8551 8.16449L39.8703 8.28318H42.0222L42.0111 8.13752C41.9166 6.94521 41.4124 6.01322 40.5122 5.36987C39.6356 4.7319 38.4825 4.4082 37.0822 4.4082C36.2264 4.4082 35.4429 4.56196 34.7567 4.86408C34.0648 5.15407 33.5064 5.57353 33.0952 6.11168C32.6979 6.65119 32.4964 7.27701 32.4964 7.97027C32.4964 8.74311 32.709 9.36488 33.1299 9.82076C33.5425 10.2524 34.0871 10.5707 34.7497 10.7703C35.3957 10.9645 36.2376 11.1237 37.2489 11.2424C37.9588 11.33 38.5089 11.419 38.8854 11.5067C39.2549 11.589 39.5564 11.7427 39.7814 11.9599C39.9981 12.1703 40.1079 12.4819 40.1079 12.8878C40.1079 13.3626 39.8731 13.7403 39.3924 14.0424C38.9132 14.3378 38.2672 14.4888 37.4726 14.4888C36.5751 14.4888 35.8319 14.2811 35.2637 13.8711C34.7122 13.4624 34.4302 12.9499 34.401 12.3038L34.3955 12.1743H32.2422V12.3106C32.2589 13.5649 32.7479 14.5589 33.6967 15.2657C34.6483 15.963 35.9194 16.3164 37.4712 16.3164C38.3408 16.3164 39.1452 16.1707 39.862 15.8834C40.5844 15.5934 41.1665 15.1753 41.593 14.6399C42.0222 14.099 42.2403 13.4638 42.2403 12.7543C42.2403 11.9383 42.0208 11.2801 41.5888 10.7973C41.1762 10.3198 40.615 9.96913 39.9204 9.75467L39.9217 9.75602Z"
+            fill="currentColor"
+          />
+        </g>
       </g>
-      <path
-        d="M55.2935 17.4016V19.7665H57.6949L64.1188 2.68625V0.321289H61.7473L55.2935 17.4016Z"
-        fill="currentColor"
-        transform-origin="59.70614814758301px 10.043894708156586px"
-        style={{ transform: 'none', transformOrigin: '59.7061px 10.0439px' }}
-      ></path>
-      <path
-        d="M113.8 17.4016V19.7665H116.201L122.625 2.68625V0.321289H120.254L113.8 17.4016Z"
-        fill="currentColor"
-        transform-origin="118.2125015258789px 10.043894708156586px"
-      ></path>
     </svg>
   )
 }
@@ -75,14 +82,14 @@ export function Wordmark({ className, muted, ...props }: SvgProps) {
 export function Logo({ className, muted, ...props }: SvgProps) {
   return (
     <svg
-      width={28}
-      height={48}
-      viewBox={`0 0 28 48`}
+      width={24}
+      height={24}
+      viewBox={`0 0 24 24`}
       xmlns="http://www.w3.org/2000/svg"
       preserveAspectRatio="xMidYMid meet"
       className={cn(
         muted
-          ? 'text-foreground/80 h-[48px] w-[28px]'
+          ? 'text-foreground/80 h-[24px] w-[24px]'
           : 'dark:text-primary text-black',
         className
       )}
@@ -90,19 +97,26 @@ export function Logo({ className, muted, ...props }: SvgProps) {
     >
       <g clipPath="url(#clip0)">
         <path
-          d="M0 32V26.7401L10.3548 0H16V5.43618L5.67641 32H0Z"
+          d="M16.0663 19.6857L1.58654 17.6882L0.476562 18.6229L16.0663 20.7728L22.4539 15.3926L21.3453 15.2402L16.0663 19.6857Z"
+          fill="currentColor"
+        />
+        <path
+          d="M16.0663 16.4252L22.4539 11.045L21.3453 10.8926L16.0663 15.3367L10.8998 14.6246L3.80372 13.6467L1.58654 13.3406L0.476563 14.2753L2.69513 14.5801L0.476562 16.4481L16.0663 18.598L22.4539 13.2192L21.3453 13.0668L16.0677 17.5123L8.68123 16.4926L9.78982 15.5593L16.0663 16.4252Z"
+          fill="currentColor"
+        />
+        <path
+          d="M16.0663 13.161L1.58654 11.1634L0.476562 12.0981L16.0663 14.248L22.4539 8.86921L21.3453 8.7168L16.0663 13.161Z"
+          fill="currentColor"
+        />
+        <path
+          d="M21.3453 4.36719L19.1267 6.23522L16.0663 8.81269L10.0816 7.98725L1.58654 6.81518L0.476562 7.74987L8.97158 8.92059L7.86299 9.85528L1.58515 8.98938L0.476563 9.92406L16.0663 12.074L22.4539 6.69514L20.2353 6.38897L22.4539 4.5196L21.3453 4.36719Z"
           fill="currentColor"
         />
         <path
-          d="M12 48V42.7401L22.3548 16H28V21.4362L17.6764 48H12Z"
+          d="M22.4539 2.34523L6.86415 0.195312L0.476562 5.57415L16.0663 7.72542L22.4539 2.34523Z"
           fill="currentColor"
         />
       </g>
-      <defs>
-        <clipPath id="clip0">
-          <rect width={28} height={48} fill="white" />
-        </clipPath>
-      </defs>
     </svg>
   )
 }
diff --git a/src/components/Navbar/Slim.tsx b/src/components/Navbar/Slim.tsx
index fc5509f5..3f0a8d8a 100644
--- a/src/components/Navbar/Slim.tsx
+++ b/src/components/Navbar/Slim.tsx
@@ -92,9 +92,15 @@ export const Slim = ({
           <button
             id="brand"
             onClick={onHomeNavigation}
-            className="dark:text-primary text-black"
+            className="text-primary"
           >
-            <Logo variant="icon" className="size-6 fill-current" />
+            <Logo
+              variant={expanded ? 'wordmark' : 'icon'}
+              className={cn(
+                'fill-current',
+                expanded ? 'h-6 w-[166px]' : 'size-6'
+              )}
+            />
           </button>
         </div>
         <div className="relative left-2 flex w-full flex-col gap-5">
@@ -107,7 +113,9 @@ export const Slim = ({
                       <div
                         className={cn(
                           'flex cursor-pointer items-start gap-2',
-                          item.active ? 'text-foreground' : 'text-body-muted'
+                          item.active
+                            ? 'text-foreground'
+                            : 'text-muted-foreground'
                         )}
                         onClick={() => onItemClick?.(item)}
                       >
@@ -156,7 +164,7 @@ export const Slim = ({
             <Tooltip delayDuration={0}>
               <TooltipTrigger asChild>
                 <Button variant="ghost" size="sm" onClick={onCollapse}>
-                  <Icon name="panel-left" className="text-body-muted" />
+                  <Icon name="panel-left" className="text-muted-foreground" />
                 </Button>
               </TooltipTrigger>
               <TooltipContent
diff --git a/src/components/Text/index.tsx b/src/components/Text/index.tsx
index b6cd3288..ca2cb066 100644
--- a/src/components/Text/index.tsx
+++ b/src/components/Text/index.tsx
@@ -23,10 +23,10 @@ export type TextProps = {
 )
 
 const variantStyles: Record<TextVariant, string> = {
-  lg: 'typography-body-lg',
-  md: 'typography-body-md',
-  sm: 'typography-body-sm',
-  xs: 'typography-body-xs',
+  lg: 'text-body-lg',
+  md: 'text-body-md',
+  sm: 'text-body-sm',
+  xs: 'text-body-xs',
 }
 
 const whitespaceStyles: Record<TextWhitespace, string> = {
@@ -49,7 +49,7 @@ export function Text({
       className={cn(
         variantStyles[variant],
         whitespaceStyles[whiteSpace],
-        muted ? 'text-body-muted' : 'text-body',
+        muted ? 'text-muted' : 'text-default',
         className
       )}
     >
diff --git a/src/components/Wizard/index.stories.tsx b/src/components/Wizard/index.stories.tsx
index 2ef30970..1de00334 100644
--- a/src/components/Wizard/index.stories.tsx
+++ b/src/components/Wizard/index.stories.tsx
@@ -103,7 +103,7 @@ const GetStartedHeaderContent = (
   <>
     <div className="flex items-center gap-2">
       <Heading variant="xl">Get Started</Heading>
-      <Badge variant="default">
+      <Badge>
         {completedSteps.length === steps.length
           ? 'Completed'
           : `${completedSteps.length} of ${steps.length} steps`}
diff --git a/src/components/__beta__/OperationGrouper/index.stories.tsx b/src/components/__beta__/OperationGrouper/index.stories.tsx
deleted file mode 100644
index 9109cd78..00000000
--- a/src/components/__beta__/OperationGrouper/index.stories.tsx
+++ /dev/null
@@ -1,107 +0,0 @@
-import { useState } from 'react'
-import { Group, Operation, OperationGrouper, OperationGrouperProps } from '.'
-import { StoryObj, Meta } from '@storybook/react'
-
-const meta: Meta<typeof OperationGrouper> = {
-  component: OperationGrouper,
-  parameters: {
-    chromatic: { disableSnapshot: true },
-  },
-}
-
-export default meta
-
-type Story = StoryObj<typeof OperationGrouper>
-
-const OperationGrouperWithState = ({
-  groups: initialGroups,
-}: Pick<OperationGrouperProps, 'groups'>) => {
-  const [groups, setGroups] = useState<Group[]>(initialGroups)
-
-  const handleItemMove = (
-    operation: Operation,
-    originalGroup: Group,
-    newGroup: Group
-  ) => {
-    const hasMoved = originalGroup.id !== newGroup.id
-    setGroups(
-      groups.map((group) => {
-        if (hasMoved && group.id === originalGroup.id) {
-          return {
-            ...group,
-            operations: group.operations.filter((o) => o.id !== operation.id),
-          }
-        } else if (hasMoved && group.id === newGroup.id) {
-          return {
-            ...group,
-            operations: [...group.operations, operation],
-          }
-        }
-        return group
-      })
-    )
-  }
-
-  return <OperationGrouper groups={groups} onItemMove={handleItemMove} />
-}
-
-const initialGroups: Group[] = [
-  {
-    id: '1',
-    name: 'orders',
-    color: 'rgba(229, 180, 42, 0.9)',
-    operations: [
-      {
-        id: 'a',
-        name: 'getOrders',
-        path: '$.paths.orders.get',
-      },
-      {
-        id: 'b',
-        name: 'createOrder',
-        path: '$.paths.orders.post',
-      },
-      {
-        id: 'c',
-        name: 'createOrderFulfillment',
-        path: '$.paths.orders.post.responses.200.content.application/json.schema.properties.fulfillment',
-      },
-    ],
-    path: '$.paths.orders',
-  },
-  {
-    id: '2',
-    name: 'fulfillments',
-    color: 'rgba(79, 59, 195, 0.9)',
-    operations: [
-      {
-        id: 'd',
-        name: 'getFulfillments',
-        path: '$.paths.fulfillments.get',
-      },
-    ],
-    path: '$.paths.fulfillments',
-  },
-  {
-    id: '3',
-    name: 'products',
-    color: 'rgba(100, 80, 95, 0.9)',
-    operations: [
-      {
-        id: 'e',
-        name: 'getProducts',
-        path: '$.paths.products.get',
-      },
-    ],
-    path: '$.paths.products',
-  },
-]
-
-export const Primary: Story = {
-  args: {
-    groups: initialGroups,
-  },
-  render: (args) => {
-    return <OperationGrouperWithState {...args} />
-  },
-}
diff --git a/src/components/__beta__/OperationGrouper/index.tsx b/src/components/__beta__/OperationGrouper/index.tsx
deleted file mode 100644
index 8a403489..00000000
--- a/src/components/__beta__/OperationGrouper/index.tsx
+++ /dev/null
@@ -1,234 +0,0 @@
-import { restrictToFirstScrollableAncestor } from '@dnd-kit/modifiers'
-import { Draggable, DraggableChildrenProps } from '../../DragNDrop/Draggable'
-import { DragNDropArea } from '../../DragNDrop/DragNDropArea'
-import { cn } from '@/lib/utils'
-import { Droppable } from '../../DragNDrop/Droppable'
-import { DragEndEvent, UniqueIdentifier } from '@dnd-kit/core'
-import { useCallback, useEffect, useState } from 'react'
-import { KeyHint } from '../../KeyHint'
-import { Icon } from '@/components/Icon'
-import { motion } from 'framer-motion'
-
-// TODO: move these types
-export interface Group {
-  id: UniqueIdentifier
-  name: string
-  operations: Operation[]
-  path: string
-  color: string
-}
-
-export interface Operation {
-  id: UniqueIdentifier
-  name: string
-  path: string
-}
-
-export interface OperationGrouperProps {
-  groups: Group[]
-  onItemMove: (operation: Operation, oldGroup: Group, newGroup: Group) => void
-}
-
-export function OperationGrouper({
-  groups,
-  onItemMove,
-}: OperationGrouperProps) {
-  const [showManualMode, setShowManualMode] = useState(false)
-  const handleDragEnd = useCallback(
-    (event: DragEndEvent, operation: Operation, originalGroup: Group) => {
-      const { over } = event
-      if (!over) {
-        return
-      }
-      const newGroup = groups.find(
-        (group) => group.id === over.data.current?.groupId
-      )
-      if (!newGroup) {
-        return
-      }
-      onItemMove(operation, originalGroup, newGroup)
-    },
-    [groups, onItemMove]
-  )
-
-  useEffect(() => {
-    const handleKeyDown = (event: KeyboardEvent) => {
-      event.preventDefault()
-      if (event.key === 'g' && (event.metaKey || event.ctrlKey)) {
-        setShowManualMode(true)
-      } else if (event.key === 'Escape') {
-        setShowManualMode(false)
-      }
-    }
-    window.addEventListener('keydown', handleKeyDown)
-    return () => window.removeEventListener('keydown', handleKeyDown)
-  }, [])
-
-  const calculateDragPreviewBackgroundGradient = useCallback(
-    (props: DraggableChildrenProps) => {
-      const { activeNodeRect, over, active, node, isDragging } = props
-
-      if (!isDragging) return 'transparent'
-
-      if (!activeNodeRect || !over || !active || !node) {
-        return 'transparent'
-      }
-
-      const originalGroupId = active.data.current?.groupId
-      const overGroupId = over.data.current?.groupId
-      const nextGroupId = over.data.current?.nextGroupId
-
-      const targetGroup = getGroup(overGroupId)
-      const originalGroup = getGroup(originalGroupId)
-      const nextGroup = getGroup(nextGroupId)
-
-      if (!targetGroup || !originalGroup) {
-        return 'transparent'
-      }
-
-      const activeRect = active.rect.current
-      const initialRect = activeRect?.initial
-      const translatedRect = activeRect?.translated
-      const nextGroupRect =
-        over.data.current?.groupId !== active.data.current?.groupId
-          ? over.rect
-          : undefined
-
-      if (!initialRect || !translatedRect) {
-        return 'transparent'
-      }
-
-      const withinOriginalGroup = originalGroup.id === targetGroup.id
-      const firstColor = originalGroup.color
-      const secondColor = withinOriginalGroup
-        ? nextGroup?.color
-        : targetGroup.color
-
-      if (!nextGroupRect) {
-        return `linear-gradient(
-      to bottom,
-      ${firstColor},
-      ${firstColor}
-        )`
-      }
-
-      const centerY = nextGroupRect.top + nextGroupRect.height / 2
-      const isAboveCenter = translatedRect.bottom <= centerY
-
-      const overlay = isAboveCenter
-        ? translatedRect.bottom - nextGroupRect.top
-        : nextGroupRect.bottom - translatedRect.top
-
-      // take into account height of translatedRect
-      const translatedHeight = translatedRect.bottom - translatedRect.top
-      const overlayPercentage = Math.round(
-        Math.max(0, Math.min(1, overlay / translatedHeight)) * 100
-      )
-
-      console.log('overlayPercentage', overlayPercentage)
-      let stops = `${firstColor} 0%,
-      ${firstColor} ${100 - overlayPercentage}%,
-      ${secondColor} ${100 - overlayPercentage}%,
-      ${secondColor} 100%`
-
-      if (!isAboveCenter) {
-        stops = `${secondColor} 0%,
-        ${secondColor} ${overlayPercentage}%,
-        ${firstColor} ${overlayPercentage}%,
-        ${firstColor} 100%`
-      }
-
-      // Create a gradient that transitions from oldGroupColor to newGroupColor
-      return `linear-gradient(
-        to bottom,
-        ${stops}
-      )`
-    },
-    [groups, onItemMove]
-  )
-
-  const getGroup = useCallback(
-    (groupId: UniqueIdentifier): Group | undefined => {
-      return groups.find((group) => group.id === groupId)
-    },
-    [groups]
-  )
-
-  return (
-    <DragNDropArea modifiers={[restrictToFirstScrollableAncestor]}>
-      <KeyHint
-        modifiers={!showManualMode ? ['ctrlorcommand'] : ['esc']}
-        keys={!showManualMode ? ['g'] : []}
-        className="mb-10"
-        actionText={
-          showManualMode
-            ? 'to exit manual grouping'
-            : 'to enter manual grouping'
-        }
-      />
-      <div className="flex max-w-screen-lg flex-col gap-8 overflow-y-auto">
-        {groups.map((group, index) => (
-          <Droppable
-            key={group.id}
-            id={group.id}
-            data={{
-              groupId: group.id,
-              nextGroupId: groups[index + 1]?.id,
-            }}
-          >
-            <div
-              className="flex flex-col gap-2 rounded-md border px-2 py-4 shadow-lg shadow-white/10"
-              style={{ borderColor: group.color }}
-            >
-              <h2 className="text-lg font-semibold">{group.name}</h2>
-
-              <div className="flex flex-col gap-2">
-                {group.operations.map((operation) => (
-                  <Draggable
-                    key={operation.id}
-                    id={operation.id}
-                    disabled={!showManualMode}
-                    onDragEnd={(event) => {
-                      handleDragEnd(event, operation, group)
-                    }}
-                    data={{
-                      groupId: group.id,
-                    }}
-                  >
-                    {(props) => (
-                      <motion.div
-                        className={cn(
-                          'inline-flex items-center gap-1.5 rounded-md px-2.5 py-1',
-                          showManualMode &&
-                            !props.isDragging &&
-                            'animate-wiggle border bg-gradient-to-br duration-500',
-                          props.isDragging && 'z-10',
-                          !props.isDragging && '-z-10'
-                        )}
-                        style={{
-                          backgroundImage:
-                            calculateDragPreviewBackgroundGradient(props),
-                        }}
-                      >
-                        {showManualMode && (
-                          <Icon
-                            name="grip-vertical"
-                            className={cn(
-                              'text-body-muted size-4',
-                              props.isDragging && 'text-foreground'
-                            )}
-                          />
-                        )}
-                        <div>{operation.name}</div>
-                      </motion.div>
-                    )}
-                  </Draggable>
-                ))}
-              </div>
-            </div>
-          </Droppable>
-        ))}
-      </div>
-    </DragNDropArea>
-  )
-}
diff --git a/src/components/__beta__/SelectionBox/index.stories.tsx b/src/components/__beta__/SelectionBox/index.stories.tsx
deleted file mode 100644
index 8b00dca9..00000000
--- a/src/components/__beta__/SelectionBox/index.stories.tsx
+++ /dev/null
@@ -1,98 +0,0 @@
-import { useEffect, useRef, useState } from 'react'
-import { SelectionBox } from '.'
-import { StoryObj, Meta } from '@storybook/react'
-import React from 'react'
-import { faker } from '@faker-js/faker'
-
-const meta: Meta<typeof SelectionBox> = {
-  title: 'Components/Beta/SelectionBox',
-  component: SelectionBox,
-}
-
-export default meta
-
-type Story = StoryObj<typeof SelectionBox>
-
-export const Inline: Story = {
-  render: () => {
-    const ref = useRef<HTMLDivElement>(null)
-    return (
-      <div className="flex max-w-sm flex-col gap-4">
-        <p className="inline-block w-fit pr-4 pl-2" ref={ref}>
-          Lorem ipsum dolor sit amet
-        </p>
-        <SelectionBox targetRef={ref} display="inline" />
-      </div>
-    )
-  },
-}
-
-const BlockWithState = () => {
-  const totalLines = 20
-  const transformedLineIndex = useRef(0)
-  const ancestorContainerRef = useRef<HTMLDivElement>(null)
-  const [activeIndex, setActiveIndex] = useState(-1)
-  const [allRefs, setAllRefs] = useState<
-    Map<number, React.RefObject<HTMLParagraphElement>>
-  >(new Map())
-
-  useEffect(() => {
-    if (allRefs.size !== totalLines) return
-    const interval = setInterval(() => {
-      if (activeIndex < totalLines - 1) {
-        setActiveIndex((prev) => prev + 1)
-      }
-    }, 400)
-
-    return () => clearInterval(interval)
-  }, [allRefs.size, activeIndex])
-
-  useEffect(() => {
-    for (const [index, ref] of allRefs.entries()) {
-      if (transformedLineIndex.current > index) continue
-      const element = ref.current
-      if (element && index <= activeIndex) {
-        element.innerHTML = faker.lorem.sentence({ min: 3, max: 5 })
-        transformedLineIndex.current++
-      }
-    }
-  }, [activeIndex])
-
-  return (
-    <div
-      ref={ancestorContainerRef}
-      className="h-screen/2 container m-auto flex flex-col gap-1 rounded-lg bg-zinc-900 px-6 py-4"
-    >
-      {Array.from({ length: totalLines }).map((_, index) => (
-        <p
-          key={index}
-          className="inline-block w-fit px-2"
-          ref={(el) => {
-            if (el) {
-              setAllRefs((prev) => prev.set(index, { current: el }))
-            }
-          }}
-        >
-          Lorem ipsum dolor sit amet
-        </p>
-      ))}
-      {allRefs.size > 0 && (
-        <SelectionBox
-          targetRef={allRefs.get(activeIndex)}
-          display="block"
-          ancestorContainerRef={ancestorContainerRef}
-          className="flex items-center opacity-100"
-        />
-      )}
-    </div>
-  )
-}
-
-export const Block: Story = {
-  render: () => <BlockWithState />,
-  parameters: {
-    chromatic: {
-      disableSnapshot: true,
-    },
-  },
-}
diff --git a/src/components/__beta__/SelectionBox/index.tsx b/src/components/__beta__/SelectionBox/index.tsx
deleted file mode 100644
index 1a5a37a1..00000000
--- a/src/components/__beta__/SelectionBox/index.tsx
+++ /dev/null
@@ -1,96 +0,0 @@
-import { Icon } from '@/components/Icon'
-import { cn } from '@/lib/utils'
-import React, { useCallback, useEffect, useMemo, useState } from 'react'
-
-interface SelectionBoxProps<T extends HTMLElement> {
-  targetRef: React.RefObject<T> | undefined
-  display: 'block' | 'inline'
-  ancestorContainerRef?: React.RefObject<HTMLElement>
-  className?: string
-}
-
-export const SelectionBox = <T extends HTMLElement>({
-  targetRef,
-  display = 'block',
-  ancestorContainerRef,
-  className,
-}: SelectionBoxProps<T>) => {
-  const [width, setWidth] = useState(0)
-  const [height, setHeight] = useState(0)
-  const [x, setX] = useState(0)
-  const [y, setY] = useState(0)
-
-  const recalc = useCallback(() => {
-    if (!targetRef) return
-
-    const element = targetRef.current
-    if (element) {
-      const { width, height, y, x } = element.getBoundingClientRect()
-
-      if (ancestorContainerRef?.current && display === 'block') {
-        const { width: ancestorWidth, x: ancestorX } =
-          ancestorContainerRef.current.getBoundingClientRect()
-        setWidth(ancestorWidth)
-        setX(ancestorX)
-      } else {
-        setWidth(width)
-        setY(y)
-        setX(x)
-      }
-
-      setY(y)
-      setHeight(height)
-    }
-  }, [targetRef, ancestorContainerRef, display])
-
-  useEffect(() => {
-    window.addEventListener('resize', recalc)
-    window.addEventListener('scroll', recalc)
-    window.addEventListener('orientationchange', recalc)
-
-    return () => {
-      window.removeEventListener('resize', recalc)
-      window.removeEventListener('scroll', recalc)
-      window.removeEventListener('orientationchange', recalc)
-    }
-  }, [recalc])
-
-  useEffect(() => {
-    recalc()
-  }, [recalc])
-
-  const basePositionProps: React.CSSProperties = useMemo(
-    () => ({
-      width: width,
-      height: height,
-      top: y,
-      left: x,
-    }),
-    [width, height, x, y]
-  )
-
-  const bgColorProps: React.CSSProperties = useMemo(() => {
-    return {
-      backgroundColor: 'hsl(200,100%,70%, 0.4)',
-    }
-  }, [])
-
-  return (
-    <div
-      className={cn(
-        'fixed rounded-sm border border-blue-500 box-decoration-clone py-0.5',
-        className
-      )}
-      style={{ ...basePositionProps, ...bgColorProps }}
-    >
-      <span className="absolute right-[-5px] bottom-[-5px] z-10 h-4 w-4 touch-none rounded-full border-blue-500 bg-blue-500 content-[''] select-none dark:border-blue-50 dark:bg-zinc-100">
-        <span className="flex h-full w-full items-center justify-center">
-          <Icon
-            name="loader-circle"
-            className="h-2.5 w-2.5 animate-spin text-zinc-50 dark:text-zinc-800"
-          />
-        </span>
-      </span>
-    </div>
-  )
-}
diff --git a/src/components/__beta__/Timeline/index.stories.tsx b/src/components/__beta__/Timeline/index.stories.tsx
deleted file mode 100644
index 60cd55d3..00000000
--- a/src/components/__beta__/Timeline/index.stories.tsx
+++ /dev/null
@@ -1,245 +0,0 @@
-import { Timeline } from '.'
-import { StoryObj, Meta } from '@storybook/react'
-import {
-  Children,
-  useState,
-  isValidElement,
-  PropsWithChildren,
-  useEffect,
-  useRef,
-  useCallback,
-} from 'react'
-import { IconName } from '@/components/Icon/names'
-import { faker } from '@faker-js/faker'
-import {
-  Color,
-  highlightBgMap,
-  highlightColors,
-  HighlightedText,
-  highlightFgMap,
-  mutedBgMap,
-  mutedFgMap,
-} from '../../HighlightedText'
-import { ActionBar } from '../../ActionBar'
-
-interface TimelineItem {
-  id: string
-  title: string
-  description: string
-  anchorElement: HTMLElement
-  iconName: IconName
-  color: Color
-}
-
-type TimelineWithStateProps = PropsWithChildren
-
-function stateFromChildren(children: React.ReactNode) {
-  return Children.toArray(children)
-    .map((child) => {
-      if (!isValidElement(child)) return null
-      return {
-        id: child.key as string,
-        title: child.props.title,
-        description: child.props.description,
-        anchorElement: child.props.anchorElement,
-        iconName: child.props.iconName,
-      }
-    })
-    .filter((item): item is TimelineItem => item !== null)
-}
-
-interface RangeIndices {
-  start: number
-  end: number
-}
-
-faker.seed(123)
-
-function TimelineWithState({ children }: TimelineWithStateProps) {
-  const [items, setItems] = useState<TimelineItem[]>(() =>
-    stateFromChildren(children)
-  )
-  const [pageContent, setPageContent] = useState<string[]>([])
-  const wordRefs = useRef<(HTMLSpanElement | null)[]>([])
-  const randomIndices = useRef<RangeIndices[]>([])
-  const colorIndices = useRef<number[]>([])
-  const [hoveredItem, setHoveredItem] = useState<string | null>(null)
-
-  const currentAnchorIndex = useRef<number>(0)
-  useEffect(() => {
-    setPageContent(
-      Array.from({ length: 15 }).map(() =>
-        faker.lorem.sentence({ min: 70, max: 100 })
-      )
-    )
-  }, [])
-
-  const annotateRandomWordInSentence = useCallback(
-    (sentence: string, index: number) => {
-      // Initialize random indices and color for this sentence if not already set
-      if (!randomIndices.current[index]) {
-        const words = sentence.split(' ')
-        const maxRange = Math.min(15, words.length)
-        const rangeLength = Math.floor(Math.random() * (maxRange - 1)) + 1 // Random range between 1-15 words
-        const startIndex = Math.floor(
-          Math.random() * (words.length - rangeLength)
-        )
-
-        randomIndices.current[index] = {
-          start: startIndex,
-          end: startIndex + rangeLength,
-        }
-        colorIndices.current[index] = Math.floor(
-          Math.random() * highlightColors.length
-        )
-      }
-
-      const words = sentence.split(' ')
-      const range = randomIndices.current[index]
-
-      return (
-        <p className="text-body-muted mb-6 text-sm leading-normal">
-          {/* Words before the range */}
-          {words.slice(0, range.start).map((word, i) => (
-            <span key={`before-${i}`}>{word} </span>
-          ))}
-
-          {/* Highlighted range */}
-          <span ref={(el) => (wordRefs.current[index] = el)}>
-            <HighlightedText
-              color={highlightColors[colorIndices.current[index]]}
-              muted={hoveredItem !== `highlight-${index}`}
-              className="text-primary cursor-pointer hover:scale-150"
-            >
-              {words.slice(range.start, range.end).join(' ')}
-            </HighlightedText>
-          </span>
-
-          {/* Words after the range */}
-          {words.slice(range.end).map((word, i) => (
-            <span key={`after-${i}`}> {word}</span>
-          ))}
-        </p>
-      )
-    },
-    [hoveredItem]
-  )
-
-  // Update positions based on refs
-  useEffect(() => {
-    if (!pageContent.length) return
-
-    const newHighlightedItems = pageContent
-      .map((content, index) => {
-        const words = content.split(' ')
-        const randomWord = words[randomIndices.current[index].start]
-        const ref = wordRefs.current[index]
-        if (!ref) return null
-
-        return {
-          id: `highlight-${index}`,
-          title: randomWord,
-          description: `Highlighted word from paragraph ${index + 1}`,
-          anchorElement: ref,
-          iconName:
-            index % 2 === 0
-              ? 'message-square'
-              : ('message-circle-code' as IconName),
-          color: highlightColors[colorIndices.current[index]],
-        }
-      })
-      .filter((item): item is TimelineItem => item !== null)
-
-    setItems(newHighlightedItems)
-  }, [pageContent])
-
-  return (
-    <Timeline>
-      <Timeline.Content>
-        <>
-          {pageContent.map((content, index) => (
-            <p key={index} className="text-body mb-6 text-base leading-normal">
-              {annotateRandomWordInSentence(content, index)}
-            </p>
-          ))}
-
-          <ActionBar
-            id="action-bar-1"
-            initialPosition={{ x: 50, y: 50 }}
-            draggable
-          >
-            <ActionBar.Item
-              onClick={() => {
-                currentAnchorIndex.current++
-                const anchorElement =
-                  items[currentAnchorIndex.current].anchorElement
-                if (anchorElement) {
-                  anchorElement.scrollIntoView({ behavior: 'smooth' })
-                }
-              }}
-              iconName="arrow-down"
-            >
-              Next
-            </ActionBar.Item>
-            <ActionBar.Item disabled iconName="arrow-up">
-              Previous
-            </ActionBar.Item>
-            <ActionBar.Separator />
-            <ActionBar.Item iconName="undo-2">Undo</ActionBar.Item>
-            <ActionBar.Item disabled iconName="redo-2">
-              Redo
-            </ActionBar.Item>
-            <ActionBar.Separator />
-            <ActionBar.Item iconName="activity">Activity</ActionBar.Item>
-          </ActionBar>
-        </>
-      </Timeline.Content>
-      {items.map((item) => (
-        <Timeline.Item
-          key={item.id}
-          title={item.title}
-          description={item.description}
-          iconName={item.iconName}
-          anchorElement={item.anchorElement}
-          onMouseEnter={() => {
-            setHoveredItem(item.id)
-          }}
-          onMouseLeave={() => {
-            setHoveredItem(null)
-          }}
-          style={{
-            backgroundColor:
-              hoveredItem === item.id
-                ? highlightBgMap[item.color]
-                : mutedBgMap[item.color],
-            color:
-              hoveredItem === item.id
-                ? highlightFgMap[item.color]
-                : mutedFgMap[item.color],
-          }}
-        >
-          {item.title}
-        </Timeline.Item>
-      ))}
-    </Timeline>
-  )
-}
-
-const meta: Meta<typeof Timeline> = {
-  component: Timeline,
-  tags: ['autodocs'],
-}
-
-export default meta
-
-type Story = StoryObj<typeof Timeline>
-
-export const Default: Story = {
-  args: {
-    // children will be calculated based on the page content
-    children: [],
-  },
-  render: (args) => {
-    return <TimelineWithState {...args} />
-  },
-}
diff --git a/src/components/__beta__/Timeline/index.tsx b/src/components/__beta__/Timeline/index.tsx
deleted file mode 100644
index 1a6dfcb8..00000000
--- a/src/components/__beta__/Timeline/index.tsx
+++ /dev/null
@@ -1,114 +0,0 @@
-import { Icon } from '@/components/Icon'
-import { IconName } from '@/components/Icon/names'
-import debounce from '@/lib/debounce'
-import { cn } from '@/lib/utils'
-import {
-  PropsWithChildren,
-  Children,
-  isValidElement,
-  useEffect,
-  useState,
-} from 'react'
-
-interface ItemProps extends React.HTMLAttributes<HTMLDivElement> {
-  title: string
-  description: string
-  iconName: IconName
-  className?: string
-  style?: React.CSSProperties
-  anchorElement: HTMLElement
-}
-
-function calculateNormalisedOffset(anchorElement: HTMLElement) {
-  const { top, height } = anchorElement.getBoundingClientRect()
-  return top - height / 2
-}
-
-const Item: React.FC<ItemProps> = ({
-  anchorElement,
-  iconName,
-  className,
-  style,
-  ...props
-}) => {
-  const [top, setTop] = useState(0)
-
-  const updateTop = debounce(() => {
-    if (anchorElement) {
-      const normalisedOffset = calculateNormalisedOffset(anchorElement)
-      setTop(normalisedOffset)
-    }
-  }, 10)
-
-  useEffect(() => {
-    updateTop()
-
-    window.addEventListener('resize', updateTop)
-    return () => window.removeEventListener('resize', updateTop)
-  }, [anchorElement])
-
-  return (
-    <div
-      style={{
-        top: `${top}px`,
-        ...style,
-      }}
-      {...props}
-      className={cn(
-        'bg-background absolute flex size-auto min-h-12 min-w-12 scale-[0.85] cursor-pointer items-center justify-center rounded-full border px-2 transition-transform duration-500',
-        className
-      )}
-    >
-      <Icon name={iconName} size="medium" className="h-4 w-4" />
-    </div>
-  )
-}
-Item.displayName = 'Timeline.Item'
-
-interface RootProps extends PropsWithChildren {
-  className?: string
-}
-
-export type { RootProps, ItemProps }
-
-const Root: React.FC<RootProps> = ({ children, className }) => {
-  const timelineItems = Children.toArray(children).filter((child) => {
-    if (!isValidElement(child)) return false
-    const type = child.type as { displayName?: string }
-    return type.displayName === 'Timeline.Item'
-  })
-
-  const timelineContent = Children.toArray(children).find((child) => {
-    if (!isValidElement(child)) return false
-    const type = child.type as { displayName?: string }
-    return type.displayName === 'Timeline.Content'
-  })
-
-  return (
-    <div className="flex h-svh">
-      <div className="min-h-full flex-grow">{timelineContent}</div>
-      <div
-        className={cn(
-          'absolute top-0 right-10 bottom-0 min-h-svh w-auto min-w-12 rounded-2xl',
-          className
-        )}
-      >
-        <div className="bg-mask pointer-events-none fixed top-0 bottom-0 z-10 h-full w-12"></div>
-        <div className="h-full before:fixed before:right-16 before:-z-0 before:h-full before:w-[1px] before:-translate-x-1/2 before:bg-gradient-to-b before:from-transparent before:via-zinc-200 before:to-transparent dark:before:via-zinc-700">
-          {timelineItems}
-        </div>
-      </div>
-    </div>
-  )
-}
-
-const TimelineContent = ({ children }: PropsWithChildren) => {
-  return <div className="mr-36 h-full">{children}</div>
-}
-
-TimelineContent.displayName = 'Timeline.Content'
-
-export const Timeline = Object.assign(Root, {
-  Item,
-  Content: TimelineContent,
-})
diff --git a/src/global.css b/src/global.css
index 1cfd8083..fcc49c30 100644
--- a/src/global.css
+++ b/src/global.css
@@ -1,576 +1,67 @@
+/*
+ * Global CSS - Main Entry Point
+ * 
+ * This file orchestrates the design system by:
+ * 1. Importing Tailwind and plugins
+ * 2. Defining custom variants
+ * 3. Configuring responsive utilities via @source
+ * 4. Setting theme values
+ * 5. Importing our design tokens and utilities
+ */
+
+/* ============================================
+ * CORE IMPORTS
+ * ============================================ */
 @import 'tailwindcss';
 @import 'tw-animate-css';
 @plugin "@tailwindcss/typography";
 
-@source inline("{,sm:,md:,lg:,xl:,2xl:}{p-,px-,py-,pr-,pb-,pl-,pt-}{0,0.5,1,2,3,4,5,6,8,10,12,16}");
-@source inline("{,sm:,md:,lg:,xl:,2xl:}gap-{0,0.5,1,2,3,4,5,6,8,10,12,16}");
-@source inline("{,sm:,md:,lg:,xl:,2xl:}grid-cols-{1,2,3,4,5,6,7,8,9,10,11,12}");
-@source inline("{,sm:,md:,lg:,xl:,2xl:}flex-{row,col,nowrap,wrap,wrap-reverse,none,1,auto,initial,grow,shrink}");
-@source inline("{,sm:,md:,lg:,xl:,2xl:}justify-{start,center,end,between,evenly}");
-@source inline("{,sm:,md:,lg:,xl:,2xl:}items-{start,center,end,stretch,baseline}");
-@source inline("{,sm:,md:,lg:,xl:,2xl:}col-span-{1,2,3,4,5,6,7,8,9,10,11,12}");
-@source inline("{,sm:,md:,lg:,xl:,2xl:}size-{8,12,16,24,32}");
-
+/* ============================================
+ * DESIGN SYSTEM IMPORTS
+ * Order matters: base tokens must come before utilities
+ * ============================================ */
+@import './base.css';
+@import './utilities.css';
+
+/* ============================================
+ * CUSTOM VARIANTS
+ * Define responsive and interactive variants
+ * ============================================ */
 @custom-variant dark (&:is(.dark *));
-
-/*
-  TODO: Remove all the heading !important after we remove Mui
-*/
-@utility typography-heading-xl {
-  font-size: 1.8125rem !important;
-  font-weight: 300 !important;
-  line-height: 1.517 !important;
-  letter-spacing: 0.0015em !important;
-  @variant md {
-    font-size: 2.0625rem !important;
-    line-height: 1.375 !important;
-  }
-}
-@utility typography-heading-lg {
-  font-size: 1.625rem !important;
-  font-weight: 300 !important;
-  line-height: 1.615 !important;
-  letter-spacing: 0.0015em !important;
-  @variant md {
-    font-size: 1.8125rem !important;
-    line-height: 1.517 !important;
+@custom-variant interact {
+  &:hover,
+  &:focus-visible {
+    @slot;
   }
 }
-@utility typography-heading-md {
-  font-size: 1.4375rem !important;
-  font-weight: 300 !important;
-  line-height: 1.609 !important;
-  letter-spacing: 0.0015em !important;
-  @variant md {
-    font-size: 1.625rem !important;
-    line-height: 1.615 !important;
-  }
-}
-@utility typography-heading-sm {
-  font-size: 1.25rem !important;
-  font-weight: 300 !important;
-  line-height: 1.75 !important;
-  letter-spacing: 0.0015em !important;
-
-  @variant md {
-    font-size: 1.4375rem !important;
-    line-height: 1.609 !important;
-  }
-}
-@utility typography-heading-xs {
-  font-size: 1.125rem !important;
-  font-weight: 300 !important;
-  line-height: 1.778 !important;
-  letter-spacing: 0.0015em !important;
-  @variant md {
-    font-size: 1.25rem !important;
-    line-height: 1.75 !important;
-  }
-}
-@utility typography-heading-xxs {
-  font-size: 1.125rem !important;
-  font-weight: 300 !important;
-  line-height: 1.778 !important;
-  letter-spacing: 0.0015em !important;
-}
-@utility typography-body-lg {
-  font-size: 1.125rem;
-  font-weight: 400;
-  line-height: 1.75;
-  letter-spacing: 0.0025em;
-}
-@utility typography-body-md {
-  font-size: 1rem;
-  font-weight: 400;
-  line-height: 1.75;
-  letter-spacing: 0.0025em;
-}
-@utility typography-body-sm {
-  font-size: 0.875rem;
-  font-weight: 400;
-  line-height: 1.75;
-  letter-spacing: 0.0025em;
-}
-@utility typography-body-xs {
-  font-size: 0.75rem;
-  font-weight: 400;
-  line-height: 1.75;
-  letter-spacing: 0.0025em;
-}
-
-@utility container {
-  padding-inline: 1rem;
-  margin-inline: auto;
-
-  @variant sm {
-    padding-inline: 0.5rem;
-  }
-
-  @variant md {
-    padding-inline: 1rem;
-  }
-
-  @variant lg {
-    padding-inline: 1.5rem;
-  }
-
-  @variant xl {
-    padding-inline: 2rem;
-  }
-
-  @variant 2xl {
-    padding-inline: 2.5rem;
-  }
-}
-
-@utility bg-mask {
-  background-image: linear-gradient(
-    to bottom,
-    var(--background) 0%,
-    var(--color-transparent) 5%,
-    var(--color-transparent) 95%,
-    var(--background) 100%
-  );
-}
-
-/*
-  Shadcn classes are deprecated and will be removed once we add the proper moonshine tokens
-*/
-
-:root {
-  /* Shadcn theme */
-  --radius: 0.375rem;
-
-  --background: hsl(0 0% 100%);
-  --foreground: hsl(24 10% 10%);
-  --card: hsl(0 0% 98%);
-  --card-foreground: hsl(240 10% 4%);
-  --popover: hsl(0 0% 100%);
-  --popover-foreground: hsl(240 10% 4%);
-  --primary: hsl(48 92% 47%);
-  --primary-foreground: hsl(240 6% 10%);
-  --secondary: hsl(240 6% 90%);
-  --secondary-foreground: hsl(240 6% 10%);
-  --muted: hsl(240 5% 96%);
-  --muted-foreground: hsl(240 5% 65);
-  --accent: hsl(240 6% 90%);
-  --accent-foreground: hsl(240 6% 10%);
-  --border: hsl(240 6% 90%);
-  --input: hsl(240 5% 84%);
-  --ring: hsl(217 91% 60%);
-  --chart-1: hsl(173 58% 39%);
-  --chart-2: hsl(12 76% 61%);
-  --chart-3: hsl(197 37% 24%);
-  --chart-4: hsl(43 74% 66%);
-  --chart-5: hsl(27 87% 67%);
-  --sidebar-foreground: hsl(240 5% 26%);
-  --sidebar-background: hsl(0 0% 98%);
-  --sidebar-primary: hsl(48 92% 47%);
-  --sidebar-primary-foreground: hsl(0 0% 98%);
-  --sidebar-accent: hsl(40 5% 96%);
-  --sidebar-accent-foreground: hsl(240 6% 10%);
-  --sidebar-border: hsl(240 6% 90%);
-  --sidebar-ring: hsl(240 5% 65%);
-
-  --success: hsl(161 76% 27%);
-  --success-foreground: hsl(0 0% 98%);
-
-  --destructive: hsl(345 83% 41%);
-  --destructive-foreground: hsl(0 0% 98%);
-
-  --warning: hsl(26 89% 37%);
-  --warning-foreground: hsl(0 0% 98%);
-
-  --info: hsl(206 67% 38%);
-  --info-foreground: hsl(0 0% 98%);
-
-  --feature: hsl(263 70% 50%);
-  --feature-foreground: hsl(0 0% 98%);
-
-  /* TODO: Update these once we know what these map to in terms of generic tokens */
-  --score-low: hsl(350 89% 60%);
-  --score-mid: hsl(38 92% 50%);
-  --score-high: hsl(160 84% 39%);
-  --score-track: hsl(48 4% 28%);
-
-  /* Custom easing functions */
-  --ease-in-quad: cubic-bezier(0.55, 0.085, 0.68, 0.53);
-  --ease-in-cubic: cubic-bezier(0.55, 0.055, 0.675, 0.19);
-  --ease-in-quart: cubic-bezier(0.895, 0.03, 0.685, 0.22);
-  --ease-in-quint: cubic-bezier(0.755, 0.05, 0.855, 0.06);
-  --ease-in-expo: cubic-bezier(0.95, 0.05, 0.795, 0.035);
-  --ease-in-circ: cubic-bezier(0.6, 0.04, 0.98, 0.335);
-
-  --ease-out-quad: cubic-bezier(0.25, 0.46, 0.45, 0.94);
-  --ease-out-cubic: cubic-bezier(0.215, 0.61, 0.355, 1);
-  --ease-out-quart: cubic-bezier(0.165, 0.84, 0.44, 1);
-  --ease-out-quint: cubic-bezier(0.23, 1, 0.32, 1);
-  --ease-out-expo: cubic-bezier(0.19, 1, 0.22, 1);
-  --ease-out-circ: cubic-bezier(0.075, 0.82, 0.165, 1);
-
-  --ease-in-out-quad: cubic-bezier(0.455, 0.03, 0.515, 0.955);
-  --ease-in-out-cubic: cubic-bezier(0.645, 0.045, 0.355, 1);
-  --ease-in-out-quart: cubic-bezier(0.77, 0, 0.175, 1);
-  --ease-in-out-quint: cubic-bezier(0.86, 0, 0.07, 1);
-  --ease-in-out-expo: cubic-bezier(1, 0, 0, 1);
-  --ease-in-out-circ: cubic-bezier(0.785, 0.135, 0.15, 0.86);
-
-  /* Moonshine tokens */
-  --color-accessibility: hsl(221 83% 53%);
-  --color-transparent: hsla(0 0% 0% / 0);
-
-  --color-neutral-50: hsl(240 10% 4%);
-  --color-neutral-100: hsl(240 6% 10%);
-  --color-neutral-200: hsl(240 4% 16%);
-  --color-neutral-300: hsl(240 4% 24%);
-  --color-neutral-400: hsl(240 5% 34%);
-  --color-neutral-500: hsl(240 4% 46%);
-  --color-neutral-600: hsl(240 5% 65%);
-  --color-neutral-800: hsl(240 6% 90%);
-  --color-neutral-900: hsl(240 5% 96%);
-  --color-neutral-950: hsl(0 0% 98%);
 
-  --color-brand-yellow-50: hsl(57 92% 95%);
-  --color-brand-yellow-100: hsl(58 93% 88%);
-  --color-brand-yellow-200: hsl(55 97% 77%);
-  --color-brand-yellow-300: hsl(53 96% 59%);
-  --color-brand-yellow-400: hsl(50 94% 53%);
-  --color-brand-yellow-500: hsl(48 92% 47%);
-  --color-brand-yellow-600: hsl(43 94% 40%);
-  --color-brand-yellow-700: hsl(38 90% 33%);
-  --color-brand-yellow-800: hsl(31 71% 26%);
-  --color-brand-yellow-900: hsl(29 67% 23%);
-  --color-brand-yellow-950: hsl(29 81% 14%);
+/* ============================================
+ * RESPONSIVE UTILITY SOURCES
+ * Generate utilities at different breakpoints
+ * ============================================ */
 
-  --color-base-white: hsl(0 0% 100%);
-  --color-base-black: hsl(0 0% 0%);
-
-  --color-danger-fill: hsl(345 83% 41%);
-  --color-danger-text: hsl(350 89% 60%);
-  --color-feature-fill: hsl(263 70% 50%);
-  --color-feature-text: hsl(258 90% 66%);
-  --color-information-fill: hsl(224 76% 48%);
-  --color-information-text: hsl(217 91% 60%);
-  --color-success-fill: hsl(163 94% 24%);
-  --color-success-text: hsl(160 84% 39%);
-  --color-warning-fill: hsl(26 90% 37%);
-  --color-warning-text: hsl(46 97% 65%);
-
-  --color-link-default: hsl(198 93% 60%);
-  --color-link-visited-primary: hsl(200 98% 39%);
-  --color-link-visited-secondary: hsl(240 5% 65%);
-}
-
-.dark {
-  /* Shadcn theme */
-  --radius: 0.375rem;
-
-  --background: hsl(240 10% 4%);
-  --foreground: hsl(0 0% 98%);
-  --card: hsl(240 6% 10%);
-  --card-foreground: hsl(60 9% 98%);
-  --popover: hsl(240 10% 4%);
-  --popover-foreground: hsl(0 0% 98%);
-  --primary: hsl(53 96% 59%);
-  --primary-foreground: hsl(240 6% 10%);
-  --secondary: hsl(240 4% 16%);
-  --secondary-foreground: hsl(0 0% 98%);
-  --muted: hsl(240 6% 10%);
-  --muted-foreground: hsl(240 5% 65%);
-  --accent: hsl(240 6% 10%);
-  --accent-foreground: hsl(0 0% 98%);
-  --border: hsl(240 4% 16%);
-  --input: hsl(240 4% 16%);
-  --ring: hsl(217 91% 60%);
-  --chart-1: hsl(220 70% 50%);
-  --chart-2: hsl(340 75% 55%);
-  --chart-3: hsl(30 80% 55%);
-  --chart-4: hsl(280 65% 60%);
-  --chart-5: hsl(160 60% 45%);
-  --sidebar-background: hsl(240 10% 4%);
-  --sidebar-foreground: hsl(240 5% 96%);
-  --sidebar-primary: hsl(53 96% 59%);
-  --sidebar-primary-foreground: hsl(0 0% 100%);
-  --sidebar-accent: hsl(240 6% 10%);
-  --sidebar-accent-foreground: hsl(240 5% 96%);
-  --sidebar-border: hsl(240 4% 16%);
-  --sidebar-ring: hsl(240 5% 84%);
-
-  --success: hsl(161 76% 27%);
-  --success-foreground: hsl(0 0% 98%);
-  --destructive: hsl(345 83% 41%);
-  --destructive-foreground: hsl(0 0% 98%);
-  --warning: hsl(26 89% 37%);
-  --warning-foreground: hsl(0 0% 98%);
-  --info: hsl(206 67% 38%);
-  --info-foreground: hsl(0 0% 98%);
-  --feature: hsl(263 70% 50%);
-  --feature-foreground: hsl(0 0% 98%);
-
-  /* TODO: Update these once we know what these map to in terms of generic tokens */
-  --score-low: hsl(350 89% 60%);
-  --score-mid: hsl(38 92% 50%);
-  --score-high: hsl(160 84% 39%);
-  --score-track: hsl(48 4% 28%);
-
-  /* Dark override Moonshine tokens */
-  --color-neutral-50: hsl(0 0% 98%);
-  --color-neutral-100: hsl(240 5% 96%);
-  --color-neutral-200: hsl(240 6% 90%);
-  --color-neutral-300: hsl(240 5% 84%);
-  --color-neutral-400: hsl(240 5% 65%);
-  --color-neutral-500: hsl(240 4% 46%);
-  --color-neutral-600: hsl(240 5% 34%);
-  --color-neutral-800: hsl(240 4% 16%);
-  --color-neutral-900: hsl(240 6% 10%);
-  --color-neutral-950: hsl(240 10% 4%);
-}
-
-/* Theme configuration */
-@theme inline {
-  /* Moonshine Base Colors */
-  --color-base-white: var(--color-base-white);
-  --color-base-black: var(--color-base-black);
-
-  /* Moonshine Brand Colors */
-  --color-brand-yellow-50: var(--color-brand-yellow-50);
-  --color-brand-yellow-100: var(--color-brand-yellow-100);
-  --color-brand-yellow-200: var(--color-brand-yellow-200);
-  --color-brand-yellow-300: var(--color-brand-yellow-300);
-  --color-brand-yellow-400: var(--color-brand-yellow-400);
-  --color-brand-yellow-500: var(--color-brand-yellow-500);
-  --color-brand-yellow-600: var(--color-brand-yellow-600);
-  --color-brand-yellow-700: var(--color-brand-yellow-700);
-  --color-brand-yellow-800: var(--color-brand-yellow-800);
-  --color-brand-yellow-900: var(--color-brand-yellow-900);
-  --color-brand-yellow-950: var(--color-brand-yellow-950);
-
-  /* Moonshine Neutral Colors */
-  --color-neutral-50: var(--color-neutral-50);
-  --color-neutral-100: var(--color-neutral-100);
-  --color-neutral-200: var(--color-neutral-200);
-  --color-neutral-400: var(--color-neutral-400);
-  --color-neutral-500: var(--color-neutral-500);
-  --color-neutral-600: var(--color-neutral-600);
-  --color-neutral-800: var(--color-neutral-800);
-  --color-neutral-900: var(--color-neutral-900);
-  --color-neutral-950: var(--color-neutral-950);
-
-  /* Moonshine Semantic Colors */
-  --color-danger-fill: var(--color-danger-fill);
-  --color-danger-text: var(--color-danger-text);
-  --color-feature-fill: var(--color-feature-fill);
-  --color-feature-text: var(--color-feature-text);
-  --color-information-fill: var(--color-information-fill);
-  --color-information-text: var(--color-information-text);
-  --color-success-fill: var(--color-success-fill);
-  --color-success-text: var(--color-success-text);
-  --color-warning-fill: var(--color-warning-fill);
-  --color-warning-text: var(--color-warning-text);
-
-  /* Moonshine Link Colors */
-  --color-link-default: var(--color-link-default);
-  --color-link-visited-primary: var(--color-link-visited-primary);
-  --color-link-visited-secondary: var(--color-link-visited-secondary);
-
-  /* Moonshine Accessibility */
-  --color-accessibility: var(--color-accessibility);
-  --color-transparent: var(--color-transparent);
-
-  /* Existing theme configuration */
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-
-  /* Shadcn Colors */
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-destructive: var(--destructive);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
-  --color-chart-1: var(--chart-1);
-  --color-chart-2: var(--chart-2);
-  --color-chart-3: var(--chart-3);
-  --color-chart-4: var(--chart-4);
-  --color-chart-5: var(--chart-5);
-  --color-sidebar: var(--sidebar);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-ring: var(--sidebar-ring);
-
-  /* Moonshine Alert Colors */
-  --color-success: var(--success);
-  --color-success-foreground: var(--success-foreground);
-  --color-info: var(--info);
-  --color-info-foreground: var(--info-foreground);
-  --color-warning: var(--warning);
-  --color-warning-foreground: var(--warning-foreground);
-  --color-destructive: var(--destructive);
-  --color-destructive-foreground: var(--destructive-foreground);
-  --color-feature: var(--feature);
-  --color-feature-foreground: var(--feature-foreground);
-
-  /* Moonshine Text Colors */
-  --color-heading-xl: var(--color-neutral-50);
-  --color-heading-lg: var(--color-neutral-50);
-  --color-heading-md: var(--color-neutral-50);
-  --color-heading-sm: var(--color-neutral-100);
-  --color-heading-xs: var(--color-neutral-100);
-  --color-body: var(--color-neutral-200);
-  --color-body-muted: var(--color-neutral-400);
-
-  /* Moonshine Link Colors */
-  --color-link: var(--color-link-default);
-  --color-link-secondary: var(--color-neutral-200);
-  --color-link-visited-primary: var(--color-link-visited-primary);
-  --color-link-visited-secondary: var(--color-link-visited-secondary);
-
-  /* Animation */
-  --keyframes-wiggle: {
-    0%,
-    100% {
-      transform: rotate(-1.5deg);
-    }
-    50% {
-      transform: rotate(1.5deg);
-    }
-  };
-  --animate-wiggle: wiggle 1s ease-in-out infinite;
-
-  /* Moonshine Transition Timing Functions */
-  --ease-in-out-quad: var(--ease-in-out-quad);
-  --ease-in-out-cubic: var(--ease-in-out-cubic);
-  --ease-in-out-quart: var(--ease-in-out-quart);
-  --ease-in-out-quint: var(--ease-in-out-quint);
-  --ease-in-out-expo: var(--ease-in-out-expo);
-  --ease-in-out-circ: var(--ease-in-out-circ);
-
-  --ease-in-quad: var(--ease-in-quad);
-  --ease-in-cubic: var(--ease-in-cubic);
-  --ease-in-quart: var(--ease-in-quart);
-  --ease-in-quint: var(--ease-in-quint);
-  --ease-in-expo: var(--ease-in-expo);
-  --ease-in-circ: var(--ease-in-circ);
-
-  --ease-out-quad: var(--ease-out-quad);
-  --ease-out-cubic: var(--ease-out-cubic);
-  --ease-out-quart: var(--ease-out-quart);
-  --ease-out-quint: var(--ease-out-quint);
-  --ease-out-expo: var(--ease-out-expo);
-  --ease-out-circ: var(--ease-out-circ);
-}
-
-/*
-  The default border color has changed to `currentColor` in Tailwind CSS v4,
-  so we've added these compatibility styles to make sure everything still
-  looks the same as it did with Tailwind CSS v3.
-
-  If we ever want to remove these styles, we need to add an explicit border
-  color utility to any element that depends on these defaults.
-*/
-@layer base {
-  *,
-  ::after,
-  ::before,
-  ::backdrop,
-  ::file-selector-button {
-    border-color: var(--color-gray-200, currentColor);
-  }
-
-  button:not(:disabled),
-  [role='button']:not(:disabled) {
-    cursor: pointer;
-  }
-
-  * {
-    @apply border-border;
-  }
+/* Spacing Utilities */
+@source inline("{,sm:,md:,lg:,xl:,2xl:}{p-,px-,py-,pr-,pb-,pl-,pt-}{0,0.5,1,2,3,4,5,6,8,10,12,16}");
+@source inline("{,sm:,md:,lg:,xl:,2xl:}gap-{0,0.5,1,2,3,4,5,6,8,10,12,16}");
 
-  body {
-    @apply bg-background text-foreground;
-  }
+/* Grid & Flexbox */
+@source inline("{,sm:,md:,lg:,xl:,2xl:}grid-cols-{1,2,3,4,5,6,7,8,9,10,11,12}");
+@source inline("{,sm:,md:,lg:,xl:,2xl:}col-span-{1,2,3,4,5,6,7,8,9,10,11,12}");
+@source inline("{,sm:,md:,lg:,xl:,2xl:}flex-{row,col,nowrap,wrap,wrap-reverse,none,1,auto,initial,grow,shrink}");
+@source inline("{,sm:,md:,lg:,xl:,2xl:}justify-{start,center,end,between,evenly}");
+@source inline("{,sm:,md:,lg:,xl:,2xl:}items-{start,center,end,stretch,baseline}");
 
-  :root {
-    --neutral-50-base: 0 0% 98%;
-    --neutral-100-base: 240 5% 96%;
-    --neutral-200-base: 240 6% 90%;
-    --neutral-400-base: 240 5% 65%;
-    --neutral-500-base: 240 4% 46%;
-    --neutral-600-base: 240 5% 34%;
-    --neutral-800-base: 240 4% 16%;
-    --neutral-900-base: 240 6% 10%;
-    --neutral-950-base: 240 10% 4%;
-  }
+/* Sizing */
+@source inline("{,sm:,md:,lg:,xl:,2xl:}size-{8,12,16,24,32}");
 
-  .dark {
-    --neutral-50-base: 240 10% 4%;
-    --neutral-100-base: 240 6% 10%;
-    --neutral-200-base: 240 4% 16%;
-    --neutral-400-base: 240 5% 34%;
-    --neutral-500-base: 240 4% 46%;
-    --neutral-600-base: 240 5% 65%;
-    --neutral-800-base: 240 6% 90%;
-    --neutral-900-base: 240 5% 96%;
-    --neutral-950-base: 0 0% 98%;
-  }
+/* ============================================
+ * THEME CONFIGURATION
+ * Map our custom fonts to Tailwind's theme
+ * ============================================ */
+@theme {
+  --font-sans: var(--font-diatype);
+  --font-mono: var(--font-diatype-mono);
+  --font-display: var(--font-tobias);
+  --font-ascii: var(--font-speakeasy), var(--font-diatype-mono), monospace;
 }
 
-@layer utilities {
-  .devicon-devicon-plain {
-    max-width: 2em;
-  }
-
-  /* if you want to change the original color */
-  .devicon-devicon-plain path {
-    fill: var(--primary);
-  }
-
-  @keyframes slide-fade-in {
-    from {
-      opacity: 0;
-      transform: translateX(100%);
-    }
-    to {
-      opacity: 1;
-      transform: translateX(0);
-    }
-  }
-
-  @keyframes slide-fade-out {
-    from {
-      opacity: 1;
-      transform: translateX(0);
-    }
-    to {
-      opacity: 0;
-      transform: translateX(-100%);
-    }
-  }
-
-  @keyframes spin {
-    from {
-      transform: rotate(0deg);
-    }
-    to {
-      transform: rotate(360deg);
-    }
-  }
-}
diff --git a/src/hooks/useTailwindTheme.ts b/src/hooks/useTheme.ts
similarity index 65%
rename from src/hooks/useTailwindTheme.ts
rename to src/hooks/useTheme.ts
index d8834fea..9ef34ee4 100644
--- a/src/hooks/useTailwindTheme.ts
+++ b/src/hooks/useTheme.ts
@@ -1,29 +1,31 @@
 import { useEffect, useState } from 'react'
+import { useConfig } from './useConfig'
 
 type Theme = 'dark' | 'light'
 
 /**
  * Hook to get the current theme (light or dark) from the tailwind class element.
  */
-export default function useTailwindTheme(tailwindClassElement: HTMLElement) {
+export function useTheme() {
+  const { themeElement } = useConfig()
   const [theme, setTheme] = useState<Theme>(() =>
-    tailwindClassElement.classList.contains('dark') ? 'dark' : 'light'
+    themeElement.classList.contains('dark') ? 'dark' : 'light'
   )
 
   useEffect(() => {
-    const isDark = tailwindClassElement.classList.contains('dark')
+    const isDark = themeElement.classList.contains('dark')
     setTheme(isDark ? 'dark' : 'light')
 
     const observer = new MutationObserver((mutations) => {
       mutations.forEach((mutation) => {
         if (mutation.attributeName === 'class') {
-          const isDark = tailwindClassElement.classList.contains('dark')
+          const isDark = themeElement.classList.contains('dark')
           setTheme(isDark ? 'dark' : 'light')
         }
       })
     })
 
-    observer.observe(tailwindClassElement, {
+    observer.observe(themeElement, {
       attributes: true,
       attributeFilter: ['class'],
     })
diff --git a/src/index.ts b/src/index.ts
index e86b97ee..a908f8a8 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -23,7 +23,6 @@ export {
 } from '@/components/TargetLanguageIcon'
 export { UserAvatar, type UserAvatarProps } from '@/components/UserAvatar'
 export { Subnav, type SubnavItem, type SubnavProps } from '@/components/Subnav'
-export { Breadcrumb, type BreadcrumbProps } from '@/components/Breadcrumb'
 export { CodeSnippet, type CodeSnippetProps } from '@/components/CodeSnippet'
 export {
   LoggedInUserMenu,
@@ -48,6 +47,8 @@ export {
   type MoonshineConfigProviderProps,
 } from '@/context/ConfigContext'
 export { useConfig as useMoonshineConfig } from '@/hooks/useConfig'
+export { useTheme as useMoonshineTheme } from '@/hooks/useTheme'
+export { default as useTailwindBreakpoint } from '@/hooks/useTailwindBreakpoint'
 export {
   GradientCircle,
   type GradientCircleProps,
@@ -67,7 +68,7 @@ export {
   isSupportedLanguage,
 } from '@/types'
 export { PageHeader, type PageHeaderProps } from '@/components/PageHeader'
-export { default as useTailwindBreakpoint } from '@/hooks/useTailwindBreakpoint'
+
 export { ExternalPill, type ExternalPillProps } from '@/components/ExternalPill'
 export {
   LanguageIndicator,
@@ -173,17 +174,15 @@ export {
   DropdownMenuShortcut,
 } from '@/components/Dropdown'
 
+export { cn } from '@/lib/utils'
+
 /** START BETA COMPONENTS */
 import { CLIWizard } from '@/components/__beta__/CLIWizard'
-import { Timeline } from '@/components/__beta__/Timeline'
 
 export const beta = {
   // TODO: This component is not yet reusable, it's only for use on the SDK Overview page right now
   // TODO: needs light mode tweaks too.
   CLIWizard,
-
-  // Readme editor components
-  Timeline,
 }
 // DO NOT USE: EXPORTED TO UNBLOCK GRAM
 export {
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
index 13391d94..7d0c567b 100644
--- a/src/lib/utils.ts
+++ b/src/lib/utils.ts
@@ -1,10 +1,30 @@
 import { Breakpoint, ResponsiveValue } from '@/types'
 import { clsx, type ClassValue } from 'clsx'
-import { twMerge } from 'tailwind-merge'
+import { extendTailwindMerge } from 'tailwind-merge'
 import { isResponsiveValueObject } from './typeUtils'
 
+const customTwMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      'font-size': [
+        {
+          text: [
+            (value: string) =>
+              ['heading', 'body', 'codeline', 'display'].some((element) =>
+                value.includes(element)
+              ) &&
+              ['xs', 'sm', 'md', 'lg', 'xl', '2xl'].some((element) =>
+                value.includes(element)
+              ),
+          ],
+        },
+      ],
+    },
+  },
+})
+
 export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs))
+  return customTwMerge(clsx(inputs))
 }
 
 /**
diff --git a/src/utilities.css b/src/utilities.css
new file mode 100644
index 00000000..af13a023
--- /dev/null
+++ b/src/utilities.css
@@ -0,0 +1,1062 @@
+/*
+ * Utilities CSS - Exposed Tailwind Utilities
+ * These are the utilities that are exposed as Tailwind classes.
+ * They reference the primitives defined in base.css
+ */
+
+/*
+  TODO: rename to text-*
+  TODO: replace these with the ones for the new brand
+  TODO: Delete all typography classes https://linear.app/speakeasy/issue/DES-325/replace-all-references-to-typography-classes
+*/
+@utility typography-heading-xl {
+  font-size: 2.063rem;
+  font-weight: 300;
+  line-height: 1.375;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+@utility typography-heading-lg {
+  font-size: 1.813rem;
+  font-weight: 300;
+  line-height: 1.5;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+@utility typography-heading-md {
+  font-size: 1.625rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+@utility typography-heading-sm {
+  font-size: 1.438rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+@utility typography-heading-xs {
+  font-size: 1.25rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+@utility typography-heading-xxs {
+  font-size: 1.125rem;
+  font-weight: 300;
+  line-height: 1.778;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+}
+@utility typography-body-lg {
+  font-size: 1.125rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+}
+@utility typography-body-md {
+  font-size: 1rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+}
+@utility typography-body-sm {
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+}
+@utility typography-body-xs {
+  font-size: 0.75rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+}
+
+@utility container {
+  padding-inline: 1rem;
+  margin-inline: auto;
+
+  @variant sm {
+    padding-inline: 0.5rem;
+  }
+
+  @variant md {
+    padding-inline: 1rem;
+  }
+
+  @variant lg {
+    padding-inline: 1.5rem;
+  }
+
+  @variant xl {
+    padding-inline: 2rem;
+  }
+
+  @variant 2xl {
+    padding-inline: 2.5rem;
+  }
+}
+
+@utility bg-mask {
+  background-image: linear-gradient(
+    to bottom,
+    var(--background) 0%,
+    var(--color-transparent) 5%,
+    var(--color-transparent) 95%,
+    var(--background) 100%
+  );
+}
+
+/* Display Typography */
+
+/* This token name is not final */
+@utility text-display-2xl {
+  font-size: 11.375rem; /* 182px */
+  font-weight: 100;
+  line-height: 1;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+
+@utility text-display-xl {
+  font-size: 5.625rem;
+  font-weight: 100;
+  line-height: 1.1;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+
+@utility text-display-lg {
+  font-size: 4.188rem;
+  font-weight: 100;
+  line-height: 1.2;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+
+@utility text-display-md {
+  font-size: 3.188rem;
+  font-weight: 100;
+  line-height: 1.3;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+
+@utility text-display-sm {
+  font-size: 2.375rem;
+  font-weight: 100;
+  line-height: 1.375;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+
+@utility text-display-xs {
+  font-size: 1.75rem;
+  font-weight: 100;
+  line-height: 1.4;
+  letter-spacing: -0.04em;
+  font-family: var(--font-tobias);
+  color: var(--text-display);
+}
+
+/* Heading */
+@utility text-heading-xl {
+  font-size: 2.063rem;
+  font-weight: 300;
+  line-height: 1.375;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+  color: var(--text-heading-xl);
+}
+@utility text-heading-lg {
+  font-size: 1.813rem;
+  font-weight: 300;
+  line-height: 1.5;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+  color: var(--text-heading-lg);
+}
+@utility text-heading-md {
+  font-size: 1.625rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+  color: var(--text-heading-md);
+}
+@utility text-heading-sm {
+  font-size: 1.438rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+  color: var(--text-heading-sm);
+}
+@utility text-heading-xs {
+  font-size: 1.25rem;
+  font-weight: 300;
+  line-height: 1.6;
+  letter-spacing: 0.0015em;
+  font-family: var(--font-diatype);
+  color: var(--text-heading-xs);
+}
+
+/* Body */
+@utility text-body-lg {
+  font-size: 1.125rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+  color: var(--text-default);
+}
+@utility text-body-md {
+  font-size: 1rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+  color: var(--text-default);
+}
+@utility text-body-sm {
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+  color: var(--text-default);
+}
+@utility text-body-xs {
+  font-size: 0.75rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+  color: var(--text-default);
+}
+
+/* Code */
+@utility text-codeline-md {
+  font-size: 1rem;
+  font-weight: 300;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype-mono);
+  color: var(--text-default);
+}
+@utility text-codeline-sm {
+  font-size: 0.875rem;
+  font-weight: 300;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype-mono);
+  color: var(--text-default);
+}
+@utility text-codeline-xs {
+  font-size: 0.75rem;
+  font-weight: 300;
+  line-height: 1.7;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype-mono);
+  color: var(--text-default);
+}
+
+/* Buttons */
+@utility text-button-md {
+  font-size: 1rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+  color: var(--text-default);
+}
+@utility text-button-sm {
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+  color: var(--text-default);
+}
+@utility text-button-xs {
+  font-size: 0.75rem;
+  font-weight: 400;
+  line-height: 1.75;
+  letter-spacing: 0.0025em;
+  font-family: var(--font-diatype);
+  color: var(--text-default);
+}
+
+/* Text colors */
+
+/* Body */
+@utility text-hightlight {
+  color: var(--text-highlight);
+}
+
+@utility text-text-default {
+  color: var(--text-default);
+}
+
+@utility text-muted {
+  color: var(--text-muted)!important;
+}
+
+@utility text-placeholder {
+  color: var(--text-placeholder);
+}
+
+@utility text-disabled {
+  color: var(--text-disabled);
+}
+
+/* onColor / Dark */
+@utility text-dark-light-highlight {
+  color: var(--text-dark-light-highlight);
+}
+
+@utility text-dark-light-default {
+  color: var(--text-dark-light-default);
+}
+
+@utility text-dark-light-muted {
+  color: var(--text-dark-light-muted);
+}
+
+/*  onColor / Light */
+@utility text-light-dark-highlight {
+  color: var(--text-light-dark-highlight);
+}
+
+@utility text-light-dark-default {
+  color: var(--text-light-dark-default);
+}
+
+@utility text-light-dark-muted {
+  color: var(--text-light-dark-muted);
+}
+
+/* Link colors */
+@utility text-link-primary {
+  color: var(--text-link-primary);
+}
+
+@utility text-link-secondary {
+  color: var(--text-link-secondary);
+}
+
+@utility text-link-visited {
+  color: var(--text-link-visited);
+}
+
+/* Destructive */
+@utility text-default-destructive {
+  color: var(--text-default-destructive);
+}
+
+@utility text-link-destructive {
+  color: var(--text-link-destructive);
+}
+
+/* Information */
+@utility text-default-information {
+  color: var(--text-default-information);
+}
+
+@utility text-link-information {
+  color: var(--text-link-information);
+}
+
+/* Success */
+@utility text-default-success {
+  color: var(--text-default-success);
+}
+
+@utility text-link-success {
+  color: var(--text-link-success);
+}
+
+/* Warning */
+@utility text-default-warning {
+  color: var(--text-default-warning);
+}
+
+@utility text-link-warning {
+  color: var(--text-link-warning);
+}
+
+
+@utility bg-gradient-primary {
+  background: var(--gradient-brand-primary);
+}
+
+@utility border-gradient-primary {
+  border-image: var(--gradient-brand-primary) 1;
+}
+
+@utility bg-surface-primary {
+  background-color: var(--color-base-white);
+
+  @variant dark {
+    background-color: var(--color-base-black);
+  }
+}
+
+@utility bg-surface-secondary {
+  background-color: var(--color-neutral-100);
+}
+
+@utility bg-warning {
+  background-color: var(--bg-warning);
+}
+
+@utility text-warning {
+  color: var(--text-warning) !important;
+}
+
+@utility border-warning {
+  border-color: var(--border-warning);
+  border-width: 1px;
+  border-style: solid;
+}
+
+
+/* Link underline utilities */
+@utility underline-link-primary {
+  color: var(--underline-link-primary);
+  text-decoration: underline;
+  text-underline-offset: 0.125rem;
+}
+
+@utility underline-link-secondary {
+  color: var(--underline-link-secondary);
+  text-decoration: underline;
+  text-underline-offset: 0.125rem;
+}
+
+@utility underline-link-visited {
+  color: var(--underline-link-visited);
+  text-decoration: underline;
+  text-underline-offset: 0.125rem;
+}
+
+/* ======================================
+* BORDERS
+* ======================================= */
+
+/* Border utilities for neutral colors */
+@utility border-neutral-active {
+  border-color: var(--border-neutral-active);
+}
+
+@utility border-neutral-hover {
+  border-color: var(--border-neutral-hover);
+}
+
+@utility border-neutral-default {
+  border-color: var(--border-neutral-default);
+}
+
+@utility border-neutral-disabled {
+  border-color: var(--border-neutral-disabled);
+  opacity: 0.4;
+}
+
+@utility border-neutral-softest {
+  border-color: var(--border-neutral-softest);
+}
+
+@utility border-neutral-inset {
+  border-color: var(--border-neutral-inset);
+}
+
+@utility border-neutral-alpha {
+  border-color: var(--border-neutral-alpha);
+}
+
+/* Destructive border utilities */
+@utility border-destructive-highlight {
+  border-color: var(--border-destructive-highlight);
+}
+
+@utility border-destructive-default {
+  border-color: var(--border-destructive-default);
+}
+
+@utility border-destructive-muted {
+  border-color: var(--border-destructive-muted);
+}
+
+@utility border-destructive-softest {
+  border-color: var(--border-destructive-softest);
+}
+
+/* Information Border utilities */
+@utility border-information-highlight {
+  border-color: var(--border-information-highlight);
+}
+
+@utility border-information-default {
+  border-color: var(--border-information-default);
+}
+
+@utility border-information-muted {
+  border-color: var(--border-information-muted);
+}
+
+@utility border-information-softest {
+  border-color: var(--border-information-softest);
+}
+
+/* Success Border utilities */
+@utility border-success-highlight {
+  border-color: var(--border-success-highlight);
+}
+
+@utility border-success-default {
+  border-color: var(--border-success-default);
+}
+
+@utility border-success-muted {
+  border-color: var(--border-success-muted);
+}
+
+@utility border-success-softest {
+  border-color: var(--border-success-softest);
+}
+
+/* Warning Border utilities */
+@utility border-warning-highlight {
+  border-color: var(--border-warning-highlight);
+}
+
+@utility border-warning-default {
+  border-color: var(--border-warning-default);
+}
+
+@utility border-warning-muted {
+  border-color: var(--border-warning-muted);
+}
+
+@utility border-warning-softest {
+  border-color: var(--border-warning-softest);
+}
+
+/* Focus Border utilities */
+@utility border-focus {
+  border-color: var(--border-focus);
+}
+
+/* =============================
+*  FILLS
+*  ============================*/
+
+/* Neutrals */
+@utility fill-neutral-highlight {
+  fill: var(--fill-neutral-highlight);
+}
+
+@utility fill-neutral-active {
+  fill: var(--fill-neutral-active);
+}
+
+@utility fill-neutral-default {
+  fill: var(--fill-neutral-default);
+}
+
+@utility fill-neutral-muted {
+  fill: var(--fill-neutral-muted);
+}
+
+/* onColor / Dark */
+@utility fill-onColor-dark-highlight {
+  fill: var(--fill-onColor-dark-highlight);
+}
+
+@utility fill-onColor-dark-default {
+  fill: var(--fill-onColor-dark-default);
+}
+
+@utility fill-onColor-dark-muted {
+  fill: var(--fill-onColor-dark-muted);
+}
+
+/* onColor / Light */
+@utility fill-onColor-light-highlight {
+  fill: var(--fill-onColor-light-highlight);
+}
+
+@utility fill-onColor-light-default {
+  fill: var(--fill-onColor-light-default);
+}
+
+@utility fill-onColor-light-muted {
+  fill: var(--fill-onColor-light-muted);
+}
+
+/* Link Fill */
+@utility fill-link-primary {
+  fill: var(--fill-link-primary);
+}
+
+@utility fill-link-secondary {
+  fill: var(--fill-link-secondary);
+}
+
+@utility fill-link-visited {
+  fill: var(--fill-link-visited);
+}
+
+/* Destructive Fill */
+@utility fill-destructive-highlight {
+  fill: var(--fill-destructive-highlight);
+}
+
+@utility fill-destructive-default {
+  fill: var(--fill-destructive-default);
+}
+
+@utility fill-destructive-muted {
+  fill: var(--fill-destructive-muted);
+}
+
+/* Information Fill */
+@utility fill-information-highlight {
+  fill: var(--fill-information-highlight);
+}
+
+@utility fill-information-default {
+  fill: var(--fill-information-default);
+}
+
+@utility fill-information-muted {
+  fill: var(--fill-information-muted);
+}
+
+/* Success Fill */
+@utility fill-success-highlight {
+  fill: var(--fill-success-highlight);
+}
+
+@utility fill-success-default {
+  fill: var(--fill-success-default);
+}
+
+@utility fill-success-muted {
+  fill: var(--fill-success-muted);
+}
+
+/* Warninig Fill */
+@utility fill-warning-highlight {
+  fill: var(--fill-warning-highlight);
+}
+
+@utility fill-warning-default {
+  fill: var(--fill-warning-default);
+}
+
+@utility fill-warning-muted {
+  fill: var(--fill-warning-muted);
+}
+
+/* =============================
+*  Strokes
+*  ============================*/
+
+/* Neutrals */
+@utility stroke-neutral-highlight {
+  stroke: var(--stroke-neutral-highlight);
+}
+
+@utility stroke-neutral-active {
+  stroke: var(--stroke-neutral-active);
+}
+
+@utility stroke-neutral-default {
+  stroke: var(--stroke-neutral-default);
+}
+
+@utility stroke-neutral-muted {
+  stroke: var(--stroke-neutral-muted);
+}
+
+/* onColor / Dark */
+@utility stroke-onColor-dark-highlight {
+  stroke: var(--stroke-onColor-dark-highlight);
+}
+
+@utility stroke-onColor-dark-default {
+  stroke: var(--stroke-onColor-dark-default);
+}
+
+@utility stroke-onColor-dark-muted {
+  stroke: var(--stroke-onColor-dark-muted);
+}
+
+/* onColor / Light */
+@utility stroke-onColor-light-highlight {
+  stroke: var(--stroke-onColor-light-highlight);
+}
+
+@utility stroke-onColor-light-default {
+  stroke: var(--stroke-onColor-light-default);
+}
+
+@utility stroke-onColor-light-muted {
+  stroke: var(--stroke-onColor-light-muted);
+}
+
+/* Link stroke */
+@utility stroke-link-primary {
+  stroke: var(--stroke-link-primary);
+}
+
+@utility stroke-link-secondary {
+  stroke: var(--stroke-link-secondary);
+}
+
+@utility stroke-link-visited {
+  stroke: var(--stroke-link-visited);
+}
+
+/* Destructive stroke */
+@utility stroke-destructive-highlight {
+  stroke: var(--stroke-destructive-highlight);
+}
+
+@utility stroke-destructive-default {
+  stroke: var(--stroke-destructive-default);
+}
+
+@utility stroke-destructive-muted {
+  stroke: var(--stroke-destructive-muted);
+}
+
+/* Information stroke */
+@utility stroke-information-highlight {
+  stroke: var(--stroke-information-highlight);
+}
+
+@utility stroke-information-default {
+  stroke: var(--stroke-information-default);
+}
+
+@utility stroke-information-muted {
+  stroke: var(--stroke-information-muted);
+}
+
+/* Success stroke */
+@utility stroke-success-highlight {
+  stroke: var(--stroke-success-highlight);
+}
+
+@utility stroke-success-default {
+  stroke: var(--stroke-success-default);
+}
+
+@utility stroke-success-muted {
+  stroke: var(--stroke-success-muted);
+}
+
+/* Warninig stroke */
+@utility stroke-warning-highlight {
+  stroke: var(--stroke-warning-highlight);
+}
+
+@utility stroke-warning-default {
+  stroke: var(--stroke-warning-default);
+}
+
+@utility stroke-warning-muted {
+  stroke: var(--stroke-warning-muted);
+}
+
+/* ============================================
+* BACKGROUNDS
+* ============================================ */
+@utilities bg-primary {
+  background-color: var(--bg-primary);
+}
+
+@utilities bg-secondary {
+  background-color: var(--bg-secondary);
+}
+
+@utilities bg-tertiary {
+  background-color: var(--bg-tertiary);
+}
+
+/* State */
+@utility bg-highlight {
+  background-color: var(--bg-highlight);
+}
+
+@utility bg-active {
+  background-color: var(--bg-active);
+}
+
+@utility bg-default {
+  background-color: var(--bg-default);
+}
+
+@utility bg-muted {
+  background-color: var(--bg-muted);
+}
+
+@utility bg-inset {
+  background-color: var(--bg-inset);
+}
+
+/* Light background in dark mode */
+@utility bg-light-dark-primary {
+  background-color: var(--bg-light-dark-primary);
+}
+
+@utility bg-light-dark-secondary {
+  background-color: var(--bg-light-dark-secondary);
+}
+
+@utility bg-light-dark-tertiary {
+  background-color: var(--bg-light-dark-tertiary);
+}
+
+/* Dark background in light mode */
+@utility bg-dark-light-primary {
+  background-color: var(--bg-dark-light-primary);
+}
+
+@utility bg-dark-light-secondary {
+  background-color: var(--bg-dark-light-secondary);
+}
+
+@utility bg-dark-light-tertiary {
+  background-color: var(--bg-dark-light-tertiary);
+}
+
+/* Destructive */
+@utility bg-destructive-highlight {
+  background-color: var(--bg-destructive-highlight);
+}
+
+@utility bg-destructive-default {
+  background-color: var(--bg-destructive-default);
+}
+
+@utility bg-destructive-muted {
+  background-color: var(--bg-destructive-muted);
+}
+
+@utility bg-destructive-softest {
+  background-color: var(--bg-destructive-softest);
+}
+
+/* Information */
+@utility bg-information-highlight {
+  background-color: var(--bg-information-highlight);
+}
+
+@utility bg-information-default {
+  background-color: var(--bg-information-default);
+}
+
+@utility bg-information-muted {
+  background-color: var(--bg-information-muted);
+}
+
+@utility bg-information-softest {
+  background-color: var(--bg-information-softest);
+}
+
+/* Success */
+@utility bg-success-highlight {
+  background-color: var(--bg-success-highlight);
+}
+
+@utility bg-success-default {
+  background-color: var(--bg-success-default);
+}
+
+@utility bg-success-muted {
+  background-color: var(--bg-success-muted);
+}
+
+@utility bg-success-softest {
+  background-color: var(--bg-success-softest);
+}
+
+/* Warning */
+@utility bg-warning-highlight {
+  background-color: var(--bg-warning-highlight);
+}
+
+@utility bg-warning-default {
+  background-color: var(--bg-warning-default);
+}
+
+@utility bg-warning-muted {
+  background-color: var(--bg-warning-muted);
+}
+
+@utility bg-warning-softest {
+  background-color: var(--bg-warning-softest);
+}
+
+
+@layer utilities {
+  .devicon-devicon-plain {
+    max-width: 2em;
+  }
+
+  /* if you want to change the original color */
+  .devicon-devicon-plain path {
+    fill: var(--primary);
+  }
+
+  @keyframes slide-fade-in {
+    from {
+      opacity: 0;
+      transform: translateX(100%);
+    }
+    to {
+      opacity: 1;
+      transform: translateX(0);
+    }
+  }
+
+  @keyframes slide-fade-out {
+    from {
+      opacity: 1;
+      transform: translateX(0);
+    }
+    to {
+      opacity: 0;
+      transform: translateX(-100%);
+    }
+  }
+
+  @keyframes spin {
+    from {
+      transform: rotate(0deg);
+    }
+    to {
+      transform: rotate(360deg);
+    }
+  }
+}
+
+/*
+  Expose theme variables as utilities
+  Note: We're being selective about what we expose to avoid people using raw color values
+*/
+@theme inline {
+  /* --color-*: initial; */
+
+  /* Link colors */
+  --color-link: var(--text-link-primary);
+
+  /* Shadcn theme */
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  --color-background: var(--background);
+  --color-background-pure: var(--background-pure);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+
+  /* Alert Colors */
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-feature: var(--feature);
+  --color-feature-foreground: var(--feature-foreground);
+
+  /* Text Colors */
+  --color-body: var(--text-body);
+  --color-body-muted: var(--text-body-muted);
+
+  /* Animation */
+  --keyframes-wiggle: {
+    0%,
+    100% {
+      transform: rotate(-1.5deg);
+    }
+    50% {
+      transform: rotate(1.5deg);
+    }
+  };
+  --animate-wiggle: wiggle 1s ease-in-out infinite;
+
+  /* Transition Timing Functions */
+  --ease-in-out-quad: var(--ease-in-out-quad);
+  --ease-in-out-cubic: var(--ease-in-out-cubic);
+  --ease-in-out-quart: var(--ease-in-out-quart);
+  --ease-in-out-quint: var(--ease-in-out-quint);
+  --ease-in-out-expo: var(--ease-in-out-expo);
+  --ease-in-out-circ: var(--ease-in-out-circ);
+
+  --ease-in-quad: var(--ease-in-quad);
+  --ease-in-cubic: var(--ease-in-cubic);
+  --ease-in-quart: var(--ease-in-quart);
+  --ease-in-quint: var(--ease-in-quint);
+  --ease-in-expo: var(--ease-in-expo);
+  --ease-in-circ: var(--ease-in-circ);
+
+  --ease-out-quad: var(--ease-out-quad);
+  --ease-out-cubic: var(--ease-out-cubic);
+  --ease-out-quart: var(--ease-out-quart);
+  --ease-out-quint: var(--ease-out-quint);
+  --ease-out-expo: var(--ease-out-expo);
+  --ease-out-circ: var(--ease-out-circ);
+}
+
+
diff --git a/types/utilities.d.ts b/types/utilities.d.ts
new file mode 100644
index 00000000..d22bb37a
--- /dev/null
+++ b/types/utilities.d.ts
@@ -0,0 +1,382 @@
+/**
+ * Auto-generated TypeScript definitions for Moonshine utilities
+ * Generated on: 2025-07-16T17:53:27.860Z
+ *
+ * DO NOT EDIT THIS FILE DIRECTLY
+ * Run 'pnpm generate:docs' to update
+ */
+
+/**
+ * Custom utility classes defined in utilities.css
+ */
+export type MoonshineUtilities =
+  | 'typography-heading-xl'
+  | 'typography-heading-lg'
+  | 'typography-heading-md'
+  | 'typography-heading-sm'
+  | 'typography-heading-xs'
+  | 'typography-heading-xxs'
+  | 'typography-body-lg'
+  | 'typography-body-md'
+  | 'typography-body-sm'
+  | 'typography-body-xs'
+  | 'container'
+  | 'bg-mask'
+  | 'text-display-2xl'
+  | 'text-display-xl'
+  | 'text-display-lg'
+  | 'text-display-md'
+  | 'text-display-sm'
+  | 'text-display-xs'
+  | 'text-heading-xl'
+  | 'text-heading-lg'
+  | 'text-heading-md'
+  | 'text-heading-sm'
+  | 'text-heading-xs'
+  | 'text-body-lg'
+  | 'text-body-md'
+  | 'text-body-sm'
+  | 'text-body-xs'
+  | 'text-codeline-md'
+  | 'text-codeline-sm'
+  | 'text-codeline-xs'
+  | 'text-hightlight'
+  | 'text-text-default'
+  | 'text-muted'
+  | 'text-placeholder'
+  | 'text-disabled'
+  | 'text-dark-light-highlight'
+  | 'text-dark-light-default'
+  | 'text-dark-light-muted'
+  | 'text-light-dark-highlight'
+  | 'text-light-dark-default'
+  | 'text-light-dark-muted'
+  | 'text-link-primary'
+  | 'text-link-secondary'
+  | 'text-link-visited'
+  | 'text-default-destructive'
+  | 'text-link-destructive'
+  | 'text-default-information'
+  | 'text-link-information'
+  | 'text-default-success'
+  | 'text-link-success'
+  | 'text-default-warning'
+  | 'text-link-warning'
+  | 'bg-gradient-primary'
+  | 'border-gradient-primary'
+  | 'bg-surface-primary'
+  | 'bg-surface-secondary'
+  | 'bg-warning'
+  | 'text-warning'
+  | 'border-warning'
+  | 'underline-link-primary'
+  | 'underline-link-secondary'
+  | 'underline-link-visited'
+  | 'border-neutral-active'
+  | 'border-neutral-hover'
+  | 'border-neutral-default'
+  | 'border-neutral-disabled'
+  | 'border-neutral-softest'
+  | 'border-neutral-inset'
+  | 'border-neutral-alpha'
+  | 'border-destructive-highlight'
+  | 'border-destructive-default'
+  | 'border-destructive-muted'
+  | 'border-destructive-softest'
+  | 'border-information-highlight'
+  | 'border-information-default'
+  | 'border-information-muted'
+  | 'border-information-softest'
+  | 'border-success-highlight'
+  | 'border-success-default'
+  | 'border-success-muted'
+  | 'border-success-softest'
+  | 'border-focus'
+  | 'fill-neutral-highlight'
+  | 'fill-neutral-active'
+  | 'fill-neutral-default'
+  | 'fill-neutral-muted'
+  | 'fill-onColor-dark-highlight'
+  | 'fill-onColor-dark-default'
+  | 'fill-onColor-dark-muted'
+  | 'fill-onColor-light-highlight'
+  | 'fill-onColor-light-default'
+  | 'fill-onColor-light-muted'
+  | 'fill-link-primary'
+  | 'fill-link-secondary'
+  | 'fill-link-visited'
+  | 'fill-destructive-highlight'
+  | 'fill-destructive-default'
+  | 'fill-destructive-muted'
+  | 'fill-information-highlight'
+  | 'fill-information-default'
+  | 'fill-information-muted'
+  | 'fill-success-highlight'
+  | 'fill-success-default'
+  | 'fill-success-muted'
+  | 'fill-warning-highlight'
+  | 'fill-warning-default'
+  | 'fill-warning-muted'
+  | 'bg-highlight'
+  | 'bg-active'
+  | 'bg-default'
+  | 'bg-muted'
+  | 'bg-inset'
+  | 'bg-light-dark-primary'
+  | 'bg-light-dark-secondary'
+  | 'bg-light-dark-tertiary'
+  | 'bg-dark-light-primary'
+  | 'bg-dark-light-secondary'
+  | 'bg-dark-light-tertiary'
+  | 'bg-destructive-highlight'
+  | 'bg-destructive-default'
+  | 'bg-destructive-muted'
+  | 'bg-destructive-softest'
+  | 'bg-information-highlight'
+  | 'bg-information-default'
+  | 'bg-information-muted'
+  | 'bg-information-softest'
+  | 'bg-success-highlight'
+  | 'bg-success-default'
+  | 'bg-success-muted'
+  | 'bg-success-softest'
+  | 'bg-warning-highlight'
+  | 'bg-warning-default'
+  | 'bg-warning-muted'
+  | 'bg-warning-softest';
+
+/**
+ * Semantic color utilities available from theme
+ * These are auto-generated from theme colors with standard prefixes
+ */
+export type MoonshineColorUtilities =
+  | 'bg-link'
+  | 'text-link'
+  | 'border-link'
+  | 'ring-link'
+  | 'divide-link'
+  | 'bg-background'
+  | 'text-background'
+  | 'border-background'
+  | 'ring-background'
+  | 'divide-background'
+  | 'bg-background-pure'
+  | 'text-background-pure'
+  | 'border-background-pure'
+  | 'ring-background-pure'
+  | 'divide-background-pure'
+  | 'bg-foreground'
+  | 'text-foreground'
+  | 'border-foreground'
+  | 'ring-foreground'
+  | 'divide-foreground'
+  | 'bg-card'
+  | 'text-card'
+  | 'border-card'
+  | 'ring-card'
+  | 'divide-card'
+  | 'bg-card-foreground'
+  | 'text-card-foreground'
+  | 'border-card-foreground'
+  | 'ring-card-foreground'
+  | 'divide-card-foreground'
+  | 'bg-popover'
+  | 'text-popover'
+  | 'border-popover'
+  | 'ring-popover'
+  | 'divide-popover'
+  | 'bg-popover-foreground'
+  | 'text-popover-foreground'
+  | 'border-popover-foreground'
+  | 'ring-popover-foreground'
+  | 'divide-popover-foreground'
+  | 'bg-primary'
+  | 'text-primary'
+  | 'border-primary'
+  | 'ring-primary'
+  | 'divide-primary'
+  | 'bg-primary-foreground'
+  | 'text-primary-foreground'
+  | 'border-primary-foreground'
+  | 'ring-primary-foreground'
+  | 'divide-primary-foreground'
+  | 'bg-secondary'
+  | 'text-secondary'
+  | 'border-secondary'
+  | 'ring-secondary'
+  | 'divide-secondary'
+  | 'bg-secondary-foreground'
+  | 'text-secondary-foreground'
+  | 'border-secondary-foreground'
+  | 'ring-secondary-foreground'
+  | 'divide-secondary-foreground'
+  | 'bg-muted'
+  | 'text-muted'
+  | 'border-muted'
+  | 'ring-muted'
+  | 'divide-muted'
+  | 'bg-muted-foreground'
+  | 'text-muted-foreground'
+  | 'border-muted-foreground'
+  | 'ring-muted-foreground'
+  | 'divide-muted-foreground'
+  | 'bg-accent'
+  | 'text-accent'
+  | 'border-accent'
+  | 'ring-accent'
+  | 'divide-accent'
+  | 'bg-accent-foreground'
+  | 'text-accent-foreground'
+  | 'border-accent-foreground'
+  | 'ring-accent-foreground'
+  | 'divide-accent-foreground'
+  | 'bg-destructive'
+  | 'text-destructive'
+  | 'border-destructive'
+  | 'ring-destructive'
+  | 'divide-destructive'
+  | 'bg-border'
+  | 'text-border'
+  | 'border-border'
+  | 'ring-border'
+  | 'divide-border'
+  | 'bg-input'
+  | 'text-input'
+  | 'border-input'
+  | 'ring-input'
+  | 'divide-input'
+  | 'bg-ring'
+  | 'text-ring'
+  | 'border-ring'
+  | 'ring-ring'
+  | 'divide-ring'
+  | 'bg-chart-1'
+  | 'text-chart-1'
+  | 'border-chart-1'
+  | 'ring-chart-1'
+  | 'divide-chart-1'
+  | 'bg-chart-2'
+  | 'text-chart-2'
+  | 'border-chart-2'
+  | 'ring-chart-2'
+  | 'divide-chart-2'
+  | 'bg-chart-3'
+  | 'text-chart-3'
+  | 'border-chart-3'
+  | 'ring-chart-3'
+  | 'divide-chart-3'
+  | 'bg-chart-4'
+  | 'text-chart-4'
+  | 'border-chart-4'
+  | 'ring-chart-4'
+  | 'divide-chart-4'
+  | 'bg-chart-5'
+  | 'text-chart-5'
+  | 'border-chart-5'
+  | 'ring-chart-5'
+  | 'divide-chart-5'
+  | 'bg-sidebar'
+  | 'text-sidebar'
+  | 'border-sidebar'
+  | 'ring-sidebar'
+  | 'divide-sidebar'
+  | 'bg-sidebar-foreground'
+  | 'text-sidebar-foreground'
+  | 'border-sidebar-foreground'
+  | 'ring-sidebar-foreground'
+  | 'divide-sidebar-foreground'
+  | 'bg-sidebar-primary'
+  | 'text-sidebar-primary'
+  | 'border-sidebar-primary'
+  | 'ring-sidebar-primary'
+  | 'divide-sidebar-primary'
+  | 'bg-sidebar-primary-foreground'
+  | 'text-sidebar-primary-foreground'
+  | 'border-sidebar-primary-foreground'
+  | 'ring-sidebar-primary-foreground'
+  | 'divide-sidebar-primary-foreground'
+  | 'bg-sidebar-accent'
+  | 'text-sidebar-accent'
+  | 'border-sidebar-accent'
+  | 'ring-sidebar-accent'
+  | 'divide-sidebar-accent'
+  | 'bg-sidebar-accent-foreground'
+  | 'text-sidebar-accent-foreground'
+  | 'border-sidebar-accent-foreground'
+  | 'ring-sidebar-accent-foreground'
+  | 'divide-sidebar-accent-foreground'
+  | 'bg-sidebar-border'
+  | 'text-sidebar-border'
+  | 'border-sidebar-border'
+  | 'ring-sidebar-border'
+  | 'divide-sidebar-border'
+  | 'bg-sidebar-ring'
+  | 'text-sidebar-ring'
+  | 'border-sidebar-ring'
+  | 'ring-sidebar-ring'
+  | 'divide-sidebar-ring'
+  | 'bg-success'
+  | 'text-success'
+  | 'border-success'
+  | 'ring-success'
+  | 'divide-success'
+  | 'bg-success-foreground'
+  | 'text-success-foreground'
+  | 'border-success-foreground'
+  | 'ring-success-foreground'
+  | 'divide-success-foreground'
+  | 'bg-info'
+  | 'text-info'
+  | 'border-info'
+  | 'ring-info'
+  | 'divide-info'
+  | 'bg-info-foreground'
+  | 'text-info-foreground'
+  | 'border-info-foreground'
+  | 'ring-info-foreground'
+  | 'divide-info-foreground'
+  | 'bg-warning'
+  | 'text-warning'
+  | 'border-warning'
+  | 'ring-warning'
+  | 'divide-warning'
+  | 'bg-warning-foreground'
+  | 'text-warning-foreground'
+  | 'border-warning-foreground'
+  | 'ring-warning-foreground'
+  | 'divide-warning-foreground'
+  | 'bg-destructive-foreground'
+  | 'text-destructive-foreground'
+  | 'border-destructive-foreground'
+  | 'ring-destructive-foreground'
+  | 'divide-destructive-foreground'
+  | 'bg-feature'
+  | 'text-feature'
+  | 'border-feature'
+  | 'ring-feature'
+  | 'divide-feature'
+  | 'bg-feature-foreground'
+  | 'text-feature-foreground'
+  | 'border-feature-foreground'
+  | 'ring-feature-foreground'
+  | 'divide-feature-foreground'
+  | 'bg-body'
+  | 'text-body'
+  | 'border-body'
+  | 'ring-body'
+  | 'divide-body'
+  | 'bg-body-muted'
+  | 'text-body-muted'
+  | 'border-body-muted'
+  | 'ring-body-muted'
+  | 'divide-body-muted';
+
+/**
+ * All available Moonshine utility classes
+ */
+export type MoonshineClasses = MoonshineUtilities | MoonshineColorUtilities;
+
+/**
+ * Helper type for className props
+ */
+export type MoonshineClassName = MoonshineClasses | MoonshineClasses[] | undefined | null | false;