From 3e4ec12b22e064419c3a74394de23e9f7d757c1b Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Thu, 5 Mar 2026 08:47:22 -0600
Subject: [PATCH 1/8] docs(ui): add ButtonGroup stories to storybook

---
 .storybook/main.ts                      |  35 +----
 .storybook/manager.ts                   |   9 +-
 .storybook/preview-head.html            |   6 +
 .storybook/preview.ts                   |  57 ++++----
 .storybook/theme.ts                     |  13 ++
 app/components/Button/Base.stories.ts   |  60 ---------
 app/components/Button/Base.vue          |   7 +
 app/components/Button/Button.stories.ts | 165 ++++++++++++++++++++++++
 package.json                            |   1 +
 pnpm-lock.yaml                          |  31 +++++
 pnpm-workspace.yaml                     |   1 +
 11 files changed, 264 insertions(+), 121 deletions(-)
 create mode 100644 .storybook/preview-head.html
 create mode 100644 .storybook/theme.ts
 delete mode 100644 app/components/Button/Base.stories.ts
 create mode 100644 app/components/Button/Button.stories.ts

diff --git a/.storybook/main.ts b/.storybook/main.ts
index 45af6e1491..06e3153da9 100644
--- a/.storybook/main.ts
+++ b/.storybook/main.ts
@@ -2,7 +2,12 @@ import type { StorybookConfig } from '@storybook-vue/nuxt'
 
 const config = {
   stories: ['../app/**/*.stories.@(js|ts)'],
-  addons: ['@storybook/addon-a11y', '@storybook/addon-docs', '@storybook/addon-themes'],
+  addons: [
+    '@storybook/addon-a11y',
+    '@storybook/addon-docs',
+    '@storybook/addon-themes',
+    'storybook-i18n',
+  ],
   framework: '@storybook-vue/nuxt',
   staticDirs: ['./.public'],
   features: {
@@ -19,34 +24,6 @@ const config = {
         }
       },
     })
-    // Replace the built-in vue-docgen plugin with a fault-tolerant version.
-    // vue-docgen-api can crash on components that import types from other
-    // .vue files (it tries to parse the SFC with @babel/parser as plain TS).
-    // This wrapper catches those errors so the build doesn't fail.
-    const docgenPlugin = config.plugins?.find(
-      (p): p is Extract<typeof p, { name: string }> =>
-        !!p && typeof p === 'object' && 'name' in p && p.name === 'storybook:vue-docgen-plugin',
-    )
-
-    if (docgenPlugin && 'transform' in docgenPlugin) {
-      const hook = docgenPlugin.transform
-      // Vite plugin hooks can be a function or an object with a `handler` property
-      const originalFn = typeof hook === 'function' ? hook : hook?.handler
-      if (originalFn) {
-        const wrapped = async function (this: unknown, ...args: unknown[]) {
-          try {
-            return await originalFn.apply(this, args)
-          } catch {
-            return undefined
-          }
-        }
-        if (typeof hook === 'function') {
-          docgenPlugin.transform = wrapped as typeof hook
-        } else if (hook) {
-          hook.handler = wrapped as typeof hook.handler
-        }
-      }
-    }
 
     return config
   },
diff --git a/.storybook/manager.ts b/.storybook/manager.ts
index 023e4fd21d..e56c80a6a6 100644
--- a/.storybook/manager.ts
+++ b/.storybook/manager.ts
@@ -1,11 +1,6 @@
 import { addons } from 'storybook/manager-api'
-import { create } from 'storybook/theming'
-
-const npmxTheme = create({
-  brandTitle: 'npmx Storybook',
-  brandImage: '/npmx-storybook.svg',
-})
+import npmxDark from './theme'
 
 addons.setConfig({
-  theme: npmxTheme,
+  theme: npmxDark,
 })
diff --git a/.storybook/preview-head.html b/.storybook/preview-head.html
new file mode 100644
index 0000000000..49c5636054
--- /dev/null
+++ b/.storybook/preview-head.html
@@ -0,0 +1,6 @@
+<style>
+  /* Override docs story canvas background to match npmx theme */
+  .docs-story {
+    background-color: var(--bg, oklch(0.171 0 0)) !important;
+  }
+</style>
diff --git a/.storybook/preview.ts b/.storybook/preview.ts
index 3242f7788a..1a3f4ff432 100644
--- a/.storybook/preview.ts
+++ b/.storybook/preview.ts
@@ -1,8 +1,10 @@
 import type { Preview } from '@storybook-vue/nuxt'
 import { withThemeByDataAttribute } from '@storybook/addon-themes'
+import { addons } from 'storybook/preview-api'
 import { currentLocales } from '../config/i18n'
 import { fn } from 'storybook/test'
 import { ACCENT_COLORS } from '../shared/utils/constants'
