diff --git a/docs/theming/configuration/css-variables.md b/docs/theming/configuration/css-variables.md
index 34e94f8b..e2202113 100644
--- a/docs/theming/configuration/css-variables.md
+++ b/docs/theming/configuration/css-variables.md
@@ -43,12 +43,12 @@ Variables defined in `:root` or theme-specific selectors are for component-speci
 
 ```css
 @theme {
-  --font-family-header: system-ui, sans-serif;
-  --font-family-body: system-ui, sans-serif;
-  --font-family-code: 'Courier New', monospace;
-  --font-family-label: system-ui, sans-serif;
-  --font-family-caption: system-ui, sans-serif;
-  --font-family-marquee: system-ui, sans-serif;
+  --font-header: system-ui, sans-serif;
+  --font-body: system-ui, sans-serif;
+  --font-code: 'Courier New', monospace;
+  --font-label: system-ui, sans-serif;
+  --font-caption: system-ui, sans-serif;
+  --font-marquee: system-ui, sans-serif;
 }
 ```
 
@@ -303,9 +303,9 @@ Or per-theme:
 }
 
 @theme {
-  --font-family-header: 'Inter', system-ui, sans-serif;
-  --font-family-body: 'Inter', system-ui, sans-serif;
-  --font-family-label: 'Inter', system-ui, sans-serif;
+  --font-header: 'Inter', system-ui, sans-serif;
+  --font-body: 'Inter', system-ui, sans-serif;
+  --font-label: 'Inter', system-ui, sans-serif;
 }
 ```
 
diff --git a/docs/theming/configuration/customization.md b/docs/theming/configuration/customization.md
index a0d7521b..90761190 100644
--- a/docs/theming/configuration/customization.md
+++ b/docs/theming/configuration/customization.md
@@ -116,10 +116,10 @@ Override font families for different text categories:
 }
 
 @theme {
-  --font-family-header: 'Inter', system-ui, sans-serif;
-  --font-family-body: 'Inter', system-ui, sans-serif;
-  --font-family-label: 'Inter', system-ui, sans-serif;
-  --font-family-code: 'JetBrains Mono', monospace;
+  --font-header: 'Inter', system-ui, sans-serif;
+  --font-body: 'Inter', system-ui, sans-serif;
+  --font-label: 'Inter', system-ui, sans-serif;
+  --font-code: 'JetBrains Mono', monospace;
 }
 ```
 
@@ -130,12 +130,12 @@ Use different fonts for light and dark themes:
 ```css
 .light,
 .dark .theme-inverse {
-  --font-family-body: 'Inter', system-ui, sans-serif;
+  --font-body: 'Inter', system-ui, sans-serif;
 }
 
 .dark,
 .light .theme-inverse {
-  --font-family-body: 'Geist', system-ui, sans-serif;
+  --font-body: 'Geist', system-ui, sans-serif;
 }
 ```
 
