diff --git a/.changeset/fuzzy-berries-do.md b/.changeset/fuzzy-berries-do.md
new file mode 100644
index 0000000..a286108
--- /dev/null
+++ b/.changeset/fuzzy-berries-do.md
@@ -0,0 +1,5 @@
+---
+'commerce-toolkit': minor
+---
+
+Feat: simplified CSS variables available for customizing components
diff --git a/.cursor/commands/create-story.md b/.cursor/commands/create-story.md
index 19f81c8..9d73eb8 100644
--- a/.cursor/commands/create-story.md
+++ b/.cursor/commands/create-story.md
@@ -16,6 +16,94 @@ Our composable components allow for custom CSS classes to be passed in to overri
 
 Do not provide too many examples. Focus on examples that highlight the monolith component and the interface it exposes. A composable example that simply highlights how to use them is fine, but try and limit the amount of customization.
 
+## Code preview source
+
+Stories using `render` functions (especially with hooks like `useState`) show the raw story object in Storybook's "Show code" feature. To display clean React code instead, add a `source` parameter:
+
+```tsx
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A controlled component example.',
+      },
+      source: {
+        code: `
+const [value, setValue] = useState(false);
+
+<Component checked={value} onChange={setValue} />
+        `,
+      },
+    },
+  },
+  render: () => {
+    const [value, setValue] = useState(false);
+
+    return <Component checked={value} onChange={setValue} />;
+  },
+};
+```
+
+Always include `source.code` for stories that use `render` functions to ensure users see clean, copyable React code.
+
+## Container queries
+
+Components that use container queries (identified by `@container` class on the root and `@` prefixed breakpoints like `@lg:text-xl`) should document their responsive behavior. Include:
+
+1. **Documentation table** - Add a table in the component description showing what changes at each breakpoint:
+
+```markdown
+## Container Queries
+
+The component uses container queries to adapt based on container width.
+
+| Element | Below @lg | @lg and above |
+|---------|-----------|---------------|
+| Title | text-base | text-xl |
+| Content | text-sm | text-base |
+```
+
+2. **ContainerQueries story** - Create a story showing the component at different container sizes side by side:
+
+```tsx
+export const ContainerQueries: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <p className="mb-2 text-sm text-contrast-400">Small container (below @lg breakpoint)</p>
+        <div className="w-72">
+          <Component {...props} />
+        </div>
+      </div>
+      <div>
+        <p className="mb-2 text-sm text-contrast-400">Large container (at @lg breakpoint)</p>
+        <div className="w-[32rem]">
+          <Component {...props} />
+        </div>
+      </div>
+    </div>
+  ),
+};
+```
+
+### Tailwind container query breakpoints
+
+Use these default breakpoint widths when sizing containers:
+
+| Breakpoint | Width |
+|------------|-------|
+| `@xs` | 20rem (320px) |
+| `@sm` | 24rem (384px) |
+| `@md` | 28rem (448px) |
+| `@lg` | 32rem (512px) |
+| `@xl` | 36rem (576px) |
+| `@2xl` | 42rem (672px) |
+| `@3xl` | 48rem (768px) |
+| `@4xl` | 56rem (896px) |
+| `@5xl` | 64rem (1024px) |
+| `@6xl` | 72rem (1152px) |
+| `@7xl` | 80rem (1280px) |
+
 ## Product images
 
 Below are some product names and images you can use for examples:
diff --git a/.cursor/commands/organize-tailwind-classes.md b/.cursor/commands/organize-tailwind-classes.md
index 5c9461e..c61a006 100644
--- a/.cursor/commands/organize-tailwind-classes.md
+++ b/.cursor/commands/organize-tailwind-classes.md
@@ -1,6 +1,23 @@
 # Organize Tailwind Classes
 
-You are helping to organize long Tailwind CSS class strings into readable, grouped lines. Take a single long className string and break it into multiple lines within a `cn()` function call, with comments indicating the purpose of each group.
+You are helping to organize Tailwind CSS class strings into readable, maintainable code. The level of organization depends on the complexity of the component.
+
+## When to Use Which Approach
+
+### Simple Format (1-2 lines)
+Use when the className has:
+- **Fewer than ~15 total classes**, OR
+- **Minimal state variants** (0-1 state variants with just 1-2 classes each)
+
+Keep all classes on one line, or split into two lines (base + states) if it improves readability.
+
+### Detailed Grouping (multiple commented sections)
+Use when the className has:
+- **3+ state variants**, OR
+- **Any state variant with 3+ classes**, OR
+- **Complex modifiers** (e.g., `group-data-[*]`, multiple breakpoints per variant)
+
+Break into multiple commented sections for better maintainability.
 
 ## Grouping Strategy
 
@@ -25,7 +42,31 @@ Organize classes into logical groups in this order (skip groups that don't apply
 10. **Responsive** - breakpoint prefixes (`sm:*`, `md:*`, `lg:*`, `xl:*`, `2xl:*`)
 11. **Container queries** - `@*:` classes
 
-## Output Format
+## Simple Format Examples
+
+For simple components, keep classes concise:
+
+### Single line (very simple)
+
+```tsx
+className={cn('truncate text-sm font-semibold text-foreground', className)}
+```
+
+### Two lines (simple with minimal states)
+
+```tsx
+className={cn(
+  'flex items-center gap-1 rounded-md px-2 py-1 text-sm transition-colors',
+  'hover:bg-accent disabled:opacity-50',
+  className,
+)}
+```
+
+## Detailed Format Examples
+
+For complex components with many interactive states, use commented groupings:
+
+### Standard detailed format
 
 Use the `cn()` function with base styles on an uncommented first line, then state variants with comments:
 
@@ -44,9 +85,23 @@ className={cn(
 )}
 ```
 
-## Example Reference
+## Real-World Examples
+
+### Simple component (FileInputHeader)
+
+```tsx
+<div
+  className={cn(
+    'flex items-center gap-1 [font-family:var(--file-input-font-header,var(--font-body))]',
+    className,
+  )}
+  data-slot="file-input-header"
+>
+  {children}
+</div>
+```
 
-Here's a well-organized component to use as a reference:
+### Complex component (NavigationMenuTrigger)
 
 ```tsx
 <NavigationMenuPrimitive.Trigger
@@ -70,13 +125,15 @@ Here's a well-organized component to use as a reference:
 
 ## Rules
 
-1. **Preserve all classes** - Don't remove or modify any classes, just reorganize them
-2. **No comment for base styles** - The first line containing all base styles (layout, spacing, typography, colors, borders, effects, transitions) should have no comment
+1. **Assess complexity first** - Count total classes and state variants to determine whether to use simple or detailed format
+2. **Preserve all classes** - Don't remove or modify any classes, just reorganize them
 3. **Keep related classes together** - If there are multiple classes for the same state (e.g., `hover:bg-*` and `hover:text-*`), keep them on the same line
-4. **Use consistent comment style** - Use `// Comment` format for state variant group labels
-5. **End with className prop** - Always end with `className,` to allow external overrides
-6. **Split long state groups** - If a state group has many classes, split into multiple lines under the same comment section
-7. **Alphabetize within variants** - When multiple data attributes or modifiers exist, prefer alphabetical order (e.g., `data-[state=closed]` before `data-[state=open]`)
+4. **End with className prop** - Always end with `className,` to allow external overrides
+5. **For detailed format only:**
+   - No comment for base styles - The first line with base styles should have no comment
+   - Use consistent comment style - Use `// Comment` format for state variant group labels
+   - Split long state groups - If a state group has many classes, split into multiple lines under the same comment section
+   - Alphabetize within variants - When multiple data attributes or modifiers exist, prefer alphabetical order (e.g., `data-[state=closed]` before `data-[state=open]`)
 
 ## Handling Complex Modifiers
 
@@ -91,3 +148,11 @@ For complex modifiers like `group-data-[viewport=false]/navigation-menu:*`, crea
 // Container styling
 'group-data-[viewport=false]/navigation-menu:rounded-md group-data-[viewport=false]/navigation-menu:border',
 ```
+
+## Quick Decision Guide
+
+Ask yourself:
+1. Are there **15+ total classes**? → Likely needs detailed format
+2. Are there **3+ different state variants** (hover, focus, disabled, etc.)? → Use detailed format
+3. Does any single state variant have **3+ classes**? → Use detailed format
+4. Otherwise → Use simple format (1-2 lines)
diff --git a/.cursor/commands/resolve-conflicts.md b/.cursor/commands/resolve-conflicts.md
deleted file mode 100644
index 53e4d8b..0000000
--- a/.cursor/commands/resolve-conflicts.md
+++ /dev/null
@@ -1,45 +0,0 @@
-I'm rebasing my project and have a lot of conflicts to resolve. Most of the conflicts
-are from recent changes to CSS variables being renamed and simplifying how fallback
-variables are being passed into Tailwind classes.
-
-## Current Changes
-
-### Renamed CSS vars
-
-For example, you may see a current change like this:
-
---accordion-focus: var(--brand);
-
-And in the incoming change like this:
-
---accordion-focus: var(--primary);
-
-This above example is because we've renamed the --primary CSS variable to --brand.
-
-### Simplified fallbacks inside Tailwind
-
-There were some changes merged that simplified how we use inline and fallback variables
-in Tailwind classes.
-
-For example, you'll see classes like this in incoming changes:
-
-stroke-[var(--accordion-light-title-icon,hsl(var(--contrast-500)))]
-
-However, this has been simplified in current changes:
-
-stroke-[var(--accordion-light-title-icon,var(--contrast-500))]
-
-You'll notice that we're no longer needing to wrap the fallback in hsl() and can pass
-the variable directly.
-
-## Incoming changes
-
-The incoming change are from making sure consistent patterns are being applied 
-across all of our components. This includes things like organizing classes, applying
-Class Variance Authority, and ensuring component architecture like monolith 
-and composable components.
-
-## Your task
-
-Your task is to identify the current changes that need to be applied to the incoming
-changes.
\ No newline at end of file
diff --git a/.storybook/main.js b/.storybook/main.js
index b88a819..5dcf7e7 100644
--- a/.storybook/main.js
+++ b/.storybook/main.js
@@ -22,6 +22,7 @@ const config = {
     name: '@storybook/react-vite',
     options: {},
   },
+  staticDirs: ['../public'],
   async viteFinal(config) {
     return mergeConfig(config, {
       resolve: {
diff --git a/.storybook/preview-head.html b/.storybook/preview-head.html
new file mode 100644
index 0000000..548851e
--- /dev/null
+++ b/.storybook/preview-head.html
@@ -0,0 +1,22 @@
+<link
+  rel="preload"
+  href="/fonts/GeneralSans-Variable.woff2"
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+<link
+  rel="preload"
+  href="/fonts/GeneralSans-VariableItalic.woff2"
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+<link rel="preload" href="/fonts/InterVariable.woff2" as="font" type="font/woff2" crossorigin />
+<link
+  rel="preload"
+  href="/fonts/InterVariable-Italic.woff2"
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
diff --git a/.storybook/preview.css b/.storybook/preview.css
new file mode 100644
index 0000000..f1a35c1
--- /dev/null
+++ b/.storybook/preview.css
@@ -0,0 +1,33 @@
+/* Fonts for Storybook examples only - not exported with the library */
+
+@font-face {
+  font-family: 'Inter';
+  src: url('/fonts/InterVariable.woff2') format('woff2-variations');
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Inter';
+  src: url('/fonts/InterVariable-Italic.woff2') format('woff2-variations');
+  font-weight: 100 900;
+  font-style: italic;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'General Sans';
+  src: url('/fonts/GeneralSans-Variable.woff2') format('woff2-variations');
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'General Sans';
+  src: url('/fonts/GeneralSans-VariableItalic.woff2') format('woff2-variations');
+  font-weight: 100 900;
+  font-style: italic;
+  font-display: swap;
+}
diff --git a/.storybook/preview.js b/.storybook/preview.js
index c36b637..c34c785 100644
--- a/.storybook/preview.js
+++ b/.storybook/preview.js
@@ -1,4 +1,5 @@
 import '../src/globals.css';
+import './preview.css';
 
 const preview = {
   parameters: {
diff --git a/package.json b/package.json
index 2066df2..6fe7928 100644
--- a/package.json
+++ b/package.json
@@ -67,14 +67,14 @@
         "default": "./dist/button-radio-group.cjs"
       }
     },
-    "./blog-post-card": {
+    "./blog-card": {
       "import": {
-        "types": "./dist/components/blog-post-card/primitives.d.ts",
-        "default": "./dist/blog-post-card.js"
+        "types": "./dist/components/blog-card/primitives.d.ts",
+        "default": "./dist/blog-card.js"
       },
       "require": {
-        "types": "./dist/components/blog-post-card/primitives.d.ts",
-        "default": "./dist/blog-post-card.cjs"
+        "types": "./dist/components/blog-card/primitives.d.ts",
+        "default": "./dist/blog-card.cjs"
       }
     },
     "./button": {
@@ -481,7 +481,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "build:lib": "vite build --config vite.config.lib.js && tsc --project tsconfig.lib.json && resolve-tspaths -p tsconfig.lib.json && cp src/styles.css dist/styles.css",
+    "build:lib": "vite build --config vite.config.lib.js && tsc --project tsconfig.lib.json && resolve-tspaths -p tsconfig.lib.json && cp src/globals.css dist/styles.css",
     "lint": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
diff --git a/public/fonts/GeneralSans-Variable.woff2 b/public/fonts/GeneralSans-Variable.woff2
new file mode 100644
index 0000000..55e906b
Binary files /dev/null and b/public/fonts/GeneralSans-Variable.woff2 differ
diff --git a/public/fonts/GeneralSans-VariableItalic.woff2 b/public/fonts/GeneralSans-VariableItalic.woff2
new file mode 100644
index 0000000..5c1e1ca
Binary files /dev/null and b/public/fonts/GeneralSans-VariableItalic.woff2 differ
diff --git a/public/fonts/InterVariable-Italic.woff2 b/public/fonts/InterVariable-Italic.woff2
new file mode 100644
index 0000000..b3530f3
Binary files /dev/null and b/public/fonts/InterVariable-Italic.woff2 differ
diff --git a/public/fonts/InterVariable.woff2 b/public/fonts/InterVariable.woff2
new file mode 100644
index 0000000..5a8d3e7
Binary files /dev/null and b/public/fonts/InterVariable.woff2 differ
diff --git a/src/components/accordion/accordion.tsx b/src/components/accordion/accordion.tsx
index 31fac50..c3b85e3 100644
--- a/src/components/accordion/accordion.tsx
+++ b/src/components/accordion/accordion.tsx
@@ -30,20 +30,11 @@ export type AccordionProps = AccordionSingleProps | AccordionMultipleProps;
  *
  * ```css
  * :root {
- *   --accordion-focus: var(--brand);
- *   --accordion-offset: var(--background);
- *   --accordion-light-title-text: var(--contrast-400);
- *   --accordion-light-title-text-hover: var(--foreground);
- *   --accordion-light-title-icon: var(--contrast-500);
- *   --accordion-light-title-icon-hover: var(--foreground);
- *   --accordion-light-content-text: var(--foreground);
- *   --accordion-dark-title-text: var(--contrast-200);
- *   --accordion-dark-title-text-hover: var(--background);
- *   --accordion-dark-title-icon: var(--contrast-200);
- *   --accordion-dark-title-icon-hover: var(--background);
- *   --accordion-dark-content-text: var(--background);
- *   --accordion-title-font-family: var(--font-family-body);
- *   --accordion-content-font-family: var(--font-family-body);
+ *   --accordion-text-primary: var(--text-primary);
+ *   --accordion-text-secondary: var(--text-secondary);
+ *   --accordion-fill-icon: var(--contrast-400);
+ *   --accordion-font-title: var(--font-heading);
+ *   --accordion-font-body: var(--font-body);
  * }
  * ```
  */
@@ -59,7 +50,7 @@ export function Accordion({ className, items, ...props }: AccordionProps) {
             </AccordionPrimitive.Trigger>
           </AccordionPrimitive.Header>
           <AccordionPrimitive.Content>
-            <AccordionPrimitive.ContentArea>{content}</AccordionPrimitive.ContentArea>
+            <AccordionPrimitive.Body>{content}</AccordionPrimitive.Body>
           </AccordionPrimitive.Content>
         </AccordionPrimitive.Item>
       ))}
diff --git a/src/components/accordion/primitives.ts b/src/components/accordion/primitives.ts
index 70b0d3b..08bab2b 100644
--- a/src/components/accordion/primitives.ts
+++ b/src/components/accordion/primitives.ts
@@ -11,9 +11,9 @@ export {
   type AccordionContentProps as ContentProps,
 } from '@/components/accordion/primitives/accordion-content';
 export {
-  AccordionContentArea as ContentArea,
-  type AccordionContentAreaProps as ContentAreaProps,
-} from '@/components/accordion/primitives/accordion-content-area';
+  AccordionBody as Body,
+  type AccordionBodyProps as BodyProps,
+} from '@/components/accordion/primitives/accordion-body';
 export {
   AccordionHeader as Header,
   type AccordionHeaderProps as HeaderProps,
diff --git a/src/components/accordion/primitives/accordion-body.tsx b/src/components/accordion/primitives/accordion-body.tsx
new file mode 100644
index 0000000..f7b59d8
--- /dev/null
+++ b/src/components/accordion/primitives/accordion-body.tsx
@@ -0,0 +1,20 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type AccordionBodyProps = ComponentProps<'div'>;
+
+export function AccordionBody({ children, className, ...props }: AccordionBodyProps) {
+  return (
+    <div
+      className={cn(
+        '[font-family:--accordion-font-body,var(--font-body))] py-3 text-base text-[--accordion-text-primary,var(--text-secondary)]',
+        className,
+      )}
+      data-slot="accordion-body"
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
diff --git a/src/components/accordion/primitives/accordion-chevron.tsx b/src/components/accordion/primitives/accordion-chevron.tsx
index 265a1c8..7b7b9c0 100644
--- a/src/components/accordion/primitives/accordion-chevron.tsx
+++ b/src/components/accordion/primitives/accordion-chevron.tsx
@@ -8,9 +8,7 @@ export function AccordionChevron({ className, ...props }: AccordionChevronProps)
   return (
     <svg
       className={cn(
-        'mt-1 shrink-0 stroke-[var(--accordion-light-title-icon,var(--contrast-500))] [&>line]:origin-center [&>line]:transition [&>line]:duration-300 [&>line]:ease-out',
-        // Hover state
-        'group-hover/accordion:stroke-[var(--accordion-light-title-icon-hover,var(--foreground))]',
+        'mt-1 shrink-0 stroke-[--accordion-fill-icon,var(--contrast-400)] [&>line]:origin-center [&>line]:transition [&>line]:duration-300 [&>line]:ease-out',
         className,
       )}
       data-slot="accordion-chevron"
diff --git a/src/components/accordion/primitives/accordion-content-area.tsx b/src/components/accordion/primitives/accordion-content-area.tsx
deleted file mode 100644
index ca00507..0000000
--- a/src/components/accordion/primitives/accordion-content-area.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type AccordionContentAreaProps = ComponentProps<'div'>;
-
-export function AccordionContentArea({ children, className, ...props }: AccordionContentAreaProps) {
-  return (
-    <div
-      className={cn(
-        'py-3 text-base font-light leading-normal text-[var(--accordion-light-content-text,var(--foreground))] [font-family:var(--accordion-content-font-family,var(--font-family-body))]',
-
-        className,
-      )}
-      data-slot="accordion-content-area"
-      {...props}
-    >
-      {children}
-    </div>
-  );
-}
diff --git a/src/components/accordion/primitives/accordion-content.tsx b/src/components/accordion/primitives/accordion-content.tsx
index 54a4705..9aed7fb 100644
--- a/src/components/accordion/primitives/accordion-content.tsx
+++ b/src/components/accordion/primitives/accordion-content.tsx
@@ -19,7 +19,6 @@ export function AccordionContent({ className, children, ...props }: AccordionCon
     <AccordionPrimitive.Content
       className={cn(
         'overflow-hidden',
-        // We need to delay the animation until the component is mounted to avoid the animation from being triggered when the component is first rendered.
         isMounted && 'data-[state=closed]:animate-collapse data-[state=open]:animate-expand',
       )}
       data-slot="accordion-content"
diff --git a/src/components/accordion/primitives/accordion-item.tsx b/src/components/accordion/primitives/accordion-item.tsx
index 31afae8..1d9ba34 100644
--- a/src/components/accordion/primitives/accordion-item.tsx
+++ b/src/components/accordion/primitives/accordion-item.tsx
@@ -9,16 +9,7 @@ export type AccordionItemProps = ComponentProps<typeof AccordionPrimitive.Item>;
 
 export function AccordionItem({ children, className, ...props }: AccordionItemProps) {
   return (
-    <AccordionPrimitive.Item
-      className={cn(
-        'focus:outline-2',
-        // Focus-visible state - using ring for better visibility
-        'has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-[var(--accordion-focus,var(--brand))] has-[:focus-visible]:ring-offset-4 has-[:focus-visible]:ring-offset-[var(--accordion-offset,var(--background))]',
-        className,
-      )}
-      data-slot="accordion-item"
-      {...props}
-    >
+    <AccordionPrimitive.Item className={cn(className)} data-slot="accordion-item" {...props}>
       {children}
     </AccordionPrimitive.Item>
   );
diff --git a/src/components/accordion/primitives/accordion-title.tsx b/src/components/accordion/primitives/accordion-title.tsx
index ef205fa..2351280 100644
--- a/src/components/accordion/primitives/accordion-title.tsx
+++ b/src/components/accordion/primitives/accordion-title.tsx
@@ -8,9 +8,7 @@ export function AccordionTitle({ children, className, ...props }: AccordionTitle
   return (
     <div
       className={cn(
-        'flex-1 select-none text-sm font-normal uppercase text-[var(--accordion-light-title-text,var(--contrast-400))] transition-colors duration-300 ease-out [font-family:var(--accordion-title-font-family,var(--font-family-mono))]',
-        // Hover state
-        'group-hover/accordion:text-[var(--accordion-light-title-text-hover,var(--foreground))]',
+        'flex-1 select-none text-sm font-medium text-[--accordion-text-primary,var(--text-primary)] transition-colors duration-300 ease-out [font-family:--accordion-font-title,var(--font-heading)] group-hover/accordion:opacity-70',
         className,
       )}
       data-slot="accordion-title"
diff --git a/src/components/accordion/primitives/accordion-trigger.tsx b/src/components/accordion/primitives/accordion-trigger.tsx
index 7cfcc41..2f59ed1 100644
--- a/src/components/accordion/primitives/accordion-trigger.tsx
+++ b/src/components/accordion/primitives/accordion-trigger.tsx
@@ -11,7 +11,7 @@ export function AccordionTrigger({ className, children, ...props }: AccordionTri
   return (
     <AccordionPrimitive.Trigger
       className={cn(
-        'group/accordion flex w-full cursor-pointer items-start gap-8 border-none py-3 text-start focus:outline-none @md:py-4',
+        'group/accordion focus-primary flex w-full cursor-pointer items-start gap-8 rounded-lg border-none py-3 text-start @md:py-4',
         className,
       )}
       data-slot="accordion-trigger"
diff --git a/src/components/accordion/storybook/accordion.stories.tsx b/src/components/accordion/storybook/accordion.stories.tsx
index 66b6b6a..af90b8a 100644
--- a/src/components/accordion/storybook/accordion.stories.tsx
+++ b/src/components/accordion/storybook/accordion.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import type { ComponentType } from 'react';
 
 import { Accordion, type AccordionProps } from '@/components/accordion';
 import * as AccordionPrimitive from '@/components/accordion/primitives';
@@ -8,29 +7,21 @@ const meta: Meta<typeof Accordion> = {
   title: 'Components/Accordion',
   component: Accordion,
   parameters: {
-    layout: 'fullscreen',
+    layout: 'centered',
     docs: {
       description: {
         component: `
-A collapsible content component that allows users to toggle sections of content open and closed.
+A collapsible content component for organizing and revealing information in expandable sections.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --accordion-focus: var(--brand);
-  --accordion-light-title-text: var(--contrast-400);
-  --accordion-light-title-text-hover: var(--foreground);
-  --accordion-light-title-icon: var(--contrast-500);
-  --accordion-light-title-icon-hover: var(--foreground);
-  --accordion-light-content-text: var(--foreground);
-  --accordion-dark-title-text: var(--contrast-200);
-  --accordion-dark-title-text-hover: var(--background);
-  --accordion-dark-title-icon: var(--contrast-200);
-  --accordion-dark-title-icon-hover: var(--background);
-  --accordion-dark-content-text: var(--background);
-  --accordion-title-font-family: var(--font-family-body);
-  --accordion-content-font-family: var(--font-family-body);
+  --accordion-text-primary: var(--text-primary);
+  --accordion-text-secondary: var(--text-secondary);
+  --accordion-fill-icon: var(--contrast-400);
+  --accordion-font-title: var(--font-heading);
+  --accordion-font-body: var(--font-body);
 }
 \`\`\`
         `,
@@ -42,7 +33,7 @@ A collapsible content component that allows users to toggle sections of content
     type: {
       control: 'select',
       options: ['single', 'multiple'],
-      description: 'Whether one or multiple items can be open at a time',
+      description: 'Whether one or multiple items can be expanded at once',
     },
     collapsible: {
       control: 'boolean',
@@ -58,8 +49,8 @@ A collapsible content component that allows users to toggle sections of content
     },
   },
   decorators: [
-    (Story: ComponentType) => (
-      <div className="mx-auto max-w-2xl bg-background px-6 py-8">
+    (Story) => (
+      <div className="w-[400px]">
         <Story />
       </div>
     ),
@@ -70,79 +61,82 @@ export default meta;
 
 type Story = StoryObj<AccordionProps>;
 
-const faqItems: AccordionProps['items'] = [
+const sampleItems = [
   {
-    value: 'shipping',
-    title: 'Shipping Information',
-    content: (
-      <p>
-        We offer free standard shipping on orders over $50. Standard shipping takes 5-7 business
-        days, while expedited shipping arrives in 2-3 business days for an additional fee. All
-        orders include tracking information sent via email.
-      </p>
-    ),
+    title: 'What materials are used?',
+    content:
+      'Our products are crafted from sustainable materials including bamboo, natural fibers, and recycled glass. Each item is designed with environmental impact in mind.',
+    value: 'materials',
   },
   {
-    value: 'returns',
-    title: 'Returns & Exchanges',
-    content: (
-      <p>
-        Items can be returned within 30 days of purchase for a full refund. Products must be unused
-        and in original packaging. Exchanges are processed within 5-7 business days of receiving
-        your return.
-      </p>
-    ),
+    title: 'How do I care for these products?',
+    content:
+      'Most items can be cleaned with mild soap and water. Wooden items should be dried thoroughly after cleaning. Glass containers are dishwasher safe.',
+    value: 'care',
   },
   {
-    value: 'materials',
-    title: 'Materials & Care',
-    content: (
-      <p>
-        Our products are crafted from sustainable, eco-friendly materials including bamboo, recycled
-        glass, and organic cotton. Hand wash with mild soap and water. Avoid harsh chemicals to
-        extend product life.
-      </p>
-    ),
+    title: 'What is your return policy?',
+    content:
+      'We offer a 30-day return policy on all unused items in original packaging. Contact our support team to initiate a return.',
+    value: 'returns',
   },
 ];
 
-export const Default: Story = {
+export const Single: Story = {
+  args: {
+    type: 'single',
+    items: sampleItems,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Only one item can be expanded at a time. Expanding a new item closes the previous one.',
+      },
+    },
+  },
+};
+
+export const SingleCollapsible: Story = {
   args: {
     type: 'single',
     collapsible: true,
-    defaultValue: 'shipping',
-    items: faqItems,
+    items: sampleItems,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'With `collapsible` enabled, clicking an expanded item will close it.',
+      },
+    },
   },
 };
 
-export const MultipleOpen: Story = {
+export const Multiple: Story = {
   args: {
     type: 'multiple',
-    defaultValue: ['shipping', 'materials'],
-    items: faqItems,
+    items: sampleItems,
   },
   parameters: {
     docs: {
       description: {
-        story:
-          'When `type` is set to `"multiple"`, users can expand multiple accordion items at once.',
+        story: 'Multiple items can be expanded simultaneously.',
       },
     },
   },
 };
 
-export const NonCollapsible: Story = {
+export const WithDefaultValue: Story = {
   args: {
     type: 'single',
-    collapsible: false,
-    defaultValue: 'shipping',
-    items: faqItems,
+    collapsible: true,
+    defaultValue: 'care',
+    items: sampleItems,
   },
   parameters: {
     docs: {
       description: {
-        story:
-          'When `collapsible` is `false` and `type` is `"single"`, one item must always remain open.',
+        story: 'Use `defaultValue` to specify which item(s) should be expanded on initial render.',
       },
     },
   },
@@ -154,56 +148,31 @@ export const NonCollapsible: Story = {
  */
 export const ComposableAnatomy: Story = {
   render: () => (
-    <AccordionPrimitive.Root collapsible defaultValue="item-1" type="single">
-      <AccordionPrimitive.Item value="item-1">
-        <AccordionPrimitive.Header>
-          <AccordionPrimitive.Trigger>
-            <AccordionPrimitive.Title>Natural Fiber Scrub Brush</AccordionPrimitive.Title>
-            <AccordionPrimitive.Chevron />
-          </AccordionPrimitive.Trigger>
-        </AccordionPrimitive.Header>
-        <AccordionPrimitive.Content>
-          <AccordionPrimitive.ContentArea>
-            <p>
-              Hand-crafted from sustainable plant fibers, this scrub brush is perfect for dishes,
-              vegetables, and general cleaning. The ergonomic wooden handle provides a comfortable
-              grip while the natural bristles are tough on grime but gentle on surfaces.
-            </p>
-          </AccordionPrimitive.ContentArea>
-        </AccordionPrimitive.Content>
-      </AccordionPrimitive.Item>
-      <AccordionPrimitive.Item value="item-2">
+    <AccordionPrimitive.Root collapsible type="single">
+      <AccordionPrimitive.Item value="shipping">
         <AccordionPrimitive.Header>
           <AccordionPrimitive.Trigger>
-            <AccordionPrimitive.Title>Minimal Ceramic Soap Dispenser</AccordionPrimitive.Title>
+            <AccordionPrimitive.Title>Shipping Information</AccordionPrimitive.Title>
             <AccordionPrimitive.Chevron />
           </AccordionPrimitive.Trigger>
         </AccordionPrimitive.Header>
         <AccordionPrimitive.Content>
-          <AccordionPrimitive.ContentArea>
-            <p>
-              Elevate your bathroom or kitchen with this sleek ceramic soap dispenser. Features a
-              smooth pump mechanism and a weighted base for stability. Refillable design helps
-              reduce plastic waste.
-            </p>
-          </AccordionPrimitive.ContentArea>
+          <AccordionPrimitive.Body>
+            Free shipping on orders over $50. Standard delivery takes 3-5 business days.
+          </AccordionPrimitive.Body>
         </AccordionPrimitive.Content>
       </AccordionPrimitive.Item>
-      <AccordionPrimitive.Item value="item-3">
+      <AccordionPrimitive.Item value="warranty">
         <AccordionPrimitive.Header>
           <AccordionPrimitive.Trigger>
-            <AccordionPrimitive.Title>Linen Hand Towel</AccordionPrimitive.Title>
+            <AccordionPrimitive.Title>Warranty Details</AccordionPrimitive.Title>
             <AccordionPrimitive.Chevron />
           </AccordionPrimitive.Trigger>
         </AccordionPrimitive.Header>
         <AccordionPrimitive.Content>
-          <AccordionPrimitive.ContentArea>
-            <p>
-              Made from 100% European linen, these hand towels are highly absorbent and quick
-              drying. They become softer with each wash while maintaining their durability. A
-              timeless addition to any home.
-            </p>
-          </AccordionPrimitive.ContentArea>
+          <AccordionPrimitive.Body>
+            All products come with a 1-year warranty against manufacturing defects.
+          </AccordionPrimitive.Body>
         </AccordionPrimitive.Content>
       </AccordionPrimitive.Item>
     </AccordionPrimitive.Root>
@@ -226,9 +195,7 @@ import * as AccordionPrimitive from '@/components/accordion/primitives';
       </AccordionPrimitive.Trigger>
     </AccordionPrimitive.Header>
     <AccordionPrimitive.Content>
-      <AccordionPrimitive.ContentArea>
-        Content goes here
-      </AccordionPrimitive.ContentArea>
+      <AccordionPrimitive.Body>Content goes here</AccordionPrimitive.Body>
     </AccordionPrimitive.Content>
   </AccordionPrimitive.Item>
 </AccordionPrimitive.Root>
diff --git a/src/components/alert/alert.tsx b/src/components/alert/alert.tsx
index e75bae7..b8f088a 100644
--- a/src/components/alert/alert.tsx
+++ b/src/components/alert/alert.tsx
@@ -23,28 +23,29 @@ export interface AlertProps {
  *
  * ```css
  * :root {
- *   --alert-success-background: color-mix(in oklab, var(--success), white 75%);
- *   --alert-warning-background: color-mix(in oklab, var(--warning), white 75%);
- *   --alert-error-background: color-mix(in oklab, var(--error), white 75%);
- *   --alert-info-background: var(--background);
- *   --alert-font-family: var(--font-family-body);
- *   --alert-border: color-mix(in oklab, var(--foreground) 10%, transparent);
- *   --alert-message-text: var(--foreground);
- *   --alert-description-text: color-mix(in oklab, var(--foreground) 50%, transparent);
+ *   --alert-text: var(--text-primary);
+ *   --alert-fill-info: var(--background);
+ *   --alert-fill-success: var(--success-background);
+ *   --alert-fill-warning: var(--warning-background);
+ *   --alert-fill-error: var(--error-background);
+ *   --alert-font-title: var(--font-body);
+ *   --alert-font-description: var(--font-body);
  * }
  * ```
  */
 export function Alert({ className, variant, message, description, action, dismiss }: AlertProps) {
   return (
-    <AlertPrimitive.Root action={action} className={className} dismiss={dismiss} variant={variant}>
+    <AlertPrimitive.Root className={className} variant={variant}>
       <AlertPrimitive.Header>
         <AlertPrimitive.Title>{message}</AlertPrimitive.Title>
         <AlertPrimitive.Description>{description}</AlertPrimitive.Description>
       </AlertPrimitive.Header>
       <AlertPrimitive.Actions>
-        <AlertPrimitive.Action />
-        <AlertPrimitive.Dismiss />
+        {action && (
+          <AlertPrimitive.Action onClick={action.onClick}>{action.label}</AlertPrimitive.Action>
+        )}
       </AlertPrimitive.Actions>
+      <AlertPrimitive.Dismiss onClick={dismiss.onClick} />
     </AlertPrimitive.Root>
   );
 }
diff --git a/src/components/alert/primitives.ts b/src/components/alert/primitives.ts
index 6664622..a6504e0 100644
--- a/src/components/alert/primitives.ts
+++ b/src/components/alert/primitives.ts
@@ -1,7 +1,6 @@
 export {
   AlertRoot as Root,
   type AlertRootProps as RootProps,
-  useAlert,
 } from '@/components/alert/primitives/alert-root';
 export {
   AlertHeader as Header,
diff --git a/src/components/alert/primitives/alert-action.tsx b/src/components/alert/primitives/alert-action.tsx
index 5a28d51..7f25a63 100644
--- a/src/components/alert/primitives/alert-action.tsx
+++ b/src/components/alert/primitives/alert-action.tsx
@@ -2,21 +2,21 @@
 
 import type { ComponentProps } from 'react';
 
-import { useAlert } from '@/components/alert';
 import { Button } from '@/components/button';
+import { cn } from '@/lib';
 
 export type AlertActionProps = ComponentProps<typeof Button>;
 
-export function AlertAction({ children, ...props }: AlertActionProps) {
-  const { action } = useAlert();
-
-  if (!action) return null;
-
-  const { label, onClick } = action;
-
+export function AlertAction({ children, className, ...props }: AlertActionProps) {
   return (
-    <Button data-slot="alert-action" onClick={onClick} size="x-small" variant="ghost" {...props}>
-      {label}
+    <Button
+      className={cn('shrink-0', className)}
+      data-slot="alert-action"
+      size="x-small"
+      variant="ghost"
+      {...props}
+    >
+      {children}
     </Button>
   );
 }
diff --git a/src/components/alert/primitives/alert-actions.tsx b/src/components/alert/primitives/alert-actions.tsx
index 5769a82..f8ae4b2 100644
--- a/src/components/alert/primitives/alert-actions.tsx
+++ b/src/components/alert/primitives/alert-actions.tsx
@@ -6,7 +6,11 @@ export type AlertActionsProps = ComponentProps<'div'>;
 
 export function AlertActions({ children, className, ...props }: AlertActionsProps) {
   return (
-    <div className={cn('flex items-center gap-1', className)} data-slot="alert-actions" {...props}>
+    <div
+      className={cn('flex flex-none items-center gap-1', className)}
+      data-slot="alert-actions"
+      {...props}
+    >
       {children}
     </div>
   );
diff --git a/src/components/alert/primitives/alert-description.tsx b/src/components/alert/primitives/alert-description.tsx
index b8421e8..26d37bc 100644
--- a/src/components/alert/primitives/alert-description.tsx
+++ b/src/components/alert/primitives/alert-description.tsx
@@ -4,11 +4,11 @@ import { cn } from '@/lib';
 
 export type AlertDescriptionProps = ComponentProps<'p'>;
 
-export function AlertDescription({ className, children, ...props }: AlertDescriptionProps) {
+export function AlertDescription({ children, className, ...props }: AlertDescriptionProps) {
   return (
     <p
       className={cn(
-        'text-xs font-medium text-[color:var(--alert-description-text,color-mix(in_oklab,var(--foreground)_50%,transparent))]',
+        'text-xs font-medium text-[--alert-text,var(--text-primary)] opacity-50',
         className,
       )}
       data-slot="alert-description"
diff --git a/src/components/alert/primitives/alert-dismiss.tsx b/src/components/alert/primitives/alert-dismiss.tsx
index b3e333d..ad6e716 100644
--- a/src/components/alert/primitives/alert-dismiss.tsx
+++ b/src/components/alert/primitives/alert-dismiss.tsx
@@ -3,27 +3,23 @@
 import { X } from 'lucide-react';
 import type { ComponentProps } from 'react';
 
-import { useAlert } from '@/components/alert';
 import { Button } from '@/components/button';
+import { cn } from '@/lib';
 
 export type AlertDismissProps = ComponentProps<typeof Button>;
 
-export function AlertDismiss({ ...props }: AlertDismissProps) {
-  const { dismiss } = useAlert();
-
-  const { label, onClick } = dismiss;
-
+export function AlertDismiss({ children, className, ...props }: AlertDismissProps) {
   return (
     <Button
-      aria-label={label}
+      className={cn('shrink-0', className)}
       data-slot="alert-dismiss"
-      onClick={onClick}
       shape="circle"
       size="x-small"
       variant="ghost"
       {...props}
     >
       <X absoluteStrokeWidth size={20} strokeWidth={1} />
+      <span className="sr-only">{children ?? 'Dismiss'}</span>
     </Button>
   );
 }
diff --git a/src/components/alert/primitives/alert-header.tsx b/src/components/alert/primitives/alert-header.tsx
index a5f4dfa..0cc6492 100644
--- a/src/components/alert/primitives/alert-header.tsx
+++ b/src/components/alert/primitives/alert-header.tsx
@@ -7,7 +7,7 @@ export type AlertHeaderProps = ComponentProps<'div'>;
 export function AlertHeader({ children, className, ...props }: AlertHeaderProps) {
   return (
     <div
-      className={cn('[font-family:var(--alert-font-family,var(--font-family-body))]', className)}
+      className={cn('flex-initial [font-family:--alert-font,var(--font-body)]', className)}
       data-slot="alert-header"
       {...props}
     >
diff --git a/src/components/alert/primitives/alert-root.tsx b/src/components/alert/primitives/alert-root.tsx
index b4db156..a19c21c 100644
--- a/src/components/alert/primitives/alert-root.tsx
+++ b/src/components/alert/primitives/alert-root.tsx
@@ -1,33 +1,19 @@
 'use client';
 
 import { cva, type VariantProps } from 'class-variance-authority';
-import { createContext, use, useMemo } from 'react';
-import type { ComponentProps, MouseEventHandler } from 'react';
+import type { ComponentProps } from 'react';
 
 import { cn } from '@/lib';
 
-interface AlertContext {
-  action?: {
-    label: string;
-    onClick: MouseEventHandler<HTMLButtonElement> | undefined;
-  };
-  dismiss: {
-    label: string;
-    onClick: MouseEventHandler<HTMLButtonElement> | undefined;
-  };
-}
-
-export const AlertContext = createContext<AlertContext | undefined>(undefined);
-
 const alertVariants = cva(
   'group/alert flex max-w-[356px] items-center justify-between gap-2 rounded-xl border border-black/10 py-3 pe-3 ps-4 shadow',
   {
     variants: {
       variant: {
-        success: 'bg-[var(--alert-success-background,var(--success-background))]',
-        warning: 'bg-[var(--alert-warning-background,var(--warning-background))]',
-        error: 'bg-[var(--alert-error-background,var(--error-background))]',
-        info: 'bg-[var(--alert-info-background,var(--background))]',
+        success: 'bg-[--alert-fill-success,var(--success-background)]',
+        warning: 'bg-[--alert-fill-warning,var(--warning-background)]',
+        error: 'bg-[--alert-fill-error,var(--error-background)]',
+        info: 'bg-[--alert-fill-info,var(--background)]',
       },
     },
     defaultVariants: {
@@ -36,55 +22,18 @@ const alertVariants = cva(
   },
 );
 
-export type AlertRootProps = ComponentProps<'div'> &
-  VariantProps<typeof alertVariants> & {
-    action?: {
-      label: string;
-      onClick: MouseEventHandler<HTMLButtonElement> | undefined;
-    };
-    dismiss: {
-      label: string;
-      onClick: MouseEventHandler<HTMLButtonElement> | undefined;
-    };
-  };
-
-export function AlertRoot({
-  className,
-  children,
-  action,
-  dismiss,
-  variant,
-  ...props
-}: AlertRootProps) {
-  const contextValues = useMemo(
-    () => ({
-      action,
-      dismiss,
-    }),
-    [action, dismiss],
-  );
+export type AlertRootProps = ComponentProps<'div'> & VariantProps<typeof alertVariants>;
 
+export function AlertRoot({ children, className, variant, ...props }: AlertRootProps) {
   return (
-    <AlertContext.Provider value={contextValues}>
-      <div
-        className={cn(alertVariants({ variant }), className)}
-        data-slot="alert-root"
-        data-variant={variant}
-        role="alert"
-        {...props}
-      >
-        {children}
-      </div>
-    </AlertContext.Provider>
+    <div
+      className={cn(alertVariants({ variant }), className)}
+      data-slot="alert-root"
+      data-variant={variant}
+      role="alert"
+      {...props}
+    >
+      {children}
+    </div>
   );
 }
-
-export function useAlert() {
-  const context = use(AlertContext);
-
-  if (context === undefined) {
-    throw new Error('useAlert must be used within an AlertRoot');
-  }
-
-  return context;
-}
diff --git a/src/components/alert/primitives/alert-title.tsx b/src/components/alert/primitives/alert-title.tsx
index f429843..5401c47 100644
--- a/src/components/alert/primitives/alert-title.tsx
+++ b/src/components/alert/primitives/alert-title.tsx
@@ -7,10 +7,7 @@ export type AlertTitleProps = ComponentProps<'h5'>;
 export function AlertTitle({ children, className, ...props }: AlertTitleProps) {
   return (
     <h5
-      className={cn(
-        'text-sm font-normal text-[var(--alert-message-text,var(--foreground))]',
-        className,
-      )}
+      className={cn('text-[--alert-text,var(--text-primary))] text-sm', className)}
       data-slot="alert-title"
       {...props}
     >
diff --git a/src/components/alert/storybook/alert.stories.tsx b/src/components/alert/storybook/alert.stories.tsx
index 7781f64..f81e105 100644
--- a/src/components/alert/storybook/alert.stories.tsx
+++ b/src/components/alert/storybook/alert.stories.tsx
@@ -17,14 +17,13 @@ A notification component for displaying important messages to users with support
 
 \`\`\`css
 :root {
-  --alert-success-background: color-mix(in oklab, var(--success), white 75%);
-  --alert-warning-background: color-mix(in oklab, var(--warning), white 75%);
-  --alert-error-background: color-mix(in oklab, var(--error), white 75%);
-  --alert-info-background: var(--background);
-  --alert-font-family: var(--font-family-body);
-  --alert-border: color-mix(in oklab, var(--foreground) 10%, transparent);
-  --alert-message-text: var(--foreground);
-  --alert-description-text: color-mix(in oklab, var(--foreground) 50%, transparent);
+  --alert-text: var(--text-primary);
+  --alert-fill-info: var(--background);
+  --alert-fill-success: var(--success-background);
+  --alert-fill-warning: var(--warning-background);
+  --alert-fill-error: var(--error-background);
+  --alert-font-title: var(--font-body);
+  --alert-font-description: var(--font-body);
 }
 \`\`\`
         `,
@@ -46,6 +45,13 @@ A notification component for displaying important messages to users with support
       control: 'text',
       description: 'Optional description text',
     },
+    action: {
+      description: 'Optional action button configuration with label and onClick handler',
+    },
+    dismiss: {
+      description:
+        'Dismiss button configuration with label (for accessibility) and onClick handler',
+    },
   },
 };
 
@@ -53,50 +59,53 @@ export default meta;
 
 type Story = StoryObj<AlertProps>;
 
-export const Success: Story = {
+export const Default: Story = {
   args: {
-    variant: 'success',
-    message: 'Payment successful',
-    description: 'Your payment has been processed successfully.',
-    dismiss: {
-      label: 'Dismiss payment alert',
-      onClick: () => console.log('Dismissed'),
-    },
-  },
-};
-
-export const Warning: Story = {
-  args: {
-    variant: 'warning',
-    message: 'Low inventory',
-    description: 'Only 3 items left in stock.',
-    dismiss: {
-      label: 'Dismiss inventory alert',
-      onClick: () => console.log('Dismissed'),
-    },
-  },
-};
-
-export const Error: Story = {
-  args: {
-    variant: 'error',
-    message: 'Payment failed',
-    description: 'There was an error processing your payment. Please try again.',
+    variant: 'info',
+    message: 'New feature available',
+    description: 'Check out our new shopping experience.',
     dismiss: {
-      label: 'Dismiss payment failure alert',
+      label: 'Dismiss alert',
       onClick: () => console.log('Dismissed'),
     },
   },
 };
 
-export const Info: Story = {
-  args: {
-    variant: 'info',
-    message: 'New feature available',
-    description: 'Check out our new shopping experience.',
-    dismiss: {
-      label: 'Dismiss new feature alert',
-      onClick: () => console.log('Dismissed'),
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Alert
+        description="Your order has been placed successfully."
+        dismiss={{ label: 'Dismiss success alert', onClick: () => console.log('Dismissed') }}
+        message="Order confirmed"
+        variant="success"
+      />
+      <Alert
+        description="Only 3 items left in stock."
+        dismiss={{ label: 'Dismiss warning alert', onClick: () => console.log('Dismissed') }}
+        message="Low inventory"
+        variant="warning"
+      />
+      <Alert
+        description="There was an error processing your payment."
+        dismiss={{ label: 'Dismiss error alert', onClick: () => console.log('Dismissed') }}
+        message="Payment failed"
+        variant="error"
+      />
+      <Alert
+        description="Check out our new shopping experience."
+        dismiss={{ label: 'Dismiss info alert', onClick: () => console.log('Dismissed') }}
+        message="New feature available"
+        variant="info"
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The alert supports four semantic variants: `success`, `warning`, `error`, and `info`.',
+      },
     },
   },
 };
@@ -130,10 +139,7 @@ export const WithAction: Story = {
  */
 export const ComposableAnatomy: Story = {
   render: () => (
-    <AlertPrimitive.Root
-      dismiss={{ label: 'Dismiss alert', onClick: () => console.log('Dismissed') }}
-      variant="success"
-    >
+    <AlertPrimitive.Root variant="success">
       <AlertPrimitive.Header>
         <AlertPrimitive.Title>Order confirmed</AlertPrimitive.Title>
         <AlertPrimitive.Description>
@@ -141,7 +147,12 @@ export const ComposableAnatomy: Story = {
         </AlertPrimitive.Description>
       </AlertPrimitive.Header>
       <AlertPrimitive.Actions>
-        <AlertPrimitive.Dismiss />
+        <AlertPrimitive.Action onClick={() => console.log('View order')}>
+          View Order
+        </AlertPrimitive.Action>
+        <AlertPrimitive.Dismiss onClick={() => console.log('Dismissed')}>
+          Dismiss alert
+        </AlertPrimitive.Dismiss>
       </AlertPrimitive.Actions>
     </AlertPrimitive.Root>
   ),
@@ -154,17 +165,14 @@ Use the composable primitives to build custom alert layouts:
 \`\`\`tsx
 import * as AlertPrimitive from '@/components/alert/primitives';
 
-<AlertPrimitive.Root
-  variant="success"
-  dismiss={{ label: 'Dismiss', onClick: handleDismiss }}
->
+<AlertPrimitive.Root variant="success">
   <AlertPrimitive.Header>
     <AlertPrimitive.Title>Title</AlertPrimitive.Title>
     <AlertPrimitive.Description>Description text</AlertPrimitive.Description>
   </AlertPrimitive.Header>
   <AlertPrimitive.Actions>
-    <AlertPrimitive.Action />
-    <AlertPrimitive.Dismiss />
+    <AlertPrimitive.Action onClick={handleAction}>Action</AlertPrimitive.Action>
+    <AlertPrimitive.Dismiss onClick={handleDismiss}>Dismiss</AlertPrimitive.Dismiss>
   </AlertPrimitive.Actions>
 </AlertPrimitive.Root>
 \`\`\`
diff --git a/src/components/animated-underline/animated-underline.tsx b/src/components/animated-underline/animated-underline.tsx
index 72f917b..0b17b0e 100644
--- a/src/components/animated-underline/animated-underline.tsx
+++ b/src/components/animated-underline/animated-underline.tsx
@@ -12,9 +12,7 @@ export type AnimatedUnderlineProps = ComponentProps<'span'> & {
  *
  * ```css
  * :root {
- *   --animated-underline-hover: var(--brand);
- *   --animated-underline-text: var(--foreground);
- *   --animated-underline-font-family: var(--font-family-body);
+ *   --animated-underline: var(--brand);
  * }
  * ```
  */
@@ -22,7 +20,7 @@ export function AnimatedUnderline({ className, children, ...props }: AnimatedUnd
   return (
     <span
       className={cn(
-        'origin-left font-semibold leading-normal text-[var(--animated-underline-text,var(--foreground))] transition-[background-size] duration-300 [background:linear-gradient(0deg,var(--animated-underline-hover,var(--brand)),var(--animated-underline-hover,var(--brand)))_no-repeat_left_bottom_/_0_2px] [font-family:var(--animated-underline-font-family,var(--font-family-body))]',
+        'origin-left font-semibold text-inherit transition-[background-size] duration-300 [background:linear-gradient(0deg,var(--animated-underline,var(--brand)),var(--animated-underline,var(--brand)))_no-repeat_left_bottom_/_0_2px] [font-family:inherit]',
         // Hover state
         'hover:bg-[size:100%_2px]',
         // Group focus state
diff --git a/src/components/animated-underline/storybook/animated-underline.stories.tsx b/src/components/animated-underline/storybook/animated-underline.stories.tsx
index c95e5d9..b87848e 100644
--- a/src/components/animated-underline/storybook/animated-underline.stories.tsx
+++ b/src/components/animated-underline/storybook/animated-underline.stories.tsx
@@ -16,9 +16,7 @@ An animated underline component that creates a smooth expanding underline effect
 
 \`\`\`css
 :root {
-  --animated-underline-hover: var(--brand);
-  --animated-underline-text: var(--foreground);
-  --animated-underline-font-family: var(--font-family-body);
+  --animated-underline: var(--brand);
 }
 \`\`\`
         `,
diff --git a/src/components/badge/badge.tsx b/src/components/badge/badge.tsx
index f348b3c..01ee786 100644
--- a/src/components/badge/badge.tsx
+++ b/src/components/badge/badge.tsx
@@ -4,7 +4,7 @@ import type { ComponentProps } from 'react';
 import { cn } from '@/lib';
 
 export const badgeVariants = cva(
-  'border border-black/10 px-2 py-1 text-xs font-semibold text-[var(--badge-text,var(--text-brand))] antialiased [font-family:var(--badge-font-family,var(--font-family-body))]',
+  'border border-black/10 px-2 py-1 text-xs font-semibold text-[--badge-text,var(--text-primary)] antialiased [font-family:--badge-font,var(--font-body)]',
   {
     variants: {
       shape: {
@@ -12,16 +12,16 @@ export const badgeVariants = cva(
         rounded: 'rounded',
       },
       variant: {
-        primary: 'bg-[var(--badge-brand-background,var(--brand-background))]',
-        warning: 'bg-[var(--badge-warning-background,var(--warning-background))]',
-        error: 'bg-[var(--badge-error-background,var(--error-background))]',
-        success: 'bg-[var(--badge-success-background,var(--success-background))]',
-        info: 'bg-[var(--badge-info-background,var(--background))]',
+        brand: 'bg-[--badge-brand-fill,var(--brand-background)]',
+        warning: 'bg-[--badge-warning-fill,var(--warning-background)]',
+        error: 'bg-[--badge-error-fill,var(--error-background)]',
+        success: 'bg-[--badge-success-fill,var(--success-background)]',
+        info: 'bg-[--badge-info-fill,var(--background)]',
       },
     },
     defaultVariants: {
       shape: 'rounded',
-      variant: 'primary',
+      variant: 'brand',
     },
   },
 );
@@ -37,13 +37,13 @@ export type BadgeProps = ComponentProps<'span'> &
  *
  * ```css
  * :root {
- *   --badge-brand-background: color-mix(in oklab, var(--brand), white 75%);
- *   --badge-success-background: color-mix(in oklab, var(--success), white 75%);
- *   --badge-warning-background: color-mix(in oklab, var(--warning), white 75%);
- *   --badge-error-background: color-mix(in oklab, var(--error), white 75%);
- *   --badge-info-background: color-mix(in oklab, var(--info), white 75%);
+ *   --badge-fill-brand: color-mix(in oklab, var(--brand), white 75%);
+ *   --badge-fill-success: color-mix(in oklab, var(--success), white 75%);
+ *   --badge-fill-warning: color-mix(in oklab, var(--warning), white 75%);
+ *   --badge-fill-error: color-mix(in oklab, var(--error), white 75%);
+ *   --badge-fill-info: color-mix(in oklab, var(--info), white 75%);
  *   --badge-text: var(--foreground);
- *   --badge-font-family: var(--font-family-body);
+ *   --badge-font: var(--font-body);
  * }
  * ```
  */
diff --git a/src/components/badge/storybook/badge.stories.tsx b/src/components/badge/storybook/badge.stories.tsx
index eff3970..54372d5 100644
--- a/src/components/badge/storybook/badge.stories.tsx
+++ b/src/components/badge/storybook/badge.stories.tsx
@@ -16,13 +16,13 @@ A small status indicator component for displaying labels, tags, and statuses.
 
 \`\`\`css
 :root {
-  --badge-brand-background: var(--brand-background);
-  --badge-success-background: var(--success-background);
-  --badge-warning-background: var(--warning-background);
-  --badge-error-background: var(--error-background);
-  --badge-info-background: var(--background);
+  --badge-fill-brand: var(--brand-background);
+  --badge-fill-success: var(--success-background);
+  --badge-fill-warning: var(--warning-background);
+  --badge-fill-error: var(--error-background);
+  --badge-fill-info: var(--background);
   --badge-text: var(--text-brand);
-  --badge-font-family: var(--font-family-body);
+  --badge-font: var(--font-body);
 }
 \`\`\`
         `,
@@ -37,7 +37,7 @@ A small status indicator component for displaying labels, tags, and statuses.
     },
     variant: {
       control: 'select',
-      options: ['primary', 'success', 'warning', 'error', 'info'],
+      options: ['brand', 'success', 'warning', 'error', 'info'],
       description: 'The semantic variant of the badge',
     },
     shape: {
@@ -54,14 +54,14 @@ type Story = StoryObj<BadgeProps>;
 export const Default: Story = {
   args: {
     children: 'New',
-    variant: 'primary',
+    variant: 'brand',
   },
 };
 
 export const AllVariants: Story = {
   render: () => (
     <div className="flex flex-wrap items-center gap-3">
-      <Badge variant="primary">Primary</Badge>
+      <Badge variant="brand">Brand</Badge>
       <Badge variant="success">Success</Badge>
       <Badge variant="warning">Warning</Badge>
       <Badge variant="error">Error</Badge>
@@ -80,10 +80,10 @@ export const AllVariants: Story = {
 export const Shapes: Story = {
   render: () => (
     <div className="flex flex-wrap gap-3">
-      <Badge shape="rounded" variant="primary">
+      <Badge shape="rounded" variant="brand">
         Rounded
       </Badge>
-      <Badge shape="pill" variant="primary">
+      <Badge shape="pill" variant="brand">
         Pill
       </Badge>
     </div>
diff --git a/src/components/banner/banner.tsx b/src/components/banner/banner.tsx
index f622304..45c5129 100644
--- a/src/components/banner/banner.tsx
+++ b/src/components/banner/banner.tsx
@@ -8,6 +8,10 @@ export interface BannerProps {
   hideDismiss?: boolean;
   children: ReactNode;
   onDismiss?: () => void;
+  dismissIcon?: {
+    asChild?: boolean;
+    children?: ReactNode;
+  };
 }
 
 /**
@@ -16,18 +20,21 @@ export interface BannerProps {
  *
  * ```css
  * :root {
- *   --banner-focus: var(--foreground);
- *   --banner-background: var(--brand);
- *   --banner-text: var(--foreground);
- *   --banner-close-icon: color-mix(in oklab, var(--foreground) 50%, transparent);
- *   --banner-close-icon-hover: var(--foreground);
- *   --banner-close-background: transparent;
- *   --banner-close-background-hover: color-mix(in oklab, var(--background) 40%, transparent);
- *   --banner-font-family: var(--font-family-body);
+ *   --banner-text: var(--text-primary);
+ *   --banner-fill: var(--brand);
+ *   --banner-fill-icon: var(--contrast-400);
+ *   --banner-font: var(--font-body);
  * }
  * ```
  */
-export function Banner({ id, children, hideDismiss = false, className, onDismiss }: BannerProps) {
+export function Banner({
+  id,
+  children,
+  hideDismiss = false,
+  className,
+  onDismiss,
+  dismissIcon,
+}: BannerProps) {
   return (
     <BannerPrimitive.Root
       className={className}
@@ -37,7 +44,11 @@ export function Banner({ id, children, hideDismiss = false, className, onDismiss
     >
       <BannerPrimitive.Content>
         <BannerPrimitive.Text>{children}</BannerPrimitive.Text>
-        <BannerPrimitive.Dismiss />
+        <BannerPrimitive.Dismiss>
+          <BannerPrimitive.DismissIcon asChild={dismissIcon?.asChild}>
+            {dismissIcon?.children}
+          </BannerPrimitive.DismissIcon>
+        </BannerPrimitive.Dismiss>
       </BannerPrimitive.Content>
     </BannerPrimitive.Root>
   );
diff --git a/src/components/banner/primitives.ts b/src/components/banner/primitives.ts
index 43ad458..366321a 100644
--- a/src/components/banner/primitives.ts
+++ b/src/components/banner/primitives.ts
@@ -15,3 +15,7 @@ export {
   BannerDismiss as Dismiss,
   type BannerDismissProps as DismissProps,
 } from '@/components/banner/primitives/banner-dismiss';
+export {
+  BannerDismissIcon as DismissIcon,
+  type BannerDismissIconProps as DismissIconProps,
+} from '@/components/banner/primitives/banner-dismiss-icon';
diff --git a/src/components/banner/primitives/banner-dismiss-icon.tsx b/src/components/banner/primitives/banner-dismiss-icon.tsx
new file mode 100644
index 0000000..f36badc
--- /dev/null
+++ b/src/components/banner/primitives/banner-dismiss-icon.tsx
@@ -0,0 +1,36 @@
+import { Slot } from '@radix-ui/react-slot';
+import { X } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { cn } from '@/lib';
+
+export interface BannerDismissIconProps {
+  asChild?: boolean;
+  className?: string;
+  children?: ReactNode;
+}
+
+export function BannerDismissIcon({
+  asChild = false,
+  className,
+  children,
+}: BannerDismissIconProps) {
+  const iconStyles = cn('size-5 shrink-0 text-[--banner-fill-icon,var(--foreground)]', className);
+
+  if (asChild) {
+    return (
+      <Slot className={iconStyles} data-slot="banner-dismiss-icon">
+        {children}
+      </Slot>
+    );
+  }
+
+  return (
+    <X
+      absoluteStrokeWidth
+      className={iconStyles}
+      data-slot="banner-dismiss-icon"
+      strokeWidth={1.5}
+    />
+  );
+}
diff --git a/src/components/banner/primitives/banner-dismiss.tsx b/src/components/banner/primitives/banner-dismiss.tsx
index a3b27fa..d34f8cb 100644
--- a/src/components/banner/primitives/banner-dismiss.tsx
+++ b/src/components/banner/primitives/banner-dismiss.tsx
@@ -1,37 +1,33 @@
 'use client';
 
-import { X } from 'lucide-react';
 import type { ComponentProps } from 'react';
 
 import { useBanner } from '@/components/banner';
+import { Button } from '@/components/button';
 import { cn } from '@/lib';
 
 export type BannerDismissProps = ComponentProps<'button'>;
 
-export function BannerDismiss({ className, ...props }: BannerDismissProps) {
+export function BannerDismiss({ children, className, ...props }: BannerDismissProps) {
   const { hideDismiss, handleDismiss } = useBanner();
 
   if (hideDismiss) return null;
 
   return (
-    <button
+    <Button
       aria-label="Dismiss banner"
-      className={cn(
-        'flex h-8 w-8 items-center justify-center rounded-full bg-[var(--banner-close-background,transparent)] text-[var(--banner-close-icon,color-mix(in_oklab,var(--foreground)_50%,transparent))] transition-colors duration-300 focus:outline-none',
-        // Hover state
-        'hover:bg-[var(--banner-close-background-hover,color-mix(in_oklab,var(--background)_40%,transparent))] hover:text-[var(--banner-close-icon-hover,var(--foreground))]',
-        // Focus-visible state
-        'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--banner-focus,var(--foreground))]',
-        className,
-      )}
+      className={cn('focus-secondary', className)}
       data-slot="banner-dismiss"
       onClick={(e) => {
         e.preventDefault();
         handleDismiss();
       }}
+      shape="circle"
+      size="x-small"
+      variant="ghost"
       {...props}
     >
-      <X absoluteStrokeWidth size={20} strokeWidth={1.5} />
-    </button>
+      {children}
+    </Button>
   );
 }
diff --git a/src/components/banner/primitives/banner-root.tsx b/src/components/banner/primitives/banner-root.tsx
index 2afb2e9..8836bd7 100644
--- a/src/components/banner/primitives/banner-root.tsx
+++ b/src/components/banner/primitives/banner-root.tsx
@@ -60,7 +60,7 @@ export function BannerRoot({
     <BannerContext.Provider value={contextValues}>
       <div
         className={cn(
-          'group/banner overflow-hidden bg-[var(--banner-background,var(--brand))] transition-all duration-300 ease-in @container',
+          'group/banner overflow-hidden bg-[--banner-fill,var(--brand)] transition-all duration-300 ease-in @container',
           isDismissed ? 'pointer-events-none max-h-0' : 'max-h-32',
           className,
         )}
diff --git a/src/components/banner/primitives/banner-text.tsx b/src/components/banner/primitives/banner-text.tsx
index 6cefd7b..c105be1 100644
--- a/src/components/banner/primitives/banner-text.tsx
+++ b/src/components/banner/primitives/banner-text.tsx
@@ -8,7 +8,7 @@ export function BannerText({ children, className, ...props }: BannerTextProps) {
   return (
     <div
       className={cn(
-        'flex-1 text-sm text-[var(--banner-text,var(--foreground))] [font-family:var(--banner-font-family,var(--font-family-body))] @xl:text-center @xl:text-base',
+        'flex-1 text-sm text-[--banner-text,var(--text-primary)] [font-family:--banner-font,var(--font-body)] @xl:text-center @xl:text-base',
         className,
       )}
       data-slot="banner-text"
diff --git a/src/components/banner/storybook/banner.stories.tsx b/src/components/banner/storybook/banner.stories.tsx
index c726734..3aed730 100644
--- a/src/components/banner/storybook/banner.stories.tsx
+++ b/src/components/banner/storybook/banner.stories.tsx
@@ -8,7 +8,7 @@ import { Banner, type BannerProps } from '@/components/banner';
 import * as BannerPrimitive from '@/components/banner/primitives';
 import { Button } from '@/components/button';
 
-// Wrapper component to handle banner reset functionality
+// Wrapper component to handle banner reset functionality for Storybook demos
 const BannerWithReset = ({
   id,
   children,
@@ -23,7 +23,6 @@ const BannerWithReset = ({
   const [key, setKey] = useState(0);
 
   useEffect(() => {
-    // Clear localStorage on mount
     localStorage.removeItem(`${id}-hidden-banner`);
   }, [id]);
 
@@ -54,20 +53,16 @@ const meta: Meta<typeof Banner> = {
     docs: {
       description: {
         component: `
-A dismissible banner component for displaying promotional messages, announcements, and notifications at the top of a page.
+A dismissible banner component for displaying promotional messages, announcements, and notifications at the top of a page. The banner persists its dismissed state in localStorage.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --banner-focus: var(--foreground);
-  --banner-background: var(--brand);
-  --banner-text: var(--foreground);
-  --banner-close-icon: color-mix(in oklab, var(--foreground) 50%, transparent);
-  --banner-close-icon-hover: var(--foreground);
-  --banner-close-background: transparent;
-  --banner-close-background-hover: color-mix(in oklab, var(--background) 40%, transparent);
-  --banner-font-family: var(--font-family-body);
+  --banner-text: var(--text-primary);
+  --banner-fill: var(--brand);
+  --banner-fill-icon: var(--foreground);
+  --banner-font: var(--font-body);
 }
 \`\`\`
         `,
@@ -78,7 +73,7 @@ A dismissible banner component for displaying promotional messages, announcement
   argTypes: {
     id: {
       control: 'text',
-      description: 'Unique identifier for localStorage persistence',
+      description: 'Unique identifier used for localStorage persistence of dismissed state',
     },
     children: {
       control: 'text',
@@ -88,6 +83,12 @@ A dismissible banner component for displaying promotional messages, announcement
       control: 'boolean',
       description: 'Whether to hide the dismiss button',
     },
+    onDismiss: {
+      description: 'Callback function called when the banner is dismissed',
+    },
+    dismissIcon: {
+      description: 'Configuration for a custom dismiss icon with `asChild` and `children` props',
+    },
   },
 };
 
@@ -118,21 +119,6 @@ export const WithoutDismiss: Story = {
   },
 };
 
-export const ShippingPromotion: Story = {
-  render: () => (
-    <BannerWithReset id="shipping-promo-banner">
-      🚚 <strong>Free shipping</strong> on all orders over $50
-    </BannerWithReset>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'Banners support rich content including emojis and HTML elements like `<strong>`.',
-      },
-    },
-  },
-};
-
 /**
  * The Banner can be built using composable primitives for full customization.
  * This example shows the component anatomy using the primitive components.
@@ -158,7 +144,9 @@ export const ComposableAnatomy: Story = {
             <BannerPrimitive.Text>
               ✨ <strong>Summer Sale:</strong> Up to 50% off select items. Shop now!
             </BannerPrimitive.Text>
-            <BannerPrimitive.Dismiss />
+            <BannerPrimitive.Dismiss>
+              <BannerPrimitive.DismissIcon />
+            </BannerPrimitive.Dismiss>
           </BannerPrimitive.Content>
         </BannerPrimitive.Root>
         <div className="mt-8 flex justify-center">
@@ -181,7 +169,9 @@ import * as BannerPrimitive from '@/components/banner/primitives';
 <BannerPrimitive.Root id="unique-id">
   <BannerPrimitive.Content>
     <BannerPrimitive.Text>Banner message</BannerPrimitive.Text>
-    <BannerPrimitive.Dismiss />
+    <BannerPrimitive.Dismiss>
+      <BannerPrimitive.DismissIcon />
+    </BannerPrimitive.Dismiss>
   </BannerPrimitive.Content>
 </BannerPrimitive.Root>
 \`\`\`
diff --git a/src/components/blog-card/blog-card.tsx b/src/components/blog-card/blog-card.tsx
new file mode 100644
index 0000000..ce5e474
--- /dev/null
+++ b/src/components/blog-card/blog-card.tsx
@@ -0,0 +1,61 @@
+import * as BlogCardPrimitive from '@/components/blog-card';
+
+export interface BlogCardProps {
+  className?: string;
+  aspectRatio?: '5/6' | '3/4' | '4/3' | '1/1';
+  title: string;
+  author?: string;
+  content: string;
+  date: string;
+  image?: {
+    src: string;
+    alt: string;
+  };
+  link: {
+    href: string;
+    ariaLabel: string;
+  };
+}
+
+/**
+ * This component supports various CSS variables for theming. Here's a comprehensive list, along
+ * with their default values:
+ *
+ * ```css
+ * :root {
+ *   --blog-card-text-primary: var(--text-primary);
+ *   --blog-card-text-secondary: var(--text-secondary);
+ *   --blog-card-font-title: var(--font-body);
+ *   --blog-card-font-content: var(--font-body);
+ * }
+ * ```
+ */
+export function BlogCard({
+  author,
+  aspectRatio = '4/3',
+  content,
+  date,
+  link,
+  image,
+  title,
+  className,
+}: BlogCardProps) {
+  return (
+    <BlogCardPrimitive.Root aspectRatio={aspectRatio} className={className}>
+      <BlogCardPrimitive.Thumbnail>
+        {image ? (
+          <BlogCardPrimitive.Image alt={image.alt} src={image.src} />
+        ) : (
+          <BlogCardPrimitive.Fallback>{title}</BlogCardPrimitive.Fallback>
+        )}
+      </BlogCardPrimitive.Thumbnail>
+      <BlogCardPrimitive.Title>{title}</BlogCardPrimitive.Title>
+      <BlogCardPrimitive.Content>{content}</BlogCardPrimitive.Content>
+      <BlogCardPrimitive.Details>
+        <BlogCardPrimitive.Date>{date}</BlogCardPrimitive.Date>
+        {author !== undefined && <BlogCardPrimitive.Author>{author}</BlogCardPrimitive.Author>}
+      </BlogCardPrimitive.Details>
+      <BlogCardPrimitive.Link aria-label={link.ariaLabel} href={link.href} />
+    </BlogCardPrimitive.Root>
+  );
+}
diff --git a/src/components/blog-card/index.ts b/src/components/blog-card/index.ts
new file mode 100644
index 0000000..48ad8a4
--- /dev/null
+++ b/src/components/blog-card/index.ts
@@ -0,0 +1,2 @@
+export { BlogCard, type BlogCardProps } from '@/components/blog-card/blog-card';
+export * from '@/components/blog-card/primitives';
diff --git a/src/components/blog-card/primitives.ts b/src/components/blog-card/primitives.ts
new file mode 100644
index 0000000..61632d7
--- /dev/null
+++ b/src/components/blog-card/primitives.ts
@@ -0,0 +1,44 @@
+export {
+  BlogCardRoot as Root,
+  type BlogCardRootProps as RootProps,
+} from '@/components/blog-card/primitives/blog-card-root';
+export {
+  BlogCardFallback as Fallback,
+  type BlogCardFallbackProps as FallbackProps,
+} from '@/components/blog-card/primitives/blog-card-fallback';
+export {
+  BlogCardThumbnail as Thumbnail,
+  type BlogCardThumbnailProps as ThumbnailProps,
+} from '@/components/blog-card/primitives/blog-card-thumbnail';
+export {
+  BlogCardImage as Image,
+  type BlogCardImageProps as ImageProps,
+} from '@/components/blog-card/primitives/blog-card-image';
+export {
+  BlogCardLink as Link,
+  type BlogCardLinkProps as LinkProps,
+} from '@/components/blog-card/primitives/blog-card-link';
+export {
+  BlogCardTitle as Title,
+  type BlogCardTitleProps as TitleProps,
+} from '@/components/blog-card/primitives/blog-card-title';
+export {
+  BlogCardContent as Content,
+  type BlogCardContentProps as ContentProps,
+} from '@/components/blog-card/primitives/blog-card-content';
+export {
+  BlogCardDetails as Details,
+  type BlogCardDetailsProps as DetailsProps,
+} from '@/components/blog-card/primitives/blog-card-details';
+export {
+  BlogCardDate as Date,
+  type BlogCardDateProps as DateProps,
+} from '@/components/blog-card/primitives/blog-card-date';
+export {
+  BlogCardAuthor as Author,
+  type BlogCardAuthorProps as AuthorProps,
+} from '@/components/blog-card/primitives/blog-card-author';
+export {
+  BlogCardSkeleton as Skeleton,
+  type BlogCardSkeletonProps as SkeletonProps,
+} from '@/components/blog-card/primitives/blog-card-skeleton';
diff --git a/src/components/blog-post-card/primitives/blog-post-card-author.tsx b/src/components/blog-card/primitives/blog-card-author.tsx
similarity index 53%
rename from src/components/blog-post-card/primitives/blog-post-card-author.tsx
rename to src/components/blog-card/primitives/blog-card-author.tsx
index 1d6688b..9cafb27 100644
--- a/src/components/blog-post-card/primitives/blog-post-card-author.tsx
+++ b/src/components/blog-card/primitives/blog-card-author.tsx
@@ -2,13 +2,13 @@ import type { ComponentProps } from 'react';
 
 import { cn } from '@/lib';
 
-export type BlogPostCardAuthorProps = ComponentProps<'span'>;
+export type BlogCardAuthorProps = ComponentProps<'span'>;
 
-export function BlogPostCardAuthor({ className, children, ...props }: BlogPostCardAuthorProps) {
+export function BlogCardAuthor({ className, children, ...props }: BlogCardAuthorProps) {
   return (
     <span
       className={cn("before:mx-2 before:content-['•']", className)}
-      data-slot="blog-post-card-author"
+      data-slot="blog-card-author"
       {...props}
     >
       {children}
diff --git a/src/components/blog-card/primitives/blog-card-content.tsx b/src/components/blog-card/primitives/blog-card-content.tsx
new file mode 100644
index 0000000..db4396a
--- /dev/null
+++ b/src/components/blog-card/primitives/blog-card-content.tsx
@@ -0,0 +1,20 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type BlogCardContentProps = ComponentProps<'p'>;
+
+export function BlogCardContent({ className, children, ...props }: BlogCardContentProps) {
+  return (
+    <p
+      className={cn(
+        'mt-2 line-clamp-3 text-sm text-[--blog-card-text-secondary,var(--text-secondary)] [font-family:var(--blog-card-font-content,var(--font-body))] @lg:mt-3 @lg:text-base',
+        className,
+      )}
+      data-slot="blog-card-content"
+      {...props}
+    >
+      {children}
+    </p>
+  );
+}
diff --git a/src/components/blog-card/primitives/blog-card-date.tsx b/src/components/blog-card/primitives/blog-card-date.tsx
new file mode 100644
index 0000000..5229f24
--- /dev/null
+++ b/src/components/blog-card/primitives/blog-card-date.tsx
@@ -0,0 +1,17 @@
+import type { ComponentProps } from 'react';
+
+export type BlogCardDateProps = ComponentProps<'time'> & {
+  children: string;
+};
+
+export function BlogCardDate({ className, children, ...props }: BlogCardDateProps) {
+  return (
+    <time className={className} data-slot="blog-card-date" dateTime={children} {...props}>
+      {new Date(children).toLocaleDateString('en-US', {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+      })}
+    </time>
+  );
+}
diff --git a/src/components/blog-card/primitives/blog-card-details.tsx b/src/components/blog-card/primitives/blog-card-details.tsx
new file mode 100644
index 0000000..6b0b857
--- /dev/null
+++ b/src/components/blog-card/primitives/blog-card-details.tsx
@@ -0,0 +1,20 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type BlogCardDetailsProps = ComponentProps<'div'>;
+
+export function BlogCardDetails({ children, className, ...props }: BlogCardDetailsProps) {
+  return (
+    <div
+      className={cn(
+        'mt-3 text-sm text-[--blog-card-text-primary,var(--text-primary)] @lg:text-base',
+        className,
+      )}
+      data-slot="blog-card-details"
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
diff --git a/src/components/blog-card/primitives/blog-card-fallback.tsx b/src/components/blog-card/primitives/blog-card-fallback.tsx
new file mode 100644
index 0000000..14a2ec1
--- /dev/null
+++ b/src/components/blog-card/primitives/blog-card-fallback.tsx
@@ -0,0 +1,20 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type BlogCardFallbackProps = ComponentProps<'div'>;
+
+export function BlogCardFallback({ children, className, ...props }: BlogCardFallbackProps) {
+  return (
+    <div
+      className={cn(
+        'break-words p-4 text-3xl font-bold text-[color-mix(in_oklab,var(--blog-card-text-primary,var(--text-primary))_30%,transparent)] transition-transform duration-500 ease-out group-hover/blog-card:scale-105',
+        className,
+      )}
+      data-slot="blog-card-fallback"
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
diff --git a/src/components/blog-post-card/primitives/blog-post-card-image.tsx b/src/components/blog-card/primitives/blog-card-image.tsx
similarity index 53%
rename from src/components/blog-post-card/primitives/blog-post-card-image.tsx
rename to src/components/blog-card/primitives/blog-card-image.tsx
index 7e75ee7..715dbfd 100644
--- a/src/components/blog-post-card/primitives/blog-post-card-image.tsx
+++ b/src/components/blog-card/primitives/blog-card-image.tsx
@@ -3,26 +3,20 @@ import type { ComponentProps } from 'react';
 
 import { cn } from '@/lib';
 
-export interface BlogPostCardImageProps extends ComponentProps<'img'> {
+export interface BlogCardImageProps extends ComponentProps<'img'> {
   asChild?: boolean;
 }
 
-export function BlogPostCardImage({
-  className,
-  asChild = false,
-  ...props
-}: BlogPostCardImageProps) {
+export function BlogCardImage({ className, asChild = false, ...props }: BlogCardImageProps) {
   const Component = asChild ? Slot : 'img';
 
   return (
     <Component
       className={cn(
-        'h-full w-full object-cover transition-transform duration-500 ease-out',
-        // Group hover state
-        'group-hover/blog-post-card:scale-110',
+        'h-full w-full object-cover transition-transform duration-500 ease-out group-hover/blog-card:scale-110',
         className,
       )}
-      data-slot="blog-post-card-image"
+      data-slot="blog-card-image"
       {...props}
     />
   );
diff --git a/src/components/blog-card/primitives/blog-card-link.tsx b/src/components/blog-card/primitives/blog-card-link.tsx
new file mode 100644
index 0000000..fc486f6
--- /dev/null
+++ b/src/components/blog-card/primitives/blog-card-link.tsx
@@ -0,0 +1,20 @@
+import { Slot } from '@radix-ui/react-slot';
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export interface BlogCardLinkProps extends ComponentProps<'a'> {
+  asChild?: boolean;
+}
+
+export function BlogCardLink({ asChild = false, className, ...props }: BlogCardLinkProps) {
+  const Component = asChild ? Slot : 'a';
+
+  return (
+    <Component
+      className={cn('focus-primary absolute inset-0 rounded-b-lg rounded-t-2xl', className)}
+      data-slot="blog-card-link"
+      {...props}
+    />
+  );
+}
diff --git a/src/components/blog-card/primitives/blog-card-root.tsx b/src/components/blog-card/primitives/blog-card-root.tsx
new file mode 100644
index 0000000..3413082
--- /dev/null
+++ b/src/components/blog-card/primitives/blog-card-root.tsx
@@ -0,0 +1,29 @@
+import type { ComponentProps, ElementType } from 'react';
+
+import { cn } from '@/lib';
+
+export type BlogCardRootProps<E extends ElementType = 'article'> = Omit<ComponentProps<E>, 'as'> & {
+  as?: E;
+  aspectRatio?: '5/6' | '3/4' | '4/3' | '1/1';
+};
+
+export function BlogCardRoot<T extends ElementType = 'article'>({
+  as,
+  className,
+  children,
+  aspectRatio = '4/3',
+  ...props
+}: BlogCardRootProps<T>) {
+  const BlogCardRootElement = as ?? 'article';
+
+  return (
+    <BlogCardRootElement
+      className={cn('group/blog-card relative w-full @container', className)}
+      data-aspect-ratio={aspectRatio}
+      data-slot="blog-card-root"
+      {...props}
+    >
+      {children}
+    </BlogCardRootElement>
+  );
+}
diff --git a/src/components/blog-post-card/primitives/blog-post-card-skeleton.tsx b/src/components/blog-card/primitives/blog-card-skeleton.tsx
similarity index 63%
rename from src/components/blog-post-card/primitives/blog-post-card-skeleton.tsx
rename to src/components/blog-card/primitives/blog-card-skeleton.tsx
index 460f228..8129ec6 100644
--- a/src/components/blog-post-card/primitives/blog-post-card-skeleton.tsx
+++ b/src/components/blog-card/primitives/blog-card-skeleton.tsx
@@ -3,22 +3,22 @@ import type { ComponentProps } from 'react';
 import * as SkeletonPrimitive from '@/components/skeleton';
 import { cn } from '@/lib';
 
-export type BlogPostCardSkeletonProps = ComponentProps<'div'>;
+export type BlogCardSkeletonProps = ComponentProps<'div'>;
 
-export function BlogPostCardSkeleton({ className, ...props }: BlogPostCardSkeletonProps) {
+export function BlogCardSkeleton({ className, ...props }: BlogCardSkeletonProps) {
   return (
     <div
       className={cn('w-full max-w-md @container', className)}
-      data-slot="blog-post-card-skeleton"
+      data-slot="blog-card-skeleton"
       {...props}
     >
       <SkeletonPrimitive.Box
         className={cn(
           'mb-4 w-full rounded-2xl',
-          'group-data-[aspect-ratio=5/6]/blog-post-card:aspect-[5/6]',
-          'group-data-[aspect-ratio=3/4]/blog-post-card:aspect-[3/4]',
-          'group-data-[aspect-ratio=4/3]/blog-post-card:aspect-[4/3]',
-          'group-data-[aspect-ratio=1/1]/blog-post-card:aspect-square',
+          'group-data-[aspect-ratio=5/6]/blog-card:aspect-[5/6]',
+          'group-data-[aspect-ratio=3/4]/blog-card:aspect-[3/4]',
+          'group-data-[aspect-ratio=4/3]/blog-card:aspect-[4/3]',
+          'group-data-[aspect-ratio=1/1]/blog-card:aspect-square',
         )}
       />
       <SkeletonPrimitive.Text characterCount={25} className="mt-4 rounded text-lg" />
diff --git a/src/components/blog-card/primitives/blog-card-thumbnail.tsx b/src/components/blog-card/primitives/blog-card-thumbnail.tsx
new file mode 100644
index 0000000..3ded25f
--- /dev/null
+++ b/src/components/blog-card/primitives/blog-card-thumbnail.tsx
@@ -0,0 +1,24 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type BlogCardThumbnailProps = ComponentProps<'div'>;
+
+export function BlogCardThumbnail({ className, children, ...props }: BlogCardThumbnailProps) {
+  return (
+    <div
+      className={cn(
+        'relative w-full overflow-hidden rounded-2xl bg-[--fill-image]',
+        'group-data-[aspect-ratio=5/6]/blog-card:aspect-[5/6]',
+        'group-data-[aspect-ratio=3/4]/blog-card:aspect-[3/4]',
+        'group-data-[aspect-ratio=4/3]/blog-card:aspect-[4/3]',
+        'group-data-[aspect-ratio=1/1]/blog-card:aspect-square',
+        className,
+      )}
+      data-slot="blog-card-thumbnail"
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
diff --git a/src/components/blog-card/primitives/blog-card-title.tsx b/src/components/blog-card/primitives/blog-card-title.tsx
new file mode 100644
index 0000000..7668b04
--- /dev/null
+++ b/src/components/blog-card/primitives/blog-card-title.tsx
@@ -0,0 +1,20 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type BlogCardTitleProps = ComponentProps<'h5'>;
+
+export function BlogCardTitle({ className, children, ...props }: BlogCardTitleProps) {
+  return (
+    <h5
+      className={cn(
+        'mt-3 text-base leading-snug text-[--blog-card-text-primary,var(--text-primary)] [font-family:var(--blog-card-font-title,var(--font-body))] @lg:mt-4 @lg:text-xl',
+        className,
+      )}
+      data-slot="blog-card-title"
+      {...props}
+    >
+      {children}
+    </h5>
+  );
+}
diff --git a/src/components/blog-card/storybook/blog-card.stories.tsx b/src/components/blog-card/storybook/blog-card.stories.tsx
new file mode 100644
index 0000000..3d81c1a
--- /dev/null
+++ b/src/components/blog-card/storybook/blog-card.stories.tsx
@@ -0,0 +1,285 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import * as BlogCardPrimitive from '@/components/blog-card';
+import { BlogCard, type BlogCardProps } from '@/components/blog-card/blog-card';
+
+const meta: Meta<typeof BlogCard> = {
+  title: 'Components/BlogCard',
+  component: BlogCard,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: `
+A card component for displaying blog post previews with image, title, content summary, date, and optional author.
+
+## CSS Variables
+
+\`\`\`css
+:root {
+  --blog-card-text-primary: var(--text-primary);
+  --blog-card-text-secondary: var(--text-secondary);
+  --blog-card-font-title: var(--font-body);
+  --blog-card-font-content: var(--font-body);
+}
+\`\`\`
+
+## Container Queries
+
+The component adapts at the \`@lg\` breakpoint (32rem).
+
+| Element | Below @lg       | @lg and above    |
+|---------|-----------------|------------------|
+| Title   | text-base, mt-3 | text-xl, mt-4    |
+| Content | text-sm, mt-2   | text-base, mt-3  |
+| Details | text-sm         | text-base        |
+        `,
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    aspectRatio: {
+      control: 'select',
+      options: ['5/6', '3/4', '4/3', '1/1'],
+      description: 'Thumbnail image aspect ratio',
+    },
+    title: {
+      control: 'text',
+      description: 'Blog post title',
+    },
+    content: {
+      control: 'text',
+      description: 'Content summary',
+    },
+    date: {
+      control: 'text',
+      description: 'Publication date',
+    },
+    author: {
+      control: 'text',
+      description: 'Author name (optional)',
+    },
+    image: {
+      control: 'object',
+      description: 'Image object with `src` and `alt`',
+    },
+    link: {
+      control: 'object',
+      description: 'Link object with `href` and `ariaLabel`',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<BlogCardProps>;
+
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Blog card with image, title, content, date, and author.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-80">
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    title: "Sustainable Cleaning: A Beginner's Guide",
+    content:
+      'Discover how small changes in your cleaning routine can make a big impact on the environment. From natural ingredients to reusable tools, we cover everything you need to get started.',
+    date: 'December 15, 2024',
+    author: 'Sarah Mitchell',
+    image: {
+      src: 'https://images.unsplash.com/photo-1685052392996-5c042ab4c170?w=900',
+      alt: 'Eco-friendly cleaning supplies arranged on a wooden surface',
+    },
+    link: {
+      href: '/blog/sustainable-cleaning-guide',
+      ariaLabel: "Read Sustainable Cleaning: A Beginner's Guide",
+    },
+  },
+};
+
+export const WithoutImage: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'When no image is provided, a fallback displays the title text.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-80">
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    title: 'Natural Cleaning Ingredients You Already Have',
+    content:
+      'Your pantry is full of powerful cleaning agents. Learn how to use vinegar, baking soda, and lemon to keep your home sparkling clean.',
+    date: 'December 5, 2024',
+    author: 'James Chen',
+    link: {
+      href: '/blog/natural-cleaning-ingredients',
+      ariaLabel: 'Read Natural Cleaning Ingredients You Already Have',
+    },
+  },
+};
+
+export const ContainerQueries: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Typography and spacing adapt at the `@lg` breakpoint (32rem).',
+      },
+      source: {
+        code: `
+// Small container - text-base title, text-sm content
+<div className="w-72">
+  <BlogCard {...props} />
+</div>
+
+// Large container - text-xl title, text-base content
+<div className="w-[32rem]">
+  <BlogCard {...props} />
+</div>
+        `,
+      },
+    },
+  },
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <p className="mb-2 text-sm text-contrast-400">Small container (below @lg breakpoint)</p>
+        <div className="w-72">
+          <BlogCard
+            content="Discover how small changes in your cleaning routine can make a big impact on the environment."
+            date="December 15, 2024"
+            image={{
+              src: 'https://images.unsplash.com/photo-1590439471364-192aa70c0b53?w=900',
+              alt: 'Bamboo countertop brush',
+            }}
+            link={{
+              href: '/blog/eco-cleaning',
+              ariaLabel: 'Read Eco-Friendly Cleaning Tips',
+            }}
+            title="Eco-Friendly Cleaning Tips"
+          />
+        </div>
+      </div>
+      <div>
+        <p className="mb-2 text-sm text-contrast-400">Large container (at @lg breakpoint)</p>
+        <div className="w-[32rem]">
+          <BlogCard
+            content="Discover how small changes in your cleaning routine can make a big impact on the environment."
+            date="December 15, 2024"
+            image={{
+              src: 'https://images.unsplash.com/photo-1590439471364-192aa70c0b53?w=900',
+              alt: 'Bamboo countertop brush',
+            }}
+            link={{
+              href: '/blog/eco-cleaning',
+              ariaLabel: 'Read Eco-Friendly Cleaning Tips',
+            }}
+            title="Eco-Friendly Cleaning Tips"
+          />
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitives to build custom blog card layouts.',
+      },
+      source: {
+        code: `
+import * as BlogCardPrimitive from '@/components/blog-card';
+
+<BlogCardPrimitive.Root aspectRatio="4/3">
+  <BlogCardPrimitive.Thumbnail>
+    <BlogCardPrimitive.Image src="..." alt="..." />
+  </BlogCardPrimitive.Thumbnail>
+  <BlogCardPrimitive.Title>Post Title</BlogCardPrimitive.Title>
+  <BlogCardPrimitive.Content>Summary text...</BlogCardPrimitive.Content>
+  <BlogCardPrimitive.Details>
+    <BlogCardPrimitive.Date>December 15, 2024</BlogCardPrimitive.Date>
+    <BlogCardPrimitive.Author>Author Name</BlogCardPrimitive.Author>
+  </BlogCardPrimitive.Details>
+  <BlogCardPrimitive.Link href="/blog/post" aria-label="Read post" />
+</BlogCardPrimitive.Root>
+        `,
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-80">
+        <Story />
+      </div>
+    ),
+  ],
+  render: () => (
+    <BlogCardPrimitive.Root aspectRatio="4/3">
+      <BlogCardPrimitive.Thumbnail>
+        <BlogCardPrimitive.Image
+          alt="Glass soap pump bottles on a shelf"
+          src="https://images.unsplash.com/photo-1606448009227-af1758630e60?w=900"
+        />
+      </BlogCardPrimitive.Thumbnail>
+      <BlogCardPrimitive.Title>DIY Natural Cleaning Solutions</BlogCardPrimitive.Title>
+      <BlogCardPrimitive.Content>
+        Create your own effective cleaning products using simple, natural ingredients. Safe for your
+        family and the environment.
+      </BlogCardPrimitive.Content>
+      <BlogCardPrimitive.Details>
+        <BlogCardPrimitive.Date>November 20, 2024</BlogCardPrimitive.Date>
+        <BlogCardPrimitive.Author>Emma Wilson</BlogCardPrimitive.Author>
+      </BlogCardPrimitive.Details>
+      <BlogCardPrimitive.Link
+        aria-label="Read DIY Natural Cleaning Solutions"
+        href="/blog/diy-natural-cleaning"
+      />
+    </BlogCardPrimitive.Root>
+  ),
+};
+
+export const Skeleton: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Loading state while blog post data loads.',
+      },
+      source: {
+        code: `
+<BlogCardPrimitive.Root aspectRatio="4/3">
+  <BlogCardPrimitive.Skeleton />
+</BlogCardPrimitive.Root>
+        `,
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-80">
+        <Story />
+      </div>
+    ),
+  ],
+  render: () => (
+    <BlogCardPrimitive.Root aspectRatio="4/3">
+      <BlogCardPrimitive.Skeleton />
+    </BlogCardPrimitive.Root>
+  ),
+};
diff --git a/src/components/blog-post-card/blog-post-card.tsx b/src/components/blog-post-card/blog-post-card.tsx
deleted file mode 100644
index a826812..0000000
--- a/src/components/blog-post-card/blog-post-card.tsx
+++ /dev/null
@@ -1,68 +0,0 @@
-import * as BlogPostCardPrimitive from '@/components/blog-post-card';
-
-export interface BlogPostCardProps {
-  className?: string;
-  aspectRatio?: '5/6' | '3/4' | '4/3' | '1/1';
-  title: string;
-  author?: string;
-  content: string;
-  date: string;
-  image?: {
-    src: string;
-    alt: string;
-  };
-  link: {
-    href: string;
-    ariaLabel: string;
-  };
-}
-
-/**
- * This component supports various CSS variables for theming. Here's a comprehensive list, along
- * with their default values:
- *
- * ```css
- * :root {
- *   --blog-post-card-focus: var(--brand);
- *   --blog-post-card-image-background: var(--contrast-100);
- *   --blog-post-card-empty-text: color-mix(in oklab, var(--foreground) 15%, transparent);
- *   --blog-post-card-title-text: var(--foreground);
- *   --blog-post-card-content-text: var(--contrast-400);
- *   --blog-post-card-author-date-text: var(--foreground);
- *   --blog-post-card-font-family: var(--font-family-body);
- *   --blog-post-card-summary-text: var(--contrast-400);
- *   --blog-post-card-author-date-text: var(--foreground);
- * }
- * ```
- */
-export function BlogPostCard({
-  author,
-  aspectRatio = '4/3',
-  content,
-  date,
-  link,
-  image,
-  title,
-  className,
-}: BlogPostCardProps) {
-  return (
-    <BlogPostCardPrimitive.Root aspectRatio={aspectRatio} className={className}>
-      <BlogPostCardPrimitive.Thumbnail>
-        {image ? (
-          <BlogPostCardPrimitive.Image alt={image.alt} src={image.src} />
-        ) : (
-          <BlogPostCardPrimitive.Fallback>{title}</BlogPostCardPrimitive.Fallback>
-        )}
-      </BlogPostCardPrimitive.Thumbnail>
-      <BlogPostCardPrimitive.Title>{title}</BlogPostCardPrimitive.Title>
-      <BlogPostCardPrimitive.Content>{content}</BlogPostCardPrimitive.Content>
-      <BlogPostCardPrimitive.Details>
-        <BlogPostCardPrimitive.Date>{date}</BlogPostCardPrimitive.Date>
-        {author !== undefined && (
-          <BlogPostCardPrimitive.Author>{author}</BlogPostCardPrimitive.Author>
-        )}
-      </BlogPostCardPrimitive.Details>
-      <BlogPostCardPrimitive.Link aria-label={link.ariaLabel} href={link.href} />
-    </BlogPostCardPrimitive.Root>
-  );
-}
diff --git a/src/components/blog-post-card/index.ts b/src/components/blog-post-card/index.ts
deleted file mode 100644
index ad22777..0000000
--- a/src/components/blog-post-card/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { BlogPostCard, type BlogPostCardProps } from '@/components/blog-post-card/blog-post-card';
-export * from '@/components/blog-post-card/primitives';
diff --git a/src/components/blog-post-card/primitives.ts b/src/components/blog-post-card/primitives.ts
deleted file mode 100644
index 22d280e..0000000
--- a/src/components/blog-post-card/primitives.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-export {
-  BlogPostCardRoot as Root,
-  type BlogPostCardRootProps as RootProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-root';
-export {
-  BlogPostCardFallback as Fallback,
-  type BlogPostCardFallbackProps as FallbackProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-fallback';
-export {
-  BlogPostCardThumbnail as Thumbnail,
-  type BlogPostCardThumbnailProps as ThumbnailProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-thumbnail';
-export {
-  BlogPostCardImage as Image,
-  type BlogPostCardImageProps as ImageProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-image';
-export {
-  BlogPostCardLink as Link,
-  type BlogPostCardLinkProps as LinkProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-link';
-export {
-  BlogPostCardTitle as Title,
-  type BlogPostCardTitleProps as TitleProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-title';
-export {
-  BlogPostCardContent as Content,
-  type BlogPostCardContentProps as ContentProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-content';
-export {
-  BlogPostCardDetails as Details,
-  type BlogPostCardDetailsProps as DetailsProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-details';
-export {
-  BlogPostCardDate as Date,
-  type BlogPostCardDateProps as DateProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-date';
-export {
-  BlogPostCardAuthor as Author,
-  type BlogPostCardAuthorProps as AuthorProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-author';
-export {
-  BlogPostCardSkeleton as Skeleton,
-  type BlogPostCardSkeletonProps as SkeletonProps,
-} from '@/components/blog-post-card/primitives/blog-post-card-skeleton';
diff --git a/src/components/blog-post-card/primitives/blog-post-card-content.tsx b/src/components/blog-post-card/primitives/blog-post-card-content.tsx
deleted file mode 100644
index 8e56b80..0000000
--- a/src/components/blog-post-card/primitives/blog-post-card-content.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type BlogPostCardContentProps = ComponentProps<'p'>;
-
-export function BlogPostCardContent({ className, children, ...props }: BlogPostCardContentProps) {
-  return (
-    <p
-      className={cn(
-        'mt-1.5 line-clamp-3 text-sm font-normal text-[var(--blog-post-card-content-text,var(--contrast-400))]',
-        className,
-      )}
-      data-slot="blog-post-card-content"
-      {...props}
-    >
-      {children}
-    </p>
-  );
-}
diff --git a/src/components/blog-post-card/primitives/blog-post-card-date.tsx b/src/components/blog-post-card/primitives/blog-post-card-date.tsx
deleted file mode 100644
index 17857ff..0000000
--- a/src/components/blog-post-card/primitives/blog-post-card-date.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-import type { ComponentProps } from 'react';
-
-export type BlogPostCardDateProps = ComponentProps<'time'> & {
-  children: string;
-};
-
-export function BlogPostCardDate({ className, children, ...props }: BlogPostCardDateProps) {
-  return (
-    <time className={className} data-slot="blog-post-card-date" dateTime={children} {...props}>
-      {new Date(children).toLocaleDateString('en-US', {
-        year: 'numeric',
-        month: 'long',
-        day: 'numeric',
-      })}
-    </time>
-  );
-}
diff --git a/src/components/blog-post-card/primitives/blog-post-card-details.tsx b/src/components/blog-post-card/primitives/blog-post-card-details.tsx
deleted file mode 100644
index 43335bb..0000000
--- a/src/components/blog-post-card/primitives/blog-post-card-details.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type BlogPostCardDetailsProps = ComponentProps<'div'>;
-
-export function BlogPostCardDetails({ children, className, ...props }: BlogPostCardDetailsProps) {
-  return (
-    <div
-      className={cn(
-        'mt-3 text-sm text-[var(--blog-post-card-author-date-text,var(--foreground))]',
-        className,
-      )}
-      data-slot="blog-post-card-details"
-      {...props}
-    >
-      {children}
-    </div>
-  );
-}
diff --git a/src/components/blog-post-card/primitives/blog-post-card-fallback.tsx b/src/components/blog-post-card/primitives/blog-post-card-fallback.tsx
deleted file mode 100644
index 03b336a..0000000
--- a/src/components/blog-post-card/primitives/blog-post-card-fallback.tsx
+++ /dev/null
@@ -1,22 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type BlogPostCardFallbackProps = ComponentProps<'div'>;
-
-export function BlogPostCardFallback({ children, className, ...props }: BlogPostCardFallbackProps) {
-  return (
-    <div
-      className={cn(
-        'break-words p-4 text-4xl font-bold leading-none tracking-tight transition-transform duration-500 ease-out [color:color-mix(in_oklab,var(--foreground)_30%,transparent)]',
-        // Group hover state
-        'group-hover/blog-post-card:scale-105',
-        className,
-      )}
-      data-slot="blog-post-card-fallback"
-      {...props}
-    >
-      {children}
-    </div>
-  );
-}
diff --git a/src/components/blog-post-card/primitives/blog-post-card-link.tsx b/src/components/blog-post-card/primitives/blog-post-card-link.tsx
deleted file mode 100644
index d78eb8b..0000000
--- a/src/components/blog-post-card/primitives/blog-post-card-link.tsx
+++ /dev/null
@@ -1,25 +0,0 @@
-import { Slot } from '@radix-ui/react-slot';
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export interface BlogPostCardLinkProps extends ComponentProps<'a'> {
-  asChild?: boolean;
-}
-
-export function BlogPostCardLink({ asChild = false, className, ...props }: BlogPostCardLinkProps) {
-  const Component = asChild ? Slot : 'a';
-
-  return (
-    <Component
-      className={cn(
-        'absolute inset-0 rounded-b-lg rounded-t-2xl',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-[var(--blog-post-card-focus,var(--brand))]',
-        className,
-      )}
-      data-slot="blog-post-card-link"
-      {...props}
-    />
-  );
-}
diff --git a/src/components/blog-post-card/primitives/blog-post-card-root.tsx b/src/components/blog-post-card/primitives/blog-post-card-root.tsx
deleted file mode 100644
index 8b362a8..0000000
--- a/src/components/blog-post-card/primitives/blog-post-card-root.tsx
+++ /dev/null
@@ -1,35 +0,0 @@
-import type { ComponentProps, ElementType } from 'react';
-
-import { cn } from '@/lib';
-
-export type BlogPostCardRootProps<E extends ElementType = 'article'> = Omit<
-  ComponentProps<E>,
-  'as'
-> & {
-  as?: E;
-  aspectRatio?: '5/6' | '3/4' | '4/3' | '1/1';
-};
-
-export function BlogPostCardRoot<T extends ElementType = 'article'>({
-  as,
-  className,
-  children,
-  aspectRatio = '4/3',
-  ...props
-}: BlogPostCardRootProps<T>) {
-  const BlogPostCardRootElement = as ?? 'article';
-
-  return (
-    <BlogPostCardRootElement
-      className={cn(
-        'group/blog-post-card relative w-full max-w-md @container [font-family:var(--blog-post-card-font-family,var(--font-family-body))]',
-        className,
-      )}
-      data-aspect-ratio={aspectRatio}
-      data-slot="blog-post-card-root"
-      {...props}
-    >
-      {children}
-    </BlogPostCardRootElement>
-  );
-}
diff --git a/src/components/blog-post-card/primitives/blog-post-card-thumbnail.tsx b/src/components/blog-post-card/primitives/blog-post-card-thumbnail.tsx
deleted file mode 100644
index 71bd4ec..0000000
--- a/src/components/blog-post-card/primitives/blog-post-card-thumbnail.tsx
+++ /dev/null
@@ -1,28 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type BlogPostCardThumbnailProps = ComponentProps<'div'>;
-
-export function BlogPostCardThumbnail({
-  className,
-  children,
-  ...props
-}: BlogPostCardThumbnailProps) {
-  return (
-    <div
-      className={cn(
-        'relative w-full overflow-hidden rounded-2xl bg-[var(--blog-post-card-image-background,var(--contrast-100))]',
-        'group-data-[aspect-ratio=5/6]/blog-post-card:aspect-[5/6]',
-        'group-data-[aspect-ratio=3/4]/blog-post-card:aspect-[3/4]',
-        'group-data-[aspect-ratio=4/3]/blog-post-card:aspect-[4/3]',
-        'group-data-[aspect-ratio=1/1]/blog-post-card:aspect-square',
-        className,
-      )}
-      data-slot="blog-post-card-thumbnail"
-      {...props}
-    >
-      {children}
-    </div>
-  );
-}
diff --git a/src/components/blog-post-card/primitives/blog-post-card-title.tsx b/src/components/blog-post-card/primitives/blog-post-card-title.tsx
deleted file mode 100644
index fddd390..0000000
--- a/src/components/blog-post-card/primitives/blog-post-card-title.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type BlogPostCardTitleProps = ComponentProps<'h5'>;
-
-export function BlogPostCardTitle({ className, children, ...props }: BlogPostCardTitleProps) {
-  return (
-    <h5
-      className={cn(
-        'mt-4 text-lg font-normal leading-snug text-[var(--blog-post-card-title-text,var(--foreground))]',
-        className,
-      )}
-      data-slot="blog-post-card-title"
-      {...props}
-    >
-      {children}
-    </h5>
-  );
-}
diff --git a/src/components/blog-post-card/storybook/blog-post-card.stories.tsx b/src/components/blog-post-card/storybook/blog-post-card.stories.tsx
deleted file mode 100644
index aabfa6c..0000000
--- a/src/components/blog-post-card/storybook/blog-post-card.stories.tsx
+++ /dev/null
@@ -1,274 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
-
-import * as BlogPostCardPrimitive from '@/components/blog-post-card';
-import { BlogPostCard, type BlogPostCardProps } from '@/components/blog-post-card/blog-post-card';
-
-const meta: Meta<typeof BlogPostCard> = {
-  title: 'Components/BlogPostCard',
-  component: BlogPostCard,
-  parameters: {
-    layout: 'centered',
-    docs: {
-      description: {
-        component: `
-The BlogPostCard component displays a blog post preview with image, title, content summary, date, and optional author.
-
-## CSS Variables
-
-The following CSS variables can be used to customize the BlogPostCard component:
-
-\`\`\`css
-:root {
-  --blog-post-card-focus: var(--brand);
-  --blog-post-card-image-background: var(--contrast-100);
-  --blog-post-card-empty-text: color-mix(in oklab, var(--foreground) 15%, transparent);
-  --blog-post-card-title-text: var(--foreground);
-  --blog-post-card-content-text: var(--contrast-400);
-  --blog-post-card-author-date-text: var(--foreground);
-  --blog-post-card-font-family: var(--font-family-body);
-  --blog-post-card-summary-text: var(--contrast-400);
-}
-\`\`\`
-
-## Aspect Ratios
-
-The component supports four aspect ratios for the thumbnail image:
-- \`4/3\` (default) - Landscape, ideal for blog imagery
-- \`5/6\` - Slightly tall
-- \`3/4\` - Portrait orientation
-- \`1/1\` - Square format
-        `,
-      },
-    },
-  },
-  tags: ['autodocs'],
-  argTypes: {
-    aspectRatio: {
-      control: 'select',
-      options: ['5/6', '3/4', '4/3', '1/1'],
-      description: 'The aspect ratio of the thumbnail image',
-    },
-    title: {
-      control: 'text',
-      description: 'The blog post title',
-    },
-    content: {
-      control: 'text',
-      description: 'The blog post content summary',
-    },
-    date: {
-      control: 'text',
-      description: 'The publication date',
-    },
-    author: {
-      control: 'text',
-      description: 'The author name (optional)',
-    },
-    image: {
-      control: 'object',
-      description: 'The thumbnail image object with src and alt',
-    },
-    link: {
-      control: 'object',
-      description: 'The link object with href and ariaLabel',
-    },
-  },
-};
-
-export default meta;
-type Story = StoryObj<BlogPostCardProps>;
-
-function StoryWrapper({ children }: { children: React.ReactNode }) {
-  return <div className="w-80">{children}</div>;
-}
-
-/**
- * The default BlogPostCard displays a thumbnail, title, content summary, and date.
- */
-export const Default: Story = {
-  decorators: [
-    (Story) => (
-      <StoryWrapper>
-        <Story />
-      </StoryWrapper>
-    ),
-  ],
-  args: {
-    title: "Sustainable Cleaning: A Beginner's Guide",
-    content:
-      'Discover how small changes in your cleaning routine can make a big impact on the environment. From natural ingredients to reusable tools, we cover everything you need to get started.',
-    date: 'December 15, 2024',
-    image: {
-      src: 'https://images.unsplash.com/photo-1685052392996-5c042ab4c170?w=900',
-      alt: 'Eco-friendly cleaning supplies arranged on a wooden surface',
-    },
-    link: {
-      href: '/blog/sustainable-cleaning-guide',
-      ariaLabel: "Read Sustainable Cleaning: A Beginner's Guide",
-    },
-  },
-};
-
-/**
- * BlogPostCard with an author displayed below the date.
- */
-export const WithAuthor: Story = {
-  decorators: [
-    (Story) => (
-      <StoryWrapper>
-        <Story />
-      </StoryWrapper>
-    ),
-  ],
-  args: {
-    title: 'The Art of Minimalist Home Organization',
-    content:
-      'Learn how to declutter your space and create a serene home environment with our step-by-step guide to minimalist organization principles.',
-    date: 'December 10, 2024',
-    author: 'Sarah Mitchell',
-    image: {
-      src: 'https://images.unsplash.com/photo-1597816189341-6ed558ab017e?w=900',
-      alt: 'Minimal ceramic soap dispenser in a clean bathroom',
-    },
-    link: {
-      href: '/blog/minimalist-home-organization',
-      ariaLabel: 'Read The Art of Minimalist Home Organization',
-    },
-  },
-};
-
-/**
- * BlogPostCard without an image displays a fallback with the title.
- */
-export const WithoutImage: Story = {
-  decorators: [
-    (Story) => (
-      <StoryWrapper>
-        <Story />
-      </StoryWrapper>
-    ),
-  ],
-  args: {
-    title: 'Natural Cleaning Ingredients You Already Have',
-    content:
-      'Your pantry is full of powerful cleaning agents. Learn how to use vinegar, baking soda, and lemon to keep your home sparkling clean.',
-    date: 'December 5, 2024',
-    author: 'James Chen',
-    link: {
-      href: '/blog/natural-cleaning-ingredients',
-      ariaLabel: 'Read Natural Cleaning Ingredients You Already Have',
-    },
-  },
-};
-
-/**
- * BlogPostCard with a square aspect ratio.
- */
-export const SquareAspectRatio: Story = {
-  decorators: [
-    (Story) => (
-      <StoryWrapper>
-        <Story />
-      </StoryWrapper>
-    ),
-  ],
-  args: {
-    aspectRatio: '1/1',
-    title: 'Zero-Waste Kitchen Essentials',
-    content:
-      'Transform your kitchen into an eco-friendly space with these essential zero-waste products and practices.',
-    date: 'November 28, 2024',
-    image: {
-      src: 'https://images.unsplash.com/photo-1590439471364-192aa70c0b53?w=900',
-      alt: 'Bamboo countertop brush',
-    },
-    link: {
-      href: '/blog/zero-waste-kitchen',
-      ariaLabel: 'Read Zero-Waste Kitchen Essentials',
-    },
-  },
-};
-
-/**
- * ## Composable Anatomy
- *
- * For advanced customization, you can use the primitive components directly. The primitives include:
- *
- * - `Root` - Container with aspect ratio configuration
- * - `Thumbnail` - Image container
- * - `Image` - Blog post image with hover effects
- * - `Fallback` - Displayed when no image is available
- * - `Title` - Blog post title
- * - `Content` - Content summary text
- * - `Details` - Container for date and author
- * - `Date` - Publication date
- * - `Author` - Author name
- * - `Link` - Invisible link overlay for click area
- *
- * ```tsx
- * import * as BlogPostCardPrimitive from '@/components/blog-post-card';
- *
- * <BlogPostCardPrimitive.Root aspectRatio="4/3">
- *   <BlogPostCardPrimitive.Thumbnail>
- *     <BlogPostCardPrimitive.Image src="..." alt="..." />
- *   </BlogPostCardPrimitive.Thumbnail>
- *   <BlogPostCardPrimitive.Title>Post Title</BlogPostCardPrimitive.Title>
- *   <BlogPostCardPrimitive.Content>Summary text...</BlogPostCardPrimitive.Content>
- *   <BlogPostCardPrimitive.Details>
- *     <BlogPostCardPrimitive.Date>December 15, 2024</BlogPostCardPrimitive.Date>
- *     <BlogPostCardPrimitive.Author>Author Name</BlogPostCardPrimitive.Author>
- *   </BlogPostCardPrimitive.Details>
- *   <BlogPostCardPrimitive.Link href="/blog/post" aria-label="Read post" />
- * </BlogPostCardPrimitive.Root>
- * ```
- */
-export const ComposableAnatomy: Story = {
-  decorators: [
-    (Story) => (
-      <StoryWrapper>
-        <Story />
-      </StoryWrapper>
-    ),
-  ],
-  render: () => (
-    <BlogPostCardPrimitive.Root aspectRatio="4/3">
-      <BlogPostCardPrimitive.Thumbnail>
-        <BlogPostCardPrimitive.Image
-          alt="Glass soap pump bottles on a shelf"
-          src="https://images.unsplash.com/photo-1606448009227-af1758630e60?w=900"
-        />
-      </BlogPostCardPrimitive.Thumbnail>
-      <BlogPostCardPrimitive.Title>DIY Natural Cleaning Solutions</BlogPostCardPrimitive.Title>
-      <BlogPostCardPrimitive.Content>
-        Create your own effective cleaning products using simple, natural ingredients. Safe for your
-        family and the environment.
-      </BlogPostCardPrimitive.Content>
-      <BlogPostCardPrimitive.Details>
-        <BlogPostCardPrimitive.Date>November 20, 2024</BlogPostCardPrimitive.Date>
-        <BlogPostCardPrimitive.Author>Emma Wilson</BlogPostCardPrimitive.Author>
-      </BlogPostCardPrimitive.Details>
-      <BlogPostCardPrimitive.Link
-        aria-label="Read DIY Natural Cleaning Solutions"
-        href="/blog/diy-natural-cleaning"
-      />
-    </BlogPostCardPrimitive.Root>
-  ),
-};
-
-/**
- * The skeleton state is displayed while blog post data is loading.
- */
-export const Skeleton: Story = {
-  decorators: [
-    (Story) => (
-      <StoryWrapper>
-        <Story />
-      </StoryWrapper>
-    ),
-  ],
-  render: () => (
-    <BlogPostCardPrimitive.Root aspectRatio="4/3">
-      <BlogPostCardPrimitive.Skeleton />
-    </BlogPostCardPrimitive.Root>
-  ),
-};
diff --git a/src/components/breadcrumbs/breadcrumbs.tsx b/src/components/breadcrumbs/breadcrumbs.tsx
index 6f87c46..4aa0692 100644
--- a/src/components/breadcrumbs/breadcrumbs.tsx
+++ b/src/components/breadcrumbs/breadcrumbs.tsx
@@ -27,10 +27,10 @@ export interface BreadcrumbsProps {
  *
  * ```css
  * :root {
- *   --breadcrumbs-font-family: var(--font-family-body);
- *   --breadcrumbs-primary-text: var(--foreground);
- *   --breadcrumbs-secondary-text: var(--contrast-500);
- *   --breadcrumbs-icon: var(--contrast-500);
+ *   --breadcrumbs-font:           var(--font-body);
+ *   --breadcrumbs-text-primary:   var(--primary-text);
+ *   --breadcrumbs-text-secondary: var(--text-secondary);
+ *   --breadcrumbs-fill-icon:      var(--contrast-400);
  * }
  * ```
  */
diff --git a/src/components/breadcrumbs/primitives/breadcrumbs-current.tsx b/src/components/breadcrumbs/primitives/breadcrumbs-current.tsx
index 4a1d056..b2d98a1 100644
--- a/src/components/breadcrumbs/primitives/breadcrumbs-current.tsx
+++ b/src/components/breadcrumbs/primitives/breadcrumbs-current.tsx
@@ -9,7 +9,7 @@ export function BreadcrumbsCurrent({ className, children, ...props }: Breadcrumb
     <span
       aria-current="page"
       aria-disabled="true"
-      className={cn('text-[var(--breadcrumbs-secondary-text,var(--contrast-500))]', className)}
+      className={cn('text-[--breadcrumbs-text-secondary,var(--text-secondary)]', className)}
       data-slot="breadcrumbs-current"
       role="link"
       {...props}
diff --git a/src/components/breadcrumbs/primitives/breadcrumbs-icon.tsx b/src/components/breadcrumbs/primitives/breadcrumbs-icon.tsx
index c490519..909a402 100644
--- a/src/components/breadcrumbs/primitives/breadcrumbs-icon.tsx
+++ b/src/components/breadcrumbs/primitives/breadcrumbs-icon.tsx
@@ -13,13 +13,11 @@ export interface BreadcrumbsIconProps {
 }
 
 export function BreadcrumbsIcon({ asChild = false, className, children }: BreadcrumbsIconProps) {
+  const iconStyles = cn('size-5 text-[--breadcrumbs-fill-icon,var(--contrast-400)]', className);
+
   if (asChild) {
     return (
-      <Slot
-        aria-hidden="true"
-        className={cn('size-5 text-[var(--breadcrumbs-icon,var(--contrast-500))]', className)}
-        data-slot="breadcrumbs-icon"
-      >
+      <Slot aria-hidden="true" className={iconStyles} data-slot="breadcrumbs-icon">
         {children}
       </Slot>
     );
@@ -29,7 +27,7 @@ export function BreadcrumbsIcon({ asChild = false, className, children }: Breadc
     <ChevronRight
       absoluteStrokeWidth
       aria-hidden="true"
-      className={cn('size-5 text-[var(--breadcrumbs-icon,var(--contrast-500))]', className)}
+      className={iconStyles}
       data-slot="breadcrumbs-icon"
       strokeWidth={1.5}
     />
diff --git a/src/components/breadcrumbs/primitives/breadcrumbs-link.tsx b/src/components/breadcrumbs/primitives/breadcrumbs-link.tsx
index 37b15d4..f9a19fd 100644
--- a/src/components/breadcrumbs/primitives/breadcrumbs-link.tsx
+++ b/src/components/breadcrumbs/primitives/breadcrumbs-link.tsx
@@ -15,9 +15,7 @@ export function BreadcrumbsLink({ asChild = false, className, ...props }: Breadc
   return (
     <Component
       className={cn(
-        'group/underline text-[var(--breadcrumbs-primary-text,var(--foreground))]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2',
+        'focus-primary group/underline text-[--breadcrumbs-text-primary,var(--primary-text)]',
         className,
       )}
       data-slot="breadcrumbs-link"
diff --git a/src/components/breadcrumbs/primitives/breadcrumbs-list.tsx b/src/components/breadcrumbs/primitives/breadcrumbs-list.tsx
index 5dc50f8..a2eed45 100644
--- a/src/components/breadcrumbs/primitives/breadcrumbs-list.tsx
+++ b/src/components/breadcrumbs/primitives/breadcrumbs-list.tsx
@@ -8,7 +8,7 @@ export function BreadcrumbsList({ className, children, ...props }: BreadcrumbsLi
   return (
     <ol
       className={cn(
-        'flex flex-wrap items-center gap-x-1.5 font-[family-name:var(--breadcrumbs-font-family,var(--font-family-body))] text-sm @xl:text-base',
+        'flex flex-wrap items-center gap-x-1.5 font-[family-name:var(--breadcrumbs-font,var(--font-body))] text-sm @xl:text-base',
         className,
       )}
       data-slot="breadcrumbs-list"
diff --git a/src/components/breadcrumbs/storybook/breadcrumbs.stories.tsx b/src/components/breadcrumbs/storybook/breadcrumbs.stories.tsx
index 8d4267e..59bd2c2 100644
--- a/src/components/breadcrumbs/storybook/breadcrumbs.stories.tsx
+++ b/src/components/breadcrumbs/storybook/breadcrumbs.stories.tsx
@@ -1,6 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Dot } from 'lucide-react';
-import type { ComponentType } from 'react';
 
 import { AnimatedUnderline } from '@/components/animated-underline';
 import { Breadcrumbs, type BreadcrumbsProps } from '@/components/breadcrumbs';
@@ -20,59 +18,11 @@ A navigation component that displays the current page's location within a hierar
 
 \`\`\`css
 :root {
-  --breadcrumbs-font-family: var(--font-family-body);
-  --breadcrumbs-primary-text: var(--foreground);
-  --breadcrumbs-secondary-text: var(--contrast-500);
-  --breadcrumbs-icon: var(--contrast-500);
+  --breadcrumbs-font: var(--font-body);
+  --breadcrumbs-text-primary: var(--foreground);
+  --breadcrumbs-text-secondary: var(--contrast-500);
+  --breadcrumbs-fill-icon: var(--contrast-500);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Breadcrumbs\` component provides a simple API for breadcrumb navigation:
-
-\`\`\`tsx
-import { Breadcrumbs } from '@/components/breadcrumbs';
-
-<Breadcrumbs
-  breadcrumbs={[
-    { label: 'Home', href: '/' },
-    { label: 'Products', href: '/products' },
-    { label: 'Cleaning Supplies', href: '/products/cleaning' },
-  ]}
-  ariaLabel="Breadcrumb"
-/>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Breadcrumbs from '@/components/breadcrumbs';
-import { AnimatedUnderline } from '@/components/animated-underline';
-
-<Breadcrumbs.Root aria-label="Breadcrumb">
-  <Breadcrumbs.List>
-    <Breadcrumbs.Item>
-      <Breadcrumbs.Link href="/">
-        <AnimatedUnderline>Home</AnimatedUnderline>
-      </Breadcrumbs.Link>
-      <Breadcrumbs.Icon />
-    </Breadcrumbs.Item>
-    <Breadcrumbs.Item>
-      <Breadcrumbs.Link href="/products">
-        <AnimatedUnderline>Products</AnimatedUnderline>
-      </Breadcrumbs.Link>
-      <Breadcrumbs.Icon />
-    </Breadcrumbs.Item>
-    <Breadcrumbs.Item>
-      <Breadcrumbs.Current>Cleaning Supplies</Breadcrumbs.Current>
-    </Breadcrumbs.Item>
-  </Breadcrumbs.List>
-</Breadcrumbs.Root>
 \`\`\`
         `,
       },
@@ -88,24 +38,15 @@ import { AnimatedUnderline } from '@/components/animated-underline';
       control: 'text',
       description: 'Accessible label for the navigation landmark',
     },
-    className: {
-      control: 'text',
-      description: 'Additional CSS classes to apply',
+    icon: {
+      description: 'Configuration for a custom separator icon with `asChild` and `children` props',
     },
   },
-  decorators: [
-    (Story: ComponentType) => (
-      <div className="bg-background p-4">
-        <Story />
-      </div>
-    ),
-  ],
 };
 
 export default meta;
 type Story = StoryObj<BreadcrumbsProps>;
 
-// Default breadcrumbs
 export const Default: Story = {
   args: {
     breadcrumbs: [
@@ -117,7 +58,6 @@ export const Default: Story = {
   },
 };
 
-// Longer breadcrumb trail
 export const LongPath: Story = {
   args: {
     breadcrumbs: [
@@ -129,9 +69,18 @@ export const LongPath: Story = {
     ],
     ariaLabel: 'Breadcrumb',
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Breadcrumbs automatically wrap when the path is long.',
+      },
+    },
+  },
 };
 
-// Composable anatomy example
+/**
+ * Use the composable primitives to build custom breadcrumb layouts.
+ */
 export const ComposableAnatomy: Story = {
   render: () => (
     <BreadcrumbsPrimitive.Root aria-label="Breadcrumb">
@@ -154,33 +103,38 @@ export const ComposableAnatomy: Story = {
       </BreadcrumbsPrimitive.List>
     </BreadcrumbsPrimitive.Root>
   ),
-};
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the composable primitives to build custom breadcrumb layouts:
 
-// Custom separator icon
-export const CustomSeparator: Story = {
-  render: () => (
-    <BreadcrumbsPrimitive.Root aria-label="Breadcrumb">
-      <BreadcrumbsPrimitive.List>
-        <BreadcrumbsPrimitive.Item>
-          <BreadcrumbsPrimitive.Link href="/">
-            <AnimatedUnderline>Home</AnimatedUnderline>
-          </BreadcrumbsPrimitive.Link>
-          <BreadcrumbsPrimitive.Icon asChild>
-            <Dot absoluteStrokeWidth strokeWidth={1.5} />
-          </BreadcrumbsPrimitive.Icon>
-        </BreadcrumbsPrimitive.Item>
-        <BreadcrumbsPrimitive.Item>
-          <BreadcrumbsPrimitive.Link href="/categories">
-            <AnimatedUnderline>Categories</AnimatedUnderline>
-          </BreadcrumbsPrimitive.Link>
-          <BreadcrumbsPrimitive.Icon asChild>
-            <Dot absoluteStrokeWidth strokeWidth={1.5} />
-          </BreadcrumbsPrimitive.Icon>
-        </BreadcrumbsPrimitive.Item>
-        <BreadcrumbsPrimitive.Item>
-          <BreadcrumbsPrimitive.Current>Bathroom</BreadcrumbsPrimitive.Current>
-        </BreadcrumbsPrimitive.Item>
-      </BreadcrumbsPrimitive.List>
-    </BreadcrumbsPrimitive.Root>
-  ),
+\`\`\`tsx
+import * as BreadcrumbsPrimitive from '@/components/breadcrumbs/primitives';
+import { AnimatedUnderline } from '@/components/animated-underline';
+
+<BreadcrumbsPrimitive.Root aria-label="Breadcrumb">
+  <BreadcrumbsPrimitive.List>
+    <BreadcrumbsPrimitive.Item>
+      <BreadcrumbsPrimitive.Link href="/">
+        <AnimatedUnderline>Home</AnimatedUnderline>
+      </BreadcrumbsPrimitive.Link>
+      <BreadcrumbsPrimitive.Icon />
+    </BreadcrumbsPrimitive.Item>
+    <BreadcrumbsPrimitive.Item>
+      <BreadcrumbsPrimitive.Link href="/products">
+        <AnimatedUnderline>Products</AnimatedUnderline>
+      </BreadcrumbsPrimitive.Link>
+      <BreadcrumbsPrimitive.Icon />
+    </BreadcrumbsPrimitive.Item>
+    <BreadcrumbsPrimitive.Item>
+      <BreadcrumbsPrimitive.Current>Current Page</BreadcrumbsPrimitive.Current>
+    </BreadcrumbsPrimitive.Item>
+  </BreadcrumbsPrimitive.List>
+</BreadcrumbsPrimitive.Root>
+\`\`\`
+        `,
+      },
+    },
+  },
 };
diff --git a/src/components/button-link/button-link.tsx b/src/components/button-link/button-link.tsx
index d7f086e..94498e5 100644
--- a/src/components/button-link/button-link.tsx
+++ b/src/components/button-link/button-link.tsx
@@ -28,12 +28,7 @@ export function ButtonLink({
 
   return (
     <Comp
-      className={cn(
-        buttonVariants({ variant, size, shape }),
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--button-focus,var(--brand))]',
-        className,
-      )}
+      className={cn(buttonVariants({ variant, size, shape }), 'focus-primary', className)}
       data-slot="button-link"
       {...props}
     >
diff --git a/src/components/button-link/storybook/button-link.stories.tsx b/src/components/button-link/storybook/button-link.stories.tsx
index 39000a3..9ca4d84 100644
--- a/src/components/button-link/storybook/button-link.stories.tsx
+++ b/src/components/button-link/storybook/button-link.stories.tsx
@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { ArrowRight } from 'lucide-react';
+import { ArrowRight, X } from 'lucide-react';
 
 import { ButtonLink, type ButtonLinkProps } from '@/components/button-link';
 
@@ -15,42 +15,20 @@ A link styled as a button. Shares the same visual styles and CSS variables as th
 
 ## CSS Variables
 
-The ButtonLink component supports extensive theming through the shared Button CSS variables:
-
 \`\`\`css
 :root {
-  --button-focus: var(--brand);
-  --button-font-family: var(--font-family-body);
-
-  /* Primary variant */
-  --button-primary-background: var(--foreground);
-  --button-primary-text: var(--background);
-
-  /* Brand variant */
-  --button-brand-background: var(--brand);
-  --button-brand-text: var(--foreground);
-
-  /* Outline variant */
-  --button-outline-background: var(--background);
-  --button-outline-text: var(--foreground);
-  --button-outline-border: var(--contrast-200);
-
-  /* Ghost variant */
-  --button-ghost-text: var(--foreground);
+  --button-font: var(--font-body);
+  --button-fill-primary: var(--foreground);
+  --button-text-primary: var(--text-inverse);
+  --button-fill-brand: var(--brand);
+  --button-text-brand: var(--text-primary);
+  --button-fill-outline: var(--background);
+  --button-text-outline: var(--text-primary);
+  --button-stroke-outline: var(--border);
+  --button-text-ghost: var(--text-primary);
+  --button-fill-danger: var(--error);
+  --button-danger-text: var(--text-inverse);
 }
-\`\`\`
-
-## Usage with Routing Libraries
-
-The \`asChild\` prop allows ButtonLink to integrate seamlessly with routing libraries like Next.js Link or React Router:
-
-\`\`\`tsx
-import { ButtonLink } from '@/components/button-link';
-import Link from 'next/link';
-
-<ButtonLink asChild variant="primary">
-  <Link href="/products">View Products</Link>
-</ButtonLink>
 \`\`\`
         `,
       },
@@ -60,7 +38,7 @@ import Link from 'next/link';
   argTypes: {
     variant: {
       control: 'select',
-      options: ['primary', 'brand', 'outline', 'ghost'],
+      options: ['primary', 'brand', 'outline', 'ghost', 'danger'],
       description: 'The visual style variant of the button link',
     },
     size: {
@@ -80,7 +58,7 @@ import Link from 'next/link';
     asChild: {
       control: 'boolean',
       description:
-        'When true, the component will render its child element instead of an anchor tag, merging props and behavior',
+        'When true, renders the child element instead of an anchor tag, merging props. Useful for routing libraries like Next.js Link.',
     },
   },
   args: {
@@ -92,7 +70,6 @@ import Link from 'next/link';
 export default meta;
 type Story = StoryObj<ButtonLinkProps>;
 
-// Default story
 export const Default: Story = {
   args: {
     variant: 'primary',
@@ -100,30 +77,39 @@ export const Default: Story = {
   },
 };
 
-// Variants
 export const AllVariants: Story = {
   render: () => (
-    <div className="flex flex-wrap items-center gap-3">
-      <ButtonLink href="#" variant="brand">
-        Brand
-      </ButtonLink>
+    <div className="flex flex-wrap items-center gap-4">
       <ButtonLink href="#" variant="primary">
         Primary
       </ButtonLink>
+      <ButtonLink href="#" variant="brand">
+        Brand
+      </ButtonLink>
       <ButtonLink href="#" variant="outline">
         Outline
       </ButtonLink>
       <ButtonLink href="#" variant="ghost">
         Ghost
       </ButtonLink>
+      <ButtonLink href="#" variant="danger">
+        Danger
+      </ButtonLink>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The button link supports five variants: `primary`, `brand`, `outline`, `ghost`, and `danger`.',
+      },
+    },
+  },
 };
 
-// Sizes
 export const AllSizes: Story = {
   render: () => (
-    <div className="flex flex-wrap items-center gap-3">
+    <div className="flex flex-wrap items-center gap-4">
       <ButtonLink href="#" size="large">
         Large
       </ButtonLink>
@@ -138,12 +124,19 @@ export const AllSizes: Story = {
       </ButtonLink>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Four size options are available: `large` (default), `medium`, `small`, and `x-small`.',
+      },
+    },
+  },
 };
 
-// Shapes
 export const AllShapes: Story = {
   render: () => (
-    <div className="flex flex-wrap items-center gap-3">
+    <div className="flex flex-wrap items-center gap-4">
       <ButtonLink href="#" shape="pill">
         Pill
       </ButtonLink>
@@ -154,17 +147,23 @@ export const AllShapes: Story = {
         Square
       </ButtonLink>
       <ButtonLink href="#" shape="circle">
-        <ArrowRight size={20} />
+        <X absoluteStrokeWidth size={20} strokeWidth={1.5} />
       </ButtonLink>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Shape options include `pill` (default), `rounded`, `square`, and `circle` (for icon-only links).',
+      },
+    },
+  },
 };
 
-// With Icon
 export const WithIcon: Story = {
   args: {
     variant: 'primary',
-    size: 'large',
     children: (
       <>
         Shop Now
@@ -172,33 +171,11 @@ export const WithIcon: Story = {
       </>
     ),
   },
-};
-
-// Icon Only
-export const IconOnly: Story = {
-  args: {
-    variant: 'primary',
-    shape: 'circle',
-    size: 'medium',
-    children: <ArrowRight size={20} />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Icons can be added as children alongside text.',
+      },
+    },
   },
 };
-
-// asChild usage with custom link
-export const WithAsChild: Story = {
-  name: 'With asChild (Router Integration)',
-  render: () => (
-    <ButtonLink asChild variant="primary">
-      <a
-        href="/products"
-        onClick={(e) => {
-          e.preventDefault();
-          alert('This would navigate using your routing library (e.g., Next.js Link)');
-        }}
-      >
-        View Products
-      </a>
-      <ArrowRight size={20} />
-    </ButtonLink>
-  ),
-};
diff --git a/src/components/button-radio-group/button-radio-group.tsx b/src/components/button-radio-group/button-radio-group.tsx
index 32da3a0..15f3124 100644
--- a/src/components/button-radio-group/button-radio-group.tsx
+++ b/src/components/button-radio-group/button-radio-group.tsx
@@ -19,17 +19,14 @@ export type ButtonRadioGroupProps = ComponentProps<typeof RadioGroupPrimitive.Ro
  * with their default values:
  *
  * ```css
- *  :root {
- *   --button-radio-group-focus: var(--brand);
- *   --button-radio-group-light-unchecked-border: var(--contrast-100);
- *   --button-radio-group-light-unchecked-background: var(--background);
- *   --button-radio-group-light-unchecked-text: var(--foreground);
- *   --button-radio-group-light-unchecked-border-hover: var(--contrast-200);
- *   --button-radio-group-light-unchecked-background-hover: var(--contrast-100);
- *   --button-radio-group-light-checked-background: var(--foreground);
- *   --button-radio-group-light-checked-text: var(--background);
- *   --button-radio-group-light-border-error: var(--error);
- *  }
+ * :root {
+ *   --button-radio-group-font: var(--font-body);
+ *   --button-radio-group-fill-unchecked: var(--form-fill-unchecked);
+ *   --button-radio-group-fill-checked: var(--form-fill-checked);
+ *   --button-radio-group-fill-hover: var(--form-fill-hover);
+ *   --button-radio-group-text-unchecked: var(--form-text-unchecked);
+ *   --button-radio-group-text-checked: var(--form-text-checked);
+ * }
  * ```
  */
 export function ButtonRadioGroup({
diff --git a/src/components/button-radio-group/primitives/button-radio-group-item.tsx b/src/components/button-radio-group/primitives/button-radio-group-item.tsx
index 58ddc6a..0c27026 100644
--- a/src/components/button-radio-group/primitives/button-radio-group-item.tsx
+++ b/src/components/button-radio-group/primitives/button-radio-group-item.tsx
@@ -9,17 +9,15 @@ export function ButtonRadioGroupItem({ children, className, ...props }: ButtonRa
   return (
     <RadioGroupPrimitive.Item
       className={cn(
-        'h-12 whitespace-nowrap rounded-full border border-[var(--button-radio-group-unchecked-border,var(--contrast-100))] px-4 font-body text-sm font-normal leading-normal transition-colors',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--button-radio-group-focus,var(--brand))]',
+        'focus-primary h-12 min-w-12 whitespace-nowrap rounded-full border border-[--border-subtle] px-4 text-sm leading-normal transition-colors [font-family:var(--button-radio-group-font,var(--font-body))]',
         // Checked state
-        'data-[state=checked]:border-[var(--button-radio-group-checked-background,var(--foreground))] data-[state=checked]:bg-[var(--button-radio-group-checked-background,var(--foreground))] data-[state=checked]:text-[var(--button-radio-group-checked-text,var(--background))]',
+        'data-[state=checked]:border-[--border-checked] data-[state=checked]:bg-[--button-radio-group-fill-checked,var(--form-fill-checked)] data-[state=checked]:text-[--button-radio-group-text-checked,var(--form-text-checked)]',
         // Unchecked state
-        'data-[state=unchecked]:bg-[var(--button-radio-group-unchecked-background,var(--background))] data-[state=unchecked]:text-[var(--button-radio-group-unchecked-text,var(--foreground))]',
+        'data-[state=unchecked]:bg-[--button-radio-group-fill-unchecked,var(--form-fill-unchecked)] data-[state=unchecked]:text-[--button-radio-group-text-unchecked,var(--form-text-unchecked)]',
         // Unchecked hover state
-        'data-[state=unchecked]:hover:border-[var(--button-radio-group-unchecked-border-hover,var(--contrast-200))] data-[state=unchecked]:hover:bg-[var(--button-radio-group-unchecked-background-hover,var(--contrast-100))]',
+        'data-[state=unchecked]:hover:border-[--border] data-[state=unchecked]:hover:bg-[--button-radio-group-fill-hover,var(--form-fill-hover)]',
         // Aria-invalid state
-        'aria-invalid:border-[var(--button-radio-group-border-error,var(--error))]',
+        'aria-invalid:border-[--error]',
         // Disabled state
         'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
         className,
diff --git a/src/components/button-radio-group/storybook/button-radio-group.stories.tsx b/src/components/button-radio-group/storybook/button-radio-group.stories.tsx
index 8f55e1f..b301c9a 100644
--- a/src/components/button-radio-group/storybook/button-radio-group.stories.tsx
+++ b/src/components/button-radio-group/storybook/button-radio-group.stories.tsx
@@ -1,7 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { useState } from 'react';
 
-import { ButtonRadioGroup } from '@/components/button-radio-group/button-radio-group';
+import {
+  ButtonRadioGroup,
+  type ButtonRadioGroupProps,
+} from '@/components/button-radio-group/button-radio-group';
 import * as ButtonRadioGroupPrimitive from '@/components/button-radio-group/primitives';
 
 const sizeOptions = [
@@ -12,12 +14,6 @@ const sizeOptions = [
   { id: 'size-xl', value: 'xl', label: 'XL' },
 ];
 
-const colorOptions = [
-  { id: 'color-natural', value: 'natural', label: 'Natural' },
-  { id: 'color-charcoal', value: 'charcoal', label: 'Charcoal' },
-  { id: 'color-sage', value: 'sage', label: 'Sage' },
-];
-
 const meta: Meta<typeof ButtonRadioGroup> = {
   title: 'Components/ButtonRadioGroup',
   component: ButtonRadioGroup,
@@ -30,57 +26,15 @@ A radio group component styled as a set of selectable buttons. Perfect for produ
 
 ## CSS Variables
 
-The ButtonRadioGroup component supports extensive theming through CSS variables:
-
 \`\`\`css
 :root {
-  --button-radio-group-focus: var(--brand);
-  --button-radio-group-light-unchecked-border: var(--contrast-100);
-  --button-radio-group-light-unchecked-background: var(--background);
-  --button-radio-group-light-unchecked-text: var(--foreground);
-  --button-radio-group-light-unchecked-border-hover: var(--contrast-200);
-  --button-radio-group-light-unchecked-background-hover: var(--contrast-100);
-  --button-radio-group-light-checked-background: var(--foreground);
-  --button-radio-group-light-checked-text: var(--background);
-  --button-radio-group-light-border-error: var(--error);
+  --button-radio-group-font: var(--font-body);
+  --button-radio-group-fill-unchecked: var(--form-fill-unchecked);
+  --button-radio-group-fill-checked: var(--form-fill-checked);
+  --button-radio-group-fill-hover: var(--form-fill-hover);
+  --button-radio-group-text-unchecked: var(--form-text-unchecked);
+  --button-radio-group-text-checked: var(--form-text-checked);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`ButtonRadioGroup\` component provides a simple API with an \`options\` array:
-
-\`\`\`tsx
-import { ButtonRadioGroup } from '@/components/button-radio-group';
-
-const sizeOptions = [
-  { id: 'size-xs', value: 'xs', label: 'XS' },
-  { id: 'size-s', value: 's', label: 'S' },
-  { id: 'size-m', value: 'm', label: 'M' },
-  { id: 'size-l', value: 'l', label: 'L' },
-];
-
-<ButtonRadioGroup
-  options={sizeOptions}
-  defaultValue="m"
-/>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as ButtonRadioGroup from '@/components/button-radio-group';
-
-<ButtonRadioGroup.Root defaultValue="m">
-  <ButtonRadioGroup.Item value="xs">XS</ButtonRadioGroup.Item>
-  <ButtonRadioGroup.Item value="s">S</ButtonRadioGroup.Item>
-  <ButtonRadioGroup.Item value="m">M</ButtonRadioGroup.Item>
-  <ButtonRadioGroup.Item value="l">L</ButtonRadioGroup.Item>
-</ButtonRadioGroup.Root>
 \`\`\`
         `,
       },
@@ -89,7 +43,8 @@ import * as ButtonRadioGroup from '@/components/button-radio-group';
   tags: ['autodocs'],
   argTypes: {
     options: {
-      description: 'Array of options with id, value, label, and optional disabled flag',
+      control: false,
+      description: 'Array of options with `id`, `value`, `label`, and optional `disabled`',
     },
     defaultValue: {
       control: 'text',
@@ -100,10 +55,12 @@ import * as ButtonRadioGroup from '@/components/button-radio-group';
       description: 'The controlled selected value',
     },
     onValueChange: {
+      control: false,
       description: 'Callback when the selected value changes',
     },
     onOptionMouseEnter: {
-      description: 'Callback when hovering over an option (useful for previews)',
+      control: false,
+      description: 'Callback when hovering over an option',
     },
     disabled: {
       control: 'boolean',
@@ -113,9 +70,8 @@ import * as ButtonRadioGroup from '@/components/button-radio-group';
 };
 
 export default meta;
-type Story = StoryObj<typeof ButtonRadioGroup>;
+type Story = StoryObj<ButtonRadioGroupProps>;
 
-// Default story using high-level component
 export const Default: Story = {
   args: {
     options: sizeOptions,
@@ -123,19 +79,25 @@ export const Default: Story = {
   },
 };
 
-// Composable anatomy example
-export const ComposableAnatomy: Story = {
-  render: () => (
-    <ButtonRadioGroupPrimitive.Root defaultValue="natural">
-      <ButtonRadioGroupPrimitive.Item value="natural">Natural</ButtonRadioGroupPrimitive.Item>
-      <ButtonRadioGroupPrimitive.Item value="charcoal">Charcoal</ButtonRadioGroupPrimitive.Item>
-      <ButtonRadioGroupPrimitive.Item value="sage">Sage</ButtonRadioGroupPrimitive.Item>
-    </ButtonRadioGroupPrimitive.Root>
-  ),
-};
-
-// Disabled items (e.g., out of stock)
 export const DisabledItems: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Individual options can be disabled (e.g., out of stock sizes).',
+      },
+      source: {
+        code: `
+<ButtonRadioGroupPrimitive.Root defaultValue="m">
+  <ButtonRadioGroupPrimitive.Item value="xs">XS</ButtonRadioGroupPrimitive.Item>
+  <ButtonRadioGroupPrimitive.Item value="s">S</ButtonRadioGroupPrimitive.Item>
+  <ButtonRadioGroupPrimitive.Item value="m">M</ButtonRadioGroupPrimitive.Item>
+  <ButtonRadioGroupPrimitive.Item value="l" disabled>L</ButtonRadioGroupPrimitive.Item>
+  <ButtonRadioGroupPrimitive.Item value="xl" disabled>XL</ButtonRadioGroupPrimitive.Item>
+</ButtonRadioGroupPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <ButtonRadioGroupPrimitive.Root defaultValue="m">
       <ButtonRadioGroupPrimitive.Item value="xs">XS</ButtonRadioGroupPrimitive.Item>
@@ -151,38 +113,37 @@ export const DisabledItems: Story = {
   ),
 };
 
-// Fully disabled group
-export const Disabled: Story = {
-  args: {
-    options: sizeOptions,
-    defaultValue: 'm',
-    disabled: true,
-  },
-};
-
-// Controlled example
-export const Controlled: Story = {
-  render: () => {
-    const [value, setValue] = useState<string>('m');
-
-    return <ButtonRadioGroup onValueChange={setValue} options={sizeOptions} value={value} />;
-  },
-};
+export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the primitive components for full control over the structure.
 
-// With onOptionMouseEnter callback
-export const WithHoverCallback: Story = {
-  render: () => {
-    const [hoveredValue, setHoveredValue] = useState<string | null>(null);
+| Primitive                          | Description                     |
+|------------------------------------|---------------------------------|
+| \`ButtonRadioGroupPrimitive.Root\`    | Radio group container.          |
+| \`ButtonRadioGroupPrimitive.Item\`    | Individual button option.       |
+        `,
+      },
+      source: {
+        code: `
+import * as ButtonRadioGroupPrimitive from '@/components/button-radio-group/primitives';
 
-    return (
-      <div>
-        <ButtonRadioGroup
-          defaultValue="natural"
-          onOptionMouseEnter={setHoveredValue}
-          options={colorOptions}
-        />
-        <p className="mt-4 text-sm text-contrast-500">Hovered: {hoveredValue ?? 'None'}</p>
-      </div>
-    );
+<ButtonRadioGroupPrimitive.Root defaultValue="natural">
+  <ButtonRadioGroupPrimitive.Item value="natural">Natural</ButtonRadioGroupPrimitive.Item>
+  <ButtonRadioGroupPrimitive.Item value="charcoal">Charcoal</ButtonRadioGroupPrimitive.Item>
+  <ButtonRadioGroupPrimitive.Item value="sage">Sage</ButtonRadioGroupPrimitive.Item>
+</ButtonRadioGroupPrimitive.Root>
+        `,
+      },
+    },
   },
+  render: () => (
+    <ButtonRadioGroupPrimitive.Root defaultValue="natural">
+      <ButtonRadioGroupPrimitive.Item value="natural">Natural</ButtonRadioGroupPrimitive.Item>
+      <ButtonRadioGroupPrimitive.Item value="charcoal">Charcoal</ButtonRadioGroupPrimitive.Item>
+      <ButtonRadioGroupPrimitive.Item value="sage">Sage</ButtonRadioGroupPrimitive.Item>
+    </ButtonRadioGroupPrimitive.Root>
+  ),
 };
diff --git a/src/components/button/button.tsx b/src/components/button/button.tsx
index 1fdbac6..073ac2b 100644
--- a/src/components/button/button.tsx
+++ b/src/components/button/button.tsx
@@ -7,26 +7,27 @@ import * as ButtonPrimitive from '@/components/button';
 import { cn } from '@/lib';
 
 export const buttonVariants = cva(
-  'relative z-0 inline-flex h-fit select-none items-center justify-center overflow-hidden text-center font-semibold leading-normal transition-all duration-75 ease-linear [font-family:var(--button-font-family,var(--font-family-body))]',
+  'relative z-0 inline-flex h-fit select-none items-center justify-center overflow-hidden text-center transition-all duration-75 ease-linear [font-family:var(--button-font,var(--font-body))] focus-primary group disabled:pointer-events-none disabled:opacity-30 aria-busy:pointer-events-none',
   {
     variants: {
       variant: {
         primary:
-          'bg-[var(--button-brand-background,var(--foreground))] text-[var(--button-brand-text,var(--background))] hover:opacity-70',
+          'bg-[--button-fill-primary,var(--foreground)] text-[--button-text-primary,var(--text-inverse)] hover:opacity-70',
         brand:
-          'bg-[var(--button-brand-background,var(--brand))] text-[var(--button-brand-text,var(--foreground))] hover:opacity-70',
+          'bg-[--button-fill-brand,var(--brand)] text-[--button-text-brand,var(--text-primary)] hover:opacity-70',
         outline:
-          'border border-[var(--button-outline-border,var(--contrast-200))] bg-[var(--button-outline-background,var(--background))] text-[var(--button-outline-text,var(--foreground))] hover:bg-foreground/5',
+          'border border-[--button-stroke-outline,var(--border)] bg-[--button-fill-outline,var(--background)] text-[--button-text-outline,var(--text-primary)] hover:bg-[color-mix(in_oklch,var(--fill-hover,var(--contrast-100))_80%,transparent)]',
         ghost:
-          'bg-transparent text-[var(--button-ghost-text,var(--foreground))] hover:bg-foreground/5',
+          'bg-transparent text-[--button-text-ghost,var(--text-primary)] hover:bg-[color-mix(in_oklch,var(--fill-hover,var(--contrast-100))_80%,transparent)]',
         danger:
-          'bg-[var(--button-danger-background,var(--error))] text-[var(--button-danger-text,var(--background))] hover:opacity-70',
+          'bg-[--button-fill-danger,var(--error)] text-[--button-danger-text,var(--text-inverse)] hover:opacity-70',
       },
       size: {
-        'x-small': 'min-h-8 text-xs',
-        small: 'min-h-9 text-sm',
-        medium: 'min-h-11 text-base',
-        large: 'min-h-14 text-base',
+        '2x-small': 'min-h-5',
+        'x-small': 'min-h-8',
+        small: 'min-h-9',
+        medium: 'min-h-11',
+        large: 'min-h-14',
       },
       shape: {
         pill: 'rounded-full',
@@ -37,6 +38,7 @@ export const buttonVariants = cva(
     },
     compoundVariants: [
       // Rounded shape uses size-specific border radius
+      { shape: 'rounded', size: '2x-small', class: 'rounded-md' },
       { shape: 'rounded', size: 'x-small', class: 'rounded-lg' },
       { shape: 'rounded', size: 'small', class: 'rounded-lg' },
       { shape: 'rounded', size: 'medium', class: 'rounded-xl' },
@@ -51,10 +53,11 @@ export const buttonVariants = cva(
 );
 
 export const buttonContentVariants = cva(
-  'inline-flex items-center justify-center transition-all duration-300 ease-in-out',
+  'inline-flex font-semibold items-center justify-center transition-all duration-300 ease-in-out translate-y-0 opacity-100 group-aria-busy:-translate-y-full group-aria-busy:opacity-0',
   {
     variants: {
       size: {
+        '2x-small': 'min-h-5 gap-x-1.5 px-2 py-1 text-xs',
         'x-small': 'min-h-8 gap-x-2 px-3 py-1.5 text-xs',
         small: 'min-h-9 gap-x-2 px-3.5 py-2 text-sm',
         medium: 'min-h-11 gap-x-2.5 px-4 py-2.5 text-base',
@@ -89,29 +92,17 @@ export type ButtonProps = ComponentProps<'button'> &
  *
  * ```css
  * :root {
- *   --button-focus: var(--brand);
- *   --button-font-family: var(--font-family-body);
- *   --button-brand-background: var(--brand);
- *   --button-brand-background-hover: color-mix(in oklab, var(--brand), white 75%);
- *   --button-brand-text: var(--foreground);
- *   --button-brand-border: var(--brand);
- *   --button-brand-background: var(--foreground);
- *   --button-brand-background-hover: var(--background);
- *   --button-brand-text: var(--background);
- *   --button-brand-border: var(--foreground);
- *   --button-outline-background: var(--background);
- *   --button-outline-background-hover: var(--contrast-100);
- *   --button-outline-text: var(--foreground);
- *   --button-outline-border: var(--contrast-200);
- *   --button-ghost-background: transparent;
- *   --button-ghost-background-hover: color-mix(in oklab, var(--foreground) 5%, transparent);
- *   --button-ghost-text: var(--foreground);
- *   --button-ghost-border: transparent;
- *   --button-loader-icon: var(--foreground);
- *   --button-danger-background: color-mix(in oklab, var(--error), white 30%);
- *   --button-danger-background-hover: color-mix(in oklab, var(--error), white 75%);
- *   --button-danger-text: var(--foreground);
- *   --button-danger-border: color-mix(in oklab, var(--error), white 30%);
+ *   --button-font:          var(--font-body);
+ *   --button-fill-primary:  var(--foreground);
+ *   --button-text-primary:  var(--text-inverse);
+ *   --button-fill-brand:    var(--brand);
+ *   --button-text-brand:    var(--text-brand);
+ *   --button-fill-outline:  var(--background);
+ *   --button-text-outline:  var(--text-primary);
+ *   --button-stroke-outline: var(--border);
+ *   --button-text-ghost:    var(--text-primary);
+ *   --button-fill-danger:   var(--error);
+ *   --button-text-danger:   var(--text-inverse);
  * }
  * ```
  */
@@ -130,41 +121,15 @@ export function Button({
   return (
     <button
       aria-busy={loading}
-      className={cn(
-        buttonVariants({ variant, size, shape }),
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--button-focus,var(--brand))]',
-        // Disabled state
-        'disabled:pointer-events-none disabled:opacity-30',
-        // Loading state
-        loading && 'pointer-events-none',
-        className,
-      )}
+      className={cn(buttonVariants({ variant, size, shape }), className)}
       data-slot="button"
       disabled={disabled}
       type={type}
       {...props}
     >
-      <span
-        className={cn(
-          buttonContentVariants({ size, shape }),
-          loading ? '-translate-y-full opacity-0' : 'translate-y-0 opacity-100',
-        )}
-      >
-        {children}
-      </span>
-      <span
-        className={cn(
-          'absolute inset-0 grid place-content-center transition-all duration-300 ease-in-out',
-          loading ? 'translate-y-0 opacity-100' : 'translate-y-full opacity-0',
-        )}
-      >
-        <ButtonPrimitive.LoaderIcon
-          asChild={loaderIcon?.asChild}
-          className={cn(
-            variant === 'outline' && 'text-[var(--button-loader-icon,var(--foreground))]',
-          )}
-        >
+      <span className={cn(buttonContentVariants({ size, shape }))}>{children}</span>
+      <span className="absolute inset-0 grid translate-y-full place-content-center opacity-0 transition-all duration-300 ease-in-out group-aria-busy:translate-y-0 group-aria-busy:opacity-100">
+        <ButtonPrimitive.LoaderIcon asChild={loaderIcon?.asChild}>
           {loaderIcon?.children}
         </ButtonPrimitive.LoaderIcon>
       </span>
diff --git a/src/components/button/primitives/button-loader-icon.tsx b/src/components/button/primitives/button-loader-icon.tsx
index 931e17a..202ecca 100644
--- a/src/components/button/primitives/button-loader-icon.tsx
+++ b/src/components/button/primitives/button-loader-icon.tsx
@@ -11,13 +11,15 @@ export interface ButtonLoaderIconProps {
 }
 
 export function ButtonLoaderIcon({ asChild = false, className, children }: ButtonLoaderIconProps) {
+  const iconStyles = cn('animate-spin', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('animate-spin', className)} data-slot="button-loader-icon">
+      <Slot className={iconStyles} data-slot="button-loader-icon">
         {children}
       </Slot>
     );
   }
 
-  return <Loader2 className={cn('animate-spin', className)} data-slot="button-loader-icon" />;
+  return <Loader2 className={iconStyles} data-slot="button-loader-icon" />;
 }
diff --git a/src/components/button/storybook/button.stories.tsx b/src/components/button/storybook/button.stories.tsx
index 9031df7..9114e54 100644
--- a/src/components/button/storybook/button.stories.tsx
+++ b/src/components/button/storybook/button.stories.tsx
@@ -1,9 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { ArrowRight, LoaderCircle, X } from 'lucide-react';
+import { ArrowRight, X } from 'lucide-react';
 
 import { Button } from '@/components/button';
 
-const meta = {
+const meta: Meta<typeof Button> = {
   title: 'Components/Button',
   component: Button,
   parameters: {
@@ -17,46 +17,18 @@ A versatile button component with multiple variants, sizes, and shapes.
 
 \`\`\`css
 :root {
-  --button-focus: var(--brand);
-  --button-font-family: var(--font-family-body);
-  --button-brand-background: var(--brand);
-  --button-brand-text: var(--foreground);
-  --button-primary-background: var(--foreground);
-  --button-primary-text: var(--background);
-  --button-outline-background: var(--background);
-  --button-outline-text: var(--foreground);
-  --button-outline-border: var(--contrast-200);
-  --button-ghost-text: var(--foreground);
-  --button-danger-background: var(--error);
-  --button-danger-text: var(--background);
-  --button-loader-icon: var(--foreground);
+  --button-font: var(--font-body);
+  --button-fill-primary: var(--foreground);
+  --button-text-primary: var(--text-inverse);
+  --button-fill-brand: var(--brand);
+  --button-text-brand: var(--text-primary);
+  --button-fill-outline: var(--background);
+  --button-text-outline: var(--text-primary);
+  --button-stroke-outline: var(--border);
+  --button-text-ghost: var(--text-primary);
+  --button-fill-danger: var(--error);
+  --button-danger-text: var(--text-inverse);
 }
-\`\`\`
-
-## Custom Loader Icon
-
-The loading spinner can be customized using the \`loaderIcon\` prop with \`asChild\`:
-
-\`\`\`tsx
-<Button
-  loading
-  loaderIcon={{
-    asChild: true,
-    children: <LoaderCircle />,
-  }}
->
-  Loading...
-</Button>
-\`\`\`
-
-The \`LoaderIcon\` primitive is also available:
-
-\`\`\`tsx
-import * as ButtonPrimitive from '@/components/button';
-
-<ButtonPrimitive.LoaderIcon asChild>
-  <MyCustomSpinner />
-</ButtonPrimitive.LoaderIcon>
 \`\`\`
         `,
       },
@@ -81,11 +53,11 @@ import * as ButtonPrimitive from '@/components/button';
     },
     loading: {
       control: 'boolean',
-      description: 'Shows a loading spinner',
+      description: 'Shows a loading spinner and disables interaction',
     },
     loaderIcon: {
       control: false,
-      description: 'Custom loader icon with asChild support',
+      description: 'Custom loader icon configuration with `asChild` and `children` props',
     },
     disabled: {
       control: 'boolean',
@@ -95,151 +67,78 @@ import * as ButtonPrimitive from '@/components/button';
   args: {
     children: 'Button',
   },
-} satisfies Meta<typeof Button>;
+};
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-// Variant stories
-export const Primary: Story = {
+export const Default: Story = {
   args: {
     variant: 'primary',
-    children: 'Primary Button',
-  },
-};
-
-export const Brand: Story = {
-  args: {
-    variant: 'brand',
-    children: 'Brand Button',
-  },
-};
-
-export const Outline: Story = {
-  args: {
-    variant: 'outline',
-    children: 'Outline Button',
-  },
-};
-
-export const Ghost: Story = {
-  args: {
-    variant: 'ghost',
-    children: 'Ghost Button',
+    children: 'Add to Cart',
   },
 };
 
-export const Danger: Story = {
-  args: {
-    variant: 'danger',
-    children: 'Danger Button',
-  },
-};
-
-// Size stories
-export const Large: Story = {
-  args: {
-    size: 'large',
-    children: 'Large Button',
-  },
-};
-
-export const Medium: Story = {
-  args: {
-    size: 'medium',
-    children: 'Medium Button',
-  },
-};
-
-export const Small: Story = {
-  args: {
-    size: 'small',
-    children: 'Small Button',
-  },
-};
-
-export const ExtraSmall: Story = {
-  args: {
-    size: 'x-small',
-    children: 'Extra Small',
-  },
-};
-
-// Shape stories
-export const Pill: Story = {
-  args: {
-    shape: 'pill',
-    children: 'Pill Shape',
-  },
-};
-
-export const Rounded: Story = {
-  args: {
-    shape: 'rounded',
-    children: 'Rounded Shape',
-  },
-};
-
-export const Square: Story = {
-  args: {
-    shape: 'square',
-    children: 'Square Shape',
-  },
-};
-
-export const Circle: Story = {
-  args: {
-    shape: 'circle',
-    children: <X absoluteStrokeWidth size={20} strokeWidth={1.5} />,
-  },
-};
-
-// State stories
-export const Loading: Story = {
-  args: {
-    loading: true,
-    children: 'Loading Button',
-  },
-};
-
-export const CustomLoaderIcon: Story = {
-  args: {
-    loading: true,
-    loaderIcon: {
-      asChild: true,
-      children: <LoaderCircle />,
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-4">
+      <Button variant="primary">Primary</Button>
+      <Button variant="brand">Brand</Button>
+      <Button variant="outline">Outline</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="danger">Danger</Button>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The button supports five variants: `primary`, `brand`, `outline`, `ghost`, and `danger`.',
+      },
     },
-    children: 'Custom Loader',
   },
 };
 
-export const Disabled: Story = {
-  args: {
-    disabled: true,
-    children: 'Disabled Button',
-  },
-};
-
-// Combination examples
-export const DangerSmallPill: Story = {
-  args: {
-    variant: 'danger',
-    size: 'small',
-    shape: 'pill',
-    children: 'Delete',
+export const AllSizes: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-4">
+      <Button size="large">Large</Button>
+      <Button size="medium">Medium</Button>
+      <Button size="small">Small</Button>
+      <Button size="x-small">X-Small</Button>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Four size options are available: `large` (default), `medium`, `small`, and `x-small`.',
+      },
+    },
   },
 };
 
-export const PrimaryMediumRounded: Story = {
-  args: {
-    variant: 'primary',
-    size: 'medium',
-    shape: 'rounded',
-    children: 'Cancel',
+export const AllShapes: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-4">
+      <Button shape="pill">Pill</Button>
+      <Button shape="rounded">Rounded</Button>
+      <Button shape="square">Square</Button>
+      <Button shape="circle">
+        <X absoluteStrokeWidth size={20} strokeWidth={1.5} />
+      </Button>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Shape options include `pill` (default), `rounded`, `square`, and `circle` (for icon-only buttons).',
+      },
+    },
   },
 };
 
-// With icon examples
 export const WithIcon: Story = {
   args: {
     variant: 'primary',
@@ -250,39 +149,33 @@ export const WithIcon: Story = {
       </>
     ),
   },
-};
-
-export const IconOnly: Story = {
-  args: {
-    variant: 'primary',
-    shape: 'circle',
-    size: 'medium',
-    children: <ArrowRight size={20} />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Icons can be added as children alongside text.',
+      },
+    },
   },
 };
 
-// Use case examples
-export const CallToAction: Story = {
+export const Loading: Story = {
   args: {
-    variant: 'primary',
-    size: 'large',
-    children: (
-      <>
-        Get Started <ArrowRight size={20} />
-      </>
-    ),
+    loading: true,
+    children: 'Processing...',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The `loading` prop shows a spinner and disables interaction. Use the `loaderIcon` prop to customize the spinner.',
+      },
+    },
   },
 };
 
-export const DangerWithIcon: Story = {
+export const Disabled: Story = {
   args: {
-    variant: 'danger',
-    size: 'medium',
-    children: (
-      <>
-        <X size={20} />
-        Delete Item
-      </>
-    ),
+    disabled: true,
+    children: 'Disabled',
   },
 };
diff --git a/src/components/calendar/calendar.tsx b/src/components/calendar/calendar.tsx
index 9b0589a..5bb1577 100644
--- a/src/components/calendar/calendar.tsx
+++ b/src/components/calendar/calendar.tsx
@@ -13,13 +13,11 @@ import { cn } from '@/lib';
  *
  * ```css
  * :root {
- *   --calendar-font-family: var(--font-family-body);
- *   --calendar-focus: var(--brand);
- *   --calendar-text: var(--foreground);
- *   --calendar-background: var(--background);
- *   --calendar-selected-background: var(--brand);
- *   --calendar-selected-text: var(--foreground);
- *   --calendar-text-disabled: var(--contrast-300);
+ *   --calendar-font: var(--font-body);
+ *   --calendar-fill: var(--background);
+ *   --calendar-text-primary:  var(--text-primary);
+ *   --calendar-fill-selected: var(--brand);
+ *   --calendar-text-selected: var(--text-primary);
  * }
  * ```
  */
@@ -60,7 +58,7 @@ export function Calendar({
     <DayPicker
       captionLayout={captionLayout}
       className={cn(
-        'group/calendar rounded-2xl bg-[var(--calendar-background,var(--background))] p-3 font-[var(--calendar-font-family,var(--font-family-body))] text-[var(--calendar-text,var(--foreground))] shadow-lg shadow-black/10 ring-1 ring-black/5',
+        'group/calendar rounded-2xl bg-[--calendar-fill,var(--background)] p-3 font-[--calendar-font,var(--font-body)] text-[--calendar-text-primary,var(--text-primary)] shadow-lg shadow-black/10 ring-1 ring-black/5',
         className,
       )}
       classNames={{
@@ -72,27 +70,27 @@ export function Calendar({
           defaultClassNames.nav,
         ),
         button_previous: cn(
-          'inline-flex size-[var(--cell-size)] cursor-default items-center justify-center rounded-full transition-colors duration-75 ease-linear hover:bg-contrast-100 focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--calendar-focus,var(--brand))] aria-disabled:cursor-not-allowed aria-disabled:opacity-50',
+          'focus-primary inline-flex size-[--cell-size] cursor-default items-center justify-center rounded-full text-[--calendar-text-primary,var(--text-primary)] transition-colors duration-75 ease-linear hover:bg-[--fill-hover] aria-disabled:cursor-not-allowed aria-disabled:opacity-50',
           defaultClassNames.button_previous,
         ),
         button_next: cn(
-          'inline-flex size-[var(--cell-size)] cursor-default items-center justify-center rounded-full transition-colors duration-75 ease-linear hover:bg-contrast-100 focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--calendar-focus,var(--brand))] aria-disabled:cursor-not-allowed aria-disabled:opacity-25',
+          'focus-primary inline-flex size-[--cell-size] cursor-default items-center justify-center rounded-full text-[--calendar-text-primary,var(--text-primary)] transition-colors duration-75 ease-linear hover:bg-[--fill-hover] aria-disabled:cursor-not-allowed aria-disabled:opacity-25',
           defaultClassNames.button_next,
         ),
         month_caption: cn(
-          'flex h-[var(--cell-size)] w-full items-center justify-center px-[var(--cell-size)]',
+          'flex h-[--cell-size] w-full items-center justify-center px-[--cell-size]',
           defaultClassNames.month_caption,
         ),
         dropdowns: cn(
-          'flex h-[var(--cell-size)] w-full items-center justify-center gap-1.5 text-sm font-medium',
+          'flex h-[--cell-size] w-full items-center justify-center gap-1.5 text-sm font-medium',
           defaultClassNames.dropdowns,
         ),
         dropdown_root: cn(
-          'relative rounded-lg border border-contrast-200 transition-colors duration-75 ease-linear',
+          'relative rounded-lg border border-[--border] transition-colors duration-75 ease-linear',
           // Hover state
-          'hover:bg-foreground/5',
+          'hover:bg-[--fill-hover]',
           // Focus-visible state
-          'focus-visible:border-foreground',
+          'focus-visible:border-[--border-focus-secondary]',
           defaultClassNames.dropdown_root,
         ),
         dropdown: cn('absolute inset-0 opacity-0', defaultClassNames.dropdown),
@@ -103,29 +101,29 @@ export function Calendar({
         table: 'w-full border-collapse',
         weekdays: cn('flex', defaultClassNames.weekdays),
         weekday: cn(
-          'inline-flex size-[var(--cell-size)] flex-1 select-none items-center justify-center text-xs font-semibold',
+          'inline-flex size-[--cell-size] flex-1 select-none items-center justify-center text-xs font-semibold',
           defaultClassNames.weekday,
         ),
         week: cn('mt-1 flex w-full', defaultClassNames.week),
         week_number_header: cn(
-          'size-[var(--cell-size)] select-none',
+          'size-[--cell-size] select-none',
           defaultClassNames.week_number_header,
         ),
         week_number: cn('select-none text-xs', defaultClassNames.week_number),
         day: cn(
-          'group/day relative z-0 size-[var(--cell-size)] select-none p-0 text-center [&:last-child[data-selected=true]_button]:rounded-r-full',
+          'group/day relative z-0 size-[--cell-size] select-none p-0 text-center [&:last-child[data-selected=true]_button]:rounded-r-full',
           props.showWeekNumber === true
             ? '[&:nth-child(2)[data-selected=true]_button]:rounded-l-full'
             : '[&:first-child[data-selected=true]_button]:rounded-l-full',
           defaultClassNames.day,
         ),
         range_start: cn(
-          'rounded-l-full bg-[var(--calendar-selected-background,color-mix(in_oklch,var(--brand)_25%,transparent))]',
+          'rounded-l-full bg-[color-mix(in_oklch,var(--calendar-fill-selected,var(--brand))_25%,transparent)]',
           defaultClassNames.range_start,
         ),
         range_middle: cn('rounded-none', defaultClassNames.range_middle),
         range_end: cn(
-          'rounded-r-full bg-[var(--calendar-selected-background,color-mix(in_oklch,var(--brand)_25%,transparent))]',
+          'rounded-r-full bg-[color-mix(in_oklch,var(--calendar-fill-selected,var(--brand))_25%,transparent)]',
           defaultClassNames.range_end,
         ),
         today: cn(
@@ -184,7 +182,7 @@ export function Calendar({
         WeekNumber: ({ children, ...weekNumberProps }) => {
           return (
             <td {...weekNumberProps}>
-              <div className="flex size-[var(--cell-size)] items-center justify-center text-center">
+              <div className="flex size-[--cell-size] items-center justify-center text-center">
                 {children}
               </div>
             </td>
@@ -222,21 +220,21 @@ function CalendarDayButton({
   return (
     <button
       className={cn(
-        'size-[var(--cell-size)] rounded-full p-0 text-xs font-normal transition-colors duration-75 ease-linear',
+        'size-[--cell-size] rounded-full p-0 text-xs font-normal transition-colors duration-75 ease-linear',
         // Hover state
-        'hover:bg-contrast-100',
+        'hover:bg-[--fill-hover]',
         // Range end
         'data-[range-end=true]:rounded-full',
-        'data-[range-end=true]:bg-[var(--calendar-selected-button-background,var(--brand))]',
-        'data-[range-end=true]:text-[var(--calendar-selected-text,var(--foreground))]',
+        'data-[range-end=true]:bg-[--calendar-fill-selected,var(--brand)]',
+        'data-[range-end=true]:text-[--calendar-text-selected,var(--text-primary)]',
         // Range middle
         'data-[range-middle=true]:rounded-none',
-        'data-[range-middle=true]:bg-[var(--calendar-selected-background,color-mix(in_oklch,var(--brand)_25%,transparent))]',
+        'data-[range-middle=true]:bg-[color-mix(in_oklch,var(--calendar-fill-selected,var(--brand))_25%,transparent)]',
         'data-[range-middle=true]:before:content-[""]',
         'data-[range-middle=true]:before:absolute',
         'data-[range-middle=true]:before:-z-10',
         'data-[range-middle=true]:before:inset-0',
-        'data-[range-middle=true]:before:bg-[var(--calendar-selected-background,var(--brand))]',
+        'data-[range-middle=true]:before:bg-[--calendar-fill-selected,var(--brand)]',
         'data-[range-middle=true]:before:rounded-full',
         'data-[range-middle=true]:before:opacity-0',
         'data-[range-middle=true]:before:transition-opacity',
@@ -245,23 +243,23 @@ function CalendarDayButton({
         'data-[range-middle=true]:hover:before:opacity-100',
         // Range start
         'data-[range-start=true]:rounded-full',
-        'data-[range-start=true]:bg-[var(--calendar-selected-background,var(--brand))]',
-        'data-[range-start=true]:text-[var(--calendar-selected-text,var(--foreground))]',
+        'data-[range-start=true]:bg-[--calendar-fill-selected,var(--brand)]',
+        'data-[range-start=true]:text-[--calendar-text-selected,var(--text-primary)]',
         // Selected single
-        'data-[selected-single=true]:bg-[var(--calendar-selected-background,var(--brand))]',
-        'data-[selected-single=true]:text-[var(--calendar-selected-text,var(--foreground))]',
+        'data-[selected-single=true]:bg-[--calendar-fill-selected,var(--brand)]',
+        'data-[selected-single=true]:text-[--calendar-text-selected,var(--text-primary)]',
         // Focused day (group)
         'group-data-[focused=true]/day:relative',
         'group-data-[focused=true]/day:z-10',
         'group-data-[focused=true]/day:outline-2',
         'group-data-[focused=true]/day:outline-offset-2',
-        'group-data-[focused=true]/day:outline-foreground',
+        'group-data-[focused=true]/day:outline-[--border-focus-primary]',
         // Outside day (group)
-        'group-data-[outside=true]/day:text-[var(--calendar-text,color-mix(in_oklch,var(--foreground)_40%,transparent))]',
-        'group-data-[outside=true]/day:hover:text-[var(--calendar-text,var(--foreground))]',
+        'group-data-[outside=true]/day:text-[color-mix(in_oklch,var(--calendar-text-primary,var(--text-primary))_40%,transparent))]',
+        'group-data-[outside=true]/day:hover:text-[--calendar-text-primary,var(--foreground)]',
         // Selected day (group)
-        'group-data-[selected=true]/day:text-foreground',
-        'group-data-[selected=true]/day:hover:text-foreground',
+        'group-data-[selected=true]/day:text-[--calendar-text-selected,var(--text-primary)]',
+        'group-data-[selected=true]/day:hover:text-[--calendar-text-selected,var(--text-primary)]',
         // Disabled day (group)
         'group-data-[disabled=true]/day:opacity-40',
         'group-data-[disabled=true]/day:pointer-events-none',
diff --git a/src/components/calendar/primitives/calendar-dropdown-icon.tsx b/src/components/calendar/primitives/calendar-dropdown-icon.tsx
index 7715b41..ee43970 100644
--- a/src/components/calendar/primitives/calendar-dropdown-icon.tsx
+++ b/src/components/calendar/primitives/calendar-dropdown-icon.tsx
@@ -15,19 +15,15 @@ export function CalendarDropdownIcon({
   className,
   children,
 }: CalendarDropdownIconProps) {
+  const iconStyles = cn('size-3.5', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-3.5', className)} data-slot="calendar-dropdown-icon">
+      <Slot className={iconStyles} data-slot="calendar-dropdown-icon">
         {children}
       </Slot>
     );
   }
 
-  return (
-    <ChevronDownIcon
-      absoluteStrokeWidth
-      className={cn('size-3.5', className)}
-      data-slot="calendar-dropdown-icon"
-    />
-  );
+  return <ChevronDownIcon absoluteStrokeWidth className={iconStyles} />;
 }
diff --git a/src/components/calendar/primitives/calendar-next-icon.tsx b/src/components/calendar/primitives/calendar-next-icon.tsx
index 4066430..4f98df4 100644
--- a/src/components/calendar/primitives/calendar-next-icon.tsx
+++ b/src/components/calendar/primitives/calendar-next-icon.tsx
@@ -11,19 +11,17 @@ export interface CalendarNextIconProps {
 }
 
 export function CalendarNextIcon({ asChild = false, className, children }: CalendarNextIconProps) {
+  const iconStyles = cn('size-5 translate-x-px', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-5 translate-x-px', className)} data-slot="calendar-next-icon">
+      <Slot className={iconStyles} data-slot="calendar-next-icon">
         {children}
       </Slot>
     );
   }
 
   return (
-    <ChevronRightIcon
-      absoluteStrokeWidth
-      className={cn('size-5 translate-x-px', className)}
-      data-slot="calendar-next-icon"
-    />
+    <ChevronRightIcon absoluteStrokeWidth className={iconStyles} data-slot="calendar-next-icon" />
   );
 }
diff --git a/src/components/calendar/primitives/calendar-prev-icon.tsx b/src/components/calendar/primitives/calendar-prev-icon.tsx
index b7c7e5a..e293868 100644
--- a/src/components/calendar/primitives/calendar-prev-icon.tsx
+++ b/src/components/calendar/primitives/calendar-prev-icon.tsx
@@ -11,19 +11,17 @@ export interface CalendarPrevIconProps {
 }
 
 export function CalendarPrevIcon({ asChild = false, className, children }: CalendarPrevIconProps) {
+  const iconStyles = cn('size-5 -translate-x-px', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-5 -translate-x-px', className)} data-slot="calendar-prev-icon">
+      <Slot className={iconStyles} data-slot="calendar-prev-icon">
         {children}
       </Slot>
     );
   }
 
   return (
-    <ChevronLeftIcon
-      absoluteStrokeWidth
-      className={cn('size-5 -translate-x-px', className)}
-      data-slot="calendar-prev-icon"
-    />
+    <ChevronLeftIcon absoluteStrokeWidth className={iconStyles} data-slot="calendar-prev-icon" />
   );
 }
diff --git a/src/components/calendar/storybook/calendar.stories.tsx b/src/components/calendar/storybook/calendar.stories.tsx
index f5a6111..9b83e3d 100644
--- a/src/components/calendar/storybook/calendar.stories.tsx
+++ b/src/components/calendar/storybook/calendar.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { ArrowLeftIcon, ArrowRightIcon, ChevronsUpDownIcon } from 'lucide-react';
 import * as React from 'react';
 import type { DateRange } from 'react-day-picker';
 
@@ -29,56 +28,18 @@ const meta: Meta<typeof Calendar> = {
     docs: {
       description: {
         component: `
-The Calendar component provides a date picker built on top of [react-day-picker](https://react-day-picker.js.org/). It supports single date selection, date ranges, and multiple date selection.
+A date picker component built on [react-day-picker](https://react-day-picker.js.org/). Supports single date, date range, and multiple date selection.
 
 ## CSS Variables
 
-The following CSS variables can be used to customize the Calendar component:
-
 \`\`\`css
 :root {
-  --calendar-font-family: var(--font-family-body);
-  --calendar-focus: var(--brand);
-  --calendar-text: var(--foreground);
-  --calendar-background: var(--background);
-  --calendar-selected-background: var(--brand);
-  --calendar-selected-text: var(--foreground);
-  --calendar-text-disabled: var(--contrast-300);
+  --calendar-font: var(--font-body);
+  --calendar-fill: var(--background);
+  --calendar-text-primary: var(--text-primary);
+  --calendar-fill-selected: var(--brand);
+  --calendar-text-selected: var(--text-primary);
 }
-\`\`\`
-
-## Selection Modes
-
-The component supports three selection modes:
-- \`single\` (default) - Select a single date
-- \`range\` - Select a date range with start and end dates
-- \`multiple\` - Select multiple individual dates
-
-## Caption Layouts
-
-The \`captionLayout\` prop controls how month/year navigation is displayed:
-- \`label\` (default) - Shows month and year as text
-- \`dropdown\` - Shows dropdowns for month and year selection
-- \`dropdown-months\` - Shows dropdown for month only
-- \`dropdown-years\` - Shows dropdown for year only
-
-## Custom Icons
-
-The Calendar component exposes icon primitives that can be customized using the \`asChild\` pattern:
-- \`prevIcon\` - Previous month navigation icon
-- \`nextIcon\` - Next month navigation icon
-- \`dropdownIcon\` - Dropdown chevron icon (when using dropdown caption layout)
-
-## Icon Primitives
-
-The following icon primitives are available for composable usage:
-
-\`\`\`tsx
-import * as CalendarPrimitive from '@/components/calendar';
-
-<CalendarPrimitive.PrevIcon />
-<CalendarPrimitive.NextIcon />
-<CalendarPrimitive.DropdownIcon />
 \`\`\`
         `,
       },
@@ -89,12 +50,12 @@ import * as CalendarPrimitive from '@/components/calendar';
     mode: {
       control: 'select',
       options: ['single', 'range', 'multiple'],
-      description: 'The selection mode for the calendar',
+      description: 'Selection mode: `single`, `range`, or `multiple`',
     },
     captionLayout: {
       control: 'select',
       options: ['label', 'dropdown', 'dropdown-months', 'dropdown-years'],
-      description: 'Layout of the month/year caption',
+      description: 'Caption layout for month/year navigation',
     },
     showOutsideDays: {
       control: 'boolean',
@@ -109,13 +70,16 @@ import * as CalendarPrimitive from '@/components/calendar';
       description: 'Number of months to display',
     },
     prevIcon: {
-      description: 'Custom previous navigation icon with asChild support',
+      control: false,
+      description: 'Custom previous navigation icon with `asChild` support',
     },
     nextIcon: {
-      description: 'Custom next navigation icon with asChild support',
+      control: false,
+      description: 'Custom next navigation icon with `asChild` support',
     },
     dropdownIcon: {
-      description: 'Custom dropdown chevron icon with asChild support',
+      control: false,
+      description: 'Custom dropdown chevron icon with `asChild` support',
     },
   },
 };
@@ -123,9 +87,6 @@ import * as CalendarPrimitive from '@/components/calendar';
 export default meta;
 type Story = StoryObj<typeof Calendar>;
 
-/**
- * The default Calendar displays a single month with single date selection.
- */
 export const Default: Story = {
   render: () => {
     const [selected, setSelected] = React.useState<Date | undefined>(new Date());
@@ -134,9 +95,6 @@ export const Default: Story = {
   },
 };
 
-/**
- * Range selection allows users to select a start and end date.
- */
 export const RangeSelection: Story = {
   render: () => {
     const [range, setRange] = React.useState<DateRange | undefined>({
@@ -146,26 +104,15 @@ export const RangeSelection: Story = {
 
     return <Calendar mode="range" onSelect={setRange} selected={range} />;
   },
-};
-
-/**
- * Multiple selection allows users to select multiple individual dates.
- */
-export const MultipleSelection: Story = {
-  render: () => {
-    const [selected, setSelected] = React.useState<Date[] | undefined>([
-      new Date(),
-      addDays(new Date(), 2),
-      addDays(new Date(), 5),
-    ]);
-
-    return <Calendar mode="multiple" onSelect={setSelected} selected={selected} />;
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `mode="range"` to allow selection of a start and end date.',
+      },
+    },
   },
 };
 
-/**
- * Display dropdown selectors for quick month and year navigation.
- */
 export const WithDropdowns: Story = {
   render: () => {
     const [selected, setSelected] = React.useState<Date | undefined>(new Date());
@@ -181,11 +128,16 @@ export const WithDropdowns: Story = {
       />
     );
   },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use `captionLayout="dropdown"` for quick month/year navigation. Set `startMonth` and `endMonth` to define the selectable range.',
+      },
+    },
+  },
 };
 
-/**
- * Display multiple months side by side for easier range selection.
- */
 export const MultipleMonths: Story = {
   render: () => {
     const [range, setRange] = React.useState<DateRange | undefined>({
@@ -195,97 +147,11 @@ export const MultipleMonths: Story = {
 
     return <Calendar mode="range" numberOfMonths={2} onSelect={setRange} selected={range} />;
   },
-};
-
-/**
- * Show week numbers alongside the calendar days.
- */
-export const WithWeekNumbers: Story = {
-  render: () => {
-    const [selected, setSelected] = React.useState<Date | undefined>(new Date());
-
-    return <Calendar mode="single" onSelect={setSelected} selected={selected} showWeekNumber />;
-  },
-};
-
-/**
- * Disable specific dates to prevent selection.
- */
-export const DisabledDates: Story = {
-  render: () => {
-    const [selected, setSelected] = React.useState<Date | undefined>();
-
-    // Disable weekends and dates in the past
-    const disabledDays = [
-      { before: new Date() },
-      { dayOfWeek: [0, 6] }, // Sunday and Saturday
-    ];
-
-    return (
-      <Calendar disabled={disabledDays} mode="single" onSelect={setSelected} selected={selected} />
-    );
-  },
-};
-
-/**
- * Hide days from adjacent months for a cleaner look.
- */
-export const HideOutsideDays: Story = {
-  render: () => {
-    const [selected, setSelected] = React.useState<Date | undefined>(new Date());
-
-    return (
-      <Calendar mode="single" onSelect={setSelected} selected={selected} showOutsideDays={false} />
-    );
-  },
-};
-
-/**
- * Use custom icons for navigation by leveraging the `asChild` pattern.
- * This allows you to substitute your own icon components.
- */
-export const CustomIcons: Story = {
-  render: () => {
-    const [selected, setSelected] = React.useState<Date | undefined>(new Date());
-
-    return (
-      <Calendar
-        mode="single"
-        nextIcon={{
-          asChild: true,
-          children: <ArrowRightIcon absoluteStrokeWidth strokeWidth={1.5} />,
-        }}
-        onSelect={setSelected}
-        prevIcon={{
-          asChild: true,
-          children: <ArrowLeftIcon absoluteStrokeWidth strokeWidth={1.5} />,
-        }}
-        selected={selected}
-      />
-    );
-  },
-};
-
-/**
- * Customize the dropdown icon when using dropdown caption layouts.
- */
-export const CustomDropdownIcon: Story = {
-  render: () => {
-    const [selected, setSelected] = React.useState<Date | undefined>(new Date());
-
-    return (
-      <Calendar
-        captionLayout="dropdown"
-        dropdownIcon={{
-          asChild: true,
-          children: <ChevronsUpDownIcon absoluteStrokeWidth strokeWidth={1.5} />,
-        }}
-        endMonth={addMonths(new Date(), 12)}
-        mode="single"
-        onSelect={setSelected}
-        selected={selected}
-        startMonth={addMonths(new Date(), -12)}
-      />
-    );
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `numberOfMonths` to display multiple months side by side.',
+      },
+    },
   },
 };
diff --git a/src/components/card-radio-group/card-radio-group.tsx b/src/components/card-radio-group/card-radio-group.tsx
index b9d2b52..f57b648 100644
--- a/src/components/card-radio-group/card-radio-group.tsx
+++ b/src/components/card-radio-group/card-radio-group.tsx
@@ -25,17 +25,14 @@ export type CardRadioGroupProps = ComponentProps<typeof RadioGroupPrimitive.Root
  * with their default values:
  *
  * ```css
- *  :root {
- *   --card-radio-group-focus: var(--brand);
- *   --card-radio-group-light-unchecked-border: var(--contrast-100);
- *   --card-radio-group-light-unchecked-border-hover: var(--contrast-200);
- *   --card-radio-group-light-unchecked-background: var(--background);
- *   --card-radio-group-light-unchecked-text: var(--foreground);
- *   --card-radio-group-light-unchecked-background-hover: var(--contrast-100);
- *   --card-radio-group-light-checked-background: var(--foreground);
- *   --card-radio-group-light-checked-text: var(--background);
- *   --card-radio-group-light-border-error: var(--error);
- *  }
+ * :root {
+ *   --card-radio-group-font: var(--font-body);
+ *   --card-radio-group-fill-unchecked: var(--form-fill-unchecked);
+ *   --card-radio-group-fill-checked: var(--form-fill-checked);
+ *   --card-radio-group-fill-hover: var(--form-fill-hover);
+ *   --card-radio-group-text-unchecked: var(--form-text-unchecked);
+ *   --card-radio-group-text-checked: var(--form-text-checked);
+ * }
  * ```
  */
 export function CardRadioGroup({
diff --git a/src/components/card-radio-group/primitives/card-radio-group-item.tsx b/src/components/card-radio-group/primitives/card-radio-group-item.tsx
index 285269b..297c8c6 100644
--- a/src/components/card-radio-group/primitives/card-radio-group-item.tsx
+++ b/src/components/card-radio-group/primitives/card-radio-group-item.tsx
@@ -9,17 +9,15 @@ export function CardRadioGroupItem({ children, className, ...props }: CardRadioG
   return (
     <RadioGroupPrimitive.Item
       className={cn(
-        'relative flex h-12 w-full items-center overflow-hidden rounded-lg border border-[var(--card-radio-group-unchecked-border,var(--contrast-100))] font-body text-sm font-normal leading-normal text-[var(--card-radio-group-unchecked-text,var(--foreground))] transition-colors',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--card-radio-group-focus,var(--brand))]',
+        'focus-primary relative flex h-12 w-full items-center overflow-hidden rounded-lg border border-[--border-subtle] text-sm text-[--card-radio-group-text-unchecked,var(--form-text-unchecked)] transition-colors [font-family:var(--card-radio-group-font,var(--font-body))]',
         // Checked state
-        'data-[state=checked]:border-[var(--card-radio-group-checked-background,var(--foreground))] data-[state=checked]:bg-[var(--card-radio-group-checked-background,var(--foreground))] data-[state=checked]:text-[var(--card-radio-group-checked-text,var(--background))]',
+        'data-[state=checked]:border-[--border-checked] data-[state=checked]:bg-[--card-radio-group-fill-checked,var(--form-fill-checked)] data-[state=checked]:text-[--card-radio-group-text-checked,var(--form-text-checked)]',
         // Unchecked state
-        'data-[state=unchecked]:bg-[var(--card-radio-group-unchecked-background,var(--background))]',
+        'data-[state=unchecked]:bg-[--card-radio-group-fill-unchecked,var(--form-fill-unchecked)]',
         // Unchecked hover state
-        'data-[state=unchecked]:hover:border-[var(--card-radio-group-unchecked-border-hover,var(--contrast-200))] data-[state=unchecked]:hover:bg-[var(--card-radio-group-unchecked-background-hover,var(--contrast-100))]',
+        'data-[state=unchecked]:hover:border-[--border] data-[state=unchecked]:hover:bg-[--card-radio-group-fill-hover,var(--form-fill-hover)]',
         // Aria-invalid state
-        'aria-invalid:border-[var(--card-radio-group-border-error,var(--error))]',
+        'aria-invalid:border-[--error]',
         // Disabled state
         'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
         className,
diff --git a/src/components/card-radio-group/storybook/card-radio-group.stories.tsx b/src/components/card-radio-group/storybook/card-radio-group.stories.tsx
index ebc447a..1949bb9 100644
--- a/src/components/card-radio-group/storybook/card-radio-group.stories.tsx
+++ b/src/components/card-radio-group/storybook/card-radio-group.stories.tsx
@@ -1,22 +1,11 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import type { ComponentType, ReactNode } from 'react';
-import { useState } from 'react';
 
-import { CardRadioGroup } from '@/components/card-radio-group/card-radio-group';
+import {
+  CardRadioGroup,
+  type CardRadioGroupProps,
+} from '@/components/card-radio-group/card-radio-group';
 import * as CardRadioGroupPrimitive from '@/components/card-radio-group/primitives';
 
-// Wrapper component for stories to avoid complex Radix union type issues
-interface CardRadioGroupStoryProps {
-  disabled?: boolean;
-  orientation?: 'horizontal' | 'vertical';
-  loop?: boolean;
-  children?: ReactNode;
-}
-
-function CardRadioGroupStory({ children, ...props }: CardRadioGroupStoryProps) {
-  return <CardRadioGroupPrimitive.Root {...props}>{children}</CardRadioGroupPrimitive.Root>;
-}
-
 const productOptions = [
   {
     id: 'product-scrub-brush',
@@ -45,15 +34,6 @@ const productOptions = [
       alt: 'Linen hand towel',
     },
   },
-  {
-    id: 'product-spray-bottle',
-    value: 'spray-bottle',
-    label: 'Amber Glass Spray Bottle',
-    image: {
-      src: 'https://images.unsplash.com/photo-1638609927127-aeb9e74c3cfd?w=96&h=96&fit=crop',
-      alt: 'Amber glass spray bottle',
-    },
-  },
 ];
 
 const shippingOptions = [
@@ -62,89 +42,27 @@ const shippingOptions = [
   { id: 'shipping-overnight', value: 'overnight', label: 'Overnight Delivery' },
 ];
 
-const paymentOptions = [
-  { id: 'payment-credit-card', value: 'credit-card', label: 'Credit Card' },
-  { id: 'payment-paypal', value: 'paypal', label: 'PayPal' },
-  { id: 'payment-apple-pay', value: 'apple-pay', label: 'Apple Pay' },
-  { id: 'payment-google-pay', value: 'google-pay', label: 'Google Pay' },
-];
-
-const meta: Meta<typeof CardRadioGroupStory> = {
+const meta: Meta<typeof CardRadioGroup> = {
   title: 'Components/CardRadioGroup',
-  component: CardRadioGroupStory,
+  component: CardRadioGroup,
   parameters: {
     layout: 'centered',
     docs: {
       description: {
         component: `
-A radio group component styled as a set of selectable cards. Perfect for product variant selection with visual swatches, shipping options, or payment methods. Built on Radix UI Radio Group primitives.
+A radio group component styled as a set of selectable cards. Perfect for product variant selection, shipping options, or payment methods. Built on Radix UI Radio Group primitives.
 
 ## CSS Variables
 
-The CardRadioGroup component supports extensive theming through CSS variables:
-
 \`\`\`css
 :root {
-  --card-radio-group-focus: var(--brand);
-  --card-radio-group-light-unchecked-border: var(--contrast-100);
-  --card-radio-group-light-unchecked-border-hover: var(--contrast-200);
-  --card-radio-group-light-unchecked-background: var(--background);
-  --card-radio-group-light-unchecked-text: var(--foreground);
-  --card-radio-group-light-unchecked-background-hover: var(--contrast-100);
-  --card-radio-group-light-checked-background: var(--foreground);
-  --card-radio-group-light-checked-text: var(--background);
-  --card-radio-group-light-border-error: var(--error);
+  --card-radio-group-font: var(--font-body);
+  --card-radio-group-fill-unchecked: var(--form-fill-unchecked);
+  --card-radio-group-fill-checked: var(--form-fill-checked);
+  --card-radio-group-fill-hover: var(--form-fill-hover);
+  --card-radio-group-text-unchecked: var(--form-text-unchecked);
+  --card-radio-group-text-checked: var(--form-text-checked);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`CardRadioGroup\` component provides a simple API with an \`options\` array:
-
-\`\`\`tsx
-import { CardRadioGroup } from '@/components/card-radio-group';
-
-const productOptions = [
-  { 
-    id: 'backpack',
-    value: 'backpack', 
-    label: 'Hiking Backpack',
-    image: { src: '/products/backpack.jpg', alt: 'Hiking backpack' }
-  },
-  { 
-    id: 'tent',
-    value: 'tent', 
-    label: 'Camping Tent',
-    image: { src: '/products/tent.jpg', alt: 'Camping tent' }
-  },
-];
-
-<CardRadioGroup
-  options={productOptions}
-  defaultValue="backpack"
-/>
-\`\`\`
-
-### Primitives
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as CardRadioGroup from '@/components/card-radio-group';
-
-<CardRadioGroup.Root defaultValue="standard">
-  <CardRadioGroup.Item value="standard">
-    <CardRadioGroup.Label>Standard Shipping</CardRadioGroup.Label>
-  </CardRadioGroup.Item>
-  <CardRadioGroup.Item value="express">
-    <CardRadioGroup.Thumbnail>
-      <CardRadioGroup.Image src="/icons/express.png" alt="Express" />
-    </CardRadioGroup.Thumbnail>
-    <CardRadioGroup.Label>Express Shipping</CardRadioGroup.Label>
-  </CardRadioGroup.Item>
-</CardRadioGroup.Root>
 \`\`\`
         `,
       },
@@ -152,499 +70,187 @@ import * as CardRadioGroup from '@/components/card-radio-group';
   },
   tags: ['autodocs'],
   argTypes: {
+    options: {
+      control: false,
+      description:
+        'Array of options with `value`, `label`, `id`, optional `image`, and optional `disabled`',
+    },
+    defaultValue: {
+      control: 'text',
+      description: 'The value of the option to select by default',
+    },
     disabled: {
       control: 'boolean',
       description: 'Whether the entire radio group is disabled',
     },
-    orientation: {
-      control: 'select',
-      options: ['horizontal', 'vertical'],
-      description: 'The orientation of the radio group',
-    },
-    loop: {
-      control: 'boolean',
-      description: 'Whether keyboard navigation should loop from last to first and vice versa',
+    onOptionMouseEnter: {
+      control: false,
+      description: 'Callback fired when hovering over an option',
     },
   },
-  decorators: [
-    (Story: ComponentType) => (
-      <div className="flex w-80 items-center justify-center p-8">
-        <Story />
-      </div>
-    ),
-  ],
+  decorators: [(Story) => <div className="w-80">{Story()}</div>],
 };
 
 export default meta;
-
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<CardRadioGroupProps>;
 
 export const Default: Story = {
-  args: {},
-  render: () => (
-    <CardRadioGroupPrimitive.Root className="w-full" defaultValue="standard">
-      {shippingOptions.map((option) => (
-        <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-          <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-        </CardRadioGroupPrimitive.Item>
-      ))}
-    </CardRadioGroupPrimitive.Root>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'The default CardRadioGroup with text-only options. Only one item can be selected at a time.',
-      },
-    },
-  },
-};
-
-export const WithImages: Story = {
-  args: {},
-  render: () => (
-    <CardRadioGroupPrimitive.Root className="w-full" defaultValue="scrub-brush">
-      {productOptions.map((option) => (
-        <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-          <CardRadioGroupPrimitive.Thumbnail>
-            <CardRadioGroupPrimitive.Image alt={option.image.alt} src={option.image.src} />
-          </CardRadioGroupPrimitive.Thumbnail>
-          <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-        </CardRadioGroupPrimitive.Item>
-      ))}
-    </CardRadioGroupPrimitive.Root>
-  ),
   parameters: {
     docs: {
       description: {
-        story:
-          'CardRadioGroup with thumbnail images, perfect for product variant selection with visual previews.',
+        story: 'Text-only card options for selections like shipping methods.',
       },
-    },
-  },
-};
+      source: {
+        code: `
+const shippingOptions = [
+  { id: 'shipping-standard', value: 'standard', label: 'Standard Shipping (5-7 days)' },
+  { id: 'shipping-express', value: 'express', label: 'Express Shipping (2-3 days)' },
+  { id: 'shipping-overnight', value: 'overnight', label: 'Overnight Delivery' },
+];
 
-export const HighLevelComponent: Story = {
-  args: {},
-  render: () => (
-    <CardRadioGroup className="w-full" defaultValue="scrub-brush" options={productOptions} />
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Using the high-level `CardRadioGroup` component with an options array for a simpler API.',
+<CardRadioGroup
+  options={shippingOptions}
+  defaultValue="standard"
+/>
+        `,
       },
     },
   },
+  render: () => <CardRadioGroup defaultValue="standard" options={shippingOptions} />,
 };
 
-export const HighLevelWithoutImages: Story = {
-  args: {},
-  render: () => (
-    <CardRadioGroup className="w-full" defaultValue="standard" options={shippingOptions} />
-  ),
+export const WithImages: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'High-level component without images, useful for text-based options.',
+        story: 'Cards with thumbnail images for product variant selection.',
       },
+      source: {
+        code: `
+const productOptions = [
+  {
+    id: 'product-scrub-brush',
+    value: 'scrub-brush',
+    label: 'Natural Fiber Scrub Brush',
+    image: {
+      src: 'https://images.unsplash.com/photo-1685052392951-4eb54985d3ae?w=96&h=96&fit=crop',
+      alt: 'Natural fiber scrub brush',
     },
   },
-};
+  // ... more options
+];
 
-export const Disabled: Story = {
-  args: {},
-  render: () => (
-    <CardRadioGroupPrimitive.Root className="w-full" defaultValue="standard" disabled>
-      {shippingOptions.map((option) => (
-        <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-          <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-        </CardRadioGroupPrimitive.Item>
-      ))}
-    </CardRadioGroupPrimitive.Root>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'The entire radio group can be disabled, preventing any interaction.',
+<CardRadioGroup
+  options={productOptions}
+  defaultValue="scrub-brush"
+/>
+        `,
       },
     },
   },
+  render: () => <CardRadioGroup defaultValue="scrub-brush" options={productOptions} />,
 };
 
 export const DisabledItems: Story = {
-  args: {},
-  render: () => (
-    <CardRadioGroupPrimitive.Root className="w-full" defaultValue="standard">
-      <CardRadioGroupPrimitive.Item value="standard">
-        <CardRadioGroupPrimitive.Label>Standard Shipping (5-7 days)</CardRadioGroupPrimitive.Label>
-      </CardRadioGroupPrimitive.Item>
-      <CardRadioGroupPrimitive.Item value="express">
-        <CardRadioGroupPrimitive.Label>Express Shipping (2-3 days)</CardRadioGroupPrimitive.Label>
-      </CardRadioGroupPrimitive.Item>
-      <CardRadioGroupPrimitive.Item disabled value="overnight">
-        <CardRadioGroupPrimitive.Label>
-          Overnight Delivery (Not Available)
-        </CardRadioGroupPrimitive.Label>
-      </CardRadioGroupPrimitive.Item>
-    </CardRadioGroupPrimitive.Root>
-  ),
   parameters: {
     docs: {
       description: {
-        story:
-          'Individual items can be disabled while others remain interactive. Useful for unavailable shipping methods or out-of-stock variants.',
+        story: 'Individual options can be disabled (e.g., unavailable shipping methods).',
       },
-    },
-  },
-};
-
-export const Controlled: Story = {
-  args: {},
-  render: () => {
-    const [value, setValue] = useState<string>('credit-card');
-
-    return (
-      <div className="w-full space-y-4">
-        <CardRadioGroupPrimitive.Root className="w-full" onValueChange={setValue} value={value}>
-          {paymentOptions.map((option) => (
-            <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-              <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-            </CardRadioGroupPrimitive.Item>
-          ))}
-        </CardRadioGroupPrimitive.Root>
-        <div className="rounded-lg bg-contrast-100 p-3 text-sm">
-          <span className="font-medium text-contrast-500">Selected payment:</span>{' '}
-          <span className="text-foreground">
-            {paymentOptions.find((o) => o.value === value)?.label}
-          </span>
-        </div>
-        <button
-          className="rounded-lg bg-brand px-3 py-2 text-sm font-medium text-background transition-colors hover:bg-brand/90"
-          onClick={() => setValue('credit-card')}
-          type="button"
-        >
-          Reset to Credit Card
-        </button>
-      </div>
-    );
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Use `value` and `onValueChange` for controlled state management.',
-      },
-    },
-  },
-};
-
-export const WithMouseEnterCallback: Story = {
-  args: {},
-  render: () => {
-    const [hoveredValue, setHoveredValue] = useState<string | null>(null);
+      source: {
+        code: `
+const options = [
+  { id: 'standard', value: 'standard', label: 'Standard Shipping' },
+  { id: 'express', value: 'express', label: 'Express Shipping' },
+  { id: 'overnight', value: 'overnight', label: 'Overnight (Unavailable)', disabled: true },
+];
 
-    return (
-      <div className="w-full space-y-4">
-        <CardRadioGroup
-          className="w-full"
-          defaultValue="scrub-brush"
-          onOptionMouseEnter={setHoveredValue}
-          options={productOptions}
-        />
-        <div className="rounded-lg bg-contrast-100 p-3 text-sm">
-          <span className="font-medium text-contrast-500">Previewing:</span>{' '}
-          <span className="text-foreground">
-            {hoveredValue != null && hoveredValue !== ''
-              ? productOptions.find((o) => o.value === hoveredValue)?.label
-              : 'Hover over an option'}
-          </span>
-        </div>
-      </div>
-    );
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'The `onOptionMouseEnter` callback fires when hovering over options. Useful for showing product previews before selection.',
+<CardRadioGroup
+  options={options}
+  defaultValue="standard"
+/>
+        `,
       },
     },
   },
-};
-
-export const ProductVariantSelector: Story = {
-  args: {},
   render: () => (
-    <div className="w-full space-y-3">
-      <label className="text-sm font-medium text-foreground">Select Product</label>
-      <CardRadioGroupPrimitive.Root className="w-full" defaultValue="scrub-brush">
-        {productOptions.map((option) => (
-          <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-            <CardRadioGroupPrimitive.Thumbnail>
-              <CardRadioGroupPrimitive.Image alt={option.image.alt} src={option.image.src} />
-            </CardRadioGroupPrimitive.Thumbnail>
-            <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-          </CardRadioGroupPrimitive.Item>
-        ))}
-      </CardRadioGroupPrimitive.Root>
-    </div>
+    <CardRadioGroup
+      defaultValue="standard"
+      options={[
+        { id: 'standard', value: 'standard', label: 'Standard Shipping (5-7 days)' },
+        { id: 'express', value: 'express', label: 'Express Shipping (2-3 days)' },
+        { id: 'overnight', value: 'overnight', label: 'Overnight (Unavailable)', disabled: true },
+      ]}
+    />
   ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'A practical example for product variant selection in e-commerce applications.',
-      },
-    },
-  },
 };
 
-export const ShippingMethodSelector: Story = {
-  args: {},
-  render: () => (
-    <div className="w-full space-y-3">
-      <label className="text-sm font-medium text-foreground">Shipping Method</label>
-      <CardRadioGroupPrimitive.Root className="w-full" defaultValue="standard">
-        {shippingOptions.map((option) => (
-          <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-            <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-          </CardRadioGroupPrimitive.Item>
-        ))}
-      </CardRadioGroupPrimitive.Root>
-    </div>
-  ),
+export const ComposableAnatomy: Story = {
   parameters: {
     docs: {
       description: {
-        story: 'CardRadioGroup works well for shipping method selection during checkout.',
+        story: `
+Use the primitive components for full control over the structure.
+
+| Primitive                          | Description                              |
+|------------------------------------|------------------------------------------|
+| \`CardRadioGroupPrimitive.Root\`      | Radio group container.                   |
+| \`CardRadioGroupPrimitive.Item\`      | Individual card option.                  |
+| \`CardRadioGroupPrimitive.Thumbnail\` | Container for the image.                 |
+| \`CardRadioGroupPrimitive.Image\`     | Image element with \`asChild\` support.  |
+| \`CardRadioGroupPrimitive.Label\`     | Text label for the option.               |
+        `,
       },
-    },
-  },
-};
+      source: {
+        code: `
+import * as CardRadioGroupPrimitive from '@/components/card-radio-group/primitives';
 
-export const PaymentMethodSelector: Story = {
-  args: {},
-  render: () => (
-    <div className="w-full space-y-3">
-      <label className="text-sm font-medium text-foreground">Payment Method</label>
-      <CardRadioGroupPrimitive.Root className="w-full" defaultValue="credit-card">
-        {paymentOptions.map((option) => (
-          <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-            <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-          </CardRadioGroupPrimitive.Item>
-        ))}
-      </CardRadioGroupPrimitive.Root>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story: 'Payment method selection during checkout using CardRadioGroup.',
+<CardRadioGroupPrimitive.Root defaultValue="scrub-brush">
+  <CardRadioGroupPrimitive.Item value="scrub-brush">
+    <CardRadioGroupPrimitive.Thumbnail>
+      <CardRadioGroupPrimitive.Image
+        src="https://images.unsplash.com/photo-1685052392951-4eb54985d3ae?w=96&h=96&fit=crop"
+        alt="Natural fiber scrub brush"
+      />
+    </CardRadioGroupPrimitive.Thumbnail>
+    <CardRadioGroupPrimitive.Label>Natural Fiber Scrub Brush</CardRadioGroupPrimitive.Label>
+  </CardRadioGroupPrimitive.Item>
+  <CardRadioGroupPrimitive.Item value="soap-dispenser">
+    <CardRadioGroupPrimitive.Thumbnail>
+      <CardRadioGroupPrimitive.Image
+        src="https://images.unsplash.com/photo-1597816189341-6ed558ab017e?w=96&h=96&fit=crop"
+        alt="Minimal ceramic soap dispenser"
+      />
+    </CardRadioGroupPrimitive.Thumbnail>
+    <CardRadioGroupPrimitive.Label>Minimal Ceramic Soap Dispenser</CardRadioGroupPrimitive.Label>
+  </CardRadioGroupPrimitive.Item>
+</CardRadioGroupPrimitive.Root>
+        `,
       },
     },
   },
-};
-
-export const CustomThemed: Story = {
-  args: {},
   render: () => (
-    <CardRadioGroupPrimitive.Root className="w-full" defaultValue="standard">
-      {shippingOptions.map((option) => (
-        <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-          <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-        </CardRadioGroupPrimitive.Item>
-      ))}
+    <CardRadioGroupPrimitive.Root defaultValue="scrub-brush">
+      <CardRadioGroupPrimitive.Item value="scrub-brush">
+        <CardRadioGroupPrimitive.Thumbnail>
+          <CardRadioGroupPrimitive.Image
+            alt="Natural fiber scrub brush"
+            src="https://images.unsplash.com/photo-1685052392951-4eb54985d3ae?w=96&h=96&fit=crop"
+          />
+        </CardRadioGroupPrimitive.Thumbnail>
+        <CardRadioGroupPrimitive.Label>Natural Fiber Scrub Brush</CardRadioGroupPrimitive.Label>
+      </CardRadioGroupPrimitive.Item>
+      <CardRadioGroupPrimitive.Item value="soap-dispenser">
+        <CardRadioGroupPrimitive.Thumbnail>
+          <CardRadioGroupPrimitive.Image
+            alt="Minimal ceramic soap dispenser"
+            src="https://images.unsplash.com/photo-1597816189341-6ed558ab017e?w=96&h=96&fit=crop"
+          />
+        </CardRadioGroupPrimitive.Thumbnail>
+        <CardRadioGroupPrimitive.Label>
+          Minimal Ceramic Soap Dispenser
+        </CardRadioGroupPrimitive.Label>
+      </CardRadioGroupPrimitive.Item>
     </CardRadioGroupPrimitive.Root>
   ),
-  decorators: [
-    (Story: ComponentType) => (
-      <div className="flex w-80 items-center justify-center rounded-xl bg-contrast-100 p-8 [--card-radio-group-light-checked-background:var(--brand)] [--card-radio-group-light-unchecked-background-hover:color-mix(in_oklch,var(--brand)_10%,transparent)] [--card-radio-group-light-unchecked-border-hover:var(--brand)]">
-        <Story />
-      </div>
-    ),
-  ],
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'The CardRadioGroup can be fully themed using CSS variables. This example uses the primary color for the selected state.',
-      },
-    },
-  },
-};
-
-export const SubscriptionPlans: Story = {
-  args: {},
-  render: () => {
-    const planOptions = [
-      { id: 'plan-monthly', value: 'monthly', label: 'Monthly — $9.99/month' },
-      { id: 'plan-quarterly', value: 'quarterly', label: 'Quarterly — $24.99/quarter (Save 17%)' },
-      { id: 'plan-annual', value: 'annual', label: 'Annual — $79.99/year (Save 33%)' },
-    ];
-
-    return (
-      <div className="w-full space-y-3">
-        <label className="text-sm font-medium text-foreground">Select Plan</label>
-        <CardRadioGroup className="w-full" defaultValue="annual" options={planOptions} />
-      </div>
-    );
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Subscription plan selection showcasing pricing tiers with savings information.',
-      },
-    },
-  },
-};
-
-export const DeliveryTimeSlots: Story = {
-  args: {},
-  render: () => {
-    const timeSlotOptions = [
-      { value: 'morning', label: 'Morning (8:00 AM - 12:00 PM)' },
-      { value: 'afternoon', label: 'Afternoon (12:00 PM - 5:00 PM)' },
-      { value: 'evening', label: 'Evening (5:00 PM - 9:00 PM)' },
-    ];
-
-    return (
-      <div className="w-full space-y-3">
-        <label className="text-sm font-medium text-foreground">Delivery Time Slot</label>
-        <CardRadioGroupPrimitive.Root className="w-full" defaultValue="afternoon">
-          {timeSlotOptions.map((option) => (
-            <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-              <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-            </CardRadioGroupPrimitive.Item>
-          ))}
-        </CardRadioGroupPrimitive.Root>
-      </div>
-    );
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Delivery time slot selection for scheduling deliveries.',
-      },
-    },
-  },
-};
-
-export const CleaningKitBundles: Story = {
-  args: {},
-  render: () => {
-    const bundleOptions = [
-      {
-        value: 'starter',
-        label: 'Eco Cleaning Starter Kit',
-        image: {
-          src: 'https://images.unsplash.com/photo-1685052392996-5c042ab4c170?w=96&h=96&fit=crop',
-          alt: 'Eco cleaning starter kit',
-        },
-      },
-      {
-        value: 'essentials',
-        label: 'Natural Cleaning Essentials',
-        image: {
-          src: 'https://images.unsplash.com/photo-1551239330-2db25ffa5e90?w=96&h=96&fit=crop',
-          alt: 'Natural cleaning essentials set',
-        },
-      },
-      {
-        value: 'complete',
-        label: 'Complete Home Set',
-        image: {
-          src: 'https://images.unsplash.com/photo-1619451427882-6aaaded0cc61?w=96&h=96&fit=crop',
-          alt: 'Reusable cleaning cloths',
-        },
-      },
-    ];
-
-    return (
-      <div className="w-full space-y-3">
-        <label className="text-sm font-medium text-foreground">Choose Your Bundle</label>
-        <CardRadioGroupPrimitive.Root className="w-full" defaultValue="starter">
-          {bundleOptions.map((option) => (
-            <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-              <CardRadioGroupPrimitive.Thumbnail>
-                <CardRadioGroupPrimitive.Image alt={option.image.alt} src={option.image.src} />
-              </CardRadioGroupPrimitive.Thumbnail>
-              <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-            </CardRadioGroupPrimitive.Item>
-          ))}
-        </CardRadioGroupPrimitive.Root>
-      </div>
-    );
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Product bundle selection for eco-friendly cleaning supplies, demonstrating image thumbnails with product categories.',
-      },
-    },
-  },
-};
-
-export const KitchenAccessories: Story = {
-  args: {},
-  render: () => {
-    const accessoryOptions = [
-      {
-        value: 'dish-sponge',
-        label: 'Eco Dish Sponge Set',
-        image: {
-          src: 'https://images.unsplash.com/photo-1685052391251-e09402a6b8e8?w=96&h=96&fit=crop',
-          alt: 'Eco dish sponge set',
-        },
-      },
-      {
-        value: 'cleaning-brush',
-        label: 'Wood Handle Cleaning Brush',
-        image: {
-          src: 'https://images.unsplash.com/photo-1682251008222-412b140cbf4f?w=96&h=96&fit=crop',
-          alt: 'Wood handle cleaning brush',
-        },
-      },
-      {
-        value: 'loofah',
-        label: 'Natural Loofah Sponge',
-        image: {
-          src: 'https://images.unsplash.com/photo-1638609269267-f0128098a809?w=96&h=96&fit=crop',
-          alt: 'Natural loofah sponge',
-        },
-      },
-      {
-        value: 'scrubber',
-        label: 'Plant-Based Scrubber Pad',
-        image: {
-          src: 'https://images.unsplash.com/photo-1685052386750-902a081b99da?w=96&h=96&fit=crop',
-          alt: 'Plant-based scrubber pad',
-        },
-      },
-    ];
-
-    return (
-      <div className="w-full space-y-3">
-        <label className="text-sm font-medium text-foreground">Add an Accessory</label>
-        <CardRadioGroupPrimitive.Root className="w-full" defaultValue="dish-sponge">
-          {accessoryOptions.map((option) => (
-            <CardRadioGroupPrimitive.Item key={option.value} value={option.value}>
-              <CardRadioGroupPrimitive.Thumbnail>
-                <CardRadioGroupPrimitive.Image alt={option.image.alt} src={option.image.src} />
-              </CardRadioGroupPrimitive.Thumbnail>
-              <CardRadioGroupPrimitive.Label>{option.label}</CardRadioGroupPrimitive.Label>
-            </CardRadioGroupPrimitive.Item>
-          ))}
-        </CardRadioGroupPrimitive.Root>
-      </div>
-    );
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          'Kitchen accessory selection showcasing various eco-friendly cleaning tools with image previews.',
-      },
-    },
-  },
 };
diff --git a/src/components/card/card.tsx b/src/components/card/card.tsx
index 063187a..90a936f 100644
--- a/src/components/card/card.tsx
+++ b/src/components/card/card.tsx
@@ -20,10 +20,8 @@ export interface CardProps {
  *
  * ```css
  * :root {
- *   --card-focus: var(--brand);
- *   --card-border-color: var(--contrast-200);
- *   --card-background: var(--background);
- *   --card-hover-background: color-mix(in oklab, var(--contrast-100) 50%,transparent);
+ *   --card-fill: var(--background);
+ *   --card-fill-hover: color-mix(in oklch,var(--contrast-100) 50%,transparent);
  * }
  * ```
  */
diff --git a/src/components/card/primitives/card-link.tsx b/src/components/card/primitives/card-link.tsx
index 0b49b03..1d8af07 100644
--- a/src/components/card/primitives/card-link.tsx
+++ b/src/components/card/primitives/card-link.tsx
@@ -12,11 +12,7 @@ export function CardLink({ asChild = false, className, children, ...props }: Car
 
   return (
     <Component
-      className={cn(
-        'absolute inset-0 rounded-2xl',
-        'focus:outline-none focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-[var(--card-focus,var(--brand))]',
-        className,
-      )}
+      className={cn('focus-primary absolute inset-0 rounded-2xl', className)}
       data-slot="card-link"
       {...props}
     />
diff --git a/src/components/card/primitives/card-root.tsx b/src/components/card/primitives/card-root.tsx
index 1fa88a5..13a71e8 100644
--- a/src/components/card/primitives/card-root.tsx
+++ b/src/components/card/primitives/card-root.tsx
@@ -18,9 +18,7 @@ export function CardRoot<T extends ElementType = 'div'>({
     <Component
       className={cn(
         'group/card relative w-full rounded-2xl border p-6 @container',
-        'border-[var(--card-border-color,var(--contrast-200))] bg-[var(--card-background,var(--background))] has-[a]:hover:bg-[var(--card-hover-background,color-mix(in_oklab,var(--contrast-100)_50%,transparent))]',
-        // Hover state (when card contains a link)
-        'has-[a]:hover:bg-[var(--card-hover-background,color-mix(in_oklab,var(--contrast-100)_50%,transparent))]',
+        'border-[--border] bg-[--card-fill,var(--background)] has-[a]:hover:bg-[color-mix(in_oklch,var(--card-fill-hover,var(--contrast-100))_50%,transparent)]',
         className,
       )}
       data-slot="card-root"
diff --git a/src/components/card/storybook/card.stories.tsx b/src/components/card/storybook/card.stories.tsx
index ebc031f..b104edb 100644
--- a/src/components/card/storybook/card.stories.tsx
+++ b/src/components/card/storybook/card.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { ArrowRight, Package } from 'lucide-react';
 
 import { Card, type CardProps } from '@/components/card';
 import * as CardPrimitive from '@/components/card/primitives';
@@ -12,67 +11,14 @@ const meta: Meta<typeof Card> = {
     docs: {
       description: {
         component: `
-A versatile card component for displaying content in a contained, styled container. Supports optional link behavior for clickable cards.
+A versatile container component for displaying content with optional link behavior for clickable cards.
 
 ## CSS Variables
 
-The Card component supports theming through CSS variables:
-
 \`\`\`css
 :root {
-  --card-focus: var(--brand);
-  --card-border-color: var(--contrast-200);
-  --card-background: var(--background);
-  --card-hover-background: color-mix(in oklab, var(--contrast-100) 50%, transparent);
+  --card-fill: var(--background);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Card\` component provides a simple API with an optional \`link\` prop for clickable cards:
-
-\`\`\`tsx
-import { Card } from '@/components/card';
-
-<Card
-  link={{
-    href: '/products',
-    ariaLabel: 'View all products',
-  }}
->
-  <h3>Shop Products</h3>
-  <p>Browse our collection</p>
-</Card>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Card from '@/components/card';
-
-<Card.Root>
-  <h3>Card Title</h3>
-  <p>Card content goes here.</p>
-  <Card.Link href="/page" aria-label="Go to page" />
-</Card.Root>
-\`\`\`
-
-\`Card.Root\` supports the \`as\` prop for semantic elements, and \`Card.Link\` supports \`asChild\` for router integration:
-
-\`\`\`tsx
-import * as Card from '@/components/card';
-import Link from 'next/link';
-
-<Card.Root as="article">
-  <h3>Products</h3>
-  <Card.Link asChild>
-    <Link href="/products" aria-label="View products" />
-  </Card.Link>
-</Card.Root>
 \`\`\`
         `,
       },
@@ -87,115 +33,61 @@ import Link from 'next/link';
     },
     link: {
       control: false,
-      description: 'Link configuration with href and ariaLabel for clickable cards',
+      description:
+        'Link configuration with `href`, `ariaLabel`, and optional `asChild` for router integration',
     },
     children: {
       control: false,
       description: 'Content to display inside the card',
     },
   },
-  decorators: [(Story) => <div className="w-96">{Story()}</div>],
+  decorators: [(Story) => <div className="w-80">{Story()}</div>],
 };
 
 export default meta;
 type Story = StoryObj<CardProps>;
 
-// Default card
 export const Default: Story = {
   args: {
     children: (
-      <div>
+      <>
         <h3 className="text-lg font-semibold">Card Title</h3>
         <p className="mt-2 text-sm text-contrast-400">
           This is a simple card component with some basic content.
         </p>
-      </div>
+      </>
     ),
   },
 };
 
-// Clickable card with link
 export const WithLink: Story = {
   args: {
     children: (
-      <div>
+      <>
         <h3 className="text-lg font-semibold">Clickable Card</h3>
         <p className="mt-2 text-sm text-contrast-400">
           This card is clickable and will navigate to a new page.
         </p>
-        <div className="mt-4 flex items-center gap-2 font-semibold text-foreground">
-          <span>Learn more</span>
-          <ArrowRight
-            className="transition-transform duration-100 ease-linear group-hover/card:translate-x-1"
-            size={20}
-          />
-        </div>
-      </div>
+      </>
     ),
     link: {
       href: '#',
       ariaLabel: 'Learn more about this card',
     },
   },
-};
-
-// Card with asChild link for router integration
-export const WithAsChildLink: Story = {
-  name: 'With asChild Link (Monolith)',
-  render: () => (
-    <Card
-      link={{
-        href: '/products',
-        ariaLabel: 'View products',
-        asChild: true,
-        children: (
-          <a
-            href="/products"
-            onClick={(e) => {
-              e.preventDefault();
-              alert('This would navigate using your routing library');
-            }}
-          />
-        ),
-      }}
-    >
-      <h3 className="text-lg font-semibold">Router Integration</h3>
-      <p className="mt-2 text-sm text-contrast-400">
-        Using asChild on the link for Next.js Link or React Router.
-      </p>
-    </Card>
-  ),
-};
-
-// Card with as prop for semantic element
-export const WithAsRoot: Story = {
-  name: 'With as Prop (Monolith)',
-  render: () => (
-    <Card as="article" link={{ href: '#', ariaLabel: 'Learn more' }}>
-      <h3 className="text-lg font-semibold">Semantic Article</h3>
-      <p className="mt-2 text-sm text-contrast-400">
-        Using the as prop to render as an article element for better semantics.
-      </p>
-    </Card>
-  ),
-};
-
-// Card with icon
-export const WithIcon: Story = {
-  args: {
-    children: (
-      <div>
-        <div className="mb-4 flex h-12 w-12 items-center justify-center rounded-full bg-brand-background">
-          <Package className="text-brand-shadow" size={24} />
-        </div>
-        <h3 className="text-lg font-semibold">Free Shipping</h3>
-        <p className="mt-2 text-sm text-contrast-400">Get free shipping on all orders over $50.</p>
-      </div>
-    ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Add the `link` prop to make the entire card clickable. The card will show a hover state when it contains a link.',
+      },
+    },
   },
 };
 
-// Composable anatomy example
+/**
+ * Use the composable primitives to build custom card layouts.
+ */
 export const ComposableAnatomy: Story = {
   render: () => (
     <CardPrimitive.Root>
@@ -204,46 +96,34 @@ export const ComposableAnatomy: Story = {
       <CardPrimitive.Link aria-label="View details" href="#" />
     </CardPrimitive.Root>
   ),
-};
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the composable primitives to build custom card layouts:
 
-// With as prop for semantic element (primitives)
-export const WithAsRootPrimitive: Story = {
-  name: 'With as Prop (Primitive)',
-  render: () => (
-    <CardPrimitive.Root as="article">
-      <h3 className="text-lg font-semibold">Semantic Article</h3>
-      <p className="mt-2 text-sm text-contrast-400">
-        Using the as prop to render as an article element for better semantics.
-      </p>
-      <CardPrimitive.Link aria-label="View details" href="#" />
-    </CardPrimitive.Root>
-  ),
-};
+\`\`\`tsx
+import * as CardPrimitive from '@/components/card/primitives';
 
-// With asChild for router integration (primitives)
-export const WithAsChildLinkPrimitive: Story = {
-  name: 'With asChild Link (Primitive)',
-  render: () => (
-    <CardPrimitive.Root>
-      <h3 className="text-lg font-semibold">Router Integration</h3>
-      <p className="mt-2 text-sm text-contrast-400">
-        The Card.Link supports asChild for Next.js Link or React Router.
-      </p>
-      <CardPrimitive.Link asChild>
-        <a
-          aria-label="View products"
-          href="/products"
-          onClick={(e) => {
-            e.preventDefault();
-            alert('This would navigate using your routing library');
-          }}
-        />
-      </CardPrimitive.Link>
-    </CardPrimitive.Root>
-  ),
+<CardPrimitive.Root>
+  <h3>Card Title</h3>
+  <p>Card content goes here.</p>
+  <CardPrimitive.Link href="/page" aria-label="Go to page" />
+</CardPrimitive.Root>
+\`\`\`
+        `,
+      },
+    },
+  },
 };
 
-// Skeleton loading state
 export const Skeleton: Story = {
-  render: () => <CardPrimitive.Skeleton className="h-40 w-96" />,
+  render: () => <CardPrimitive.Skeleton className="h-40" />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use the Skeleton primitive to display a loading state.',
+      },
+    },
+  },
 };
diff --git a/src/components/carousel/carousel.tsx b/src/components/carousel/carousel.tsx
index aa3a270..957ad3c 100644
--- a/src/components/carousel/carousel.tsx
+++ b/src/components/carousel/carousel.tsx
@@ -24,11 +24,7 @@ export type CarouselProps = ComponentProps<typeof CarouselPrimitive.Root> & {
  *
  * ```css
  * :root {
-    --carousel-light-scrollbar: var(--foreground);
-    --carousel-dark-scrollbar: var(--background);
-    --carousel-focus: var(--brand);
-    --carousel-light-button: var(--foreground);
-    --carousel-dark-button: var(--background);
+ *   --carousel-fill-scrollbar:    var(--foreground);
  * }
  * ```
  */
diff --git a/src/components/carousel/primitives/carousel-controls.tsx b/src/components/carousel/primitives/carousel-controls.tsx
index 21293e8..b060221 100644
--- a/src/components/carousel/primitives/carousel-controls.tsx
+++ b/src/components/carousel/primitives/carousel-controls.tsx
@@ -9,10 +9,7 @@ export type CarouselControlsProps = ComponentProps<'div'>;
 export function CarouselControls({ className, children, ...props }: CarouselControlsProps) {
   return (
     <div
-      className={cn(
-        'mt-10 flex w-full items-center justify-between gap-2 text-[var(--carousel-light-button,var(--foreground))]',
-        className,
-      )}
+      className={cn('mt-10 flex w-full items-center justify-between gap-2', className)}
       data-slot="carousel-controls"
       {...props}
     >
diff --git a/src/components/carousel/primitives/carousel-next-icon.tsx b/src/components/carousel/primitives/carousel-next-icon.tsx
index c8e3b6f..f6c3376 100644
--- a/src/components/carousel/primitives/carousel-next-icon.tsx
+++ b/src/components/carousel/primitives/carousel-next-icon.tsx
@@ -13,9 +13,11 @@ export interface CarouselNextIconProps {
 }
 
 export function CarouselNextIcon({ asChild = false, className, children }: CarouselNextIconProps) {
+  const iconStyles = cn('size-6', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-6', className)} data-slot="carousel-next-icon">
+      <Slot className={cn(iconStyles, className)} data-slot="carousel-next-icon">
         {children}
       </Slot>
     );
@@ -24,7 +26,7 @@ export function CarouselNextIcon({ asChild = false, className, children }: Carou
   return (
     <ArrowRight
       absoluteStrokeWidth
-      className={cn('size-6', className)}
+      className={iconStyles}
       data-slot="carousel-next-icon"
       strokeWidth={1.5}
     />
diff --git a/src/components/carousel/primitives/carousel-next.tsx b/src/components/carousel/primitives/carousel-next.tsx
index e52ad2b..7be49d3 100644
--- a/src/components/carousel/primitives/carousel-next.tsx
+++ b/src/components/carousel/primitives/carousel-next.tsx
@@ -2,8 +2,8 @@
 
 import type { ComponentProps } from 'react';
 
+import { Button } from '@/components/button';
 import { useCarousel } from '@/components/carousel';
-import { cn } from '@/lib';
 
 export type CarouselNextProps = ComponentProps<'button'>;
 
@@ -11,23 +11,18 @@ export function CarouselNext({ children, className, ...props }: CarouselNextProp
   const { canScrollNext, scrollNext } = useCarousel();
 
   return (
-    <button
-      className={cn(
-        'rounded-lg transition-colors duration-300',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--carousel-focus,var(--brand))]',
-        // Disabled state
-        'disabled:pointer-events-none disabled:opacity-25',
-        className,
-      )}
-      data-slot="carousel-next"
+    <Button
+      className={className}
       disabled={!canScrollNext}
       onClick={scrollNext}
+      shape="circle"
+      size="small"
       title="Next"
       type="button"
+      variant="ghost"
       {...props}
     >
       {children}
-    </button>
+    </Button>
   );
 }
diff --git a/src/components/carousel/primitives/carousel-prev-icon.tsx b/src/components/carousel/primitives/carousel-prev-icon.tsx
index 746a6b9..3228686 100644
--- a/src/components/carousel/primitives/carousel-prev-icon.tsx
+++ b/src/components/carousel/primitives/carousel-prev-icon.tsx
@@ -13,9 +13,11 @@ export interface CarouselPrevIconProps {
 }
 
 export function CarouselPrevIcon({ asChild = false, className, children }: CarouselPrevIconProps) {
+  const iconStyles = cn('size-6', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-6', className)} data-slot="carousel-prev-icon">
+      <Slot className={iconStyles} data-slot="carousel-prev-icon">
         {children}
       </Slot>
     );
@@ -24,7 +26,7 @@ export function CarouselPrevIcon({ asChild = false, className, children }: Carou
   return (
     <ArrowLeft
       absoluteStrokeWidth
-      className={cn('size-6', className)}
+      className={iconStyles}
       data-slot="carousel-prev-icon"
       strokeWidth={1.5}
     />
diff --git a/src/components/carousel/primitives/carousel-prev.tsx b/src/components/carousel/primitives/carousel-prev.tsx
index b1f0c3b..23a453a 100644
--- a/src/components/carousel/primitives/carousel-prev.tsx
+++ b/src/components/carousel/primitives/carousel-prev.tsx
@@ -2,32 +2,27 @@
 
 import type { ComponentProps } from 'react';
 
+import { Button } from '@/components/button';
 import { useCarousel } from '@/components/carousel';
-import { cn } from '@/lib';
 
-export type CarouselPrevProps = ComponentProps<'button'>;
+export type CarouselPrevProps = ComponentProps<typeof Button>;
 
 export function CarouselPrev({ children, className, ...props }: CarouselPrevProps) {
   const { canScrollPrev, scrollPrev } = useCarousel();
 
   return (
-    <button
-      className={cn(
-        'rounded-lg transition-colors duration-300',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--carousel-focus,var(--brand))]',
-        // Disabled state
-        'disabled:pointer-events-none disabled:opacity-25',
-        className,
-      )}
-      data-slot="carousel-prev"
+    <Button
+      className={className}
       disabled={!canScrollPrev}
       onClick={scrollPrev}
+      shape="circle"
+      size="small"
       title="Previous"
       type="button"
+      variant="ghost"
       {...props}
     >
       {children}
-    </button>
+    </Button>
   );
 }
diff --git a/src/components/carousel/primitives/carousel-scrollbar.tsx b/src/components/carousel/primitives/carousel-scrollbar.tsx
index 155c97d..37662cd 100644
--- a/src/components/carousel/primitives/carousel-scrollbar.tsx
+++ b/src/components/carousel/primitives/carousel-scrollbar.tsx
@@ -92,14 +92,14 @@ export function CarouselScrollbar({ className, ...props }: CarouselScrollbarProp
       {/* Track */}
       <div
         className={cn(
-          'pointer-events-none absolute h-1 w-full rounded-full bg-[var(--carousel-light-scrollbar,var(--foreground))] opacity-10',
+          'pointer-events-none absolute h-1 w-full rounded-full bg-[--carousel-fill-scrollbar,var(--foreground)] opacity-10',
         )}
         data-slot="carousel-track"
       />
       {/* Bar */}
       <div
         className={cn(
-          'pointer-events-none absolute h-1 rounded-full bg-[var(--carousel-light-scrollbar,var(--foreground))] transition-all ease-out',
+          'pointer-events-none absolute h-1 rounded-full bg-[--carousel-fill-scrollbar,var(--foreground)] transition-all ease-out',
         )}
         data-slot="carousel-bar"
         style={{
diff --git a/src/components/carousel/storybook/carousel.stories.tsx b/src/components/carousel/storybook/carousel.stories.tsx
index 1ef5566..3b52ef1 100644
--- a/src/components/carousel/storybook/carousel.stories.tsx
+++ b/src/components/carousel/storybook/carousel.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { ArrowLeft, ArrowRight } from 'lucide-react';
 import type { ComponentType } from 'react';
 
 import { Carousel, type CarouselProps } from '@/components/carousel';
@@ -13,19 +12,23 @@ const meta: Meta<typeof Carousel> = {
     docs: {
       description: {
         component: `
-A responsive carousel component built on top of Embla Carousel. Supports customizable navigation, scrollbar, and flexible item layouts.
+A responsive carousel component built on [Embla Carousel](https://www.embla-carousel.com/). Supports customizable navigation, scrollbar, and flexible item layouts.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --carousel-light-scrollbar: var(--foreground);
-  --carousel-dark-scrollbar: var(--background);
-  --carousel-focus: var(--brand);
-  --carousel-light-button: var(--foreground);
-  --carousel-dark-button: var(--background);
+  --carousel-fill-scrollbar: var(--foreground);
 }
 \`\`\`
+
+## Container Queries
+
+The carousel uses container queries to adjust item spacing at the \`@2xl\` breakpoint (42rem / 672px):
+
+| Element | Below @2xl | @2xl and above |
+|---------|------------|----------------|
+| Item gap | pl-4 (-ml-4) | pl-5 (-ml-5) |
         `,
       },
     },
@@ -48,6 +51,14 @@ A responsive carousel component built on top of Embla Carousel. Supports customi
       control: false,
       description: 'Embla Carousel options for customizing behavior',
     },
+    prevIcon: {
+      control: false,
+      description: 'Custom previous icon configuration with `asChild` support',
+    },
+    nextIcon: {
+      control: false,
+      description: 'Custom next icon configuration with `asChild` support',
+    },
   },
   decorators: [
     (Story: ComponentType) => (
@@ -115,39 +126,8 @@ export const Default: Story = {
   },
 };
 
-export const WithoutScrollbar: Story = {
-  args: {
-    items: productItems,
-    showScrollbar: false,
-    showNav: true,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Hide the scrollbar by setting `showScrollbar` to `false`.',
-      },
-    },
-  },
-};
-
-export const WithoutNav: Story = {
-  args: {
-    items: productItems,
-    showScrollbar: true,
-    showNav: false,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Hide the navigation arrows by setting `showNav` to `false`.',
-      },
-    },
-  },
-};
-
 /**
- * The Carousel can be built using composable primitives for full customization.
- * This example shows the component anatomy using the primitive components.
+ * Use the composable primitives to build custom carousel layouts.
  */
 export const ComposableAnatomy: Story = {
   render: () => (
@@ -177,10 +157,10 @@ export const ComposableAnatomy: Story = {
         <CarouselPrimitive.Scrollbar />
         <CarouselPrimitive.Nav>
           <CarouselPrimitive.Prev>
-            <ArrowLeft className="h-6 w-6" strokeWidth={1.5} />
+            <CarouselPrimitive.PrevIcon />
           </CarouselPrimitive.Prev>
           <CarouselPrimitive.Next>
-            <ArrowRight className="h-6 w-6" strokeWidth={1.5} />
+            <CarouselPrimitive.NextIcon />
           </CarouselPrimitive.Next>
         </CarouselPrimitive.Nav>
       </CarouselPrimitive.Controls>
@@ -194,24 +174,21 @@ Use the composable primitives to build custom carousel layouts:
 
 \`\`\`tsx
 import * as CarouselPrimitive from '@/components/carousel/primitives';
-import { ArrowLeft, ArrowRight } from 'lucide-react';
 
 <CarouselPrimitive.Root>
   <CarouselPrimitive.Viewport>
     <CarouselPrimitive.Content>
-      <CarouselPrimitive.Item>
-        {/* Your content */}
-      </CarouselPrimitive.Item>
+      <CarouselPrimitive.Item>{/* Your content */}</CarouselPrimitive.Item>
     </CarouselPrimitive.Content>
   </CarouselPrimitive.Viewport>
   <CarouselPrimitive.Controls>
     <CarouselPrimitive.Scrollbar />
     <CarouselPrimitive.Nav>
       <CarouselPrimitive.Prev>
-        <ArrowLeft />
+        <CarouselPrimitive.PrevIcon />
       </CarouselPrimitive.Prev>
       <CarouselPrimitive.Next>
-        <ArrowRight />
+        <CarouselPrimitive.NextIcon />
       </CarouselPrimitive.Next>
     </CarouselPrimitive.Nav>
   </CarouselPrimitive.Controls>
diff --git a/src/components/category-card/category-card.tsx b/src/components/category-card/category-card.tsx
index 37a0675..b51263d 100644
--- a/src/components/category-card/category-card.tsx
+++ b/src/components/category-card/category-card.tsx
@@ -38,17 +38,12 @@ export interface CategoryCardProps extends CategoryCardContent {
  *
  * ```css
  * :root {
- *   --category-card-focus: var(--brand);
- *   --category-card-light-offset: var(--background);
- *   --category-card-light-text: var(--foreground);
- *   --category-card-light-icon: var(--foreground);
- *   --category-card-light-background: var(--contrast-100);
- *   --category-card-dark-offset: var(--foreground);
- *   --category-card-dark-text: var(--background);
- *   --category-card-dark-icon: var(--background);
- *   --category-card-dark-background: var(--contrast-500);
- *   --category-card-font-family: var(--font-family-body);
- *   --category-card-border-radius: 1rem;
+ *   --category-card-radius: 1rem;
+ *   --category-card-font: var(--font-body);
+ *   --category-card-text-light: var(--background);
+ *   --category-card-text-dark:  var(--foreground);
+ *   --category-card-icon-light: var(--background);
+ *   --category-card-icon-dark:  var(--foreground);
  * }
  * ```
  */
diff --git a/src/components/category-card/primitives/category-card-fallback.tsx b/src/components/category-card/primitives/category-card-fallback.tsx
index 4ce00f5..c1c78fe 100644
--- a/src/components/category-card/primitives/category-card-fallback.tsx
+++ b/src/components/category-card/primitives/category-card-fallback.tsx
@@ -8,9 +8,7 @@ export function CategoryCardFallback({ className, children, ...props }: Category
   return (
     <div
       className={cn(
-        'break-words p-4 text-4xl font-bold leading-none tracking-tight transition-transform duration-500 ease-out [color:color-mix(in_oklab,var(--foreground)_30%,transparent)]',
-        // Group hover state
-        'group-hover/category-card:scale-105',
+        'max-w-[80%] break-words pl-4 pt-4 text-4xl font-bold leading-none tracking-tight transition-transform duration-500 ease-out [color:var(--text-disabled)] group-hover/category-card:scale-105',
         className,
       )}
       data-slot="category-card-fallback"
diff --git a/src/components/category-card/primitives/category-card-icon.tsx b/src/components/category-card/primitives/category-card-icon.tsx
index 01d5ff2..13c4693 100644
--- a/src/components/category-card/primitives/category-card-icon.tsx
+++ b/src/components/category-card/primitives/category-card-icon.tsx
@@ -13,20 +13,20 @@ export interface CategoryCardIconProps {
 }
 
 export function CategoryCardIcon({ asChild = false, className, children }: CategoryCardIconProps) {
-  const baseClassName = cn(
-    'absolute right-5 top-5 z-10 size-6 text-[var(--category-card-light-icon,var(--foreground))] transition-transform duration-700 ease-out',
+  const iconStyles = cn(
+    'absolute right-5 top-5 z-10 size-6 transition-transform duration-700 ease-out',
     // Group hover state
     'group-hover/category-card:-translate-y-1.5 group-hover/category-card:translate-x-1.5',
     // Icon color: light
-    'group-data-[icon-color=light]/category-card:text-[var(--category-card-light-icon,var(--background))]',
+    'group-data-[icon-color=light]/category-card:text-[--category-card-icon-light,var(--background)]',
     // Icon color: dark
-    'group-data-[icon-color=dark]/category-card:text-[var(--category-card-dark-icon,var(--foreground))]',
+    'group-data-[icon-color=dark]/category-card:text-[--category-card-icon-dark,var(--foreground)]',
     className,
   );
 
   if (asChild) {
     return (
-      <Slot className={baseClassName} data-slot="category-card-icon">
+      <Slot className={iconStyles} data-slot="category-card-icon">
         {children}
       </Slot>
     );
@@ -35,7 +35,7 @@ export function CategoryCardIcon({ asChild = false, className, children }: Categ
   return (
     <ArrowUpRight
       absoluteStrokeWidth
-      className={baseClassName}
+      className={iconStyles}
       data-slot="category-card-icon"
       strokeWidth={1.5}
     />
diff --git a/src/components/category-card/primitives/category-card-image.tsx b/src/components/category-card/primitives/category-card-image.tsx
index f1e8d13..a11ac17 100644
--- a/src/components/category-card/primitives/category-card-image.tsx
+++ b/src/components/category-card/primitives/category-card-image.tsx
@@ -20,7 +20,7 @@ export function CategoryCardImage({
   return (
     <Component
       className={cn(
-        'h-full w-full scale-100 select-none bg-[var(--category-card-light-background,var(--contrast-100))] object-cover transition-transform duration-500 ease-out',
+        'h-full w-full scale-100 select-none bg-[--fill-pending] object-cover transition-transform duration-500 ease-out',
         // Group hover state
         'group-hover/category-card:scale-110',
         className,
diff --git a/src/components/category-card/primitives/category-card-link.tsx b/src/components/category-card/primitives/category-card-link.tsx
index 49a4f7b..cff6d3c 100644
--- a/src/components/category-card/primitives/category-card-link.tsx
+++ b/src/components/category-card/primitives/category-card-link.tsx
@@ -15,9 +15,7 @@ export function CategoryCardLink({ asChild = false, className, ...props }: Categ
   return (
     <Component
       className={cn(
-        'absolute inset-0 rounded-[var(--category-card-border-radius,1rem)]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-[var(--category-card-focus,var(--brand))]',
+        'focus-primary absolute inset-0 rounded-[var(--category-card-radius,1rem)]',
         className,
       )}
       data-slot="category-card-link"
diff --git a/src/components/category-card/primitives/category-card-root.tsx b/src/components/category-card/primitives/category-card-root.tsx
index b08dc92..5eb4ca6 100644
--- a/src/components/category-card/primitives/category-card-root.tsx
+++ b/src/components/category-card/primitives/category-card-root.tsx
@@ -32,7 +32,7 @@ export function CategoryCardRoot<T extends ElementType = 'article'>({
   return (
     <CategoryCardRootElement
       className={cn(
-        'group/category-card relative flex w-full max-w-md cursor-pointer flex-col rounded-[var(--category-card-border-radius,1rem)] font-[var(--category-card-font-family,var(--font-family-body))] @container',
+        'group/category-card relative flex w-full max-w-md cursor-pointer flex-col rounded-[var(--category-card-radius,1rem)] @container [font-family:var(--category-card-font,var(--font-body))]',
         // Text size gap variants
         'data-[text-size=small]:gap-2',
         'data-[text-size=medium]:gap-3',
diff --git a/src/components/category-card/primitives/category-card-thumbnail.tsx b/src/components/category-card/primitives/category-card-thumbnail.tsx
index 2c5c9ae..e6605b1 100644
--- a/src/components/category-card/primitives/category-card-thumbnail.tsx
+++ b/src/components/category-card/primitives/category-card-thumbnail.tsx
@@ -12,9 +12,7 @@ export function CategoryCardThumbnail({
   return (
     <div
       className={cn(
-        'relative overflow-hidden rounded-[inherit] bg-[var(--category-card-light-background,var(--contrast-100))]',
-        // Group focus-visible state
-        'group-focus-visible/category-card:outline-2 group-focus-visible/category-card:outline-offset-4 group-focus-visible/category-card:outline-[var(--category-card-focus,var(--brand))]',
+        'focus-primary relative overflow-hidden rounded-[inherit] bg-[--fill-pending]',
         // Aspect ratio variants
         'group-data-[aspect-ratio=1/1]/category-card:aspect-square',
         'group-data-[aspect-ratio=3/4]/category-card:aspect-[3/4]',
diff --git a/src/components/category-card/primitives/category-card-title.tsx b/src/components/category-card/primitives/category-card-title.tsx
index 6d92a27..8955645 100644
--- a/src/components/category-card/primitives/category-card-title.tsx
+++ b/src/components/category-card/primitives/category-card-title.tsx
@@ -8,23 +8,19 @@ export function CategoryCardTitle({ children, className, ...props }: CategoryCar
   return (
     <h3
       className={cn(
-        'font-semibold leading-tight',
+        'font-semibold',
         // Text size: small
-        'group-data-[text-size=small]/category-card:text-lg group-data-[text-size=small]/category-card:tracking-normal',
-        'group-data-[text-size=small]/category-card:@xs:text-xl',
+        'group-data-[text-size=small]/category-card:text-lg group-data-[text-size=small]/category-card:@xs:text-xl',
         // Text size: medium
-        'group-data-[text-size=medium]/category-card:text-xl group-data-[text-size=medium]/category-card:tracking-normal',
-        'group-data-[text-size=medium]/category-card:@xs:text-2xl',
+        'group-data-[text-size=medium]/category-card:text-xl group-data-[text-size=medium]/category-card:@xs:text-2xl',
         // Text size: large
-        'group-data-[text-size=large]/category-card:text-2xl group-data-[text-size=large]/category-card:tracking-tight',
-        'group-data-[text-size=large]/category-card:@xs:text-3xl',
+        'group-data-[text-size=large]/category-card:text-2xl group-data-[text-size=large]/category-card:@xs:text-3xl',
         // Text size: x-large
-        'group-data-[text-size=x-large]/category-card:text-3xl group-data-[text-size=x-large]/category-card:tracking-tight',
-        'group-data-[text-size=x-large]/category-card:@xs:text-4xl',
+        'group-data-[text-size=x-large]/category-card:text-3xl group-data-[text-size=x-large]/category-card:@xs:text-4xl',
         // Text color: light
-        'group-data-[text-color=light]/category-card:text-[var(--category-card-light-text,var(--background))]',
+        'group-data-[text-color=light]/category-card:text-[--category-card-text-light,var(--background)]',
         // Text color: dark
-        'group-data-[text-color=dark]/category-card:text-[var(--category-card-dark-text,var(--foreground))]',
+        'group-data-[text-color=dark]/category-card:text-[--category-card-text-dark,var(--foreground)]',
         className,
       )}
       data-slot="category-card-title"
diff --git a/src/components/category-card/storybook/category-card.stories.tsx b/src/components/category-card/storybook/category-card.stories.tsx
index 4201fd6..a0a94a7 100644
--- a/src/components/category-card/storybook/category-card.stories.tsx
+++ b/src/components/category-card/storybook/category-card.stories.tsx
@@ -19,17 +19,12 @@ A card component for displaying product categories with an image, title, and lin
 
 \`\`\`css
 :root {
-  --category-card-focus: var(--brand);
-  --category-card-light-offset: var(--background);
-  --category-card-light-text: var(--foreground);
-  --category-card-light-icon: var(--foreground);
-  --category-card-light-background: var(--contrast-100);
-  --category-card-dark-offset: var(--foreground);
-  --category-card-dark-text: var(--background);
-  --category-card-dark-icon: var(--background);
-  --category-card-dark-background: var(--contrast-500);
-  --category-card-font-family: var(--font-family-body);
-  --category-card-border-radius: 1rem;
+  --category-card-radius:     1rem;
+  --category-card-font:       var(--font-body);
+  --category-card-text-light: var(--background);
+  --category-card-text-dark:  var(--foreground);
+  --category-card-icon-light: var(--background);
+  --category-card-icon-dark:  var(--foreground);
 }
 \`\`\`
 
diff --git a/src/components/checkbox-group/storybook/checkbox-group.stories.tsx b/src/components/checkbox-group/storybook/checkbox-group.stories.tsx
index ca3a02f..3547006 100644
--- a/src/components/checkbox-group/storybook/checkbox-group.stories.tsx
+++ b/src/components/checkbox-group/storybook/checkbox-group.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import type { ComponentType } from 'react';
 import { useState } from 'react';
 
 import { CheckboxGroup, type CheckboxGroupProps } from '@/components/checkbox-group/checkbox-group';
@@ -24,73 +23,17 @@ A checkbox group component for selecting multiple options from a set of choices.
 
 ## CSS Variables
 
-The CheckboxGroup uses the Checkbox component internally, which supports theming through CSS variables:
+The CheckboxGroup uses the Checkbox component internally. See Checkbox for theming variables:
 
 \`\`\`css
 :root {
-  --checkbox-focus: var(--brand);
-  --checkbox-light-label: var(--foreground);
-  --checkbox-light-error: var(--error);
-  --checkbox-light-unchecked-border: var(--contrast-200);
-  --checkbox-light-unchecked-border-hover: var(--contrast-300);
-  --checkbox-light-unchecked-background: var(--background);
-  --checkbox-light-unchecked-icon: var(--foreground);
-  --checkbox-light-checked-border: var(--foreground);
-  --checkbox-light-checked-border-hover: var(--foreground);
-  --checkbox-light-checked-background: var(--foreground);
-  --checkbox-light-checked-icon: var(--background);
-  --checkbox-light-disabled-border: var(--contrast-200);
-  --checkbox-light-disabled-background: var(--contrast-100);
-  --checkbox-light-disabled-icon: var(--contrast-300);
+  --checkbox-fill-unchecked: var(--form-fill-unchecked);
+  --checkbox-fill-checked: var(--form-fill-checked);
+  --checkbox-fill-disabled: var(--form-fill-disabled);
+  --checkbox-text-unchecked: var(--form-text-unchecked);
+  --checkbox-text-checked: var(--form-text-checked);
+  --checkbox-text-disabled: var(--form-text-disabled);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`CheckboxGroup\` component provides a controlled API with an \`options\` array:
-
-\`\`\`tsx
-import { CheckboxGroup } from '@/components/checkbox-group';
-import { useState } from 'react';
-
-const options = [
-  { value: 'email', label: 'Email notifications', id: 'notify-email' },
-  { value: 'sms', label: 'SMS notifications', id: 'notify-sms' },
-  { value: 'push', label: 'Push notifications', id: 'notify-push' },
-];
-
-function MyComponent() {
-  const [selected, setSelected] = useState<string[]>(['email']);
-
-  return (
-    <CheckboxGroup
-      options={options}
-      value={selected}
-      onValueChange={setSelected}
-    />
-  );
-}
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components:
-
-\`\`\`tsx
-import * as CheckboxGroup from '@/components/checkbox-group';
-
-<CheckboxGroup.Root>
-  <CheckboxGroup.FieldItem>
-    <CheckboxGroup.Checkbox id="email" value="email" checked={selected.includes('email')} />
-    <CheckboxGroup.Label htmlFor="email">Email notifications</CheckboxGroup.Label>
-  </CheckboxGroup.FieldItem>
-  <CheckboxGroup.FieldItem>
-    <CheckboxGroup.Checkbox id="sms" value="sms" checked={selected.includes('sms')} />
-    <CheckboxGroup.Label htmlFor="sms">SMS notifications</CheckboxGroup.Label>
-  </CheckboxGroup.FieldItem>
-</CheckboxGroup.Root>
 \`\`\`
         `,
       },
@@ -99,30 +42,50 @@ import * as CheckboxGroup from '@/components/checkbox-group';
   tags: ['autodocs'],
   argTypes: {
     options: {
+      control: false,
       description:
-        'Array of options with value, label, id, optional disabled flag, and optional icon',
+        'Array of options with `value`, `label`, `id`, optional `disabled`, and optional `icon`',
     },
     value: {
+      control: false,
       description: 'Array of selected option values (controlled)',
     },
     onValueChange: {
+      control: false,
       description: 'Callback when the selected values change',
     },
   },
-  decorators: [
-    (Story: ComponentType) => (
-      <div className="flex items-center justify-center p-8">
-        <Story />
-      </div>
-    ),
-  ],
 };
 
 export default meta;
 type Story = StoryObj<CheckboxGroupProps>;
 
-// Default example
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A controlled checkbox group allowing multiple selections.',
+      },
+      source: {
+        code: `
+const [selected, setSelected] = useState<string[]>(['brushes']);
+
+const options = [
+  { value: 'brushes', label: 'Brushes & Scrubbers', id: 'cat-brushes' },
+  { value: 'sponges', label: 'Sponges & Cloths', id: 'cat-sponges' },
+  { value: 'bottles', label: 'Bottles & Dispensers', id: 'cat-bottles' },
+  { value: 'towels', label: 'Towels & Linens', id: 'cat-towels' },
+];
+
+<CheckboxGroup
+  options={options}
+  value={selected}
+  onValueChange={setSelected}
+/>
+        `,
+      },
+    },
+  },
   render: () => {
     const [selected, setSelected] = useState<string[]>(['brushes']);
 
@@ -130,8 +93,31 @@ export const Default: Story = {
   },
 };
 
-// Disabled items
 export const DisabledItems: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Individual options can be disabled using the `disabled` property.',
+      },
+      source: {
+        code: `
+const [selected, setSelected] = useState<string[]>(['email']);
+
+const options = [
+  { value: 'email', label: 'Email notifications', id: 'notify-email' },
+  { value: 'sms', label: 'SMS notifications', id: 'notify-sms' },
+  { value: 'push', label: 'Push notifications (Coming Soon)', id: 'notify-push', disabled: true },
+];
+
+<CheckboxGroup
+  options={options}
+  value={selected}
+  onValueChange={setSelected}
+/>
+        `,
+      },
+    },
+  },
   render: () => {
     const [selected, setSelected] = useState<string[]>(['email']);
 
@@ -150,17 +136,61 @@ export const DisabledItems: Story = {
   },
 };
 
-// Controlled example
-export const Controlled: Story = {
-  render: () => {
-    const [selected, setSelected] = useState<string[]>(['brushes', 'sponges']);
+export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the primitive components for full control over the structure.
+
+| Primitive                          | Description                              |
+|------------------------------------|------------------------------------------|
+| \`CheckboxGroupPrimitive.Root\`       | Grid container for the checkboxes.       |
+| \`CheckboxGroupPrimitive.FieldItem\`  | Horizontal field wrapper for each item.  |
+| \`CheckboxGroupPrimitive.Checkbox\`   | The checkbox input (wraps Checkbox).     |
+| \`CheckboxGroupPrimitive.Label\`      | Label for each checkbox option.          |
+        `,
+      },
+      source: {
+        code: `
+import * as CheckboxGroupPrimitive from '@/components/checkbox-group/primitives';
 
-    return <CheckboxGroup onValueChange={setSelected} options={categoryOptions} value={selected} />;
-  },
+const [selected, setSelected] = useState<string[]>(['email']);
+
+const handleChange = (value: string, checked: boolean) => {
+  setSelected((prev) =>
+    checked ? [...prev, value] : prev.filter((v) => v !== value)
+  );
 };
 
-// Composable anatomy example
-export const ComposableAnatomy: Story = {
+<CheckboxGroupPrimitive.Root>
+  <CheckboxGroupPrimitive.FieldItem>
+    <CheckboxGroupPrimitive.Checkbox
+      id="email-notif"
+      value="email"
+      checked={selected.includes('email')}
+      onCheckedChange={(checked) => handleChange('email', Boolean(checked))}
+    />
+    <CheckboxGroupPrimitive.Label htmlFor="email-notif">
+      Email notifications
+    </CheckboxGroupPrimitive.Label>
+  </CheckboxGroupPrimitive.FieldItem>
+  <CheckboxGroupPrimitive.FieldItem>
+    <CheckboxGroupPrimitive.Checkbox
+      id="sms-notif"
+      value="sms"
+      checked={selected.includes('sms')}
+      onCheckedChange={(checked) => handleChange('sms', Boolean(checked))}
+    />
+    <CheckboxGroupPrimitive.Label htmlFor="sms-notif">
+      SMS notifications
+    </CheckboxGroupPrimitive.Label>
+  </CheckboxGroupPrimitive.FieldItem>
+</CheckboxGroupPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => {
     const [selected, setSelected] = useState<string[]>(['email']);
 
@@ -192,17 +222,6 @@ export const ComposableAnatomy: Story = {
             SMS notifications
           </CheckboxGroupPrimitive.Label>
         </CheckboxGroupPrimitive.FieldItem>
-        <CheckboxGroupPrimitive.FieldItem>
-          <CheckboxGroupPrimitive.Checkbox
-            checked={selected.includes('push')}
-            id="push-notif"
-            onCheckedChange={(checked) => handleChange('push', Boolean(checked))}
-            value="push"
-          />
-          <CheckboxGroupPrimitive.Label htmlFor="push-notif">
-            Push notifications
-          </CheckboxGroupPrimitive.Label>
-        </CheckboxGroupPrimitive.FieldItem>
       </CheckboxGroupPrimitive.Root>
     );
   },
diff --git a/src/components/checkbox/checkbox.tsx b/src/components/checkbox/checkbox.tsx
index 1b46d81..adc09ba 100644
--- a/src/components/checkbox/checkbox.tsx
+++ b/src/components/checkbox/checkbox.tsx
@@ -16,23 +16,14 @@ export type CheckboxProps = ComponentProps<typeof CheckboxPrimitive.Root> & {
  * with their default values:
  *
  * ```css
- *  :root {
- *    --checkbox-focus: var(--brand);
- *    --checkbox-light-label: var(--foreground);
- *    --checkbox-light-error: var(--error);
- *    --checkbox-light-unchecked-border: var(--contrast-200);
- *    --checkbox-light-unchecked-border-hover: var(--contrast-300);
- *    --checkbox-light-unchecked-background: var(--background);
- *    --checkbox-light-unchecked-icon: var(--foreground);
- *    --checkbox-light-checked-border: var(--foreground);
- *    --checkbox-light-checked-border-hover: var(--foreground);
- *    --checkbox-light-checked-background: var(--foreground);
- *    --checkbox-light-checked-icon: var(--background);
- *    --checkbox-light-disabled-border: var(--contrast-200);
- *    --checkbox-light-disabled-background: var(--contrast-100);
- *    --checkbox-light-disabled-icon: var(--contrast-300);
- *    --checkbox-font-family: var(--font-family-body);
- *  }
+ * :root {
+ *   --checkbox-fill-unchecked: var(--form-fill-unchecked);
+ *   --checkbox-fill-checked: var(--form-fill-checked);
+ *   --checkbox-fill-disabled: var(--form-fill-disabled);
+ *   --checkbox-text-unchecked: var(--form-text-unchecked);
+ *   --checkbox-text-checked: var(--form-text-checked);
+ *   --checkbox-text-disabled: var(--form-text-disabled);
+ * }
  * ```
  */
 export function Checkbox({ className, icon, ...props }: CheckboxProps) {
diff --git a/src/components/checkbox/primitives/checkbox-icon.tsx b/src/components/checkbox/primitives/checkbox-icon.tsx
index dc9bf88..d8a0482 100644
--- a/src/components/checkbox/primitives/checkbox-icon.tsx
+++ b/src/components/checkbox/primitives/checkbox-icon.tsx
@@ -13,9 +13,11 @@ export interface CheckboxIconProps {
 }
 
 export function CheckboxIcon({ asChild = false, className, children }: CheckboxIconProps) {
+  const iconStyles = cn('size-4', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-4', className)} data-slot="checkbox-icon">
+      <Slot className={iconStyles} data-slot="checkbox-icon">
         {children}
       </Slot>
     );
@@ -24,7 +26,7 @@ export function CheckboxIcon({ asChild = false, className, children }: CheckboxI
   return (
     <Check
       absoluteStrokeWidth
-      className={cn('size-4', className)}
+      className={iconStyles}
       color="currentColor"
       data-slot="checkbox-icon"
     />
diff --git a/src/components/checkbox/primitives/checkbox-root.tsx b/src/components/checkbox/primitives/checkbox-root.tsx
index a3a1a1b..8cd6255 100644
--- a/src/components/checkbox/primitives/checkbox-root.tsx
+++ b/src/components/checkbox/primitives/checkbox-root.tsx
@@ -11,21 +11,19 @@ export function CheckboxRoot({ children, className, ...props }: CheckboxRootProp
   return (
     <CheckboxPrimitive.Root
       className={cn(
-        'peer flex size-5 items-center justify-center rounded-md border transition-colors duration-150',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--checkbox-focus,var(--brand))]',
+        'focus-primary peer flex size-5 items-center justify-center rounded-md border transition-colors duration-150',
         // Disabled state
-        'disabled:cursor-not-allowed disabled:border-[var(--checkbox-light-disabled-border,var(--contrast-200))] disabled:bg-[var(--checkbox-light-disabled-background,var(--contrast-100))] disabled:text-[var(--checkbox-light-disabled-icon,var(--contrast-300))]',
+        'disabled:cursor-not-allowed disabled:border-[--border] disabled:bg-[--checkbox-fill-disabled,var(--form-fill-disabled)] disabled:text-[--checkbox-text-disabled,var(--form-text-disabled)]',
         // Enabled + Checked state
-        'enabled:data-[state=checked]:border-[var(--checkbox-light-checked-border,var(--foreground))] enabled:data-[state=checked]:bg-[var(--checkbox-light-checked-background,var(--foreground))] enabled:data-[state=checked]:text-[var(--checkbox-light-checked-text,var(--background))]',
+        'enabled:data-[state=checked]:border-[--border-focus-secondary] enabled:data-[state=checked]:bg-[--checkbox-fill-checked,var(--form-fill-checked)] enabled:data-[state=checked]:text-[--checkbox-text-checked,var(--form-text-checked)]',
         // Enabled + Unchecked state
-        'enabled:data-[state=unchecked]:border-[var(--checkbox-light-unchecked-border,var(--contrast-200))] enabled:data-[state=unchecked]:bg-[var(--checkbox-light-unchecked-background,var(--background))] enabled:data-[state=unchecked]:text-[var(--checkbox-light-unchecked-text,var(--foreground))]',
+        'enabled:data-[state=unchecked]:border-[--border] enabled:data-[state=unchecked]:bg-[--checkbox-fill-unchecked,var(--form-fill-unchecked)] enabled:data-[state=unchecked]:text-[--checkbox-text-unchecked-text,var(--form-text-unchecked)]',
         // Enabled + Checked + Hover state
-        'enabled:data-[state=checked]:hover:border-[var(--checkbox-light-checked-border-hover,var(--foreground))]',
+        'enabled:data-[state=checked]:hover:border-[--border-checked]',
         // Enabled + Unchecked + Hover state
-        'enabled:data-[state=unchecked]:hover:border-[var(--checkbox-light-unchecked-border-hover,var(--contrast-300))]',
+        'enabled:data-[state=unchecked]:hover:border-[--border-hover]',
         // Aria-invalid state
-        'aria-invalid:border-[var(--checkbox-light-error,var(--error))]',
+        'aria-invalid:border-[--border-error]',
         className,
       )}
       data-slot="checkbox-root"
diff --git a/src/components/checkbox/storybook/checkbox.stories.tsx b/src/components/checkbox/storybook/checkbox.stories.tsx
index b1df2ba..ccdb801 100644
--- a/src/components/checkbox/storybook/checkbox.stories.tsx
+++ b/src/components/checkbox/storybook/checkbox.stories.tsx
@@ -1,6 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Check } from 'lucide-react';
-import { type ComponentType, useState } from 'react';
+import { useState } from 'react';
 
 import { Checkbox, type CheckboxProps } from '@/components/checkbox';
 import * as CheckboxPrimitive from '@/components/checkbox/primitives';
@@ -21,76 +20,13 @@ A checkbox component built on Radix UI for accessible, customizable binary selec
 
 \`\`\`css
 :root {
-  --checkbox-focus: var(--brand);
-  --checkbox-light-label: var(--foreground);
-  --checkbox-light-error: var(--error);
-  --checkbox-light-unchecked-border: var(--contrast-200);
-  --checkbox-light-unchecked-border-hover: var(--contrast-300);
-  --checkbox-light-unchecked-background: var(--background);
-  --checkbox-light-unchecked-icon: var(--foreground);
-  --checkbox-light-checked-border: var(--foreground);
-  --checkbox-light-checked-border-hover: var(--foreground);
-  --checkbox-light-checked-background: var(--foreground);
-  --checkbox-light-checked-icon: var(--background);
-  --checkbox-light-disabled-border: var(--contrast-200);
-  --checkbox-light-disabled-background: var(--contrast-100);
-  --checkbox-light-disabled-icon: var(--contrast-300);
-  --checkbox-font-family: var(--font-family-body);
-
-  /* Unchecked state */
-  --checkbox-light-unchecked-border: var(--contrast-200);
-  --checkbox-light-unchecked-border-hover: var(--contrast-300);
-  --checkbox-light-unchecked-background: var(--background);
-  --checkbox-light-unchecked-icon: var(--foreground);
-
-  /* Checked state */
-  --checkbox-light-checked-border: var(--foreground);
-  --checkbox-light-checked-border-hover: var(--foreground);
-  --checkbox-light-checked-background: var(--foreground);
-  --checkbox-light-checked-icon: var(--background);
-
-  /* Disabled state */
-  --checkbox-light-disabled-border: var(--contrast-200);
-  --checkbox-light-disabled-background: var(--contrast-100);
-  --checkbox-light-disabled-icon: var(--contrast-300);
-
-  /* Error state */
-  --checkbox-light-error: var(--error);
+  --checkbox-fill-unchecked: var(--form-fill-unchecked);
+  --checkbox-fill-checked: var(--form-fill-checked);
+  --checkbox-fill-disabled: var(--form-fill-disabled);
+  --checkbox-text-unchecked: var(--form-text-unchecked);
+  --checkbox-text-checked: var(--form-text-checked);
+  --checkbox-text-disabled: var(--form-text-disabled);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Checkbox\` component provides a simple API. Use with \`Field.Item\` and \`Label\` for accessibility:
-
-\`\`\`tsx
-import { Checkbox } from '@/components/checkbox';
-import * as Field from '@/components/field';
-import { Label } from '@/components/label';
-
-<Field.Item orientation="horizontal">
-  <Checkbox id="terms" name="terms" />
-  <Label htmlFor="terms">I agree to the terms</Label>
-</Field.Item>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Checkbox from '@/components/checkbox';
-import { Check } from 'lucide-react';
-
-<Checkbox.Root id="my-checkbox">
-  <Checkbox.Indicator>
-    <Checkbox.Icon>
-      <Check />
-    </Checkbox.Icon>
-  </Checkbox.Indicator>
-</Checkbox.Root>
 \`\`\`
         `,
       },
@@ -118,32 +54,43 @@ import { Check } from 'lucide-react';
       control: 'text',
       description: 'The name of the checkbox for form submission',
     },
+    icon: {
+      control: false,
+      description: 'Custom icon configuration with `asChild` support',
+    },
     onCheckedChange: {
       control: false,
       description: 'Callback when the checked state changes',
     },
   },
-  decorators: [
-    (Story: ComponentType) => (
-      <div className="flex items-center gap-4 bg-background p-8">
-        <Story />
-      </div>
-    ),
-  ],
 };
 
 export default meta;
 type Story = StoryObj<CheckboxProps>;
 
-// Default checkbox
 export const Default: Story = {
   args: {
     defaultChecked: false,
   },
 };
 
-// With label (common use case)
 export const WithLabel: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use with `Field.Item` and `Label` for accessible labeling. Set `orientation="horizontal"` for inline layout.',
+      },
+      source: {
+        code: `
+<Field.Item orientation="horizontal">
+  <Checkbox id="terms" name="terms" />
+  <Label htmlFor="terms">I agree to the terms and conditions</Label>
+</Field.Item>
+        `,
+      },
+    },
+  },
   render: () => (
     <Field.Item orientation="horizontal">
       <Checkbox id="terms" name="terms" />
@@ -152,17 +99,44 @@ export const WithLabel: Story = {
   ),
 };
 
-// Disabled state
 export const Disabled: Story = {
   args: {
     disabled: true,
     defaultChecked: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'The `disabled` prop prevents interaction and applies reduced opacity styling.',
+      },
+    },
+  },
 };
 
-// Controlled example
 export const Controlled: Story = {
-  render: function ControlledCheckbox() {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `checked` and `onCheckedChange` for controlled state management.',
+      },
+      source: {
+        code: `
+const [checked, setChecked] = useState(false);
+
+<Field.Item orientation="horizontal">
+  <Checkbox
+    id="newsletter"
+    name="newsletter"
+    checked={checked}
+    onCheckedChange={(value) => setChecked(value === true)}
+  />
+  <Label htmlFor="newsletter">Subscribe to newsletter</Label>
+</Field.Item>
+        `,
+      },
+    },
+  },
+  render: () => {
     const [checked, setChecked] = useState(false);
 
     return (
@@ -179,13 +153,38 @@ export const Controlled: Story = {
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the primitive components for full control over the structure.
+
+| Primitive                    | Description                                    |
+|------------------------------|------------------------------------------------|
+| \`CheckboxPrimitive.Root\`      | The checkbox root with all state styling.      |
+| \`CheckboxPrimitive.Indicator\` | Container that shows when checked.             |
+| \`CheckboxPrimitive.Icon\`      | Check icon with \`asChild\` support.           |
+        `,
+      },
+      source: {
+        code: `
+import * as CheckboxPrimitive from '@/components/checkbox/primitives';
+
+<CheckboxPrimitive.Root id="custom-checkbox">
+  <CheckboxPrimitive.Indicator>
+    <CheckboxPrimitive.Icon />
+  </CheckboxPrimitive.Indicator>
+</CheckboxPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <Field.Item orientation="horizontal">
-      <CheckboxPrimitive.Root defaultChecked={false} id="custom-checkbox">
+      <CheckboxPrimitive.Root id="custom-checkbox">
         <CheckboxPrimitive.Indicator>
-          <Check absoluteStrokeWidth className="h-4 w-4" color="currentColor" />
+          <CheckboxPrimitive.Icon />
         </CheckboxPrimitive.Indicator>
       </CheckboxPrimitive.Root>
       <Label htmlFor="custom-checkbox">Custom checkbox</Label>
diff --git a/src/components/chip/chip.tsx b/src/components/chip/chip.tsx
index e05dc5a..22062d4 100644
--- a/src/components/chip/chip.tsx
+++ b/src/components/chip/chip.tsx
@@ -16,11 +16,9 @@ export interface ChipProps extends ComponentProps<'button'> {
  *
  * ```css
  * :root {
- *   --chip-focus: var(--foreground);
- *   --chip-font-family: var(--font-family-body);
- *   --chip-background: var(--contrast-100);
- *   --chip-background-hover: var(--contrast-200);
- *   --chip-text: var(--foreground);
+ *   --chip-fill: var(--contrast-100);
+ *   --chip-text: var(--text-primary);
+ *   --chip-font: var(--font-body);
  * }
  * ```
  */
diff --git a/src/components/chip/primitives/chip-button.tsx b/src/components/chip/primitives/chip-button.tsx
index a1a7f0f..324e201 100644
--- a/src/components/chip/primitives/chip-button.tsx
+++ b/src/components/chip/primitives/chip-button.tsx
@@ -1,27 +1,20 @@
-import type { ComponentProps, ReactNode } from 'react';
+import type { ComponentProps } from 'react';
 
-import { cn } from '@/lib';
+import { Button } from '@/components/button';
 
-export interface ChipButtonProps extends ComponentProps<'button'> {
-  children?: ReactNode;
-}
+export type ChipButtonProps = ComponentProps<typeof Button>;
 
 export function ChipButton({ className, children, ...props }: ChipButtonProps) {
   return (
-    <button
-      className={cn(
-        'flex size-5 items-center justify-center rounded-full',
-        // Hover state
-        'hover:bg-[var(--chip-background-hover,var(--contrast-200))]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--chip-focus,var(--foreground))]',
-        className,
-      )}
+    <Button
+      className={className}
       data-slot="chip-button"
-      type="button"
+      shape="circle"
+      size="2x-small"
+      variant="ghost"
       {...props}
     >
       {children}
-    </button>
+    </Button>
   );
 }
diff --git a/src/components/chip/primitives/chip-icon.tsx b/src/components/chip/primitives/chip-icon.tsx
index 92047d3..31c74a7 100644
--- a/src/components/chip/primitives/chip-icon.tsx
+++ b/src/components/chip/primitives/chip-icon.tsx
@@ -13,13 +13,15 @@ export interface ChipIconProps {
 }
 
 export function ChipIcon({ asChild = false, className, children }: ChipIconProps) {
+  const iconStyles = cn('size-3', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-3', className)} data-slot="chip-icon">
+      <Slot className={iconStyles} data-slot="chip-icon">
         {children}
       </Slot>
     );
   }
 
-  return <X className={cn('size-3', className)} data-slot="chip-icon" />;
+  return <X className={iconStyles} data-slot="chip-icon" />;
 }
diff --git a/src/components/chip/primitives/chip-root.tsx b/src/components/chip/primitives/chip-root.tsx
index 9c68eb4..a8f8523 100644
--- a/src/components/chip/primitives/chip-root.tsx
+++ b/src/components/chip/primitives/chip-root.tsx
@@ -8,7 +8,7 @@ export function ChipRoot({ children, className, ...props }: ChipRootProps) {
   return (
     <span
       className={cn(
-        'flex h-9 items-center gap-1.5 rounded-lg bg-[var(--chip-background,var(--contrast-100))] py-2 pe-2 ps-3 text-sm font-semibold leading-5 text-[var(--chip-text,var(--foreground))] [font-family:var(--chip-font-family,var(--font-family-body))]',
+        'flex h-9 items-center gap-1.5 rounded-lg bg-[--chip-fill,var(--contrast-100)] py-2 pe-2 ps-3 text-sm font-semibold text-[--chip-text,var(--text-primary)] [font-family:var(--chip-font,var(--font-body))]',
         className,
       )}
       data-slot="chip-root"
diff --git a/src/components/chip/storybook/chip.stories.tsx b/src/components/chip/storybook/chip.stories.tsx
index bb653c2..721f208 100644
--- a/src/components/chip/storybook/chip.stories.tsx
+++ b/src/components/chip/storybook/chip.stories.tsx
@@ -1,6 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Tag } from 'lucide-react';
-import { useState } from 'react';
 
 import { Chip, type ChipProps } from '@/components/chip';
 import * as ChipPrimitive from '@/components/chip/primitives';
@@ -19,49 +17,10 @@ A dismissible chip component for displaying selected filters, tags, or removable
 
 \`\`\`css
 :root {
-  --chip-focus: var(--foreground);
-  --chip-font-family: var(--font-family-body);
-  --chip-background: var(--contrast-100);
-  --chip-background-hover: var(--contrast-200);
-  --chip-text: var(--foreground);
+  --chip-fill: var(--contrast-100);
+  --chip-text: var(--text-primary);
+  --chip-font: var(--font-body);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Chip\` component provides a dismissible chip with a remove button:
-
-\`\`\`tsx
-import { Chip } from '@/components/chip';
-
-<Chip onClick={handleRemove} removeLabel="Remove filter">
-  Electronics
-</Chip>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Chip from '@/components/chip';
-
-<Chip.Root>
-  Electronics
-  <Chip.Button title="Remove" onClick={handleRemove}>
-    <Chip.Icon />
-  </Chip.Button>
-</Chip.Root>
-\`\`\`
-
-The \`Chip.Icon\` supports \`asChild\` for custom icons:
-
-\`\`\`tsx
-<Chip.Icon asChild>
-  <MyCustomIcon />
-</Chip.Icon>
 \`\`\`
         `,
       },
@@ -75,22 +34,14 @@ The \`Chip.Icon\` supports \`asChild\` for custom icons:
     },
     removeLabel: {
       control: 'text',
-      description: 'Accessible label for remove button',
-    },
-    name: {
-      control: 'text',
-      description: 'Input name for form integration',
-    },
-    value: {
-      control: 'text',
-      description: 'Input value for form integration',
-    },
-    onClick: {
-      description: 'Handler for remove button click',
+      description: 'Accessible label for the remove button',
     },
     icon: {
       control: false,
-      description: 'Custom icon configuration with asChild support',
+      description: 'Custom icon configuration with `asChild` support',
+    },
+    onClick: {
+      description: 'Handler called when the remove button is clicked',
     },
   },
   args: {
@@ -102,59 +53,66 @@ The \`Chip.Icon\` supports \`asChild\` for custom icons:
 export default meta;
 type Story = StoryObj<ChipProps>;
 
-const noop = () => {
-  // no-op for storybook
-};
-
-// Default chip
 export const Default: Story = {
   args: {
     children: 'Electronics',
-    onClick: noop,
+    onClick: () => console.log('Removed'),
   },
 };
 
-// With custom icon
-export const WithIcon: Story = {
-  args: {
-    children: 'Tagged',
-    onClick: noop,
-    icon: {
-      asChild: true,
-      children: <Tag className="size-3" />,
+export const MultipleChips: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      <Chip onClick={() => console.log('Removed')} removeLabel="Remove Electronics">
+        Electronics
+      </Chip>
+      <Chip onClick={() => console.log('Removed')} removeLabel="Remove Under $50">
+        Under $50
+      </Chip>
+      <Chip onClick={() => console.log('Removed')} removeLabel="Remove In Stock">
+        In Stock
+      </Chip>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Chips are commonly used to display active filters that can be removed.',
+      },
     },
   },
 };
 
-// Interactive filter chips
-export const Interactive: Story = {
-  render: () => {
-    const [filters, setFilters] = useState(['Electronics', 'Under $50', 'In Stock']);
-
-    const removeFilter = (index: number) => {
-      setFilters(filters.filter((_, i) => i !== index));
-    };
-
-    return (
-      <div className="flex flex-wrap gap-2">
-        {filters.map((filter, index) => (
-          <Chip key={filter} onClick={() => removeFilter(index)} removeLabel={`Remove ${filter}`}>
-            {filter}
-          </Chip>
-        ))}
-      </div>
-    );
-  },
-};
-
-// Composable anatomy example
+/**
+ * Use the composable primitives to build custom chip layouts.
+ */
 export const ComposableAnatomy: Story = {
   render: () => (
     <ChipPrimitive.Root>
       Custom Chip
-      <ChipPrimitive.Button onClick={noop} title="Remove">
+      <ChipPrimitive.Button onClick={() => console.log('Removed')} title="Remove">
         <ChipPrimitive.Icon />
       </ChipPrimitive.Button>
     </ChipPrimitive.Root>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the composable primitives to build custom chip layouts:
+
+\`\`\`tsx
+import * as ChipPrimitive from '@/components/chip/primitives';
+
+<ChipPrimitive.Root>
+  Chip Label
+  <ChipPrimitive.Button onClick={handleRemove} title="Remove">
+    <ChipPrimitive.Icon />
+  </ChipPrimitive.Button>
+</ChipPrimitive.Root>
+\`\`\`
+        `,
+      },
+    },
+  },
 };
diff --git a/src/components/compare-card/compare-card.tsx b/src/components/compare-card/compare-card.tsx
index 9e84329..08be243 100644
--- a/src/components/compare-card/compare-card.tsx
+++ b/src/components/compare-card/compare-card.tsx
@@ -1,17 +1,11 @@
-import { Fragment } from 'react';
-
 import * as CompareCardPrimitive from '@/components/compare-card';
+import type { CompareCardNode } from '@/components/compare-card';
 import type { ProductCardProps } from '@/components/product-card';
 
 export interface CompareCardProps {
   className?: string;
   productCard: Omit<ProductCardProps, 'className'>;
-  description?: string;
-  descriptionLabel?: string;
-  emptyDescriptionLabel?: string;
-  specs?: Array<{ name: string; value: string }>;
-  specsLabel?: string;
-  emptySpecsLabel?: string;
+  nodes?: CompareCardNode[];
 }
 
 /**
@@ -20,65 +14,21 @@ export interface CompareCardProps {
  *
  * ```css
  * :root {
- *   --compare-card-divider: var(--contrast-100);
- *   --compare-card-label: var(--foreground);
- *   --compare-card-description: var(--contrast-400);
- *   --compare-card-field: var(--foreground);
- *   --compare-card-font-family-brand: var(--font-family-body);
- *   --compare-card-font-family-secondary: var(--font-family-body);
+ *   --compare-card-font: var(--font-body);
+ *   --compare-card-text-primary: var(--text-primary);
+ *   --compare-card-text-secondary: var(--text-secondary);
  * }
  * ```
  */
-export function CompareCard({
-  className,
-  productCard,
-  description,
-  descriptionLabel = 'Description',
-  emptyDescriptionLabel = 'There is no description available.',
-  specs,
-  specsLabel = 'Other details',
-  emptySpecsLabel = 'There are no other details.',
-}: CompareCardProps) {
+export function CompareCard({ className, productCard, nodes = [] }: CompareCardProps) {
   return (
     <CompareCardPrimitive.Root className={className}>
       <CompareCardPrimitive.Product>
         <CompareCardPrimitive.ProductCard {...productCard} />
       </CompareCardPrimitive.Product>
-      <CompareCardPrimitive.Description>
-        <CompareCardPrimitive.DescriptionLabel>
-          {descriptionLabel}
-        </CompareCardPrimitive.DescriptionLabel>
-        {description != null ? (
-          <CompareCardPrimitive.Reveal>
-            <CompareCardPrimitive.DescriptionContent>
-              {description}
-            </CompareCardPrimitive.DescriptionContent>
-          </CompareCardPrimitive.Reveal>
-        ) : (
-          <CompareCardPrimitive.DescriptionEmpty>
-            {emptyDescriptionLabel}
-          </CompareCardPrimitive.DescriptionEmpty>
-        )}
-      </CompareCardPrimitive.Description>
-      <CompareCardPrimitive.Specs>
-        <CompareCardPrimitive.SpecsLabel>{specsLabel}</CompareCardPrimitive.SpecsLabel>
-        {specs ? (
-          <CompareCardPrimitive.Reveal>
-            <CompareCardPrimitive.SpecsList>
-              {specs.map(({ name, value }, index) => (
-                <Fragment key={index}>
-                  <CompareCardPrimitive.SpecsTerm>{name}: </CompareCardPrimitive.SpecsTerm>
-                  <CompareCardPrimitive.SpecsDefinition>
-                    {value}
-                  </CompareCardPrimitive.SpecsDefinition>
-                </Fragment>
-              ))}
-            </CompareCardPrimitive.SpecsList>
-          </CompareCardPrimitive.Reveal>
-        ) : (
-          <CompareCardPrimitive.SpecsEmpty>{emptySpecsLabel}</CompareCardPrimitive.SpecsEmpty>
-        )}
-      </CompareCardPrimitive.Specs>
+      {nodes.map((node, index) => (
+        <CompareCardPrimitive.Node compareCardNode={node} key={index} />
+      ))}
     </CompareCardPrimitive.Root>
   );
 }
diff --git a/src/components/compare-card/primitives.ts b/src/components/compare-card/primitives.ts
index 5b76b2f..407636c 100644
--- a/src/components/compare-card/primitives.ts
+++ b/src/components/compare-card/primitives.ts
@@ -15,46 +15,39 @@ export {
   type CompareCardSkeletonProps as SkeletonProps,
 } from '@/components/compare-card/primitives/compare-card-skeleton';
 export {
-  CompareCardDescription as Description,
-  type CompareCardDescriptionProps as DescriptionProps,
-} from '@/components/compare-card/primitives/compare-card-description';
+  CompareCardSection as Section,
+  type CompareCardSectionProps as SectionProps,
+} from '@/components/compare-card/primitives/compare-card-section';
 export {
-  CompareCardDescriptionLabel as DescriptionLabel,
-  type CompareCardDescriptionLabelProps as DescriptionLabelProps,
-} from '@/components/compare-card/primitives/compare-card-description-label';
+  CompareCardLabel as Label,
+  type CompareCardLabelProps as LabelProps,
+} from '@/components/compare-card/primitives/compare-card-label';
 export {
-  CompareCardDescriptionContent as DescriptionContent,
-  type CompareCardDescriptionContentProps as DescriptionContentProps,
-} from '@/components/compare-card/primitives/compare-card-description-content';
+  CompareCardContent as Content,
+  type CompareCardContentProps as ContentProps,
+} from '@/components/compare-card/primitives/compare-card-content';
 export {
-  CompareCardDescriptionEmpty as DescriptionEmpty,
-  type CompareCardDescriptionEmptyProps as DescriptionEmptyProps,
-} from '@/components/compare-card/primitives/compare-card-description-empty';
+  CompareCardEmpty as Empty,
+  type CompareCardEmptyProps as EmptyProps,
+} from '@/components/compare-card/primitives/compare-card-empty';
 export {
-  CompareCardSpecs as Specs,
-  type CompareCardSpecsProps as SpecsProps,
-} from '@/components/compare-card/primitives/compare-card-specs';
+  CompareCardList as List,
+  type CompareCardListProps as ListProps,
+} from '@/components/compare-card/primitives/compare-card-list';
 export {
-  CompareCardSpecsLabel as SpecsLabel,
-  type CompareCardSpecsLabelProps as SpecsLabelProps,
-} from '@/components/compare-card/primitives/compare-card-specs-label';
+  CompareCardTerm as Term,
+  type CompareCardTermProps as TermProps,
+} from '@/components/compare-card/primitives/compare-card-term';
 export {
-  CompareCardSpecsList as SpecsList,
-  type CompareCardSpecsListProps as SpecsListProps,
-} from '@/components/compare-card/primitives/compare-card-specs-list';
-export {
-  CompareCardSpecsTerm as SpecsTerm,
-  type CompareCardSpecsTermProps as SpecsTermProps,
-} from '@/components/compare-card/primitives/compare-card-specs-term';
-export {
-  CompareCardSpecsDefinition as SpecsDefinition,
-  type CompareCardSpecsDefinitionProps as SpecsDefinitionProps,
-} from '@/components/compare-card/primitives/compare-card-specs-definition';
-export {
-  CompareCardSpecsEmpty as SpecsEmpty,
-  type CompareCardSpecsEmptyProps as SpecsEmptyProps,
-} from '@/components/compare-card/primitives/compare-card-specs-empty';
+  CompareCardDefinition as Definition,
+  type CompareCardDefinitionProps as DefinitionProps,
+} from '@/components/compare-card/primitives/compare-card-definition';
 export {
   CompareCardReveal as Reveal,
   type CompareCardRevealProps as RevealProps,
 } from '@/components/compare-card/primitives/compare-card-reveal';
+export {
+  CompareCardNode as Node,
+  type CompareCardNodeProps as NodeProps,
+  type CompareCardNode,
+} from '@/components/compare-card/primitives/compare-card-node';
diff --git a/src/components/compare-card/primitives/compare-card-description-content.tsx b/src/components/compare-card/primitives/compare-card-content.tsx
similarity index 53%
rename from src/components/compare-card/primitives/compare-card-description-content.tsx
rename to src/components/compare-card/primitives/compare-card-content.tsx
index 23feba0..5969215 100644
--- a/src/components/compare-card/primitives/compare-card-description-content.tsx
+++ b/src/components/compare-card/primitives/compare-card-content.tsx
@@ -2,20 +2,16 @@ import type { ComponentProps } from 'react';
 
 import { cn } from '@/lib';
 
-export type CompareCardDescriptionContentProps = ComponentProps<'div'>;
+export type CompareCardContentProps = ComponentProps<'div'>;
 
-export function CompareCardDescriptionContent({
-  children,
-  className,
-  ...props
-}: CompareCardDescriptionContentProps) {
+export function CompareCardContent({ children, className, ...props }: CompareCardContentProps) {
   return (
     <div
       className={cn(
         'prose prose-sm [&>div>*:first-child]:mt-0 [&>div>*:last-child]:mb-0',
         className,
       )}
-      data-slot="compare-card-description-content"
+      data-slot="compare-card-content"
       {...props}
     >
       {children}
diff --git a/src/components/compare-card/primitives/compare-card-definition.tsx b/src/components/compare-card/primitives/compare-card-definition.tsx
new file mode 100644
index 0000000..560a429
--- /dev/null
+++ b/src/components/compare-card/primitives/compare-card-definition.tsx
@@ -0,0 +1,17 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type CompareCardDefinitionProps = ComponentProps<'dd'>;
+
+export function CompareCardDefinition({
+  children,
+  className,
+  ...props
+}: CompareCardDefinitionProps) {
+  return (
+    <dd className={cn(className)} data-slot="compare-card-definition" {...props}>
+      {children}
+    </dd>
+  );
+}
diff --git a/src/components/compare-card/primitives/compare-card-description-empty.tsx b/src/components/compare-card/primitives/compare-card-description-empty.tsx
deleted file mode 100644
index 64dcab4..0000000
--- a/src/components/compare-card/primitives/compare-card-description-empty.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type CompareCardDescriptionEmptyProps = ComponentProps<'p'>;
-
-export function CompareCardDescriptionEmpty({
-  children,
-  className,
-  ...props
-}: CompareCardDescriptionEmptyProps) {
-  return (
-    <p
-      className={cn(
-        'text-sm text-[var(--compare-card-description,var(--contrast-400))]',
-        className,
-      )}
-      data-slot="compare-card-description-empty"
-      {...props}
-    >
-      {children}
-    </p>
-  );
-}
diff --git a/src/components/compare-card/primitives/compare-card-description-label.tsx b/src/components/compare-card/primitives/compare-card-description-label.tsx
deleted file mode 100644
index 9159216..0000000
--- a/src/components/compare-card/primitives/compare-card-description-label.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type CompareCardDescriptionLabelProps = ComponentProps<'p'>;
-
-export function CompareCardDescriptionLabel({
-  children,
-  className,
-  ...props
-}: CompareCardDescriptionLabelProps) {
-  return (
-    <p
-      className={cn(
-        'font-[family-name:var(--compare-card-font-family-secondary,var(--font-family-body))] text-xs font-normal uppercase text-[var(--compare-card-label,var(--foreground))]',
-        className,
-      )}
-      data-slot="compare-card-description-label"
-      {...props}
-    >
-      {children}
-    </p>
-  );
-}
diff --git a/src/components/compare-card/primitives/compare-card-description.tsx b/src/components/compare-card/primitives/compare-card-description.tsx
deleted file mode 100644
index 007cf58..0000000
--- a/src/components/compare-card/primitives/compare-card-description.tsx
+++ /dev/null
@@ -1,21 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type CompareCardDescriptionProps = ComponentProps<'div'>;
-
-export function CompareCardDescription({
-  className,
-  children,
-  ...props
-}: CompareCardDescriptionProps) {
-  return (
-    <div
-      className={cn('space-y-4 py-4', className)}
-      data-slot="compare-card-description"
-      {...props}
-    >
-      {children}
-    </div>
-  );
-}
diff --git a/src/components/compare-card/primitives/compare-card-empty.tsx b/src/components/compare-card/primitives/compare-card-empty.tsx
new file mode 100644
index 0000000..9b68723
--- /dev/null
+++ b/src/components/compare-card/primitives/compare-card-empty.tsx
@@ -0,0 +1,20 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type CompareCardEmptyProps = ComponentProps<'p'>;
+
+export function CompareCardEmpty({ children, className, ...props }: CompareCardEmptyProps) {
+  return (
+    <p
+      className={cn(
+        'text-sm text-[--compare-card-text-secondary,var(--text-secondary)]',
+        className,
+      )}
+      data-slot="compare-card-empty"
+      {...props}
+    >
+      {children}
+    </p>
+  );
+}
diff --git a/src/components/compare-card/primitives/compare-card-label.tsx b/src/components/compare-card/primitives/compare-card-label.tsx
new file mode 100644
index 0000000..7ed8d7f
--- /dev/null
+++ b/src/components/compare-card/primitives/compare-card-label.tsx
@@ -0,0 +1,20 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type CompareCardLabelProps = ComponentProps<'p'>;
+
+export function CompareCardLabel({ children, className, ...props }: CompareCardLabelProps) {
+  return (
+    <p
+      className={cn(
+        'text-xs font-semibold text-[--compare-card-text-secondary,var(--text-secondary)] [family-name:var(--compare-card-font,var(--font-body))]',
+        className,
+      )}
+      data-slot="compare-card-label"
+      {...props}
+    >
+      {children}
+    </p>
+  );
+}
diff --git a/src/components/compare-card/primitives/compare-card-list.tsx b/src/components/compare-card/primitives/compare-card-list.tsx
new file mode 100644
index 0000000..8ae6730
--- /dev/null
+++ b/src/components/compare-card/primitives/compare-card-list.tsx
@@ -0,0 +1,20 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type CompareCardListProps = ComponentProps<'dl'>;
+
+export function CompareCardList({ children, className, ...props }: CompareCardListProps) {
+  return (
+    <dl
+      className={cn(
+        'text-[--compare-card-text-primary,var(--text-primary)) grid grid-cols-2 gap-1 text-xs font-normal',
+        className,
+      )}
+      data-slot="compare-card-list"
+      {...props}
+    >
+      {children}
+    </dl>
+  );
+}
diff --git a/src/components/compare-card/primitives/compare-card-node.tsx b/src/components/compare-card/primitives/compare-card-node.tsx
new file mode 100644
index 0000000..78d2148
--- /dev/null
+++ b/src/components/compare-card/primitives/compare-card-node.tsx
@@ -0,0 +1,88 @@
+import { Fragment, type ReactNode } from 'react';
+
+import * as CompareCardPrimitive from '@/components/compare-card';
+
+export type CompareCardNode =
+  | {
+      type: 'content';
+      label: string;
+      content?: ReactNode;
+      emptyLabel?: string;
+      showReveal?: boolean;
+    }
+  | {
+      type: 'list';
+      label: string;
+      items?: Array<{ name: string; value: string }>;
+      emptyLabel?: string;
+      showReveal?: boolean;
+    };
+
+export interface CompareCardNodeProps {
+  compareCardNode: CompareCardNode;
+}
+
+export function CompareCardNode({ compareCardNode }: CompareCardNodeProps) {
+  function renderContent(node: Extract<CompareCardNode, { type: 'content' }>) {
+    const { content, emptyLabel, showReveal = true } = node;
+
+    if (content == null) {
+      if (emptyLabel == null) return null;
+
+      return <CompareCardPrimitive.Empty>{emptyLabel}</CompareCardPrimitive.Empty>;
+    }
+
+    const sectionContent = <CompareCardPrimitive.Content>{content}</CompareCardPrimitive.Content>;
+
+    if (!showReveal) return sectionContent;
+
+    return <CompareCardPrimitive.Reveal>{sectionContent}</CompareCardPrimitive.Reveal>;
+  }
+
+  function renderList(node: Extract<CompareCardNode, { type: 'list' }>) {
+    const { items, emptyLabel, showReveal = true } = node;
+    const hasItems = items != null && items.length > 0;
+
+    if (!hasItems) {
+      if (emptyLabel == null) return null;
+
+      return <CompareCardPrimitive.Empty>{emptyLabel}</CompareCardPrimitive.Empty>;
+    }
+
+    const sectionList = (
+      <CompareCardPrimitive.List>
+        {items.map(({ name, value }, idx) => (
+          <Fragment key={idx}>
+            <CompareCardPrimitive.Term>{name}: </CompareCardPrimitive.Term>
+            <CompareCardPrimitive.Definition>{value}</CompareCardPrimitive.Definition>
+          </Fragment>
+        ))}
+      </CompareCardPrimitive.List>
+    );
+
+    if (!showReveal) return sectionList;
+
+    return <CompareCardPrimitive.Reveal>{sectionList}</CompareCardPrimitive.Reveal>;
+  }
+
+  function renderNode(node: CompareCardNode) {
+    switch (node.type) {
+      case 'content':
+        return (
+          <CompareCardPrimitive.Section>
+            <CompareCardPrimitive.Label>{node.label}</CompareCardPrimitive.Label>
+            {renderContent(node)}
+          </CompareCardPrimitive.Section>
+        );
+      case 'list':
+        return (
+          <CompareCardPrimitive.Section>
+            <CompareCardPrimitive.Label>{node.label}</CompareCardPrimitive.Label>
+            {renderList(node)}
+          </CompareCardPrimitive.Section>
+        );
+    }
+  }
+
+  return renderNode(compareCardNode);
+}
diff --git a/src/components/compare-card/primitives/compare-card-product-card.tsx b/src/components/compare-card/primitives/compare-card-product-card.tsx
index f11b958..60a573f 100644
--- a/src/components/compare-card/primitives/compare-card-product-card.tsx
+++ b/src/components/compare-card/primitives/compare-card-product-card.tsx
@@ -1,10 +1,9 @@
 import type { ComponentProps } from 'react';
 
 import { ProductCard } from '@/components/product-card';
-import { cn } from '@/lib';
 
 export type CompareCardProductCardProps = ComponentProps<typeof ProductCard>;
 
 export function CompareCardProductCard({ className, ...props }: CompareCardProductCardProps) {
-  return <ProductCard className={cn(className)} data-slot="compare-card-product-card" {...props} />;
+  return <ProductCard className={className} data-slot="compare-card-product-card" {...props} />;
 }
diff --git a/src/components/compare-card/primitives/compare-card-reveal.tsx b/src/components/compare-card/primitives/compare-card-reveal.tsx
index 361e87c..0aef701 100644
--- a/src/components/compare-card/primitives/compare-card-reveal.tsx
+++ b/src/components/compare-card/primitives/compare-card-reveal.tsx
@@ -1,13 +1,12 @@
 import type { ComponentProps } from 'react';
 
 import { Reveal } from '@/components/reveal';
-import { cn } from '@/lib';
 
 export type CompareCardRevealProps = ComponentProps<typeof Reveal>;
 
 export function CompareCardReveal({ className, children, ...props }: CompareCardRevealProps) {
   return (
-    <Reveal className={cn(className)} data-slot="compare-card-reveal" {...props}>
+    <Reveal className={className} data-slot="compare-card-reveal" {...props}>
       {children}
     </Reveal>
   );
diff --git a/src/components/compare-card/primitives/compare-card-root.tsx b/src/components/compare-card/primitives/compare-card-root.tsx
index ceeb275..7b097a7 100644
--- a/src/components/compare-card/primitives/compare-card-root.tsx
+++ b/src/components/compare-card/primitives/compare-card-root.tsx
@@ -8,7 +8,7 @@ export function CompareCardRoot({ children, className, ...props }: CompareCardRo
   return (
     <div
       className={cn(
-        'w-full max-w-72 divide-y divide-[var(--compare-card-divider,var(--contrast-100))] font-[family-name:var(--compare-card-font-family-brand,var(--font-family-body))] font-normal @container',
+        'w-full max-w-72 divide-y divide-[--border-subtle] font-normal @container [font-family:var(--compare-card-font,var(--font-body))]',
         className,
       )}
       data-slot="compare-card-root"
diff --git a/src/components/compare-card/primitives/compare-card-section.tsx b/src/components/compare-card/primitives/compare-card-section.tsx
new file mode 100644
index 0000000..29a41ea
--- /dev/null
+++ b/src/components/compare-card/primitives/compare-card-section.tsx
@@ -0,0 +1,13 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type CompareCardSectionProps = ComponentProps<'div'>;
+
+export function CompareCardSection({ className, children, ...props }: CompareCardSectionProps) {
+  return (
+    <div className={cn('space-y-4 py-4', className)} data-slot="compare-card-section" {...props}>
+      {children}
+    </div>
+  );
+}
diff --git a/src/components/compare-card/primitives/compare-card-skeleton.tsx b/src/components/compare-card/primitives/compare-card-skeleton.tsx
index 51ce01b..771e676 100644
--- a/src/components/compare-card/primitives/compare-card-skeleton.tsx
+++ b/src/components/compare-card/primitives/compare-card-skeleton.tsx
@@ -9,10 +9,7 @@ export type CompareCardSkeletonProps = ComponentProps<'div'>;
 export function CompareCardSkeleton({ className, ...props }: CompareCardSkeletonProps) {
   return (
     <div
-      className={cn(
-        'w-full max-w-md divide-y divide-[var(--compare-card-divider,var(--contrast-100))] @container',
-        className,
-      )}
+      className={cn('w-full max-w-md divide-y divide-[--border-subtle] @container', className)}
       data-slot="compare-card-skeleton"
       {...props}
     >
diff --git a/src/components/compare-card/primitives/compare-card-specs-definition.tsx b/src/components/compare-card/primitives/compare-card-specs-definition.tsx
deleted file mode 100644
index 6dd9793..0000000
--- a/src/components/compare-card/primitives/compare-card-specs-definition.tsx
+++ /dev/null
@@ -1,17 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type CompareCardSpecsDefinitionProps = ComponentProps<'dd'>;
-
-export function CompareCardSpecsDefinition({
-  children,
-  className,
-  ...props
-}: CompareCardSpecsDefinitionProps) {
-  return (
-    <dd className={cn(className)} data-slot="compare-card-specs-definition" {...props}>
-      {children}
-    </dd>
-  );
-}
diff --git a/src/components/compare-card/primitives/compare-card-specs-empty.tsx b/src/components/compare-card/primitives/compare-card-specs-empty.tsx
deleted file mode 100644
index 3a74781..0000000
--- a/src/components/compare-card/primitives/compare-card-specs-empty.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type CompareCardSpecsEmptyProps = ComponentProps<'p'>;
-
-export function CompareCardSpecsEmpty({
-  children,
-  className,
-  ...props
-}: CompareCardSpecsEmptyProps) {
-  return (
-    <p
-      className={cn(
-        'text-sm text-[var(--compare-card-description,var(--contrast-400))]',
-        className,
-      )}
-      data-slot="compare-card-specs-empty"
-      {...props}
-    >
-      {children}
-    </p>
-  );
-}
diff --git a/src/components/compare-card/primitives/compare-card-specs-label.tsx b/src/components/compare-card/primitives/compare-card-specs-label.tsx
deleted file mode 100644
index 5c0c74d..0000000
--- a/src/components/compare-card/primitives/compare-card-specs-label.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type CompareCardSpecsLabelProps = ComponentProps<'p'>;
-
-export function CompareCardSpecsLabel({
-  children,
-  className,
-  ...props
-}: CompareCardSpecsLabelProps) {
-  return (
-    <p
-      className={cn(
-        'font-[family-name:var(--compare-card-font-family-secondary,var(--font-family-body))] text-xs font-normal uppercase text-[var(--compare-card-label,var(--foreground))]',
-        className,
-      )}
-      data-slot="compare-card-specs-label"
-      {...props}
-    >
-      {children}
-    </p>
-  );
-}
diff --git a/src/components/compare-card/primitives/compare-card-specs-list.tsx b/src/components/compare-card/primitives/compare-card-specs-list.tsx
deleted file mode 100644
index 5fbe97a..0000000
--- a/src/components/compare-card/primitives/compare-card-specs-list.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type CompareCardSpecsListProps = ComponentProps<'dl'>;
-
-export function CompareCardSpecsList({ children, className, ...props }: CompareCardSpecsListProps) {
-  return (
-    <dl
-      className={cn(
-        'grid grid-cols-2 gap-1 text-xs font-normal text-[var(--compare-card-field,var(--foreground))]',
-        className,
-      )}
-      data-slot="compare-card-specs-list"
-      {...props}
-    >
-      {children}
-    </dl>
-  );
-}
diff --git a/src/components/compare-card/primitives/compare-card-specs-term.tsx b/src/components/compare-card/primitives/compare-card-specs-term.tsx
deleted file mode 100644
index e76d637..0000000
--- a/src/components/compare-card/primitives/compare-card-specs-term.tsx
+++ /dev/null
@@ -1,13 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type CompareCardSpecsTermProps = ComponentProps<'dt'>;
-
-export function CompareCardSpecsTerm({ children, className, ...props }: CompareCardSpecsTermProps) {
-  return (
-    <dt className={cn('font-semibold', className)} data-slot="compare-card-specs-term" {...props}>
-      {children}
-    </dt>
-  );
-}
diff --git a/src/components/compare-card/primitives/compare-card-specs.tsx b/src/components/compare-card/primitives/compare-card-specs.tsx
deleted file mode 100644
index 91cd726..0000000
--- a/src/components/compare-card/primitives/compare-card-specs.tsx
+++ /dev/null
@@ -1,13 +0,0 @@
-import type { ComponentProps } from 'react';
-
-import { cn } from '@/lib';
-
-export type CompareCardSpecsProps = ComponentProps<'div'>;
-
-export function CompareCardSpecs({ className, children, ...props }: CompareCardSpecsProps) {
-  return (
-    <div className={cn('space-y-4 py-4', className)} data-slot="compare-card-specs" {...props}>
-      {children}
-    </div>
-  );
-}
diff --git a/src/components/compare-card/primitives/compare-card-term.tsx b/src/components/compare-card/primitives/compare-card-term.tsx
new file mode 100644
index 0000000..4fe6e75
--- /dev/null
+++ b/src/components/compare-card/primitives/compare-card-term.tsx
@@ -0,0 +1,13 @@
+import type { ComponentProps } from 'react';
+
+import { cn } from '@/lib';
+
+export type CompareCardTermProps = ComponentProps<'dt'>;
+
+export function CompareCardTerm({ children, className, ...props }: CompareCardTermProps) {
+  return (
+    <dt className={cn('font-semibold', className)} data-slot="compare-card-term" {...props}>
+      {children}
+    </dt>
+  );
+}
diff --git a/src/components/compare-card/storybook/compare-card.stories.tsx b/src/components/compare-card/storybook/compare-card.stories.tsx
index 4a8cd39..45f8c84 100644
--- a/src/components/compare-card/storybook/compare-card.stories.tsx
+++ b/src/components/compare-card/storybook/compare-card.stories.tsx
@@ -12,26 +12,21 @@ const meta: Meta<typeof CompareCard> = {
     docs: {
       description: {
         component: `
-A product comparison card that extends the ProductCard with additional description and specification sections. Ideal for side-by-side product comparisons.
+A product comparison card that extends the ProductCard with additional content nodes. Ideal for side-by-side product comparisons.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --compare-card-divider: var(--contrast-100);
-  --compare-card-label: var(--foreground);
-  --compare-card-description: var(--contrast-400);
-  --compare-card-field: var(--foreground);
-  --compare-card-font-family-brand: var(--font-family-body);
-  --compare-card-font-family-secondary: var(--font-family-body);
+  --compare-card-font: var(--font-body);
+  --compare-card-text-primary: var(--text-primary);
+  --compare-card-text-secondary: var(--text-secondary);
 }
 \`\`\`
 
 ## Usage
 
-### High-Level Component
-
-The \`CompareCard\` component wraps a ProductCard with description and specs sections:
+The \`CompareCard\` component wraps a ProductCard with configurable content nodes:
 
 \`\`\`tsx
 import { CompareCard } from '@/components/compare-card';
@@ -44,50 +39,70 @@ import { CompareCard } from '@/components/compare-card';
       subtitle: 'Category',
       link: { href: '/products/id', ariaLabel: 'View Product' },
       image: { src: '...', alt: '...' },
-      showRating: true,
-      rating: 4.5,
       price: { type: 'default', value: '$19.99' },
     },
-    cartAction: {
-      type: 'form',
-      action: (formData) => console.log('Add to cart:', formData.get('id')),
-      label: 'Add to Cart',
-    },
   }}
-  description="Product description text..."
-  specs={[
-    { name: 'Material', value: 'Bamboo' },
-    { name: 'Dimensions', value: '6" x 2"' },
+  nodes={[
+    {
+      type: 'content',
+      label: 'Description',
+      content: 'Product description text...',
+      emptyLabel: 'No description available.',
+    },
+    {
+      type: 'list',
+      label: 'Specifications',
+      items: [
+        { name: 'Material', value: 'Bamboo' },
+        { name: 'Dimensions', value: '6" x 2"' },
+      ],
+    },
   ]}
 />
 \`\`\`
 
-### Composable Anatomy
+## Node Types
+
+| Type | Description |
+|------|-------------|
+| \`content\` | Prose/rich text content with optional reveal animation |
+| \`list\` | Key-value definition list for specifications |
+
+## Node Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| \`type\` | \`'content' \\| 'list'\` | The type of node to render |
+| \`label\` | \`string\` | Section heading |
+| \`content\` | \`ReactNode\` | Content for \`content\` type nodes |
+| \`items\` | \`Array<{ name: string; value: string }>\` | Items for \`list\` type nodes |
+| \`emptyLabel\` | \`string\` | Message shown when content/items are empty |
+| \`showReveal\` | \`boolean\` | Whether to show reveal animation (default: \`true\`) |
+
+## Composable Anatomy
 
 For more control, use the primitive components directly:
 
 \`\`\`tsx
-import * as CompareCard from '@/components/compare-card';
+import * as CompareCard from '@/components/compare-card/primitives';
 
 <CompareCard.Root>
   <CompareCard.Product>
     <CompareCard.ProductCard product={...} />
   </CompareCard.Product>
-  <CompareCard.Description>
-    <CompareCard.DescriptionLabel>Description</CompareCard.DescriptionLabel>
-    <CompareCard.Reveal>
-      <CompareCard.DescriptionContent>...</CompareCard.DescriptionContent>
-    </CompareCard.Reveal>
-  </CompareCard.Description>
-  <CompareCard.Specs>
-    <CompareCard.SpecsLabel>Specifications</CompareCard.SpecsLabel>
+  <CompareCard.Section>
+    <CompareCard.Label>Description</CompareCard.Label>
     <CompareCard.Reveal>
-      <CompareCard.SpecsList>
-        <CompareCard.SpecsTerm>Material: </CompareCard.SpecsTerm>
-        <CompareCard.SpecsDefinition>Bamboo</CompareCard.SpecsDefinition>
-      </CompareCard.SpecsList>
+      <CompareCard.Content>...</CompareCard.Content>
     </CompareCard.Reveal>
-  </CompareCard.Specs>
+  </CompareCard.Section>
+  <CompareCard.Section>
+    <CompareCard.Label>Specifications</CompareCard.Label>
+    <CompareCard.List>
+      <CompareCard.Term>Material: </CompareCard.Term>
+      <CompareCard.Definition>Bamboo</CompareCard.Definition>
+    </CompareCard.List>
+  </CompareCard.Section>
 </CompareCard.Root>
 \`\`\`
         `,
@@ -98,32 +113,11 @@ import * as CompareCard from '@/components/compare-card';
   argTypes: {
     productCard: {
       control: false,
-      description:
-        'Props passed to the embedded ProductCard (product, cartAction, compareAction, aspectRatio)',
-    },
-    description: {
-      control: 'text',
-      description: 'Product description text',
-    },
-    descriptionLabel: {
-      control: 'text',
-      description: 'Label for the description section (default: "Description")',
-    },
-    emptyDescriptionLabel: {
-      control: 'text',
-      description: 'Message shown when no description is available',
+      description: 'Props passed to the embedded ProductCard',
     },
-    specs: {
+    nodes: {
       control: false,
-      description: 'Array of specification objects with name and value',
-    },
-    specsLabel: {
-      control: 'text',
-      description: 'Label for the specifications section (default: "Other details")',
-    },
-    emptySpecsLabel: {
-      control: 'text',
-      description: 'Message shown when no specs are available',
+      description: 'Array of content nodes to render below the product card',
     },
   },
   decorators: [
@@ -138,7 +132,6 @@ import * as CompareCard from '@/components/compare-card';
 export default meta;
 type Story = StoryObj<CompareCardProps>;
 
-// Default with description and specs
 export const Default: Story = {
   args: {
     productCard: {
@@ -159,18 +152,27 @@ export const Default: Story = {
         price: { type: 'default', value: '$8.99' },
       },
     },
-    description:
-      'A sturdy, eco-friendly scrub brush made from natural plant fibers and a sustainably sourced wooden handle. Perfect for pots, pans, and tough kitchen messes.',
-    specs: [
-      { name: 'Material', value: 'Natural plant fiber, beechwood' },
-      { name: 'Dimensions', value: '6" x 2.5"' },
-      { name: 'Care', value: 'Rinse and air dry' },
+    nodes: [
+      {
+        type: 'content',
+        label: 'Description',
+        content:
+          'A sturdy, eco-friendly scrub brush made from natural plant fibers and a sustainably sourced wooden handle. Perfect for pots, pans, and tough kitchen messes.',
+      },
+      {
+        type: 'list',
+        label: 'Other details',
+        items: [
+          { name: 'Material', value: 'Natural plant fiber, beechwood' },
+          { name: 'Dimensions', value: '6" x 2.5"' },
+          { name: 'Care', value: 'Rinse and air dry' },
+        ],
+      },
     ],
   },
 };
 
-// With cart action
-export const WithCartAction: Story = {
+export const MultipleNodes: Story = {
   args: {
     productCard: {
       product: {
@@ -189,24 +191,32 @@ export const WithCartAction: Story = {
         rating: 4.6,
         price: { type: 'default', value: '$14.50' },
       },
-      cartAction: {
-        type: 'form',
-        action: (formData) => {
-          console.log('Added to cart:', formData.get('id'));
-        },
-        label: 'Add to Cart',
-      },
     },
-    description:
-      'A sleek glass pump bottle with a brushed metal pump mechanism. Perfect for hand soap, dish soap, or lotion.',
-    specs: [
-      { name: 'Capacity', value: '16 oz' },
-      { name: 'Material', value: 'Recycled glass, stainless steel' },
+    nodes: [
+      {
+        type: 'content',
+        label: 'Description',
+        content:
+          'A sleek glass pump bottle with a brushed metal pump mechanism. Perfect for hand soap, dish soap, or lotion.',
+      },
+      {
+        type: 'list',
+        label: 'Specifications',
+        items: [
+          { name: 'Capacity', value: '16 oz' },
+          { name: 'Material', value: 'Recycled glass, stainless steel' },
+          { name: 'Dimensions', value: '7.5" x 3"' },
+        ],
+      },
+      {
+        type: 'content',
+        label: 'Care instructions',
+        content: 'Hand wash only. Do not microwave. Refill with your favorite soap or lotion.',
+      },
     ],
   },
 };
 
-// Empty states (no description or specs)
 export const EmptyStates: Story = {
   args: {
     productCard: {
@@ -227,10 +237,21 @@ export const EmptyStates: Story = {
         price: { type: 'default', value: '$6.49' },
       },
     },
+    nodes: [
+      {
+        type: 'content',
+        label: 'Description',
+        emptyLabel: 'There is no description available.',
+      },
+      {
+        type: 'list',
+        label: 'Other details',
+        emptyLabel: 'There are no other details.',
+      },
+    ],
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
   render: () => (
     <CompareCardPrimitive.Root>
@@ -254,37 +275,36 @@ export const ComposableAnatomy: Story = {
           }}
         />
       </CompareCardPrimitive.Product>
-      <CompareCardPrimitive.Description>
-        <CompareCardPrimitive.DescriptionLabel>Description</CompareCardPrimitive.DescriptionLabel>
+      <CompareCardPrimitive.Section>
+        <CompareCardPrimitive.Label>Description</CompareCardPrimitive.Label>
         <CompareCardPrimitive.Reveal>
-          <CompareCardPrimitive.DescriptionContent>
+          <CompareCardPrimitive.Content>
             A versatile cleaning brush with an ergonomic wooden handle and durable bristles. Great
             for dishes, vegetables, and general cleaning tasks.
-          </CompareCardPrimitive.DescriptionContent>
+          </CompareCardPrimitive.Content>
         </CompareCardPrimitive.Reveal>
-      </CompareCardPrimitive.Description>
-      <CompareCardPrimitive.Specs>
-        <CompareCardPrimitive.SpecsLabel>Specifications</CompareCardPrimitive.SpecsLabel>
+      </CompareCardPrimitive.Section>
+      <CompareCardPrimitive.Section>
+        <CompareCardPrimitive.Label>Specifications</CompareCardPrimitive.Label>
         <CompareCardPrimitive.Reveal>
-          <CompareCardPrimitive.SpecsList>
+          <CompareCardPrimitive.List>
             <Fragment>
-              <CompareCardPrimitive.SpecsTerm>Material: </CompareCardPrimitive.SpecsTerm>
-              <CompareCardPrimitive.SpecsDefinition>
+              <CompareCardPrimitive.Term>Material: </CompareCardPrimitive.Term>
+              <CompareCardPrimitive.Definition>
                 Beechwood, natural bristle
-              </CompareCardPrimitive.SpecsDefinition>
+              </CompareCardPrimitive.Definition>
             </Fragment>
             <Fragment>
-              <CompareCardPrimitive.SpecsTerm>Dimensions: </CompareCardPrimitive.SpecsTerm>
-              <CompareCardPrimitive.SpecsDefinition>7" x 2"</CompareCardPrimitive.SpecsDefinition>
+              <CompareCardPrimitive.Term>Dimensions: </CompareCardPrimitive.Term>
+              <CompareCardPrimitive.Definition>7" x 2"</CompareCardPrimitive.Definition>
             </Fragment>
-          </CompareCardPrimitive.SpecsList>
+          </CompareCardPrimitive.List>
         </CompareCardPrimitive.Reveal>
-      </CompareCardPrimitive.Specs>
+      </CompareCardPrimitive.Section>
     </CompareCardPrimitive.Root>
   ),
 };
 
-// Skeleton loading state
 export const Skeleton: Story = {
   render: () => (
     <CompareCardPrimitive.Root>
diff --git a/src/components/compare-drawer/compare-drawer.tsx b/src/components/compare-drawer/compare-drawer.tsx
index cc9cf10..9667039 100644
--- a/src/components/compare-drawer/compare-drawer.tsx
+++ b/src/components/compare-drawer/compare-drawer.tsx
@@ -44,21 +44,11 @@ export interface CompareDrawerProps {
  *
  * ```css
  * :root {
- *   --compare-drawer-background: var(--background);
- *   --compare-drawer-font-family: var(--font-family-body);
- *   --compare-drawer-card-focus: var(--brand);
- *   --compare-drawer-card-border: var(--contrast-100);
- *   --compare-drawer-card-background: var(--background);
- *   --compare-drawer-card-background-hover: var(--contrast-100);
- *   --compare-drawer-card-image-background: var(--contrast-100);
- *   --compare-drawer-empty-image-text: var(--brand-shadow);
- *   --compare-drawer-card-text: var(--foreground);
- *   --compare-drawer-dismiss-border: var(--contast-100);
- *   --compare-drawer-dismiss-border-hover: var(--contast-200);
- *   --compare-drawer-dismiss-background: var(--background);
- *   --compare-drawer-dismiss-background-hover: var(--contrast-100);
- *   --compare-drawer-dismiss-icon: var(--contrast-400);
- *   --compare-drawer-dismiss-icon-hover: var(--foreground);
+ *   --compare-drawer-fill-primary: var(--background);
+ *   --compare-drawer-fill-secondary: var(--contrast-100);
+ *   --compare-drawer-fill-hover: var(--contrast-100);
+ *   --compare-drawer-text-primary: var(--text-primary);
+ *   --compare-drawer-text-secondary: var(--text-secondary);
  * }
  * ```
  */
diff --git a/src/components/compare-drawer/primitives/compare-drawer-fallback.tsx b/src/components/compare-drawer/primitives/compare-drawer-fallback.tsx
index 2945c1a..ad4be9c 100644
--- a/src/components/compare-drawer/primitives/compare-drawer-fallback.tsx
+++ b/src/components/compare-drawer/primitives/compare-drawer-fallback.tsx
@@ -14,7 +14,7 @@ export function CompareDrawerFallback({
   return (
     <span
       className={cn(
-        'flex h-full w-full items-center justify-center break-all p-1 text-xs text-[var(--compare-drawer-empty-image-text,var(--brand-shadow))] opacity-20',
+        'flex h-full w-full items-center justify-center break-all p-1 text-xs text-[var(--compare-drawer-text-secondary,var(--text-secondary))]',
         className,
       )}
       data-slot="compare-drawer-fallback"
diff --git a/src/components/compare-drawer/primitives/compare-drawer-image.tsx b/src/components/compare-drawer/primitives/compare-drawer-image.tsx
index c6ad57d..8be5bcb 100644
--- a/src/components/compare-drawer/primitives/compare-drawer-image.tsx
+++ b/src/components/compare-drawer/primitives/compare-drawer-image.tsx
@@ -17,12 +17,7 @@ export function CompareDrawerImage({
 
   return (
     <Component
-      className={cn(
-        'size-full object-cover transition-transform duration-500 ease-out',
-        // Group hover state
-        'group-hover/compare-drawer-link:scale-110',
-        className,
-      )}
+      className={cn('size-full object-cover transition-transform duration-500 ease-out', className)}
       data-slot="compare-drawer-image"
       {...props}
     />
diff --git a/src/components/compare-drawer/primitives/compare-drawer-link.tsx b/src/components/compare-drawer/primitives/compare-drawer-link.tsx
index c66ad2b..5ed25cf 100644
--- a/src/components/compare-drawer/primitives/compare-drawer-link.tsx
+++ b/src/components/compare-drawer/primitives/compare-drawer-link.tsx
@@ -18,13 +18,7 @@ export function CompareDrawerLink({
   return (
     <Component
       className={cn(
-        'group/compare-drawer-link relative flex max-w-56 items-center overflow-hidden whitespace-nowrap rounded-xl border border-[var(--compare-drawer-link-border,var(--contrast-100))] bg-[var(--compare-drawer-card-background,var(--background))] font-semibold transition-all duration-150',
-        // Hover state
-        'hover:bg-[var(--compare-drawer-card-background-hover,var(--contrast-100))]',
-        // Focus state
-        'focus:outline-none',
-        // Focus-visible state
-        'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--compare-drawer-card-focus,var(--brand))]',
+        'focus-primary group/compare-drawer-link relative flex max-w-56 items-center overflow-hidden whitespace-nowrap rounded-xl border border-[--border-subtle] bg-[--compare-drawer-fill-primary,var(--background)] font-semibold transition-all duration-150 hover:bg-[--compare-drawer-fill-hover,var(--contrast-100)]',
         className,
       )}
       data-slot="compare-drawer-link"
diff --git a/src/components/compare-drawer/primitives/compare-drawer-remove.tsx b/src/components/compare-drawer/primitives/compare-drawer-remove.tsx
index b4c3e53..7bb4eed 100644
--- a/src/components/compare-drawer/primitives/compare-drawer-remove.tsx
+++ b/src/components/compare-drawer/primitives/compare-drawer-remove.tsx
@@ -1,27 +1,21 @@
 import type { ComponentProps } from 'react';
 
+import { Button } from '@/components/button';
 import { cn } from '@/lib';
 
-export type CompareDrawerRemoveProps = ComponentProps<'button'>;
+export type CompareDrawerRemoveProps = ComponentProps<typeof Button>;
 
 export function CompareDrawerRemove({ className, children, ...props }: CompareDrawerRemoveProps) {
   return (
-    <button
-      className={cn(
-        'absolute -right-2.5 -top-2.5 flex size-7 items-center justify-center rounded-full border border-[var(--compare-drawer-dismiss-border,var(--contrast-100))] bg-[var(--compare-drawer-dismiss-background,var(--background))] text-[var(--compare-drawer-dismiss-icon,var(--contrast-400))] transition-colors duration-150',
-        // Hover state
-        'hover:border-[var(--compare-drawer-dismiss-border-hover,var(--contrast-200))] hover:bg-[var(--compare-drawer-dismiss-background-hover,var(--contrast-100))] hover:text-[var(--compare-drawer-dismiss-icon-hover,var(--foreground))]',
-        // Focus state
-        'focus:outline-none',
-        // Focus-visible state
-        'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--compare-drawer-card-focus,var(--brand))]',
-        className,
-      )}
+    <Button
+      className={cn('absolute -right-2.5 -top-2.5', className)}
       data-slot="compare-drawer-remove"
-      type="button"
+      shape="circle"
+      size="x-small"
+      variant="outline"
       {...props}
     >
       {children}
-    </button>
+    </Button>
   );
 }
diff --git a/src/components/compare-drawer/primitives/compare-drawer-thumbnail.tsx b/src/components/compare-drawer/primitives/compare-drawer-thumbnail.tsx
index 1c4671f..e28550f 100644
--- a/src/components/compare-drawer/primitives/compare-drawer-thumbnail.tsx
+++ b/src/components/compare-drawer/primitives/compare-drawer-thumbnail.tsx
@@ -12,7 +12,7 @@ export function CompareDrawerThumbnail({
   return (
     <div
       className={cn(
-        'relative aspect-square w-12 shrink-0 bg-[var(--compare-drawer-card-image-background,var(--contrast-100))]',
+        'relative aspect-square w-12 shrink-0 bg-[--compare-drawer-fill-secondary,var(--contrast-100)]',
         className,
       )}
       data-slot="compare-drawer-thumbnail"
diff --git a/src/components/compare-drawer/primitives/compare-drawer-title.tsx b/src/components/compare-drawer/primitives/compare-drawer-title.tsx
index e19d258..3d254d8 100644
--- a/src/components/compare-drawer/primitives/compare-drawer-title.tsx
+++ b/src/components/compare-drawer/primitives/compare-drawer-title.tsx
@@ -8,7 +8,7 @@ export function CompareDrawerTitle({ children, className, ...props }: CompareDra
   return (
     <span
       className={cn(
-        'hidden truncate pl-3 pr-5 text-[var(--compare-drawer-card-text,var(--foreground))] @4xl:block',
+        'hidden truncate pl-3 pr-5 text-[--compare-drawer-text-primary,var(--text-primary)] @4xl:block',
         className,
       )}
       data-slot="compare-drawer-title"
diff --git a/src/components/compare-drawer/primitives/compare-drawer-viewport.tsx b/src/components/compare-drawer/primitives/compare-drawer-viewport.tsx
index 14b242a..2904435 100644
--- a/src/components/compare-drawer/primitives/compare-drawer-viewport.tsx
+++ b/src/components/compare-drawer/primitives/compare-drawer-viewport.tsx
@@ -12,7 +12,7 @@ export function CompareDrawerViewport({
   return (
     <div
       className={cn(
-        'sticky bottom-0 z-10 w-full border-t border-[var(--compare-drawer-card-border,var(--contrast-100))] bg-[var(--compare-drawer-background,var(--background))] px-3 py-4 @container @md:py-5 @xl:px-6 @5xl:px-10',
+        'sticky bottom-0 z-10 w-full border-t border-[--border-subtle] bg-[--compare-drawer-fill-primary,var(--background)] px-3 py-4 @container @md:py-5 @xl:px-6 @5xl:px-10',
         className,
       )}
       data-slot="compare-drawer-viewport"
diff --git a/src/components/compare-drawer/storybook/compare-drawer.stories.tsx b/src/components/compare-drawer/storybook/compare-drawer.stories.tsx
index f5ebc38..adf747c 100644
--- a/src/components/compare-drawer/storybook/compare-drawer.stories.tsx
+++ b/src/components/compare-drawer/storybook/compare-drawer.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { X } from 'lucide-react';
 import type { ComponentType } from 'react';
 import { useEffect, useRef, useState } from 'react';
 
@@ -50,10 +49,6 @@ const mockItems: CompareDrawerItem[] = [
   },
 ];
 
-function StoryWrapper({ children }: { children: React.ReactNode }) {
-  return <div className="relative flex min-h-[300px] flex-col">{children}</div>;
-}
-
 function CompareDrawerWrapper({ items: initialItems = [], ...props }: CompareDrawerProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const [container, setContainer] = useState<HTMLDivElement | null>(null);
@@ -108,124 +103,23 @@ A sticky drawer component for comparing products. Displays product thumbnails wi
 
 \`\`\`css
 :root {
-  --compare-drawer-background: var(--background);
-  --compare-drawer-font-family: var(--font-family-body);
-  --compare-drawer-card-focus: var(--brand);
-  --compare-drawer-card-border: var(--contrast-100);
-  --compare-drawer-card-background: var(--background);
-  --compare-drawer-card-background-hover: var(--contrast-100);
-  --compare-drawer-card-image-background: var(--contrast-100);
-  --compare-drawer-empty-image-text: var(--brand-shadow);
-  --compare-drawer-card-text: var(--foreground);
-  --compare-drawer-dismiss-border: var(--contast-100);
-  --compare-drawer-dismiss-border-hover: var(--contast-200);
-  --compare-drawer-dismiss-background: var(--background);
-  --compare-drawer-dismiss-background-hover: var(--contrast-100);
-  --compare-drawer-dismiss-icon: var(--contrast-400);
-  --compare-drawer-dismiss-icon-hover: var(--foreground);
+  --compare-drawer-fill-primary: var(--background);
+  --compare-drawer-fill-secondary: var(--contrast-100);
+  --compare-drawer-fill-hover: var(--contrast-100);
+  --compare-drawer-text-primary: var(--text-primary);
+  --compare-drawer-text-secondary: var(--text-secondary);
 }
 \`\`\`
 
-## Usage
-
-### High-Level Component
-
-The \`CompareDrawer\` component provides a data-driven API for product comparison:
-
-\`\`\`tsx
-import { CompareDrawer } from '@/components/compare-drawer';
-
-<CompareDrawer
-  items={[
-    {
-      id: '1',
-      title: 'Product Name',
-      image: { src: '/image.jpg', alt: 'Product' },
-      link: { href: '/products/1', ariaLabel: 'View Product' },
-    },
-  ]}
-  onRemove={(id) => handleRemove(id)}
-  submitHref="/compare"
-  submitLabel="Compare"
-/>
-\`\`\`
-
-### Custom Link Components with asChild
-
-Use the \`asChild\` prop to render your own link component (e.g., Next.js \`Link\`):
-
-\`\`\`tsx
-import Link from 'next/link';
-import { CompareDrawer } from '@/components/compare-drawer';
-
-<CompareDrawer
-  items={[
-    {
-      id: '1',
-      title: 'Product Name',
-      image: { src: '/image.jpg', alt: 'Product' },
-      link: {
-        href: '/products/1',
-        ariaLabel: 'View Product',
-        asChild: true,
-        children: (
-          <Link href="/products/1">
-            {/* Thumbnail and Title rendered by parent */}
-          </Link>
-        ),
-      },
-    },
-  ]}
-  onRemove={(id) => handleRemove(id)}
-/>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as CompareDrawer from '@/components/compare-drawer';
-
-<CompareDrawer.Root container={containerElement}>
-  <CompareDrawer.Viewport>
-    <CompareDrawer.Content>
-      <CompareDrawer.ItemList>
-        <CompareDrawer.Item>
-          <CompareDrawer.Link href="/products/1" aria-label="View Product">
-            <CompareDrawer.Thumbnail>
-              <CompareDrawer.Image src="/image.jpg" alt="Product" />
-            </CompareDrawer.Thumbnail>
-            <CompareDrawer.Title>Product Name</CompareDrawer.Title>
-          </CompareDrawer.Link>
-          <CompareDrawer.Remove aria-label="Remove Product">
-            <CompareDrawer.RemoveIcon />
-          </CompareDrawer.Remove>
-        </CompareDrawer.Item>
-      </CompareDrawer.ItemList>
-      <CompareDrawer.Submit href="/compare" variant="primary">
-        Compare <CompareDrawer.SubmitIcon />
-      </CompareDrawer.Submit>
-    </CompareDrawer.Content>
-  </CompareDrawer.Viewport>
-</CompareDrawer.Root>
-\`\`\`
-
-With custom link components:
+## Container Queries
 
-\`\`\`tsx
-import Link from 'next/link';
-import * as CompareDrawer from '@/components/compare-drawer';
+The component uses container queries to adapt its layout:
 
-<CompareDrawer.Link asChild>
-  <Link href="/products/1">
-    <CompareDrawer.Thumbnail>
-      <CompareDrawer.Image src="/image.jpg" alt="Product" />
-    </CompareDrawer.Thumbnail>
-    <CompareDrawer.Title>Product Name</CompareDrawer.Title>
-  </Link>
-</CompareDrawer.Link>
-\`\`\`
+| Element | Below @md | @md and above |
+|---------|-----------|---------------|
+| Layout | Column, full-width button | Row, medium button |
+| Title | Hidden | Visible (@4xl) |
+| Padding | px-3, py-4 | py-5 (@md), px-6 (@xl), px-10 (@5xl) |
         `,
       },
     },
@@ -238,32 +132,33 @@ import * as CompareDrawer from '@/components/compare-drawer';
     },
     removeLabel: {
       control: 'text',
-      description: 'Label for the remove item button (used in aria-label)',
-      table: {
-        defaultValue: { summary: 'Remove' },
-      },
+      description: 'Label for the remove button (used in aria-label)',
     },
     submitLabel: {
       control: 'text',
       description: 'Label for the submit button',
-      table: {
-        defaultValue: { summary: 'Compare' },
-      },
     },
     submitHref: {
       control: 'text',
       description: 'URL for the submit button link',
     },
     onRemove: {
-      action: 'onRemove',
       description: 'Callback fired when an item is removed, receives the item id',
     },
+    removeIcon: {
+      control: false,
+      description: 'Custom remove icon configuration with `asChild` support',
+    },
+    submitIcon: {
+      control: false,
+      description: 'Custom submit icon configuration with `asChild` support',
+    },
   },
   decorators: [
     (Story: ComponentType) => (
-      <StoryWrapper>
+      <div className="relative flex min-h-[300px] flex-col">
         <Story />
-      </StoryWrapper>
+      </div>
     ),
   ],
 };
@@ -272,9 +167,6 @@ export default meta;
 
 type Story = StoryObj<CompareDrawerProps>;
 
-/**
- * The default CompareDrawer displays product items with thumbnails, titles, and remove buttons.
- */
 export const Default: Story = {
   args: {
     items: mockItems,
@@ -285,9 +177,6 @@ export const Default: Story = {
   render: (args) => <CompareDrawerWrapper {...args} />,
 };
 
-/**
- * When items don't have images, a fallback displays the product initials.
- */
 export const WithoutImages: Story = {
   args: {
     items: [
@@ -313,93 +202,60 @@ export const WithoutImages: Story = {
     submitHref: '/compare',
   },
   render: (args) => <CompareDrawerWrapper {...args} />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'When items have no images, a fallback displays the product initials.',
+      },
+    },
+  },
 };
 
 /**
- * Use the primitive components directly for full customization control.
+ * Use the composable primitives to build custom compare drawer layouts.
  */
 export const ComposableAnatomy: Story = {
   render: () => {
     const containerRef = useRef<HTMLDivElement>(null);
     const [container, setContainer] = useState<HTMLDivElement | null>(null);
-    const [items, setItems] = useState(mockItems);
 
     useEffect(() => {
       setContainer(containerRef.current);
     }, []);
 
-    const handleRemove = (id: string) => {
-      setItems((prev) => prev.filter((item) => item.id !== id));
-    };
-
-    const handleReset = () => {
-      setItems(mockItems);
-    };
-
     return (
       <div className="relative flex min-h-[300px] flex-col" ref={containerRef}>
         <div className="flex-1 bg-contrast-100 p-8">
-          <p className="text-sm text-contrast-400">
-            Page content area - the compare drawer appears below.
-          </p>
-          {items.length === 0 && (
-            <Button className="mt-4" onClick={handleReset} size="small" variant="primary">
-              Reset Items
-            </Button>
-          )}
+          <p className="text-sm text-contrast-400">Page content area</p>
         </div>
-        {container && items.length > 0 && (
+        {container && (
           <CompareDrawerPrimitive.Root container={container}>
             <CompareDrawerPrimitive.Viewport>
               <CompareDrawerPrimitive.Content>
                 <CompareDrawerPrimitive.ItemList>
-                  {items.map((item) => (
-                    <CompareDrawerPrimitive.Item key={item.id}>
-                      <CompareDrawerPrimitive.Link
-                        aria-label={item.link.ariaLabel}
-                        href={item.link.href}
-                      >
-                        <CompareDrawerPrimitive.Thumbnail>
-                          {item.image != null ? (
-                            <CompareDrawerPrimitive.Image
-                              alt={item.image.alt}
-                              src={item.image.src}
-                            />
-                          ) : (
-                            <CompareDrawerPrimitive.Fallback>
-                              {item.title}
-                            </CompareDrawerPrimitive.Fallback>
-                          )}
-                        </CompareDrawerPrimitive.Thumbnail>
-                        <CompareDrawerPrimitive.Title>{item.title}</CompareDrawerPrimitive.Title>
-                      </CompareDrawerPrimitive.Link>
-                      <CompareDrawerPrimitive.Remove
-                        aria-label={`Remove ${item.title}`}
-                        onClick={() => handleRemove(item.id)}
-                      >
-                        <CompareDrawerPrimitive.RemoveIcon asChild>
-                          <X />
-                        </CompareDrawerPrimitive.RemoveIcon>
-                      </CompareDrawerPrimitive.Remove>
-                    </CompareDrawerPrimitive.Item>
-                  ))}
+                  <CompareDrawerPrimitive.Item>
+                    <CompareDrawerPrimitive.Link
+                      aria-label="View Natural Fiber Scrub Brush"
+                      href="/products/scrub-brush"
+                    >
+                      <CompareDrawerPrimitive.Thumbnail>
+                        <CompareDrawerPrimitive.Image
+                          alt="Natural Fiber Scrub Brush"
+                          src="https://images.unsplash.com/photo-1685052392951-4eb54985d3ae?w=200&h=200&fit=crop"
+                        />
+                      </CompareDrawerPrimitive.Thumbnail>
+                      <CompareDrawerPrimitive.Title>
+                        Natural Fiber Scrub Brush
+                      </CompareDrawerPrimitive.Title>
+                    </CompareDrawerPrimitive.Link>
+                    <CompareDrawerPrimitive.Remove aria-label="Remove Natural Fiber Scrub Brush">
+                      <CompareDrawerPrimitive.RemoveIcon />
+                    </CompareDrawerPrimitive.Remove>
+                  </CompareDrawerPrimitive.Item>
                 </CompareDrawerPrimitive.ItemList>
-                <CompareDrawerPrimitive.Submit
-                  className="hidden @md:block"
-                  href="/compare"
-                  size="medium"
-                  variant="primary"
-                >
+                <CompareDrawerPrimitive.Submit href="/compare" size="medium" variant="primary">
                   Compare <CompareDrawerPrimitive.SubmitIcon size="medium" />
                 </CompareDrawerPrimitive.Submit>
-                <CompareDrawerPrimitive.Submit
-                  className="w-full @md:hidden"
-                  href="/compare"
-                  size="small"
-                  variant="primary"
-                >
-                  Compare <CompareDrawerPrimitive.SubmitIcon size="small" />
-                </CompareDrawerPrimitive.Submit>
               </CompareDrawerPrimitive.Content>
             </CompareDrawerPrimitive.Viewport>
           </CompareDrawerPrimitive.Root>
@@ -407,4 +263,40 @@ export const ComposableAnatomy: Story = {
       </div>
     );
   },
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the composable primitives to build custom compare drawer layouts:
+
+\`\`\`tsx
+import * as CompareDrawerPrimitive from '@/components/compare-drawer/primitives';
+
+<CompareDrawerPrimitive.Root container={containerElement}>
+  <CompareDrawerPrimitive.Viewport>
+    <CompareDrawerPrimitive.Content>
+      <CompareDrawerPrimitive.ItemList>
+        <CompareDrawerPrimitive.Item>
+          <CompareDrawerPrimitive.Link href="/product" aria-label="View Product">
+            <CompareDrawerPrimitive.Thumbnail>
+              <CompareDrawerPrimitive.Image src="..." alt="..." />
+            </CompareDrawerPrimitive.Thumbnail>
+            <CompareDrawerPrimitive.Title>Product Name</CompareDrawerPrimitive.Title>
+          </CompareDrawerPrimitive.Link>
+          <CompareDrawerPrimitive.Remove aria-label="Remove Product">
+            <CompareDrawerPrimitive.RemoveIcon />
+          </CompareDrawerPrimitive.Remove>
+        </CompareDrawerPrimitive.Item>
+      </CompareDrawerPrimitive.ItemList>
+      <CompareDrawerPrimitive.Submit href="/compare" variant="primary">
+        Compare <CompareDrawerPrimitive.SubmitIcon />
+      </CompareDrawerPrimitive.Submit>
+    </CompareDrawerPrimitive.Content>
+  </CompareDrawerPrimitive.Viewport>
+</CompareDrawerPrimitive.Root>
+\`\`\`
+        `,
+      },
+    },
+  },
 };
diff --git a/src/components/counter/counter.tsx b/src/components/counter/counter.tsx
index 9403964..3bb07a2 100644
--- a/src/components/counter/counter.tsx
+++ b/src/components/counter/counter.tsx
@@ -24,14 +24,12 @@ export type CounterProps = ComponentProps<'input'> & {
  *
  * ```css
  * :root {
- *   --counter-focus: var(--brand);
- *   --counter-font-family: var(--font-family-body);
- *   --counter-background: var(--background);
- *   --counter-background-hover: color-mix(in oklab, var(--contrast-100) 50%, transparent);
- *   --counter-border: var(--contrast-100);
- *   --counter-text: var(--foreground);
- *   --counter-icon-hover: var(--foreground);
- *   --counter-icon: var(--contrast-300);
+ *   --counter-fill: var(--form-fill);
+ *   --counter-fill-hover: var(--form-fill-hover);
+ *   --counter-fill-icon: var(--form-fill-icon);
+ *   --counter-fill-icon-hover: var(--form-fill-icon-hover);
+ *   --counter-text: var(--form-text-primary);
+ *   --counter-font: var(--font-body);
  * }
  * ```
  */
diff --git a/src/components/counter/primitives/counter-decrease-icon.tsx b/src/components/counter/primitives/counter-decrease-icon.tsx
index 759604a..c2d6c85 100644
--- a/src/components/counter/primitives/counter-decrease-icon.tsx
+++ b/src/components/counter/primitives/counter-decrease-icon.tsx
@@ -16,9 +16,9 @@ export function CounterDecreaseIcon({
   children,
 }: CounterDecreaseIconProps) {
   const iconStyles = cn(
-    'size-[18px] text-[var(--counter-icon,var(--contrast-300))] transition-colors duration-300',
+    'size-[18px] text-[--counter-fill-icon,var(--form-fill-icon)] transition-colors duration-300',
     // Hover state (via parent group)
-    'group-enabled/counter:group-hover/counter:text-[var(--counter-icon-hover,var(--foreground))]',
+    'group-enabled/counter:group-hover/counter:text-[--counter-fill-icon-hover,var(--form-fill-icon-hover)]',
     className,
   );
 
diff --git a/src/components/counter/primitives/counter-decrease.tsx b/src/components/counter/primitives/counter-decrease.tsx
index 6bb3c76..b350212 100644
--- a/src/components/counter/primitives/counter-decrease.tsx
+++ b/src/components/counter/primitives/counter-decrease.tsx
@@ -14,11 +14,9 @@ export function CounterDecrease({
   return (
     <button
       className={cn(
-        'group/counter z-[1] rounded-l-lg p-3',
+        'focus-primary group/counter z-[1] rounded-l-lg p-3',
         // Hover state
-        'enabled:hover:bg-[var(--counter-background-hover,color-mix(in_oklab,var(--contrast-100)_50%,transparent))]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--counter-focus,var(--brand))]',
+        'enabled:hover:bg-[color-mix(in_oklab,var(--counter-fill-hover,var(--form-fill-hover))_50%,transparent)]',
         // Disabled state
         'disabled:cursor-not-allowed disabled:opacity-50',
         className,
diff --git a/src/components/counter/primitives/counter-increase-icon.tsx b/src/components/counter/primitives/counter-increase-icon.tsx
index f4a6e57..1537e58 100644
--- a/src/components/counter/primitives/counter-increase-icon.tsx
+++ b/src/components/counter/primitives/counter-increase-icon.tsx
@@ -16,9 +16,9 @@ export function CounterIncreaseIcon({
   children,
 }: CounterIncreaseIconProps) {
   const iconStyles = cn(
-    'size-[18px] text-[var(--counter-icon,var(--contrast-300))] transition-colors duration-300',
+    'size-[18px] text-[--counter-fill-icon,var(--form-fill-icon)] transition-colors duration-300',
     // Hover state (via parent group)
-    'group-enabled/counter:group-hover/counter:text-[var(--counter-icon-hover,var(--foreground))]',
+    'group-enabled/counter:group-hover/counter:text-[--counter-fill-icon-hover,var(--form-fill-icon-hover)]',
     className,
   );
 
diff --git a/src/components/counter/primitives/counter-increase.tsx b/src/components/counter/primitives/counter-increase.tsx
index 9f2eb31..0a05a77 100644
--- a/src/components/counter/primitives/counter-increase.tsx
+++ b/src/components/counter/primitives/counter-increase.tsx
@@ -14,11 +14,9 @@ export function CounterIncrease({
   return (
     <button
       className={cn(
-        'group/counter z-[1] rounded-r-lg p-3',
+        'focus-primary group/counter z-[1] rounded-r-lg p-3',
         // Hover state
-        'enabled:hover:bg-[var(--counter-background-hover,color-mix(in_oklab,var(--contrast-100)_50%,transparent))]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--counter-focus,var(--brand))]',
+        'enabled:hover:bg-[color-mix(in_oklab,var(--counter-fill-hover,var(--form-fill-hover))_50%,transparent)]',
         // Disabled state
         'disabled:cursor-not-allowed disabled:opacity-50',
         className,
diff --git a/src/components/counter/primitives/counter-root.tsx b/src/components/counter/primitives/counter-root.tsx
index 3bdce46..a736dac 100644
--- a/src/components/counter/primitives/counter-root.tsx
+++ b/src/components/counter/primitives/counter-root.tsx
@@ -8,7 +8,7 @@ export function CounterRoot({ children, className, ...props }: CounterRootProps)
   return (
     <div
       className={cn(
-        'flex items-center justify-between rounded-lg border border-[var(--counter-border,var(--contrast-100))] bg-[var(--counter-background,var(--background))] font-[var(--counter-font-family,var(--font-family-body))] text-[var(--counter-text,var(--foreground))]',
+        'flex items-center justify-between rounded-lg border border-[--border-subtle] bg-[--counter-fill,var(--form-fill)] text-[--counter-text,var(--form-text-primary)] [font-family:var(--counter-font,var(--font-body))]',
         className,
       )}
       data-slot="counter-root"
diff --git a/src/components/counter/storybook/counter.stories.tsx b/src/components/counter/storybook/counter.stories.tsx
index 0b728ce..89c7b25 100644
--- a/src/components/counter/storybook/counter.stories.tsx
+++ b/src/components/counter/storybook/counter.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Minus, Plus } from 'lucide-react';
 import { useRef, useState } from 'react';
 
 import { Counter, type CounterProps } from '@/components/counter';
@@ -19,70 +18,13 @@ A numeric counter input component for selecting quantities. Features increment/d
 
 \`\`\`css
 :root {
-  --counter-focus: var(--brand);
-  --counter-font-family: var(--font-family-body);
-  --counter-background: var(--background);
-  --counter-background-hover: color-mix(in oklab, var(--contrast-100) 50%, transparent);
-  --counter-border: var(--contrast-100);
-  --counter-text: var(--foreground);
-  --counter-icon: var(--contrast-300);
-  --counter-icon-hover: var(--foreground);
+  --counter-fill: var(--form-fill);
+  --counter-fill-hover: var(--form-fill-hover);
+  --counter-fill-icon: var(--form-fill-icon);
+  --counter-fill-icon-hover: var(--form-fill-icon-hover);
+  --counter-text: var(--form-text-primary);
+  --counter-font: var(--font-body);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Counter\` component provides a simple API for quantity selection:
-
-\`\`\`tsx
-import { Counter } from '@/components/counter';
-
-<Counter
-  defaultValue={1}
-  min={0}
-  max={10}
-/>
-\`\`\`
-
-### With Custom Icons
-
-Use the \`decrementIcon\` and \`incrementIcon\` props with \`asChild\` for custom icons:
-
-\`\`\`tsx
-import { Counter } from '@/components/counter';
-import { Minus, Plus } from 'lucide-react';
-
-<Counter
-  defaultValue={1}
-  decrementIcon={{ asChild: true, children: <Minus size={16} /> }}
-  incrementIcon={{ asChild: true, children: <Plus size={16} /> }}
-/>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Counter from '@/components/counter';
-
-<Counter.Root>
-  <Counter.Decrease aria-label="Decrease" onClick={handleDecrement}>
-    <Counter.DecreaseIcon />
-  </Counter.Decrease>
-  <Counter.Input
-    type="number"
-    min={0}
-    max={10}
-    value={count}
-    onChange={handleChange}
-  />
-  <Counter.Increase aria-label="Increase" onClick={handleIncrement}>
-    <Counter.IncreaseIcon />
-  </Counter.Increase>
-</Counter.Root>
 \`\`\`
         `,
       },
@@ -112,11 +54,11 @@ import * as Counter from '@/components/counter';
     },
     decrementIcon: {
       control: false,
-      description: 'Custom decrement icon configuration with asChild support',
+      description: 'Custom decrement icon configuration with `asChild` support',
     },
     incrementIcon: {
       control: false,
-      description: 'Custom increment icon configuration with asChild support',
+      description: 'Custom increment icon configuration with `asChild` support',
     },
   },
   args: {
@@ -129,39 +71,86 @@ import * as Counter from '@/components/counter';
 export default meta;
 type Story = StoryObj<CounterProps>;
 
-// Default counter
 export const Default: Story = {
   args: {
     defaultValue: 1,
   },
 };
 
-// Controlled example
-export const Controlled: Story = {
-  render: () => {
-    const [count, setCount] = useState(3);
-
-    return (
-      <Counter
-        max={10}
-        min={0}
-        onChange={(e) => setCount(Number(e.currentTarget.value))}
-        value={count}
-      />
-    );
-  },
-};
-
-// Disabled state
 export const Disabled: Story = {
   args: {
     defaultValue: 5,
     disabled: true,
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'The `disabled` prop prevents all interaction with the counter.',
+      },
+    },
+  },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the primitive components for full control over the structure.
+
+| Primitive                      | Description                                 |
+|--------------------------------|---------------------------------------------|
+| \`CounterPrimitive.Root\`         | Container with border and background.       |
+| \`CounterPrimitive.Decrease\`     | Decrement button.                           |
+| \`CounterPrimitive.DecreaseIcon\` | Minus icon with \`asChild\` support.        |
+| \`CounterPrimitive.Input\`        | Number input field.                         |
+| \`CounterPrimitive.Increase\`     | Increment button.                           |
+| \`CounterPrimitive.IncreaseIcon\` | Plus icon with \`asChild\` support.         |
+        `,
+      },
+      source: {
+        code: `
+import * as CounterPrimitive from '@/components/counter/primitives';
+
+const inputRef = useRef<HTMLInputElement>(null);
+const [count, setCount] = useState(2);
+
+const handleDecrement = () => {
+  if (count > 0) setCount(count - 1);
+};
+
+const handleIncrement = () => {
+  if (count < 10) setCount(count + 1);
+};
+
+<CounterPrimitive.Root>
+  <CounterPrimitive.Decrease
+    aria-label="Decrease quantity"
+    disabled={count <= 0}
+    onClick={handleDecrement}
+  >
+    <CounterPrimitive.DecreaseIcon />
+  </CounterPrimitive.Decrease>
+  <CounterPrimitive.Input
+    ref={inputRef}
+    type="number"
+    min={0}
+    max={10}
+    value={count}
+    onChange={(e) => setCount(Number(e.target.value))}
+  />
+  <CounterPrimitive.Increase
+    aria-label="Increase quantity"
+    disabled={count >= 10}
+    onClick={handleIncrement}
+  >
+    <CounterPrimitive.IncreaseIcon />
+  </CounterPrimitive.Increase>
+</CounterPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => {
     const inputRef = useRef<HTMLInputElement>(null);
     const [count, setCount] = useState(2);
@@ -185,9 +174,7 @@ export const ComposableAnatomy: Story = {
           disabled={count <= 0}
           onClick={handleDecrement}
         >
-          <CounterPrimitive.DecreaseIcon asChild>
-            <Minus absoluteStrokeWidth size={18} strokeWidth={1.5} />
-          </CounterPrimitive.DecreaseIcon>
+          <CounterPrimitive.DecreaseIcon />
         </CounterPrimitive.Decrease>
         <CounterPrimitive.Input
           max={10}
@@ -202,9 +189,7 @@ export const ComposableAnatomy: Story = {
           disabled={count >= 10}
           onClick={handleIncrement}
         >
-          <CounterPrimitive.IncreaseIcon asChild>
-            <Plus absoluteStrokeWidth size={18} strokeWidth={1.5} />
-          </CounterPrimitive.IncreaseIcon>
+          <CounterPrimitive.IncreaseIcon />
         </CounterPrimitive.Increase>
       </CounterPrimitive.Root>
     );
diff --git a/src/components/cursor-pagination/cursor-pagination.tsx b/src/components/cursor-pagination/cursor-pagination.tsx
index 93bc152..be38a9f 100644
--- a/src/components/cursor-pagination/cursor-pagination.tsx
+++ b/src/components/cursor-pagination/cursor-pagination.tsx
@@ -32,12 +32,9 @@ export interface CursorPaginationProps {
  *
  * ```css
  * :root {
- *   --cursor-pagination-focus: var(--brand);
- *   --cursor-pagination-border: var(--contrast-100);
- *   --cursor-pagination-border-hover: var(--contrast-200);
- *   --cursor-pagination-icon: var(--foreground);
- *   --cursor-pagination-background: var(--background);
- *   --cursor-pagination-background-hover: var(--contrast-100);
+ *   --cursor-pagination-fill: var(--background);
+ *   --cursor-pagination-fill-hover: var(--contrast-100);
+ *   --cursor-pagination-fill-icon: var(--foreground);
  * }
  * ```
  */
diff --git a/src/components/cursor-pagination/primitives/cursor-pagination-link.tsx b/src/components/cursor-pagination/primitives/cursor-pagination-link.tsx
index c186608..a51c987 100644
--- a/src/components/cursor-pagination/primitives/cursor-pagination-link.tsx
+++ b/src/components/cursor-pagination/primitives/cursor-pagination-link.tsx
@@ -18,11 +18,9 @@ export function CursorPaginationLink({
   return (
     <Component
       className={cn(
-        'flex h-12 w-12 items-center justify-center rounded-full border border-[var(--cursor-pagination-border,var(--contrast-100))] bg-[var(--cursor-pagination-background,var(--background))] transition-colors duration-300',
+        'focus-primary flex h-12 w-12 items-center justify-center rounded-full border border-[--border-subtle] bg-[--cursor-pagination-fill,var(--background)] transition-colors duration-300',
         // Hover state
-        'hover:border-[var(--cursor-pagination-border-hover,var(--contrast-200))] hover:bg-[var(--cursor-pagination-background-hover,var(--contrast-100))]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--cursor-pagination-focus,var(--brand))]',
+        'hover:border-[--border-hover] hover:bg-[--cursor-pagination-fill-hover,var(--contrast-100)]',
         // Disabled state (aria-disabled)
         'aria-disabled:pointer-events-none aria-disabled:cursor-not-allowed aria-disabled:opacity-25',
         className,
diff --git a/src/components/cursor-pagination/primitives/cursor-pagination-next-icon.tsx b/src/components/cursor-pagination/primitives/cursor-pagination-next-icon.tsx
index 20d4628..f6ecaa5 100644
--- a/src/components/cursor-pagination/primitives/cursor-pagination-next-icon.tsx
+++ b/src/components/cursor-pagination/primitives/cursor-pagination-next-icon.tsx
@@ -15,9 +15,11 @@ export function CursorPaginationNextIcon({
   className,
   children,
 }: CursorPaginationNextIconProps) {
+  const iconStyles = cn('size-6', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-6', className)} data-slot="cursor-pagination-next-icon">
+      <Slot className={iconStyles} data-slot="cursor-pagination-next-icon">
         {children}
       </Slot>
     );
@@ -26,7 +28,7 @@ export function CursorPaginationNextIcon({
   return (
     <ArrowRight
       absoluteStrokeWidth
-      className={cn('size-6', className)}
+      className={iconStyles}
       color="currentColor"
       data-slot="cursor-pagination-next-icon"
       strokeWidth={1}
diff --git a/src/components/cursor-pagination/primitives/cursor-pagination-previous-icon.tsx b/src/components/cursor-pagination/primitives/cursor-pagination-previous-icon.tsx
index e99011a..2d193d6 100644
--- a/src/components/cursor-pagination/primitives/cursor-pagination-previous-icon.tsx
+++ b/src/components/cursor-pagination/primitives/cursor-pagination-previous-icon.tsx
@@ -15,9 +15,11 @@ export function CursorPaginationPreviousIcon({
   className,
   children,
 }: CursorPaginationPreviousIconProps) {
+  const iconStyles = cn('size-6', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-6', className)} data-slot="cursor-pagination-previous-icon">
+      <Slot className={iconStyles} data-slot="cursor-pagination-previous-icon">
         {children}
       </Slot>
     );
@@ -26,7 +28,7 @@ export function CursorPaginationPreviousIcon({
   return (
     <ArrowLeft
       absoluteStrokeWidth
-      className={cn('size-6', className)}
+      className={iconStyles}
       color="currentColor"
       data-slot="cursor-pagination-previous-icon"
       strokeWidth={1}
diff --git a/src/components/cursor-pagination/primitives/cursor-pagination-root.tsx b/src/components/cursor-pagination/primitives/cursor-pagination-root.tsx
index b0e91c5..adc1910 100644
--- a/src/components/cursor-pagination/primitives/cursor-pagination-root.tsx
+++ b/src/components/cursor-pagination/primitives/cursor-pagination-root.tsx
@@ -7,7 +7,7 @@ export type CursorPaginationRootProps = ComponentProps<'div'>;
 export function CursorPaginationRoot({ className, children, ...props }: CursorPaginationRootProps) {
   return (
     <nav
-      className={cn('py-10 text-[var(--cursor-pagination-icon,var(--foreground))]', className)}
+      className={cn('py-10 text-[--cursor-pagination-fill-icon,var(--foreground)]', className)}
       data-slot="cursor-pagination-root"
       {...props}
     >
diff --git a/src/components/cursor-pagination/primitives/cursor-pagination-skeleton.tsx b/src/components/cursor-pagination/primitives/cursor-pagination-skeleton.tsx
index c662524..cc8368f 100644
--- a/src/components/cursor-pagination/primitives/cursor-pagination-skeleton.tsx
+++ b/src/components/cursor-pagination/primitives/cursor-pagination-skeleton.tsx
@@ -9,17 +9,17 @@ export type CursorPaginationSkeletonProps = ComponentProps<'div'>;
 export function CursorPaginationSkeleton({ className, ...props }: CursorPaginationSkeletonProps) {
   return (
     <div
-      className={cn('py-10 text-[var(--cursor-pagination-icon,var(--foreground))]', className)}
+      className={cn('py-10 text-[--cursor-pagination-fill-icon,var(--foreground)]', className)}
       data-slot="cursor-pagination-skeleton"
       {...props}
     >
       <div className="flex items-center justify-center gap-3">
         <SkeletonPrimitive.Icon
-          className="flex h-12 w-12 cursor-not-allowed items-center justify-center rounded-full border border-[var(--cursor-pagination-border,var(--contrast-100))]"
+          className="flex h-12 w-12 cursor-not-allowed items-center justify-center rounded-full border border-[--border-subtle]"
           icon={<ArrowLeft absoluteStrokeWidth size={24} strokeWidth={1} />}
         />
         <SkeletonPrimitive.Icon
-          className="flex h-12 w-12 cursor-not-allowed items-center justify-center rounded-full border border-[var(--cursor-pagination-border,var(--contrast-100))]"
+          className="flex h-12 w-12 cursor-not-allowed items-center justify-center rounded-full border border-[--border-subtle]"
           icon={<ArrowRight absoluteStrokeWidth size={24} strokeWidth={1} />}
         />
       </div>
diff --git a/src/components/cursor-pagination/storybook/cursor-pagination.stories.tsx b/src/components/cursor-pagination/storybook/cursor-pagination.stories.tsx
index 3683ab6..2285f28 100644
--- a/src/components/cursor-pagination/storybook/cursor-pagination.stories.tsx
+++ b/src/components/cursor-pagination/storybook/cursor-pagination.stories.tsx
@@ -11,80 +11,17 @@ const meta: Meta<typeof CursorPagination> = {
     docs: {
       description: {
         component: `
-A cursor-based pagination component for navigating through paginated content. Uses cursor tokens instead of page numbers, ideal for infinite-scroll or real-time data.
+A cursor-based pagination component for navigating through paginated content. Uses cursor tokens instead of page numbers, ideal for real-time data.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --cursor-pagination-focus: var(--brand);
-  --cursor-pagination-border: var(--contrast-100);
-  --cursor-pagination-border-hover: var(--contrast-200);
-  --cursor-pagination-icon: var(--foreground);
-  --cursor-pagination-background: var(--background);
-  --cursor-pagination-background-hover: var(--contrast-100);
+  --cursor-pagination-fill: var(--background);
+  --cursor-pagination-fill-hover: var(--contrast-100);
+  --cursor-pagination-fill-icon: var(--foreground);
 }
 \`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`CursorPagination\` component provides a simple API for cursor-based navigation:
-
-\`\`\`tsx
-import { CursorPagination } from '@/components/cursor-pagination';
-
-<CursorPagination
-  previousLink={{ href: '?before=cursor-123' }}
-  nextLink={{ href: '?after=cursor-456' }}
-/>
-\`\`\`
-
-### With Router Integration
-
-Use the \`asChild\` pattern for Next.js Link or React Router:
-
-\`\`\`tsx
-import { CursorPagination } from '@/components/cursor-pagination';
-import Link from 'next/link';
-
-<CursorPagination
-  previousLink={{
-    asChild: true,
-    children: <Link href="?before=cursor-123"><PreviousIcon /></Link>,
-  }}
-  nextLink={{
-    asChild: true,
-    children: <Link href="?after=cursor-456"><NextIcon /></Link>,
-  }}
-/>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as CursorPagination from '@/components/cursor-pagination';
-
-<CursorPagination.Root aria-label="pagination" role="navigation">
-  <CursorPagination.List>
-    <CursorPagination.Item>
-      <CursorPagination.Link href="?before=cursor-123" aria-label="Previous page">
-        <CursorPagination.PreviousIcon />
-      </CursorPagination.Link>
-    </CursorPagination.Item>
-    <CursorPagination.Item>
-      <CursorPagination.Link href="?after=cursor-456" aria-label="Next page">
-        <CursorPagination.NextIcon />
-      </CursorPagination.Link>
-    </CursorPagination.Item>
-  </CursorPagination.List>
-</CursorPagination.Root>
-\`\`\`
-
-The \`Link\` component supports \`asChild\` for router integration. Use \`aria-disabled\` for disabled states.
         `,
       },
     },
@@ -97,19 +34,19 @@ The \`Link\` component supports \`asChild\` for router integration. Use \`aria-d
     },
     previousLink: {
       control: false,
-      description: 'Configuration for the previous page link with href and optional asChild',
+      description: 'Previous link config with `href` and optional `asChild`',
     },
     nextLink: {
       control: false,
-      description: 'Configuration for the next page link with href and optional asChild',
+      description: 'Next link config with `href` and optional `asChild`',
     },
     previousIcon: {
       control: false,
-      description: 'Custom previous icon configuration with asChild support',
+      description: 'Custom previous icon with `asChild` support',
     },
     nextIcon: {
       control: false,
-      description: 'Custom next icon configuration with asChild support',
+      description: 'Custom next icon with `asChild` support',
     },
   },
 };
@@ -117,24 +54,60 @@ The \`Link\` component supports \`asChild\` for router integration. Use \`aria-d
 export default meta;
 type Story = StoryObj<CursorPaginationProps>;
 
-// Default with both directions enabled
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Both directions enabled with cursor-based hrefs.',
+      },
+    },
+  },
   args: {
     previousLink: { href: '?before=prev-cursor-123' },
     nextLink: { href: '?after=next-cursor-456' },
   },
 };
 
-// First page (no previous link - disabled state)
 export const FirstPage: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'First page state with previous link disabled (href is null).',
+      },
+    },
+  },
   args: {
     previousLink: { href: null },
     nextLink: { href: '?after=next-cursor-456' },
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitive components for custom layouts.',
+      },
+      source: {
+        code: `
+<CursorPaginationPrimitive.Root aria-label="Product pagination" role="navigation">
+  <CursorPaginationPrimitive.List>
+    <CursorPaginationPrimitive.Item>
+      <CursorPaginationPrimitive.Link href="?before=cursor-123" aria-label="Go to previous page">
+        <CursorPaginationPrimitive.PreviousIcon />
+      </CursorPaginationPrimitive.Link>
+    </CursorPaginationPrimitive.Item>
+    <CursorPaginationPrimitive.Item>
+      <CursorPaginationPrimitive.Link href="?after=cursor-456" aria-label="Go to next page">
+        <CursorPaginationPrimitive.NextIcon />
+      </CursorPaginationPrimitive.Link>
+    </CursorPaginationPrimitive.Item>
+  </CursorPaginationPrimitive.List>
+</CursorPaginationPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <CursorPaginationPrimitive.Root aria-label="Product pagination" role="navigation">
       <CursorPaginationPrimitive.List>
@@ -156,7 +129,16 @@ export const ComposableAnatomy: Story = {
   ),
 };
 
-// Skeleton loading state
 export const Skeleton: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Loading state placeholder.',
+      },
+      source: {
+        code: `<CursorPaginationPrimitive.Skeleton />`,
+      },
+    },
+  },
   render: () => <CursorPaginationPrimitive.Skeleton />,
 };
diff --git a/src/components/date-picker/primitives/date-picker-icon.tsx b/src/components/date-picker/primitives/date-picker-icon.tsx
index dd3bb86..b837b06 100644
--- a/src/components/date-picker/primitives/date-picker-icon.tsx
+++ b/src/components/date-picker/primitives/date-picker-icon.tsx
@@ -13,7 +13,7 @@ export interface DatePickerIconProps {
 }
 
 export function DatePickerIcon({ asChild = false, className, children }: DatePickerIconProps) {
-  const iconStyles = cn('size-5 text-[var(--input-light-icon,var(--contrast-400))]', className);
+  const iconStyles = cn('size-5', className);
 
   if (asChild) {
     return (
diff --git a/src/components/date-picker/primitives/date-picker-input.tsx b/src/components/date-picker/primitives/date-picker-input.tsx
index 23d181d..2f35f95 100644
--- a/src/components/date-picker/primitives/date-picker-input.tsx
+++ b/src/components/date-picker/primitives/date-picker-input.tsx
@@ -1,13 +1,14 @@
-import type { ComponentProps, ReactNode } from 'react';
+import type { ReactNode } from 'react';
+import type { ComponentProps } from 'react';
 
 import { Input } from '@/components/input';
 
-export interface DatePickerInputProps extends ComponentProps<'input'> {
+export type DatePickerInputProps = ComponentProps<typeof Input> & {
   prependIcon?: {
     asChild?: boolean;
     children?: ReactNode;
   };
-}
+};
 
 export function DatePickerInput({ className, prependIcon, ...props }: DatePickerInputProps) {
   return (
diff --git a/src/components/date-picker/storybook/date-picker.stories.tsx b/src/components/date-picker/storybook/date-picker.stories.tsx
index de4aa9b..7db59f9 100644
--- a/src/components/date-picker/storybook/date-picker.stories.tsx
+++ b/src/components/date-picker/storybook/date-picker.stories.tsx
@@ -1,19 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { CalendarDays } from 'lucide-react';
-import type { ComponentType } from 'react';
 import { useState } from 'react';
 
 import { DatePicker, type DatePickerProps } from '@/components/date-picker';
 import * as DatePickerPrimitive from '@/components/date-picker/primitives';
 
-function addDays(date: Date, days: number): Date {
-  const result = new Date(date);
-
-  result.setDate(result.getDate() + days);
-
-  return result;
-}
-
 const meta: Meta<typeof DatePicker> = {
   title: 'Components/DatePicker',
   component: DatePicker,
@@ -22,86 +12,33 @@ const meta: Meta<typeof DatePicker> = {
     docs: {
       description: {
         component: `
-A date picker component that combines an input field with a calendar popover. Built on top of Radix UI Popover and react-day-picker.
+A date picker component that combines an input field with a calendar popover. Built on Radix UI Popover and react-day-picker.
 
 ## CSS Variables
 
 The DatePicker uses CSS variables from the Input and Calendar components:
 
+### Input Variables
+
 \`\`\`css
 :root {
-  /* Input styling */
-  --input-light-background: var(--background);
-  --input-light-border: var(--contrast-100);
-  --input-light-focus: var(--foreground);
-  --input-light-border-error: var(--error);
-  --input-light-text: var(--foreground);
-  --input-light-placeholder: var(--contrast-500);
-  --input-light-icon: var(--contrast-400);
-
-  /* Calendar styling */
-  --calendar-font-family: var(--font-family-body);
-  --calendar-light-focus: var(--foreground);
-  --calendar-light-border: var(--contrast-100);
-  --calendar-light-text: var(--foreground);
-  --calendar-light-background: var(--background);
-  --calendar-light-button-border-hover: var(--contrast-200);
-  --calendar-light-selected-button-background: var(--brand);
-  --calendar-light-selected-button-text: var(--foreground);
-  --calendar-light-text-disabled: var(--contrast-300);
+  --input-fill: var(--form-fill);
+  --input-fill-icon: var(--form-fill-icon);
+  --input-text: var(--form-text-primary);
+  --input-text-placeholder: var(--form-text-placeholder);
 }
 \`\`\`
 
-## Usage
-
-### High-Level Component
-
-The \`DatePicker\` component provides a simple API for single date selection:
-
-\`\`\`tsx
-import { DatePicker } from '@/components/date-picker';
-
-const [date, setDate] = useState<Date | undefined>();
-
-<DatePicker
-  id="date-field"
-  name="date"
-  selected={date}
-  onCalendarSelect={setDate}
-  placeholder="Select a date"
-/>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
+### Calendar Variables
 
-\`\`\`tsx
-import * as DatePicker from '@/components/date-picker';
-
-<DatePicker.Root>
-  <DatePicker.Trigger asChild>
-    <DatePicker.Input
-      id="date-field"
-      name="date"
-      placeholder="MM/DD/YYYY"
-      prependIcon={{
-        asChild: true,
-        children: <DatePicker.Icon />,
-      }}
-      readOnly
-    />
-  </DatePicker.Trigger>
-  <DatePicker.Portal>
-    <DatePicker.Content align="start" sideOffset={8}>
-      <DatePicker.Calendar
-        mode="single"
-        selected={date}
-        onSelect={setDate}
-      />
-    </DatePicker.Content>
-  </DatePicker.Portal>
-</DatePicker.Root>
+\`\`\`css
+:root {
+  --calendar-font: var(--font-body);
+  --calendar-fill: var(--background);
+  --calendar-text-primary: var(--text-primary);
+  --calendar-fill-selected: var(--brand);
+  --calendar-text-selected: var(--text-primary);
+}
 \`\`\`
         `,
       },
@@ -139,19 +76,36 @@ import * as DatePicker from '@/components/date-picker';
     },
     icon: {
       control: false,
-      description: 'Custom icon configuration with asChild and children props',
+      description: 'Custom icon configuration with `asChild` support',
     },
   },
-  decorators: [(Story: ComponentType) => <Story />],
 };
 
 export default meta;
 type Story = StoryObj<DatePickerProps>;
 
-/**
- * The default DatePicker displays an input with a calendar icon that opens a calendar popover.
- */
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'A controlled date picker with a calendar icon that opens a calendar popover on click.',
+      },
+      source: {
+        code: `
+const [selected, setSelected] = useState<Date | undefined>(new Date());
+
+<DatePicker
+  id="date-default"
+  name="date"
+  selected={selected}
+  onCalendarSelect={setSelected}
+  placeholder="Select a date"
+/>
+        `,
+      },
+    },
+  },
   render: () => {
     const [selected, setSelected] = useState<Date | undefined>(new Date());
 
@@ -167,53 +121,36 @@ export const Default: Story = {
   },
 };
 
-/**
- * A DatePicker with no initial value shows the placeholder text.
- */
-export const WithPlaceholder: Story = {
-  render: () => {
-    const [selected, setSelected] = useState<Date | undefined>();
-
-    return (
-      <DatePicker
-        id="date-placeholder"
-        name="date"
-        onCalendarSelect={setSelected}
-        placeholder="Choose your date"
-        selected={selected}
-      />
-    );
-  },
-};
+export const DisabledDates: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use `disabledDays` to prevent selection of specific dates. This example disables past dates and weekends.',
+      },
+      source: {
+        code: `
+const [selected, setSelected] = useState<Date | undefined>();
 
-/**
- * Customize the icon using the `icon` prop with `asChild` to render your own icon component.
- */
-export const CustomIcon: Story = {
-  render: () => {
-    const [selected, setSelected] = useState<Date | undefined>(new Date());
+const disabledDays = [
+  { before: new Date() },
+  { dayOfWeek: [0, 6] }
+];
 
-    return (
-      <DatePicker
-        icon={{ asChild: true, children: <CalendarDays /> }}
-        id="date-custom-icon"
-        name="date"
-        onCalendarSelect={setSelected}
-        placeholder="Select a date"
-        selected={selected}
-      />
-    );
+<DatePicker
+  id="date-disabled"
+  name="date"
+  selected={selected}
+  onCalendarSelect={setSelected}
+  placeholder="Select a weekday"
+  disabledDays={disabledDays}
+/>
+        `,
+      },
+    },
   },
-};
-
-/**
- * Disable specific dates to prevent selection, such as past dates or weekends.
- */
-export const DisabledDates: Story = {
   render: () => {
     const [selected, setSelected] = useState<Date | undefined>();
-
-    // Disable past dates and weekends
     const disabledDays = [{ before: new Date() }, { dayOfWeek: [0, 6] }];
 
     return (
@@ -229,33 +166,59 @@ export const DisabledDates: Story = {
   },
 };
 
-/**
- * Limit date selection to a specific range by disabling dates outside the range.
- */
-export const DateRange: Story = {
-  render: () => {
-    const [selected, setSelected] = useState<Date | undefined>();
+export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the primitive components for full control over the structure.
+
+| Primitive                      | Description                                   |
+|--------------------------------|-----------------------------------------------|
+| \`DatePickerPrimitive.Root\`      | Popover root provider.                        |
+| \`DatePickerPrimitive.Trigger\`   | Element that opens the popover.               |
+| \`DatePickerPrimitive.Input\`     | Input field (wraps the Input component).      |
+| \`DatePickerPrimitive.Icon\`      | Calendar icon with \`asChild\` support.       |
+| \`DatePickerPrimitive.Portal\`    | Portals content to document body.             |
+| \`DatePickerPrimitive.Content\`   | Popover content container with animations.    |
+| \`DatePickerPrimitive.Calendar\`  | Calendar component for date selection.        |
+        `,
+      },
+      source: {
+        code: `
+import * as DatePickerPrimitive from '@/components/date-picker/primitives';
 
-    // Only allow dates within the next 30 days
-    const disabledDays = [{ before: new Date() }, { after: addDays(new Date(), 30) }];
+const [selected, setSelected] = useState<Date | undefined>(new Date());
+const formattedDate = selected ? Intl.DateTimeFormat().format(selected) : '';
 
-    return (
-      <DatePicker
-        disabledDays={disabledDays}
-        id="date-range"
-        name="date"
-        onCalendarSelect={setSelected}
-        placeholder="Next 30 days only"
+<DatePickerPrimitive.Root>
+  <DatePickerPrimitive.Trigger asChild>
+    <DatePickerPrimitive.Input
+      id="date-composable"
+      name="date"
+      placeholder="MM/DD/YYYY"
+      prependIcon={{
+        asChild: true,
+        children: <DatePickerPrimitive.Icon />,
+      }}
+      readOnly
+      value={formattedDate}
+    />
+  </DatePickerPrimitive.Trigger>
+  <DatePickerPrimitive.Portal>
+    <DatePickerPrimitive.Content align="start" sideOffset={8}>
+      <DatePickerPrimitive.Calendar
+        mode="single"
         selected={selected}
+        onSelect={setSelected}
       />
-    );
+    </DatePickerPrimitive.Content>
+  </DatePickerPrimitive.Portal>
+</DatePickerPrimitive.Root>
+        `,
+      },
+    },
   },
-};
-
-/**
- * Use the primitive components directly for full customization control.
- */
-export const ComposableAnatomy: Story = {
   render: () => {
     const [selected, setSelected] = useState<Date | undefined>(new Date());
     const formattedDate = selected ? Intl.DateTimeFormat().format(selected) : '';
diff --git a/src/components/dropdown-menu/dropdown-menu.tsx b/src/components/dropdown-menu/dropdown-menu.tsx
index 88aa014..81c90c9 100644
--- a/src/components/dropdown-menu/dropdown-menu.tsx
+++ b/src/components/dropdown-menu/dropdown-menu.tsx
@@ -2,8 +2,8 @@
 
 import type { ReactNode } from 'react';
 
-import { Button } from '@/components/button';
 import * as DropdownMenuPrimitive from '@/components/dropdown-menu';
+import type { DropdownMenuNode } from '@/components/dropdown-menu';
 import { cn } from '@/lib';
 
 /**
@@ -12,39 +12,21 @@ import { cn } from '@/lib';
  *
  * ```css
  * :root {
- *   --dropdown-menu-background: var(--background);
- *   --dropdown-menu-border: var(--contrast-100);
- *   --dropdown-menu-focus: var(--brand);
- *   --dropdown-menu-item-focus: var(--brand);
- *   --dropdown-menu-item-text: var(--contrast-400);
- *   --dropdown-menu-item-text-hover: var(--foreground);
- *   --dropdown-menu-item-danger-text: var(--error);
- *   --dropdown-menu-item-danger-text-hover: color-mix(in oklab, var(--error), black 75%);
- *   --dropdown-menu-item-background: transparent;
- *   --dropdown-menu-item-background-hover: var(--contrast-100);
- *   --dropdown-menu-item-danger-background: var(--error);
- *   --dropdown-menu-item-danger-background-hover: color-mix(in oklab, var(--error), white 75%);
- *   --dropdown-menu-item-font-family: var(--font-family-body);
- *   --dropdown-menu-seperator: var(--contrast-200);
+ *   --dropdown-menu-fill: var(--background);
+ *   --dropdown-menu-font: var(--font-body);
+ *   --dropdown-menu-text: var(--text-secondary);
+ *   --dropdown-menu-fill-hover: var(--contrast-100);
+ *   --dropdown-menu-text-hover: var(--text-primary);
+ *   --dropdown-menu-text-error: var(--error);
+ *   --dropdown-menu-fill-error: var(--error-background);
+ *   --dropdown-menu-text-error-hover: var(--error-foreground);
  * }
  * ```
  */
 
-type MenuNode =
-  | { type: 'item'; props?: DropdownMenuPrimitive.ItemProps }
-  | { type: 'checkbox'; props?: DropdownMenuPrimitive.CheckboxItemProps }
-  | { type: 'separator'; props?: DropdownMenuPrimitive.SeparatorProps }
-  | { type: 'group'; props?: DropdownMenuPrimitive.GroupProps; items: MenuNode[] }
-  | {
-      type: 'sub';
-      props?: DropdownMenuPrimitive.SubProps;
-      trigger: { props?: DropdownMenuPrimitive.SubTriggerProps };
-      content?: { props?: DropdownMenuPrimitive.SubContentProps; items: MenuNode[] };
-    };
-
 export interface DropdownMenuProps {
   className?: string;
-  items: MenuNode[];
+  nodes: DropdownMenuNode[];
   trigger?: ReactNode;
   triggerIcon?: {
     asChild?: boolean;
@@ -59,7 +41,7 @@ export interface DropdownMenuProps {
 
 export function DropdownMenu({
   className,
-  items,
+  nodes,
   trigger,
   triggerIcon,
   align,
@@ -79,19 +61,23 @@ export function DropdownMenu({
         {trigger !== undefined ? (
           trigger
         ) : (
-          <Button shape="circle" size="small" variant="ghost">
+          <DropdownMenuPrimitive.Button>
             <DropdownMenuPrimitive.TriggerIcon asChild={triggerIcon?.asChild}>
               {triggerIcon?.children}
             </DropdownMenuPrimitive.TriggerIcon>
-          </Button>
+          </DropdownMenuPrimitive.Button>
         )}
       </DropdownMenuPrimitive.Trigger>
       <DropdownMenuPrimitive.Portal>
         <DropdownMenuPrimitive.Content className={cn(className)}>
           <DropdownMenuPrimitive.ScrollArea>
             <DropdownMenuPrimitive.Label>{label}</DropdownMenuPrimitive.Label>
-            {items.map((item, index) => (
-              <DropdownMenuPrimitive.Node key={index} menuKey={index} menuNode={item} />
+            {nodes.map((node, index) => (
+              <DropdownMenuPrimitive.Node
+                dropdownMenuKey={index}
+                dropdownMenuNode={node}
+                key={index}
+              />
             ))}
           </DropdownMenuPrimitive.ScrollArea>
         </DropdownMenuPrimitive.Content>
diff --git a/src/components/dropdown-menu/primitives.ts b/src/components/dropdown-menu/primitives.ts
index a4d1cde..8767cf7 100644
--- a/src/components/dropdown-menu/primitives.ts
+++ b/src/components/dropdown-menu/primitives.ts
@@ -54,6 +54,7 @@ export {
 export {
   DropdownMenuNode as Node,
   type DropdownMenuNodeProps as NodeProps,
+  type DropdownMenuNode,
 } from '@/components/dropdown-menu/primitives/dropdown-menu-node';
 export {
   DropdownMenuCheckboxIndicator as CheckboxIndicator,
@@ -67,3 +68,7 @@ export {
   DropdownMenuTriggerIcon as TriggerIcon,
   type DropdownMenuTriggerIconProps as TriggerIconProps,
 } from '@/components/dropdown-menu/primitives/dropdown-menu-trigger-icon';
+export {
+  DropdownMenuButton as Button,
+  type DropdownMenuButtonProps as ButtonProps,
+} from '@/components/dropdown-menu/primitives/dropdown-menu-button';
diff --git a/src/components/dropdown-menu/primitives/dropdown-menu-button.tsx b/src/components/dropdown-menu/primitives/dropdown-menu-button.tsx
new file mode 100644
index 0000000..e4dba7f
--- /dev/null
+++ b/src/components/dropdown-menu/primitives/dropdown-menu-button.tsx
@@ -0,0 +1,13 @@
+import type { ComponentProps } from 'react';
+
+import { Button } from '@/components/button';
+
+export type DropdownMenuButtonProps = ComponentProps<typeof Button>;
+
+export function DropdownMenuButton({ className, children, ...props }: DropdownMenuButtonProps) {
+  return (
+    <Button className={className} shape="circle" size="small" variant="ghost" {...props}>
+      {children}
+    </Button>
+  );
+}
diff --git a/src/components/dropdown-menu/primitives/dropdown-menu-checkbox-item.tsx b/src/components/dropdown-menu/primitives/dropdown-menu-checkbox-item.tsx
index 977d31d..9ae3764 100644
--- a/src/components/dropdown-menu/primitives/dropdown-menu-checkbox-item.tsx
+++ b/src/components/dropdown-menu/primitives/dropdown-menu-checkbox-item.tsx
@@ -25,15 +25,15 @@ export function DropdownMenuCheckboxItem({
     <DropdownMenuPrimitive.CheckboxItem
       checked={checked}
       className={cn(
-        'flex h-9 w-full cursor-pointer select-none items-center rounded-lg bg-[var(--dropdown-menu-item-background,transparent)] pl-3 pr-1.5 outline-none transition-colors',
+        'flex h-9 w-full cursor-pointer select-none items-center rounded-lg pl-3 pr-1.5 outline-none transition-colors',
         // Font styles
-        'font-[family-name:var(--dropdown-menu-item-font-family,var(--font-family-body))] text-sm font-normal',
+        'text-sm font-normal [family-name:var(--dropdown-menu-font,var(--font-body))]',
         // Disabled styles
         'data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50',
         // Default variant styles
-        'data-[variant=default]:text-[var(--dropdown-menu-item-text,var(--contrast-500))] data-[variant=default]:[&:not([data-disabled])]:focus:bg-[var(--dropdown-menu-item-background-hover,var(--contrast-100))] data-[variant=default]:[&:not([data-disabled])]:focus:text-[var(--dropdown-menu-item-text-hover,var(--foreground))]',
+        'data-[variant=default]:text-[--dropdown-menu-text,var(--text-secondary)] data-[variant=default]:[&:not([data-disabled])]:focus:bg-[--dropdown-menu-fill-hover,var(--contrast-100)] data-[variant=default]:[&:not([data-disabled])]:focus:text-[--dropdown-menu-text-hover,var(--text-primary)]',
         // Danger variant styles
-        'data-[variant=danger]:text-[var(--dropdown-menu-item-danger-text,var(--error))] data-[variant=danger]:[&:not([data-disabled])]:focus:bg-[var(--dropdown-menu-item-danger-background-hover,color-mix(in_oklab,var(--error),white_75%))] data-[variant=danger]:[&:not([data-disabled])]:focus:text-[var(--dropdown-menu-item-danger-text-hover,color-mix(in_oklab,var(--error),black_75%))]',
+        'data-[variant=danger]:text-[--dropdown-menu-text-error,var(--error)] data-[variant=danger]:[&:not([data-disabled])]:focus:bg-[--dropdown-menu-fill-error,var(--error-background)] data-[variant=danger]:[&:not([data-disabled])]:focus:text-[--dropdown-menu-text-error-hover,var(--error-foreground)]',
         className,
       )}
       data-slot="dropdown-menu-checkbox-item"
diff --git a/src/components/dropdown-menu/primitives/dropdown-menu-content.tsx b/src/components/dropdown-menu/primitives/dropdown-menu-content.tsx
index 34e4b92..18da105 100644
--- a/src/components/dropdown-menu/primitives/dropdown-menu-content.tsx
+++ b/src/components/dropdown-menu/primitives/dropdown-menu-content.tsx
@@ -15,7 +15,7 @@ export function DropdownMenuContent({ className, children, ...props }: DropdownM
     <DropdownMenuPrimitive.Content
       align={align}
       className={cn(
-        'z-50 min-w-32 rounded-2xl border border-[var(--dropdown-menu-border,var(--contrast-100))] bg-[var(--dropdown-menu-background,var(--background))] shadow-xl',
+        'z-50 min-w-32 rounded-2xl border border-[--border-subtle] bg-[--dropdown-menu-fill,var(--background)] shadow-xl',
         // Open styles
         'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
         // Closed styles
diff --git a/src/components/dropdown-menu/primitives/dropdown-menu-item.tsx b/src/components/dropdown-menu/primitives/dropdown-menu-item.tsx
index 5c90ef3..1c317b4 100644
--- a/src/components/dropdown-menu/primitives/dropdown-menu-item.tsx
+++ b/src/components/dropdown-menu/primitives/dropdown-menu-item.tsx
@@ -16,15 +16,15 @@ export function DropdownMenuItem({
   return (
     <DropdownMenuPrimitive.Item
       className={cn(
-        'flex h-9 cursor-pointer select-none items-center rounded-lg bg-[var(--dropdown-menu-item-background,transparent)] py-2 pl-3 pr-5 outline-none transition-colors',
+        'flex h-9 cursor-pointer select-none items-center rounded-lg py-2 pl-3 pr-5 outline-none transition-colors',
         // Font styles
-        'font-[family-name:var(--dropdown-menu-item-font-family,var(--font-family-body))] text-sm font-medium',
+        'text-sm font-medium [font-family:var(--dropdown-menu-font,var(--font-body))]',
         // Disabled styles
         'data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50',
         // Default variant styles
-        'data-[variant=default]:text-[var(--dropdown-menu-item-text,var(--contrast-500))] data-[variant=default]:[&:not([data-disabled])]:focus:bg-[var(--dropdown-menu-item-background-hover,var(--contrast-100))] data-[variant=default]:[&:not([data-disabled])]:focus:text-[var(--dropdown-menu-item-text-hover,var(--foreground))]',
+        'data-[variant=default]:text-[--dropdown-menu-text,var(--text-secondary)] data-[variant=default]:[&:not([data-disabled])]:focus:bg-[--dropdown-menu-fill-hover,var(--contrast-100)] data-[variant=default]:[&:not([data-disabled])]:focus:text-[--dropdown-menu-text-hover,var(--primary-text)]',
         // Danger variant styles
-        'data-[variant=danger]:text-[var(--dropdown-menu-item-danger-text,var(--error))] data-[variant=danger]:[&:not([data-disabled])]:focus:bg-[var(--dropdown-menu-item-danger-background-hover,color-mix(in_oklab,var(--error),white_75%))] data-[variant=danger]:[&:not([data-disabled])]:focus:text-[var(--dropdown-menu-item-danger-text-hover,color-mix(in_oklab,var(--error),black_75%))]',
+        'data-[variant=danger]:text-[--dropdown-menu-text-error,var(--error)] data-[variant=danger]:[&:not([data-disabled])]:focus:bg-[--dropdown-menu-fill-error,var(--error-background)] data-[variant=danger]:[&:not([data-disabled])]:focus:text-[--dropdown-menu-text-error-hover,var(--error-foreground)]',
         className,
       )}
       data-slot="dropdown-menu-item"
diff --git a/src/components/dropdown-menu/primitives/dropdown-menu-node.tsx b/src/components/dropdown-menu/primitives/dropdown-menu-node.tsx
index 4f925f8..6482da2 100644
--- a/src/components/dropdown-menu/primitives/dropdown-menu-node.tsx
+++ b/src/components/dropdown-menu/primitives/dropdown-menu-node.tsx
@@ -1,25 +1,25 @@
 import * as DropdownMenuPrimitive from '@/components/dropdown-menu';
 import { cn } from '@/lib';
 
-type MenuNode =
+export type DropdownMenuNode =
   | { type: 'item'; props?: DropdownMenuPrimitive.ItemProps }
   | { type: 'checkbox'; props?: DropdownMenuPrimitive.CheckboxItemProps }
   | { type: 'separator'; props?: DropdownMenuPrimitive.SeparatorProps }
-  | { type: 'group'; props?: DropdownMenuPrimitive.GroupProps; items: MenuNode[] }
+  | { type: 'group'; props?: DropdownMenuPrimitive.GroupProps; items: DropdownMenuNode[] }
   | {
       type: 'sub';
       props?: DropdownMenuPrimitive.SubProps;
       trigger: { props?: DropdownMenuPrimitive.SubTriggerProps };
-      content?: { props?: DropdownMenuPrimitive.SubContentProps; items: MenuNode[] };
+      content?: { props?: DropdownMenuPrimitive.SubContentProps; items: DropdownMenuNode[] };
     };
 
 export interface DropdownMenuNodeProps {
-  menuNode: MenuNode;
-  menuKey: string | number;
+  dropdownMenuNode: DropdownMenuNode;
+  dropdownMenuKey: string | number;
 }
 
-export function DropdownMenuNode({ menuNode, menuKey }: DropdownMenuNodeProps) {
-  function renderMenuNode(node: MenuNode, key: string | number) {
+export function DropdownMenuNode({ dropdownMenuNode, dropdownMenuKey }: DropdownMenuNodeProps) {
+  function renderDrodownMenuNode(node: DropdownMenuNode, key: string | number) {
     switch (node.type) {
       case 'item': {
         return <DropdownMenuPrimitive.Item key={key} {...node.props} />;
@@ -32,7 +32,7 @@ export function DropdownMenuNode({ menuNode, menuKey }: DropdownMenuNodeProps) {
       case 'group':
         return (
           <DropdownMenuPrimitive.Group key={key} {...node.props}>
-            {node.items.map((child, index) => renderMenuNode(child, String(index)))}
+            {node.items.map((child, index) => renderDrodownMenuNode(child, String(index)))}
           </DropdownMenuPrimitive.Group>
         );
       case 'sub':
@@ -47,7 +47,9 @@ export function DropdownMenuNode({ menuNode, menuKey }: DropdownMenuNodeProps) {
                   {...node.content.props}
                 >
                   <DropdownMenuPrimitive.ScrollArea>
-                    {node.content.items.map((child, index) => renderMenuNode(child, String(index)))}
+                    {node.content.items.map((child, index) =>
+                      renderDrodownMenuNode(child, String(index)),
+                    )}
                   </DropdownMenuPrimitive.ScrollArea>
                 </DropdownMenuPrimitive.SubContent>
               </DropdownMenuPrimitive.Portal>
@@ -57,5 +59,5 @@ export function DropdownMenuNode({ menuNode, menuKey }: DropdownMenuNodeProps) {
     }
   }
 
-  return renderMenuNode(menuNode, menuKey);
+  return renderDrodownMenuNode(dropdownMenuNode, dropdownMenuKey);
 }
diff --git a/src/components/dropdown-menu/primitives/dropdown-menu-separator.tsx b/src/components/dropdown-menu/primitives/dropdown-menu-separator.tsx
index 2136193..ae2bdac 100644
--- a/src/components/dropdown-menu/primitives/dropdown-menu-separator.tsx
+++ b/src/components/dropdown-menu/primitives/dropdown-menu-separator.tsx
@@ -9,7 +9,7 @@ export function DropdownMenuSeparator({ className, ...props }: DropdownMenuSepar
   return (
     <DropdownMenuPrimitive.Separator
       className={cn(
-        'relative my-1.5 after:absolute after:-left-2 after:-right-5 after:h-px after:bg-[var(--dropdown-menu-seperator,var(--contrast-100))]',
+        'relative my-1.5 after:absolute after:-left-2 after:-right-5 after:h-px after:bg-[--border-subtle]',
         className,
       )}
       data-slot="dropdown-menu-separator"
diff --git a/src/components/dropdown-menu/primitives/dropdown-menu-sub-content.tsx b/src/components/dropdown-menu/primitives/dropdown-menu-sub-content.tsx
index 46a30ad..b811d95 100644
--- a/src/components/dropdown-menu/primitives/dropdown-menu-sub-content.tsx
+++ b/src/components/dropdown-menu/primitives/dropdown-menu-sub-content.tsx
@@ -13,7 +13,7 @@ export function DropdownMenuSubContent({
   return (
     <DropdownMenuPrimitive.SubContent
       className={cn(
-        'z-50 min-w-32 origin-top-left rounded-2xl border border-[var(--dropdown-menu-border,var(--contrast-100))] bg-[var(--dropdown-menu-background,var(--background))] shadow-xl',
+        'z-50 min-w-32 origin-top-left rounded-2xl border border-[--border-subtle] bg-[--dropdown-menu-fill,var(--background)] shadow-xl',
         // Open styles
         'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
         // Closed styles
diff --git a/src/components/dropdown-menu/primitives/dropdown-menu-sub-trigger.tsx b/src/components/dropdown-menu/primitives/dropdown-menu-sub-trigger.tsx
index e9029ed..78abd10 100644
--- a/src/components/dropdown-menu/primitives/dropdown-menu-sub-trigger.tsx
+++ b/src/components/dropdown-menu/primitives/dropdown-menu-sub-trigger.tsx
@@ -23,15 +23,15 @@ export function DropdownMenuSubTrigger({
   return (
     <DropdownMenuPrimitive.SubTrigger
       className={cn(
-        'flex h-9 cursor-pointer select-none items-center rounded-lg bg-[var(--dropdown-menu-item-background,transparent)] pl-3 pr-1 outline-none transition-colors',
+        'flex h-9 cursor-pointer select-none items-center rounded-lg pl-3 pr-1 outline-none transition-colors',
         // Font styles
-        'font-[family-name:var(--dropdown-menu-item-font-family,var(--font-family-body))] text-sm font-normal',
+        'text-sm font-normal [font-name:var(--dropdown-menu-font,var(--font-body))]',
         // Disabled styles
         'data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50',
         // Default variant styles
-        'data-[variant=default]:text-[var(--dropdown-menu-item-text,var(--contrast-500))] data-[variant=default]:[&:not([data-disabled])]:focus:bg-[var(--dropdown-menu-item-background-hover,var(--contrast-100))] data-[variant=default]:[&:not([data-disabled])]:focus:text-[var(--dropdown-menu-item-text-hover,var(--foreground))]',
+        'data-[variant=default]:text-[--dropdown-menu-text,var(--text-secondary)] data-[variant=default]:[&:not([data-disabled])]:focus:bg-[--dropdown-menu-fill-hover,var(--contrast-100)] data-[variant=default]:[&:not([data-disabled])]:focus:text-[--dropdown-menu-text-hover,var(--text-primary)]',
         // Danger variant styles
-        'data-[variant=danger]:text-[var(--dropdown-menu-item-danger-text,var(--error))] data-[variant=danger]:[&:not([data-disabled])]:focus:bg-[var(--dropdown-menu-item-danger-background-hover,color-mix(in_oklab,var(--error),white_75%))] data-[variant=danger]:[&:not([data-disabled])]:focus:text-[var(--dropdown-menu-item-danger-text-hover,color-mix(in_oklab,var(--error),black_75%))]',
+        'data-[variant=danger]:text-[--dropdown-menu-text-error,var(--error)] data-[variant=danger]:[&:not([data-disabled])]:focus:bg-[--dropdown-menu-fill-error,var(--error-background)] data-[variant=danger]:[&:not([data-disabled])]:focus:text-[--dropdown-menu-text-error-hover,var(--error-foreground)]',
         className,
       )}
       data-slot="dropdown-menu-sub-trigger"
diff --git a/src/components/dropdown-menu/storybook/dropdown-menu.stories.tsx b/src/components/dropdown-menu/storybook/dropdown-menu.stories.tsx
index dab58b9..216a2e9 100644
--- a/src/components/dropdown-menu/storybook/dropdown-menu.stories.tsx
+++ b/src/components/dropdown-menu/storybook/dropdown-menu.stories.tsx
@@ -17,117 +17,30 @@ const meta: Meta<typeof DropdownMenu> = {
     docs: {
       description: {
         component: `
-A dropdown menu component for displaying a list of actions or options. Built on Radix UI primitives with support for items, checkboxes, submenus, and groups.
+A dropdown menu for displaying actions or options. Built on Radix UI with support for items, checkboxes, submenus, and groups.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --dropdown-menu-background: var(--background);
-  --dropdown-menu-border: var(--contrast-100);
-  --dropdown-menu-focus: var(--brand);
-  --dropdown-menu-item-focus: var(--brand);
-  --dropdown-menu-item-text: var(--contrast-400);
-  --dropdown-menu-item-text-hover: var(--foreground);
-  --dropdown-menu-item-danger-text: var(--error);
-  --dropdown-menu-item-danger-text-hover: color-mix(in oklab, var(--error), black 75%);
-  --dropdown-menu-item-background: transparent;
-  --dropdown-menu-item-background-hover: var(--contrast-100);
-  --dropdown-menu-item-danger-background: var(--error);
-  --dropdown-menu-item-danger-background-hover: color-mix(in oklab, var(--error), white 75%);
-  --dropdown-menu-item-font-family: var(--font-family-body);
-  --dropdown-menu-seperator: var(--contrast-200);
+  --dropdown-menu-fill: var(--background);
+  --dropdown-menu-font: var(--font-body);
+  --dropdown-menu-text: var(--text-secondary);
+  --dropdown-menu-fill-hover: var(--contrast-100);
+  --dropdown-menu-text-hover: var(--text-primary);
+  --dropdown-menu-text-error: var(--error);
+  --dropdown-menu-fill-error: var(--error-background);
+  --dropdown-menu-text-error-hover: var(--error-foreground);
 }
 \`\`\`
 
-## Usage
+## Node Types
 
-### High-Level Component
-
-The \`DropdownMenu\` component uses a data-driven \`items\` array:
-
-\`\`\`tsx
-import { DropdownMenu } from '@/components/dropdown-menu';
-
-<DropdownMenu
-  label="Actions"
-  items={[
-    { type: 'item', props: { children: 'Edit', onClick: handleEdit } },
-    { type: 'item', props: { children: 'Duplicate', onClick: handleDuplicate } },
-    { type: 'separator' },
-    { type: 'item', props: { children: 'Delete', variant: 'danger' } },
-  ]}
-/>
-\`\`\`
-
-### Item Types
-
-- \`{ type: 'item', props: { ... } }\` - Standard menu item
-- \`{ type: 'checkbox', props: { checked, onCheckedChange, ... } }\` - Checkbox item
-- \`{ type: 'separator' }\` - Visual separator
-- \`{ type: 'group', items: [...] }\` - Group of related items
-- \`{ type: 'sub', trigger: { props }, content: { items } }\` - Submenu
-
-### Custom Trigger
-
-Pass a custom \`trigger\` element. Default is an ellipsis icon button:
-
-\`\`\`tsx
-<DropdownMenu
-  label="Account"
-  trigger={<Button>Open Menu</Button>}
-  items={[...]}
-/>
-\`\`\`
-
-### Custom Trigger Icon
-
-Customize the default trigger icon using the \`triggerIcon\` prop with \`asChild\`:
-
-\`\`\`tsx
-<DropdownMenu
-  label="Actions"
-  triggerIcon={{
-    asChild: true,
-    children: <MoreVerticalIcon size={20} />,
-  }}
-  items={[...]}
-/>
-\`\`\`
-
-The \`TriggerIcon\` primitive is also available for composable usage:
-
-\`\`\`tsx
-<DropdownMenuPrimitive.TriggerIcon asChild>
-  <MyCustomIcon />
-</DropdownMenuPrimitive.TriggerIcon>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as DropdownMenu from '@/components/dropdown-menu';
-import { Button } from '@/components/button';
-
-<DropdownMenu.Root>
-  <DropdownMenu.Trigger asChild>
-    <Button>Open</Button>
-  </DropdownMenu.Trigger>
-  <DropdownMenu.Portal>
-    <DropdownMenu.Content>
-      <DropdownMenu.ScrollArea>
-        <DropdownMenu.Label>Actions</DropdownMenu.Label>
-        <DropdownMenu.Item>Edit</DropdownMenu.Item>
-        <DropdownMenu.Item>Duplicate</DropdownMenu.Item>
-        <DropdownMenu.Separator />
-        <DropdownMenu.Item variant="danger">Delete</DropdownMenu.Item>
-      </DropdownMenu.ScrollArea>
-    </DropdownMenu.Content>
-  </DropdownMenu.Portal>
-</DropdownMenu.Root>
-\`\`\`
+- \`{ type: 'item', props: { ... } }\` — Standard menu item
+- \`{ type: 'checkbox', props: { checked, onCheckedChange, ... } }\` — Checkbox item
+- \`{ type: 'separator' }\` — Visual separator
+- \`{ type: 'group', items: [...] }\` — Group of related items
+- \`{ type: 'sub', trigger: { props }, content: { items } }\` — Submenu
         `,
       },
     },
@@ -141,27 +54,27 @@ import { Button } from '@/components/button';
     align: {
       control: 'select',
       options: ['start', 'center', 'end'],
-      description: 'Alignment of the dropdown relative to the trigger',
+      description: 'Dropdown alignment relative to trigger',
     },
     sideOffset: {
       control: 'number',
-      description: 'Offset from the trigger in pixels',
+      description: 'Offset from trigger in pixels',
     },
     showScrollArea: {
       control: 'boolean',
-      description: 'Whether to enable scroll area for long menus',
+      description: 'Enable scroll area for long menus',
     },
     trigger: {
       control: false,
-      description: 'Custom trigger element (default: ellipsis icon button)',
+      description: 'Custom trigger element (default: ellipsis icon)',
     },
     triggerIcon: {
       control: false,
-      description: 'Custom trigger icon with asChild support',
+      description: 'Custom trigger icon with `asChild` support',
     },
-    items: {
+    nodes: {
       control: false,
-      description: 'Array of menu items (item, checkbox, separator, group, sub)',
+      description: 'Array of menu nodes (item, checkbox, separator, group, sub)',
     },
   },
 };
@@ -169,11 +82,17 @@ import { Button } from '@/components/button';
 export default meta;
 type Story = StoryObj<DropdownMenuProps>;
 
-// Default dropdown menu
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Dropdown with items and a danger action.',
+      },
+    },
+  },
   args: {
     label: 'Actions',
-    items: [
+    nodes: [
       {
         type: 'item',
         props: {
@@ -218,11 +137,17 @@ export const Default: Story = {
   },
 };
 
-// With submenu
 export const WithSubmenu: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `type: "sub"` for nested menus.',
+      },
+    },
+  },
   args: {
     label: 'More Options',
-    items: [
+    nodes: [
       {
         type: 'item',
         props: {
@@ -292,12 +217,18 @@ export const WithSubmenu: Story = {
   },
 };
 
-// With checkbox items
 export const WithCheckboxItems: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `type: "checkbox"` for toggleable options with a custom trigger.',
+      },
+    },
+  },
   args: {
     label: 'View Options',
     trigger: <Button size="small">View Options</Button>,
-    items: [
+    nodes: [
       {
         type: 'checkbox',
         props: {
@@ -326,15 +257,21 @@ export const WithCheckboxItems: Story = {
   },
 };
 
-// Custom trigger icon
 export const CustomTriggerIcon: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `triggerIcon` with `asChild` to customize the default trigger icon.',
+      },
+    },
+  },
   args: {
     label: 'Actions',
     triggerIcon: {
       asChild: true,
       children: <MoreVerticalIcon size={20} />,
     },
-    items: [
+    nodes: [
       {
         type: 'item',
         props: {
@@ -379,8 +316,36 @@ export const CustomTriggerIcon: Story = {
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitives to build custom dropdown menus.',
+      },
+      source: {
+        code: `
+import * as DropdownMenuPrimitive from '@/components/dropdown-menu/primitives';
+
+<DropdownMenuPrimitive.Root>
+  <DropdownMenuPrimitive.Trigger asChild>
+    <Button size="small">Open Menu</Button>
+  </DropdownMenuPrimitive.Trigger>
+  <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Content>
+      <DropdownMenuPrimitive.ScrollArea>
+        <DropdownMenuPrimitive.Label>Actions</DropdownMenuPrimitive.Label>
+        <DropdownMenuPrimitive.Item>Edit</DropdownMenuPrimitive.Item>
+        <DropdownMenuPrimitive.Item>Duplicate</DropdownMenuPrimitive.Item>
+        <DropdownMenuPrimitive.Separator />
+        <DropdownMenuPrimitive.Item variant="danger">Delete</DropdownMenuPrimitive.Item>
+      </DropdownMenuPrimitive.ScrollArea>
+    </DropdownMenuPrimitive.Content>
+  </DropdownMenuPrimitive.Portal>
+</DropdownMenuPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <DropdownMenuPrimitive.Root>
       <DropdownMenuPrimitive.Trigger asChild>
diff --git a/src/components/favorite/favorite.tsx b/src/components/favorite/favorite.tsx
index 0df6aac..91ae2dc 100644
--- a/src/components/favorite/favorite.tsx
+++ b/src/components/favorite/favorite.tsx
@@ -17,11 +17,8 @@ export interface FavoriteProps {
  *
  * ```css
  * :root {
- *   --favorite-focus: var(--brand);
- *   --favorite-border: var(--contrast-100);
- *   --favorite-icon: var(--foreground);
- *   --favorite-on-background: var(--contrast-100);
- *   --favorite-off-border: var(--contrast-200);
+ *   --favorite-fill: var(--contrast-100);
+ *   --favorite-fill-icon: var(--foreground);
  * }
  * ```
  */
diff --git a/src/components/favorite/primitives/favorite-root.tsx b/src/components/favorite/primitives/favorite-root.tsx
index 138561d..9daeb36 100644
--- a/src/components/favorite/primitives/favorite-root.tsx
+++ b/src/components/favorite/primitives/favorite-root.tsx
@@ -9,13 +9,7 @@ export function FavoriteRoot({ children, className, ...props }: FavoriteRootProp
   return (
     <Toggle.Root
       className={cn(
-        'group/favorite relative flex h-[50px] w-[50px] shrink-0 cursor-pointer items-center justify-center rounded-full border border-[var(--favorite-border,var(--contrast-100))] text-[var(--favorite-icon,var(--foreground))] transition duration-300',
-        // Hover state (off)
-        'data-[state=off]:hover:border-[var(--favorite-off-border,var(--contrast-200))]',
-        // Focus state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--favorite-focus,var(--brand))]',
-        // On state
-        'data-[state=on]:bg-[var(--favorite-on-background,var(--contrast-100))]',
+        'focus-primary group/favorite relative flex h-[50px] w-[50px] shrink-0 cursor-pointer items-center justify-center rounded-full border border-[--border-subtle] text-[--favorite-fill-icon,var(--foreground)] transition duration-300 data-[state=on]:bg-[--favorite-fill,var(--contrast-100)] data-[state=off]:hover:border-[--border]',
         className,
       )}
       data-slot="favorite-root"
diff --git a/src/components/favorite/storybook/favorite.stories.tsx b/src/components/favorite/storybook/favorite.stories.tsx
index 2266df3..f3d456a 100644
--- a/src/components/favorite/storybook/favorite.stories.tsx
+++ b/src/components/favorite/storybook/favorite.stories.tsx
@@ -19,56 +19,9 @@ A toggle button for marking items as favorites. Features an animated heart icon
 
 \`\`\`css
 :root {
-  --favorite-focus: var(--brand);
-  --favorite-border: var(--contrast-100);
-  --favorite-icon: var(--foreground);
-  --favorite-on-background: var(--contrast-100);
-  --favorite-off-border: var(--contrast-200);
+  --favorite-fill-icon: var(--foreground);
+  --favorite-fill: var(--contrast-100);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Favorite\` component is controlled via \`checked\` and \`setChecked\`:
-
-\`\`\`tsx
-import { Favorite } from '@/components/favorite';
-import { useState } from 'react';
-
-function Example() {
-  const [isFavorite, setIsFavorite] = useState(false);
-
-  return <Favorite checked={isFavorite} setChecked={setIsFavorite} />;
-}
-\`\`\`
-
-### Custom Icon
-
-Use the \`icon\` prop with \`asChild\` to provide a custom icon:
-
-\`\`\`tsx
-import { Favorite } from '@/components/favorite';
-import { Heart } from 'lucide-react';
-
-<Favorite
-  checked={checked}
-  setChecked={setChecked}
-  icon={{ asChild: true, children: <Heart size={20} /> }}
-/>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Favorite from '@/components/favorite';
-
-<Favorite.Root pressed={checked} onPressedChange={setChecked}>
-  <Favorite.Heart />
-</Favorite.Root>
 \`\`\`
         `,
       },
@@ -86,7 +39,7 @@ import * as Favorite from '@/components/favorite';
     },
     icon: {
       control: false,
-      description: 'Custom icon configuration with asChild support',
+      description: 'Custom icon with `asChild` support for rendering custom icons',
     },
   },
 };
@@ -95,8 +48,21 @@ export default meta;
 
 type Story = StoryObj<FavoriteProps>;
 
-// Default controlled favorite
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A controlled favorite toggle. Click to see the heart fill animation.',
+      },
+      source: {
+        code: `
+const [checked, setChecked] = useState(false);
+
+<Favorite checked={checked} setChecked={setChecked} />
+        `,
+      },
+    },
+  },
   render: () => {
     const [checked, setChecked] = useState(false);
 
@@ -104,8 +70,25 @@ export const Default: Story = {
   },
 };
 
-// With custom icon
 export const WithCustomIcon: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use the `icon` prop with `asChild` to provide a custom icon.',
+      },
+      source: {
+        code: `
+const [checked, setChecked] = useState(false);
+
+<Favorite
+  checked={checked}
+  setChecked={setChecked}
+  icon={{ asChild: true, children: <Heart size={20} /> }}
+/>
+        `,
+      },
+    },
+  },
   render: () => {
     const [checked, setChecked] = useState(false);
 
@@ -119,8 +102,23 @@ export const WithCustomIcon: Story = {
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitive components for custom layouts.',
+      },
+      source: {
+        code: `
+const [checked, setChecked] = useState(false);
+
+<FavoritePrimitive.Root onPressedChange={setChecked} pressed={checked}>
+  <FavoritePrimitive.Heart />
+</FavoritePrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => {
     const [checked, setChecked] = useState(false);
 
diff --git a/src/components/field/primitives/field-description.tsx b/src/components/field/primitives/field-description.tsx
index fbb300a..da6d9cd 100644
--- a/src/components/field/primitives/field-description.tsx
+++ b/src/components/field/primitives/field-description.tsx
@@ -8,7 +8,7 @@ export function FieldDescription({ className, children, ...props }: FieldDescrip
   return (
     <p
       className={cn(
-        'text-sm font-normal text-[var(--field-description,var(--contrast-500))] [font-family:var(--field-description-font-family,var(--font-family-body))]',
+        'text-sm text-[--field-text-secondary,var(--font-text-secondary)] [font-family:var(--field-font-description,var(--font-body))]',
         className,
       )}
       data-slot="field-description"
diff --git a/src/components/field/primitives/field-error.tsx b/src/components/field/primitives/field-error.tsx
index 40bf875..47a4932 100644
--- a/src/components/field/primitives/field-error.tsx
+++ b/src/components/field/primitives/field-error.tsx
@@ -14,7 +14,7 @@ export function FieldError({ className, children, icon, ...props }: FieldErrorPr
   return (
     <div
       className={cn(
-        'flex items-center gap-1 text-xs text-[var(--field-error,var(--error))]',
+        'flex items-center gap-1 text-xs text-[--field-text-error,var(--error)]',
         className,
       )}
       data-slot="field-error"
diff --git a/src/components/field/primitives/field-hint.tsx b/src/components/field/primitives/field-hint.tsx
index d19cb35..2a72da0 100644
--- a/src/components/field/primitives/field-hint.tsx
+++ b/src/components/field/primitives/field-hint.tsx
@@ -8,7 +8,7 @@ export function FieldHint({ className, children, ...props }: FieldHintProps) {
   return (
     <p
       className={cn(
-        'text-xs font-medium text-[var(--field-hint,var(--contrast-500))] [font-family:var(--field-hint-font-family,var(--font-family-body))]',
+        'text-xs font-medium text-[--field-text-secondary,var(--text-secondary)] [font-family:var(--field-font-hint,var(--font-body))]',
         className,
       )}
       data-slot="field-hint"
diff --git a/src/components/field/primitives/field-legend.tsx b/src/components/field/primitives/field-legend.tsx
index de4705f..21b6c9a 100644
--- a/src/components/field/primitives/field-legend.tsx
+++ b/src/components/field/primitives/field-legend.tsx
@@ -8,7 +8,7 @@ export function FieldLegend({ className, children, ...props }: FieldLegendProps)
   return (
     <legend
       className={cn(
-        'mb-1 text-2xl font-medium text-[var(--field-legend,var(--foreground))] [font-family:var(--field-legend-font-family,var(--font-family-heading))]',
+        'mb-1 text-2xl font-medium text-[--field-text-primary,var(--text-secondary)] [font-family:var(--field-font-legend,var(--font-heading))]',
         className,
       )}
       data-slot="field-legend"
diff --git a/src/components/field/primitives/field-separator.tsx b/src/components/field/primitives/field-separator.tsx
index 4e7cb9e..6fc7896 100644
--- a/src/components/field/primitives/field-separator.tsx
+++ b/src/components/field/primitives/field-separator.tsx
@@ -7,10 +7,7 @@ export type FieldSeparatorProps = ComponentProps<'hr'>;
 export function FieldSeparator({ className, ...props }: FieldSeparatorProps) {
   return (
     <hr
-      className={cn(
-        'my-8 h-px border-0 bg-[var(--field-separator,var(--contrast-200))]',
-        className,
-      )}
+      className={cn('my-8 h-px border-0 bg-[--border-subtle]', className)}
       data-slot="field-separator"
       {...props}
     />
diff --git a/src/components/field/storybook/field.stories.tsx b/src/components/field/storybook/field.stories.tsx
index c689947..f4d0718 100644
--- a/src/components/field/storybook/field.stories.tsx
+++ b/src/components/field/storybook/field.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import type { ComponentType } from 'react';
 
 import { Checkbox } from '@/components/checkbox';
 import * as Field from '@/components/field/primitives';
@@ -8,87 +7,68 @@ import { Input } from '@/components/input';
 const meta: Meta = {
   title: 'Components/Field',
   parameters: {
-    layout: 'fullscreen',
+    layout: 'padded',
     docs: {
       description: {
         component: `
-A flexible form field component system that provides structure and styling for labels, descriptions, hints, errors, and field grouping. Use these primitives to create accessible, well-structured forms with consistent styling.
+A composable form field system that provides structure and styling for labels, descriptions, hints, errors, and field grouping. Use these primitives to create accessible, well-structured forms with consistent styling.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --field-legend: var(--foreground);
-  --field-legend-font-family: var(--font-family-heading);
-  --field-description: var(--contrast-500);
-  --field-description-font-family: var(--font-family-body);
-  --field-hint: var(--contrast-500);
-  --field-hint-font-family: var(--font-family-body);
-  --field-error: var(--error);
-  --field-separator: var(--contrast-200);
+  --field-text-primary: var(--text-secondary);
+  --field-text-secondary: var(--text-secondary);
+  --field-font-legend: var(--font-heading);
+  --field-font-description: var(--font-body);
+  --field-font-hint: var(--font-body);
+  --field-text-error: var(--error);
 }
 \`\`\`
 
-## API
-
-### Field.Set
-A \`<fieldset>\` wrapper for grouping related fields.
-
-### Field.Legend
-A \`<legend>\` element for describing a fieldset.
-
-### Field.Description
-A paragraph element for providing additional context about a field or fieldset.
-
-### Field.Group
-A container for organizing multiple field items with consistent spacing.
-
-### Field.Item
-A wrapper for individual form fields, supporting both vertical and horizontal orientations.
-
-**Props:**
-- \`orientation\`: "vertical" (default) | "horizontal" - Controls the layout direction
-
-### Field.Label
-A \`<label>\` element for field labels.
-
-### Field.Hint
-A small text element for providing helpful hints about a field.
-
-### Field.Error
-An error message component with an optional icon.
-
-**Props:**
-- \`icon.asChild\`: boolean - Use a custom icon component
-- \`icon.children\`: ReactNode - Custom icon element
-
-### Field.ErrorIcon
-The default error icon, customizable via the icon prop.
-
-### Field.Separator
-A horizontal rule for visually separating field sections.
+## Primitives
+
+| Primitive           | Description                                                     |
+|---------------------|-----------------------------------------------------------------|
+| \`Field.Set\`       | A \`<fieldset>\` wrapper for grouping related fields.           |
+| \`Field.Legend\`    | A \`<legend>\` element for describing a fieldset.               |
+| \`Field.Description\`| A paragraph for providing additional context.                   |
+| \`Field.Group\`     | Container for organizing multiple field items with spacing.     |
+| \`Field.Item\`      | Wrapper for individual fields (\`orientation\`: vertical/horizontal). |
+| \`Field.Label\`     | A \`<label>\` element for field labels.                         |
+| \`Field.Hint\`      | Small text for providing helpful hints.                         |
+| \`Field.Error\`     | Error message with optional icon (\`icon.asChild\`, \`icon.children\`). |
+| \`Field.ErrorIcon\` | The default error icon, customizable via the icon prop.         |
+| \`Field.Separator\` | Horizontal rule for visually separating sections.               |
         `,
       },
     },
   },
   tags: ['autodocs'],
-  decorators: [
-    (Story: ComponentType) => (
-      <div className="mx-auto max-w-2xl bg-background px-6 py-8">
-        <Story />
-      </div>
-    ),
-  ],
+  decorators: [(Story) => <div className="mx-auto max-w-md">{Story()}</div>],
 };
 
 export default meta;
 
 type Story = StoryObj;
 
-/**
- * A simple single field example showing label, input, and hint text.
- */
-export const Basic: Story = {
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A simple field with label, input, and hint text.',
+      },
+      source: {
+        code: `
+<Field.Item>
+  <Field.Label htmlFor="email">Email</Field.Label>
+  <Input id="email" type="email" placeholder="you@example.com" />
+  <Field.Hint>We'll never share your email with anyone else.</Field.Hint>
+</Field.Item>
+        `,
+      },
+    },
+  },
   render: () => (
     <Field.Item>
       <Field.Label htmlFor="email">Email</Field.Label>
@@ -98,38 +78,84 @@ export const Basic: Story = {
   ),
 };
 
-/**
- * A field showing an error state with an error message and icon.
- */
 export const WithError: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A field showing an error state with an error message and icon.',
+      },
+      source: {
+        code: `
+<Field.Item>
+  <Field.Label htmlFor="username">Username</Field.Label>
+  <Input id="username" type="text" defaultValue="jo" />
+  <Field.Error>Username must be at least 3 characters long.</Field.Error>
+</Field.Item>
+        `,
+      },
+    },
+  },
   render: () => (
     <Field.Item>
       <Field.Label htmlFor="username">Username</Field.Label>
-      <Input defaultValue="john" id="username" placeholder="johndoe" type="text" />
+      <Input defaultValue="jo" id="username" type="text" />
       <Field.Error>Username must be at least 3 characters long.</Field.Error>
     </Field.Item>
   ),
 };
 
-/**
- * A field with a horizontal layout, commonly used for checkboxes and switches.
- */
 export const HorizontalOrientation: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use `orientation="horizontal"` for inline layouts, commonly used for checkboxes and switches.',
+      },
+      source: {
+        code: `
+<Field.Item orientation="horizontal">
+  <Checkbox id="newsletter" />
+  <Field.Label htmlFor="newsletter">Subscribe to newsletter</Field.Label>
+</Field.Item>
+        `,
+      },
+    },
+  },
   render: () => (
     <Field.Item orientation="horizontal">
       <Checkbox id="newsletter" />
-      <div className="flex flex-col gap-1">
-        <Field.Label htmlFor="newsletter">Subscribe to newsletter</Field.Label>
-        <Field.Hint>Receive weekly updates about new products and offers.</Field.Hint>
-      </div>
+      <Field.Label htmlFor="newsletter">Subscribe to newsletter</Field.Label>
     </Field.Item>
   ),
 };
 
-/**
- * Multiple related fields grouped together with a legend and description.
- */
 export const FieldSet: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use `Field.Set` with `Field.Legend` and `Field.Description` to group related fields together.',
+      },
+      source: {
+        code: `
+<Field.Set>
+  <Field.Legend>Shipping Address</Field.Legend>
+  <Field.Description>Please provide your shipping address for delivery.</Field.Description>
+  <Field.Group>
+    <Field.Item>
+      <Field.Label htmlFor="address">Street Address</Field.Label>
+      <Input id="address" type="text" placeholder="123 Main St" />
+    </Field.Item>
+    <Field.Item>
+      <Field.Label htmlFor="city">City</Field.Label>
+      <Input id="city" type="text" placeholder="San Francisco" />
+    </Field.Item>
+  </Field.Group>
+</Field.Set>
+        `,
+      },
+    },
+  },
   render: () => (
     <Field.Set>
       <Field.Legend>Shipping Address</Field.Legend>
@@ -139,187 +165,67 @@ export const FieldSet: Story = {
           <Field.Label htmlFor="address">Street Address</Field.Label>
           <Input id="address" placeholder="123 Main St" type="text" />
         </Field.Item>
-        <div className="grid grid-cols-2 gap-4">
-          <Field.Item>
-            <Field.Label htmlFor="city">City</Field.Label>
-            <Input id="city" placeholder="San Francisco" type="text" />
-          </Field.Item>
-          <Field.Item>
-            <Field.Label htmlFor="zip">ZIP Code</Field.Label>
-            <Input id="zip" placeholder="94102" type="text" />
-          </Field.Item>
-        </div>
+        <Field.Item>
+          <Field.Label htmlFor="city">City</Field.Label>
+          <Input id="city" placeholder="San Francisco" type="text" />
+        </Field.Item>
       </Field.Group>
     </Field.Set>
   ),
 };
 
-/**
- * A fieldset with multiple groups separated by visual dividers.
- */
-export const WithSeparators: Story = {
+export const WithSeparator: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `Field.Separator` to visually divide sections within a fieldset.',
+      },
+      source: {
+        code: `
+<Field.Set>
+  <Field.Legend>Account Settings</Field.Legend>
+  <Field.Group>
+    <Field.Item>
+      <Field.Label htmlFor="display-name">Display Name</Field.Label>
+      <Input id="display-name" type="text" placeholder="John Doe" />
+    </Field.Item>
+  </Field.Group>
+  <Field.Separator />
+  <Field.Group>
+    <Field.Item orientation="horizontal">
+      <Checkbox id="email-notifications" defaultChecked />
+      <Field.Label htmlFor="email-notifications">Email Notifications</Field.Label>
+    </Field.Item>
+    <Field.Item orientation="horizontal">
+      <Checkbox id="marketing" />
+      <Field.Label htmlFor="marketing">Marketing Emails</Field.Label>
+    </Field.Item>
+  </Field.Group>
+</Field.Set>
+        `,
+      },
+    },
+  },
   render: () => (
     <Field.Set>
       <Field.Legend>Account Settings</Field.Legend>
-      <Field.Description>
-        Manage your account preferences and notification settings.
-      </Field.Description>
       <Field.Group>
         <Field.Item>
           <Field.Label htmlFor="display-name">Display Name</Field.Label>
           <Input id="display-name" placeholder="John Doe" type="text" />
-          <Field.Hint>This is how your name will appear to others.</Field.Hint>
-        </Field.Item>
-        <Field.Item>
-          <Field.Label htmlFor="bio">Bio</Field.Label>
-          <Input id="bio" placeholder="Tell us about yourself" type="text" />
         </Field.Item>
       </Field.Group>
       <Field.Separator />
       <Field.Group>
         <Field.Item orientation="horizontal">
           <Checkbox defaultChecked id="email-notifications" />
-          <div className="flex flex-col gap-1">
-            <Field.Label htmlFor="email-notifications">Email Notifications</Field.Label>
-            <Field.Hint>Receive email updates about your account activity.</Field.Hint>
-          </div>
+          <Field.Label htmlFor="email-notifications">Email Notifications</Field.Label>
         </Field.Item>
         <Field.Item orientation="horizontal">
           <Checkbox id="marketing" />
-          <div className="flex flex-col gap-1">
-            <Field.Label htmlFor="marketing">Marketing Emails</Field.Label>
-            <Field.Hint>Get the latest news and special offers.</Field.Hint>
-          </div>
-        </Field.Item>
-      </Field.Group>
-    </Field.Set>
-  ),
-};
-
-/**
- * A nested field structure showing how groups can be organized within each other.
- */
-export const NestedGroups: Story = {
-  render: () => (
-    <Field.Set>
-      <Field.Legend>Payment Information</Field.Legend>
-      <Field.Description>Enter your payment details to complete your purchase.</Field.Description>
-      <Field.Group>
-        <Field.Item>
-          <Field.Label htmlFor="card-name">Cardholder Name</Field.Label>
-          <Input id="card-name" placeholder="John Doe" type="text" />
-        </Field.Item>
-        <Field.Item>
-          <Field.Label htmlFor="card-number">Card Number</Field.Label>
-          <Input id="card-number" placeholder="1234 5678 9012 3456" type="text" />
-        </Field.Item>
-        <Field.Group>
-          <div className="grid grid-cols-2 gap-4">
-            <Field.Item>
-              <Field.Label htmlFor="expiry">Expiry Date</Field.Label>
-              <Input id="expiry" placeholder="MM/YY" type="text" />
-            </Field.Item>
-            <Field.Item>
-              <Field.Label htmlFor="cvv">CVV</Field.Label>
-              <Input id="cvv" placeholder="123" type="text" />
-            </Field.Item>
-          </div>
-        </Field.Group>
-        <Field.Item orientation="horizontal">
-          <Checkbox id="save-card" />
-          <Field.Label htmlFor="save-card">Save this card for future purchases</Field.Label>
-        </Field.Item>
-      </Field.Group>
-    </Field.Set>
-  ),
-};
-
-/**
- * Use the composable primitives to build custom field layouts with full control over structure and styling.
- */
-export const ComposableAnatomy: Story = {
-  render: () => (
-    <Field.Set>
-      <Field.Legend>Contact Form</Field.Legend>
-      <Field.Description>
-        We'd love to hear from you. Fill out the form below to get in touch.
-      </Field.Description>
-      <Field.Group>
-        <Field.Item>
-          <Field.Label htmlFor="name">Name</Field.Label>
-          <Input id="name" placeholder="Your name" type="text" />
-        </Field.Item>
-        <Field.Item>
-          <Field.Label htmlFor="email-contact">Email</Field.Label>
-          <Input id="email-contact" placeholder="you@example.com" type="email" />
-          <Field.Hint>We'll respond within 24 hours.</Field.Hint>
-        </Field.Item>
-        <Field.Item>
-          <Field.Label htmlFor="message">Message</Field.Label>
-          <Input id="message" placeholder="How can we help?" type="text" />
+          <Field.Label htmlFor="marketing">Marketing Emails</Field.Label>
         </Field.Item>
       </Field.Group>
     </Field.Set>
   ),
-  parameters: {
-    docs: {
-      description: {
-        story: `
-Use the composable primitives to build custom field layouts:
-
-\`\`\`tsx
-import * as Field from '@/components/field/primitives';
-import { Input } from '@/components/input';
-
-// Basic vertical field
-<Field.Item>
-  <Field.Label htmlFor="field-id">Label</Field.Label>
-  <Input id="field-id" type="text" />
-  <Field.Hint>Optional hint text</Field.Hint>
-</Field.Item>
-
-// Horizontal field (for checkboxes, switches)
-<Field.Item orientation="horizontal">
-  <Checkbox id="checkbox-id" />
-  <Field.Label htmlFor="checkbox-id">Label</Field.Label>
-</Field.Item>
-
-// Field with error
-<Field.Item>
-  <Field.Label htmlFor="field-id">Label</Field.Label>
-  <Input id="field-id" type="text" />
-  <Field.Error>Error message</Field.Error>
-</Field.Item>
-
-// Multiple fields with fieldset
-<Field.Set>
-  <Field.Legend>Section Title</Field.Legend>
-  <Field.Description>Section description</Field.Description>
-  <Field.Group>
-    <Field.Item>
-      <Field.Label htmlFor="field-1">Field 1</Field.Label>
-      <Input id="field-1" type="text" />
-    </Field.Item>
-    <Field.Item>
-      <Field.Label htmlFor="field-2">Field 2</Field.Label>
-      <Input id="field-2" type="text" />
-    </Field.Item>
-  </Field.Group>
-</Field.Set>
-
-// Separated groups
-<Field.Set>
-  <Field.Group>
-    {/* First group of fields */}
-  </Field.Group>
-  <Field.Separator />
-  <Field.Group>
-    {/* Second group of fields */}
-  </Field.Group>
-</Field.Set>
-\`\`\`
-        `,
-      },
-    },
-  },
 };
diff --git a/src/components/file-input/file-input.tsx b/src/components/file-input/file-input.tsx
index 9455f12..a262462 100644
--- a/src/components/file-input/file-input.tsx
+++ b/src/components/file-input/file-input.tsx
@@ -46,6 +46,26 @@ function formatBytes(bytes: number) {
   return `${(bytes / 1024 ** i).toFixed(i ? 1 : 0)} ${sizes[i]}`;
 }
 
+/**
+ * This component supports various CSS variables for theming. Here's a comprehensive list, along
+ * with their default values:
+ *
+ * ```css
+ * :root {
+ *   --file-input-fill: var(--form-fill);
+ *   --file-input-fill-hover: var(--form-fill-hover);
+ *   --file-input-fill-disabled: var(--form-fill);
+ *   --file-input-fill-dragging: var(--success-background);
+ *   --file-input-fill-progress: var(--brand);
+ *   --file-input-fill-icon: var(--form-fill-icon);
+ *   --file-input-text-primary: var(--form-text-primary);
+ *   --file-input-text-secondary: var(--form-text-secondary);
+ *   --file-input-text-error: var(--error);
+ *   --file-input-font-message: var(--font-body);
+ *   --file-input-font-header: var(--font-body);
+ * }
+ * ```
+ */
 export function FileInput({
   id,
   className,
diff --git a/src/components/file-input/primitives/file-input-dropzone-error.tsx b/src/components/file-input/primitives/file-input-dropzone-error.tsx
index 75b4302..5304208 100644
--- a/src/components/file-input/primitives/file-input-dropzone-error.tsx
+++ b/src/components/file-input/primitives/file-input-dropzone-error.tsx
@@ -21,7 +21,7 @@ export function FileInputDropzoneError({
   return (
     <p
       className={cn(
-        'font-[family-name:var(--file-input-dropzone-message-font-family,var(--font-family-body))] text-sm font-normal text-[var(--file-input-dropzone-message-error,var(--error))]',
+        'text-sm font-normal text-[--file-input-text-error,var(--error)] [font-family:var(--file-input-font-message,var(--font-body))]',
         className,
       )}
       data-slot="file-input-dropzone-error"
diff --git a/src/components/file-input/primitives/file-input-dropzone-hint.tsx b/src/components/file-input/primitives/file-input-dropzone-hint.tsx
index f100649..400fb4e 100644
--- a/src/components/file-input/primitives/file-input-dropzone-hint.tsx
+++ b/src/components/file-input/primitives/file-input-dropzone-hint.tsx
@@ -21,9 +21,9 @@ export function FileInputDropzoneHint({
   return (
     <p
       className={cn(
-        'font-[family-name:var(--file-input-dropzone-message-font-family,var(--font-family-body))] text-sm font-normal text-[var(--file-input-dropzone-message,var(--contrast-500))]',
+        'text-sm font-normal text-[--file-input-text-secondary,var(--form-text-secondary)] [font-family:var(--file-input-font-message,var(--font-body))]',
         // Disabled state
-        'group-aria-disabled/file-input:text-[var(--file-input-dropzone-message-disabled,color-mix(in_oklab,var(--contrast-500)_70%,transparent))]',
+        'group-aria-disabled/file-input:text-[color-mix(in_oklab,var(--file-input-text-secondary,var(--form-text-secondary))_70%,transparent)]',
         className,
       )}
       data-slot="file-input-dropzone-hint"
diff --git a/src/components/file-input/primitives/file-input-dropzone.tsx b/src/components/file-input/primitives/file-input-dropzone.tsx
index 0306e52..81036f6 100644
--- a/src/components/file-input/primitives/file-input-dropzone.tsx
+++ b/src/components/file-input/primitives/file-input-dropzone.tsx
@@ -97,18 +97,16 @@ export function FileInputDropzone({ children, className, ...props }: FileInputDr
       aria-disabled={disabled === true ? true : undefined}
       aria-invalid={invalid === true ? true : undefined}
       className={cn(
-        'min-h-19 flex cursor-pointer select-none flex-col items-center justify-center gap-1.5 rounded-lg border-[1.5px] border-dashed border-[var(--file-input-dropzone-border,var(--contrast-200))] bg-[var(--file-input-dropzone-background,var(--background))] p-4 transition-colors duration-300 ease-in-out',
+        'focus-primary min-h-19 flex cursor-pointer select-none flex-col items-center justify-center gap-1.5 rounded-lg border-[1.5px] border-dashed border-[--border] bg-[--file-input-fill,var(--form-fill)] p-4 transition-colors duration-300 ease-in-out',
         // Hover state
-        'hover:border-[var(--file-input-dropzone-border-hover,var(--foreground))] hover:bg-[var(--file-input-dropzone-background-hover,var(--contrast-100))]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--file-input-focus,var(--brand))]',
+        'hover:border-[--border-hover] hover:bg-[--file-input-fill-hover,var(--form-fill-hover)]',
         // Disabled state
-        'group-aria-disabled/file-input:cursor-not-allowed group-aria-disabled/file-input:border-[var(--file-input-dropzone-border-disabled,color-mix(in_oklab,var(--contrast-200)_70%,transparent))] group-aria-disabled/file-input:bg-[var(--file-input-dropzone-background-disabled,var(--background))]',
+        'group-aria-disabled/file-input:cursor-not-allowed group-aria-disabled/file-input:border-[var(color-mix(in_oklab,var(--border)_70%,transparent))] group-aria-disabled/file-input:bg-[--file-input-fill-disabled,var(--form-fill)]',
         'group-aria-disabled/file-input:focus-visible:outline-0',
         // Invalid state
-        'group-aria-invalid/file-input:border-[var(--file-input-dropzone-border-error,var(--error))]',
+        'group-aria-invalid/file-input:border-[--border-error]',
         // Dragging state
-        'data-[dragging]:border-[var(--file-input-dropzone-border-dragging,var(--foreground))] data-[dragging]:bg-[var(--file-input-dropzone-background-dragging,color-mix(in_oklab,var(--success),white_75%))]',
+        'data-[dragging]:border-[--border-checked] data-[dragging]:data-[dragging]:bg-[--file-input-fill-dragging,var(--success-background)]',
         // Container queries
         '@sm:flex-row',
         className,
diff --git a/src/components/file-input/primitives/file-input-error.tsx b/src/components/file-input/primitives/file-input-error.tsx
index a383e8d..9098ac6 100644
--- a/src/components/file-input/primitives/file-input-error.tsx
+++ b/src/components/file-input/primitives/file-input-error.tsx
@@ -12,10 +12,7 @@ export function FileInputError({ className, children, ...props }: FileInputError
 
   return (
     <p
-      className={cn(
-        'text-xs font-normal text-[var(--file-input-item-status-error,var(--error))]',
-        className,
-      )}
+      className={cn('text-xs text-[--file-input-text-error,var(--error)]', className)}
       data-slot="file-input-error"
       id={`${generatedId}-error`}
       {...props}
diff --git a/src/components/file-input/primitives/file-input-header.tsx b/src/components/file-input/primitives/file-input-header.tsx
index 2407eeb..5c47a61 100644
--- a/src/components/file-input/primitives/file-input-header.tsx
+++ b/src/components/file-input/primitives/file-input-header.tsx
@@ -8,7 +8,7 @@ export function FileInputHeader({ className, children, ...props }: FileInputHead
   return (
     <div
       className={cn(
-        'flex items-center gap-1 font-[family-name:var(--file-input-item-name-font-family,var(--font-family-body))]',
+        'flex items-center gap-1 [font-family:var(--file-input-font-header,var(--font-body))]',
         className,
       )}
       data-slot="file-input-header"
diff --git a/src/components/file-input/primitives/file-input-icon.tsx b/src/components/file-input/primitives/file-input-icon.tsx
index b2cb2aa..2d9a2c4 100644
--- a/src/components/file-input/primitives/file-input-icon.tsx
+++ b/src/components/file-input/primitives/file-input-icon.tsx
@@ -27,23 +27,17 @@ export function FileInputIcon({ asChild = false, className, children }: FileInpu
 
   const DefaultIcon = getIconForFile(fileState.file);
 
+  const iconStyles = cn('size-4 text-[--file-input-fill-icon,var(--form-fill-icon)]', className);
+
   if (asChild) {
     return (
-      <Slot
-        className={cn('size-4 text-[var(--file-input-icon,var(--contrast-400))]', className)}
-        data-slot="file-input-icon"
-      >
+      <Slot className={iconStyles} data-slot="file-input-icon">
         {children}
       </Slot>
     );
   }
 
-  return (
-    <DefaultIcon
-      className={cn('size-4 text-[var(--file-input-icon,var(--contrast-400))]', className)}
-      data-slot="file-input-icon"
-    />
-  );
+  return <DefaultIcon className={iconStyles} data-slot="file-input-icon" />;
 }
 
 function getIconForFile(file: File): ElementType {
diff --git a/src/components/file-input/primitives/file-input-item.tsx b/src/components/file-input/primitives/file-input-item.tsx
index e085a41..33fc15d 100644
--- a/src/components/file-input/primitives/file-input-item.tsx
+++ b/src/components/file-input/primitives/file-input-item.tsx
@@ -58,11 +58,11 @@ export function FileInputItem({ className, children, file, ...props }: FileInput
         aria-invalid={status === 'error'}
         aria-labelledby={`${generatedId}-name`}
         className={cn(
-          'relative flex items-center justify-between gap-2 overflow-hidden rounded-lg border-[1.5px] border-[var(--file-input-item-border,var(--contrast-200))] p-4',
+          'relative flex items-center justify-between gap-2 overflow-hidden rounded-lg border-[1.5px] border-[--border] p-4',
           // Start animation state
           'data-[start-animation]:animate-in data-[start-animation]:fade-in-0 data-[start-animation]:slide-in-from-top-2',
           // Invalid state
-          'aria-invalid:border-[var(--file-input-item-border-error,var(--error))]',
+          'aria-invalid:border-[--border-error]',
           className,
         )}
         data-slot="file-input-item"
diff --git a/src/components/file-input/primitives/file-input-message.tsx b/src/components/file-input/primitives/file-input-message.tsx
index 853b2ab..f57514f 100644
--- a/src/components/file-input/primitives/file-input-message.tsx
+++ b/src/components/file-input/primitives/file-input-message.tsx
@@ -13,7 +13,7 @@ export function FileInputMessage({ className, children, ...props }: FileInputMes
   return (
     <p
       className={cn(
-        'mt-2 font-[family-name:var(--file-input-message-font-family,var(--font-family-body))] text-sm font-normal text-[var(--file-input-message,var(--contrast-500))]',
+        'mt-2 text-sm text-[--file-input-text-secondary,var(--form-text-secondary)] [font-family:var(--file-input-font-message,var(--font-body))]',
         className,
       )}
       data-slot="file-input-message"
diff --git a/src/components/file-input/primitives/file-input-name.tsx b/src/components/file-input/primitives/file-input-name.tsx
index f236a2c..3ab1d6b 100644
--- a/src/components/file-input/primitives/file-input-name.tsx
+++ b/src/components/file-input/primitives/file-input-name.tsx
@@ -13,7 +13,7 @@ export function FileInputName({ className, children, ...props }: FileInputNamePr
   return (
     <p
       className={cn(
-        'truncate text-sm font-semibold text-[var(--file-input-item-name,var(--foreground))]',
+        'truncate text-sm font-semibold text-[--file-input-text-primary,var(--form-text-primary)]',
         className,
       )}
       data-slot="file-input-name"
diff --git a/src/components/file-input/primitives/file-input-progress.tsx b/src/components/file-input/primitives/file-input-progress.tsx
index 10b4899..a3465fa 100644
--- a/src/components/file-input/primitives/file-input-progress.tsx
+++ b/src/components/file-input/primitives/file-input-progress.tsx
@@ -21,7 +21,7 @@ export function FileInputProgress({ className, ...props }: FileInputProgressProp
       aria-valuenow={progress}
       aria-valuetext={`${progress}%`}
       className={cn(
-        'absolute bottom-0 left-0 h-1 w-full bg-[var(--file-input-item-progress,var(--brand))] transition-transform duration-300 ease-linear',
+        'absolute bottom-0 left-0 h-1 w-full bg-[--file-input-fill-progress,var(--brand)] transition-transform duration-300 ease-linear',
         className,
       )}
       data-slot="file-input-progress"
diff --git a/src/components/file-input/primitives/file-input-remove-icon.tsx b/src/components/file-input/primitives/file-input-remove-icon.tsx
index 1ac05cd..d689b8d 100644
--- a/src/components/file-input/primitives/file-input-remove-icon.tsx
+++ b/src/components/file-input/primitives/file-input-remove-icon.tsx
@@ -17,10 +17,7 @@ export function FileInputRemoveIcon({
   className,
   children,
 }: FileInputRemoveIconProps) {
-  const iconStyles = cn(
-    'size-5 text-[var(--file-input-item-delete-icon,var(--foreground))]',
-    className,
-  );
+  const iconStyles = cn('size-5', className);
 
   if (asChild) {
     return (
diff --git a/src/components/file-input/primitives/file-input-remove.tsx b/src/components/file-input/primitives/file-input-remove.tsx
index c280b8c..d7f3160 100644
--- a/src/components/file-input/primitives/file-input-remove.tsx
+++ b/src/components/file-input/primitives/file-input-remove.tsx
@@ -2,8 +2,8 @@
 
 import type { ComponentProps } from 'react';
 
+import { Button } from '@/components/button';
 import { useFileInputItem } from '@/components/file-input';
-import { cn } from '@/lib';
 
 export type FileInputRemoveProps = ComponentProps<'button'>;
 
@@ -16,22 +16,17 @@ export function FileInputRemove({ className, children, ...props }: FileInputRemo
   } = useFileInputItem();
 
   return (
-    <button
+    <Button
       aria-label={`Remove ${name}`}
-      className={cn(
-        'inline-flex size-8 cursor-pointer items-center justify-center rounded-full transition-colors',
-        // Hover state
-        'hover:bg-[var(--file-input-item-delete-hover,var(--contrast-100))]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--file-input-focus,var(--brand))]',
-        className,
-      )}
       data-slot="file-input-remove"
       onClick={removeFile}
+      shape="circle"
+      size="x-small"
       type="button"
+      variant="ghost"
       {...props}
     >
       {children}
-    </button>
+    </Button>
   );
 }
diff --git a/src/components/file-input/primitives/file-input-status.tsx b/src/components/file-input/primitives/file-input-status.tsx
index c26b3f5..69a2aa4 100644
--- a/src/components/file-input/primitives/file-input-status.tsx
+++ b/src/components/file-input/primitives/file-input-status.tsx
@@ -13,7 +13,7 @@ export function FileInputStatus({ className, children, ...props }: FileInputStat
   return (
     <p
       className={cn(
-        'text-xs font-normal text-[var(--file-input-item-status,var(--contrast-500))]',
+        'text-xs text-[--file-input-text-secondary,var(--form-text-secondary)]',
         className,
       )}
       data-slot="file-input-status"
diff --git a/src/components/file-input/primitives/file-input-upload-icon.tsx b/src/components/file-input/primitives/file-input-upload-icon.tsx
index 7bec749..fd074ef 100644
--- a/src/components/file-input/primitives/file-input-upload-icon.tsx
+++ b/src/components/file-input/primitives/file-input-upload-icon.tsx
@@ -17,10 +17,7 @@ export function FileInputUploadIcon({
   className,
   children,
 }: FileInputUploadIconProps) {
-  const iconStyles = cn(
-    'size-5 text-[var(--file-input-trigger-icon,var(--foreground))]',
-    className,
-  );
+  const iconStyles = cn('size-5', className);
 
   if (asChild) {
     return (
diff --git a/src/components/file-input/storybook/file-input.stories.tsx b/src/components/file-input/storybook/file-input.stories.tsx
index 852dc5f..08b3c7d 100644
--- a/src/components/file-input/storybook/file-input.stories.tsx
+++ b/src/components/file-input/storybook/file-input.stories.tsx
@@ -48,42 +48,17 @@ A file upload component with drag-and-drop support, progress tracking, and file
 
 \`\`\`css
 :root {
-  /* Dropzone */
-  --file-input-dropzone-border: var(--contrast-200);
-  --file-input-dropzone-background: var(--background);
-  --file-input-dropzone-border-hover: var(--foreground);
-  --file-input-dropzone-background-hover: var(--contrast-100);
-  --file-input-dropzone-border-disabled: color-mix(in oklab, var(--contrast-200) 70%, transparent);
-  --file-input-dropzone-background-disabled: var(--background);
-  --file-input-dropzone-border-error: var(--error);
-  --file-input-dropzone-border-dragging: var(--foreground);
-  --file-input-dropzone-background-dragging: color-mix(in oklab, var(--success), white 75%);
-  --file-input-dropzone-message-font-family: var(--font-family-body);
-  --file-input-dropzone-message: var(--contrast-500);
-  --file-input-dropzone-message-disabled: color-mix(in oklab, var(--contrast-500) 70%, transparent);
-  --file-input-dropzone-message-error: var(--error);
-
-  /* Trigger */
-  --file-input-trigger-icon: var(--foreground);
-  --file-input-focus: var(--brand);
-
-  /* Message */
-  --file-input-message-font-family: var(--font-family-body);
-  --file-input-message: var(--contrast-500);
-
-  /* File Item */
-  --file-input-item-border: var(--contrast-200);
-  --file-input-item-border-error: var(--error);
-  --file-input-item-name-font-family: var(--font-family-body);
-  --file-input-item-name: var(--foreground);
-  --file-input-item-status: var(--contrast-500);
-  --file-input-item-status-error: var(--error);
-  --file-input-item-delete-hover: var(--contrast-100);
-  --file-input-item-delete-icon: var(--foreground);
-  --file-input-item-progress: var(--brand);
-
-  /* File Icon */
-  --file-input-icon: var(--contrast-400);
+  --file-input-fill: var(--form-fill);
+  --file-input-fill-hover: var(--form-fill-hover);
+  --file-input-fill-disabled: var(--form-fill);
+  --file-input-fill-dragging: var(--success-background);
+  --file-input-fill-progress: var(--brand);
+  --file-input-fill-icon: var(--form-fill-icon);
+  --file-input-text-primary: var(--form-text-primary);
+  --file-input-text-secondary: var(--form-text-secondary);
+  --file-input-text-error: var(--error);
+  --file-input-font-message: var(--font-body);
+  --file-input-font-header: var(--font-body);
 }
 \`\`\`
 
diff --git a/src/components/form-status/form-status.tsx b/src/components/form-status/form-status.tsx
index 7035fd9..0e0cc66 100644
--- a/src/components/form-status/form-status.tsx
+++ b/src/components/form-status/form-status.tsx
@@ -20,10 +20,10 @@ export interface FormStatusProps extends ComponentProps<'div'> {
  *
  * ```css
  *  :root {
- *    --form-status-background-error: var(--error-highlight);
- *    --form-status-text-error: var(--error-shadow);
- *    --form-status-background-success: var(--success-highlight);
- *    --form-status-text-success: var(--success-shadow);
+ *    --form-status-fill-error: var(--error-foreground);
+ *    --form-status-text-error: var(--error-background);
+ *    --form-status-fill-success: var(--success-foreground);
+ *    --form-status-text-success: var(--success-background);
  *  }
  * ```
  */
diff --git a/src/components/form-status/primitives/form-status-root.tsx b/src/components/form-status/primitives/form-status-root.tsx
index ea9de09..69dae51 100644
--- a/src/components/form-status/primitives/form-status-root.tsx
+++ b/src/components/form-status/primitives/form-status-root.tsx
@@ -7,9 +7,9 @@ const formStatusVariants = cva('flex items-center gap-3 rounded-xl px-4 py-3 tex
   variants: {
     type: {
       error:
-        'bg-[var(--form-status-background-error,color-mix(in_oklab,_var(--error),_white_75%))] [color:var(--form-status-text-error,color-mix(in_oklab,var(--error),black_75%))]',
+        'bg-[--form-status-fill-error,var(--error-background)] text-[--form-status-text-error,var(--error-foreground)]',
       success:
-        'bg-[var(--form-status-background-success,color-mix(in_oklab,_var(--success),_white_75%))] [color:var(--form-status-text-success,color-mix(in_oklab,var(--success),black_75%))]',
+        'bg-[--form-status-fill-success,var(--success-background)] text-[--form-status-text-success,var(--success-foreground)]',
     },
   },
   defaultVariants: {
diff --git a/src/components/form-status/storybook/form-status.stories.tsx b/src/components/form-status/storybook/form-status.stories.tsx
index d6e3456..842dcfc 100644
--- a/src/components/form-status/storybook/form-status.stories.tsx
+++ b/src/components/form-status/storybook/form-status.stories.tsx
@@ -18,58 +18,11 @@ A status message component for displaying success or error feedback in forms. Sh
 
 \`\`\`css
 :root {
-  --form-status-background-error: var(--error-highlight);
-  --form-status-text-error: var(--error-shadow);
-  --form-status-background-success: var(--success-highlight);
-  --form-status-text-success: var(--success-shadow);
+  --form-status-fill-error: var(--error-background);
+  --form-status-text-error: var(--error-foreground);
+  --form-status-fill-success: var(--success-background);
+  --form-status-text-success: var(--success-foreground);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`FormStatus\` component provides a simple API for displaying form feedback:
-
-\`\`\`tsx
-import { FormStatus } from '@/components/form-status';
-
-<FormStatus type="success">Your changes have been saved.</FormStatus>
-<FormStatus type="error">Something went wrong. Please try again.</FormStatus>
-\`\`\`
-
-### Custom Icons
-
-Use the \`successIcon\` or \`errorIcon\` props with \`asChild\` to provide custom icons:
-
-\`\`\`tsx
-import { FormStatus } from '@/components/form-status';
-import { CheckCircle } from 'lucide-react';
-
-<FormStatus
-  type="success"
-  successIcon={{ asChild: true, children: <CheckCircle size={20} /> }}
->
-  Custom icon success message
-</FormStatus>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as FormStatus from '@/components/form-status';
-
-<FormStatus.Root type="success">
-  <FormStatus.SuccessIcon />
-  Your changes have been saved.
-</FormStatus.Root>
-
-<FormStatus.Root type="error">
-  <FormStatus.ErrorIcon />
-  Something went wrong.
-</FormStatus.Root>
 \`\`\`
         `,
       },
@@ -88,21 +41,33 @@ import * as FormStatus from '@/components/form-status';
     },
     successIcon: {
       control: false,
-      description: 'Custom success icon configuration with asChild support',
+      description: 'Custom success icon configuration with `asChild` support',
     },
     errorIcon: {
       control: false,
-      description: 'Custom error icon configuration with asChild support',
+      description: 'Custom error icon configuration with `asChild` support',
     },
   },
+  decorators: [(Story) => <div className="w-80">{Story()}</div>],
 };
 
 export default meta;
 type Story = StoryObj<FormStatusProps>;
 
-// All variants
 export const Default: Story = {
-  name: 'All Variants',
+  parameters: {
+    docs: {
+      description: {
+        story: 'Success and error status messages with default icons.',
+      },
+      source: {
+        code: `
+<FormStatus type="success">Your changes have been saved successfully.</FormStatus>
+<FormStatus type="error">Something went wrong. Please try again.</FormStatus>
+        `,
+      },
+    },
+  },
   render: () => (
     <div className="flex flex-col gap-4">
       <FormStatus type="success">Your changes have been saved successfully.</FormStatus>
@@ -111,8 +76,32 @@ export const Default: Story = {
   ),
 };
 
-// With custom icons
 export const WithCustomIcons: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use the `successIcon` or `errorIcon` props with `asChild: true` to provide custom icons.',
+      },
+      source: {
+        code: `
+<FormStatus
+  type="success"
+  successIcon={{ asChild: true, children: <CheckCircle size={20} /> }}
+>
+  Custom success icon
+</FormStatus>
+
+<FormStatus
+  type="error"
+  errorIcon={{ asChild: true, children: <AlertCircle size={20} /> }}
+>
+  Custom error icon
+</FormStatus>
+        `,
+      },
+    },
+  },
   render: () => (
     <div className="flex flex-col gap-4">
       <FormStatus
@@ -128,8 +117,37 @@ export const WithCustomIcons: Story = {
   ),
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the primitive components for full control over the structure.
+
+| Primitive                       | Description                                         |
+|---------------------------------|-----------------------------------------------------|
+| \`FormStatusPrimitive.Root\`       | Container with background/text color based on type. |
+| \`FormStatusPrimitive.SuccessIcon\` | Success icon with \`asChild\` support.                |
+| \`FormStatusPrimitive.ErrorIcon\`   | Error icon with \`asChild\` support.                  |
+        `,
+      },
+      source: {
+        code: `
+import * as FormStatusPrimitive from '@/components/form-status/primitives';
+
+<FormStatusPrimitive.Root type="success">
+  <FormStatusPrimitive.SuccessIcon />
+  Using primitives for success messages.
+</FormStatusPrimitive.Root>
+
+<FormStatusPrimitive.Root type="error">
+  <FormStatusPrimitive.ErrorIcon />
+  Using primitives for error messages.
+</FormStatusPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <div className="flex flex-col gap-4">
       <FormStatusPrimitive.Root type="success">
diff --git a/src/components/icon/primitives/icon-skeleton.tsx b/src/components/icon/primitives/icon-skeleton.tsx
index d759471..c901e65 100644
--- a/src/components/icon/primitives/icon-skeleton.tsx
+++ b/src/components/icon/primitives/icon-skeleton.tsx
@@ -10,12 +10,7 @@ export function IconSkeleton({ className, size = 24 }: IconSkeletonProps) {
     <SkeletonPrimitive.Icon
       className={cn('overflow-hidden rounded-full', className)}
       data-slot="icon-skeleton"
-      icon={
-        <div
-          className="bg-[var(--skeleton,var(--contrast-300))] opacity-25"
-          style={{ width: size, height: size }}
-        />
-      }
+      icon={<div className="bg-[--fill-pending]" style={{ width: size, height: size }} />}
     />
   );
 }
diff --git a/src/components/icon/storybook/icon.stories.tsx b/src/components/icon/storybook/icon.stories.tsx
index a5240b6..0198795 100644
--- a/src/components/icon/storybook/icon.stories.tsx
+++ b/src/components/icon/storybook/icon.stories.tsx
@@ -14,45 +14,11 @@ const meta: Meta<typeof Icon> = {
     docs: {
       description: {
         component: `
-A dynamic icon component powered by lucide-react. Supports all Lucide icons with configurable size and stroke width.
+A dynamic icon component powered by lucide-react. Supports all [Lucide icons](https://lucide.dev/icons) with configurable size and stroke width.
 
-## CSS Variables
+## Styling
 
-The Icon component inherits color from its parent. Use CSS color or Tailwind text color classes:
-
-\`\`\`css
-.icon-container {
-  color: var(--foreground);
-}
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Icon\` component dynamically loads icons by name:
-
-\`\`\`tsx
-import { Icon } from '@/components/icon';
-
-<Icon name="shopping-cart" />
-<Icon name="heart" size={32} />
-<Icon name="star" size={20} strokeWidth={2} />
-\`\`\`
-
-### Available Icons
-
-Browse all available icons at [lucide.dev/icons](https://lucide.dev/icons). Use the kebab-case name (e.g., \`shopping-cart\`, \`arrow-right\`).
-
-### Skeleton Loading State
-
-Use the Skeleton primitive for loading states:
-
-\`\`\`tsx
-import * as Icon from '@/components/icon';
-
-<Icon.Skeleton size={24} />
-\`\`\`
+The Icon inherits color from its parent via \`currentColor\`. Use Tailwind text color classes or CSS color property on a parent element.
         `,
       },
     },
@@ -62,19 +28,19 @@ import * as Icon from '@/components/icon';
     name: {
       control: 'select',
       options: iconNames,
-      description: 'The name of the icon from lucide-react',
+      description: 'Icon name from lucide-react (kebab-case)',
     },
     size: {
       control: 'number',
-      description: 'The size of the icon in pixels',
+      description: 'Icon size in pixels',
     },
     strokeWidth: {
       control: 'number',
-      description: 'The stroke width of the icon',
+      description: 'Stroke width of the icon lines',
     },
     color: {
       control: 'color',
-      description: 'The color of the icon',
+      description: 'Icon color (inherits from parent by default)',
     },
   },
   args: {
@@ -87,19 +53,38 @@ import * as Icon from '@/components/icon';
 export default meta;
 type Story = StoryObj<IconProps>;
 
-// Default icon
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A dynamically loaded icon by name.',
+      },
+    },
+  },
   args: {
     name: 'shopping-cart',
   },
 };
 
-// All sizes
 export const AllSizes: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Icons scale based on the `size` prop.',
+      },
+      source: {
+        code: `
+<Icon name="star" size={16} />
+<Icon name="star" size={24} />
+<Icon name="star" size={32} />
+<Icon name="star" size={48} />
+        `,
+      },
+    },
+  },
   render: () => (
     <div className="flex items-center gap-6">
       <Icon name="star" size={16} />
-      <Icon name="star" size={20} />
       <Icon name="star" size={24} />
       <Icon name="star" size={32} />
       <Icon name="star" size={48} />
@@ -107,22 +92,21 @@ export const AllSizes: Story = {
   ),
 };
 
-// Common e-commerce icons
-export const CommonIcons: Story = {
-  render: () => (
-    <div className="flex items-center gap-6">
-      <Icon name="shopping-cart" />
-      <Icon name="heart" />
-      <Icon name="search" />
-      <Icon name="user" />
-      <Icon name="package" />
-      <Icon name="truck" />
-    </div>
-  ),
-};
-
-// Skeleton loading state
 export const Skeleton: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use the Skeleton primitive for loading states.',
+      },
+      source: {
+        code: `
+<IconPrimitive.Skeleton size={24} />
+<IconPrimitive.Skeleton size={32} />
+<IconPrimitive.Skeleton size={48} />
+        `,
+      },
+    },
+  },
   render: () => (
     <div className="flex items-center gap-6">
       <IconPrimitive.Skeleton size={24} />
diff --git a/src/components/input/input.tsx b/src/components/input/input.tsx
index 0201a75..0460798 100644
--- a/src/components/input/input.tsx
+++ b/src/components/input/input.tsx
@@ -1,13 +1,16 @@
+import type { VariantProps } from 'class-variance-authority';
 import type { ComponentProps, ReactNode } from 'react';
 
 import * as InputPrimitive from '@/components/input';
+import { inputVariants } from '@/components/input';
 
-export interface InputProps extends ComponentProps<'input'> {
-  prependIcon?: {
-    asChild?: boolean;
-    children?: ReactNode;
+export type InputProps = Omit<ComponentProps<'input'>, 'size'> &
+  VariantProps<typeof inputVariants> & {
+    prependIcon?: {
+      asChild?: boolean;
+      children?: ReactNode;
+    };
   };
-}
 
 /**
  * This component supports various CSS variables for theming. Here's a comprehensive list, along
@@ -15,15 +18,23 @@ export interface InputProps extends ComponentProps<'input'> {
  *
  * ```css
  *  :root {
- *   --input-light-background: var(--background);
- *   --input-light-text: var(--foreground);
- *   --input-light-placeholder: var(--contrast-500);
+ *   --input-fill: var(--form-fill);
+ *   --input-fill-icon: var(--form-fill-icon);
+ *   --input-fill-disabled: var(--form-fill-disabled);
+ *   --input-text: var(--form-text-primary);
+ *   --input-text-placeholder: var(--form-text-placeholder);
+ *   --input-font: var(--font-body);
  *  }
  * ```
  */
-export function Input({ className, prependIcon, ...props }: InputProps) {
+export function Input({ className, prependIcon, size = 'medium', ...props }: InputProps) {
   return (
-    <InputPrimitive.Root className={className} prepend={prependIcon?.children != null || undefined}>
+    <InputPrimitive.Root
+      className={className}
+      prepend={prependIcon?.children != null || undefined}
+      size={size}
+      {...props}
+    >
       {prependIcon?.children != null && (
         <InputPrimitive.Prepend>
           <InputPrimitive.PrependIcon asChild={prependIcon.asChild}>
diff --git a/src/components/input/primitives.ts b/src/components/input/primitives.ts
index 5c15933..cf025c0 100644
--- a/src/components/input/primitives.ts
+++ b/src/components/input/primitives.ts
@@ -1,6 +1,7 @@
 export {
   InputRoot as Root,
   type InputRootProps as RootProps,
+  inputVariants,
 } from '@/components/input/primitives/input-root';
 export {
   InputField as Field,
diff --git a/src/components/input/primitives/input-field.tsx b/src/components/input/primitives/input-field.tsx
index dfbf981..e76553a 100644
--- a/src/components/input/primitives/input-field.tsx
+++ b/src/components/input/primitives/input-field.tsx
@@ -8,13 +8,13 @@ export function InputField({ className, ...props }: InputFieldProps) {
   return (
     <input
       className={cn(
-        'w-full bg-[var(--input-light-background,var(--background))] px-6 py-3 text-sm font-normal text-[var(--input-light-text,var(--foreground))] [appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none',
-        // Focus state
-        'focus:outline-none',
+        'w-full bg-transparent [appearance:textfield] focus:outline-none [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none',
         // Placeholder state
-        'placeholder:font-normal placeholder:text-[var(--input-light-placeholder,var(--contrast-500))]',
+        'placeholder:font-normal placeholder:text-[--input-text-placeholder,var(--form-text-placeholder)]',
+        // Disabled state
+        'disabled:cursor-not-allowed',
         // Group states (with prepend)
-        'group-data-[prepend]/input:py-2.5 group-data-[prepend]/input:pe-4 group-data-[prepend]/input:ps-12',
+        // 'group-data-[prepend]/input:py-2.5 group-data-[prepend]/input:pe-4 group-data-[prepend]/input:ps-12',
         className,
       )}
       data-slot="input-field"
diff --git a/src/components/input/primitives/input-prepend-icon.tsx b/src/components/input/primitives/input-prepend-icon.tsx
index 6d78fdb..7466d41 100644
--- a/src/components/input/primitives/input-prepend-icon.tsx
+++ b/src/components/input/primitives/input-prepend-icon.tsx
@@ -11,7 +11,10 @@ export interface InputPrependIconProps {
 }
 
 export function InputPrependIcon({ asChild = false, className, children }: InputPrependIconProps) {
-  const iconStyles = cn('size-5 text-[var(--input-light-icon,var(--contrast-400))]', className);
+  const iconStyles = cn(
+    'text-[--input-fill-icon,var(--form-fill-icon)] group-data-[size=large]/input:size-5 group-data-[size=medium]/input:size-5 group-data-[size=small]/input:size-4',
+    className,
+  );
 
   if (asChild) {
     return (
diff --git a/src/components/input/primitives/input-prepend.tsx b/src/components/input/primitives/input-prepend.tsx
index e676e0e..e8bd89a 100644
--- a/src/components/input/primitives/input-prepend.tsx
+++ b/src/components/input/primitives/input-prepend.tsx
@@ -7,7 +7,10 @@ export type InputPrependProps = ComponentProps<'span'>;
 export function InputPrepend({ className, children, ...props }: InputPrependProps) {
   return (
     <span
-      className={cn('pointer-events-none absolute left-3.5 top-1/2 -translate-y-1/2', className)}
+      className={cn(
+        'pointer-events-none group-data-[size=large]/input:mr-3 group-data-[size=medium]/input:mr-3 group-data-[size=small]/input:mr-2',
+        className,
+      )}
       data-slot="input-prepend"
       {...props}
     >
diff --git a/src/components/input/primitives/input-root.tsx b/src/components/input/primitives/input-root.tsx
index 6368892..7facea2 100644
--- a/src/components/input/primitives/input-root.tsx
+++ b/src/components/input/primitives/input-root.tsx
@@ -1,23 +1,49 @@
+import { cva, type VariantProps } from 'class-variance-authority';
 import type { ComponentProps, ReactNode } from 'react';
 
 import { cn } from '@/lib';
 
-export type InputRootProps = ComponentProps<'div'> & {
-  prepend?: ReactNode;
-};
+export const inputVariants = cva(
+  [
+    'group/input [font-family:var(--input-font,var(--font-body))] relative flex items-center overflow-hidden border border-[--border-subtle] bg-[--input-fill,var(--form-fill)] text-[--input-text,var(--form-text-primary)] transition-colors duration-200',
+    // Focus-within state
+    'focus-within:border-[--border-focus-secondary]',
+    // Aria-invalid state
+    'has-[[aria-invalid]]:border-[--border-error]',
+    // Disabled state
+    'has-[:disabled]:cursor-not-allowed has-[:disabled]:bg-[--input-fill-disabled,var(--form-fill-disabled)] has-[:disabled]:opacity-50',
+  ],
+  {
+    variants: {
+      size: {
+        small: 'h-9 text-sm px-3 py-2 rounded-lg',
+        medium: 'h-11 text-sm px-4 py-3 rounded-lg',
+        large: 'h-14 text-base px-5 py-4 rounded-xl',
+      },
+    },
+    defaultVariants: {
+      size: 'medium',
+    },
+  },
+);
 
-export function InputRoot({ className, children, prepend, ...props }: InputRootProps) {
+export type InputRootProps = ComponentProps<'div'> &
+  VariantProps<typeof inputVariants> & {
+    prepend?: ReactNode;
+  };
+
+export function InputRoot({
+  className,
+  children,
+  prepend,
+  size = 'medium',
+  ...props
+}: InputRootProps) {
   return (
     <div
-      className={cn(
-        'group/input relative overflow-hidden rounded-lg border border-[var(--input-light-border,var(--contrast-100))] bg-[var(--input-light-background,var(--background))] transition-colors duration-200',
-        // Focus-within state
-        'focus-within:border-[var(--input-light-focus,var(--foreground))]',
-        // Aria-invalid state
-        'aria-invalid:border-[var(--input-light-border-error,var(--error))]',
-        className,
-      )}
+      className={cn(inputVariants({ size }), className)}
       data-prepend={prepend != null && prepend !== '' ? '' : undefined}
+      data-size={size}
       data-slot="input-root"
       {...props}
     >
diff --git a/src/components/input/storybook/input.stories.tsx b/src/components/input/storybook/input.stories.tsx
index 8d26d92..af08f7a 100644
--- a/src/components/input/storybook/input.stories.tsx
+++ b/src/components/input/storybook/input.stories.tsx
@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { DollarSign } from 'lucide-react';
+import { DollarSign, Search } from 'lucide-react';
 
 import { Input, type InputProps } from '@/components/input';
 import * as InputPrimitive from '@/components/input/primitives';
@@ -12,67 +12,18 @@ const meta: Meta<typeof Input> = {
     docs: {
       description: {
         component: `
-A text input component with support for prepended icons. Built for forms and user input scenarios.
+A text input with support for prepended icons.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --input-light-background: var(--background);
-  --input-light-border: var(--contrast-100);
-  --input-light-focus: var(--foreground);
-  --input-light-border-error: var(--error);
-  --input-light-text: var(--foreground);
-  --input-light-placeholder: var(--contrast-500);
-  --input-light-icon: var(--contrast-400);
+  --input-fill: var(--form-fill);
+  --input-fill-icon: var(--form-fill-icon);
+  --input-fill-disabled: var(--form-fill-disabled);
+  --input-text: var(--form-text-primary);
+  --input-text-placeholder: var(--form-text-placeholder);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Input\` component provides a simple API with an optional \`prependIcon\` prop:
-
-\`\`\`tsx
-import { Input } from '@/components/input';
-import { DollarSign } from 'lucide-react';
-
-// Basic input
-<Input placeholder="Enter text..." />
-
-// With default search icon
-<Input prependIcon={{}} placeholder="Search..." />
-
-// With custom icon using asChild
-<Input prependIcon={{ asChild: true, children: <DollarSign /> }} type="number" placeholder="0.00" />
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Input from '@/components/input';
-import { DollarSign } from 'lucide-react';
-
-// Default search icon
-<Input.Root prepend>
-  <Input.Prepend>
-    <Input.PrependIcon />
-  </Input.Prepend>
-  <Input.Field placeholder="Search products..." />
-</Input.Root>
-
-// Custom icon with asChild
-<Input.Root prepend>
-  <Input.Prepend>
-    <Input.PrependIcon asChild>
-      <DollarSign />
-    </Input.PrependIcon>
-  </Input.Prepend>
-  <Input.Field type="number" placeholder="0.00" />
-</Input.Root>
 \`\`\`
         `,
       },
@@ -80,22 +31,28 @@ import { DollarSign } from 'lucide-react';
   },
   tags: ['autodocs'],
   argTypes: {
+    size: {
+      control: 'select',
+      options: ['small', 'medium', 'large'],
+      description: 'The size of the input',
+    },
     type: {
       control: 'select',
       options: ['text', 'email', 'password', 'number', 'tel', 'url', 'search'],
-      description: 'The input type',
+      description: 'The HTML input type',
     },
     placeholder: {
       control: 'text',
-      description: 'Placeholder text displayed when empty',
+      description: 'Placeholder text when empty',
     },
     disabled: {
       control: 'boolean',
-      description: 'Whether the input is disabled',
+      description: 'Disables the input',
     },
     prependIcon: {
       control: false,
-      description: 'Icon configuration to prepend before the input',
+      description:
+        'Icon configuration object with `asChild` and `children` props. Use `asChild: true` to render a custom icon.',
     },
   },
   args: {
@@ -107,18 +64,62 @@ import { DollarSign } from 'lucide-react';
 export default meta;
 type Story = StoryObj<InputProps>;
 
-// Default input
 export const Default: Story = {
   args: {
     placeholder: 'Enter text...',
   },
 };
 
-// With prepended icons
+export const AllSizes: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Three size options are available: `small`, `medium` (default), and `large`.',
+      },
+      source: {
+        code: `
+<Input size="small" placeholder="Small input" />
+<Input size="medium" placeholder="Medium input" />
+<Input size="large" placeholder="Large input" />
+        `,
+      },
+    },
+  },
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Input placeholder="Small input" size="small" />
+      <Input placeholder="Medium input" size="medium" />
+      <Input placeholder="Large input" size="large" />
+    </div>
+  ),
+};
+
 export const WithPrependIcon: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Add a prepended icon using the `prependIcon` prop. Pass `asChild: true` to use a custom icon component.',
+      },
+      source: {
+        code: `
+<Input
+  placeholder="Search..."
+  prependIcon={{ asChild: true, children: <Search /> }}
+/>
+
+<Input
+  placeholder="0.00"
+  prependIcon={{ asChild: true, children: <DollarSign /> }}
+  type="number"
+/>
+        `,
+      },
+    },
+  },
   render: () => (
     <div className="flex flex-col gap-4">
-      <Input placeholder="Search..." prependIcon={{}} />
+      <Input placeholder="Search..." prependIcon={{ asChild: true, children: <Search /> }} />
       <Input
         placeholder="0.00"
         prependIcon={{ asChild: true, children: <DollarSign /> }}
@@ -128,18 +129,51 @@ export const WithPrependIcon: Story = {
   ),
 };
 
-// Disabled state
 export const Disabled: Story = {
   args: {
     disabled: true,
     defaultValue: 'Cannot edit this',
   },
+  parameters: {
+    docs: {
+      description: {
+        story: 'The `disabled` prop prevents user interaction and applies reduced opacity styling.',
+      },
+    },
+  },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the primitive components to build custom input layouts.
+
+| Primitive                      | Description                                           |
+|--------------------------------|-------------------------------------------------------|
+| \`InputPrimitive.Root\`        | Container with border, background, and focus states.  |
+| \`InputPrimitive.Prepend\`     | Positioned wrapper for prepend content.               |
+| \`InputPrimitive.PrependIcon\` | Icon with \`asChild\` support; defaults to search.    |
+| \`InputPrimitive.Field\`       | The actual input element with styling.                |
+        `,
+      },
+      source: {
+        code: `
+import * as InputPrimitive from '@/components/input/primitives';
+
+<InputPrimitive.Root prepend size="medium">
+  <InputPrimitive.Prepend>
+    <InputPrimitive.PrependIcon />
+  </InputPrimitive.Prepend>
+  <InputPrimitive.Field placeholder="Search products..." />
+</InputPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
-    <InputPrimitive.Root prepend>
+    <InputPrimitive.Root prepend size="medium">
       <InputPrimitive.Prepend>
         <InputPrimitive.PrependIcon />
       </InputPrimitive.Prepend>
diff --git a/src/components/label/label.tsx b/src/components/label/label.tsx
index d24cd00..82912c3 100644
--- a/src/components/label/label.tsx
+++ b/src/components/label/label.tsx
@@ -5,13 +5,24 @@ import { cn } from '@/lib';
 
 export type LabelProps = ComponentProps<typeof LabelPrimitive.Root>;
 
+/**
+ * This component supports various CSS variables for theming. Here's a comprehensive list, along
+ * with their default values:
+ *
+ * ```css
+ *  :root {
+ *   --label-text: var(--form-text-primary);
+ *   --label-font: var(--font-body);
+ *  }
+ * ```
+ */
 export function Label({ className, children, ...props }: LabelProps) {
   return (
     <LabelPrimitive.Root
       className={cn(
-        'block cursor-pointer text-xs font-semibold text-[var(--label-text,var(--contrast-500))] [font-family:var(--label-font-family,var(--font-family-body))]',
+        'block cursor-pointer text-xs font-semibold text-[--label-text,var(--font-text-primary)] [font-family:var(--label-font,var(--font-body))]',
         // Horizontal label orientation (via data-label-orientation on any ancestor)
-        '[[data-label-orientation=horizontal]_&]:text-sm [[data-label-orientation=horizontal]_&]:font-normal [[data-label-orientation=horizontal]_&]:text-[var(--label-horizontal-text,var(--foreground))]',
+        '[[data-label-orientation=horizontal]_&]:text-sm [[data-label-orientation=horizontal]_&]:font-normal',
         // Disabled state
         'peer-disabled:cursor-not-allowed peer-disabled:opacity-50',
         className,
diff --git a/src/components/label/storybook/label.stories.tsx b/src/components/label/storybook/label.stories.tsx
index 551a22f..c6888f9 100644
--- a/src/components/label/storybook/label.stories.tsx
+++ b/src/components/label/storybook/label.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import type { ComponentType } from 'react';
 
 import { Checkbox } from '@/components/checkbox';
 import * as Field from '@/components/field';
@@ -18,65 +17,23 @@ A label component for form controls, built on Radix UI Label primitive. Supports
 
 ## CSS Variables
 
-The Label component supports the following CSS variables for theming:
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| \`--label-text\` | Text color (default/vertical) | \`var(--contrast-500)\` |
-| \`--label-font-family\` | Font family | \`var(--font-family-body)\` |
-| \`--label-horizontal-text\` | Text color in horizontal orientation | \`var(--foreground)\` |
-
-## Orientation-Aware Styling
-
-The default styling matches vertical orientation. When inside a \`Field.Item\` with \`data-label-orientation="horizontal"\`, the label adapts:
-
-| Orientation | Text Size | Font Weight | Color |
-|-------------|-----------|-------------|-------|
-| Default / Vertical | \`text-xs\` | semibold | \`--label-text\` |
-| Horizontal | \`text-sm\` | normal | \`--label-horizontal-text\` |
-
-Use \`Field.Item\` with \`orientation="horizontal"\` to get horizontal label styling. This is used by RadioGroup and CheckboxGroup internally.
-
-## Usage
-
-\`\`\`tsx
-import { Label } from '@/components/label';
-import { Input } from '@/components/input';
-
-<Label htmlFor="email">Email Address</Label>
-<Input id="email" type="email" />
+\`\`\`css
+:root {
+  --label-text: var(--form-text-primary);
+  --label-font: var(--font-body);
+}
 \`\`\`
 
 ## Orientation-Aware Styling
 
-The Label component adapts its styling based on the parent \`Field.Item\`'s orientation:
+The Label component adapts its styling based on the parent \`Field.Item\`'s orientation via the \`data-label-orientation\` attribute:
 
-| Orientation | Text Size | Font Weight | Color |
-|-------------|-----------|-------------|-------|
-| Vertical (default) | \`text-xs\` | semibold | \`--label-text\` |
-| Horizontal | \`text-sm\` | normal | \`--label-horizontal-text\` |
+| Orientation          | Text Size | Font Weight |
+|----------------------|-----------|-------------|
+| Vertical (default)   | text-xs   | semibold    |
+| Horizontal           | text-sm   | normal      |
 
-## With Field Components
-
-Use \`Field.Label\` inside \`Field.Item\` for automatic orientation handling:
-
-\`\`\`tsx
-import * as Field from '@/components/field';
-import { Input } from '@/components/input';
-import { Checkbox } from '@/components/checkbox';
-
-// Vertical orientation (default)
-<Field.Item>
-  <Field.Label htmlFor="name">Name</Field.Label>
-  <Input id="name" />
-</Field.Item>
-
-// Horizontal orientation for inline controls
-<Field.Item orientation="horizontal">
-  <Checkbox id="terms" />
-  <Field.Label htmlFor="terms">Accept terms</Field.Label>
-</Field.Item>
-\`\`\`
+Use \`Field.Item\` with \`orientation="horizontal"\` to get horizontal label styling. This is commonly used for checkboxes and radio buttons.
         `,
       },
     },
@@ -88,21 +45,29 @@ import { Checkbox } from '@/components/checkbox';
       description: 'The ID of the form element this label is associated with',
     },
   },
-  decorators: [
-    (Story: ComponentType) => (
-      <div className="mx-auto max-w-md">
-        <Story />
-      </div>
-    ),
-  ],
+  decorators: [(Story) => <div className="mx-auto max-w-md">{Story()}</div>],
 };
 
 export default meta;
 
 type Story = StoryObj<LabelProps>;
 
-// Default label with input
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A label paired with an input inside a `Field.Item` container.',
+      },
+      source: {
+        code: `
+<Field.Item>
+  <Label htmlFor="email">Email Address</Label>
+  <Input id="email" type="email" placeholder="you@example.com" />
+</Field.Item>
+        `,
+      },
+    },
+  },
   render: () => (
     <Field.Item>
       <Label htmlFor="email">Email Address</Label>
@@ -111,8 +76,29 @@ export const Default: Story = {
   ),
 };
 
-// Horizontal orientation (for checkboxes)
 export const HorizontalOrientation: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'When placed inside a `Field.Item` with `orientation="horizontal"`, the label switches to a lighter weight and larger size, suitable for inline controls like checkboxes.',
+      },
+      source: {
+        code: `
+<Field.Group>
+  <Field.Item orientation="horizontal">
+    <Checkbox id="newsletter" />
+    <Label htmlFor="newsletter">Subscribe to newsletter</Label>
+  </Field.Item>
+  <Field.Item orientation="horizontal">
+    <Checkbox id="terms" />
+    <Label htmlFor="terms">I agree to the terms and conditions</Label>
+  </Field.Item>
+</Field.Group>
+        `,
+      },
+    },
+  },
   render: () => (
     <Field.Group>
       <Field.Item orientation="horizontal">
diff --git a/src/components/logo/primitives/logo-link.tsx b/src/components/logo/primitives/logo-link.tsx
index a9f647e..02fbe02 100644
--- a/src/components/logo/primitives/logo-link.tsx
+++ b/src/components/logo/primitives/logo-link.tsx
@@ -11,14 +11,7 @@ export function LogoLink({ asChild = false, className, children, ...props }: Log
   const Component = asChild ? Slot : 'a';
 
   return (
-    <Component
-      className={cn(
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-[var(--logo-focus,var(--brand))]',
-        className,
-      )}
-      data-slot="logo-link"
-      {...props}
-    >
+    <Component className={cn('focus-primary', className)} data-slot="logo-link" {...props}>
       {children}
     </Component>
   );
diff --git a/src/components/logo/primitives/logo-text.tsx b/src/components/logo/primitives/logo-text.tsx
index 475afbc..07b2f92 100644
--- a/src/components/logo/primitives/logo-text.tsx
+++ b/src/components/logo/primitives/logo-text.tsx
@@ -10,7 +10,7 @@ export function LogoText({ children, className, ...props }: LogoTextProps) {
   return (
     <span
       className={cn(
-        'text-lg font-semibold leading-none text-[var(--logo-text,var(--foreground))] [font-family:var(--logo-font-family,var(--font-family-heading))] @xl:text-2xl',
+        'text-lg font-semibold text-[--logo-text,var(--foreground)] [font-family:var(--logo-font,var(--font-heading))] @xl:text-2xl',
         className,
       )}
       data-slot="logo-text"
diff --git a/src/components/logo/storybook/logo.stories.tsx b/src/components/logo/storybook/logo.stories.tsx
index 714c9a3..6d3264a 100644
--- a/src/components/logo/storybook/logo.stories.tsx
+++ b/src/components/logo/storybook/logo.stories.tsx
@@ -9,59 +9,24 @@ const meta: Meta = {
     docs: {
       description: {
         component: `
-A composable logo component for displaying brand identity with text or image. Supports router integration via \`asChild\` pattern.
+A composable logo component for displaying brand identity with text or image. This component is primitives-only.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --logo-focus: var(--brand);
   --logo-text: var(--foreground);
-  --logo-font-family: var(--font-family-heading);
+  --logo-font: var(--font-heading);
 }
 \`\`\`
 
-## Composable Anatomy
+## Container Queries
 
-The Logo component is composable-only. Use the primitives to build your logo:
+The text logo adapts based on container width.
 
-\`\`\`tsx
-import * as Logo from '@/components/logo';
-
-// Text logo
-<Logo.Link href="/" aria-label="Go to homepage">
-  <Logo.Text>Brand Name</Logo.Text>
-</Logo.Link>
-
-// Image logo
-<Logo.Link href="/" aria-label="Go to homepage">
-  <Logo.Image src="/logo.png" alt="Brand Logo" />
-</Logo.Link>
-\`\`\`
-
-### Router Integration
-
-Use \`asChild\` for Next.js Link or React Router:
-
-\`\`\`tsx
-import * as Logo from '@/components/logo';
-import Link from 'next/link';
-
-<Logo.Link asChild>
-  <Link href="/" aria-label="Go to homepage">
-    <Logo.Text>Brand Name</Logo.Text>
-  </Link>
-</Logo.Link>
-\`\`\`
-
-## Primitives
-
-| Primitive | Description |
-|-----------|-------------|
-| \`Logo.Link\` | Anchor wrapper with focus styles. Supports \`asChild\` for router integration. |
-| \`Logo.Text\` | Text-based logo with responsive sizing. |
-| \`Logo.Image\` | Image-based logo with \`src\`, \`alt\`, \`width\`, and \`height\` props. |
-| \`Logo.Skeleton\` | Loading placeholder for the logo. |
+| Element | Below @xl | @xl and above |
+|---------|-----------|---------------|
+| Text    | text-lg   | text-2xl      |
         `,
       },
     },
@@ -73,8 +38,21 @@ export default meta;
 
 type Story = StoryObj;
 
-// Text-based logo
 export const TextLogo: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A text-based logo wrapped in a link.',
+      },
+      source: {
+        code: `
+<Logo.Link href="/" aria-label="Go to homepage">
+  <Logo.Text>Clean Essentials</Logo.Text>
+</Logo.Link>
+        `,
+      },
+    },
+  },
   render: () => (
     <Logo.Link aria-label="Go to homepage" href="#">
       <Logo.Text>Clean Essentials</Logo.Text>
@@ -82,8 +60,21 @@ export const TextLogo: Story = {
   ),
 };
 
-// Image-based logo
 export const ImageLogo: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'An image-based logo wrapped in a link.',
+      },
+      source: {
+        code: `
+<Logo.Link href="/" aria-label="Go to homepage">
+  <Logo.Image src="/logo.png" alt="Brand Logo" />
+</Logo.Link>
+        `,
+      },
+    },
+  },
   render: () => (
     <Logo.Link aria-label="Go to homepage" href="#">
       <Logo.Image alt="Brand Logo" src="https://placehold.co/120x40?text=Brand" />
@@ -91,7 +82,16 @@ export const ImageLogo: Story = {
   ),
 };
 
-// Skeleton loading state
 export const Skeleton: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Loading state placeholder.',
+      },
+      source: {
+        code: `<Logo.Skeleton />`,
+      },
+    },
+  },
   render: () => <Logo.Skeleton />,
 };
diff --git a/src/components/modal/modal.tsx b/src/components/modal/modal.tsx
index d0c11e2..3ac32e1 100644
--- a/src/components/modal/modal.tsx
+++ b/src/components/modal/modal.tsx
@@ -17,8 +17,8 @@ export interface ModalProps {
  *
  * ```css
  * :root {
- *   --modal-background: var(--background);
- *   --modal-overlay-background: color-mix(in oklab, var(--foreground) 50%, transparent);
+ *   --modal-fill: var(--background);
+ *   --modal-fill-overlay: color-mix(in oklab, var(--foreground) 50%, transparent);
  * }
  * ```
  */
diff --git a/src/components/modal/primitives/modal-content.tsx b/src/components/modal/primitives/modal-content.tsx
index 7d5c682..431bb84 100644
--- a/src/components/modal/primitives/modal-content.tsx
+++ b/src/components/modal/primitives/modal-content.tsx
@@ -9,7 +9,7 @@ export function ModalContent({ children, className, ...props }: ModalContentProp
   return (
     <Dialog.Content
       className={cn(
-        'mx-3 my-10 max-h-[90%] max-w-3xl overflow-y-auto rounded-xl bg-[var(--modal-background,var(--background))] px-3 py-5 transition ease-out @sm:px-6 @sm:py-8 @5xl:px-20 @5xl:py-10',
+        'mx-3 my-10 max-h-[90%] max-w-3xl overflow-y-auto rounded-xl bg-[--modal-fill,var(--background)] px-3 py-5 transition ease-out @sm:px-6 @sm:py-8 @5xl:px-20 @5xl:py-10',
         // Focus styles
         'focus:outline-none',
         // Open styles
diff --git a/src/components/modal/primitives/modal-overlay.tsx b/src/components/modal/primitives/modal-overlay.tsx
index 03852f3..7cb0811 100644
--- a/src/components/modal/primitives/modal-overlay.tsx
+++ b/src/components/modal/primitives/modal-overlay.tsx
@@ -9,7 +9,7 @@ export function ModalOverlay({ children, className, ...props }: ModalOverlayProp
   return (
     <Dialog.Overlay
       className={cn(
-        'fixed inset-0 z-30 flex items-center justify-center bg-[var(--modal-overlay-background,color-mix(in_oklab,var(--foreground)_50%,transparent))] @container',
+        'fixed inset-0 z-30 flex items-center justify-center bg-[var(--modal-fill-overlay,color-mix(in_oklab,var(--foreground)_50%,transparent))] @container',
         // Open state
         'data-[state=open]:duration-200 data-[state=open]:animate-in data-[state=open]:fade-in-0',
         // Closed state
diff --git a/src/components/modal/storybook/modal.stories.tsx b/src/components/modal/storybook/modal.stories.tsx
index 95f9bb6..b07e54f 100644
--- a/src/components/modal/storybook/modal.stories.tsx
+++ b/src/components/modal/storybook/modal.stories.tsx
@@ -13,78 +13,24 @@ const meta: Meta<typeof Modal> = {
     docs: {
       description: {
         component: `
-A modal dialog component for displaying content that requires user attention. Built on Radix UI Dialog primitives with overlay and focus management.
+A modal dialog for content requiring user attention. Built on Radix UI Dialog with overlay and focus management.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --modal-background: var(--background);
-  --modal-overlay-background: color-mix(in oklab, var(--foreground) 50%, transparent);
+  --modal-fill: var(--background);
+  --modal-fill-overlay: color-mix(in oklab, var(--foreground) 50%, transparent);
 }
 \`\`\`
 
-## Usage
+## Container Queries
 
-### High-Level Component
+The modal content adapts its padding based on overlay width.
 
-The \`Modal\` component is controlled via \`isOpen\` and \`setOpen\`:
-
-\`\`\`tsx
-import { Modal } from '@/components/modal';
-import { Button } from '@/components/button';
-import { useState } from 'react';
-
-function Example() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <Modal
-      isOpen={open}
-      setOpen={setOpen}
-      title="Confirm Action"
-      trigger={<Button>Open Modal</Button>}
-    >
-      <p>Are you sure you want to continue?</p>
-      <Button onClick={() => setOpen(false)}>Close</Button>
-    </Modal>
-  );
-}
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Modal from '@/components/modal';
-import { Button } from '@/components/button';
-
-<Modal.Root open={open} onOpenChange={setOpen}>
-  <Modal.Trigger asChild>
-    <Button>Open</Button>
-  </Modal.Trigger>
-  <Modal.Portal>
-    <Modal.Overlay>
-      <Modal.Content>
-        <Modal.Title>Dialog Title</Modal.Title>
-        <p>Your content here.</p>
-      </Modal.Content>
-    </Modal.Overlay>
-  </Modal.Portal>
-</Modal.Root>
-\`\`\`
-
-## Primitives
-
-| Primitive | Description |
-|-----------|-------------|
-| \`Modal.Root\` | Container with \`open\` and \`onOpenChange\` props. |
-| \`Modal.Trigger\` | Element that opens the modal. Supports \`asChild\`. |
-| \`Modal.Portal\` | Renders content in a portal. |
-| \`Modal.Overlay\` | Background overlay with animation. |
-| \`Modal.Content\` | Modal content container with focus trap. |
-| \`Modal.Title\` | Accessible title (visually hidden by default). |
+| Element | Below @sm | @sm – @5xl | @5xl and above |
+|---------|-----------|------------|----------------|
+| Content | px-3 py-5 | px-6 py-8  | px-20 py-10    |
         `,
       },
     },
@@ -93,7 +39,7 @@ import { Button } from '@/components/button';
   argTypes: {
     title: {
       control: 'text',
-      description: 'Accessible title for the dialog (visually hidden)',
+      description: 'Accessible title (visually hidden)',
     },
     isOpen: {
       control: 'boolean',
@@ -105,7 +51,7 @@ import { Button } from '@/components/button';
     },
     trigger: {
       control: false,
-      description: 'Trigger element that opens the modal',
+      description: 'Element that opens the modal',
     },
     children: {
       control: false,
@@ -118,8 +64,32 @@ export default meta;
 
 type Story = StoryObj<ModalProps>;
 
-// Default modal
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A controlled modal with overlay and focus trap.',
+      },
+      source: {
+        code: `
+const [open, setOpen] = useState(false);
+
+<Modal
+  isOpen={open}
+  setOpen={setOpen}
+  title="Example Modal"
+  trigger={<Button variant="primary">Open Modal</Button>}
+>
+  <div>
+    <h2>Welcome</h2>
+    <p>Modal content here.</p>
+    <Button onClick={() => setOpen(false)}>Close</Button>
+  </div>
+</Modal>
+        `,
+      },
+    },
+  },
   render: () => {
     const [open, setOpen] = useState(false);
 
@@ -149,8 +119,33 @@ export const Default: Story = {
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitive components for custom layouts.',
+      },
+      source: {
+        code: `
+const [open, setOpen] = useState(false);
+
+<ModalPrimitive.Root open={open} onOpenChange={setOpen}>
+  <ModalPrimitive.Trigger asChild>
+    <Button>Open Modal</Button>
+  </ModalPrimitive.Trigger>
+  <ModalPrimitive.Portal>
+    <ModalPrimitive.Overlay>
+      <ModalPrimitive.Content>
+        <ModalPrimitive.Title>Dialog Title</ModalPrimitive.Title>
+        <p>Your content here.</p>
+      </ModalPrimitive.Content>
+    </ModalPrimitive.Overlay>
+  </ModalPrimitive.Portal>
+</ModalPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => {
     const [open, setOpen] = useState(false);
 
diff --git a/src/components/navigation-menu/navigation-menu.tsx b/src/components/navigation-menu/navigation-menu.tsx
index 1e73dd3..9885139 100644
--- a/src/components/navigation-menu/navigation-menu.tsx
+++ b/src/components/navigation-menu/navigation-menu.tsx
@@ -37,23 +37,12 @@ export interface NavigationMenuProps {
  *
  * ```css
  * :root {
- *   --nav-focus: var(--brand);
- *   --nav-text: var(--foreground);
- *   --nav-viewport-background: var(--background);
- *   --nav-viewport-border: color-mix(in oklab, var(--foreground) 15%, transparent);
- *   --nav-link-text: var(--foreground);
- *   --nav-link-text-hover: var(--foreground);
- *   --nav-link-background: transparent;
- *   --nav-link-background-hover: var(--contrast-100);
- *   --nav-link-font-family: var(--font-family-body);
- *   --nav-grid-label-text: var(--foreground);
- *   --nav-grid-label-text-hover: var(--foreground);
- *   --nav-grid-label-background: transparent;
- *   --nav-grid-label-background-hover: var(--contrast-100);
- *   --nav-grid-label-font-family: var(--font-family-body);
- *   --nav-grid-link-text: var(--contrast-500);
- *   --nav-grid-link-background: transparent;
- *   --nav-grid-link-font-family: var(--font-family-body);
+ *   --navigation-menu-fill: var(--background);
+ *   --navigation-menu-text-primary: var(--text-primary);
+ *   --navigation-menu-text-secondary: var(--text-secondary);
+ *   --navigation-menu-font: var(--font-body);
+ *   --navigation-menu-fill-hover: var(--contrast-100);
+ *   --navigation-menu-text-hover: var(--text-primary);
  * }
  * ```
  */
diff --git a/src/components/navigation-menu/primitives/navigation-menu-grid-column.tsx b/src/components/navigation-menu/primitives/navigation-menu-grid-column.tsx
index 7d1357b..63a4290 100644
--- a/src/components/navigation-menu/primitives/navigation-menu-grid-column.tsx
+++ b/src/components/navigation-menu/primitives/navigation-menu-grid-column.tsx
@@ -10,7 +10,11 @@ export function NavigationMenuGridColumn({
   ...props
 }: NavigationMenuGridColumnProps) {
   return (
-    <li className={cn('w-full', className)} data-slot="navigation-menu-grid-column" {...props}>
+    <li
+      className={cn('flex w-full flex-col gap-0.5', className)}
+      data-slot="navigation-menu-grid-column"
+      {...props}
+    >
       {children}
     </li>
   );
diff --git a/src/components/navigation-menu/primitives/navigation-menu-grid-label.tsx b/src/components/navigation-menu/primitives/navigation-menu-grid-label.tsx
index 7eb60d5..5125489 100644
--- a/src/components/navigation-menu/primitives/navigation-menu-grid-label.tsx
+++ b/src/components/navigation-menu/primitives/navigation-menu-grid-label.tsx
@@ -13,11 +13,11 @@ export function NavigationMenuGridLabel({
   return (
     <NavigationMenuPrimitive.Link
       className={cn(
-        'block rounded-lg bg-[var(--nav-grid-label-background,transparent)] px-3 py-2 font-[family-name:var(--nav-grid-label-font-family,var(--font-family-body))] text-sm font-semibold text-[var(--nav-grid-label-text,var(--foreground))] transition-colors',
+        'focus-primary block rounded-lg px-3 py-2 text-sm font-semibold text-[--navigation-menu-text-primary,var(--text-primary)] transition-colors [font-family:var(--navigation-menu-font,var(--font-body))]',
         // Hover state
-        'hover:bg-[var(--nav-grid-label-background-hover,var(--contrast-100))] hover:text-[var(--nav-grid-label-text-hover,var(--foreground))]',
+        'hover:bg-[--navigation-menu-fill-hover,var(--contrast-100)] hover:text-[var(--navigation-menu-text-hover,var(--primary-text))]',
         // Focus-visible state
-        'focus-visible:bg-[var(--nav-grid-label-background-hover,var(--contrast-100))] focus-visible:text-[var(--nav-grid-label-text-hover,var(--foreground))] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--nav-focus,var(--brand))]',
+        'focus-visible:bg-[--navigation-menu-fill-hover,var(--contrast-100)] focus-visible:text-[--navigation-menu-text-hover,var(--primary-text)]',
         className,
       )}
       data-slot="navigation-menu-grid-label"
diff --git a/src/components/navigation-menu/primitives/navigation-menu-grid-link.tsx b/src/components/navigation-menu/primitives/navigation-menu-grid-link.tsx
index 3550761..0b5354e 100644
--- a/src/components/navigation-menu/primitives/navigation-menu-grid-link.tsx
+++ b/src/components/navigation-menu/primitives/navigation-menu-grid-link.tsx
@@ -13,11 +13,11 @@ export function NavigationMenuGridLink({
   return (
     <NavigationMenuPrimitive.Link
       className={cn(
-        'block rounded-lg bg-[var(--nav-grid-link-background,transparent)] px-3 py-2 font-[family-name:var(--nav-grid-link-font-family,var(--font-family-body))] text-sm font-medium text-[var(--nav-grid-link-text,var(--contrast-500))] transition-colors',
+        'focus-primary block rounded-lg px-3 py-2 text-sm font-medium text-[--navigation-menu-text-secondary,var(--text-secondary)] transition-colors [font-family:var(--navigation-menu-font,var(--font-body))]',
         // Hover state
-        'hover:bg-[var(--nav-grid-label-background-hover,var(--contrast-100))] hover:text-[var(--nav-grid-label-text-hover,var(--foreground))]',
+        'hover:bg-[--navigation-menu-fill-hover,var(--contrast-100)] hover:text-[--navigation-menu-text-hover,var(--text-primary)]',
         // Focus-visible state
-        'focus-visible:bg-[var(--nav-grid-label-background-hover,var(--contrast-100))] focus-visible:text-[var(--nav-grid-label-text-hover,var(--foreground))] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--nav-focus,var(--brand))]',
+        'focus-visible:bg-[--navigation-menu-fill-hover,var(--contrast-100)] focus-visible:text-[--navigation-menu-text-hover,var(--text-primary)]',
         className,
       )}
       data-slot="navigation-menu-grid-link"
diff --git a/src/components/navigation-menu/primitives/navigation-menu-link.tsx b/src/components/navigation-menu/primitives/navigation-menu-link.tsx
index 10d7987..084f7b4 100644
--- a/src/components/navigation-menu/primitives/navigation-menu-link.tsx
+++ b/src/components/navigation-menu/primitives/navigation-menu-link.tsx
@@ -9,13 +9,11 @@ export function NavigationMenuLink({ className, children, ...props }: Navigation
   return (
     <NavigationMenuPrimitive.Link
       className={cn(
-        'group/navigation-menu-link inline-flex h-9 w-max items-center justify-center rounded-full bg-background px-4 py-2 text-sm font-semibold text-[var(--nav-link-text,var(--foreground))] outline-none transition-[color,box-shadow] duration-200 [font-family:var(--nav-link-font-family,var(--font-family-body))]',
+        'group/navigation-menu-link focus-primary inline-flex h-9 w-max items-center justify-center rounded-full bg-background px-4 py-2 text-sm font-semibold text-[--navigation-menu-text-primary,var(--text-primary)] outline-none transition-[color,box-shadow] duration-200 [font-family:var(--navigation-menu-font,var(--font-body))]',
         // Hover state
-        'hover:bg-[var(--nav-link-background-hover,var(--contrast-100))] hover:text-[var(--nav-link-text-hover,var(--foreground))]',
+        'hover:bg-[--navigation-menu-fill-hover,var(--contrast-100)] hover:text-[--navigation-menu-text-hover,var(--text-primary)]',
         // Focus state
-        'focus:bg-[var(--nav-link-background-hover,var(--contrast-100))] focus:text-[var(--nav-link-text-hover,var(--foreground))]',
-        // Focus-visible state
-        'focus-visible:outline-2 focus-visible:outline-[var(--nav-focus,var(--brand))]',
+        'focus:bg-[--navigation-menu-fill-hover,var(--contrast-100)] focus:text-[--navigation-menu-text-hover,var(--text-primary)]',
         className,
       )}
       data-slot="navigation-menu-link"
diff --git a/src/components/navigation-menu/primitives/navigation-menu-list.tsx b/src/components/navigation-menu/primitives/navigation-menu-list.tsx
index afe3edd..5bc3c4b 100644
--- a/src/components/navigation-menu/primitives/navigation-menu-list.tsx
+++ b/src/components/navigation-menu/primitives/navigation-menu-list.tsx
@@ -9,7 +9,7 @@ export function NavigationMenuList({ children, className, ...props }: Navigation
   return (
     <NavigationMenuPrimitive.List
       className={cn(
-        'group/navigation-menu-list flex w-full flex-1 list-none items-center justify-center',
+        'group/navigation-menu-list flex w-full flex-1 list-none items-center justify-center gap-1',
         className,
       )}
       data-slot="navigation-menu-list"
diff --git a/src/components/navigation-menu/primitives/navigation-menu-trigger.tsx b/src/components/navigation-menu/primitives/navigation-menu-trigger.tsx
index 929e4df..e0665f7 100644
--- a/src/components/navigation-menu/primitives/navigation-menu-trigger.tsx
+++ b/src/components/navigation-menu/primitives/navigation-menu-trigger.tsx
@@ -13,16 +13,14 @@ export function NavigationMenuTrigger({
   return (
     <NavigationMenuPrimitive.Trigger
       className={cn(
-        'group/navigation-menu-trigger inline-flex h-9 w-max items-center justify-center rounded-full bg-background px-4 py-2 text-sm font-semibold text-[var(--nav-link-text,var(--foreground))] outline-none transition-[color,box-shadow] duration-200 [font-family:var(--nav-link-font-family,var(--font-family-body))]',
+        'group/navigation-menu-trigger focus-primary inline-flex h-9 w-max items-center justify-center rounded-full bg-background px-4 py-2 text-sm font-semibold text-[--navigation-menu-text-primary,var(--text-primary)] outline-none transition-[color,box-shadow] duration-200 [font-family:var(--navigation-menu-font,var(--font-body))]',
         // Hover state
-        'hover:bg-[var(--nav-link-background-hover,var(--contrast-100))] hover:text-[var(--nav-link-text-hover,var(--foreground))]',
+        'hover:bg-[--navigation-menu-fill-hover,var(--contrast-100)] hover:text-[--navigation-menu-text-hover,var(--text-primary)]',
         // Focus state
-        'focus:bg-[var(--nav-link-background-hover,var(--contrast-100))] focus:text-[var(--nav-link-text-hover,var(--foreground))]',
-        // Focus-visible state
-        'focus-visible:outline-2 focus-visible:outline-[var(--nav-focus,var(--brand))]',
+        'focus:bg-[--navigation-menu-fill-hover,var(--contrast-100)] focus:text-[--navigation-menu-text-hover,var(--text-primary)]',
         // Open state
-        'data-[state=open]:bg-contrast-100/50 data-[state=open]:text-foreground',
-        'data-[state=open]:hover:bg-contrast-100 data-[state=open]:focus:bg-contrast-100',
+        'data-[state=open]:bg-[color-mix(in_oklab,var(--navigation-menu-fill-hover,var(--contrast-100))_50%,transparent)] data-[state=open]:text-[--navigation-menu-text-hover,var(--text-primary)]',
+        'data-[state=open]:hover:bg-[--navigation-menu-fill-hover,var(--contrast-100)] data-[state=open]:focus:bg-[--navigation-menu-fill-hover,var(--contrast-100)]',
         // Disabled state
         'disabled:pointer-events-none disabled:opacity-50',
         className,
diff --git a/src/components/navigation-menu/primitives/navigation-menu-viewport.tsx b/src/components/navigation-menu/primitives/navigation-menu-viewport.tsx
index 053c631..6d1a0e9 100644
--- a/src/components/navigation-menu/primitives/navigation-menu-viewport.tsx
+++ b/src/components/navigation-menu/primitives/navigation-menu-viewport.tsx
@@ -13,7 +13,7 @@ export function NavigationMenuViewport({
   return (
     <NavigationMenuPrimitive.Viewport
       className={cn(
-        'origin-top-center relative mt-2 h-[var(--radix-navigation-menu-viewport-height)] w-full overflow-hidden rounded-2xl bg-[var(--nav-viewport-background,var(--background))] text-[var(--nav-text,var(--foreground))] shadow-xl ring-1 ring-black/5 @container [transition:height_200ms_ease-in-out,opacity_75ms_ease-in-out]',
+        'origin-top-center relative mt-2 h-[var(--radix-navigation-menu-viewport-height)] w-full overflow-hidden rounded-2xl bg-[--navigation-menu-fill,var(--background)] text-[--navigation-menu-text-primary,var(--foreground)] shadow-xl ring-1 ring-black/5 @container [transition:height_200ms_ease-in-out,opacity_75ms_ease-in-out]',
         // Closed state
         'data-[state=closed]:animate-out data-[state=closed]:fade-out',
         // Open state
diff --git a/src/components/navigation-menu/storybook/navigation-menu.stories.tsx b/src/components/navigation-menu/storybook/navigation-menu.stories.tsx
index d8c8eac..911d8ae 100644
--- a/src/components/navigation-menu/storybook/navigation-menu.stories.tsx
+++ b/src/components/navigation-menu/storybook/navigation-menu.stories.tsx
@@ -61,11 +61,13 @@ const defaultItems: NavigationMenuProps['items'] = [
       ],
       slot: (
         <CategoryCard
+          iconColor="light"
           image={{
             src: 'https://images.unsplash.com/photo-1441986300917-64674bd600d8?w=400&h=400&fit=crop',
             alt: 'New collection',
           }}
           link={{ href: '/new-collection', ariaLabel: 'Shop new collection' }}
+          textColor="light"
           textPosition="inside"
           textSize="medium"
           title="New Collection"
@@ -131,11 +133,13 @@ const defaultItems: NavigationMenuProps['items'] = [
       ],
       slot: (
         <CategoryCard
+          iconColor="light"
           image={{
             src: 'https://images.unsplash.com/photo-1483985988355-763728e1935b?w=400&h=400&fit=crop',
             alt: 'Women collection',
           }}
           link={{ href: '/women', ariaLabel: 'Shop women' }}
+          textColor="light"
           textPosition="inside"
           textSize="medium"
           title="Shop Women"
@@ -178,11 +182,13 @@ const defaultItems: NavigationMenuProps['items'] = [
       slot: (
         <CategoryCard
           aspectRatio="1/1"
+          iconColor="light"
           image={{
             src: 'https://images.unsplash.com/photo-1490578474895-699cd4e2cf59?w=400&h=400&fit=crop',
             alt: 'Men collection',
           }}
           link={{ href: '/men', ariaLabel: 'Shop men' }}
+          textColor="light"
           textPosition="inside"
           textSize="medium"
           title="Shop Men"
@@ -207,171 +213,34 @@ const meta: Meta<typeof NavigationMenu> = {
     docs: {
       description: {
         component: `
-A responsive navigation menu with dropdown support. Built on top of Radix UI Navigation Menu.
+A navigation menu with dropdown support. Built on Radix UI Navigation Menu.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --nav-focus: var(--brand);
-  --nav-text: var(--foreground);
-  --nav-viewport-background: var(--background);
-  --nav-viewport-border: color-mix(in oklab, var(--foreground) 15%, transparent);
-  --nav-link-text: var(--foreground);
-  --nav-link-text-hover: var(--foreground);
-  --nav-link-background: transparent;
-  --nav-link-background-hover: var(--contrast-100);
-  --nav-link-font-family: var(--font-family-body);
-  --nav-grid-label-text: var(--foreground);
-  --nav-grid-label-text-hover: var(--foreground);
-  --nav-grid-label-background: transparent;
-  --nav-grid-label-background-hover: var(--contrast-100);
-  --nav-grid-label-font-family: var(--font-family-body);
-  --nav-grid-link-text: var(--contrast-500);
-  --nav-grid-link-background: transparent;
-  --nav-grid-link-font-family: var(--font-family-body);
+  --navigation-menu-fill: var(--background);
+  --navigation-menu-text-primary: var(--text-primary);
+  --navigation-menu-text-secondary: var(--text-secondary);
+  --navigation-menu-font: var(--font-body);
+  --navigation-menu-fill-hover: var(--contrast-100);
+  --navigation-menu-text-hover: var(--text-primary);
 }
 \`\`\`
 
-## Usage
+## Item Structure
 
-### High-Level Component
+Each item can be a simple link or have dropdown content:
 
-The \`NavigationMenu\` component provides a simple data-driven API:
+- \`{ trigger: 'Home', href: '/' }\` — Simple link
+- \`{ trigger: 'Shop', content: { columns: [...], slot: <Component /> } }\` — Dropdown with columns and optional slot
 
-\`\`\`tsx
-import { NavigationMenu } from '@/components/navigation-menu';
-
-<NavigationMenu
-  items={[
-    { trigger: 'Home', href: '/' },
-    {
-      trigger: 'Shop',
-      content: {
-        columns: [
-          {
-            label: { label: 'Category', href: '/category' },
-            links: [
-              { label: 'Item 1', href: '/item-1' },
-              { label: 'Item 2', href: '/item-2' },
-            ],
-          },
-        ],
-      },
-    },
-  ]}
-/>
-\`\`\`
-
-### Custom Link Components with asChild
-
-Use the \`asChild\` prop to render your own link component (e.g., Next.js \`Link\`, React Router \`Link\`). This passes all styling and accessibility props to your custom component:
-
-\`\`\`tsx
-import Link from 'next/link';
-import { NavigationMenu } from '@/components/navigation-menu';
-
-<NavigationMenu
-  items={[
-    {
-      trigger: 'Home',
-      asChild: true,
-      children: <Link href="/">Home</Link>,
-    },
-    {
-      trigger: 'Shop',
-      content: {
-        columns: [
-          {
-            label: {
-              label: 'Category',
-              href: '/category',
-              asChild: true,
-              children: <Link href="/category">Category</Link>,
-            },
-            links: [
-              {
-                label: 'Item 1',
-                href: '/item-1',
-                asChild: true,
-                children: <Link href="/item-1">Item 1</Link>,
-              },
-            ],
-          },
-        ],
-      },
-    },
-  ]}
-/>
-\`\`\`
-
-### Composable Anatomy
+## Custom Link Components
 
-For more control, use the primitive components directly:
+Use \`asChild\` to render custom link components (e.g., Next.js \`Link\`):
 
 \`\`\`tsx
-import * as NavigationMenu from '@/components/navigation-menu';
-
-<NavigationMenu.Root viewport>
-  <NavigationMenu.List>
-    <NavigationMenu.Item>
-      <NavigationMenu.Link href="/">Home</NavigationMenu.Link>
-    </NavigationMenu.Item>
-    <NavigationMenu.Item>
-      <NavigationMenu.Trigger>Shop</NavigationMenu.Trigger>
-      <NavigationMenu.Content>
-        <NavigationMenu.Grid>
-          <NavigationMenu.GridColumn>
-            <NavigationMenu.GridLabel href="/category">
-              Category
-            </NavigationMenu.GridLabel>
-            <NavigationMenu.GridLink href="/item-1">
-              Item 1
-            </NavigationMenu.GridLink>
-          </NavigationMenu.GridColumn>
-        </NavigationMenu.Grid>
-      </NavigationMenu.Content>
-    </NavigationMenu.Item>
-  </NavigationMenu.List>
-  <NavigationMenu.Panel>
-    <NavigationMenu.Viewport />
-  </NavigationMenu.Panel>
-</NavigationMenu.Root>
-\`\`\`
-
-With custom link components:
-
-\`\`\`tsx
-import Link from 'next/link';
-import * as NavigationMenu from '@/components/navigation-menu';
-
-<NavigationMenu.Root viewport>
-  <NavigationMenu.List>
-    <NavigationMenu.Item>
-      <NavigationMenu.Link asChild>
-        <Link href="/">Home</Link>
-      </NavigationMenu.Link>
-    </NavigationMenu.Item>
-    <NavigationMenu.Item>
-      <NavigationMenu.Trigger>Shop</NavigationMenu.Trigger>
-      <NavigationMenu.Content>
-        <NavigationMenu.Grid>
-          <NavigationMenu.GridColumn>
-            <NavigationMenu.GridLabel asChild>
-              <Link href="/category">Category</Link>
-            </NavigationMenu.GridLabel>
-            <NavigationMenu.GridLink asChild>
-              <Link href="/item-1">Item 1</Link>
-            </NavigationMenu.GridLink>
-          </NavigationMenu.GridColumn>
-        </NavigationMenu.Grid>
-      </NavigationMenu.Content>
-    </NavigationMenu.Item>
-  </NavigationMenu.List>
-  <NavigationMenu.Panel>
-    <NavigationMenu.Viewport />
-  </NavigationMenu.Panel>
-</NavigationMenu.Root>
+{ trigger: 'Home', asChild: true, children: <Link href="/">Home</Link> }
 \`\`\`
         `,
       },
@@ -381,11 +250,11 @@ import * as NavigationMenu from '@/components/navigation-menu';
   argTypes: {
     items: {
       control: 'object',
-      description: 'Array of navigation menu items',
+      description: 'Array of navigation items (links or dropdowns)',
     },
     viewport: {
       control: 'boolean',
-      description: 'Whether to render the viewport container for dropdown content',
+      description: 'Render viewport container for dropdown content',
     },
     columns: {
       control: 'select',
@@ -405,11 +274,14 @@ import * as NavigationMenu from '@/components/navigation-menu';
 export default meta;
 type Story = StoryObj<NavigationMenuProps>;
 
-/**
- * The default NavigationMenu displays trigger items with dropdown content organized in columns,
- * including an optional slot for featured content like a CategoryCard.
- */
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Dropdown menu with columns and an optional slot for featured content.',
+      },
+    },
+  },
   args: {
     items: defaultItems,
     viewport: true,
@@ -417,20 +289,67 @@ export const Default: Story = {
   },
 };
 
-/**
- * Navigation items without dropdown content render as simple links.
- */
 export const SimpleLinks: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Items without `content` render as simple links.',
+      },
+    },
+  },
   args: {
     items: simpleItems,
     viewport: true,
   },
 };
 
-/**
- * Use the primitive components directly for full customization control.
- */
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitives to build custom navigation menus.',
+      },
+      source: {
+        code: `
+import * as NavigationMenu from '@/components/navigation-menu';
+
+<NavigationMenu.Root columns={4} viewport>
+  <NavigationMenu.List>
+    <NavigationMenu.Item>
+      <NavigationMenu.Link href="/">Home</NavigationMenu.Link>
+    </NavigationMenu.Item>
+    <NavigationMenu.Item>
+      <NavigationMenu.Trigger>Shop</NavigationMenu.Trigger>
+      <NavigationMenu.Content>
+        <NavigationMenu.Grid>
+          <NavigationMenu.GridColumn>
+            <NavigationMenu.GridLabel href="/featured">Featured</NavigationMenu.GridLabel>
+            <NavigationMenu.GridLink href="/new-arrivals">New arrivals</NavigationMenu.GridLink>
+            <NavigationMenu.GridLink href="/best-sellers">Best sellers</NavigationMenu.GridLink>
+          </NavigationMenu.GridColumn>
+          <NavigationMenu.GridColumn>
+            <NavigationMenu.GridLabel href="/categories">Categories</NavigationMenu.GridLabel>
+            <NavigationMenu.GridLink href="/clothing">Clothing</NavigationMenu.GridLink>
+            <NavigationMenu.GridLink href="/accessories">Accessories</NavigationMenu.GridLink>
+          </NavigationMenu.GridColumn>
+        </NavigationMenu.Grid>
+        <NavigationMenu.Slot>
+          <CategoryCard ... />
+        </NavigationMenu.Slot>
+      </NavigationMenu.Content>
+    </NavigationMenu.Item>
+    <NavigationMenu.Item>
+      <NavigationMenu.Link href="/about">About</NavigationMenu.Link>
+    </NavigationMenu.Item>
+  </NavigationMenu.List>
+  <NavigationMenu.Panel>
+    <NavigationMenu.Viewport />
+  </NavigationMenu.Panel>
+</NavigationMenu.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <NavigationMenuPrimitive.Root columns={4} delayDuration={0} viewport>
       <NavigationMenuPrimitive.List>
@@ -466,11 +385,13 @@ export const ComposableAnatomy: Story = {
             </NavigationMenuPrimitive.Grid>
             <NavigationMenuPrimitive.Slot>
               <CategoryCard
+                iconColor="light"
                 image={{
                   src: 'https://images.unsplash.com/photo-1441986300917-64674bd600d8?w=400&h=400&fit=crop',
                   alt: 'New collection',
                 }}
                 link={{ href: '/new-collection', ariaLabel: 'Shop new collection' }}
+                textColor="light"
                 textPosition="inside"
                 textSize="medium"
                 title="New Collection"
diff --git a/src/components/offset-pagination/offset-pagination.tsx b/src/components/offset-pagination/offset-pagination.tsx
index b5ce42d..379405d 100644
--- a/src/components/offset-pagination/offset-pagination.tsx
+++ b/src/components/offset-pagination/offset-pagination.tsx
@@ -21,16 +21,13 @@ export interface OffsetPaginationProps {
  *
  * ```css
  * :root {
- *   --offset-pagination-focus: var(--brand);
- *   --offset-pagination-font-family: var(--font-family-body);
+ *   --offset-pagination-font: var(--font-body);
  *   --offset-pagination-ellipsis: var(--foreground);
- *   --offset-pagination-border: var(--contrast-100)  ;
- *   --offset-pagination-text: var(--foreground)  ;
- *   --offset-pagination-background-hover: var(--contrast-100)  ;
- *   --offset-pagination-current-page-border: var(--foreground);
- *   --offset-pagination-current-page-background: var(--foreground);
- *   --offset-pagination-current-page-text: var(--background);
- *   --offset-pagination-current-page-background-hover: var(--contrast-500);
+ *   --offset-pagination-text-primary: var(--text-primary);
+ *   --offset-pagination-fill-hover: var(--contrast-100);
+ *   --offset-pagination-fill-current: var(--foreground);
+ *   --offset-pagination-text-current: var(--text-inverse);
+ *   --offset-pagination-fill-current-hover: var(--contrast-500);
  * }
  * ```
  */
diff --git a/src/components/offset-pagination/primitives/offset-pagination-ellipsis.tsx b/src/components/offset-pagination/primitives/offset-pagination-ellipsis.tsx
index 85c198c..b312dba 100644
--- a/src/components/offset-pagination/primitives/offset-pagination-ellipsis.tsx
+++ b/src/components/offset-pagination/primitives/offset-pagination-ellipsis.tsx
@@ -13,7 +13,7 @@ export function OffsetPaginationEllipsis({
     <span
       aria-hidden
       className={cn(
-        'flex h-12 w-12 items-center justify-center text-[var(--offset-pagination-ellipsis,var(--foreground))]',
+        'flex h-12 w-12 items-center justify-center text-[--offset-pagination-ellipsis,var(--foreground)]',
         className,
       )}
       data-slot="offset-pagination-ellipsis"
diff --git a/src/components/offset-pagination/primitives/offset-pagination-link.tsx b/src/components/offset-pagination/primitives/offset-pagination-link.tsx
index 2f2ef3a..2619f3a 100644
--- a/src/components/offset-pagination/primitives/offset-pagination-link.tsx
+++ b/src/components/offset-pagination/primitives/offset-pagination-link.tsx
@@ -18,13 +18,9 @@ export function OffsetPaginationLink({
   return (
     <Component
       className={cn(
-        'flex size-12 items-center justify-center rounded-full border border-[var(--offset-pagination-border,var(--contrast-100))] text-[var(--offset-pagination-text,var(--foreground))] transition-colors duration-300',
-        // Hover state
-        'hover:bg-[var(--offset-pagination-background-hover,var(--contrast-100))]',
-        // Focus state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--offset-pagination-focus,var(--brand))]',
+        'focus-primary flex size-12 items-center justify-center rounded-full border border-[--border-subtle] text-[--offset-pagination-text-primary,var(--text-primary)] transition-colors duration-300 hover:bg-[--offset-pagination-fill-hover,var(--contrast-100)]',
         // Current page state
-        'aria-[current=page]:border-[var(--offset-pagination-current-page-border,var(--foreground))] aria-[current=page]:bg-[var(--offset-pagination-current-page-background,var(--foreground))] aria-[current=page]:text-[var(--offset-pagination-current-page-text,var(--background))] aria-[current=page]:hover:bg-[var(--offset-pagination-current-page-background-hover,var(--contrast-500))]',
+        'aria-[current=page]:border-[--border-inverse] aria-[current=page]:bg-[--offset-pagination-fill-current,var(--foreground)] aria-[current=page]:text-[--offset-pagination-text-current,var(--text-inverse)] aria-[current=page]:hover:bg-[--offset-pagination-fill-current-hover,var(--contrast-500)]',
         className,
       )}
       data-slot="offset-pagination-link"
diff --git a/src/components/offset-pagination/primitives/offset-pagination-root.tsx b/src/components/offset-pagination/primitives/offset-pagination-root.tsx
index 6cd6983..245700e 100644
--- a/src/components/offset-pagination/primitives/offset-pagination-root.tsx
+++ b/src/components/offset-pagination/primitives/offset-pagination-root.tsx
@@ -8,7 +8,7 @@ export function OffsetPaginationRoot({ className, children, ...props }: OffsetPa
   return (
     <nav
       className={cn(
-        'py-10 text-xs font-[var(--offset-pagination-font-family,var(--font-family-body))]',
+        'py-10 text-xs [font-family:var(--offset-pagination-font,var(--font-body))]',
         className,
       )}
       data-slot="offset-pagination-root"
diff --git a/src/components/offset-pagination/storybook/offset-pagination.stories.tsx b/src/components/offset-pagination/storybook/offset-pagination.stories.tsx
index 389c64d..715913e 100644
--- a/src/components/offset-pagination/storybook/offset-pagination.stories.tsx
+++ b/src/components/offset-pagination/storybook/offset-pagination.stories.tsx
@@ -60,76 +60,21 @@ const meta: Meta<typeof OffsetPagination> = {
     docs: {
       description: {
         component: `
-A pagination component for navigating through pages of content with ellipsis support for large page counts.
+A pagination component for navigating through pages with ellipsis support for large page counts.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --offset-pagination-focus: var(--brand);
-  --offset-pagination-font-family: var(--font-family-body);
+  --offset-pagination-font: var(--font-body);
   --offset-pagination-ellipsis: var(--foreground);
-  --offset-pagination-border: var(--contrast-100);
-  --offset-pagination-text: var(--foreground);
-  --offset-pagination-background-hover: var(--contrast-100);
-  --offset-pagination-current-page-border: var(--foreground);
-  --offset-pagination-current-page-background: var(--foreground);
-  --offset-pagination-current-page-text: var(--background);
-  --offset-pagination-current-page-background-hover: var(--contrast-500);
+  --offset-pagination-text-primary: var(--text-primary);
+  --offset-pagination-fill-hover: var(--contrast-100);
+  --offset-pagination-fill-current: var(--foreground);
+  --offset-pagination-text-current: var(--text-inverse);
+  --offset-pagination-fill-current-hover: var(--contrast-500);
 }
 \`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`OffsetPagination\` component takes a \`pages\` array and \`currentPage\`:
-
-\`\`\`tsx
-import { OffsetPagination, type PageItem } from '@/components/offset-pagination';
-
-const pages: Array<PageItem | 'ellipsis'> = [
-  { href: '/products?page=1', page: 1 },
-  'ellipsis',
-  { href: '/products?page=4', page: 4 },
-  { href: '/products?page=5', page: 5 },
-  { href: '/products?page=6', page: 6 },
-  'ellipsis',
-  { href: '/products?page=10', page: 10 },
-];
-
-<OffsetPagination
-  pages={pages}
-  currentPage={5}
-  label="Product pagination"
-/>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as OffsetPagination from '@/components/offset-pagination';
-
-<OffsetPagination.Root aria-label="pagination" role="navigation">
-  <OffsetPagination.List>
-    <OffsetPagination.Item>
-      <OffsetPagination.Link href="/products?page=1">1</OffsetPagination.Link>
-    </OffsetPagination.Item>
-    <OffsetPagination.Item>
-      <OffsetPagination.Ellipsis />
-    </OffsetPagination.Item>
-    <OffsetPagination.Item>
-      <OffsetPagination.Link href="/products?page=5" aria-current="page">
-        5
-      </OffsetPagination.Link>
-    </OffsetPagination.Item>
-  </OffsetPagination.List>
-</OffsetPagination.Root>
-\`\`\`
-
-The \`Link\` component supports \`asChild\` for router integration with Next.js Link or React Router.
         `,
       },
     },
@@ -138,7 +83,7 @@ The \`Link\` component supports \`asChild\` for router integration with Next.js
   argTypes: {
     pages: {
       control: false,
-      description: 'Array of page items or ellipsis markers',
+      description: 'Array of `PageItem` objects or `"ellipsis"` strings',
     },
     currentPage: {
       control: 'number',
@@ -154,24 +99,67 @@ The \`Link\` component supports \`asChild\` for router integration with Next.js
 export default meta;
 type Story = StoryObj<OffsetPaginationProps>;
 
-// Default pagination (middle of range with ellipsis)
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Pagination in the middle of a range with ellipsis on both sides.',
+      },
+    },
+  },
   args: {
     pages: generatePages(10, 5),
     currentPage: 5,
   },
 };
 
-// Few pages (no ellipsis needed)
 export const FewPages: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'When there are few pages, no ellipsis is needed.',
+      },
+    },
+  },
   args: {
     pages: generatePages(4, 2),
     currentPage: 2,
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitive components for custom layouts.',
+      },
+      source: {
+        code: `
+<OffsetPaginationPrimitive.Root aria-label="pagination" role="navigation">
+  <OffsetPaginationPrimitive.List>
+    <OffsetPaginationPrimitive.Item>
+      <OffsetPaginationPrimitive.Link href="/products?page=1">1</OffsetPaginationPrimitive.Link>
+    </OffsetPaginationPrimitive.Item>
+    <OffsetPaginationPrimitive.Item>
+      <OffsetPaginationPrimitive.Ellipsis />
+    </OffsetPaginationPrimitive.Item>
+    <OffsetPaginationPrimitive.Item>
+      <OffsetPaginationPrimitive.Link href="/products?page=5" aria-current="page">
+        5
+      </OffsetPaginationPrimitive.Link>
+    </OffsetPaginationPrimitive.Item>
+    <OffsetPaginationPrimitive.Item>
+      <OffsetPaginationPrimitive.Ellipsis />
+    </OffsetPaginationPrimitive.Item>
+    <OffsetPaginationPrimitive.Item>
+      <OffsetPaginationPrimitive.Link href="/products?page=10">10</OffsetPaginationPrimitive.Link>
+    </OffsetPaginationPrimitive.Item>
+  </OffsetPaginationPrimitive.List>
+</OffsetPaginationPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <OffsetPaginationPrimitive.Root aria-label="pagination" role="navigation">
       <OffsetPaginationPrimitive.List>
diff --git a/src/components/price/price.tsx b/src/components/price/price.tsx
index a9cd734..e260a0d 100644
--- a/src/components/price/price.tsx
+++ b/src/components/price/price.tsx
@@ -29,10 +29,7 @@ export interface PriceProps extends PricePrimitive.RootProps {
  *
  * ```css
  * :root {
- *   --price-light-text: var(--foreground);
- *   --price-light-sale-text: var(--foreground);
- *   --price-dark-text: var(--background);
- *   --price-dark-sale-text: var(--background);
+ *   --price-text: var(--text-primary);
  * }
  * ```
  */
diff --git a/src/components/price/primitives/price-root.tsx b/src/components/price/primitives/price-root.tsx
index 7590fe3..e67553a 100644
--- a/src/components/price/primitives/price-root.tsx
+++ b/src/components/price/primitives/price-root.tsx
@@ -8,7 +8,7 @@ export function PriceRoot({ className, children, ...props }: PriceRootProps) {
   return (
     <div
       className={cn(
-        'text-base font-semibold text-[var(--price-light-text,var(--foreground))]',
+        'text-base font-semibold text-[var(--price-text,var(--text-primary))]',
         className,
       )}
       data-slot="price-root"
diff --git a/src/components/price/storybook/price.stories.tsx b/src/components/price/storybook/price.stories.tsx
index 86bf7a7..04d3188 100644
--- a/src/components/price/storybook/price.stories.tsx
+++ b/src/components/price/storybook/price.stories.tsx
@@ -17,43 +17,8 @@ A price display component supporting default, range, and sale price formats.
 
 \`\`\`css
 :root {
-  --price-light-text: var(--foreground);
-  --price-light-sale-text: var(--foreground);
-  --price-dark-text: var(--background);
-  --price-dark-sale-text: var(--background);
+  --price-text: var(--text-primary);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Price\` component provides a simple API with a \`price\` object:
-
-\`\`\`tsx
-import { Price } from '@/components/price';
-
-// Default price
-<Price price={{ type: 'default', value: '$18.00' }} />
-
-// Range price (for products with variants)
-<Price price={{ type: 'range', minValue: '$8.99', maxValue: '$29.00' }} />
-
-// Sale price (with strikethrough)
-<Price price={{ type: 'sale', previousValue: '$18.00', currentValue: '$12.00' }} />
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Price from '@/components/price';
-
-<Price.Root>
-  <Price.Strike>$18.00</Price.Strike>{' '}
-  <Price.Default>$12.00</Price.Default>
-</Price.Root>
 \`\`\`
         `,
       },
@@ -63,7 +28,8 @@ import * as Price from '@/components/price';
   argTypes: {
     price: {
       control: 'object',
-      description: 'The price object with type and values',
+      description:
+        'Price object with `type` ("default", "range", or "sale") and corresponding value fields',
     },
   },
 };
@@ -71,8 +37,14 @@ import * as Price from '@/components/price';
 export default meta;
 type Story = StoryObj<PriceProps>;
 
-// Default single price
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A single price display.',
+      },
+    },
+  },
   args: {
     price: {
       type: 'default',
@@ -81,8 +53,14 @@ export const Default: Story = {
   },
 };
 
-// Range price for products with variants
 export const Range: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A price range for products with multiple variants.',
+      },
+    },
+  },
   args: {
     price: {
       type: 'range',
@@ -92,8 +70,14 @@ export const Range: Story = {
   },
 };
 
-// Sale price with strikethrough
 export const Sale: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'A sale price with the original price struck through.',
+      },
+    },
+  },
   args: {
     price: {
       type: 'sale',
@@ -103,8 +87,22 @@ export const Sale: Story = {
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitive components for custom layouts.',
+      },
+      source: {
+        code: `
+<PricePrimitive.Root>
+  <PricePrimitive.Strike>$18.00</PricePrimitive.Strike>{' '}
+  <PricePrimitive.Default>$12.00</PricePrimitive.Default>
+</PricePrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <PricePrimitive.Root>
       <PricePrimitive.Strike>$18.00</PricePrimitive.Strike>{' '}
diff --git a/src/components/product-card/primitives/product-card-fallback.tsx b/src/components/product-card/primitives/product-card-fallback.tsx
index 496546e..fe86d52 100644
--- a/src/components/product-card/primitives/product-card-fallback.tsx
+++ b/src/components/product-card/primitives/product-card-fallback.tsx
@@ -8,7 +8,7 @@ export function ProductCardFallback({ className, children, ...props }: ProductCa
   return (
     <div
       className={cn(
-        'break-words p-4 text-4xl font-bold leading-none tracking-tight transition-transform duration-500 ease-out [color:color-mix(in_oklab,var(--foreground)_30%,transparent)] group-hover:scale-105',
+        'break-words p-4 text-3xl font-bold text-[color-mix(in_oklab,var(--product-card-text-primary,var(--text-primary))_30%,transparent)] transition-transform duration-500 ease-out group-hover:scale-105',
         className,
       )}
       data-slot="product-card-fallback"
diff --git a/src/components/product-card/primitives/product-card-image.tsx b/src/components/product-card/primitives/product-card-image.tsx
index c030527..865a841 100644
--- a/src/components/product-card/primitives/product-card-image.tsx
+++ b/src/components/product-card/primitives/product-card-image.tsx
@@ -18,9 +18,7 @@ export function ProductCardImage({
   return (
     <Component
       className={cn(
-        'size-full scale-100 select-none bg-[var(--product-card-light-background,var(--contrast-100))] object-cover transition-transform duration-500 ease-out',
-        // Group hover state
-        'group-hover/product-card:scale-110',
+        'size-full scale-100 select-none object-cover transition-transform duration-500 ease-out group-hover/product-card:scale-110',
         className,
       )}
       data-slot="product-card-image"
diff --git a/src/components/product-card/primitives/product-card-link.tsx b/src/components/product-card/primitives/product-card-link.tsx
index c6f252e..b8b6601 100644
--- a/src/components/product-card/primitives/product-card-link.tsx
+++ b/src/components/product-card/primitives/product-card-link.tsx
@@ -13,7 +13,7 @@ export function ProductCardLink({ asChild = false, className, ...props }: Produc
   return (
     <Component
       className={cn(
-        'absolute inset-0 rounded-[var(--product-card-border-radius,1rem)] focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-[var(--product-card-focus,var(--brand))]',
+        'focus-primary absolute inset-0 rounded-[var(--product-card-radius,1rem)]',
         className,
       )}
       data-slot="product-card-link"
diff --git a/src/components/product-card/primitives/product-card-root.tsx b/src/components/product-card/primitives/product-card-root.tsx
index b2731d4..f1e0e9b 100644
--- a/src/components/product-card/primitives/product-card-root.tsx
+++ b/src/components/product-card/primitives/product-card-root.tsx
@@ -21,10 +21,7 @@ export function ProductCardRoot<T extends ElementType = 'article'>({
 
   return (
     <ProductCardRootElement
-      className={cn(
-        'group/product-card flex w-full max-w-md flex-col font-[var(--product-card-font-family,var(--font-family-body))] @container',
-        className,
-      )}
+      className={cn('group/product-card flex w-full flex-col @container', className)}
       data-aspect-ratio={aspectRatio}
       data-slot="product-card-root"
       {...props}
diff --git a/src/components/product-card/primitives/product-card-skeleton.tsx b/src/components/product-card/primitives/product-card-skeleton.tsx
index 7a38921..fa6d9ff 100644
--- a/src/components/product-card/primitives/product-card-skeleton.tsx
+++ b/src/components/product-card/primitives/product-card-skeleton.tsx
@@ -10,7 +10,7 @@ export function ProductCardSkeleton({ className, ...props }: ProductCardSkeleton
     <SkeletonPrimitive.Root className={cn(className)} data-slot="product-card-skeleton" {...props}>
       <SkeletonPrimitive.Box
         className={cn(
-          'rounded-[var(--product-card-border-radius,1rem)]',
+          'rounded-[var(--product-card-radius,1rem)]',
           'group-data-[aspect-ratio=5/6]/product-card:aspect-[5/6]',
           'group-data-[aspect-ratio=3/4]/product-card:aspect-[3/4]',
           'group-data-[aspect-ratio=1/1]/product-card:aspect-square',
diff --git a/src/components/product-card/primitives/product-card-subtitle.tsx b/src/components/product-card/primitives/product-card-subtitle.tsx
index 8182d55..71daea0 100644
--- a/src/components/product-card/primitives/product-card-subtitle.tsx
+++ b/src/components/product-card/primitives/product-card-subtitle.tsx
@@ -8,7 +8,7 @@ export function ProductCardSubtitle({ children, className, ...props }: ProductCa
   return (
     <span
       className={cn(
-        'block text-sm font-normal text-[var(--product-card-light-subtitle,color-mix(in_oklab,var(--foreground)_75%,transparent))]',
+        'block text-sm text-[--product-card-text-secondary,var(--text-secondary)] [font-family:var(--product-card-font-subtitle,var(--font-body))]',
         className,
       )}
       data-slot="product-card-subtitle"
diff --git a/src/components/product-card/primitives/product-card-thumbnail.tsx b/src/components/product-card/primitives/product-card-thumbnail.tsx
index ae4e1bd..8c1d3b3 100644
--- a/src/components/product-card/primitives/product-card-thumbnail.tsx
+++ b/src/components/product-card/primitives/product-card-thumbnail.tsx
@@ -8,7 +8,7 @@ export function ProductCardThumbnail({ className, children, ...props }: ProductC
   return (
     <div
       className={cn(
-        'relative overflow-hidden rounded-[var(--product-card-border-radius,1rem)] bg-[var(--product-card-light-background,var(--contrast-100))]',
+        'relative overflow-hidden rounded-[var(--product-card-radius,1rem)] bg-[--fill-image]',
         'group-data-[aspect-ratio=5/6]/product-card:aspect-[5/6]',
         'group-data-[aspect-ratio=3/4]/product-card:aspect-[3/4]',
         'group-data-[aspect-ratio=1/1]/product-card:aspect-square',
diff --git a/src/components/product-card/primitives/product-card-title.tsx b/src/components/product-card/primitives/product-card-title.tsx
index 3dac91d..1c8af27 100644
--- a/src/components/product-card/primitives/product-card-title.tsx
+++ b/src/components/product-card/primitives/product-card-title.tsx
@@ -8,7 +8,7 @@ export function ProductCardTitle({ className, children, ...props }: ProductCardT
   return (
     <h3
       className={cn(
-        'block font-semibold text-[var(--product-card-light-title,var(--foreground))]',
+        'block font-semibold text-[--product-card-text-primary,var(--text-primary)] [font-family:var(--product-card-font-title,var(--font-body))]',
         className,
       )}
       data-slot="product-card-title"
diff --git a/src/components/product-card/product-card.tsx b/src/components/product-card/product-card.tsx
index c35e9fc..4cef46f 100644
--- a/src/components/product-card/product-card.tsx
+++ b/src/components/product-card/product-card.tsx
@@ -75,18 +75,11 @@ export interface ProductCardProps {
  *
  * ```css
  * :root {
- *   --product-card-focus: var(--brand);
- *   --product-card-empty-text: color-mix(in oklab, var(--foreground) 15%, transparent);
- *   --product-card-light-offset: var(--background);
- *   --product-card-light-background: var(--contrast-100);
- *   --product-card-light-title: var(--foreground);
- *   --product-card-light-subtitle: color-mix(in oklab, var(--foreground) 75%, transparent);
- *   --product-card-dark-offset: var(--foreground);
- *   --product-card-dark-background: var(--contrast-500);
- *   --product-card-dark-title: var(--background);
- *   --product-card-dark-subtitle: color-mix(in oklab, var(--background) 75%, transparent);
- *   --product-card-font-family: var(--font-family-body);
- *   --product-card-border-radius: 1rem;
+ *   --product-card-text-primary: var(--text-primary);
+ *   --product-card-text-secondary: var(--text-secondary);
+ *   --product-card-font-title: var(--font-body);
+ *   --product-card-font-subtitle: var(--font-body);
+ *   --product-card-radius: 1rem;
  * }
  * ```
  */
diff --git a/src/components/product-card/storybook/product-card.stories.tsx b/src/components/product-card/storybook/product-card.stories.tsx
index 979f6c4..064aeaa 100644
--- a/src/components/product-card/storybook/product-card.stories.tsx
+++ b/src/components/product-card/storybook/product-card.stories.tsx
@@ -13,95 +13,27 @@ const meta: Meta<typeof ProductCard> = {
     docs: {
       description: {
         component: `
-A versatile product card component for displaying product information with optional actions. Supports product images, badges, ratings, pricing, and both cart and compare actions.
+A product card for displaying product information with optional actions like add-to-cart and compare.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --product-card-focus: var(--brand);
-  --product-card-empty-text: color-mix(in oklab, var(--foreground) 15%, transparent);
-  --product-card-light-offset: var(--background);
-  --product-card-light-background: var(--contrast-100);
-  --product-card-light-title: var(--foreground);
-  --product-card-light-subtitle: color-mix(in oklab, var(--foreground) 75%, transparent);
-  --product-card-dark-offset: var(--foreground);
-  --product-card-dark-background: var(--contrast-500);
-  --product-card-dark-title: var(--background);
-  --product-card-dark-subtitle: color-mix(in oklab, var(--background) 75%, transparent);
-  --product-card-font-family: var(--font-family-body);
-  --product-card-border-radius: 1rem;
+  --product-card-text-primary: var(--text-primary);
+  --product-card-text-secondary: var(--text-secondary);
+  --product-card-font-title: var(--font-body);
+  --product-card-font-subtitle: var(--font-body);
+  --product-card-radius: 1rem;
 }
 \`\`\`
 
-## Usage
-
-### High-Level Component
-
-The \`ProductCard\` component provides a comprehensive API for displaying products:
-
-\`\`\`tsx
-import { ProductCard } from '@/components/product-card';
-
-<ProductCard
-  aspectRatio="5/6"
-  product={{
-    id: 'product-id',
-    title: 'Product Name',
-    subtitle: 'Category',
-    badge: 'Sale',
-    link: { href: '/products/id', ariaLabel: 'View Product' },
-    image: { src: '...', alt: '...' },
-    showRating: true,
-    rating: 4.5,
-    price: { type: 'default', value: '$19.99' },
-  }}
-  cartAction={{
-    type: 'form',
-    action: (formData) => console.log('Add to cart:', formData.get('id')),
-    label: 'Add to Cart',
-  }}
-/>
-\`\`\`
-
-### Price Types
+## Price Types
 
 The \`price\` prop supports three formats:
 
-- \`{ type: 'default', value: '$19.99' }\` - Standard price
-- \`{ type: 'sale', previousValue: '$29.99', currentValue: '$19.99' }\` - Sale price
-- \`{ type: 'range', minValue: '$19.99', maxValue: '$29.99' }\` - Price range
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as ProductCard from '@/components/product-card';
-
-<ProductCard.Root aspectRatio="5/6">
-  <ProductCard.Preview>
-    <ProductCard.Thumbnail>
-      <ProductCard.Image src="..." alt="..." />
-      <ProductCard.Badge>Sale</ProductCard.Badge>
-    </ProductCard.Thumbnail>
-    <ProductCard.Link href="..." aria-label="..." />
-  </ProductCard.Preview>
-  <ProductCard.Details>
-    <ProductCard.Header>
-      <ProductCard.Title>Product Name</ProductCard.Title>
-      <ProductCard.Subtitle>Category</ProductCard.Subtitle>
-      <ProductCard.Price price={{ type: 'default', value: '$19.99' }} />
-      <ProductCard.Rating rating={4.5} />
-      <ProductCard.Link href="..." aria-label="..." />
-    </ProductCard.Header>
-  </ProductCard.Details>
-  <ProductCard.Actions>
-    <ProductCard.CartButton>Add to Cart</ProductCard.CartButton>
-    <ProductCard.Compare id="compare-id" label="Compare" />
-  </ProductCard.Actions>
-</ProductCard.Root>
-\`\`\`
+- \`{ type: 'default', value: '$19.99' }\` — Standard price
+- \`{ type: 'sale', previousValue: '$29.99', currentValue: '$19.99' }\` — Sale price
+- \`{ type: 'range', minValue: '$19.99', maxValue: '$29.99' }\` — Price range
         `,
       },
     },
@@ -111,19 +43,19 @@ import * as ProductCard from '@/components/product-card';
     aspectRatio: {
       control: 'select',
       options: ['5/6', '3/4', '1/1'],
-      description: 'The aspect ratio of the product thumbnail',
+      description: 'Thumbnail aspect ratio',
     },
     product: {
       control: false,
-      description: 'Product data object including title, image, price, rating, and link',
+      description: 'Product data (title, image, price, rating, link, badge)',
     },
     compareAction: {
       control: false,
-      description: 'Configuration for the compare checkbox action',
+      description: 'Compare checkbox configuration',
     },
     cartAction: {
       control: false,
-      description: 'Configuration for the cart action (form submission or link)',
+      description: 'Cart action (form submission or link)',
     },
   },
   decorators: [
@@ -138,31 +70,14 @@ import * as ProductCard from '@/components/product-card';
 export default meta;
 type Story = StoryObj<ProductCardProps>;
 
-// Default product card
 export const Default: Story = {
-  args: {
-    product: {
-      id: 'natural-fiber-scrub-brush',
-      title: 'Natural Fiber Scrub Brush',
-      subtitle: 'Kitchen Essentials',
-      link: {
-        href: '/products/natural-fiber-scrub-brush',
-        ariaLabel: 'View Natural Fiber Scrub Brush',
-      },
-      image: {
-        src: 'https://images.unsplash.com/photo-1685052392951-4eb54985d3ae?w=900',
-        alt: 'Natural fiber scrub brush with wooden handle',
+  parameters: {
+    docs: {
+      description: {
+        story: 'Product card with badge, rating, and standard price.',
       },
-      showRating: true,
-      rating: 4.5,
-      price: { type: 'default', value: '$8.99' },
     },
-    aspectRatio: '5/6',
   },
-};
-
-// With badge overlay
-export const WithBadge: Story = {
   args: {
     product: {
       id: 'eco-cleaning-starter-kit',
@@ -185,8 +100,14 @@ export const WithBadge: Story = {
   },
 };
 
-// With sale price
 export const WithSalePrice: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `{ type: "sale" }` price to show original and discounted prices.',
+      },
+    },
+  },
   args: {
     product: {
       id: 'glass-soap-pump-bottle',
@@ -209,8 +130,14 @@ export const WithSalePrice: Story = {
   },
 };
 
-// With cart action
 export const WithCartAction: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `cartAction` with `type: "form"` for server action integration.',
+      },
+    },
+  },
   args: {
     product: {
       id: 'minimal-ceramic-soap-dispenser',
@@ -239,8 +166,39 @@ export const WithCartAction: Story = {
   },
 };
 
-// With compare action (controlled)
 export const WithCompareAction: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `compareAction` for a controlled compare checkbox.',
+      },
+      source: {
+        code: `
+const [checked, setChecked] = useState(false);
+
+<ProductCard
+  aspectRatio="5/6"
+  compareAction={{
+    id: 'compare-product',
+    checked,
+    onCheckedChange: (value) => setChecked(value === true),
+    label: 'Compare',
+  }}
+  product={{
+    id: 'product-id',
+    title: 'Product Name',
+    subtitle: 'Category',
+    link: { href: '/products/id', ariaLabel: 'View Product' },
+    image: { src: '...', alt: '...' },
+    showRating: true,
+    rating: 4.3,
+    price: { type: 'default', value: '$10.50' },
+  }}
+/>
+        `,
+      },
+    },
+  },
   render: () => {
     const [checked, setChecked] = useState(false);
 
@@ -274,8 +232,42 @@ export const WithCompareAction: Story = {
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitives to build custom product card layouts.',
+      },
+      source: {
+        code: `
+import * as ProductCardPrimitive from '@/components/product-card/primitives';
+
+<ProductCardPrimitive.Root aspectRatio="5/6">
+  <ProductCardPrimitive.Preview>
+    <ProductCardPrimitive.Thumbnail>
+      <ProductCardPrimitive.Image src="..." alt="..." />
+      <ProductCardPrimitive.Badge>Popular</ProductCardPrimitive.Badge>
+    </ProductCardPrimitive.Thumbnail>
+    <ProductCardPrimitive.Link href="..." aria-label="..." />
+  </ProductCardPrimitive.Preview>
+  <ProductCardPrimitive.Details>
+    <ProductCardPrimitive.Header>
+      <ProductCardPrimitive.Title>Product Name</ProductCardPrimitive.Title>
+      <ProductCardPrimitive.Subtitle>Category</ProductCardPrimitive.Subtitle>
+      <ProductCardPrimitive.Price price={{ type: 'default', value: '$9.99' }} />
+      <ProductCardPrimitive.Rating rating={4.5} />
+      <ProductCardPrimitive.Link href="..." aria-label="..." />
+    </ProductCardPrimitive.Header>
+  </ProductCardPrimitive.Details>
+  <ProductCardPrimitive.Actions>
+    <ProductCardPrimitive.CartButton>Add to Cart</ProductCardPrimitive.CartButton>
+    <ProductCardPrimitive.Compare id="compare-id" label="Compare" />
+  </ProductCardPrimitive.Actions>
+</ProductCardPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <ProductCardPrimitive.Root aspectRatio="5/6">
       <ProductCardPrimitive.Preview>
@@ -311,8 +303,21 @@ export const ComposableAnatomy: Story = {
   ),
 };
 
-// Skeleton loading state
 export const Skeleton: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Loading state while product data loads.',
+      },
+      source: {
+        code: `
+<ProductCardPrimitive.Root aspectRatio="5/6">
+  <ProductCardPrimitive.Skeleton />
+</ProductCardPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <ProductCardPrimitive.Root aspectRatio="5/6">
       <ProductCardPrimitive.Skeleton />
diff --git a/src/components/radio-group/primitives/radio-group-indicator.tsx b/src/components/radio-group/primitives/radio-group-indicator.tsx
index ee50827..c15cad0 100644
--- a/src/components/radio-group/primitives/radio-group-indicator.tsx
+++ b/src/components/radio-group/primitives/radio-group-indicator.tsx
@@ -11,7 +11,7 @@ export function RadioGroupIndicator({ className, children, ...props }: RadioGrou
   return (
     <RadioGroupPrimitive.Indicator
       className={cn(
-        'relative flex size-full items-center justify-center after:block after:size-3 after:rounded-full after:bg-[var(--radio-group-light-indicator-background,var(--foreground))]',
+        'relative flex size-full items-center justify-center after:block after:size-3 after:rounded-full after:bg-[--radio-group-fill-checked,var(--form-fill-checked)]',
         className,
       )}
       data-slot="radio-group-indicator"
diff --git a/src/components/radio-group/primitives/radio-group-item.tsx b/src/components/radio-group/primitives/radio-group-item.tsx
index f0e5d12..17000ae 100644
--- a/src/components/radio-group/primitives/radio-group-item.tsx
+++ b/src/components/radio-group/primitives/radio-group-item.tsx
@@ -11,13 +11,11 @@ export function RadioGroupItem({ children, className, ...props }: RadioGroupItem
   return (
     <RadioGroupPrimitive.Item
       className={cn(
-        'size-5 cursor-default rounded-full border border-[var(--radio-group-light-border,var(--contrast-200))] bg-[var(--radio-group-light-background,var(--background))]',
+        'focus-primary size-5 cursor-default rounded-full border border-[--border] bg-[--radio-group-fill,var(--form-fill)]',
         // Hover state
-        'hover:border-[var(--radio-group-light-border-hover,var(--contrast-300))]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--radio-group-light-focus,var(--brand))]',
+        'hover:border-[--border-hover]',
         // Aria-invalid state
-        'aria-invalid:border-[var(--radio-group-light-border-error,var(--error))] aria-invalid:disabled:border-[var(--radio-group-light-disabled-border-error,color-mix(in_oklab,var(--error)_50%,transparent))]',
+        'aria-invalid:border-[--border-error] aria-invalid:disabled:border-[color-mix(in_oklab,var(--error)_50%,transparent)]',
         // Disabled state
         'data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&:disabled+label]:pointer-events-none [&:disabled+label]:opacity-50',
         className,
diff --git a/src/components/radio-group/radio-group.tsx b/src/components/radio-group/radio-group.tsx
index 8757c2a..51a33b2 100644
--- a/src/components/radio-group/radio-group.tsx
+++ b/src/components/radio-group/radio-group.tsx
@@ -20,13 +20,8 @@ export type RadioGroupProps = ComponentProps<typeof RadioGroupPrimitive.Root> &
  *
  * ```css
  * :root {
- *   --radio-group-light-background: var(--background);
- *   --radio-group-light-border: var(--contrast-200);
- *   --radio-group-light-border-hover: var(--contrast-300);
- *   --radio-group-light-border-error: var(--error);
- *   --radio-group-light-disabled-border-error: color-mix(in oklab, var(--error) 50%, transparent);
- *   --radio-group-light-focus: var(--brand);
- *   --radio-group-light-indicator-background: var(--foreground);
+ *   --radio-group-fill: var(--form-fill);
+ *   --radio-group-fill-checked: var(--form-fill-checked);
  * }
  * ```
  */
diff --git a/src/components/radio-group/storybook/radio-group.stories.tsx b/src/components/radio-group/storybook/radio-group.stories.tsx
index 05b7d4a..00dc001 100644
--- a/src/components/radio-group/storybook/radio-group.stories.tsx
+++ b/src/components/radio-group/storybook/radio-group.stories.tsx
@@ -32,13 +32,8 @@ A radio group component for selecting a single option from a set of choices. Bui
 
 \`\`\`css
 :root {
-  --radio-group-light-background: var(--background);
-  --radio-group-light-border: var(--contrast-200);
-  --radio-group-light-border-hover: var(--contrast-300);
-  --radio-group-light-border-error: var(--error);
-  --radio-group-light-disabled-border-error: color-mix(in oklab, var(--error) 50%, transparent);
-  --radio-group-light-focus: var(--brand);
-  --radio-group-light-indicator-background: var(--foreground);
+  --radio-group-fill: var(--form-fill);
+  --radio-group-fill-checked: var(--form-fill-checked);
 }
 \`\`\`
 
diff --git a/src/components/range-input/primitives/range-input-icon.tsx b/src/components/range-input/primitives/range-input-icon.tsx
index 94e947d..1000045 100644
--- a/src/components/range-input/primitives/range-input-icon.tsx
+++ b/src/components/range-input/primitives/range-input-icon.tsx
@@ -13,9 +13,11 @@ export interface RangeInputIconProps {
 }
 
 export function RangeInputIcon({ asChild = false, className, children }: RangeInputIconProps) {
+  const iconStyles = cn('size-5', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-5', className)} data-slot="range-input-icon">
+      <Slot className={iconStyles} data-slot="range-input-icon">
         {children}
       </Slot>
     );
@@ -24,7 +26,7 @@ export function RangeInputIcon({ asChild = false, className, children }: RangeIn
   return (
     <ArrowRight
       absoluteStrokeWidth
-      className={cn('size-5', className)}
+      className={iconStyles}
       data-slot="range-input-icon"
       strokeWidth={1}
     />
diff --git a/src/components/rating/primitives/rating-star.tsx b/src/components/rating/primitives/rating-star.tsx
index f2fd529..d0859d1 100644
--- a/src/components/rating/primitives/rating-star.tsx
+++ b/src/components/rating/primitives/rating-star.tsx
@@ -51,7 +51,7 @@ export function RatingStar({ className, ...props }: RatingStarProps) {
 
   return (
     <svg
-      className={cn('inline-block text-[var(--rating-icon,var(--foreground))]', className)}
+      className={cn('inline-block text-[--rating-fill,var(--foreground)]', className)}
       data-slot="rating-star"
       fill="none"
       height={20}
diff --git a/src/components/rating/primitives/rating-total.tsx b/src/components/rating/primitives/rating-total.tsx
index f2ff14c..ae50ae8 100644
--- a/src/components/rating/primitives/rating-total.tsx
+++ b/src/components/rating/primitives/rating-total.tsx
@@ -15,7 +15,7 @@ export function RatingTotal({ className, children, ...props }: RatingTotalProps)
   return (
     <span
       className={cn(
-        'ml-2 whitespace-nowrap border-l border-[var(--rating-border,var(--contrast-100))] pl-2 font-normal text-[var(--rating-text,var(--contrast-400))]',
+        'ml-2 whitespace-nowrap border-l border-[--border-subtle] pl-2 font-normal text-[--rating-text,var(--text-secondary)]',
         className,
       )}
       data-slot="rating-total"
diff --git a/src/components/rating/primitives/rating-value.tsx b/src/components/rating/primitives/rating-value.tsx
index db7a7c8..f0a7853 100644
--- a/src/components/rating/primitives/rating-value.tsx
+++ b/src/components/rating/primitives/rating-value.tsx
@@ -15,7 +15,7 @@ export function RatingValue({ className, children, ...props }: RatingValueProps)
   return (
     <span
       className={cn(
-        'ml-2 flex items-center text-xs font-bold leading-normal text-[var(--rating-text,var(--contrast-400))]',
+        'ml-2 flex items-center text-xs font-bold leading-normal text-[--rating-text,var(--text-secondary)]',
         className,
       )}
       data-slot="rating-value"
diff --git a/src/components/rating/rating.tsx b/src/components/rating/rating.tsx
index 68c0102..4d6d434 100644
--- a/src/components/rating/rating.tsx
+++ b/src/components/rating/rating.tsx
@@ -14,9 +14,8 @@ export interface RatingProps {
  *
  * ```css
  * :root {
- *   --rating-icon: var(--foreground);
- *   --rating-border: var(--contrast-100);
- *   --rating-text: var(--contrast-400);
+ *   --rating-fill: var(--foreground);
+ *   --rating-text: var(--text-secondary);
  * }
  * ```
  */
diff --git a/src/components/rating/storybook/rating.stories.tsx b/src/components/rating/storybook/rating.stories.tsx
index 1fd8aae..e79b697 100644
--- a/src/components/rating/storybook/rating.stories.tsx
+++ b/src/components/rating/storybook/rating.stories.tsx
@@ -11,48 +11,15 @@ const meta: Meta<typeof Rating> = {
     docs: {
       description: {
         component: `
-A star rating component for displaying product reviews and ratings. Shows filled, half-filled, and empty stars based on the rating value.
+A star rating component for displaying product reviews. Shows filled, half-filled, and empty stars based on the rating value.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --rating-icon: var(--foreground);
-  --rating-border: var(--contrast-100);
-  --rating-text: var(--contrast-400);
+  --rating-fill: var(--foreground);
+  --rating-text: var(--text-secondary);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Rating\` component provides a simple API for displaying ratings:
-
-\`\`\`tsx
-import { Rating } from '@/components/rating';
-
-<Rating
-  rating={4.5}
-  totalReviews={128}
-  showRating
-  showTotalReviews
-/>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Rating from '@/components/rating';
-
-<Rating.Root rating={4.5} totalReviews={128} showRating showTotalReviews>
-  <Rating.Stars />
-  <Rating.Value>
-    <Rating.Total />
-  </Rating.Value>
-</Rating.Root>
 \`\`\`
         `,
       },
@@ -62,19 +29,19 @@ import * as Rating from '@/components/rating';
   argTypes: {
     rating: {
       control: { type: 'number', min: 0, max: 5, step: 0.5 },
-      description: 'The rating value (0-5)',
+      description: 'Rating value from 0 to 5 (supports half stars)',
     },
     totalReviews: {
       control: 'number',
-      description: 'Total number of reviews',
+      description: 'Total number of reviews to display',
     },
     showRating: {
       control: 'boolean',
-      description: 'Whether to show the numeric rating value',
+      description: 'Show the numeric rating value',
     },
     showTotalReviews: {
       control: 'boolean',
-      description: 'Whether to show the total reviews count',
+      description: 'Show the total reviews count',
     },
   },
 };
@@ -82,8 +49,14 @@ import * as Rating from '@/components/rating';
 export default meta;
 type Story = StoryObj<RatingProps>;
 
-// Default rating
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Rating with stars, numeric value, and review count.',
+      },
+    },
+  },
   args: {
     rating: 4.5,
     totalReviews: 128,
@@ -92,23 +65,14 @@ export const Default: Story = {
   },
 };
 
-// Various ratings
-export const AllRatings: Story = {
-  render: () => (
-    <div className="space-y-4">
-      <Rating rating={5} showRating showTotalReviews={false} />
-      <Rating rating={4.5} showRating showTotalReviews={false} />
-      <Rating rating={4} showRating showTotalReviews={false} />
-      <Rating rating={3.5} showRating showTotalReviews={false} />
-      <Rating rating={3} showRating showTotalReviews={false} />
-      <Rating rating={2} showRating showTotalReviews={false} />
-      <Rating rating={1} showRating showTotalReviews={false} />
-    </div>
-  ),
-};
-
-// Stars only
 export const StarsOnly: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Stars without numeric value or review count.',
+      },
+    },
+  },
   args: {
     rating: 4,
     showRating: false,
@@ -116,8 +80,24 @@ export const StarsOnly: Story = {
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitive components for custom layouts.',
+      },
+      source: {
+        code: `
+<RatingPrimitive.Root rating={4.5} totalReviews={256} showRating showTotalReviews>
+  <RatingPrimitive.Stars />
+  <RatingPrimitive.Value>
+    <RatingPrimitive.Total />
+  </RatingPrimitive.Value>
+</RatingPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <RatingPrimitive.Root rating={4.5} showRating showTotalReviews totalReviews={256}>
       <RatingPrimitive.Stars />
diff --git a/src/components/reveal/primitives/reveal-viewport.tsx b/src/components/reveal/primitives/reveal-viewport.tsx
index b8e0b72..569470a 100644
--- a/src/components/reveal/primitives/reveal-viewport.tsx
+++ b/src/components/reveal/primitives/reveal-viewport.tsx
@@ -13,7 +13,7 @@ export function RevealViewport({ children, className, ...props }: RevealViewport
   return (
     <div
       className={cn(
-        'max-h-[var(--reveal-max-height)] overflow-hidden',
+        'max-h-[--reveal-max-height] overflow-hidden',
         // Open state
         'group-data-[open=true]/reveal:max-h-none',
         // Overflow + Closed state (show gradient mask)
diff --git a/src/components/reveal/storybook/reveal.stories.tsx b/src/components/reveal/storybook/reveal.stories.tsx
index ae66818..7080814 100644
--- a/src/components/reveal/storybook/reveal.stories.tsx
+++ b/src/components/reveal/storybook/reveal.stories.tsx
@@ -36,56 +36,19 @@ const meta: Meta<typeof Reveal> = {
     docs: {
       description: {
         component: `
-A component for revealing long content with a show more/less toggle. Useful for product descriptions, FAQ sections, and other collapsible content areas.
+A component for revealing long content with a show more/less toggle. Useful for product descriptions, FAQ sections, and collapsible content.
 
 ## CSS Variables
 
+The underline variant inherits styling from the AnimatedUnderline component:
+
 \`\`\`css
 :root {
-  --reveal-focus: var(--brand);
+  --animated-underline: var(--brand);
 }
 \`\`\`
 
-## Usage
-
-### High-Level Component
-
-The \`Reveal\` component provides a simple API for collapsible content:
-
-\`\`\`tsx
-import { Reveal } from '@/components/reveal';
-
-<Reveal
-  variant="underline"
-  showLabel="Show more"
-  hideLabel="Show less"
-  maxHeight={160}
->
-  <p>Your long content here...</p>
-</Reveal>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Reveal from '@/components/reveal';
-
-<Reveal.Root
-  variant="underline"
-  showLabel="Show more"
-  hideLabel="Show less"
-  maxHeight={160}
->
-  <Reveal.Viewport>
-    <p>Your content here...</p>
-  </Reveal.Viewport>
-  <Reveal.Controls>
-    <Reveal.Trigger />
-  </Reveal.Controls>
-</Reveal.Root>
-\`\`\`
+The button variant uses the Button component's theming.
         `,
       },
     },
@@ -95,15 +58,15 @@ import * as Reveal from '@/components/reveal';
     variant: {
       control: 'select',
       options: ['underline', 'button'],
-      description: 'The visual variant of the toggle button',
+      description: 'Toggle style: "underline" for text link, "button" for outlined button',
     },
     showLabel: {
       control: 'text',
-      description: 'Label for the show more button',
+      description: 'Label when content is collapsed',
     },
     hideLabel: {
       control: 'text',
-      description: 'Label for the show less button',
+      description: 'Label when content is expanded',
     },
     defaultOpen: {
       control: 'boolean',
@@ -126,15 +89,38 @@ import * as Reveal from '@/components/reveal';
 export default meta;
 type Story = StoryObj<RevealProps>;
 
-// Default with underline variant
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Collapsible content with underline toggle.',
+      },
+    },
+  },
   args: {
     children: longContent,
   },
 };
 
-// All variants
 export const AllVariants: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Both toggle variants: underline (text link) and button (outlined).',
+      },
+      source: {
+        code: `
+<Reveal variant="underline">
+  {content}
+</Reveal>
+
+<Reveal variant="button">
+  {content}
+</Reveal>
+        `,
+      },
+    },
+  },
   render: () => (
     <div className="space-y-8">
       <div>
@@ -149,8 +135,31 @@ export const AllVariants: Story = {
   ),
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitive components for custom layouts.',
+      },
+      source: {
+        code: `
+<RevealPrimitive.Root
+  variant="underline"
+  showLabel="Show more"
+  hideLabel="Show less"
+  maxHeight={160}
+>
+  <RevealPrimitive.Viewport>
+    {content}
+  </RevealPrimitive.Viewport>
+  <RevealPrimitive.Controls>
+    <RevealPrimitive.Trigger />
+  </RevealPrimitive.Controls>
+</RevealPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <RevealPrimitive.Root
       hideLabel="Show less"
diff --git a/src/components/scroll-area/primitives/scroll-area-thumb.tsx b/src/components/scroll-area/primitives/scroll-area-thumb.tsx
index 62e3a50..9b1d0e1 100644
--- a/src/components/scroll-area/primitives/scroll-area-thumb.tsx
+++ b/src/components/scroll-area/primitives/scroll-area-thumb.tsx
@@ -11,7 +11,7 @@ export function ScrollAreaThumb({ className, ...props }: ScrollAreaThumbProps) {
   return (
     <ScrollAreaPrimitive.ScrollAreaThumb
       className={cn(
-        'relative flex-1 rounded-full bg-[var(--scroll-area-thumb,var(--contrast-200))]',
+        'relative flex-1 rounded-full bg-[--scroll-area-fill,var(--contrast-200)]',
         className,
       )}
       data-slot="scroll-area-thumb"
diff --git a/src/components/scroll-area/primitives/scroll-area-viewport.tsx b/src/components/scroll-area/primitives/scroll-area-viewport.tsx
index 1882acb..8aa375d 100644
--- a/src/components/scroll-area/primitives/scroll-area-viewport.tsx
+++ b/src/components/scroll-area/primitives/scroll-area-viewport.tsx
@@ -11,9 +11,7 @@ export function ScrollAreaViewport({ className, children, ...props }: ScrollArea
   return (
     <ScrollAreaPrimitive.Viewport
       className={cn(
-        'size-full rounded-[inherit] transition-[color,box-shadow]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--scroll-area-focus,var(--brand))]',
+        'focus-primary transition-[color,box-shadow size-full rounded-[inherit]',
         className,
       )}
       data-slot="scroll-area-viewport"
diff --git a/src/components/scroll-area/scroll-area.tsx b/src/components/scroll-area/scroll-area.tsx
index e3edecb..946ec90 100644
--- a/src/components/scroll-area/scroll-area.tsx
+++ b/src/components/scroll-area/scroll-area.tsx
@@ -14,8 +14,7 @@ export interface ScrollAreaProps extends ComponentProps<typeof ScrollAreaPrimiti
  *
  * ```css
  * :root {
- *   --scroll-area-focus: var(--brand);
- *   --scroll-area-thumb: var(--contrast-200);
+ *   --scroll-area-fill: var(--contrast-200);
  * }
  * ```
  */
diff --git a/src/components/scroll-area/storybook/scroll-area.stories.tsx b/src/components/scroll-area/storybook/scroll-area.stories.tsx
index 1a000b0..2e35af6 100644
--- a/src/components/scroll-area/storybook/scroll-area.stories.tsx
+++ b/src/components/scroll-area/storybook/scroll-area.stories.tsx
@@ -17,8 +17,7 @@ A custom scroll area component with styled scrollbars built on Radix UI primitiv
 
 \`\`\`css
 :root {
-  --scroll-area-focus: var(--brand);
-  --scroll-area-thumb: var(--contrast-200);
+  --scroll-area-fill: var(--contrast-200);
 }
 \`\`\`
 
diff --git a/src/components/select/primitives/select-content.tsx b/src/components/select/primitives/select-content.tsx
index c9d5358..a9e70a1 100644
--- a/src/components/select/primitives/select-content.tsx
+++ b/src/components/select/primitives/select-content.tsx
@@ -11,7 +11,7 @@ export function SelectContent({ children, className, ...props }: SelectContentPr
   return (
     <SelectPrimitive.Content
       className={cn(
-        'z-50 max-h-80 w-full overflow-y-auto rounded-xl bg-[var(--select-light-content-background,var(--background))] p-2 shadow-xl ring-1 ring-[var(--select-light-content-border,color-mix(in_oklab,var(--foreground)_10%,transparent))]',
+        'z-50 max-h-80 w-full overflow-y-auto rounded-xl bg-[--select-fill,var(--form-fill)] p-2 shadow-xl ring-1 ring-[color-mix(in_oklab,var(--foreground)_10%,transparent)]',
         // Open state
         'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
         // Closed state
diff --git a/src/components/select/primitives/select-item.tsx b/src/components/select/primitives/select-item.tsx
index 135748e..6f1aea9 100644
--- a/src/components/select/primitives/select-item.tsx
+++ b/src/components/select/primitives/select-item.tsx
@@ -11,13 +11,13 @@ export function SelectItem({ children, className, ...props }: SelectItemProps) {
   return (
     <SelectPrimitive.Item
       className={cn(
-        'w-full cursor-default select-none rounded-lg px-3 py-2 text-sm font-normal text-[var(--select-light-item-text,var(--contrast-400))] outline-none transition-colors',
+        'w-full cursor-default select-none rounded-lg px-3 py-2 text-sm text-[--select-text-secondary,var(--form-text-secondary)] outline-none transition-colors',
         // Hover state
-        'hover:bg-[var(--select-light-item-background-hover,var(--contrast-100))] hover:text-[var(--select-light-item-text-hover,var(--foreground))]',
+        'hover:bg-[--select-fill-hover,var(--form-fill-hover)] hover:text-[--select-text-hover,var(--form-text-hover)]',
         // Focus-visible state
-        'focus-visible:bg-[var(--select-light-item-background-focus,var(--contrast-100))] focus-visible:text-[var(--select-light-item-text-focus,var(--foreground))]',
+        'focus-visible:bg-[--select-fill-focus,var(--form-fill-hover)] focus-visible:text-[--select-text-focus,var(--form-text-hover)]',
         // Checked state
-        'data-[state=checked]:text-[var(--select-light-item-checked-text-focus,var(--foreground))]',
+        'data-[state=checked]:text-[--select-text-focus,var(--form-text-hover)]',
         // Container queries
         '@4xl:text-base',
         className,
diff --git a/src/components/select/primitives/select-scroll-down-icon.tsx b/src/components/select/primitives/select-scroll-down-icon.tsx
index 880db04..64b5211 100644
--- a/src/components/select/primitives/select-scroll-down-icon.tsx
+++ b/src/components/select/primitives/select-scroll-down-icon.tsx
@@ -20,7 +20,7 @@ export function SelectScrollDownIcon({
   if (asChild) {
     return (
       <Slot
-        className={cn('w-5 text-[var(--select-light-icon,var(--foreground))]', className)}
+        className={cn('w-5 text-[--select-fill-icon,var(--form-fill-icon)]', className)}
         data-slot="select-scroll-down-icon"
       >
         {children}
@@ -31,7 +31,7 @@ export function SelectScrollDownIcon({
   return (
     <ChevronDown
       absoluteStrokeWidth
-      className={cn('w-5 text-[var(--select-light-icon,var(--foreground))]', className)}
+      className={cn('w-5 text-[--select-fill-icon,var(--form-fill-icon)]', className)}
       data-slot="select-scroll-down-icon"
       strokeWidth={1.5}
     />
diff --git a/src/components/select/primitives/select-scroll-up-icon.tsx b/src/components/select/primitives/select-scroll-up-icon.tsx
index a32cdf0..7754825 100644
--- a/src/components/select/primitives/select-scroll-up-icon.tsx
+++ b/src/components/select/primitives/select-scroll-up-icon.tsx
@@ -20,7 +20,7 @@ export function SelectScrollUpIcon({
   if (asChild) {
     return (
       <Slot
-        className={cn('w-5 text-[var(--select-light-icon,var(--foreground))]', className)}
+        className={cn('w-5 text-[--select-fill-icon,var(--form-fill-icon)]', className)}
         data-slot="select-scroll-up-icon"
       >
         {children}
@@ -31,7 +31,7 @@ export function SelectScrollUpIcon({
   return (
     <ChevronUp
       absoluteStrokeWidth
-      className={cn('w-5 text-[var(--select-light-icon,var(--foreground))]', className)}
+      className={cn('w-5 text-[var(--select-fill-icon,var(--form-fill-icon))]', className)}
       data-slot="select-scroll-up-icon"
       strokeWidth={1.5}
     />
diff --git a/src/components/select/primitives/select-trigger-icon.tsx b/src/components/select/primitives/select-trigger-icon.tsx
index 4dcbe93..d6edf4e 100644
--- a/src/components/select/primitives/select-trigger-icon.tsx
+++ b/src/components/select/primitives/select-trigger-icon.tsx
@@ -21,7 +21,7 @@ export function SelectTriggerIcon({
     return (
       <Slot
         className={cn(
-          'w-5 text-[var(--select-light-icon,var(--foreground))] transition-transform',
+          'w-5 text-[--select-fill-icon,var(--form-fill-icon)] transition-transform',
           className,
         )}
         data-slot="select-trigger-icon"
@@ -35,7 +35,7 @@ export function SelectTriggerIcon({
     <ChevronDown
       absoluteStrokeWidth
       className={cn(
-        'w-5 text-[var(--select-light-icon,var(--foreground))] transition-transform',
+        'w-5 text-[--select-fill-icon,var(--form-fill-icon)] transition-transform',
         className,
       )}
       data-slot="select-trigger-icon"
diff --git a/src/components/select/primitives/select-trigger.tsx b/src/components/select/primitives/select-trigger.tsx
index 4988a21..e043e8e 100644
--- a/src/components/select/primitives/select-trigger.tsx
+++ b/src/components/select/primitives/select-trigger.tsx
@@ -11,13 +11,11 @@ export function SelectTrigger({ className, children, ...props }: SelectTriggerPr
   return (
     <SelectPrimitive.Trigger
       className={cn(
-        'flex h-fit w-full select-none items-center justify-between gap-3 border border-[var(--select-light-trigger-border,var(--contrast-100))] bg-[var(--select-light-trigger-background,var(--background))] px-5 py-3 text-sm font-normal text-[var(--select-light-trigger-text,var(--foreground))] transition-colors',
+        'focus-primary flex h-fit w-full select-none items-center justify-between gap-3 border border-[--border-subtle] bg-[--select-fill,var(--form-fill)] px-5 py-3 text-sm font-normal text-[--select-text-primary,var(--form-text-primary)] transition-colors',
         // Hover state
-        'hover:border-[var(--select-light-trigger-border-hover,var(--contrast-300))] hover:bg-[var(--select-light-trigger-background-hover,var(--contrast-100))]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--select-light-trigger-focus,var(--brand))]',
+        'hover:border-[--border-hover] hover:bg-[--select-fill-hover,var(--form-fill-hover)]',
         // Aria-invalid state
-        'aria-invalid:border-[var(--select-light-trigger-border-error,var(--error))]',
+        'aria-invalid:border-[--border-error]',
         // Variant styles
         '[[data-variant=rectangle]_&]:rounded-lg [[data-variant=round]_&]:rounded-full',
         className,
diff --git a/src/components/select/select.tsx b/src/components/select/select.tsx
index 7c4c9bf..3fe402b 100644
--- a/src/components/select/select.tsx
+++ b/src/components/select/select.tsx
@@ -34,22 +34,14 @@ export type SelectProps = ComponentProps<typeof SelectPrimitive.Root> & {
  *
  * ```css
  * :root {
- *   --select-light-trigger-background: var(--background);
- *   --select-light-trigger-background-hover: var(--contrast-100);
- *   --select-light-trigger-border: var(--contrast-100);
- *   --select-light-trigger-border-hover: var(--contrast-300);
- *   --select-light-trigger-border-error: var(--error);
- *   --select-light-trigger-text: var(--foreground);
- *   --select-light-trigger-focus: var(--brand);
- *   --select-light-icon: var(--foreground);
- *   --select-light-content-background: var(--background);
- *   --select-light-content-border: color-mix(in oklab, var(--foreground) 10%, transparent);
- *   --select-light-item-background-hover: var(--contrast-100);
- *   --select-light-item-background-focus: var(--contrast-100);
- *   --select-light-item-text: var(--contrast-400);
- *   --select-light-item-text-hover: var(--foreground);
- *   --select-light-item-text-focus: var(--foreground);
- *   --select-light-item-checked-text-focus: var(--foreground);
+ *   --select-fill: var(--form-fill);
+ *   --select-fill-hover: var(--form-fill-hover);
+ *   --select-fill-focus: var(--form-fill-hover);
+ *   --select-fill-icon: var(--form-fill-icon);
+ *   --select-text-primary: var(--form-text-primary);
+ *   --select-text-secondary: var(--form-text-secondary);
+ *   --select-text-hover: var(--form-text-hover);
+ *   --select-text-focus: var(--form-text-hover);
  * }
  * ```
  */
diff --git a/src/components/select/storybook/select.stories.tsx b/src/components/select/storybook/select.stories.tsx
index 584e3a7..eedd9ae 100644
--- a/src/components/select/storybook/select.stories.tsx
+++ b/src/components/select/storybook/select.stories.tsx
@@ -1,5 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import type { ComponentType } from 'react';
 import { useState } from 'react';
 
 import { Select, type SelectProps } from '@/components/select';
@@ -26,83 +25,25 @@ A customizable select dropdown component built on Radix UI primitives. Supports
 
 \`\`\`css
 :root {
-  --select-light-trigger-background: var(--background);
-  --select-light-trigger-background-hover: var(--contrast-100);
-  --select-light-trigger-border: var(--contrast-100);
-  --select-light-trigger-border-hover: var(--contrast-300);
-  --select-light-trigger-border-error: var(--error);
-  --select-light-trigger-text: var(--foreground);
-  --select-light-trigger-focus: var(--brand);
-  --select-light-icon: var(--foreground);
-  --select-light-content-background: var(--background);
-  --select-light-content-border: color-mix(in oklab, var(--foreground) 10%, transparent);
-  --select-light-item-background-hover: var(--contrast-100);
-  --select-light-item-background-focus: var(--contrast-100);
-  --select-light-item-text: var(--contrast-400);
-  --select-light-item-text-hover: var(--foreground);
-  --select-light-item-text-focus: var(--foreground);
-  --select-light-item-checked-text-focus: var(--foreground);
+  --select-fill: var(--form-fill);
+  --select-fill-hover: var(--form-fill-hover);
+  --select-fill-focus: var(--form-fill-hover);
+  --select-fill-icon: var(--form-fill-icon);
+  --select-text-primary: var(--form-text-primary);
+  --select-text-secondary: var(--form-text-secondary);
+  --select-text-hover: var(--form-text-hover);
+  --select-text-focus: var(--form-text-hover);
 }
 \`\`\`
 
-## Usage
+## Container Queries
 
-### High-Level Component
+The dropdown content adapts based on container width.
 
-The \`Select\` component provides a simple API with an \`options\` array:
-
-\`\`\`tsx
-import { Select } from '@/components/select';
-
-const options = [
-  { label: 'Small', value: 'sm' },
-  { label: 'Medium', value: 'md' },
-  { label: 'Large', value: 'lg' },
-];
-
-<Select
-  id="size-select"
-  label="Size"
-  options={options}
-  placeholder="Select a size"
-  variant="rectangle"
-/>
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Select from '@/components/select';
-
-<Select.Root>
-  <Select.Trigger aria-label="Size">
-    <Select.Value placeholder="Select a size" />
-    <Select.Icon>
-      <Select.TriggerIcon />
-    </Select.Icon>
-  </Select.Trigger>
-  <Select.Portal>
-    <Select.Content>
-      <Select.ScrollUpButton>
-        <Select.ScrollUpIcon />
-      </Select.ScrollUpButton>
-      <Select.Viewport>
-        <Select.Item value="sm">
-          <Select.ItemText>Small</Select.ItemText>
-        </Select.Item>
-        <Select.Item value="md">
-          <Select.ItemText>Medium</Select.ItemText>
-        </Select.Item>
-      </Select.Viewport>
-      <Select.ScrollDownButton>
-        <Select.ScrollDownIcon />
-      </Select.ScrollDownButton>
-    </Select.Content>
-  </Select.Portal>
-</Select.Root>
-\`\`\`
+| Element  | Below @4xl     | @4xl and above |
+|----------|----------------|----------------|
+| Content  | rounded-xl p-2 | rounded-3xl p-4 |
+| Item     | text-sm        | text-base       |
         `,
       },
     },
@@ -132,22 +73,15 @@ import * as Select from '@/components/select';
     },
     options: {
       control: false,
-      description: 'Array of options with label and value',
+      description: 'Array of options with `label` and `value`',
     },
   },
-  decorators: [
-    (Story: ComponentType) => (
-      <div className="w-64">
-        <Story />
-      </div>
-    ),
-  ],
+  decorators: [(Story) => <div className="w-64">{Story()}</div>],
 };
 
 export default meta;
 type Story = StoryObj<SelectProps>;
 
-// Default select
 export const Default: Story = {
   args: {
     id: 'select-default',
@@ -157,8 +91,33 @@ export const Default: Story = {
   },
 };
 
-// All variants
-export const AllVariants: Story = {
+export const Variants: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Two trigger variants are available: `rectangle` (default) and `round`.',
+      },
+      source: {
+        code: `
+<Select
+  id="variant-rectangle"
+  label="Size"
+  options={sizeOptions}
+  placeholder="Rectangle variant"
+  variant="rectangle"
+/>
+
+<Select
+  id="variant-round"
+  label="Size"
+  options={sizeOptions}
+  placeholder="Round variant"
+  variant="round"
+/>
+        `,
+      },
+    },
+  },
   render: () => (
     <div className="flex flex-col gap-6">
       <Select
@@ -179,8 +138,28 @@ export const AllVariants: Story = {
   ),
 };
 
-// Controlled example
 export const Controlled: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `value` and `onValueChange` for controlled selection.',
+      },
+      source: {
+        code: `
+const [value, setValue] = useState<string>('');
+
+<Select
+  id="select-controlled"
+  label="Size"
+  options={sizeOptions}
+  placeholder="Select a size"
+  value={value}
+  onValueChange={setValue}
+/>
+        `,
+      },
+    },
+  },
   render: () => {
     const [value, setValue] = useState<string>('');
 
@@ -197,8 +176,65 @@ export const Controlled: Story = {
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the primitive components for full control over the structure.
+
+| Primitive                         | Description                              |
+|-----------------------------------|------------------------------------------|
+| \`SelectPrimitive.Root\`          | Provider with variant and pending state. |
+| \`SelectPrimitive.Trigger\`       | Button that opens the dropdown.          |
+| \`SelectPrimitive.Value\`         | Displays current selection or placeholder. |
+| \`SelectPrimitive.Icon\`          | Container for the trigger icon.          |
+| \`SelectPrimitive.TriggerIcon\`   | Chevron icon with \`asChild\` support.   |
+| \`SelectPrimitive.Portal\`        | Portals content to document body.        |
+| \`SelectPrimitive.Content\`       | Dropdown container with animations.      |
+| \`SelectPrimitive.ScrollUpButton\`| Scroll indicator for overflow.           |
+| \`SelectPrimitive.ScrollUpIcon\`  | Up chevron with \`asChild\` support.     |
+| \`SelectPrimitive.Viewport\`      | Scrollable area for items.               |
+| \`SelectPrimitive.Item\`          | Individual option item.                  |
+| \`SelectPrimitive.ItemText\`      | Text content of an option.               |
+| \`SelectPrimitive.ScrollDownButton\`| Scroll indicator for overflow.         |
+| \`SelectPrimitive.ScrollDownIcon\`| Down chevron with \`asChild\` support.   |
+        `,
+      },
+      source: {
+        code: `
+import * as SelectPrimitive from '@/components/select/primitives';
+
+<SelectPrimitive.Root>
+  <SelectPrimitive.Trigger aria-label="Size" id="select-composable">
+    <SelectPrimitive.Value placeholder="Select a size" />
+    <SelectPrimitive.Icon>
+      <SelectPrimitive.TriggerIcon />
+    </SelectPrimitive.Icon>
+  </SelectPrimitive.Trigger>
+  <SelectPrimitive.Portal>
+    <SelectPrimitive.Content>
+      <SelectPrimitive.ScrollUpButton>
+        <SelectPrimitive.ScrollUpIcon />
+      </SelectPrimitive.ScrollUpButton>
+      <SelectPrimitive.Viewport>
+        <SelectPrimitive.Item value="sm">
+          <SelectPrimitive.ItemText>Small</SelectPrimitive.ItemText>
+        </SelectPrimitive.Item>
+        <SelectPrimitive.Item value="md">
+          <SelectPrimitive.ItemText>Medium</SelectPrimitive.ItemText>
+        </SelectPrimitive.Item>
+      </SelectPrimitive.Viewport>
+      <SelectPrimitive.ScrollDownButton>
+        <SelectPrimitive.ScrollDownIcon />
+      </SelectPrimitive.ScrollDownButton>
+    </SelectPrimitive.Content>
+  </SelectPrimitive.Portal>
+</SelectPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <SelectPrimitive.Root>
       <SelectPrimitive.Trigger aria-label="Size" id="select-composable">
diff --git a/src/components/side-panel/primitives/side-panel-body.tsx b/src/components/side-panel/primitives/side-panel-body.tsx
index 1762844..9772481 100644
--- a/src/components/side-panel/primitives/side-panel-body.tsx
+++ b/src/components/side-panel/primitives/side-panel-body.tsx
@@ -7,7 +7,10 @@ export type SidePanelBodyProps = ComponentProps<'div'>;
 export function SidePanelBody({ children, className, ...props }: SidePanelBodyProps) {
   return (
     <div
-      className={cn('px-6 pb-6 @md:px-8 @md:pb-8', className)}
+      className={cn(
+        'px-6 pb-6 text-[--side-panel-text-secondary,var(--text-secondary)] @md:px-8 @md:pb-8',
+        className,
+      )}
       data-slot="side-panel-body"
       {...props}
     >
diff --git a/src/components/side-panel/primitives/side-panel-content.tsx b/src/components/side-panel/primitives/side-panel-content.tsx
index 68a32ad..8f6b951 100644
--- a/src/components/side-panel/primitives/side-panel-content.tsx
+++ b/src/components/side-panel/primitives/side-panel-content.tsx
@@ -11,7 +11,7 @@ export function SidePanelContent({ children, className, ...props }: SidePanelCon
   return (
     <Dialog.Content
       className={cn(
-        'fixed inset-y-0 right-0 flex w-96 max-w-full flex-col bg-[var(--side-panel-background,var(--background))] font-[var(--side-panel-content-font-family,var(--font-family-body))] transition duration-500 [animation-timing-function:cubic-bezier(0.25,1,0,1)]',
+        'fixed inset-y-0 right-0 flex w-96 max-w-full flex-col bg-[--side-panel-fill,var(--background)] transition duration-500 [animation-timing-function:cubic-bezier(0.25,1,0,1)] [font-family:var(--side-panel-font-content,var(--font-body))]',
         // Open state
         'data-[state=open]:animate-in data-[state=open]:slide-in-from-right',
         // Closed state
diff --git a/src/components/side-panel/primitives/side-panel-overlay.tsx b/src/components/side-panel/primitives/side-panel-overlay.tsx
index f20bf8b..0ebfd2f 100644
--- a/src/components/side-panel/primitives/side-panel-overlay.tsx
+++ b/src/components/side-panel/primitives/side-panel-overlay.tsx
@@ -11,7 +11,7 @@ export function SidePanelOverlay({ children, className, ...props }: SidePanelOve
   return (
     <Dialog.Overlay
       className={cn(
-        'fixed inset-0 z-30 overflow-hidden bg-[var(--side-panel-overlay-background,color-mix(in_oklab,var(--foreground)_50%,transparent))] @container',
+        'fixed inset-0 z-30 overflow-hidden bg-[var(--side-panel-fill-overlay,color-mix(in_oklab,var(--foreground)_50%,transparent))] @container',
         className,
       )}
       data-slot="side-panel-overlay"
diff --git a/src/components/side-panel/primitives/side-panel-title.tsx b/src/components/side-panel/primitives/side-panel-title.tsx
index f62871c..0bc8645 100644
--- a/src/components/side-panel/primitives/side-panel-title.tsx
+++ b/src/components/side-panel/primitives/side-panel-title.tsx
@@ -11,7 +11,7 @@ export function SidePanelTitle({ children, className, ...props }: SidePanelTitle
   return (
     <Dialog.Title
       className={cn(
-        'text-2xl font-medium text-[var(--side-panel-title-text,var(--foreground))] [font-family:var(--side-panel-title-font-family,var(--font-family-heading))] @lg:text-3xl',
+        'text-2xl font-medium text-[--side-panel-text-primary,var(--text-primary)] [font-family:var(--side-panel-font-title,var(--font-heading))] @lg:text-3xl',
         className,
       )}
       data-slot="side-panel-title"
diff --git a/src/components/side-panel/side-panel.tsx b/src/components/side-panel/side-panel.tsx
index 356dae6..5bcb4b3 100644
--- a/src/components/side-panel/side-panel.tsx
+++ b/src/components/side-panel/side-panel.tsx
@@ -18,16 +18,12 @@ export interface SidePanelProps {
  *
  * ```css
  * :root {
- *   --side-panel-overlay-background: color-mix(in oklab, var(--foreground) 50%, transparent);
- *   --side-panel-background: var(--background);
- *   --side-panel-title-text: var(--foreground);
- *   --side-panel-title-font-family: var(--font-family-heading);
- *   --side-panel-content-font-family: var(--font-family-body);
- *   --side-panel-overlay-background: color-mix(in oklab, var(--foreground) 50%, transparent);
- *   --side-panel-background: var(--background);
- *   --side-panel-title-text: var(--foreground);
- *   --side-panel-title-font-family: var(--font-family-heading);
- *   --side-panel-content-font-family: var(--font-family-body);
+ *   --side-panel-fill-overlay: color-mix(in oklab, var(--foreground) 50%, transparent);
+ *   --side-panel-fill: var(--background);
+ *   --side-panel-text-primary: var(--text-primary);
+ *   --side-panel-text-secondary: var(--text-secondary);
+ *   --side-panel-font-title: var(--font-heading);
+ *   --side-panel-font-content: var(--font-body);
  * }
  * ```
  */
diff --git a/src/components/side-panel/storybook/side-panel.stories.tsx b/src/components/side-panel/storybook/side-panel.stories.tsx
index 142ce70..49d1ea0 100644
--- a/src/components/side-panel/storybook/side-panel.stories.tsx
+++ b/src/components/side-panel/storybook/side-panel.stories.tsx
@@ -20,11 +20,12 @@ A slide-out panel component for displaying supplementary content like filters, s
 
 \`\`\`css
 :root {
-  --side-panel-overlay-background: color-mix(in oklab, var(--foreground) 50%, transparent);
-  --side-panel-background: var(--background);
-  --side-panel-title-text: var(--foreground);
-  --side-panel-title-font-family: var(--font-family-heading);
-  --side-panel-content-font-family: var(--font-family-body);
+  --side-panel-fill-overlay: color-mix(in oklab, var(--foreground) 50%, transparent);
+  --side-panel-fill: var(--background);
+  --side-panel-text-primary: var(--text-primary);
+  --side-panel-text-secondary: var(--text-secondary);
+  --side-panel-font-title: var(--font-heading);
+  --side-panel-font-content: var(--font-body);
 }
 \`\`\`
 
diff --git a/src/components/skeleton/primitives/skeleton-box.tsx b/src/components/skeleton/primitives/skeleton-box.tsx
index ed9b788..51232a6 100644
--- a/src/components/skeleton/primitives/skeleton-box.tsx
+++ b/src/components/skeleton/primitives/skeleton-box.tsx
@@ -6,13 +6,6 @@ export type SkeletonBoxProps = ComponentProps<'div'>;
 
 export function SkeletonBox({ className, ...props }: SkeletonBoxProps) {
   return (
-    <div
-      className={cn(
-        'bg-[var(--skeleton,color-mix(in_oklab,var(--contrast-300)_15%,transparent))]',
-        className,
-      )}
-      data-slot="skeleton-box"
-      {...props}
-    />
+    <div className={cn('bg-[--fill-pending]', className)} data-slot="skeleton-box" {...props} />
   );
 }
diff --git a/src/components/skeleton/primitives/skeleton-icon.tsx b/src/components/skeleton/primitives/skeleton-icon.tsx
index a4200a2..e03f260 100644
--- a/src/components/skeleton/primitives/skeleton-icon.tsx
+++ b/src/components/skeleton/primitives/skeleton-icon.tsx
@@ -8,11 +8,7 @@ export type SkeletonIconProps = ComponentProps<'div'> & {
 
 export function SkeletonIcon({ className, icon, ...props }: SkeletonIconProps) {
   return (
-    <div
-      className={cn('text-[var(--skeleton,var(--contrast-300))] opacity-25', className)}
-      data-slot="skeleton-icon"
-      {...props}
-    >
+    <div className={cn('text-[--fill-pending]', className)} data-slot="skeleton-icon" {...props}>
       {icon}
     </div>
   );
diff --git a/src/components/skeleton/primitives/skeleton-text.tsx b/src/components/skeleton/primitives/skeleton-text.tsx
index e133891..0e07571 100644
--- a/src/components/skeleton/primitives/skeleton-text.tsx
+++ b/src/components/skeleton/primitives/skeleton-text.tsx
@@ -14,9 +14,7 @@ export function SkeletonText({ characterCount = 10, className, ...props }: Skele
       {...props}
     >
       <div
-        className={cn(
-          `h-[1ex] max-w-full rounded-[inherit] bg-[var(--skeleton,color-mix(in_oklab,var(--contrast-300)_15%,transparent))]`,
-        )}
+        className={cn(`h-[1ex] max-w-full rounded-[inherit] bg-[--fill-pending]`)}
         style={{ width: characterCount === 'full' ? '100%' : `${characterCount}ch` }}
       />
     </div>
diff --git a/src/components/skeleton/storybook/skeleton.stories.tsx b/src/components/skeleton/storybook/skeleton.stories.tsx
index 306d7ba..f7078b4 100644
--- a/src/components/skeleton/storybook/skeleton.stories.tsx
+++ b/src/components/skeleton/storybook/skeleton.stories.tsx
@@ -10,38 +10,22 @@ const meta: Meta = {
     docs: {
       description: {
         component: `
-A set of composable skeleton loading primitives for building loading states. Use these to create placeholder UIs while content is loading.
+Composable skeleton loading primitives for building loading states.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --skeleton: color-mix(in oklab, var(--contrast-300) 15%, transparent);
+  --fill-pending: oklch(var(--contrast-100-lch));
 }
 \`\`\`
 
-## Composable Anatomy
+## Primitives
 
-The Skeleton component is composable-only. Combine the primitives to build custom loading states:
-
-\`\`\`tsx
-import * as Skeleton from '@/components/skeleton';
-import { Image } from 'lucide-react';
-
-<Skeleton.Root pending>
-  <Skeleton.Box className="h-40 w-full rounded" />
-  <Skeleton.Text characterCount={20} />
-  <Skeleton.Text characterCount="full" />
-  <Skeleton.Icon icon={<Image size={24} />} />
-</Skeleton.Root>
-\`\`\`
-
-### Primitives
-
-- \`Skeleton.Root\` - Container with \`pending\` prop for accessibility
-- \`Skeleton.Box\` - Generic rectangular placeholder
-- \`Skeleton.Text\` - Text placeholder with \`characterCount\` prop
-- \`Skeleton.Icon\` - Icon placeholder with \`icon\` prop
+- \`Skeleton.Root\` — Container with \`pending\` prop for accessibility
+- \`Skeleton.Box\` — Rectangular placeholder (requires size via className)
+- \`Skeleton.Text\` — Text placeholder with \`characterCount\` prop
+- \`Skeleton.Icon\` — Icon placeholder with \`icon\` prop
         `,
       },
     },
@@ -52,8 +36,25 @@ import { Image } from 'lucide-react';
 export default meta;
 type Story = StoryObj;
 
-// Default composable example
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Combine primitives to build custom loading states.',
+      },
+      source: {
+        code: `
+<Skeleton.Root pending>
+  <Skeleton.Box className="h-40 w-64 rounded" />
+  <div className="mt-3 space-y-2">
+    <Skeleton.Text characterCount={15} />
+    <Skeleton.Text characterCount={10} />
+  </div>
+</Skeleton.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <Skeleton.Root pending>
       <Skeleton.Box className="h-40 w-64 rounded" />
@@ -65,8 +66,23 @@ export const Default: Story = {
   ),
 };
 
-// Text variations
 export const TextVariations: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `characterCount` to set text width. Use `"full"` for 100% width.',
+      },
+      source: {
+        code: `
+<Skeleton.Root>
+  <Skeleton.Text characterCount={10} />
+  <Skeleton.Text characterCount={20} />
+  <Skeleton.Text characterCount="full" />
+</Skeleton.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <Skeleton.Root className="space-y-2">
       <Skeleton.Text characterCount={10} />
@@ -76,8 +92,23 @@ export const TextVariations: Story = {
   ),
 };
 
-// With icon
 export const WithIcon: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `Skeleton.Icon` with an `icon` prop for icon placeholders.',
+      },
+      source: {
+        code: `
+import { Image } from 'lucide-react';
+
+<Skeleton.Root>
+  <Skeleton.Icon icon={<Image size={48} />} />
+</Skeleton.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <Skeleton.Root>
       <Skeleton.Icon icon={<ImageIcon size={48} />} />
diff --git a/src/components/spinner/spinner.tsx b/src/components/spinner/spinner.tsx
index 33d54a8..3e7ffd6 100644
--- a/src/components/spinner/spinner.tsx
+++ b/src/components/spinner/spinner.tsx
@@ -4,7 +4,7 @@ import type { ComponentProps } from 'react';
 import { cn } from '@/lib';
 
 const spinnerVariants = cva(
-  'box-border inline-block animate-spin rounded-full border-[var(--spinner-base,var(--contrast-100))] [border-bottom-color:var(--spinner-ring,color-mix(in_oklab,var(--brand),black_75%))]',
+  'box-border inline-block animate-spin rounded-full border-[var(--spinner-fill-base,var(--contrast-100))] [border-bottom-color:var(--spinner-fill-ring,color-mix(in_oklab,var(--brand),black_75%))]',
   {
     variants: {
       size: {
@@ -28,8 +28,8 @@ export type SpinnerProps = ComponentProps<'span'> & VariantProps<typeof spinnerV
  *
  * ```css
  * :root {
- *   --spinner-base: var(--contrast-100);
- *   --spinner-ring: color-mix(in oklab, var(--brand), black 75%);
+ *   --spinner-fill-base: var(--contrast-100);
+ *   --spinner-fill-ring: color-mix(in oklab, var(--brand), black 75%);
  * }
  * ```
  */
diff --git a/src/components/spinner/storybook/spinner.stories.tsx b/src/components/spinner/storybook/spinner.stories.tsx
index 690e536..a1772e3 100644
--- a/src/components/spinner/storybook/spinner.stories.tsx
+++ b/src/components/spinner/storybook/spinner.stories.tsx
@@ -10,23 +10,15 @@ const meta: Meta<typeof Spinner> = {
     docs: {
       description: {
         component: `
-A loading spinner component for indicating pending operations. Supports multiple sizes and theming via CSS variables.
+A loading spinner for indicating pending operations.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --spinner-base: var(--contrast-100);
-  --spinner-ring: color-mix(in oklab, var(--brand), black 75%);
+  --spinner-fill-base: var(--contrast-100);
+  --spinner-fill-ring: color-mix(in oklab, var(--brand), black 75%);
 }
-\`\`\`
-
-## Usage
-
-\`\`\`tsx
-import { Spinner } from '@/components/spinner';
-
-<Spinner size="sm" />
 \`\`\`
         `,
       },
@@ -37,7 +29,7 @@ import { Spinner } from '@/components/spinner';
     size: {
       control: 'select',
       options: ['xs', 'sm', 'md', 'lg'],
-      description: 'The size of the spinner',
+      description: 'Spinner size: xs (20px), sm (24px), md (40px), lg (56px)',
     },
   },
   args: {
@@ -48,15 +40,35 @@ import { Spinner } from '@/components/spinner';
 export default meta;
 type Story = StoryObj<SpinnerProps>;
 
-// Default spinner
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Default spinner at small size.',
+      },
+    },
+  },
   args: {
     size: 'sm',
   },
 };
 
-// All sizes
 export const AllSizes: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'All available spinner sizes.',
+      },
+      source: {
+        code: `
+<Spinner size="xs" />
+<Spinner size="sm" />
+<Spinner size="md" />
+<Spinner size="lg" />
+        `,
+      },
+    },
+  },
   render: () => (
     <div className="flex items-center gap-6">
       <Spinner size="xs" />
diff --git a/src/components/swatch-radio-group/primitives/swatch-radio-group-color.tsx b/src/components/swatch-radio-group/primitives/swatch-radio-group-color.tsx
index f98f4ba..7f96833 100644
--- a/src/components/swatch-radio-group/primitives/swatch-radio-group-color.tsx
+++ b/src/components/swatch-radio-group/primitives/swatch-radio-group-color.tsx
@@ -15,7 +15,7 @@ export function SwatchRadioGroupColor({
   return (
     <span
       className={cn(
-        'block size-full rounded-full border [border-color:var(--swatch-radio-group-light-option-border,color-mix(in_oklab,var(--foreground)_10%,transparent))]',
+        'block size-full rounded-full border [border-color:color-mix(in_oklab,var(--foreground)_10%,transparent)]',
         // Group disabled state
         'group-disabled/swatch-radio-group-item:opacity-20',
         className,
diff --git a/src/components/swatch-radio-group/primitives/swatch-radio-group-indicator-icon.tsx b/src/components/swatch-radio-group/primitives/swatch-radio-group-indicator-icon.tsx
index a5c337c..c1caf03 100644
--- a/src/components/swatch-radio-group/primitives/swatch-radio-group-indicator-icon.tsx
+++ b/src/components/swatch-radio-group/primitives/swatch-radio-group-indicator-icon.tsx
@@ -17,9 +17,11 @@ export function SwatchRadioGroupIndicatorIcon({
   className,
   children,
 }: SwatchRadioGroupIndicatorIconProps) {
+  const iconStyles = cn('size-4', className);
+
   if (asChild) {
     return (
-      <Slot className={cn('size-4', className)} data-slot="swatch-radio-group-indicator-icon">
+      <Slot className={iconStyles} data-slot="swatch-radio-group-indicator-icon">
         {children}
       </Slot>
     );
@@ -28,7 +30,7 @@ export function SwatchRadioGroupIndicatorIcon({
   return (
     <X
       absoluteStrokeWidth
-      className={cn('size-4', className)}
+      className={iconStyles}
       data-slot="swatch-radio-group-indicator-icon"
       strokeWidth={1.5}
     />
diff --git a/src/components/swatch-radio-group/primitives/swatch-radio-group-indicator.tsx b/src/components/swatch-radio-group/primitives/swatch-radio-group-indicator.tsx
index 6f5e431..af23ebf 100644
--- a/src/components/swatch-radio-group/primitives/swatch-radio-group-indicator.tsx
+++ b/src/components/swatch-radio-group/primitives/swatch-radio-group-indicator.tsx
@@ -12,10 +12,7 @@ export function SwatchRadioGroupIndicator({
   return (
     <div
       className={cn(
-        // Base layout
-        'disabled-icon absolute inset-0 hidden place-content-center',
-        // Colors
-        'text-[var(--swatch-radio-group-light-icon,var(--foreground))]',
+        'disabled-icon absolute inset-0 hidden place-content-center text-[--swatch-radio-group-icon,var(--form-fill-icon)]',
         className,
       )}
       data-slot="swatch-radio-group-indicator"
diff --git a/src/components/swatch-radio-group/primitives/swatch-radio-group-item.tsx b/src/components/swatch-radio-group/primitives/swatch-radio-group-item.tsx
index 3c0f438..073f06d 100644
--- a/src/components/swatch-radio-group/primitives/swatch-radio-group-item.tsx
+++ b/src/components/swatch-radio-group/primitives/swatch-radio-group-item.tsx
@@ -9,17 +9,13 @@ export function SwatchRadioGroupItem({ children, className, ...props }: SwatchRa
   return (
     <RadioGroupPrimitive.Item
       className={cn(
-        'group/swatch-radio-group-item relative box-content h-8 w-8 rounded-full border border-[var(--swatch-radio-group-light-unchecked-border,transparent)] p-0.5 transition-colors',
-        // Hover state
-        'hover:border-[var(--swatch-radio-group-light-unchecked-border-hover,var(--contrast-200))]',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--swatch-radio-group-focus,var(--brand))]',
+        'focus-primary group/swatch-radio-group-item relative box-content h-8 w-8 rounded-full border border-transparent p-0.5 transition-colors hover:border-[--border-hover]',
         // Checked state
-        'data-[state=checked]:border-[var(--swatch-radio-group-light-checked-border,var(--foreground))]',
+        'data-[state=checked]:border-[--border-checked]',
         // Aria-invalid state
-        'aria-invalid:border-[var(--swatch-radio-group-light-border-error,var(--error))]',
+        'aria-invalid:border-[--border-error]',
         // Disabled state
-        'disabled:border-[var(--swatch-radio-group-light-disabled-border,transparent)] data-[disabled]:pointer-events-none [&:disabled>.disabled-icon]:grid',
+        'disabled:border-transparent data-[disabled]:pointer-events-none [&:disabled>.disabled-icon]:grid',
         className,
       )}
       data-slot="swatch-radio-group-item"
diff --git a/src/components/swatch-radio-group/primitives/swatch-radio-group-thumbnail.tsx b/src/components/swatch-radio-group/primitives/swatch-radio-group-thumbnail.tsx
index 86ba7f5..940e71e 100644
--- a/src/components/swatch-radio-group/primitives/swatch-radio-group-thumbnail.tsx
+++ b/src/components/swatch-radio-group/primitives/swatch-radio-group-thumbnail.tsx
@@ -12,7 +12,7 @@ export function SwatchRadioGroupThumbnail({
   return (
     <span
       className={cn(
-        'relative block size-full overflow-hidden rounded-full border border-[var(--swatch-radio-group-light-option-border,color-mix(in_oklab,var(--foreground)_10%,transparent))] bg-clip-padding shadow',
+        'relative block size-full overflow-hidden rounded-full border bg-clip-padding shadow [border-color:color-mix(in_oklab,var(--foreground)_10%,transparent)]',
         className,
       )}
       data-slot="swatch-radio-group-thumbnail"
diff --git a/src/components/swatch-radio-group/storybook/swatch-radio-group.stories.tsx b/src/components/swatch-radio-group/storybook/swatch-radio-group.stories.tsx
index e41edd6..0d41209 100644
--- a/src/components/swatch-radio-group/storybook/swatch-radio-group.stories.tsx
+++ b/src/components/swatch-radio-group/storybook/swatch-radio-group.stories.tsx
@@ -1,7 +1,4 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { X } from 'lucide-react';
-import type { ComponentType } from 'react';
-import { useState } from 'react';
 
 import { SwatchRadioGroup, type SwatchRadioGroupProps } from '@/components/swatch-radio-group';
 import * as SwatchRadioGroupPrimitive from '@/components/swatch-radio-group/primitives';
@@ -57,60 +54,8 @@ A swatch radio group component for selecting a single option from color or image
 
 \`\`\`css
 :root {
-  --swatch-radio-group-focus: var(--brand);
-  --swatch-radio-group-light-icon: var(--foreground);
-  --swatch-radio-group-light-unchecked-border: transparent;
-  --swatch-radio-group-light-unchecked-border-hover: var(--contrast-200);
-  --swatch-radio-group-light-checked-border: var(--foreground);
-  --swatch-radio-group-light-disabled-border: transparent;
-  --swatch-radio-group-light-border-error: var(--error);
-  --swatch-radio-group-light-option-border: color-mix(in oklab, var(--foreground) 10%, transparent);
+  --swatch-radio-group-icon: var(--form-fill-icon);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`SwatchRadioGroup\` component provides a simple API with an \`options\` array:
-
-\`\`\`tsx
-import { SwatchRadioGroup } from '@/components/swatch-radio-group';
-
-// Color swatches
-const colorOptions = [
-  { type: 'color', value: 'black', label: 'Black', color: '#000000' },
-  { type: 'color', value: 'white', label: 'White', color: '#FFFFFF' },
-];
-
-<SwatchRadioGroup options={colorOptions} defaultValue="black" />
-
-// Image swatches
-const imageOptions = [
-  { type: 'image', value: 'variant-1', label: 'Variant 1', image: { src: '...', alt: '...' } },
-];
-
-<SwatchRadioGroup options={imageOptions} defaultValue="variant-1" />
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as SwatchRadioGroup from '@/components/swatch-radio-group';
-import { X } from 'lucide-react';
-
-<SwatchRadioGroup.Root defaultValue="black">
-  <SwatchRadioGroup.Item value="black" aria-label="Black">
-    <SwatchRadioGroup.Color color="#000000" />
-    <SwatchRadioGroup.Indicator>
-      <SwatchRadioGroup.IndicatorIcon>
-        <X size={16} />
-      </SwatchRadioGroup.IndicatorIcon>
-    </SwatchRadioGroup.Indicator>
-  </SwatchRadioGroup.Item>
-</SwatchRadioGroup.Root>
 \`\`\`
         `,
       },
@@ -120,7 +65,7 @@ import { X } from 'lucide-react';
   argTypes: {
     options: {
       control: false,
-      description: 'Array of swatch options (color or image type)',
+      description: 'Array of swatch options (`color` or `image` type)',
     },
     defaultValue: {
       control: 'text',
@@ -132,43 +77,55 @@ import { X } from 'lucide-react';
     },
     onOptionMouseEnter: {
       control: false,
-      description: 'Callback fired when hovering over an option (useful for image previews)',
+      description: 'Callback fired when hovering over an option',
     },
     indicatorIcon: {
       control: false,
-      description: 'Custom indicator icon configuration with asChild support',
+      description: 'Custom indicator icon configuration with `asChild` support',
     },
   },
-  decorators: [
-    (Story: ComponentType) => (
-      <div className="flex items-center justify-center p-8">
-        <Story />
-      </div>
-    ),
-  ],
 };
 
 export default meta;
 type Story = StoryObj<SwatchRadioGroupProps>;
 
-// Color swatches (default)
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Color swatches for selecting from a set of color options.',
+      },
+    },
+  },
   args: {
     options: colorOptions,
     defaultValue: 'black',
   },
 };
 
-// Image swatches
 export const ImageSwatches: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Image swatches for selecting from product variants or patterns.',
+      },
+    },
+  },
   args: {
     options: imageOptions,
     defaultValue: 'natural-brush',
   },
 };
 
-// Disabled items (out of stock)
 export const DisabledItems: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Individual options can be disabled (e.g., out of stock) using the `disabled` property.',
+      },
+    },
+  },
   args: {
     options: [
       { type: 'color', value: 'black', label: 'Black', color: '#000000' },
@@ -186,35 +143,70 @@ export const DisabledItems: Story = {
   },
 };
 
-// Controlled example
-export const Controlled: Story = {
-  render: () => {
-    const [value, setValue] = useState<string>('navy');
+export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Use the primitive components for full control over the structure.
+
+| Primitive                                | Description                                  |
+|------------------------------------------|----------------------------------------------|
+| \`SwatchRadioGroupPrimitive.Root\`          | Radio group container.                       |
+| \`SwatchRadioGroupPrimitive.Item\`          | Individual swatch item.                      |
+| \`SwatchRadioGroupPrimitive.Color\`         | Color swatch display.                        |
+| \`SwatchRadioGroupPrimitive.Thumbnail\`     | Container for image swatches.                |
+| \`SwatchRadioGroupPrimitive.Image\`         | Image swatch with \`asChild\` support.       |
+| \`SwatchRadioGroupPrimitive.Indicator\`     | Indicator shown when selected.               |
+| \`SwatchRadioGroupPrimitive.IndicatorIcon\` | X icon with \`asChild\` support.             |
+        `,
+      },
+      source: {
+        code: `
+import * as SwatchRadioGroupPrimitive from '@/components/swatch-radio-group/primitives';
 
-    return <SwatchRadioGroup onValueChange={setValue} options={colorOptions} value={value} />;
+<SwatchRadioGroupPrimitive.Root defaultValue="black">
+  <SwatchRadioGroupPrimitive.Item value="black" aria-label="Black">
+    <SwatchRadioGroupPrimitive.Color color="#000000" />
+    <SwatchRadioGroupPrimitive.Indicator>
+      <SwatchRadioGroupPrimitive.IndicatorIcon />
+    </SwatchRadioGroupPrimitive.Indicator>
+  </SwatchRadioGroupPrimitive.Item>
+  <SwatchRadioGroupPrimitive.Item value="white" aria-label="White">
+    <SwatchRadioGroupPrimitive.Color color="#FFFFFF" />
+    <SwatchRadioGroupPrimitive.Indicator>
+      <SwatchRadioGroupPrimitive.IndicatorIcon />
+    </SwatchRadioGroupPrimitive.Indicator>
+  </SwatchRadioGroupPrimitive.Item>
+  <SwatchRadioGroupPrimitive.Item value="navy" aria-label="Navy">
+    <SwatchRadioGroupPrimitive.Color color="#1e3a5f" />
+    <SwatchRadioGroupPrimitive.Indicator>
+      <SwatchRadioGroupPrimitive.IndicatorIcon />
+    </SwatchRadioGroupPrimitive.Indicator>
+  </SwatchRadioGroupPrimitive.Item>
+</SwatchRadioGroupPrimitive.Root>
+        `,
+      },
+    },
   },
-};
-
-// Composable anatomy example
-export const ComposableAnatomy: Story = {
   render: () => (
     <SwatchRadioGroupPrimitive.Root defaultValue="black">
       <SwatchRadioGroupPrimitive.Item aria-label="Black" value="black">
         <SwatchRadioGroupPrimitive.Color color="#000000" />
         <SwatchRadioGroupPrimitive.Indicator>
-          <X absoluteStrokeWidth size={16} strokeWidth={1.5} />
+          <SwatchRadioGroupPrimitive.IndicatorIcon />
         </SwatchRadioGroupPrimitive.Indicator>
       </SwatchRadioGroupPrimitive.Item>
       <SwatchRadioGroupPrimitive.Item aria-label="White" value="white">
         <SwatchRadioGroupPrimitive.Color color="#FFFFFF" />
         <SwatchRadioGroupPrimitive.Indicator>
-          <X absoluteStrokeWidth size={16} strokeWidth={1.5} />
+          <SwatchRadioGroupPrimitive.IndicatorIcon />
         </SwatchRadioGroupPrimitive.Indicator>
       </SwatchRadioGroupPrimitive.Item>
       <SwatchRadioGroupPrimitive.Item aria-label="Navy" value="navy">
         <SwatchRadioGroupPrimitive.Color color="#1e3a5f" />
         <SwatchRadioGroupPrimitive.Indicator>
-          <X absoluteStrokeWidth size={16} strokeWidth={1.5} />
+          <SwatchRadioGroupPrimitive.IndicatorIcon />
         </SwatchRadioGroupPrimitive.Indicator>
       </SwatchRadioGroupPrimitive.Item>
     </SwatchRadioGroupPrimitive.Root>
diff --git a/src/components/swatch-radio-group/swatch-radio-group.tsx b/src/components/swatch-radio-group/swatch-radio-group.tsx
index 0293ea2..ff83f97 100644
--- a/src/components/swatch-radio-group/swatch-radio-group.tsx
+++ b/src/components/swatch-radio-group/swatch-radio-group.tsx
@@ -37,16 +37,9 @@ export type SwatchRadioGroupProps = ComponentProps<typeof SwatchRadioGroupPrimit
  * with their default values:
  *
  * ```css
- *  :root {
- *    --swatch-radio-group-focus: var(--brand);
- *    --swatch-radio-group-light-icon: var(--foreground);
- *    --swatch-radio-group-light-unchecked-border: transparent;
- *    --swatch-radio-group-light-unchecked-border-hover: var(--contrast-200);
- *    --swatch-radio-group-light-disabled-border: transparent;
- *    --swatch-radio-group-light-border-error: var(--error);
- *    --swatch-radio-group-light-checked-border: var(--foreground);
- *    --swatch-radio-group-light-option-border: color-mix(in oklab, var(--foreground) 10%, transparent);
- *  }
+ * :root {
+ *   --swatch-radio-group-icon: var(--form-fill-icon);
+ * }
  * ```
  */
 export function SwatchRadioGroup({
diff --git a/src/components/tabs/primitives/tabs-content.tsx b/src/components/tabs/primitives/tabs-content.tsx
index e62e11a..652687a 100644
--- a/src/components/tabs/primitives/tabs-content.tsx
+++ b/src/components/tabs/primitives/tabs-content.tsx
@@ -10,11 +10,7 @@ export type TabsContentProps = ComponentProps<typeof TabsPrimitive.Content>;
 export function TabsContent({ className, children, ...props }: TabsContentProps) {
   return (
     <TabsPrimitive.Content
-      className={cn(
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--tabs-focus,var(--brand))]',
-        className,
-      )}
+      className={cn('focus:outline-none', className)}
       data-slot="tabs-content"
       {...props}
     >
diff --git a/src/components/tabs/primitives/tabs-list.tsx b/src/components/tabs/primitives/tabs-list.tsx
index 7649c72..bf6047e 100644
--- a/src/components/tabs/primitives/tabs-list.tsx
+++ b/src/components/tabs/primitives/tabs-list.tsx
@@ -37,7 +37,7 @@ export function TabsList({ className, ...props }: TabsListProps) {
   return (
     <TabsPrimitive.List
       className={cn(
-        'scrollbar-none flex overflow-x-auto border-b border-[var(--tabs-border,var(--contrast-100))]',
+        'scrollbar-none flex overflow-x-auto border-b border-[--border-subtle]',
         className,
       )}
       data-slot="tabs-list"
diff --git a/src/components/tabs/primitives/tabs-trigger.tsx b/src/components/tabs/primitives/tabs-trigger.tsx
index f915b92..b4b5e97 100644
--- a/src/components/tabs/primitives/tabs-trigger.tsx
+++ b/src/components/tabs/primitives/tabs-trigger.tsx
@@ -9,17 +9,17 @@ export function TabsTrigger({ className, children, ...props }: TabsTriggerProps)
   return (
     <TabsPrimitive.Trigger
       className={cn(
-        'relative shrink-0 p-4 text-sm font-semibold text-[var(--tabs-text,var(--contrast-500))] transition-colors duration-200 ease-linear [font-family:var(--tabs-font-family,var(--font-family-body))] after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:origin-bottom after:scale-y-0 after:bg-[var(--tabs-underline-default,var(--contrast-200))] after:transition-all after:duration-200 after:ease-linear after:content-[""]',
+        'relative shrink-0 p-4 text-sm font-semibold text-[--tabs-text,var(--text-secondary)] transition-colors duration-200 ease-linear [font-family:var(--tabs-font,var(--font-body))] after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:origin-bottom after:scale-y-0 after:bg-[--tabs-underline,var(--contrast-200)] after:transition-all after:duration-200 after:ease-linear after:content-[""]',
         // Hover state
-        'hover:text-[var(--tabs-text-hover,var(--foreground))] hover:after:scale-y-100',
+        'hover:text-[--tabs-text-hover,var(--text-primary)] hover:after:scale-y-100',
         // Focus-visible state
-        'focus:outline-none focus-visible:text-[var(--tabs-text-active,var(--foreground))] focus-visible:after:scale-y-100 focus-visible:after:bg-[var(--tabs-underline-active,var(--brand))]',
+        'focus:outline-none focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-[--border-focus-primary]',
         // Disabled state
-        'disabled:pointer-events-none disabled:text-[var(--tabs-text,var(--contrast-500))]',
+        'disabled:pointer-events-none disabled:text-[--tabs-text,var(--text-secondary)]',
         // Active state
-        'data-[state=active]:text-[var(--tabs-text-active,var(--foreground))] data-[state=active]:after:scale-y-100 data-[state=active]:after:bg-[var(--tabs-underline-active,var(--brand))]',
+        'data-[state=active]:text-[--tabs-text-active,var(--text-primary)] data-[state=active]:after:scale-y-100 data-[state=active]:after:bg-[--tabs-underline-active,var(--brand)]',
         // Inactive hover state
-        'data-[state=inactive]:hover:after:bg-[var(--tabs-underline-hover,var(--contrast-200)))',
+        'data-[state=inactive]:hover:after:bg-[--tabs-underline,var(--contrast-200)]',
         className,
       )}
       data-slot="tabs-trigger"
diff --git a/src/components/tabs/storybook/tabs.stories.tsx b/src/components/tabs/storybook/tabs.stories.tsx
index 904dca7..b228e7d 100644
--- a/src/components/tabs/storybook/tabs.stories.tsx
+++ b/src/components/tabs/storybook/tabs.stories.tsx
@@ -12,65 +12,19 @@ const meta: Meta<typeof Tabs> = {
     docs: {
       description: {
         component: `
-A tabbed interface component for organizing content into separate views. Built on Radix UI primitives with scrollable tab list support.
+A tabbed interface for organizing content into separate views. Built on Radix UI with scrollable tab list support.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --tabs-focus: var(--brand);
-  --tabs-font-family: var(--font-family-body);
-  --tabs-text: var(--contrast-500);
-  --tabs-text-hover: var(--foreground);
-  --tabs-text-active: var(--foreground);
-  --tabs-underline-default: var(--contrast-200);
+  --tabs-text: var(--text-secondary);
+  --tabs-text-hover: var(--text-primary);
+  --tabs-text-active: var(--text-primary);
+  --tabs-font: var(--font-body);
+  --tabs-underline: var(--contrast-200);
   --tabs-underline-active: var(--brand);
-  --tabs-underline-hover: var(--contrast-200);
-  --tabs-border: var(--contrast-100);
 }
-\`\`\`
-
-## Usage
-
-### High-Level Component
-
-The \`Tabs\` component provides a simple API with a \`tabs\` array:
-
-\`\`\`tsx
-import { Tabs } from '@/components/tabs';
-
-const tabs = [
-  { value: 'description', label: 'Description', content: <p>Product description...</p> },
-  { value: 'shipping', label: 'Shipping', content: <p>Shipping info...</p> },
-  { value: 'specs', label: 'Specs', content: <p>Product specs...</p> },
-];
-
-<Tabs defaultValue="description" tabs={tabs} />
-\`\`\`
-
-### Composable Anatomy
-
-For more control, use the primitive components directly:
-
-\`\`\`tsx
-import * as Tabs from '@/components/tabs';
-
-<Tabs.Root defaultValue="description">
-  <Tabs.List>
-    <Tabs.Trigger value="description">Description</Tabs.Trigger>
-    <Tabs.Trigger value="shipping">Shipping</Tabs.Trigger>
-    <Tabs.Trigger value="specs">Specs</Tabs.Trigger>
-  </Tabs.List>
-  <Tabs.Content value="description">
-    <p>Product description...</p>
-  </Tabs.Content>
-  <Tabs.Content value="shipping">
-    <p>Shipping info...</p>
-  </Tabs.Content>
-  <Tabs.Content value="specs">
-    <p>Product specs...</p>
-  </Tabs.Content>
-</Tabs.Root>
 \`\`\`
         `,
       },
@@ -80,21 +34,21 @@ import * as Tabs from '@/components/tabs';
   argTypes: {
     defaultValue: {
       control: 'text',
-      description: 'The value of the tab to select by default',
+      description: 'The initially selected tab value',
     },
     tabs: {
       control: false,
-      description: 'Array of tabs with value, label, and content',
+      description: 'Array of tab objects with `value`, `label`, and `content`',
     },
     activationMode: {
       control: 'select',
       options: ['automatic', 'manual'],
-      description: 'How tabs are activated when navigating with keyboard',
+      description: 'Keyboard navigation behavior',
     },
     orientation: {
       control: 'select',
       options: ['horizontal', 'vertical'],
-      description: 'Orientation of the tabs',
+      description: 'Tab list orientation',
     },
   },
   decorators: [
@@ -143,16 +97,48 @@ const productTabs: TabsProps['tabs'] = [
   },
 ];
 
-// Default tabs
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tabbed interface with product information sections.',
+      },
+    },
+  },
   args: {
     defaultValue: 'description',
     tabs: productTabs,
   },
 };
 
-// Composable anatomy example
 export const ComposableAnatomy: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use primitive components for custom layouts.',
+      },
+      source: {
+        code: `
+<TabsPrimitive.Root defaultValue="overview">
+  <TabsPrimitive.List>
+    <TabsPrimitive.Trigger value="overview">Overview</TabsPrimitive.Trigger>
+    <TabsPrimitive.Trigger value="features">Features</TabsPrimitive.Trigger>
+    <TabsPrimitive.Trigger value="reviews">Reviews</TabsPrimitive.Trigger>
+  </TabsPrimitive.List>
+  <TabsPrimitive.Content value="overview">
+    <p>Product overview content.</p>
+  </TabsPrimitive.Content>
+  <TabsPrimitive.Content value="features">
+    <p>Product features content.</p>
+  </TabsPrimitive.Content>
+  <TabsPrimitive.Content value="reviews">
+    <p>Customer reviews content.</p>
+  </TabsPrimitive.Content>
+</TabsPrimitive.Root>
+        `,
+      },
+    },
+  },
   render: () => (
     <TabsPrimitive.Root defaultValue="overview">
       <TabsPrimitive.List>
diff --git a/src/components/tabs/tabs.tsx b/src/components/tabs/tabs.tsx
index 5cd5b52..1b87f4b 100644
--- a/src/components/tabs/tabs.tsx
+++ b/src/components/tabs/tabs.tsx
@@ -20,15 +20,12 @@ export interface TabsProps extends TabsPrimitives.RootProps {
  *
  * ```css
  * :root {
- *   --tabs-focus: var(--brand);
- *   --tabs-font-family: var(--font-family-body);
- *   --tabs-text: var(--contrast-500);
- *   --tabs-text-hover: var(--foreground);
- *   --tabs-text-active: var(--foreground);
- *   --tabs-underline-default: var(--contrast-200);
+ *   --tabs-text: var(--text-secondary);
+ *   --tabs-text-hover: var(--text-primary);
+ *   --tabs-text-active: var(--text-primary);
+ *   --tabs-font: var(--font-body);
+ *   --tabs-underline: var(--contrast-200);
  *   --tabs-underline-active: var(--brand);
- *   --tabs-underline-hover: var(--contrast-200);
- *   --tabs-border: var(--contrast-100);
  * }
  * ```
  */
diff --git a/src/components/textarea/storybook/textarea.stories.tsx b/src/components/textarea/storybook/textarea.stories.tsx
index 974be4c..d2d7428 100644
--- a/src/components/textarea/storybook/textarea.stories.tsx
+++ b/src/components/textarea/storybook/textarea.stories.tsx
@@ -10,28 +10,17 @@ const meta: Meta<typeof Textarea> = {
     docs: {
       description: {
         component: `
-A multi-line text input component for collecting longer form text content.
+A multi-line text input for collecting longer form text content.
 
 ## CSS Variables
 
 \`\`\`css
 :root {
-  --textarea-focus: var(--brand);
-  --textarea-light-background: var(--background);
-  --textarea-light-text: var(--foreground);
-  --textarea-light-placeholder: var(--contrast-300);
-  --textarea-light-border: var(--contrast-100);
-  --textarea-light-border-focus: var(--foreground);
-  --textarea-light-border-error: var(--error);
+  --textarea-fill: var(--form-fill);
+  --textarea-fill-disabled: var(--form-fill-disabled);
+  --textarea-text: var(--form-text-primary);
+  --textarea-text-placeholder: var(--form-text-placeholder);
 }
-\`\`\`
-
-## Usage
-
-\`\`\`tsx
-import { Textarea } from '@/components/textarea';
-
-<Textarea placeholder="Enter your message..." rows={4} />
 \`\`\`
         `,
       },
@@ -41,11 +30,11 @@ import { Textarea } from '@/components/textarea';
   argTypes: {
     placeholder: {
       control: 'text',
-      description: 'Placeholder text displayed when the textarea is empty',
+      description: 'Placeholder text when empty',
     },
     disabled: {
       control: 'boolean',
-      description: 'Whether the textarea is disabled',
+      description: 'Disable the textarea',
     },
     rows: {
       control: 'number',
@@ -53,11 +42,11 @@ import { Textarea } from '@/components/textarea';
     },
     maxLength: {
       control: 'number',
-      description: 'Maximum number of characters allowed',
+      description: 'Maximum character count',
     },
     readOnly: {
       control: 'boolean',
-      description: 'Whether the textarea is read-only',
+      description: 'Make the textarea read-only',
     },
   },
   args: {
@@ -68,27 +57,52 @@ import { Textarea } from '@/components/textarea';
 export default meta;
 type Story = StoryObj<TextareaProps>;
 
-// Default textarea
-export const Default: Story = {};
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Basic textarea with placeholder text.',
+      },
+    },
+  },
+};
 
-// With default value
 export const WithValue: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Textarea with pre-filled content.',
+      },
+    },
+  },
   args: {
     defaultValue:
       'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
   },
 };
 
-// Disabled state
 export const Disabled: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Disabled state prevents user interaction.',
+      },
+    },
+  },
   args: {
     disabled: true,
     defaultValue: 'This content cannot be edited',
   },
 };
 
-// Error state
 export const ErrorState: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `aria-invalid` to indicate validation errors.',
+      },
+    },
+  },
   args: {
     'aria-invalid': true,
     defaultValue: 'This field has an error',
diff --git a/src/components/textarea/textarea.tsx b/src/components/textarea/textarea.tsx
index 2b0a10d..acdb731 100644
--- a/src/components/textarea/textarea.tsx
+++ b/src/components/textarea/textarea.tsx
@@ -4,17 +4,31 @@ import { cn } from '@/lib';
 
 export type TextareaProps = ComponentProps<'textarea'>;
 
+/**
+ * This component supports various CSS variables for theming. Here's a comprehensive list, along
+ * with their default values:
+ *
+ * ```css
+ * :root {
+ *   --textarea-fill: var(--form-fill);
+ *   --textarea-fill-disabled: var(--form-fill-disabled);
+ *   --textarea-text: var(--form-text-primary);
+ *   --textarea-text-placeholder: var(--form-text-placeholder);
+ *   --textarea-font: var(--font-body);
+ * }
+ * ```
+ */
 export function Textarea({ className, ...props }: TextareaProps) {
   return (
     <textarea
       className={cn(
-        'w-full rounded-lg border border-[var(--textarea-light-border,var(--contrast-100))] bg-[var(--textarea-light-background,var(--background))] p-3 text-sm font-normal text-[var(--textarea-light-text,var(--foreground))] placeholder-[var(--textarea-light-placeholder,var(--contrast-300))] transition-colors duration-200',
+        'w-full rounded-lg border border-[--border-subtle] bg-[--textarea-fill,var(--form-fill)] p-3 text-sm text-[--textarea-text,var(--form-text-primary)] placeholder-[--textarea-text-placeholder,var(--form-text-placeholder)] transition-colors duration-200 [font-family:var(--textarea-font,var(--font-body))]',
         // Focus state
-        'focus:border-[var(--textarea-light-focus,var(--foreground))] focus:outline-none',
+        'focus:border-[--border-focus-secondary] focus:outline-none',
         // Disabled state
-        'disabled:cursor-not-allowed disabled:opacity-50',
+        'disabled:cursor-not-allowed disabled:bg-[--textarea-fill-disabled,var(--form-fill-disabled)] disabled:opacity-50',
         // Aria-invalid state
-        'aria-invalid:border-[var(--textarea-light-border-error,var(--error))]',
+        'aria-invalid:border-[--border-error]',
         className,
       )}
       data-slot="textarea"
diff --git a/src/components/toaster/storybook/toaster.stories.tsx b/src/components/toaster/storybook/toaster.stories.tsx
index 949b02b..a933835 100644
--- a/src/components/toaster/storybook/toaster.stories.tsx
+++ b/src/components/toaster/storybook/toaster.stories.tsx
@@ -15,46 +15,22 @@ const meta: Meta<typeof Toaster> = {
     docs: {
       description: {
         component: `
-A toast notification system built on Sonner with Alert component styling. Displays temporary messages for user feedback.
+A toast notification system built on Sonner. Uses the Alert component internally for consistent styling across variants.
 
 ## CSS Variables
 
-The Toaster uses the Alert component internally, which supports theming through CSS variables:
+The Toaster inherits theming from the Alert component:
 
 \`\`\`css
 :root {
-  --alert-success-background: color-mix(in oklab, var(--success), white 75%);
-  --alert-warning-background: color-mix(in oklab, var(--warning), white 75%);
-  --alert-error-background: color-mix(in oklab, var(--error), white 75%);
-  --alert-info-background: var(--background);
-  --alert-font-family: var(--font-family-body);
-  --alert-border: color-mix(in oklab, var(--foreground) 10%, transparent);
-  --alert-message-text: var(--foreground);
-  --alert-description-text: color-mix(in oklab, var(--foreground) 50%, transparent);
+  --alert-text: var(--text-primary);
+  --alert-fill-info: var(--background);
+  --alert-fill-success: var(--success-background);
+  --alert-fill-warning: var(--warning-background);
+  --alert-fill-error: var(--error-background);
+  --alert-font-title: var(--font-body);
+  --alert-font-description: var(--font-body);
 }
-\`\`\`
-
-## Usage
-
-Add the \`Toaster\` component to your app layout, then use the \`toast\` object to trigger notifications:
-
-\`\`\`tsx
-import { toast, Toaster } from '@/components/toaster';
-
-// In your layout
-<Toaster position="top-right" />
-
-// Trigger toasts from anywhere
-toast.success('Settings saved');
-toast.error('Something went wrong');
-toast.warning('Low disk space');
-toast.info('New update available');
-
-// With options
-toast.success('Item added to cart', {
-  description: 'You can view your cart anytime',
-  action: { label: 'View Cart', onClick: () => navigateToCart() },
-});
 \`\`\`
         `,
       },
@@ -83,8 +59,14 @@ toast.success('Item added to cart', {
 export default meta;
 type Story = StoryObj<ToasterProps>;
 
-// All toast variants
 export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'All toast variants: success, error, warning, and info.',
+      },
+    },
+  },
   render: (args) => (
     <div className="space-y-4">
       <Toaster position={args.position} />
@@ -106,8 +88,14 @@ export const Default: Story = {
   ),
 };
 
-// With action button
 export const WithAction: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Toast with an action button for user interaction.',
+      },
+    },
+  },
   render: (args) => (
     <div className="space-y-4">
       <Toaster position={args.position} />
@@ -125,8 +113,14 @@ export const WithAction: Story = {
   ),
 };
 
-// With description
 export const WithDescription: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Toast with additional description text.',
+      },
+    },
+  },
   render: (args) => (
     <div className="space-y-4">
       <Toaster position={args.position} />
diff --git a/src/components/toggle-group/primitives/toggle-group-item.tsx b/src/components/toggle-group/primitives/toggle-group-item.tsx
index a9a34a6..979d942 100644
--- a/src/components/toggle-group/primitives/toggle-group-item.tsx
+++ b/src/components/toggle-group/primitives/toggle-group-item.tsx
@@ -9,15 +9,13 @@ export function ToggleGroupItem({ children, className, ...props }: ToggleGroupIt
   return (
     <ToggleGroupPrimitive.Item
       className={cn(
-        'h-12 whitespace-nowrap rounded-full border border-[var(--toggle-group-light-border,var(--contrast-100))] px-4 font-body text-sm font-normal leading-normal transition-colors',
-        // Focus-visible state
-        'focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--toggle-group-light-focus,var(--brand))]',
+        'focus-primary h-12 min-w-12 whitespace-nowrap rounded-full border border-[--border-subtle] px-4 font-body text-sm font-normal leading-normal transition-colors',
         // Off state
-        'data-[state=off]:bg-[var(--toggle-group-light-off-background,var(--background))] data-[state=off]:text-[var(--toggle-group-light-off-text,var(--foreground))]',
+        'data-[state=off]:bg-[--toggle-group-fill-unchecked,var(--form-fill-unchecked)] data-[state=off]:text-[--toggle-group-text-unchecked,var(--form-text-unchecked)]',
         // Off + Hover state
-        'data-[state=off]:hover:border-[var(--toggle-group-light-off-border-hover,var(--contrast-200))] data-[state=off]:hover:bg-[var(--toggle-group-light-off-background-hover,var(--contrast-100))]',
+        'data-[state=off]:hover:border-[--border] data-[state=off]:hover:bg-[--toggle-group-fill-hover,var(--form-fill-hover)]',
         // On state
-        'data-[state=on]:border-[var(--toggle-group-light-on-border,var(--foreground))] data-[state=on]:bg-[var(--toggle-group-light-on-background,var(--foreground))] data-[state=on]:text-[var(--toggle-group-light-on-text,var(--background))]',
+        'data-[state=on]:border-[--border-checked] data-[state=on]:bg-[--toggle-group-fill-checked,var(--form-fill-checked)] data-[state=on]:text-[--toggle-group-text-checked,var(--form-text-checked)]',
         // Disabled state
         'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
         className,
diff --git a/src/components/toggle-group/storybook/toggle-group.stories.tsx b/src/components/toggle-group/storybook/toggle-group.stories.tsx
index 2f9e645..e58fc36 100644
--- a/src/components/toggle-group/storybook/toggle-group.stories.tsx
+++ b/src/components/toggle-group/storybook/toggle-group.stories.tsx
@@ -32,15 +32,11 @@ A toggle group component for selecting one or multiple options from a set of cho
 
 \`\`\`css
 :root {
-  --toggle-group-light-focus: var(--brand);
-  --toggle-group-light-border: var(--contrast-100);
-  --toggle-group-light-on-border: var(--foreground);
-  --toggle-group-light-on-background: var(--foreground);
-  --toggle-group-light-off-background: var(--background);
-  --toggle-group-light-off-text: var(--foreground);
-  --toggle-group-light-on-text: var(--background);
-  --toggle-group-light-off-border-hover: var(--contrast-200);
-  --toggle-group-light-off-background-hover: var(--contrast-100);
+  --toggle-group-fill-unchecked: var(--form-fill-unchecked);
+  --toggle-group-fill-checked: var(--form-fill-checked);
+  --toggle-group-fill-hover: var(--form-fill-hover);
+  --toggle-group-text-unchecked: var(--form-text-unchecked);
+  --toggle-group-text-checked: var(--form-text-checked);
 }
 \`\`\`
 
diff --git a/src/components/toggle-group/toggle-group.tsx b/src/components/toggle-group/toggle-group.tsx
index b5c0a38..f6bf469 100644
--- a/src/components/toggle-group/toggle-group.tsx
+++ b/src/components/toggle-group/toggle-group.tsx
@@ -20,16 +20,12 @@ export type ToggleGroupProps = ComponentProps<typeof ToggleGroupPrimitive.Root>
  * with their default values:
  *
  * ```css
- *  :root {
- *   --toggle-group-light-focus: var(--brand);
- *   --toggle-group-light-border: var(--contrast-100);
- *   --toggle-group-light-on-border: var(--foreground);
- *   --toggle-group-light-on-background: var(--foreground);
- *   --toggle-group-light-off-background: var(--background);
- *   --toggle-group-light-off-text: var(--foreground);
- *   --toggle-group-light-on-text: var(--background);
- *   --toggle-group-light-off-border-hover: var(--contrast-200);
- *   --toggle-group-light-off-background-hover: var(--contrast-100);
+ * :root {
+ *   --toggle-group-fill-unchecked: var(--form-fill-unchecked);
+ *   --toggle-group-fill-checked: var(--form-fill-checked);
+ *   --toggle-group-fill-hover: var(--form-fill-hover);
+ *   --toggle-group-text-unchecked: var(--form-text-unchecked);
+ *   --toggle-group-text-checked: var(--form-text-checked);
  * }
  * ```
  */
diff --git a/src/globals.css b/src/globals.css
index 3842535..ffc165d 100644
--- a/src/globals.css
+++ b/src/globals.css
@@ -11,6 +11,28 @@
     -ms-overflow-style: none; /* IE and Edge */
     scrollbar-width: none; /* Firefox */
   }
+
+  .focus-primary {
+    &:focus {
+      outline: none;
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--border-focus-primary);
+      outline-offset: 2px;
+    }
+  }
+
+  .focus-secondary {
+    &:focus {
+      outline: none;
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--border-focus-secondary);
+      outline-offset: 2px;
+    }
+  }
 }
 
 :root {
@@ -56,17 +78,35 @@
 
   --text-primary: oklch(var(--foreground-lch));
   --text-secondary: oklch(var(--contrast-500-lch));
-  --text-disabled: oklch(var(--contrast-400-lch));
   --text-inverse: oklch(var(--background-lch));
 
   --fill-pending: oklch(var(--contrast-100-lch));
+  --fill-image: oklch(var(--contrast-100-lch));
 
-  --border-subtle: oklch(var(--contrast-100-lch));
   --border: oklch(var(--contrast-200-lch));
+  --border-subtle: oklch(var(--contrast-100-lch));
+  --border-inverse: oklch(var(--background-lch));
   --border-hover: oklch(var(--contrast-300-lch));
+  --border-checked: oklch(var(--foreground-lch));
   --border-error: oklch(var(--error-lch));
-  --border-focus: oklch(var(--primary-lch));
+  --border-focus-primary: oklch(var(--brand-lch));
+  --border-focus-secondary: oklch(var(--foreground-lch));
+
+  --font-heading: 'General Sans', sans-serif;
+  --font-body: 'Inter', sans-serif;
 
-  --font-family-heading: 'DM Serif Text', serif;
-  --font-family-body: 'Inter', sans-serif;
+  --form-fill: oklch(var(--background-lch));
+  --form-fill-hover: oklch(var(--contrast-100-lch));
+  --form-fill-disabled: oklch(var(--contrast-100-lch));
+  --form-fill-checked: oklch(var(--foreground-lch));
+  --form-fill-unchecked: oklch(var(--background-lch));
+  --form-fill-icon: oklch(var(--contrast-400-lch));
+  --form-fill-icon-hover: oklch(var(--foreground-lch));
+  --form-text-primary: oklch(var(--foreground-lch));
+  --form-text-secondary: oklch(var(--contrast-500-lch));
+  --form-text-disabled: oklch(var(--contrast-300-lch));
+  --form-text-hover: oklch(var(--foreground-lch));
+  --form-text-placeholder: oklch(var(--contrast-400-lch));
+  --form-text-checked: oklch(var(--background-lch));
+  --form-text-unchecked: oklch(var(--foreground-lch));
 }
diff --git a/src/index.ts b/src/index.ts
index bbe119d..f7f37c5 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -13,8 +13,8 @@ export { Badge, type BadgeProps } from '@/components/badge';
 // Banner
 export { Banner, type BannerProps } from '@/components/banner';
 
-// BlogPostCard
-export { BlogPostCard, type BlogPostCardProps } from '@/components/blog-post-card';
+// BlogCard
+export { BlogCard, type BlogCardProps } from '@/components/blog-card';
 
 // Button
 export { Button, type ButtonProps } from '@/components/button';
diff --git a/src/styles.css b/src/styles.css
deleted file mode 100644
index c6bbb0a..0000000
--- a/src/styles.css
+++ /dev/null
@@ -1,41 +0,0 @@
-/* Commerce Toolkit CSS Variables */
-:root {
-  --brand: 96 100% 68%;
-  --accent: 96 100% 88%;
-  --background: 0 0% 100%;
-  --foreground: 0 0% 7%;
-  --success: 116 78% 65%;
-  --error: 0 100% 60%;
-  --warning: 40 100% 60%;
-  --info: 220 70% 45%;
-  --contrast-100: 0 0% 93%;
-  --contrast-200: 0 0% 82%;
-  --contrast-300: 0 0% 70%;
-  --contrast-400: 0 0% 54%;
-  --contrast-500: 0 0% 34%;
-  --font-family-heading:
-    'DM Serif Text', ui-serif, Georgia, Cambria, 'Times New Roman', Times, serif;
-  --font-family-body:
-    'Inter', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
-    'Segoe UI Symbol', 'Noto Color Emoji';
-  --font-family-body:
-    'Roboto Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
-    'Courier New', monospace;
-  --font-feature-settings-heading: normal;
-  --font-feature-settings-body: normal;
-  --font-feature-settings-mono: normal;
-  --font-variation-settings-body: 'slnt' 0;
-  --font-variation-settings-heading: 'slnt' 0;
-  --font-variation-settings-mono: normal;
-  --font-size-xs: 0.75rem;
-  --font-size-sm: 0.875rem;
-  --font-size-base: 1rem;
-  --font-size-lg: 1.125rem;
-  --font-size-xl: 1.25rem;
-  --font-size-2xl: 1.5rem;
-  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
-  --shadow-base: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
-  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
-  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
-  --shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
-}
diff --git a/tailwind.config.ts b/tailwind.config.ts
index 6c9aab8..8ade3cf 100644
--- a/tailwind.config.ts
+++ b/tailwind.config.ts
@@ -4,18 +4,4 @@ import preset from './tailwind.preset.js';
 export default {
   presets: [preset],
   content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}', '.storybook/**/*.{js,ts,jsx,tsx}'],
-  theme: {
-    extend: {
-      keyframes: {
-        'heart-pulse': {
-          '0%': { transform: 'scale(1)' },
-          '50%': { transform: 'scale(1.3)' },
-          '100%': { transform: 'scale(1)' },
-        },
-      },
-      animation: {
-        'heart-pulse': 'heart-pulse 0.75s forwards',
-      },
-    },
-  },
 } satisfies Config;
diff --git a/tailwind.preset.js b/tailwind.preset.js
index 3e31044..0db9f56 100644
--- a/tailwind.preset.js
+++ b/tailwind.preset.js
@@ -14,31 +14,31 @@ export default {
           css: {
             h1: {
               color: 'var(--text-primary)',
-              fontFamily: 'var(--font-family-heading)',
+              fontFamily: 'var(--font-heading)',
             },
             h2: {
               color: 'var(--text-primary)',
-              fontFamily: 'var(--font-family-heading)',
+              fontFamily: 'var(--font-heading)',
             },
             h3: {
               color: 'var(--text-primary)',
-              fontFamily: 'var(--font-family-heading)',
+              fontFamily: 'var(--font-heading)',
             },
             h4: {
               color: 'var(--text-primary)',
-              fontFamily: 'var(--font-family-heading)',
+              fontFamily: 'var(--font-heading)',
             },
             h5: {
               color: 'var(--text-primary)',
-              fontFamily: 'var(--font-family-heading)',
+              fontFamily: 'var(--font-heading)',
             },
             h6: {
               color: 'var(--text-primary)',
-              fontFamily: 'var(--font-family-heading)',
+              fontFamily: 'var(--font-heading)',
             },
             p: {
               color: 'var(--text-secondary)',
-              fontFamily: 'var(--font-family-body)',
+              fontFamily: 'var(--font-body)',
             },
             a: {
               color: 'var(--text-secondary)',
@@ -52,11 +52,11 @@ export default {
             },
             ul: {
               color: 'var(--text-secondary)',
-              fontFamily: 'var(--font-family-body)',
+              fontFamily: 'var(--font-body)',
             },
             ol: {
               color: 'var(--text-secondary)',
-              fontFamily: 'var(--font-family-body)',
+              fontFamily: 'var(--font-body)',
             },
             strong: {
               fontWeight: '600',
@@ -71,12 +71,12 @@ export default {
             },
             code: {
               color: 'var(--contrast-500)',
-              fontFamily: 'var(--font-family-body)',
+              fontFamily: 'var(--font-body)',
             },
             pre: {
               color: 'var(--background)',
               backgroundColor: 'var(--foreground)',
-              fontFamily: 'var(--font-family-body)',
+              fontFamily: 'var(--font-body)',
             },
           },
         },
@@ -113,8 +113,89 @@ export default {
         },
       },
       fontFamily: {
-        heading: 'var(--font-family-heading)',
-        body: 'var(--font-family-body)',
+        heading: 'var(--font-heading)',
+        body: 'var(--font-body)',
+      },
+      fontSize: {
+        xs: [
+          '0.75rem',
+          {
+            lineHeight: '1.125rem',
+          },
+        ],
+        sm: [
+          '0.875rem',
+          {
+            lineHeight: '1.25rem',
+          },
+        ],
+        base: [
+          '1rem',
+          {
+            lineHeight: '1.5rem',
+          },
+        ],
+        lg: [
+          '1.125rem',
+          {
+            lineHeight: '1.75rem',
+            letterSpacing: '-0.01em',
+          },
+        ],
+        xl: [
+          '1.25rem',
+          {
+            lineHeight: '2.25rem',
+            letterSpacing: '-0.01em',
+          },
+        ],
+        '2xl': [
+          '1.5rem',
+          {
+            lineHeight: '1.75rem',
+          },
+        ],
+        '3xl': [
+          '1.875rem',
+          {
+            lineHeight: '2rem',
+          },
+        ],
+        '4xl': [
+          '2.5rem',
+          {
+            lineHeight: '2.75rem',
+            letterSpacing: '-0.01em',
+          },
+        ],
+        '5xl': [
+          '3rem',
+          {
+            lineHeight: '3.25rem',
+            letterSpacing: '-0.01em',
+          },
+        ],
+        '6xl': [
+          '3.75rem',
+          {
+            lineHeight: '4rem',
+            letterSpacing: '-0.01em',
+          },
+        ],
+        '7xl': [
+          '4.5rem',
+          {
+            lineHeight: '1',
+            letterSpacing: '-0.02em',
+          },
+        ],
+        '8xl': [
+          '6rem',
+          {
+            lineHeight: '1',
+            letterSpacing: '-0.02em',
+          },
+        ],
       },
       keyframes: {
         collapse: {
@@ -125,10 +206,16 @@ export default {
           from: { height: '0' },
           to: { height: 'var(--radix-accordion-content-height)' },
         },
+        'heart-pulse': {
+          '0%': { transform: 'scale(1)' },
+          '50%': { transform: 'scale(1.3)' },
+          '100%': { transform: 'scale(1)' },
+        },
       },
       animation: {
         collapse: 'collapse 400ms cubic-bezier(1, 0, 0.25, 1)',
         expand: 'expand 400ms cubic-bezier(1, 0, 0.25, 1)',
+        'heart-pulse': 'heart-pulse 0.75s forwards',
       },
     },
   },