+import npmxDark from './theme'
 
 // related: https://github.com/npmx-dev/npmx.dev/blob/1431d24be555bca5e1ae6264434d49ca15173c43/test/nuxt/setup.ts#L12-L26
 // Stub Nuxt specific globals
@@ -25,25 +27,22 @@ const preview: Preview = {
         date: /Date$/i,
       },
     },
+    docs: {
+      theme: npmxDark,
+    },
+  },
+  initialGlobals: {
+    locale: 'en-US',
+    locales: currentLocales.reduce(
+      (acc, locale) => {
+        acc[locale.code] = locale.name
+        return acc
+      },
+      {} as Record<string, string>,
+    ),
   },
   // Provides toolbars to switch things like theming and language
   globalTypes: {
-    locale: {
-      name: 'Locale',
-      description: 'UI language',
-      defaultValue: 'en-US',
-      toolbar: {
-        icon: 'globe',
-        dynamicTitle: true,
-        items: [
-          // English is at the top so it's easier to reset to it
-          { value: 'en-US', title: 'English (US)' },
-          ...currentLocales
-            .filter(locale => locale.code !== 'en-US')
-            .map(locale => ({ value: locale.code, title: locale.name })),
-        ],
-      },
-    },
     accentColor: {
       name: 'Accent Color',
       description: 'Accent color',
@@ -70,9 +69,9 @@ const preview: Preview = {
       attributeName: 'data-theme',
     }),
     (story, context) => {
-      const { locale, accentColor } = context.globals as {
-        locale: string
+      const { accentColor, locale } = context.globals as {
         accentColor?: string
+        locale?: string
       }
 
       // Set accent color from globals
@@ -82,16 +81,24 @@ const preview: Preview = {
         document.documentElement.style.removeProperty('--accent-color')
       }
 
+      // Store reference to i18n instance for locale changes
+      let i18nInstance: any = null
+
+      // Subscribe to locale changes from storybook-i18n addon
+      addons.getChannel().on('LOCALE_CHANGED', (newLocale: string) => {
+        if (i18nInstance) {
+          i18nInstance.setLocale(newLocale)
+        }
+      })
+
       return {
         template: '<story />',
-        // Set locale from globals
         created() {
-          if (this.$i18n) {
-            this.$i18n.setLocale(locale)
-          }
-        },
-        updated() {
-          if (this.$i18n) {
+          // Store i18n instance for LOCALE_CHANGED events
+          i18nInstance = this.$i18n
+
+          // Set initial locale when component is created
+          if (locale && this.$i18n) {
             this.$i18n.setLocale(locale)
           }
         },
diff --git a/.storybook/theme.ts b/.storybook/theme.ts
new file mode 100644
index 0000000000..3bb46e9677
--- /dev/null
+++ b/.storybook/theme.ts
@@ -0,0 +1,13 @@
+import { create } from 'storybook/theming/create'
+
+export const npmxDark = create({
+  base: 'dark',
+
+  brandTitle: 'npmx Storybook',
+  brandImage: '/npmx-storybook.svg',
+
+  // UI
+  appContentBg: '#101010', // oklch(0.171 0 0)
+})
+
+export default npmxDark
diff --git a/app/components/Button/Base.stories.ts b/app/components/Button/Base.stories.ts
deleted file mode 100644
index 9de0744377..0000000000
--- a/app/components/Button/Base.stories.ts
+++ /dev/null
@@ -1,60 +0,0 @@
-import type { Meta, StoryObj } from '@storybook-vue/nuxt'
-import Component from './Base.vue'
-
-const meta = {
-  component: Component,
-} satisfies Meta<typeof Component>
-
-export default meta
-type Story = StoryObj<typeof meta>
-
-export const Primary: Story = {
-  args: {
-    default: 'Primary Button',
-  },
-}
-
-export const Secondary: Story = {
-  args: {
-    default: 'Secondary Button',
-    variant: 'secondary',
-  },
-}
-
-export const Small: Story = {
-  args: {
-    default: 'Small Button',
-    size: 'small',
-    variant: 'secondary',
-  },
-}
-
-export const Disabled: Story = {
-  args: {
-    default: 'Disabled Button',
-    disabled: true,
-  },
-}
-
-export const WithIcon: Story = {
-  args: {
-    default: 'Search',
-    classicon: 'i-lucide:search',
-    variant: 'secondary',
-  },
-}
-
-export const WithKeyboardShortcut: Story = {
-  args: {
-    ariaKeyshortcuts: '/',
-    default: 'Search',
-    variant: 'secondary',
-  },
-}
-
-export const Block: Story = {
-  args: {
-    block: true,
-    default: 'Full Width Button',
-  },
-}
diff --git a/app/components/Button/Base.vue b/app/components/Button/Base.vue
index f37d57be06..88464d6986 100644
--- a/app/components/Button/Base.vue
+++ b/app/components/Button/Base.vue
@@ -1,6 +1,13 @@
 <script setup lang="ts">
 import type { IconClass } from '~/types'
 
+/**
+ * A base button component that supports multiple variants, sizes, and states as well as icons and keyboard shortcuts.
+ */
+defineOptions({
+  name: 'ButtonBase',
+})
+
 const props = withDefaults(
   defineProps<{
     disabled?: boolean
diff --git a/app/components/Button/Button.stories.ts b/app/components/Button/Button.stories.ts
new file mode 100644
index 0000000000..c603c3d0bc
--- /dev/null
+++ b/app/components/Button/Button.stories.ts
@@ -0,0 +1,165 @@
+import type { Meta, StoryObj } from '@storybook-vue/nuxt'
+import ButtonBase from './Base.vue'
+import ButtonGroup from './Group.vue'
+
+const meta = {
+  component: ButtonBase,
+  subcomponents: { ButtonGroup },
+  parameters: {
+    docs: {
+      source: {
+        type: 'dynamic',
+        transform: (code: string) =>
+          code.replace(/<Base\b/g, '<ButtonBase').replace(/<\/Base>/g, '</ButtonBase>'),
+      },
+    },
+  },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
+  }),
+  tags: ['autodocs'],
+} satisfies Meta<typeof ButtonBase>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+export const Primary: Story = {
+  args: {
+    variant: 'primary',
+  },
+}
+
+export const Secondary: Story = {
+  args: {
+    variant: 'secondary',
+  },
+}
+
+export const Small: Story = {
+  args: {
+    size: 'small',
+  },
+}
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+}
+
+export const WithIcon: Story = {
+  args: {
+    classicon: 'i-lucide:search',
+  },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("search.button") }}</ButtonBase>`,
+  }),
+}
+
+export const WithKeyboardShortcut: Story = {
+  args: {
+    ariaKeyshortcuts: '/',
+  },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("search.button") }}</ButtonBase>`,
+  }),
+}
+
+export const Block: Story = {
+  args: {
+    block: true,
+  },
+}
+
+export const GroupedButtons: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `ButtonGroup` to group multiple buttons together with connected borders.',
+      },
+      source: {
+        code: `<template>
+  <ButtonGroup>
+    <ButtonBase>Back</ButtonBase>
+    <ButtonBase>Settings</ButtonBase>
+    <ButtonBase>Compare</ButtonBase>
+  </ButtonGroup>
+</template>`,
+      },
+    },
+  },
+  render: () => ({
+    components: { ButtonBase, ButtonGroup },
+    template: `
+      <ButtonGroup>
+        <ButtonBase>{{ $t('nav.back') }}</ButtonBase>
+        <ButtonBase>{{ $t('nav.settings') }}</ButtonBase>
+        <ButtonBase>{{ $t('nav.compare') }}</ButtonBase>
+      </ButtonGroup>
+    `,
+  }),
+}
+
+export const GroupedWithVariants: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `<template>
+  <ButtonGroup>
+    <ButtonBase variant="primary">Back</ButtonBase>
+    <ButtonBase variant="primary">Settings</ButtonBase>
+    <ButtonBase variant="primary">Compare</ButtonBase>
+  </ButtonGroup>
+</template>`,
+      },
+    },
+  },
+  render: () => ({
+    components: { ButtonBase, ButtonGroup },
+    template: `
+      <ButtonGroup>
+        <ButtonBase variant="primary">{{ $t('nav.back') }}</ButtonBase>
+        <ButtonBase variant="primary">{{ $t('nav.settings') }}</ButtonBase>
+        <ButtonBase variant="primary">{{ $t('nav.compare') }}</ButtonBase>
+      </ButtonGroup>
+    `,
+  }),
+}
+
+export const GroupedWithIcons: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `<template>
+  <ButtonGroup>
+    <ButtonBase variant="secondary" classicon="i-lucide:search">Search</ButtonBase>
+    <ButtonBase variant="secondary" classicon="i-lucide:x">Back</ButtonBase>
+  </ButtonGroup>
+</template>`,
+      },
+    },
+  },
+  render: () => ({
+    components: { ButtonBase, ButtonGroup },
+    template: `
+      <ButtonGroup>
+        <ButtonBase variant="secondary" classicon="i-lucide:search">{{ $t('search.button') }}</ButtonBase>
+        <ButtonBase variant="secondary" classicon="i-lucide:x">{{ $t('nav.back') }}</ButtonBase>
+      </ButtonGroup>
+    `,
+  }),
+}
diff --git a/package.json b/package.json
index 6f8ff9dae0..784de5cb53 100644
--- a/package.json
+++ b/package.json
@@ -153,6 +153,7 @@
     "schema-dts": "1.1.5",
     "simple-git-hooks": "2.13.1",
     "storybook": "catalog:storybook",