@@ -368,9 +368,9 @@ module.exports = frontile({
 
 @theme {
   /* Typography */
-  --font-family-header: 'Poppins', system-ui, sans-serif;
-  --font-family-body: 'Poppins', system-ui, sans-serif;
-  --font-family-label: 'Poppins', system-ui, sans-serif;
+  --font-header: 'Poppins', system-ui, sans-serif;
+  --font-body: 'Poppins', system-ui, sans-serif;
+  --font-label: 'Poppins', system-ui, sans-serif;
 
   /* Rounded design */
   --radius: 12px;
diff --git a/docs/theming/design-tokens/borders.md b/docs/theming/design-tokens/borders.md
index 685c0482..d5bca013 100644
--- a/docs/theming/design-tokens/borders.md
+++ b/docs/theming/design-tokens/borders.md
@@ -120,55 +120,6 @@ Control corner rounding with radius tokens that range from sharp edges to fully
 | Default (Custom) | `rounded-default` | Custom default radius value, soft friendly corners |
 | Pill | `rounded-pill` | Pills, badges, fully rounded buttons |
 
-### Border Radius Examples
-
-```gts preview
-<template>
-  <div class='space-y-6'>
-    {{! Button group with different radii }}
-    <div class='flex gap-3 flex-wrap'>
-      <button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded-sm hover:bg-brand-soft'>
-        Sharp (SM)
-      </button>
-      <button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded hover:bg-brand-soft'>
-        Default
-      </button>
-      <button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded-xl hover:bg-brand-soft'>
-        Soft (XL)
-      </button>
-      <button class='bg-brand-medium text-on-brand-medium px-6 py-2 rounded-pill hover:bg-brand-soft'>
-        Pill
-      </button>
-    </div>
-
-    {{! Cards with different radii }}
-    <div class='grid md:grid-cols-2 gap-4'>
-      <div class='border border-neutral-medium rounded-md p-6'>
-        <h3 class='text-header-sm mb-2'>Standard Card</h3>
-        <p class='text-body-sm text-neutral-soft'>Uses rounded-md for subtle corners</p>
-      </div>
-      <div class='border border-neutral-medium rounded-2xl p-6'>
-        <h3 class='text-header-sm mb-2'>Feature Card</h3>
-        <p class='text-body-sm text-neutral-soft'>Uses rounded-2xl for prominent display</p>
-      </div>
-    </div>
-
-    {{! Badges and pills }}
-    <div class='flex gap-3 flex-wrap items-center'>
-      <span class='bg-neutral-subtle text-neutral-strong px-3 py-1 rounded text-label-xs'>
-        Rounded Badge
-      </span>
-      <span class='bg-success-subtle text-success-strong px-3 py-1 rounded-pill text-label-xs'>
-        Pill Badge
-      </span>
-      <span class='bg-brand-medium text-on-brand-medium px-3 py-1 rounded-xl text-label-xs'>
-        Soft Badge
-      </span>
-    </div>
-  </div>
-</template>
-```
-
 ## Combining Borders and Radius
 
 Use border widths and radius together to create various UI patterns:
@@ -197,54 +148,6 @@ Use border widths and radius together to create various UI patterns:
 </template>
 ```
 
-## Directional Border Utilities
-
-Tailwind's directional utilities work with Frontile's border width tokens:
-
-```gts preview
-<template>
-  <div class='space-y-4'>
-    {{! Top border only }}
-    <div class='border-t-heavy border-brand-medium p-4 bg-background'>
-      <p class='text-body-sm'>Top border (heavy)</p>
-    </div>
-
-    {{! Left border accent }}
-    <div class='border-l-aggressive border-success-medium p-4 bg-background'>
-      <p class='text-body-sm'>Left border accent (aggressive)</p>
-    </div>
-
-    {{! Bottom divider }}
-    <div class='border-b-thin border-neutral-medium p-4 bg-background'>
-      <p class='text-body-sm'>Bottom divider (thin)</p>
-    </div>
-  </div>
-</template>
-```
-
-## Directional Border Radius
-
-Apply radius to specific corners:
-
-```gts preview
-<template>
-  <div class='grid md:grid-cols-3 gap-4'>
-    <div class='bg-brand-subtle p-6 rounded-t-xl'>
-      <p class='text-body-sm'>Top rounded</p>
-      <code class='text-code-sm'>rounded-t-xl</code>
-    </div>
-    <div class='bg-brand-subtle p-6 rounded-b-xl'>
-      <p class='text-body-sm'>Bottom rounded</p>
-      <code class='text-code-sm'>rounded-b-xl</code>
-    </div>
-    <div class='bg-brand-subtle p-6 rounded-l-xl'>
-      <p class='text-body-sm'>Left rounded</p>
-      <code class='text-code-sm'>rounded-l-xl</code>
-    </div>
-  </div>
-</template>
-```
-
 ## Best Practices
 
 ### Maintain Consistency
diff --git a/docs/theming/design-tokens/elevation.md b/docs/theming/design-tokens/elevation.md
index 653eb467..9024c43b 100644
--- a/docs/theming/design-tokens/elevation.md
+++ b/docs/theming/design-tokens/elevation.md
@@ -21,34 +21,34 @@ Higher elevations indicate elements that are more prominent or interactive, such
 <template>
   <div class='grid grid-cols-2 md:grid-cols-3 gap-8 bg-surface-solid-1 p-8'>
     <div class='shadow-elevation-0 bg-background p-6 rounded'>
-      <h3 class='text-header-sm mb-2'>Level 0</h3>
-      <p class='text-body-sm text-neutral-soft'>No shadow</p>
-      <p class='text-caption-sm text-neutral-soft mt-2'>Flat surface</p>
+      <h3 class='mb-2'>Level 0</h3>
+      <p class='text-neutral-soft'>No shadow</p>
+      <p class='text-neutral-soft text-sm mt-2'>Flat surface</p>
     </div>
     <div class='shadow-elevation-1 bg-background p-6 rounded'>
-      <h3 class='text-header-sm mb-2'>Level 1</h3>
-      <p class='text-body-sm text-neutral-soft'>Subtle lift</p>
-      <p class='text-caption-sm text-neutral-soft mt-2'>Hover states</p>
+      <h3 class='mb-2'>Level 1</h3>
+      <p class='text-neutral-soft'>Subtle lift</p>
+      <p class='text-neutral-soft text-sm mt-2'>Hover states</p>
     </div>
     <div class='shadow-elevation-2 bg-background p-6 rounded'>
-      <h3 class='text-header-sm mb-2'>Level 2</h3>
-      <p class='text-body-sm text-neutral-soft'>Raised surface</p>
-      <p class='text-caption-sm text-neutral-soft mt-2'>Cards, panels</p>
+      <h3 class='mb-2'>Level 2</h3>
+      <p class='text-neutral-soft'>Raised surface</p>
+      <p class='text-neutral-soft text-sm mt-2'>Cards, panels</p>
     </div>
     <div class='shadow-elevation-3 bg-background p-6 rounded'>
-      <h3 class='text-header-sm mb-2'>Level 3</h3>
-      <p class='text-body-sm text-neutral-soft'>Floating element</p>
-      <p class='text-caption-sm text-neutral-soft mt-2'>Dropdowns</p>
+      <h3 class='mb-2'>Level 3</h3>
+      <p class='text-neutral-soft'>Floating element</p>
+      <p class='text-neutral-soft text-sm mt-2'>Dropdowns</p>
     </div>
     <div class='shadow-elevation-4 bg-background p-6 rounded'>
-      <h3 class='text-header-sm mb-2'>Level 4</h3>
-      <p class='text-body-sm text-neutral-soft'>Elevated overlay</p>
-      <p class='text-caption-sm text-neutral-soft mt-2'>Modals, dialogs</p>
+      <h3 class='mb-2'>Level 4</h3>
+      <p class='text-neutral-soft'>Elevated overlay</p>
+      <p class='text-neutral-soft text-sm mt-2'>Modals, dialogs</p>
     </div>
     <div class='shadow-elevation-5 bg-background p-6 rounded'>
-      <h3 class='text-header-sm mb-2'>Level 5</h3>
-      <p class='text-body-sm text-neutral-soft'>Maximum depth</p>
-      <p class='text-caption-sm text-neutral-soft mt-2'>Top layer</p>
+      <h3 class='mb-2'>Level 5</h3>
+      <p class='text-neutral-soft'>Maximum depth</p>
+      <p class='text-neutral-soft text-sm mt-2'>Top layer</p>
     </div>
   </div>
 </template>
@@ -74,8 +74,8 @@ Higher elevations indicate elements that are more prominent or interactive, such
   <div class='grid md:grid-cols-2 gap-6'>
     {{! Basic card with level 2 elevation }}
     <div class='shadow-elevation-2 bg-background rounded-xl p-6'>
-      <h3 class='text-header-md mb-3'>Product Card</h3>
-      <p class='text-body-sm text-neutral-soft mb-4'>
+      <h3 class='mb-3'>Product Card</h3>
+      <p class='text-neutral-soft mb-4'>
         Standard card with level 2 elevation provides subtle depth.
       </p>
       <button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded hover:bg-brand-soft'>
@@ -85,8 +85,8 @@ Higher elevations indicate elements that are more prominent or interactive, such
 
     {{! Feature card with no shadow }}
     <div class='shadow-elevation-0 border border-neutral-medium bg-background rounded-xl p-6'>
-      <h3 class='text-header-md mb-3'>Flat Card</h3>
-      <p class='text-body-sm text-neutral-soft mb-4'>
+      <h3 class='mb-3'>Flat Card</h3>
+      <p class='text-neutral-soft mb-4'>
         Uses border instead of shadow for a flatter appearance.
       </p>
       <button class='border border-brand-medium text-brand-medium px-4 py-2 rounded hover:bg-brand-subtle'>
@@ -113,116 +113,8 @@ Higher elevations indicate elements that are more prominent or interactive, such
     <div
       class='bg-background rounded-xl p-6 shadow-elevation-1 hover:shadow-elevation-2 transition-shadow cursor-pointer'
     >
-      <h4 class='text-header-sm mb-2'>Interactive Card</h4>
-      <p class='text-body-sm text-neutral-soft'>Elevation increases on hover</p>
-    </div>
-  </div>
-</template>
-```
-
-### Dropdown Menus
-
-```gts preview
-<template>
-  <div class='relative inline-block'>
-    <button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded'>
-      Open Menu
-    </button>
-    {{! Dropdown with level 3 elevation }}
-    <div
-      class='absolute mt-2 w-56 shadow-elevation-3 bg-background rounded-lg overflow-hidden'
-    >
-      <a href='#' class='block px-4 py-3 hover:bg-neutral-subtle text-body-sm'>Menu Item 1</a>
-      <a href='#' class='block px-4 py-3 hover:bg-neutral-subtle text-body-sm'>Menu Item 2</a>
-      <a href='#' class='block px-4 py-3 hover:bg-neutral-subtle text-body-sm'>Menu Item 3</a>
-    </div>
-  </div>
-</template>
-```
-
-### Modal Dialog
-
-```gts preview
-<template>
-  <div class='relative h-64 flex items-center justify-center bg-surface-solid-1 rounded-lg'>
-    {{! Modal with level 4 elevation }}
-    <div class='shadow-elevation-4 bg-background rounded-xl p-8 max-w-md'>
-      <h3 class='text-header-lg mb-4'>Confirm Action</h3>
-      <p class='text-body-md text-neutral-soft mb-6'>
-        Are you sure you want to proceed with this action?
-      </p>
-      <div class='flex gap-3 justify-end'>
-        <button class='border border-neutral-medium px-4 py-2 rounded hover:bg-neutral-subtle'>
-          Cancel
-        </button>
-        <button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded hover:bg-brand-soft'>
-          Confirm
-        </button>
-      </div>
-    </div>
-  </div>
-</template>
-```
-
-### Alert Notifications
-
-```gts preview
-<template>
-  <div class='space-y-4'>
-    {{! Standard alert with level 2 elevation }}
-    <div class='shadow-elevation-2 bg-background border-l-aggressive border-brand-medium rounded p-4'>
-      <h4 class='text-label-md mb-1'>Information</h4>
-      <p class='text-body-sm text-neutral-soft'>Standard notification with moderate elevation.</p>
-    </div>
-
-    {{! Critical alert with level 5 elevation }}
-    <div class='shadow-elevation-5 bg-danger-medium text-on-danger-medium rounded p-4'>
-      <h4 class='text-label-md mb-1'>Critical Alert</h4>
-      <p class='text-body-sm'>Maximum elevation draws immediate attention.</p>
-    </div>
-  </div>
-</template>
-```
-
-## Combining with Other Tokens
-
-### Elevation with Border Radius
-
-Pair elevation with border radius for polished UI:
-
-```gts preview
-<template>
-  <div class='grid md:grid-cols-3 gap-4'>
-    <div class='shadow-elevation-2 rounded-sm bg-background p-4'>
-      <p class='text-body-sm'>Sharp corners</p>
-      <code class='text-code-sm'>rounded-sm</code>
-    </div>
-    <div class='shadow-elevation-2 rounded-xl bg-background p-4'>
-      <p class='text-body-sm'>Soft corners</p>
-      <code class='text-code-sm'>rounded-xl</code>
-    </div>
-    <div class='shadow-elevation-2 rounded-2xl bg-background p-4'>
-      <p class='text-body-sm'>Very soft</p>
-      <code class='text-code-sm'>rounded-2xl</code>
-    </div>
-  </div>
-</template>
-```
-
-### Elevation with Colors
-
-Use semantic colors with elevation:
-
-```gts preview
-<template>
-  <div class='grid md:grid-cols-2 gap-4'>
-    <div class='shadow-elevation-2 bg-success-subtle border border-success-soft rounded-xl p-4'>
-      <h4 class='text-label-md text-success-strong mb-2'>Success</h4>
-      <p class='text-body-sm text-success-strong'>Elevated success message</p>
-    </div>
-    <div class='shadow-elevation-3 bg-warning-medium text-on-warning-medium rounded-xl p-4'>
-      <h4 class='text-label-md mb-2'>Warning</h4>
-      <p class='text-body-sm'>High-elevation warning</p>
+      <h4 class='mb-2'>Interactive Card</h4>
+      <p class='text-neutral-soft'>Elevation increases on hover</p>
     </div>
   </div>
 </template>
diff --git a/docs/theming/design-tokens/icons.md b/docs/theming/design-tokens/icons.md
index 1fb41206..70f36ae3 100644
--- a/docs/theming/design-tokens/icons.md
+++ b/docs/theming/design-tokens/icons.md
@@ -77,59 +77,148 @@ Apply icon sizes using the `size-icon-*` utilities, which set both width and hei
 | Kilo | `size-icon-kilo` | Very large decorative icons |
 | Mega | `size-icon-mega` | Largest decorative icons |
 
+## All Icon Sizes
+
+Here are all available icon sizes with visual examples:
+
+```gts preview
+import { CheckIcon } from 'site/components/icons';
+
+<template>
+  <div class='grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4'>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-pico text-brand-medium' />
+      <div>
+        <div class='font-medium'>Pico</div>
+        <code class='text-xs'>size-icon-pico</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-nano text-brand-medium' />
+      <div>
+        <div class='font-medium'>Nano</div>
+        <code class='text-xs'>size-icon-nano</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-micro text-brand-medium' />
+      <div>
+        <div class='font-medium'>Micro</div>
+        <code class='text-xs'>size-icon-micro</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-3xs text-brand-medium' />
+      <div>
+        <div class='font-medium'>3XS</div>
+        <code class='text-xs'>size-icon-3xs</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-2xs text-brand-medium' />
+      <div>
+        <div class='font-medium'>2XS</div>
+        <code class='text-xs'>size-icon-2xs</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-xs text-brand-medium' />
+      <div>
+        <div class='font-medium'>XS</div>
+        <code class='text-xs'>size-icon-xs</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-sm text-brand-medium' />
+      <div>
+        <div class='font-medium'>SM</div>
+        <code class='text-xs'>size-icon-sm</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-md text-brand-medium' />
+      <div>
+        <div class='font-medium'>MD</div>
+        <code class='text-xs'>size-icon-md</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-lg text-brand-medium' />
+      <div>
+        <div class='font-medium'>LG</div>
+        <code class='text-xs'>size-icon-lg</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-xl text-brand-medium' />
+      <div>
+        <div class='font-medium'>XL</div>
+        <code class='text-xs'>size-icon-xl</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-2xl text-brand-medium' />
+      <div>
+        <div class='font-medium'>2XL</div>
+        <code class='text-xs'>size-icon-2xl</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-3xl text-brand-medium' />
+      <div>
+        <div class='font-medium'>3XL</div>
+        <code class='text-xs'>size-icon-3xl</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-kilo text-brand-medium' />
+      <div>
+        <div class='font-medium'>Kilo</div>
+        <code class='text-xs'>size-icon-kilo</code>
+      </div>
+    </div>
+    <div class='flex items-center gap-3 p-3 border border-neutral-medium rounded'>
+      <CheckIcon class='size-icon-mega text-brand-medium' />
+      <div>
+        <div class='font-medium'>Mega</div>
+        <code class='text-xs'>size-icon-mega</code>
+      </div>
+    </div>
+  </div>
+</template>
+```
+
 ## Pairing with Typography
 
 Icon sizes are designed to pair harmoniously with text styles. Use these recommended pairings for visual alignment:
 
 ```gts preview
+import { CheckIcon, ViewIcon, StarIcon } from 'site/components/icons';
+
 <template>
   <div class='flex flex-col gap-4'>
-    {{! Small text with small icon }}
+    {{! Small icon pairing }}
     <div class='flex items-center gap-2'>
-      <svg class='size-icon-xs text-success-medium' fill='currentColor' viewBox='0 0 20 20'>
-        <path
-          fill-rule='evenodd'
-          d='M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z'
-          clip-rule='evenodd'
-        ></path>
-      </svg>
-      <span class='text-body-sm'>Small body text with size-icon-xs</span>
+      <CheckIcon class='size-icon-xs text-success-medium' />
+      <span>Small text with size-icon-xs</span>
     </div>
 
-    {{! Medium text with medium icon }}
+    {{! Medium icon pairing }}
     <div class='flex items-center gap-2'>
-      <svg class='size-icon-md text-brand-medium' fill='currentColor' viewBox='0 0 20 20'>
-        <path
-          fill-rule='evenodd'
-          d='M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z'
-          clip-rule='evenodd'
-        ></path>
-      </svg>
-      <span class='text-body-md'>Default body text with size-icon-md</span>
+      <ViewIcon class='size-icon-md text-brand-medium' />
+      <span>Default text with size-icon-md</span>
     </div>
 
-    {{! Large text with large icon }}
+    {{! Large icon pairing }}
     <div class='flex items-center gap-2'>
-      <svg class='size-icon-lg text-warning-medium' fill='currentColor' viewBox='0 0 20 20'>
-        <path
-          fill-rule='evenodd'
-          d='M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z'
-          clip-rule='evenodd'
-        ></path>
-      </svg>
-      <span class='text-body-lg'>Large body text with size-icon-lg</span>
+      <StarIcon class='size-icon-lg text-warning-medium' />
+      <span>Larger text with size-icon-lg</span>
     </div>
 
-    {{! Header with large icon }}
+    {{! Extra large icon pairing }}
     <div class='flex items-center gap-3'>
-      <svg class='size-icon-xl text-danger-medium' fill='currentColor' viewBox='0 0 20 20'>
-        <path
-          fill-rule='evenodd'
-          d='M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z'
-          clip-rule='evenodd'
-        ></path>
-      </svg>
-      <h2 class='text-header-lg'>Header text with size-icon-xl</h2>
+      <CheckIcon class='size-icon-xl text-danger-medium' />
+      <h2>Header with size-icon-xl</h2>
     </div>
   </div>
 </template>
@@ -147,100 +236,6 @@ Icon sizes are designed to pair harmoniously with text styles. Use these recomme
 | `text-header-lg` | `size-icon-lg` or `size-icon-xl` |
 | `text-header-xl` | `size-icon-xl` or `size-icon-2xl` |
 
-## Common Use Cases
-
-### Buttons with Icons
-
-```gts preview
-<template>
-  <div class='flex gap-4 flex-wrap'>
-    <button class='flex items-center gap-2 bg-brand-medium text-on-brand-medium px-4 py-2 rounded hover:bg-brand-soft'>
-      <svg class='size-icon-sm' fill='currentColor' viewBox='0 0 20 20'>
-        <path d='M10 5a1 1 0 011 1v3h3a1 1 0 110 2h-3v3a1 1 0 11-2 0v-3H6a1 1 0 110-2h3V6a1 1 0 011-1z'></path>
-      </svg>
-      <span class='text-label-sm'>Add Item</span>
-    </button>
-
-    <button class='flex items-center gap-2 border border-neutral-medium px-4 py-2 rounded hover:bg-neutral-subtle'>
-      <svg class='size-icon-sm text-neutral-medium' fill='currentColor' viewBox='0 0 20 20'>
-        <path
-          fill-rule='evenodd'
-          d='M3 17a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zm3.293-7.707a1 1 0 011.414 0L9 10.586V3a1 1 0 112 0v7.586l1.293-1.293a1 1 0 111.414 1.414l-3 3a1 1 0 01-1.414 0l-3-3a1 1 0 010-1.414z'
-          clip-rule='evenodd'
-        ></path>
-      </svg>
-      <span class='text-label-sm text-neutral-strong'>Download</span>
-    </button>
-  </div>
-</template>
-```
-
-### List Items with Icons
-
-```gts preview
-<template>
-  <ul class='space-y-2'>
-    <li class='flex items-center gap-2'>
-      <svg class='size-icon-sm text-success-medium' fill='currentColor' viewBox='0 0 20 20'>
-        <path
-          fill-rule='evenodd'
-          d='M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z'
-          clip-rule='evenodd'
-        ></path>
-      </svg>
-      <span class='text-body-md'>Task completed successfully</span>
-    </li>
-    <li class='flex items-center gap-2'>
-      <svg class='size-icon-sm text-warning-medium' fill='currentColor' viewBox='0 0 20 20'>
-        <path
-          fill-rule='evenodd'
-          d='M10 18a8 8 0 100-16 8 8 0 000 16zM9 7a1 1 0 112 0v4a1 1 0 11-2 0V7zm1 8a1 1 0 100-2 1 1 0 000 2z'
-          clip-rule='evenodd'
-        ></path>
-      </svg>
-      <span class='text-body-md'>Warning: Review required</span>
-    </li>
-    <li class='flex items-center gap-2'>
-      <svg class='size-icon-sm text-danger-medium' fill='currentColor' viewBox='0 0 20 20'>
-        <path
-          fill-rule='evenodd'
-          d='M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z'
-          clip-rule='evenodd'
-        ></path>
-      </svg>
-      <span class='text-body-md'>Error: Action failed</span>
-    </li>
-  </ul>
-</template>
-```
-
-### Input Fields with Icons
-
-```gts preview
-<template>
-  <div class='space-y-3'>
-    <div class='relative'>
-      <svg
-        class='size-icon-sm text-neutral-soft absolute left-3 top-1/2 -translate-y-1/2'
-        fill='currentColor'
-        viewBox='0 0 20 20'
-      >
-        <path
-          fill-rule='evenodd'
-          d='M8 4a4 4 0 100 8 4 4 0 000-8zM2 8a6 6 0 1110.89 3.476l4.817 4.817a1 1 0 01-1.414 1.414l-4.816-4.816A6 6 0 012 8z'
-          clip-rule='evenodd'
-        ></path>
-      </svg>
-      <input
-        type='text'
-        placeholder='Search...'
-        class='w-full pl-10 pr-4 py-2 border border-neutral-medium rounded focus:outline-none focus:ring-2 focus:ring-brand-medium'
-      />
-    </div>
-  </div>
-</template>
-```
-
 ## Customization
 
 Override icon sizes using CSS variables in your `@theme` block:
diff --git a/docs/theming/design-tokens/typography.md b/docs/theming/design-tokens/typography.md
index e45fcc40..fe8806cb 100644
--- a/docs/theming/design-tokens/typography.md
+++ b/docs/theming/design-tokens/typography.md
@@ -28,10 +28,10 @@ Large, bold display text for hero sections and prominent headings.
 ```gts preview
 <template>
   <div class='flex flex-col gap-6'>
-    <div class='text-marquee-xl'>Marquee XL: Hero Heading</div>
-    <div class='text-marquee-lg'>Marquee LG: Large Display</div>
-    <div class='text-marquee-md'>Marquee MD: Medium Display</div>
-    <div class='text-marquee-sm'>Marquee SM: Small Display</div>
+    <div class='font-marquee text-marquee-xl'>Marquee XL: Hero Heading</div>
+    <div class='font-marquee text-marquee-lg'>Marquee LG: Large Display</div>
+    <div class='font-marquee text-marquee-md'>Marquee MD: Medium Display</div>
+    <div class='font-marquee text-marquee-sm'>Marquee SM: Small Display</div>
   </div>
 </template>
 ```
@@ -46,16 +46,16 @@ Semantic headings for content hierarchy with bold weight and condensed letter sp
 ```gts preview
 <template>
   <div class='flex flex-col gap-4'>
-    <h1 class='text-header-3xl'>Header 3XL: Page Title</h1>
-    <h2 class='text-header-2xl'>Header 2XL: Major Section</h2>
-    <h3 class='text-header-xl'>Header XL: Section Title</h3>
-    <h4 class='text-header-lg'>Header LG: Subsection</h4>
-    <h5 class='text-header-md'>Header MD: Subheading</h5>
-    <h6 class='text-header-sm'>Header SM: Minor Heading</h6>
-    <div class='text-header-xs'>Header XS: Small Heading</div>
-    <div class='text-header-2xs'>Header 2XS: Tiny Heading</div>
-    <div class='text-header-micro'>Header Micro: Micro Heading</div>
-    <div class='text-header-nano'>Header Nano: Nano Heading</div>
+    <h1 class='font-header text-header-3xl'>Header 3XL: Page Title</h1>
+    <h2 class='font-header text-header-2xl'>Header 2XL: Major Section</h2>
+    <h3 class='font-header text-header-xl'>Header XL: Section Title</h3>
+    <h4 class='font-header text-header-lg'>Header LG: Subsection</h4>
+    <h5 class='font-header text-header-md'>Header MD: Subheading</h5>
+    <h6 class='font-header text-header-sm'>Header SM: Minor Heading</h6>
+    <div class='font-header text-header-xs'>Header XS: Small Heading</div>
+    <div class='font-header text-header-2xs'>Header 2XS: Tiny Heading</div>
+    <div class='font-header text-header-micro'>Header Micro: Micro Heading</div>
+    <div class='font-header text-header-nano'>Header Nano: Nano Heading</div>
   </div>
 </template>
 ```
@@ -70,34 +70,34 @@ Standard body text with spacious line height optimized for readability.
 ```gts preview
 <template>
   <div class='flex flex-col gap-6'>
-    <p class='text-body-xl'>
+    <p class='font-body text-body-xl'>
       Body XL: The quick brown fox jumps over the lazy dog. This is extra large body text with spacious line height for comfortable reading.
     </p>
-    <p class='text-body-lg'>
+    <p class='font-body text-body-lg'>
       Body LG: The quick brown fox jumps over the lazy dog. This is large body text with spacious line height for comfortable reading.
     </p>
-    <p class='text-body-md'>
+    <p class='font-body text-body-md'>
       Body MD: The quick brown fox jumps over the lazy dog. This is default body text with spacious line height for comfortable reading.
     </p>
-    <p class='text-body-sm'>
+    <p class='font-body text-body-sm'>
       Body SM: The quick brown fox jumps over the lazy dog. This is small body text with spacious line height for comfortable reading.
     </p>
-    <p class='text-body-xs'>
+    <p class='font-body text-body-xs'>
       Body XS: The quick brown fox jumps over the lazy dog. This is extra small body text.
     </p>
-    <p class='text-body-2xs'>
+    <p class='font-body text-body-2xs'>
       Body 2XS: The quick brown fox jumps over the lazy dog. This is 2XS body text.
     </p>
-    <p class='text-body-3xs'>
+    <p class='font-body text-body-3xs'>
       Body 3XS: The quick brown fox jumps over the lazy dog. This is 3XS body text.
     </p>
-    <p class='text-body-micro'>
+    <p class='font-body text-body-micro'>
       Body Micro: The quick brown fox jumps over the lazy dog. This is micro body text.
     </p>
-    <p class='text-body-nano'>
+    <p class='font-body text-body-nano'>
       Body Nano: The quick brown fox jumps over the lazy dog. This is nano body text.
     </p>
-    <p class='text-body-pico'>
+    <p class='font-body text-body-pico'>
       Body Pico: The quick brown fox jumps over the lazy dog. This is pico body text.
     </p>
   </div>
@@ -114,10 +114,10 @@ Monospace text for code snippets and technical content.
 ```gts preview
 <template>
   <div class='flex flex-col gap-3'>
-    <code class='text-code-md bg-neutral-subtle px-2 py-1 rounded'>
+    <code class='font-code text-code-md bg-neutral-subtle px-2 py-1 rounded'>
       const greeting = "Hello, World!";
     </code>
-    <code class='text-code-sm bg-neutral-subtle px-2 py-1 rounded'>
+    <code class='font-code text-code-sm bg-neutral-subtle px-2 py-1 rounded'>
       npm install frontile
     </code>
   </div>
@@ -138,10 +138,10 @@ Secondary descriptive text with relaxed letter spacing.
       <div class='bg-neutral-subtle rounded mb-2 h-32 flex items-center justify-center text-neutral-soft'>
         Example Image
       </div>
-      <span class='text-caption-md text-neutral-soft'>Caption MD: Figure 1 - Example image caption with medium size</span>
+      <span class='font-caption text-caption-md text-neutral-soft'>Caption MD: Figure 1 - Example image caption with medium size</span>
     </div>
     <div>
-      <span class='text-caption-sm text-neutral-soft'>Caption SM: Small caption text for supplementary information</span>
+      <span class='font-caption text-caption-sm text-neutral-soft'>Caption SM: Small caption text for supplementary information</span>
     </div>
   </div>
 </template>
@@ -157,16 +157,16 @@ UI labels and form labels with bold weight and tight letter spacing.
 ```gts preview
 <template>
   <div class='flex flex-col gap-3'>
-    <div class='text-label-3xl'>Label 3XL: Extra Large Label</div>
-    <div class='text-label-2xl'>Label 2XL: Double Extra Large Label</div>
-    <div class='text-label-xl'>Label XL: Extra Large Label</div>
-    <div class='text-label-lg'>Label LG: Large Label</div>
-    <div class='text-label-md'>Label MD: Medium Label</div>
-    <div class='text-label-sm'>Label SM: Small Label</div>
-    <div class='text-label-xs'>Label XS: Extra Small Label</div>
-    <div class='text-label-2xs'>Label 2XS: Double Extra Small Label</div>
-    <div class='text-label-micro'>Label Micro: Micro Label</div>
-    <div class='text-label-nano'>Label Nano: Nano Label</div>
+    <div class='font-label text-label-3xl'>Label 3XL: Extra Large Label</div>
+    <div class='font-label text-label-2xl'>Label 2XL: Double Extra Large Label</div>
+    <div class='font-label text-label-xl'>Label XL: Extra Large Label</div>
+    <div class='font-label text-label-lg'>Label LG: Large Label</div>
+    <div class='font-label text-label-md'>Label MD: Medium Label</div>
+    <div class='font-label text-label-sm'>Label SM: Small Label</div>
+    <div class='font-label text-label-xs'>Label XS: Extra Small Label</div>
+    <div class='font-label text-label-2xs'>Label 2XS: Double Extra Small Label</div>
+    <div class='font-label text-label-micro'>Label Micro: Micro Label</div>
+    <div class='font-label text-label-nano'>Label Nano: Nano Label</div>
   </div>
 </template>
 ```
@@ -174,20 +174,18 @@ UI labels and form labels with bold weight and tight letter spacing.
 **Available sizes:** `nano`, `micro`, `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`
 **Best for:** Form labels, UI labels, buttons, navigation items, badges
 
-## Default Sizes
+## Available Utilities
 
-Each text style category has a default size that can be used without specifying the size modifier:
+All text style utilities require both a font-family utility and a sized text style utility:
 
 ```html
-<!-- These are equivalent -->
-<h1 class="text-marquee">...</h1>
-<h1 class="text-marquee-md">...</h1>
-
-<h2 class="text-header">...</h2>
-<h2 class="text-header-md">...</h2>
-
-<p class="text-body">...</p>
-<p class="text-body-md">...</p>
+<!-- Complete typography requires both font-family and sized text style -->
+<h1 class="font-marquee text-marquee-xl">...</h1>
+<h2 class="font-header text-header-md">...</h2>
+<p class="font-body text-body-md">...</p>
+<code class="font-code text-code-sm">...</code>
+<span class="font-caption text-caption-md">...</span>
+<label class="font-label text-label-sm">...</label>
 ```
 
 ## Combining with Other Utilities
@@ -198,20 +196,20 @@ Typography utilities work seamlessly with other Tailwind utilities:
 <template>
   <div class='flex flex-col gap-4'>
     {{! Colored header }}
-    <h2 class='text-header-xl text-brand-strong'>Colored Header</h2>
+    <h2 class='font-header text-header-xl text-brand-strong'>Colored Header</h2>
 
     {{! Truncated body text }}
-    <p class='text-body-md truncate max-w-md'>
+    <p class='font-body text-body-md truncate max-w-md'>
       This is a very long paragraph that will be truncated with an ellipsis when it exceeds the maximum width.
     </p>
 
     {{! Centered caption }}
-    <span class='text-caption-md text-center block text-neutral-soft'>
+    <span class='font-caption text-caption-md text-center block text-neutral-soft'>
       Centered caption text
     </span>
 
     {{! Responsive header }}
-    <h1 class='text-header-lg md:text-header-xl lg:text-header-2xl'>
+    <h1 class='font-header text-header-lg md:text-header-xl lg:text-header-2xl'>
       Responsive Heading
     </h1>
   </div>
@@ -220,36 +218,32 @@ Typography utilities work seamlessly with other Tailwind utilities:
 
 ## How It Works
 
-The typography system uses a two-part approach:
+The typography system uses Tailwind v4's `@theme` directive to automatically generate utilities from CSS variables:
 
-1. **Base tokens** defined in `@theme` provide the foundation (font families, weights, sizes, etc.)
-2. **Composite utilities** defined in `@layer utilities` bundle these tokens into semantic text styles
+1. **Base tokens** defined in `@theme` automatically generate individual utilities:
+   - `--font-header` → `font-header` utility
+   - `--font-size-14` → `text-14` utility
+   - `--font-weight-bold` → `font-bold` utility
+   - `--letter-spacing-condensed` → `tracking-condensed` utility
+   - `--line-height-comfy` → `leading-comfy` utility
 
-Each text utility is explicitly defined to combine all typography properties:
+2. **Composite text style tokens** generate size/weight/spacing utilities (but NOT font-family):
+   - `--text-header-md` → `text-header-md` utility (sets size, weight, spacing, line-height)
+   - `--text-body-lg` → `text-body-lg` utility (sets size, weight, spacing, line-height)
 
-```css
-@theme {
-  /* Base typography tokens */
-  --font-family-header: "Open Sans";
-  --font-size-14: 1.14rem;
-  --font-weight-bold: 700;
-  --letter-spacing-condensed: -0.0625rem;
-  --line-height-comfy: 1.4;
-}
+**Usage pattern:** Combine font-family with text style for complete typography:
 
-@layer utilities {
-  /* Composite utility that references base tokens */
-  .text-header-md {
-    font-size: var(--font-size-14);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-comfy);
-  }
-}
+```html
+<!-- ✓ Correct: Combine font-family with text style -->
+<h2 class="font-header text-header-md">Heading Text</h2>
+<p class="font-body text-body-lg">Body text with larger size</p>
+<span class="font-label text-label-sm">Small label</span>
+
+<!-- ✗ Incomplete: Missing font-family -->
+<h2 class="text-header-md">Heading Text</h2>
 ```
 
-When you use `.text-header-md`, all five typography properties are applied together as a cohesive style. The system uses a modular scale (ratio: 1.067) to ensure harmonious sizing relationships across all text styles.
+The separation of font-family from text styles provides flexibility to mix font families with different text styles while maintaining consistent sizing, weight, spacing, and line-height.
 
 ## Customization
 
@@ -262,9 +256,9 @@ Customize typography by overriding CSS variables in your app's CSS file:
 
 /* Override font families */
 @theme {
-  --font-family-header: "Inter", system-ui, sans-serif;
-  --font-family-body: "Inter", system-ui, sans-serif;
-  --font-family-code: "JetBrains Mono", monospace;
+  --font-header: "Inter", system-ui, sans-serif;
+  --font-body: "Inter", system-ui, sans-serif;
+  --font-code: "JetBrains Mono", monospace;
 }
 ```
 
@@ -276,13 +270,13 @@ Customize for light and dark themes using theme selectors:
 /* Light theme customization */
 .light,
 .dark .theme-inverse {
-  --font-family-body: "Inter", system-ui, sans-serif;
+  --font-body: "Inter", system-ui, sans-serif;
 }
 
 /* Dark theme customization */
 .dark,
 .light .theme-inverse {
-  --font-family-body: "Geist", system-ui, sans-serif;
+  --font-body: "Geist", system-ui, sans-serif;
 }
 ```
 
@@ -299,9 +293,9 @@ Add custom fonts by declaring them with `@font-face` and overriding the font fam
 }
 
 @theme {
-  --font-family-header: 'Inter', system-ui, sans-serif;
-  --font-family-body: 'Inter', system-ui, sans-serif;
-  --font-family-label: 'Inter', system-ui, sans-serif;
+  --font-header: 'Inter', system-ui, sans-serif;
+  --font-body: 'Inter', system-ui, sans-serif;
+  --font-label: 'Inter', system-ui, sans-serif;
 }
 ```
 
@@ -315,7 +309,7 @@ Always prefer semantic text style utilities over combining individual properties
 <template>
   <div class='flex flex-col gap-4'>
     {{! Good - semantic text style }}
-    <h2 class='text-header-lg text-brand-strong'>
+    <h2 class='font-header text-header-lg text-brand-strong'>
       ✓ Semantic: Easy to maintain
     </h2>
 
@@ -334,21 +328,21 @@ Use size variants to create clear content hierarchy:
 ```gts preview
 <template>
   <article class='space-y-4'>
-    <h1 class='text-header-3xl text-neutral-strong'>Article Title</h1>
-    <p class='text-body-md text-neutral-soft'>Published on December 7, 2024</p>
+    <h1 class='font-header text-header-3xl text-neutral-strong'>Article Title</h1>
+    <p class='font-body text-body-md text-neutral-soft'>Published on December 7, 2024</p>
 
     <div class='space-y-3'>
-      <h2 class='text-header-xl text-neutral-strong'>Major Section</h2>
-      <p class='text-body-md text-neutral-medium'>
+      <h2 class='font-header text-header-xl text-neutral-strong'>Major Section</h2>
+      <p class='font-body text-body-md text-neutral-medium'>
         This is the main body content with comfortable line height for easy reading. The text flows naturally and maintains good readability.
       </p>
 
-      <h3 class='text-header-lg text-neutral-strong'>Subsection</h3>
-      <p class='text-body-md text-neutral-medium'>
+      <h3 class='font-header text-header-lg text-neutral-strong'>Subsection</h3>
+      <p class='font-body text-body-md text-neutral-medium'>
         Subsection content continues the hierarchy with appropriately sized headers.
       </p>
 
-      <span class='text-caption-sm text-neutral-soft block'>
+      <span class='font-caption text-caption-sm text-neutral-soft block'>
         Figure 1: Caption providing additional context
       </span>
     </div>
@@ -363,10 +357,10 @@ Scale typography for different screen sizes:
 ```gts preview
 <template>
   <div class='space-y-4'>
-    <h1 class='text-header-lg md:text-header-xl lg:text-header-2xl text-neutral-strong'>
+    <h1 class='font-header text-header-lg md:text-header-xl lg:text-header-2xl text-neutral-strong'>
       Responsive Heading
     </h1>
-    <p class='text-body-sm md:text-body-md lg:text-body-lg text-neutral-medium'>
+    <p class='font-body text-body-sm md:text-body-md lg:text-body-lg text-neutral-medium'>
       Body text that scales up on larger screens for better readability across all devices.
     </p>
   </div>
diff --git a/packages/theme/src/styles/typography.css b/packages/theme/src/styles/typography.css
index 27071c30..b322205b 100644
--- a/packages/theme/src/styles/typography.css
+++ b/packages/theme/src/styles/typography.css
@@ -1,17 +1,24 @@
-/**
+/*
  * Tailwind CSS v4 Typography Configuration
+ *
+ * Defines base typography tokens that Tailwind v4 automatically converts to utilities:
+ * - font-{family}      → font-family utilities (e.g., font-body, font-header)
+ * - text-{size}        → font-size utilities (e.g., text-12, text-16)
+ * - font-{weight}      → font-weight utilities (e.g., font-regular, font-bold)
+ * - tracking-{spacing} → letter-spacing utilities (e.g., tracking-default, tracking-tight)
+ * - leading-{height}   → line-height utilities (e.g., leading-spacious, leading-tight)
  */
 
 @theme {
   /* ==================== Base Typography Tokens ==================== */
 
   /* Font Families */
-  --font-family-marquee: "STIX Two Text";
-  --font-family-header: "Open Sans";
-  --font-family-body: "Open Sans";
-  --font-family-code: "Source Code Pro";
-  --font-family-caption: "Open Sans";
-  --font-family-label: "Open Sans";
+  --font-marquee: "STIX Two Text";
+  --font-header: "Open Sans";
+  --font-body: "Open Sans";
+  --font-code: "Source Code Pro";
+  --font-caption: "Open Sans";
+  --font-label: "Open Sans";
 
   /* Font Weights */
   --font-weight-regular: 400;
@@ -75,375 +82,210 @@
   --font-size-32: calc(var(--font-size-31) * var(--typescale-ratio)); /* typescale-32 */
   --font-size-33: calc(var(--font-size-32) * var(--typescale-ratio)); /* typescale-33 */
   --font-size-34: calc(var(--font-size-33) * var(--typescale-ratio)); /* typescale-34 */
-}
 
-/* ==================== Text Style Utilities ==================== */
-/* Composite utilities that apply all typography properties together */
-/* These directly reference base tokens from @theme */
-
-@layer utilities {
-  /* marquee text style utilities */
-  .text-marquee-sm {
-    font-size: var(--font-size-23);
-    font-family: var(--font-family-marquee);
-    font-weight: var(--font-weight-semibold);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-tight);
-  }
-
-  .text-marquee-md {
-    font-size: var(--font-size-26);
-    font-family: var(--font-family-marquee);
-    font-weight: var(--font-weight-semibold);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-tight);
-  }
-
-  .text-marquee-lg {
-    font-size: var(--font-size-29);
-    font-family: var(--font-family-marquee);
-    font-weight: var(--font-weight-semibold);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-tight);
-  }
-
-  .text-marquee-xl {
-    font-size: var(--font-size-31);
-    font-family: var(--font-family-marquee);
-    font-weight: var(--font-weight-semibold);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-tight);
-  }
-
-  /* Default marquee utility (maps to md) */
-  .text-marquee {
-    font-size: var(--font-size-26);
-    font-family: var(--font-family-marquee);
-    font-weight: var(--font-weight-semibold);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-tight);
-  }
-
-  /* header text style utilities */
-  .text-header-2xs {
-    font-size: var(--font-size-8);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-comfy);
-  }
-
-  .text-header-micro {
-    font-size: var(--font-size-5);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-comfy);
-  }
-
-  .text-header-nano {
-    font-size: var(--font-size-3);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-comfy);
-  }
-
-  .text-header-xs {
-    font-size: var(--font-size-10);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-comfy);
-  }
-
-  .text-header-sm {
-    font-size: var(--font-size-12);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-comfy);
-  }
-
-  .text-header-md {
-    font-size: var(--font-size-14);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-comfy);
-  }
-
-  .text-header-lg {
-    font-size: var(--font-size-17);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-tight);
-  }
-
-  .text-header-xl {
-    font-size: var(--font-size-19);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-tight);
-  }
-
-  .text-header-2xl {
-    font-size: var(--font-size-23);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-tight);
-  }
-
-  .text-header-3xl {
-    font-size: var(--font-size-26);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-tight);
-  }
-
-  /* Default header utility (maps to md) */
-  .text-header {
-    font-size: var(--font-size-14);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-comfy);
-  }
-
-  /* body text style utilities */
-  .text-body-2xs {
-    font-size: var(--font-size-10);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-body-3xs {
-    font-size: var(--font-size-9);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-body-micro {
-    font-size: var(--font-size-8);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-body-nano {
-    font-size: var(--font-size-7);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-body-pico {
-    font-size: var(--font-size-6);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-body-xs {
-    font-size: var(--font-size-12);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-body-sm {
-    font-size: var(--font-size-14);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-body-md {
-    font-size: var(--font-size-16);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-body-lg {
-    font-size: var(--font-size-18);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-body-xl {
-    font-size: var(--font-size-21);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  /* Default body utility (maps to md) */
-  .text-body {
-    font-size: var(--font-size-16);
-    font-family: var(--font-family-body);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  /* code text style utilities */
-  .text-code-sm {
-    font-size: var(--font-size-10);
-    font-family: var(--font-family-code);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-code-md {
-    font-size: var(--font-size-12);
-    font-family: var(--font-family-code);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  /* Default code utility (maps to md) */
-  .text-code {
-    font-size: var(--font-size-12);
-    font-family: var(--font-family-code);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-default);
-    line-height: var(--line-height-spacious);
-  }
-
-  /* caption text style utilities */
-  .text-caption-sm {
-    font-size: var(--font-size-8);
-    font-family: var(--font-family-caption);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-relaxed);
-    line-height: var(--line-height-spacious);
-  }
-
-  .text-caption-md {
-    font-size: var(--font-size-10);
-    font-family: var(--font-family-caption);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-relaxed);
-    line-height: var(--line-height-spacious);
-  }
-
-  /* Default caption utility (maps to md) */
-  .text-caption {
-    font-size: var(--font-size-10);
-    font-family: var(--font-family-caption);
-    font-weight: var(--font-weight-regular);
-    letter-spacing: var(--letter-spacing-relaxed);
-    line-height: var(--line-height-spacious);
-  }
-
-  /* label text style utilities */
-  .text-label-2xs {
-    font-size: var(--font-size-8);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-tight);
-    line-height: var(--line-height-single);
-  }
-
-  .text-label-micro {
-    font-size: var(--font-size-5);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-tight);
-    line-height: var(--line-height-single);
-  }
-
-  .text-label-nano {
-    font-size: var(--font-size-3);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-condensed);
-    line-height: var(--line-height-comfy);
-  }
-
-  .text-label-xs {
-    font-size: var(--font-size-10);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-tight);
-    line-height: var(--line-height-single);
-  }
-
-  .text-label-sm {
-    font-size: var(--font-size-12);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-tight);
-    line-height: var(--line-height-single);
-  }
-
-  .text-label-md {
-    font-size: var(--font-size-14);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-tight);
-    line-height: var(--line-height-single);
-  }
-
-  .text-label-lg {
-    font-size: var(--font-size-17);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-tight);
-    line-height: var(--line-height-single);
-  }
-
-  .text-label-xl {
-    font-size: var(--font-size-19);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-tight);
-    line-height: var(--line-height-single);
-  }
-
-  .text-label-2xl {
-    font-size: var(--font-size-23);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-tight);
-    line-height: var(--line-height-single);
-  }
-
-  .text-label-3xl {
-    font-size: var(--font-size-26);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-tight);
-    line-height: var(--line-height-single);
-  }
-
-  /* Default label utility (maps to md) */
-  .text-label {
-    font-size: var(--font-size-14);
-    font-family: var(--font-family-header);
-    font-weight: var(--font-weight-bold);
-    letter-spacing: var(--letter-spacing-tight);
-    line-height: var(--line-height-single);
-  }
+  /* ==================== Text Style Tokens ==================== */
+  /* Composite text styles (without font-family for flexibility) */
+  /* Usage: Apply font-family separately, then use text style tokens */
+
+  /* marquee text styles */
+  --text-marquee-sm: var(--font-size-23);
+  --text-marquee-sm--font-weight: var(--font-weight-semibold);
+  --text-marquee-sm--letter-spacing: var(--letter-spacing-default);
+  --text-marquee-sm--line-height: var(--line-height-tight);
+
+  --text-marquee-md: var(--font-size-26);
+  --text-marquee-md--font-weight: var(--font-weight-semibold);
+  --text-marquee-md--letter-spacing: var(--letter-spacing-default);
+  --text-marquee-md--line-height: var(--line-height-tight);
+
+  --text-marquee-lg: var(--font-size-29);
+  --text-marquee-lg--font-weight: var(--font-weight-semibold);
+  --text-marquee-lg--letter-spacing: var(--letter-spacing-default);
+  --text-marquee-lg--line-height: var(--line-height-tight);
+
+  --text-marquee-xl: var(--font-size-31);
+  --text-marquee-xl--font-weight: var(--font-weight-semibold);
+  --text-marquee-xl--letter-spacing: var(--letter-spacing-default);
+  --text-marquee-xl--line-height: var(--line-height-tight);
+
+
+  /* header text styles */
+  --text-header-2xs: var(--font-size-8);
+  --text-header-2xs--font-weight: var(--font-weight-bold);
+  --text-header-2xs--letter-spacing: var(--letter-spacing-condensed);
+  --text-header-2xs--line-height: var(--line-height-comfy);
+
+  --text-header-micro: var(--font-size-5);
+  --text-header-micro--font-weight: var(--font-weight-bold);
+  --text-header-micro--letter-spacing: var(--letter-spacing-condensed);
+  --text-header-micro--line-height: var(--line-height-comfy);
+
+  --text-header-nano: var(--font-size-3);
+  --text-header-nano--font-weight: var(--font-weight-bold);
+  --text-header-nano--letter-spacing: var(--letter-spacing-condensed);
+  --text-header-nano--line-height: var(--line-height-comfy);
+
+  --text-header-xs: var(--font-size-10);
+  --text-header-xs--font-weight: var(--font-weight-bold);
+  --text-header-xs--letter-spacing: var(--letter-spacing-condensed);
+  --text-header-xs--line-height: var(--line-height-comfy);
+
+  --text-header-sm: var(--font-size-12);
+  --text-header-sm--font-weight: var(--font-weight-bold);
+  --text-header-sm--letter-spacing: var(--letter-spacing-condensed);
+  --text-header-sm--line-height: var(--line-height-comfy);
+
+  --text-header-md: var(--font-size-14);
+  --text-header-md--font-weight: var(--font-weight-bold);
+  --text-header-md--letter-spacing: var(--letter-spacing-condensed);
+  --text-header-md--line-height: var(--line-height-comfy);
+
+  --text-header-lg: var(--font-size-17);
+  --text-header-lg--font-weight: var(--font-weight-bold);
+  --text-header-lg--letter-spacing: var(--letter-spacing-condensed);
+  --text-header-lg--line-height: var(--line-height-tight);
+
+  --text-header-xl: var(--font-size-19);
+  --text-header-xl--font-weight: var(--font-weight-bold);
+  --text-header-xl--letter-spacing: var(--letter-spacing-condensed);
+  --text-header-xl--line-height: var(--line-height-tight);
+
+  --text-header-2xl: var(--font-size-23);
+  --text-header-2xl--font-weight: var(--font-weight-bold);
+  --text-header-2xl--letter-spacing: var(--letter-spacing-condensed);
+  --text-header-2xl--line-height: var(--line-height-tight);
+
+  --text-header-3xl: var(--font-size-26);
+  --text-header-3xl--font-weight: var(--font-weight-bold);
+  --text-header-3xl--letter-spacing: var(--letter-spacing-condensed);
+  --text-header-3xl--line-height: var(--line-height-tight);
+
+
+  /* body text styles */
+  --text-body-2xs: var(--font-size-10);
+  --text-body-2xs--font-weight: var(--font-weight-regular);
+  --text-body-2xs--letter-spacing: var(--letter-spacing-default);
+  --text-body-2xs--line-height: var(--line-height-spacious);
+
+  --text-body-3xs: var(--font-size-9);
+  --text-body-3xs--font-weight: var(--font-weight-regular);
+  --text-body-3xs--letter-spacing: var(--letter-spacing-default);
+  --text-body-3xs--line-height: var(--line-height-spacious);
+
+  --text-body-micro: var(--font-size-8);
+  --text-body-micro--font-weight: var(--font-weight-regular);
+  --text-body-micro--letter-spacing: var(--letter-spacing-default);
+  --text-body-micro--line-height: var(--line-height-spacious);
+
+  --text-body-nano: var(--font-size-7);
+  --text-body-nano--font-weight: var(--font-weight-regular);
+  --text-body-nano--letter-spacing: var(--letter-spacing-default);
+  --text-body-nano--line-height: var(--line-height-spacious);
+
+  --text-body-pico: var(--font-size-6);
+  --text-body-pico--font-weight: var(--font-weight-regular);
+  --text-body-pico--letter-spacing: var(--letter-spacing-default);
+  --text-body-pico--line-height: var(--line-height-spacious);
+
+  --text-body-xs: var(--font-size-12);
+  --text-body-xs--font-weight: var(--font-weight-regular);
+  --text-body-xs--letter-spacing: var(--letter-spacing-default);
+  --text-body-xs--line-height: var(--line-height-spacious);
+
+  --text-body-sm: var(--font-size-14);
+  --text-body-sm--font-weight: var(--font-weight-regular);
+  --text-body-sm--letter-spacing: var(--letter-spacing-default);
+  --text-body-sm--line-height: var(--line-height-spacious);
+
+  --text-body-md: var(--font-size-16);
+  --text-body-md--font-weight: var(--font-weight-regular);
+  --text-body-md--letter-spacing: var(--letter-spacing-default);
+  --text-body-md--line-height: var(--line-height-spacious);
+
+  --text-body-lg: var(--font-size-18);
+  --text-body-lg--font-weight: var(--font-weight-regular);
+  --text-body-lg--letter-spacing: var(--letter-spacing-default);
+  --text-body-lg--line-height: var(--line-height-spacious);
+
+  --text-body-xl: var(--font-size-21);
+  --text-body-xl--font-weight: var(--font-weight-regular);
+  --text-body-xl--letter-spacing: var(--letter-spacing-default);
+  --text-body-xl--line-height: var(--line-height-spacious);
+
+
+  /* code text styles */
+  --text-code-sm: var(--font-size-10);
+  --text-code-sm--font-weight: var(--font-weight-regular);
+  --text-code-sm--letter-spacing: var(--letter-spacing-default);
+  --text-code-sm--line-height: var(--line-height-spacious);
+
+  --text-code-md: var(--font-size-12);
+  --text-code-md--font-weight: var(--font-weight-regular);
+  --text-code-md--letter-spacing: var(--letter-spacing-default);
+  --text-code-md--line-height: var(--line-height-spacious);
+
+
+  /* caption text styles */
+  --text-caption-sm: var(--font-size-8);
+  --text-caption-sm--font-weight: var(--font-weight-regular);
+  --text-caption-sm--letter-spacing: var(--letter-spacing-relaxed);
+  --text-caption-sm--line-height: var(--line-height-spacious);
+
+  --text-caption-md: var(--font-size-10);
+  --text-caption-md--font-weight: var(--font-weight-regular);
+  --text-caption-md--letter-spacing: var(--letter-spacing-relaxed);
+  --text-caption-md--line-height: var(--line-height-spacious);
+
+
+  /* label text styles */
+  --text-label-2xs: var(--font-size-8);
+  --text-label-2xs--font-weight: var(--font-weight-bold);
+  --text-label-2xs--letter-spacing: var(--letter-spacing-tight);
+  --text-label-2xs--line-height: var(--line-height-single);
+
+  --text-label-micro: var(--font-size-5);
+  --text-label-micro--font-weight: var(--font-weight-bold);
+  --text-label-micro--letter-spacing: var(--letter-spacing-tight);
+  --text-label-micro--line-height: var(--line-height-single);
+
+  --text-label-nano: var(--font-size-3);
+  --text-label-nano--font-weight: var(--font-weight-bold);
+  --text-label-nano--letter-spacing: var(--letter-spacing-condensed);
+  --text-label-nano--line-height: var(--line-height-comfy);
+
+  --text-label-xs: var(--font-size-10);
+  --text-label-xs--font-weight: var(--font-weight-bold);
+  --text-label-xs--letter-spacing: var(--letter-spacing-tight);
+  --text-label-xs--line-height: var(--line-height-single);
+
+  --text-label-sm: var(--font-size-12);
+  --text-label-sm--font-weight: var(--font-weight-bold);
+  --text-label-sm--letter-spacing: var(--letter-spacing-tight);
+  --text-label-sm--line-height: var(--line-height-single);
+
+  --text-label-md: var(--font-size-14);
+  --text-label-md--font-weight: var(--font-weight-bold);
+  --text-label-md--letter-spacing: var(--letter-spacing-tight);
+  --text-label-md--line-height: var(--line-height-single);
+
+  --text-label-lg: var(--font-size-17);
+  --text-label-lg--font-weight: var(--font-weight-bold);
+  --text-label-lg--letter-spacing: var(--letter-spacing-tight);
+  --text-label-lg--line-height: var(--line-height-single);
+
+  --text-label-xl: var(--font-size-19);
+  --text-label-xl--font-weight: var(--font-weight-bold);
+  --text-label-xl--letter-spacing: var(--letter-spacing-tight);
+  --text-label-xl--line-height: var(--line-height-single);
+
+  --text-label-2xl: var(--font-size-23);
+  --text-label-2xl--font-weight: var(--font-weight-bold);
+  --text-label-2xl--letter-spacing: var(--letter-spacing-tight);
+  --text-label-2xl--line-height: var(--line-height-single);
+
+  --text-label-3xl: var(--font-size-26);
+  --text-label-3xl--font-weight: var(--font-weight-bold);
+  --text-label-3xl--letter-spacing: var(--letter-spacing-tight);
+  --text-label-3xl--line-height: var(--line-height-single);
 
 }