+    "storybook-i18n": "catalog:storybook",
     "typescript": "5.9.3",
     "unplugin-vue-markdown": "30.0.0",
     "vitest": "npm:@voidzero-dev/vite-plus-test@0.0.0-gd42e0ca6.20260225-0619",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index de58ba21c9..ce94ee485f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -18,6 +18,9 @@ catalogs:
     '@storybook/addon-themes':
       specifier: ^10.2.7
       version: 10.2.14
+    storybook-i18n:
+      specifier: ^10.0.3
+      version: 10.0.3
 
 overrides:
   sharp: 0.34.5
@@ -329,6 +332,9 @@ importers:
       storybook:
         specifier: ^10.2.7
         version: 10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      storybook-i18n:
+        specifier: catalog:storybook
+        version: 10.0.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
       typescript:
         specifier: 5.9.3
         version: 5.9.3
@@ -4427,6 +4433,13 @@ packages:
   '@storybook/global@5.0.0':
     resolution: {integrity: sha512-FcOqPAXACP0I3oJ/ws6/rrPT9WGhu915Cg8D02a9YxLo0DE9zI+a9A5gRGvmQ09fiWPukqI8ZAEoQEdWUKMQdQ==}
 
+  '@storybook/icons@1.6.0':
+    resolution: {integrity: sha512-hcFZIjW8yQz8O8//2WTIXylm5Xsgc+lW9ISLgUk1xGmptIJQRdlhVIXCpSyLrQaaRiyhQRaVg7l3BD9S216BHw==}
+    engines: {node: '>=14.0.0'}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta
+
   '@storybook/icons@2.0.1':
     resolution: {integrity: sha512-/smVjw88yK3CKsiuR71vNgWQ9+NuY2L+e8X7IMrFjexjm6ZR8ULrV2DRkTA61aV6ryefslzHEGDInGpnNeIocg==}
     peerDependencies:
@@ -9716,6 +9729,11 @@ packages:
     resolution: {integrity: sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==}
     engines: {node: '>= 0.4'}
 
+  storybook-i18n@10.0.3:
+    resolution: {integrity: sha512-udRoJOJfLIl83T+Vvc3Pqu1d96O9x0pnoPK0V41SnjH+UmBFggkQAovwEfMoQFmVVBPvv0rT+HjTFv9IhXQ2Yw==}
+    peerDependencies:
+      storybook: ^10.2.7
+
   storybook@10.2.13:
     resolution: {integrity: sha512-heMfJjOfbHvL+wlCAwFZlSxcakyJ5yQDam6e9k2RRArB1veJhRnsjO6lO1hOXjJYrqxfHA/ldIugbBVlCDqfvQ==}
     hasBin: true
@@ -15383,6 +15401,11 @@ snapshots:
 
   '@storybook/global@5.0.0': {}
 
+  '@storybook/icons@1.6.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+
   '@storybook/icons@2.0.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       react: 19.2.4
@@ -22355,6 +22378,14 @@ snapshots:
       es-errors: 1.3.0
       internal-slot: 1.1.0
 
+  storybook-i18n@10.0.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)):
+    dependencies:
+      '@storybook/icons': 1.6.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      storybook: 10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+    transitivePeerDependencies:
+      - react
+      - react-dom
+
   storybook@10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
       '@storybook/global': 5.0.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 015d173c7b..ea28f24115 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -46,3 +46,4 @@ catalogs:
     '@storybook/addon-docs': '^10.2.7'
     '@storybook/addon-themes': '^10.2.7'
     'storybook': '^10.2.7'
+    'storybook-i18n': '^10.0.3'

From 476316bb732b4555943d2662481a3a840e7b7577 Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Fri, 6 Mar 2026 11:11:06 -0600
Subject: [PATCH 2/8] fix: move ButtonGroup to own stories file

---
 app/components/Button/Button.stories.ts      | 125 ++++++-------------
 app/components/Button/ButtonGroup.stories.ts | 106 ++++++++++++++++
 app/components/Button/Group.vue              |   7 ++
 3 files changed, 151 insertions(+), 87 deletions(-)
 create mode 100644 app/components/Button/ButtonGroup.stories.ts

diff --git a/app/components/Button/Button.stories.ts b/app/components/Button/Button.stories.ts
index c603c3d0bc..db18a72d63 100644
--- a/app/components/Button/Button.stories.ts
+++ b/app/components/Button/Button.stories.ts
@@ -1,10 +1,8 @@
 import type { Meta, StoryObj } from '@storybook-vue/nuxt'
 import ButtonBase from './Base.vue'
-import ButtonGroup from './Group.vue'
 
 const meta = {
   component: ButtonBase,
-  subcomponents: { ButtonGroup },
   parameters: {
     docs: {
       source: {
@@ -14,43 +12,68 @@ const meta = {
       },
     },
   },
-  render: args => ({
-    components: { ButtonBase },
-    setup() {
-      return { args }
-    },
-    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
-  }),
   tags: ['autodocs'],
 } satisfies Meta<typeof ButtonBase>
 
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {}
+export const Default: Story = {
+  args: {
+    default: 'Button Text',
+  },
+}
 
 export const Primary: Story = {
   args: {
     variant: 'primary',
   },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
+  }),
 }
 
 export const Secondary: Story = {
   args: {
     variant: 'secondary',
   },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
+  }),
 }
 
 export const Small: Story = {
   args: {
     size: 'small',
   },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
+  }),
 }
 
 export const Disabled: Story = {
   args: {
     disabled: true,
   },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
+    },
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
+  }),
 }
 
 export const WithIcon: Story = {
@@ -83,83 +106,11 @@ export const Block: Story = {
   args: {
     block: true,
   },
-}
-
-export const GroupedButtons: Story = {
-  parameters: {
-    docs: {
-      description: {
-        story: 'Use `ButtonGroup` to group multiple buttons together with connected borders.',
-      },
-      source: {
-        code: `<template>
-  <ButtonGroup>
-    <ButtonBase>Back</ButtonBase>
-    <ButtonBase>Settings</ButtonBase>
-    <ButtonBase>Compare</ButtonBase>
-  </ButtonGroup>
-</template>`,
-      },
-    },
-  },
-  render: () => ({
-    components: { ButtonBase, ButtonGroup },
-    template: `
-      <ButtonGroup>
-        <ButtonBase>{{ $t('nav.back') }}</ButtonBase>
-        <ButtonBase>{{ $t('nav.settings') }}</ButtonBase>
-        <ButtonBase>{{ $t('nav.compare') }}</ButtonBase>
-      </ButtonGroup>
-    `,
-  }),
-}
-
-export const GroupedWithVariants: Story = {
-  parameters: {
-    docs: {
-      source: {
-        code: `<template>
-  <ButtonGroup>
-    <ButtonBase variant="primary">Back</ButtonBase>
-    <ButtonBase variant="primary">Settings</ButtonBase>
-    <ButtonBase variant="primary">Compare</ButtonBase>
-  </ButtonGroup>
-</template>`,
-      },
-    },
-  },
-  render: () => ({
-    components: { ButtonBase, ButtonGroup },
-    template: `
-      <ButtonGroup>
-        <ButtonBase variant="primary">{{ $t('nav.back') }}</ButtonBase>
-        <ButtonBase variant="primary">{{ $t('nav.settings') }}</ButtonBase>
-        <ButtonBase variant="primary">{{ $t('nav.compare') }}</ButtonBase>
-      </ButtonGroup>
-    `,
-  }),
-}
-
-export const GroupedWithIcons: Story = {
-  parameters: {
-    docs: {
-      source: {
-        code: `<template>
-  <ButtonGroup>
-    <ButtonBase variant="secondary" classicon="i-lucide:search">Search</ButtonBase>
-    <ButtonBase variant="secondary" classicon="i-lucide:x">Back</ButtonBase>
-  </ButtonGroup>
-</template>`,
-      },
+  render: args => ({
+    components: { ButtonBase },
+    setup() {
+      return { args }
     },
-  },
-  render: () => ({
-    components: { ButtonBase, ButtonGroup },
-    template: `
-      <ButtonGroup>
-        <ButtonBase variant="secondary" classicon="i-lucide:search">{{ $t('search.button') }}</ButtonBase>
-        <ButtonBase variant="secondary" classicon="i-lucide:x">{{ $t('nav.back') }}</ButtonBase>
-      </ButtonGroup>
-    `,
+    template: `<ButtonBase v-bind="args">{{ $t("nav.settings") }}</ButtonBase>`,
   }),
 }
diff --git a/app/components/Button/ButtonGroup.stories.ts b/app/components/Button/ButtonGroup.stories.ts
new file mode 100644
index 0000000000..6772d10925
--- /dev/null
+++ b/app/components/Button/ButtonGroup.stories.ts
@@ -0,0 +1,106 @@
+import type { Meta, StoryObj } from '@storybook-vue/nuxt'
+import ButtonBase from './Base.vue'
+import ButtonGroup from './Group.vue'
+
+const meta = {
+  component: ButtonGroup,
+  parameters: {
+    docs: {
+      source: {
+        type: 'dynamic',
+        transform: (code: string) =>
+          code
+            .replace(/<Base\b/g, '<ButtonBase')
+            .replace(/<\/Base>/g, '</ButtonBase>')
+            .replace(/<Group\b/g, '<ButtonGroup')
+            .replace(/<\/Group>/g, '</ButtonGroup>'),
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof ButtonGroup>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `
+        <template>
+            <ButtonGroup>
+                <ButtonBase>Back</ButtonBase>
+                <ButtonBase>Settings</ButtonBase>
+                <ButtonBase>Compare</ButtonBase>
+            </ButtonGroup>
+        </template>
+        `,
+      },
+    },
+  },
+  render: () => ({
+    components: { ButtonBase, ButtonGroup },
+    template: `
+      <ButtonGroup>
+        <ButtonBase>{{ $t('nav.back') }}</ButtonBase>
+        <ButtonBase>{{ $t('nav.settings') }}</ButtonBase>
+        <ButtonBase>{{ $t('nav.compare') }}</ButtonBase>
+      </ButtonGroup>
+    `,
+  }),
+}
+
+export const WithVariants: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `
+        <template>
+            <ButtonGroup>
+                <ButtonBase variant="primary">Back</ButtonBase>
+                <ButtonBase variant="primary">Settings</ButtonBase>
+                <ButtonBase variant="primary">Compare</ButtonBase>
+            </ButtonGroup>
+        </template>
+        `,
+      },
+    },
+  },
+  render: () => ({
+    components: { ButtonBase, ButtonGroup },
+    template: `
+      <ButtonGroup>
+        <ButtonBase variant="primary">{{ $t('nav.back') }}</ButtonBase>
+        <ButtonBase variant="primary">{{ $t('nav.settings') }}</ButtonBase>
+        <ButtonBase variant="primary">{{ $t('nav.compare') }}</ButtonBase>
+      </ButtonGroup>
+    `,
+  }),
+}
+
+export const WithIcons: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `
+        <template>
+            <ButtonGroup>
+                <ButtonBase variant="secondary" classicon="i-lucide:search">Search</ButtonBase>
+                <ButtonBase variant="secondary" classicon="i-lucide:x">Back</ButtonBase>
+            </ButtonGroup>
+        </template>
+        `,
+      },
+    },
+  },
+  render: () => ({
+    components: { ButtonBase, ButtonGroup },
+    template: `
+      <ButtonGroup>
+        <ButtonBase variant="secondary" classicon="i-lucide:search">{{ $t('search.button') }}</ButtonBase>
+        <ButtonBase variant="secondary" classicon="i-lucide:x">{{ $t('nav.back') }}</ButtonBase>
+      </ButtonGroup>
+    `,
+  }),
+}
diff --git a/app/components/Button/Group.vue b/app/components/Button/Group.vue
index 71f280f020..97c1723187 100644
--- a/app/components/Button/Group.vue
+++ b/app/components/Button/Group.vue
@@ -1,4 +1,11 @@
 <script setup lang="ts">