diff --git a/packages/theme/src/tw.ts b/packages/theme/src/tw.ts
index ead1da0e..3a16068d 100644
--- a/packages/theme/src/tw.ts
+++ b/packages/theme/src/tw.ts
@@ -1,6 +1,6 @@
 import { extendTailwindMerge } from 'tailwind-merge';
+import { createTV } from 'tailwind-variants';
 import type { ClassValue } from 'tailwind-variants';
-export { tv } from 'tailwind-variants';
 export type { VariantProps } from 'tailwind-variants';
 
 function flat(arr: ClassValue[], target: ClassValue[]): void {
@@ -23,9 +23,62 @@ const clsx = (...classes: ClassValue[]): string | undefined => {
   return voidEmpty(flatArray(classes).filter(Boolean).join(' '));
 };
 
-// This is empty for now as we don't have any configuration
-const twMergeConfig = {};
-const twMergeBase = extendTailwindMerge({ extend: twMergeConfig });
+// Common size units used across all design tokens (icons, typography, etc.)
+const COMMON_UNITS = [
+  'pico',
+  'nano',
+  'micro',
+  '3xs',
+  '2xs',
+  'xs',
+  'sm',
+  'md',
+  'lg',
+  'xl',
+  '2xl',
+  '3xl',
+  'kilo',
+  'mega'
+] as const;
+
+const ELEVATION_LEVELS = ['0', '1', '2', '3', '4', '5'];
+
+const twMergeConfig = {
+  extend: {
+    classGroups: {
+      // Icon sizes
+      'icon-size': [{ 'size-icon': COMMON_UNITS }],
+
+      // Border widths (directional variants handled automatically)
+      'border-w': [{ border: ['thin', 'heavy', 'aggressive'] }],
+
+      // Border radius (extend existing rounded utilities)
+      rounded: [{ rounded: ['default', 'pill'] }],
+
+      // Elevation shadows
+      shadow: [{ 'shadow-elevation': ELEVATION_LEVELS }],
+
+      // Opacity
+      opacity: [{ opacity: ['hover', 'disabled'] }],
+
+      // Typography composite text styles (extend font-size class group)
+      // These set font-size + other properties, so they should conflict with text-* utilities
+      'font-size': [
+        { 'text-marquee': [...COMMON_UNITS] },
+        { 'text-header': [...COMMON_UNITS] },
+        { 'text-body': [...COMMON_UNITS] },
+        { 'text-code': [...COMMON_UNITS] },
+        { 'text-caption': [...COMMON_UNITS] },
+        { 'text-label': [...COMMON_UNITS] }
+      ]
+    },
+    conflictingClassGroups: {
+      'icon-size': ['w', 'h', 'size']
+    }
+  }
+} as const;
+
+const twMergeBase = extendTailwindMerge<'icon-size'>(twMergeConfig);
 
 export function twMerge(defaultClass: ClassValue, overwrites: ClassValue) {
   if (overwrites) {
@@ -33,3 +86,8 @@ export function twMerge(defaultClass: ClassValue, overwrites: ClassValue) {
   }
   return clsx(defaultClass);
 }
+
+export const tv = createTV({
+  twMerge: true,
+  twMergeConfig
+});
diff --git a/site/app/components/icons.gts b/site/app/components/icons.gts
index b3ff17f3..6e132028 100644
--- a/site/app/components/icons.gts
+++ b/site/app/components/icons.gts
@@ -9,7 +9,7 @@ export const ViewIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-4 h-4"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -32,7 +32,7 @@ export const EditIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-4 h-4"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -50,7 +50,7 @@ export const DuplicateIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-4 h-4"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -68,7 +68,7 @@ export const ShareIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-4 h-4"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -86,7 +86,7 @@ export const DownloadIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-4 h-4"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -104,7 +104,7 @@ export const ArchiveIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-4 h-4"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -122,7 +122,7 @@ export const DeleteIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-4 h-4"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -140,7 +140,7 @@ export const ChevronDownIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-5 h-5"
+    class="size-icon-md"
     ...attributes
   >
     <path
@@ -158,7 +158,7 @@ export const StarIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -176,7 +176,7 @@ export const SearchIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="size-5"
+    class="size-icon-md"
     ...attributes
   >
     <path
@@ -192,7 +192,7 @@ export const SunIcon = <template>
     xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 24 24"
     fill="currentColor"
-    class="size-4"
+    class="size-icon-sm"
     ...attributes
   >
     <path
@@ -206,7 +206,7 @@ export const MoonIcon = <template>
     xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 24 24"
     fill="currentColor"
-    class="size-4"
+    class="size-icon-sm"
     ...attributes
   >
     <path
@@ -218,7 +218,12 @@ export const MoonIcon = <template>
 </template>;
 
 export const UserIcon = <template>
-  <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 20 20" ...attributes>
+  <svg
+    fill="currentColor"
+    viewBox="0 0 20 20"
+    class="size-icon-sm"
+    ...attributes
+  >
     <path
       fill-rule="evenodd"
       d="M10 9a3 3 0 100-6 3 3 0 000 6zm-7 9a7 7 0 1114 0H3z"
@@ -234,7 +239,7 @@ export const CheckIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="2"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -252,7 +257,7 @@ export const CodeIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -270,7 +275,7 @@ export const PaletteIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -288,7 +293,7 @@ export const BookIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -306,7 +311,7 @@ export const TargetIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -329,7 +334,7 @@ export const AccessibilityIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -347,7 +352,7 @@ export const SparklesIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -365,7 +370,7 @@ export const ComponentIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -383,7 +388,7 @@ export const PackageIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -401,7 +406,7 @@ export const RocketIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-6 h-6"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -419,7 +424,7 @@ export const SettingsIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-4 h-4"
+    class="size-icon-lg"
     ...attributes
   >
     <path
@@ -442,7 +447,7 @@ export const LogoutIcon = <template>
     viewBox="0 0 24 24"
     stroke-width="1.5"
     stroke="currentColor"
-    class="w-4 h-4"
+    class="size-icon-lg"
     ...attributes
   >
     <path
diff --git a/site/app/helpers/tw-merge.ts b/site/app/helpers/tw-merge.ts
new file mode 100644
index 00000000..5529cb4e
--- /dev/null
+++ b/site/app/helpers/tw-merge.ts
@@ -0,0 +1,9 @@
+import { helper } from '@ember/component/helper';
+import { twMerge } from '@frontile/theme';
+
+export default helper(function twMergeHelper([defaultClass, overrides]: [
+  string,
+  string,
+]) {
+  return twMerge(defaultClass, overrides);
+});