+/**
+ * Use `ButtonGroup` to group multiple buttons together with connected borders.
+ */
+defineOptions({
+  name: 'ButtonGroup',
+})
+
 const props = defineProps<{
   as?: string | Component
 }>()

From 20dd233a045ce066e11fdd563637ba39e39dd432 Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Fri, 6 Mar 2026 11:29:25 -0600
Subject: [PATCH 3/8] fix: clean up knip issues

---
 .storybook/theme.ts | 2 +-
 knip.ts             | 3 ---
 2 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/.storybook/theme.ts b/.storybook/theme.ts
index 3bb46e9677..01c0a3f81c 100644
--- a/.storybook/theme.ts
+++ b/.storybook/theme.ts
@@ -1,6 +1,6 @@
 import { create } from 'storybook/theming/create'
 
-export const npmxDark = create({
+const npmxDark = create({
   base: 'dark',
 
   brandTitle: 'npmx Storybook',
diff --git a/knip.ts b/knip.ts
index cd012608b8..515c803210 100644
--- a/knip.ts
+++ b/knip.ts
@@ -45,9 +45,6 @@ const config: KnipConfig = {
         /** Some components import types from here, but installing it directly could lead to a version mismatch */
         'vue-router',
 
-        /** Required by @nuxtjs/i18n at runtime but not directly imported in production code */
-        '@intlify/shared',
-
         /** Oxlint plugins don't get picked up yet */
         '@e18e/eslint-plugin',
         'eslint-plugin-regexp',

From ae7c4bedc9c4e79b69d1f5827fb4988c295e280d Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Fri, 6 Mar 2026 11:33:58 -0600
Subject: [PATCH 4/8] fix: move event listener

---
 .storybook/preview.ts | 20 +++++++++-----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/.storybook/preview.ts b/.storybook/preview.ts
index 1a3f4ff432..fd820f4269 100644
--- a/.storybook/preview.ts
+++ b/.storybook/preview.ts
@@ -19,6 +19,14 @@ globalThis['__NUXT_COLOR_MODE__'] ??= {
 // @ts-expect-error - dynamic global name
 globalThis.defineOgImageComponent = fn()
 
+// Subscribe to locale changes from storybook-i18n addon (once, outside decorator)
+let currentI18nInstance: any = null
+addons.getChannel().on('LOCALE_CHANGED', (newLocale: string) => {
+  if (currentI18nInstance) {
+    currentI18nInstance.setLocale(newLocale)
+  }
+})
+
 const preview: Preview = {
   parameters: {
     controls: {
@@ -81,21 +89,11 @@ const preview: Preview = {
         document.documentElement.style.removeProperty('--accent-color')
       }
 
-      // Store reference to i18n instance for locale changes
-      let i18nInstance: any = null
-
-      // Subscribe to locale changes from storybook-i18n addon
-      addons.getChannel().on('LOCALE_CHANGED', (newLocale: string) => {
-        if (i18nInstance) {
-          i18nInstance.setLocale(newLocale)
-        }
-      })
-
       return {
         template: '<story />',
         created() {
           // Store i18n instance for LOCALE_CHANGED events
-          i18nInstance = this.$i18n
+          currentI18nInstance = this.$i18n
 
           // Set initial locale when component is created
           if (locale && this.$i18n) {

From d4c440412cf8c2070d5227ca77388f37a56421bc Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Fri, 6 Mar 2026 11:54:11 -0600
Subject: [PATCH 5/8] fix: move Button stories to ButtonBase

---
 .../Button/{Button.stories.ts => ButtonBase.stories.ts}           | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename app/components/Button/{Button.stories.ts => ButtonBase.stories.ts} (100%)

diff --git a/app/components/Button/Button.stories.ts b/app/components/Button/ButtonBase.stories.ts
similarity index 100%
rename from app/components/Button/Button.stories.ts
rename to app/components/Button/ButtonBase.stories.ts

From 4c8e9d537a1b865a3c944ade6cbba95cdcbe7c5b Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Fri, 6 Mar 2026 11:58:18 -0600
Subject: [PATCH 6/8] fix: revert knip.ts changes

---
 knip.ts | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/knip.ts b/knip.ts
index 515c803210..8d3abe1408 100644
--- a/knip.ts
+++ b/knip.ts
@@ -45,6 +45,9 @@ const config: KnipConfig = {
         /** Some components import types from here, but installing it directly could lead to a version mismatch */
         'vue-router',
 
+        /** Required by @nuxtjs/i18n at runtime but not directly imported in production code */
+        '@intlify/shared',
+
         /** Oxlint plugins don't get picked up yet */
         '@e18e/eslint-plugin',
         'eslint-plugin-regexp',
@@ -59,7 +62,14 @@ const config: KnipConfig = {
     },
     'docs': {
       entry: ['app/**/*.{ts,vue,css}'],
-      ignoreDependencies: ['docus', 'better-sqlite3', '@nuxtjs/mdc', 'nuxt!'],
+      ignoreDependencies: [
+        'docus',
+        'better-sqlite3',
+        '@nuxtjs/mdc',
+        'nuxt!',
+        '@nuxt/ui',
+        'tailwindcss',
+      ],
     },
   },
 }

From a923dd3070a91723221390bf22cc9f0b87e98f2b Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Tue, 10 Mar 2026 12:13:15 -0500
Subject: [PATCH 7/8] fix: bump storybook-i18n to 10.1.1 to resolve provenance

---
 pnpm-lock.yaml      | 26 +++++++-------------------
 pnpm-workspace.yaml |  2 +-
 2 files changed, 8 insertions(+), 20 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ce94ee485f..79585221ee 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -19,8 +19,8 @@ catalogs:
       specifier: ^10.2.7
       version: 10.2.14
     storybook-i18n:
-      specifier: ^10.0.3
-      version: 10.0.3
+      specifier: ^10.1.1
+      version: 10.1.1
 
 overrides:
   sharp: 0.34.5
@@ -334,7 +334,7 @@ importers:
         version: 10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       storybook-i18n:
         specifier: catalog:storybook
-        version: 10.0.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
+        version: 10.1.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
       typescript:
         specifier: 5.9.3
         version: 5.9.3
@@ -4433,13 +4433,6 @@ packages:
   '@storybook/global@5.0.0':
     resolution: {integrity: sha512-FcOqPAXACP0I3oJ/ws6/rrPT9WGhu915Cg8D02a9YxLo0DE9zI+a9A5gRGvmQ09fiWPukqI8ZAEoQEdWUKMQdQ==}
 
-  '@storybook/icons@1.6.0':
-    resolution: {integrity: sha512-hcFZIjW8yQz8O8//2WTIXylm5Xsgc+lW9ISLgUk1xGmptIJQRdlhVIXCpSyLrQaaRiyhQRaVg7l3BD9S216BHw==}
-    engines: {node: '>=14.0.0'}
-    peerDependencies:
-      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta
-      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0-beta
-
   '@storybook/icons@2.0.1':
     resolution: {integrity: sha512-/smVjw88yK3CKsiuR71vNgWQ9+NuY2L+e8X7IMrFjexjm6ZR8ULrV2DRkTA61aV6ryefslzHEGDInGpnNeIocg==}
     peerDependencies:
@@ -9729,8 +9722,8 @@ packages:
     resolution: {integrity: sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==}
     engines: {node: '>= 0.4'}
 
-  storybook-i18n@10.0.3:
-    resolution: {integrity: sha512-udRoJOJfLIl83T+Vvc3Pqu1d96O9x0pnoPK0V41SnjH+UmBFggkQAovwEfMoQFmVVBPvv0rT+HjTFv9IhXQ2Yw==}
+  storybook-i18n@10.1.1:
+    resolution: {integrity: sha512-A2cFaGCysU2VkjDQUFY0aQsppAFIhZU3Tx38/NYLhWShTRkUpE3huGHP59CAgArxLQEzEjLmieiTSuNT2bwA4Q==}
     peerDependencies:
       storybook: ^10.2.7
 
@@ -15401,11 +15394,6 @@ snapshots:
 
   '@storybook/global@5.0.0': {}
 
-  '@storybook/icons@1.6.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
-    dependencies:
-      react: 19.2.4
-      react-dom: 19.2.4(react@19.2.4)
-
   '@storybook/icons@2.0.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       react: 19.2.4
@@ -22378,9 +22366,9 @@ snapshots:
       es-errors: 1.3.0
       internal-slot: 1.1.0
 
-  storybook-i18n@10.0.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)):
+  storybook-i18n@10.1.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)):
     dependencies:
-      '@storybook/icons': 1.6.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@storybook/icons': 2.0.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       storybook: 10.2.13(@testing-library/dom@10.4.1)(prettier@3.8.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
     transitivePeerDependencies:
       - react
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index ea28f24115..2e6669e4e0 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -46,4 +46,4 @@ catalogs:
     '@storybook/addon-docs': '^10.2.7'
     '@storybook/addon-themes': '^10.2.7'
     'storybook': '^10.2.7'
-    'storybook-i18n': '^10.0.3'
+    'storybook-i18n': '^10.1.1'

From 51ec2db1acb3097dadccc3a0c0244a15954d10f5 Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Wed, 11 Mar 2026 08:02:22 -0500
Subject: [PATCH 8/8] fix: pr comments

---
 app/components/Button/ButtonGroup.stories.ts | 6 +++---
 knip.ts                                      | 9 +--------
 2 files changed, 4 insertions(+), 11 deletions(-)

diff --git a/app/components/Button/ButtonGroup.stories.ts b/app/components/Button/ButtonGroup.stories.ts
index 6772d10925..7dbddccaab 100644
--- a/app/components/Button/ButtonGroup.stories.ts
+++ b/app/components/Button/ButtonGroup.stories.ts
@@ -86,8 +86,8 @@ export const WithIcons: Story = {
         code: `
         <template>
             <ButtonGroup>
+                <ButtonBase variant="secondary" classicon="i-lucide:x">Close</ButtonBase>
                 <ButtonBase variant="secondary" classicon="i-lucide:search">Search</ButtonBase>
-                <ButtonBase variant="secondary" classicon="i-lucide:x">Back</ButtonBase>
             </ButtonGroup>
         </template>
         `,
@@ -98,8 +98,8 @@ export const WithIcons: Story = {
     components: { ButtonBase, ButtonGroup },
     template: `
       <ButtonGroup>
-        <ButtonBase variant="secondary" classicon="i-lucide:search">{{ $t('search.button') }}</ButtonBase>
-        <ButtonBase variant="secondary" classicon="i-lucide:x">{{ $t('nav.back') }}</ButtonBase>
+        <ButtonBase variant="secondary" classicon="i-lucide:x">{{ $t('common.close') }}</ButtonBase>
+        <ButtonBase variant="secondary" classicon="i-lucide:search">{{ $t('filters.search') }}</ButtonBase>
       </ButtonGroup>
     `,
   }),
diff --git a/knip.ts b/knip.ts
index 8d3abe1408..cd012608b8 100644
--- a/knip.ts
+++ b/knip.ts
@@ -62,14 +62,7 @@ const config: KnipConfig = {
     },
     'docs': {
       entry: ['app/**/*.{ts,vue,css}'],
-      ignoreDependencies: [
-        'docus',
-        'better-sqlite3',
-        '@nuxtjs/mdc',
-        'nuxt!',
-        '@nuxt/ui',
-        'tailwindcss',
-      ],
+      ignoreDependencies: ['docus', 'better-sqlite3', '@nuxtjs/mdc', 'nuxt!'],
     },
   },
 }