@brumaombra/ui-vintage 0.7.13 → 0.8.0

package/README.md

@@ -85,8 +85,9 @@ This is a Nuxt library, not a generic Vue component bundle. Components rely on N
 - Vue 3 components built with Composition API and TypeScript source.
 - Primitive UI controls based on Reka UI where accessible behavior is required.
 - Reusable dashboard, landing, blog, card, field, and data-display components.
-- Built-in busy, confirm-dialog, message-dialog, and message-toast flows.
-- Theme selector with light, dark, and automatic system modes.
+- Built-in busy, confirm-dialog, message-dialog, and stacked, swipeable message-toast flows.
+- A spring-based motion system (pure CSS `linear()` easings) that respects `prefers-reduced-motion`.
+- Theme selector with light, dark, and automatic modes and a circular View Transitions reveal.
 - Library locale messages merged into an existing Vue I18n instance when available.
 - Automatic `@nuxt/image` installation for components that use `NuxtImg`.
 - Source publishing with no required library build step before installation.
@@ -190,11 +191,10 @@ const confirmed = await showConfirmDialog({
 });
 
 if (confirmed) {
-    // Keep the shared loading state visible while the request is running
-    setBusy({
-        title: 'Deleting project',
-        description: 'Please wait while the project is removed.'
-    });
+    // Keep the shared loading overlay visible while the request is running
+    setBusy(true, { label: 'Deleting project...' });
+    await deleteProject();
+    setBusy(false);
 }
 ```
 
@@ -231,7 +231,7 @@ The package exposes components through explicit subpaths. The complete public ex
 
 ### 🎛️ UI primitives
 
-`alert`, `alert-dialog`, `accordion`, `badge`, `breadcrumb`, `button`, `calendar`, `card`, `command`, `dialog`, `field`, `input`, `label`, `popover`, `progress`, `scroll-area`, `select`, `separator`, `sheet`, `sidebar`, `skeleton`, `slider`, `switch`, `table`, `tabs`, `textarea`, `time-picker`, and `tooltip`.
+`alert`, `alert-dialog`, `accordion`, `animated-number`, `avatar`, `badge`, `breadcrumb`, `button`, `calendar`, `card`, `checkbox`, `collapsible`, `combobox`, `command`, `data-table`, `date-picker`, `date-time-picker`, `dialog`, `dropdown-menu`, `field`, `file-dropzone`, `hover-card`, `input`, `kbd`, `label`, `native-select`, `number-field`, `pagination`, `pin-input`, `popover`, `progress`, `radio-group`, `scroll-area`, `select`, `separator`, `sheet`, `sidebar`, `skeleton`, `slider`, `spinner`, `stepper`, `switch`, `table`, `tabs`, `tags-input`, `textarea`, `time-picker`, `toggle-group`, and `tooltip`.
 
 ### 🧱 Composite components
 
@@ -241,10 +241,49 @@ The package exposes components through explicit subpaths. The complete public ex
 
 `busy`, `busy-indicator`, `confirm-dialog`, `message-dialog`, `message-toast`, `language-flag`, `language-selector`, `blog`, `content`, and `utils`.
 
+### 📚 Component catalog
+
+[`COMPONENTS.md`](COMPONENTS.md) lists every entry point with its import line, components, props and defaults, events, slots, helpers, and usage examples. It is generated from the source and ships inside the package, so apps can always read the version they installed at `node_modules/@brumaombra/ui-vintage/COMPONENTS.md`.
+
+Regenerate it after changing a public API, adding an entry point, or editing `scripts/components-meta.mjs`:
+
+```bash
+# Rewrite COMPONENTS.md from the source
+npm run docs:components
+
+# Fail when COMPONENTS.md is out of date (runs in the publish workflow)
+npm run docs:components:check
+```
+
+New entry points need a description and category in `scripts/components-meta.mjs`; the generator fails until they have one.
+
+### 🤖 AI assistant skill
+
+The package also ships a skill that teaches coding assistants to reuse UI Vintage and to read the catalog before writing UI. To enable it in a consuming app with Claude Code, copy it into the app's skills directory:
+
+```bash
+# Copy the skill shipped with the installed version
+mkdir -p .claude/skills
+cp -r node_modules/@brumaombra/ui-vintage/skills/ui-vintage .claude/skills/
+```
+
+The skill only points to `COMPONENTS.md`, so it stays valid when you update the package. Copy it again only when the skill itself changes.
+
+### 🎬 Motion system
+
+`src/styles.css` ships a small motion vocabulary that every component uses and that apps can reuse:
+
+- Easing utilities: `ease-spring`, `ease-bounce`, `ease-out-expo`, and `ease-snappy`.
+- Surface utilities: `uv-floating-motion` (popovers, menus, tooltips), `uv-modal-motion`, `uv-overlay-motion`, `uv-collapsible-motion`, and `uv-field` (focus glow and invalid states for inputs).
+- Animations: `animate-uv-pop`, `animate-uv-fade-up`, `animate-uv-shake`, `animate-uv-shimmer`, `animate-uv-float`, and `animate-uv-ping-soft`.
+- Elevation: `shadow-elevated-sm` through `shadow-elevated-xl`, plus `shadow-glow`.
+
+All durations collapse automatically when the user prefers reduced motion. Tailwind v4 animates `scale`, `rotate`, and `translate` as individual properties, so list those names (not `transform`) in custom transitions.
+
 <a id="demo-app"></a>
 ## 🖥️ Demo App
 
-The private `demo-app/` directory is a Nuxt 4 showcase for manual verification. It demonstrates the public components, shared theme behavior, responsive layouts, form states, dialogs, toasts, tabs, accordions, localization, and dashboard composition.
+The private `demo-app/` directory is a Nuxt 4 documentation-style showcase for manual verification. It is organized by category (Foundations, Actions, Forms, Data display, Navigation, Overlays, Feedback, Layouts), shows every component with a live preview and a copyable code tab, includes a live mini-app on the overview page, and has a global command palette (`Ctrl/⌘ + K`) to jump to any section. The navigation model lives in `demo-app/app/utils/demo-navigation.ts`.
 
 The demo app is not part of the published package and is not intended to be installed by consumers. It imports the package through `file:..`, so it exercises the same source that is published to npm.
 
@@ -309,6 +348,7 @@ UI Vintage publishes the Nuxt module entrypoint and source files directly:
 - `module.mjs` is the package entrypoint registered by Nuxt.
 - `src/` contains the published components, styles, helpers, locale messages, and runtime plugin.
 - `package.json` defines the public component subpath exports.
+- `COMPONENTS.md` and `skills/` ship the generated component catalog and the AI assistant skill.
 - `dist/` is generated repository output and is not the source of truth for consumers.
 
 There is no required library build step before publishing. The normal verification command is:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@brumaombra/ui-vintage",
-    "version": "0.7.13",
+    "version": "0.8.0",
     "description": "Source-published Nuxt UI runtime with shared theme tokens and built-in Nuxt integrations.",
     "private": false,
     "author": "Mauro Brambilla",
@@ -28,41 +28,53 @@
     },
     "files": [
         "src",
-        "module.mjs"
+        "module.mjs",
+        "COMPONENTS.md",
+        "skills"
     ],
     "exports": {
         ".": {
             "import": "./module.mjs"
         },
         "./style.css": "./src/styles.css",
+        "./accordion": "./src/components/ui/accordion/index.ts",
         "./alert": "./src/components/ui/alert/index.ts",
         "./alert-dialog": "./src/components/ui/alert-dialog/index.ts",
-        "./accordion": "./src/components/ui/accordion/index.ts",
+        "./animated-number": "./src/components/ui/animated-number/index.ts",
+        "./avatar": "./src/components/ui/avatar/index.ts",
         "./background-grid": "./src/components/background-grid/index.ts",
         "./badge": "./src/components/ui/badge/index.ts",
         "./blog": "./src/components/blog/index.ts",
+        "./breadcrumb": "./src/components/ui/breadcrumb/index.ts",
         "./busy": "./src/components/ui/busy/index.ts",
         "./busy-indicator": "./src/components/busy-indicator/index.ts",
-        "./breadcrumb": "./src/components/ui/breadcrumb/index.ts",
         "./button": "./src/components/ui/button/index.ts",
         "./calendar": "./src/components/ui/calendar/index.ts",
         "./card": "./src/components/ui/card/index.ts",
         "./card-grid": "./src/components/card-grid/index.ts",
+        "./checkbox": "./src/components/ui/checkbox/index.ts",
         "./chip": "./src/components/chip/index.ts",
+        "./collapsible": "./src/components/ui/collapsible/index.ts",
+        "./combobox": "./src/components/ui/combobox/index.ts",
         "./command": "./src/components/ui/command/index.ts",
+        "./common-types": "./src/lib/common-types.ts",
         "./confirm-dialog": "./src/components/confirm-dialog/index.ts",
         "./content": "./src/components/content/index.ts",
         "./dashboard-shell": "./src/components/dashboard-shell/index.ts",
         "./data-list": "./src/components/data-list/index.ts",
+        "./data-table": "./src/components/ui/data-table/index.ts",
         "./date-picker": "./src/components/ui/date-picker/index.ts",
         "./date-time-picker": "./src/components/ui/date-time-picker/index.ts",
         "./dialog": "./src/components/ui/dialog/index.ts",
+        "./dropdown-menu": "./src/components/ui/dropdown-menu/index.ts",
         "./empty-state-card": "./src/components/empty-state-card/index.ts",
         "./error-page": "./src/components/error-page/index.ts",
         "./field": "./src/components/ui/field/index.ts",
+        "./file-dropzone": "./src/components/ui/file-dropzone/index.ts",
+        "./hover-card": "./src/components/ui/hover-card/index.ts",
         "./info-card": "./src/components/info-card/index.ts",
-        "./common-types": "./src/lib/common-types.ts",
         "./input": "./src/components/ui/input/index.ts",
+        "./kbd": "./src/components/ui/kbd/index.ts",
         "./label": "./src/components/ui/label/index.ts",
         "./landing": "./src/components/landing/index.ts",
         "./landing-content": "./src/components/landing/landing-content/index.ts",
@@ -76,10 +88,14 @@
         "./message-dialog": "./src/components/message-dialog/index.ts",
         "./message-toast": "./src/components/message-toast/index.ts",
         "./native-select": "./src/components/ui/native-select/index.ts",
+        "./number-field": "./src/components/ui/number-field/index.ts",
         "./page-header": "./src/components/page-header/index.ts",
+        "./pagination": "./src/components/ui/pagination/index.ts",
+        "./pin-input": "./src/components/ui/pin-input/index.ts",
         "./popover": "./src/components/ui/popover/index.ts",
         "./progress": "./src/components/ui/progress/index.ts",
         "./progress-component": "./src/components/progress-component/index.ts",
+        "./radio-group": "./src/components/ui/radio-group/index.ts",
         "./scroll-area": "./src/components/ui/scroll-area/index.ts",
         "./select": "./src/components/ui/select/index.ts",
         "./separator": "./src/components/ui/separator/index.ts",
@@ -89,14 +105,18 @@
         "./skeleton": "./src/components/ui/skeleton/index.ts",
         "./slider": "./src/components/ui/slider/index.ts",
         "./slider-form-component": "./src/components/slider-form-component/index.ts",
+        "./spinner": "./src/components/ui/spinner/index.ts",
+        "./stepper": "./src/components/ui/stepper/index.ts",
         "./switch": "./src/components/ui/switch/index.ts",
         "./switch-form-component": "./src/components/switch-form-component/index.ts",
         "./table": "./src/components/ui/table/index.ts",
         "./tabs": "./src/components/ui/tabs/index.ts",
+        "./tags-input": "./src/components/ui/tags-input/index.ts",
         "./text-link": "./src/components/text-link/index.ts",
         "./textarea": "./src/components/ui/textarea/index.ts",
         "./theme-selector": "./src/components/theme-selector/index.ts",
         "./time-picker": "./src/components/ui/time-picker/index.ts",
+        "./toggle-group": "./src/components/ui/toggle-group/index.ts",
         "./tooltip": "./src/components/ui/tooltip/index.ts",
         "./utils": "./src/lib/utils.ts"
     },
@@ -104,7 +124,9 @@
         "**/*.css"
     ],
     "scripts": {
-        "typecheck": "vue-tsc --noEmit"
+        "typecheck": "vue-tsc --noEmit",
+        "docs:components": "node scripts/generate-components-doc.mjs",
+        "docs:components:check": "node scripts/generate-components-doc.mjs --check"
     },
     "peerDependencies": {
         "@nuxt/image": "^2.0.0",
@@ -123,8 +145,7 @@
         "reka-ui": "2.9.2",
         "shiki": "4.4.3",
         "tailwind-merge": "3.5.0",
-        "tailwindcss": "4.2.4",
-        "tw-animate-css": "1.4.0"
+        "tailwindcss": "4.2.4"
     },
     "devDependencies": {
         "@types/node": "24.0.0",

package/skills/ui-vintage/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ui-vintage
+description: Build Nuxt UI with the @brumaombra/ui-vintage component library. Use whenever creating or changing pages, layouts, forms, tables, dialogs, toasts, or any other UI in an app that depends on @brumaombra/ui-vintage, before writing custom components or styles.
+---
+
+# UI Vintage
+
+This app uses `@brumaombra/ui-vintage`, a Nuxt component library with its own design tokens, motion system, and runtime flows. Reuse it instead of building UI from scratch.
+
+## 1. Read the catalog first
+
+The complete, version-matched API reference is installed with the package:
+
+`node_modules/@brumaombra/ui-vintage/COMPONENTS.md`
+
+Search it (for example for `### \`@brumaombra/ui-vintage/`, a component name, or a prop) instead of reading it top to bottom. It lists every entry point with its import line, components, props and defaults, events, slots, helpers, and usage examples. Never guess prop names: check them there.
+
+## 2. Choose the component
+
+- Before writing a custom component, check the catalog's Contents list. Common mappings:
+  - Searchable select → `combobox` (`ComboboxSelect`); plain select → `select`.
+  - Table with sorting or selection → `data-table`; KPI tiles → `single-value-card`.
+  - Confirmation → `showConfirmDialog` (`confirm-dialog`); notification → `showMessageToast` (`message-toast`); blocking load → `setBusy` (`busy-indicator`). These mount themselves, so do not add them to the template.
+  - App layout with sidebar → `dashboard-shell`; marketing or blog layout → `landing`.
+  - Empty and loading placeholders → `empty-state-card`, `loading-state-card`, `skeleton`.
+- Only build something new when no entry point fits, and compose it from library primitives (`card`, `button`, `field`, ...).
+
+## 3. Follow the library conventions
+
+- Import from explicit subpaths: `import { Button } from '@brumaombra/ui-vintage/button'`. Never import from `@brumaombra/ui-vintage/src/...`.
+- Style with the semantic tokens (`bg-card`, `bg-surface`, `bg-accent`, `bg-primary`, `text-muted-foreground`, `border-border`, `border-border-strong`, ...). They adapt to dark mode, so do not write `dark:` color variants or hard-coded colors for surfaces and text.
+- Customize components through their props and the `class` prop (merged with tailwind-merge) rather than wrapping them in extra styled elements.
+- For motion, reuse the library utilities (`ease-spring`, `ease-out-expo`, `animate-uv-fade-up`, `animate-uv-pop`, `uv-floating-motion`, `shadow-elevated-*`). In custom transitions, name `scale`, `rotate`, and `translate` explicitly; Tailwind v4 does not animate them through `transform`.
+- Icons are Hugeicons definitions: import from `@hugeicons/core-free-icons` and pass them to `:icon` props, or render them with `HugeiconsIcon` from `@hugeicons/vue`.
+- Form controls use `v-model`. Mark invalid fields with `aria-invalid` and show messages with `FieldError`.
+- Library strings are translated through vue-i18n (`uiVintage.*` keys). App copy belongs in the app's own locale files.
+
+## 4. Check your work
+
+- Every import path you used appears as an entry point in `COMPONENTS.md`.
+- Every prop and event you used appears in that component's table.
+- No new CSS reimplements something a component or token already provides.

package/src/components/blog/BlogFAQSection.vue

@@ -24,14 +24,14 @@ const hasValidFAQs = computed(() => props.faqs && props.faqs.length > 0);
         <BlogSectionTitle :title="t('uiVintage.blog.faq.title')" />
 
         <!-- Description -->
-        <p class="text-base md:text-lg text-(--text-secondary-light) dark:text-(--text-secondary-dark) mb-8">
+        <p class="text-base md:text-lg text-muted-foreground mb-8">
             {{ t('uiVintage.blog.faq.description') }}
         </p>
 
         <!-- FAQ Items -->
         <div class="space-y-4">
             <Accordion v-for="(faq, index) in props.faqs" :key="index" :title="faq.question" :initially-expanded="index === 0">
-                <p class="text-xs md:text-sm text-(--text-secondary-light) dark:text-(--text-secondary-dark) leading-relaxed">
+                <p class="text-xs md:text-sm text-muted-foreground leading-relaxed">
                     {{ faq.answer }}
                 </p>
             </Accordion>

package/src/components/blog/BlogHeaderSection.vue

@@ -26,12 +26,12 @@ const props = withDefaults(defineProps<{
         </div>
 
         <!-- Title -->
-        <h1 class="text-3xl md:text-6xl font-bold text-(--text-primary-light) dark:text-(--text-primary-dark) leading-tight">
+        <h1 class="text-3xl md:text-6xl font-bold text-foreground leading-tight">
             {{ props.title }}
         </h1>
 
         <!-- Description -->
-        <p class="text-sm md:text-xl text-(--text-secondary-light) dark:text-(--text-secondary-dark) leading-relaxed">
+        <p class="text-sm md:text-xl text-muted-foreground leading-relaxed">
             {{ props.description }}
         </p>
     </div>

package/src/components/blog/BlogInfoSection.vue

@@ -38,8 +38,8 @@ const formattedModifiedDate = computed(() => formatDateLongItalyTimezone(props.d
 
                         <!-- Author name -->
                         <div>
-                            <p class="text-sm text-(--text-secondary-light) dark:text-(--text-secondary-dark)">{{ t('uiVintage.blog.author') }}</p>
-                            <p class="font-bold text-(--text-primary-light) dark:text-(--text-primary-dark)">
+                            <p class="text-sm text-muted-foreground">{{ t('uiVintage.blog.author') }}</p>
+                            <p class="font-bold text-foreground">
                                 <NuxtLink :to="props.authorUrl" target="_blank" rel="noopener noreferrer" class="hover:underline">
                                     {{ props.author }}
                                 </NuxtLink>
@@ -49,7 +49,7 @@ const formattedModifiedDate = computed(() => formatDateLongItalyTimezone(props.d
                 </div>
 
                 <!-- Date information -->
-                <div class="flex flex-col sm:items-end text-xs md:text-sm text-(--text-secondary-light) dark:text-(--text-secondary-dark)">
+                <div class="flex flex-col sm:items-end text-xs md:text-sm text-muted-foreground">
                     <!-- Published date -->
                     <div v-if="props.datePublished" class="mb-1">
                         <span class="font-semibold">{{ t('uiVintage.blog.publishedDate') }}:</span>

package/src/components/blog/BlogProgressBar.vue

@@ -1,16 +1,17 @@
 <script setup lang="ts">
-import { onMounted, onUnmounted, ref } from 'vue';
+import { computed, onMounted, onUnmounted, ref } from 'vue';
 import type { HTMLAttributes } from 'vue';
+import { useI18n } from 'vue-i18n';
 import { cn } from '../../lib/utils';
 
 // Props
-const props = withDefaults(defineProps<{
+const props = defineProps<{
     class?: HTMLAttributes['class'];
     ariaLabel?: string;
-}>(), {
-    ariaLabel: 'Reading progress'
-});
+}>();
 
+const { t } = useI18n();
+const resolvedAriaLabel = computed(() => props.ariaLabel || t('uiVintage.blog.readingProgress'));
 const progress = ref(0);
 let animationFrame = 0;
 
@@ -44,7 +45,7 @@ onUnmounted(() => {
 <template>
     <div :class="cn('relative h-1 w-full border-t border-(--border-light) bg-(--bg-selected-light) dark:border-(--border-dark) dark:bg-(--bg-selected-dark) landing-navbar-progress', props.class)"
         role="progressbar"
-        :aria-label="props.ariaLabel"
+        :aria-label="resolvedAriaLabel"
         aria-valuemin="0"
         aria-valuemax="100"
         :aria-valuenow="Math.round(progress)">

package/src/components/blog/BlogSectionTitle.vue

@@ -6,7 +6,7 @@ const props = defineProps<{
 </script>
 
 <template>
-    <h2 class="text-xl md:text-2xl font-bold text-(--text-primary-light) dark:text-(--text-primary-dark) mb-5">
+    <h2 class="text-xl md:text-2xl font-bold text-foreground mb-5">
         {{ props.title }}
     </h2>
 </template>

package/src/components/blog/BlogTagsSection.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import { Badge } from '../ui/badge';
+
+// Props
+const props = withDefaults(defineProps<{
+    tags?: Array<{
+        name: string;
+        slug: string;
+        count: number;
+    }>;
+}>(), {
+    tags: () => []
+});
+</script>
+
+<template>
+    <div v-if="props.tags.length" class="flex flex-wrap gap-3">
+        <NuxtLinkLocale v-for="(tag, index) in props.tags" :key="tag.slug" :to="`/blog/tags/${tag.slug}`" data-aos="fade-up" :data-aos-delay="Math.min(index * 100, 500)">
+            <Badge color="gray" :text="`${tag.name} (${tag.count})`" class="transition-transform duration-200 ease-out hover:scale-105 motion-reduce:transition-none motion-reduce:hover:scale-100" />
+        </NuxtLinkLocale>
+    </div>
+</template>

package/src/components/blog/CategoryCard.vue

@@ -24,7 +24,7 @@ const props = withDefaults(defineProps<{
             <!-- Content -->
             <div class="p-4 flex items-center justify-between">
                 <!-- Name -->
-                <span class="text-sm font-bold text-(--text-primary-light) dark:text-(--text-primary-dark) truncate mr-3">
+                <span class="text-sm font-bold text-foreground truncate mr-3">
                     {{ props.name }}
                 </span>
 

package/src/components/blog/HeaderCarousel.vue

@@ -100,13 +100,13 @@ onUnmounted(() => {
 
                                 <!-- Title -->
                                 <NuxtLink :to="post.path">
-                                    <h3 class="text-base md:text-3xl font-bold text-(--text-primary-light) dark:text-(--text-primary-dark) mb-3 line-clamp-2 hover:opacity-75 transition-opacity duration-200">
+                                    <h3 class="text-base md:text-3xl font-bold text-foreground mb-3 line-clamp-2 hover:opacity-75 transition-opacity duration-200">
                                         {{ post.title }}
                                     </h3>
                                 </NuxtLink>
 
                                 <!-- Description -->
-                                <p class="text-xs md:text-base! text-(--text-secondary-light) dark:text-(--text-secondary-dark) mb-6 line-clamp-2 leading-relaxed">
+                                <p class="text-xs md:text-base! text-muted-foreground mb-6 line-clamp-2 leading-relaxed">
                                     {{ post.description }}
                                 </p>
 
@@ -144,16 +144,16 @@ onUnmounted(() => {
         <button v-if="props.featuredPosts.length > 1"
             @click="prevSlide"
             :aria-label="t('uiVintage.blog.previousSlide')"
-            class="absolute left-2 top-[calc(50%-4rem)] -translate-y-1/2 z-10 border border-(--border-light) dark:border-(--border-dark) bg-(--bg-card-light) dark:bg-(--bg-card-dark) px-3 py-3 rounded-[3px] transition-colors duration-200 hover:border-(--border-hover-light) dark:hover:border-(--border-hover-dark) cursor-pointer">
-            <HugeiconsIcon :icon="ArrowLeft01Icon" class="size-4 text-(--text-secondary-light) dark:text-(--text-secondary-dark)" />
+            class="absolute left-2 top-[calc(50%-4rem)] -translate-y-1/2 z-10 border border-border bg-card px-3 py-3 rounded-[3px] transition-colors duration-200 hover:border-border-strong cursor-pointer">
+            <HugeiconsIcon :icon="ArrowLeft01Icon" class="size-4 text-muted-foreground" />
         </button>
 
         <!-- Next slide -->
         <button v-if="props.featuredPosts.length > 1"
             @click="nextSlide"
             :aria-label="t('uiVintage.blog.nextSlide')"
-            class="absolute right-2 top-[calc(50%-4rem)] -translate-y-1/2 z-10 border border-(--border-light) dark:border-(--border-dark) bg-(--bg-card-light) dark:bg-(--bg-card-dark) px-3 py-3 rounded-[3px] transition-colors duration-200 hover:border-(--border-hover-light) dark:hover:border-(--border-hover-dark) cursor-pointer">
-            <HugeiconsIcon :icon="ArrowRight01Icon" class="size-4 text-(--text-secondary-light) dark:text-(--text-secondary-dark)" />
+            class="absolute right-2 top-[calc(50%-4rem)] -translate-y-1/2 z-10 border border-border bg-card px-3 py-3 rounded-[3px] transition-colors duration-200 hover:border-border-strong cursor-pointer">
+            <HugeiconsIcon :icon="ArrowRight01Icon" class="size-4 text-muted-foreground" />
         </button>
     </div>
 </template>

package/src/components/blog/PostCard.vue

@@ -39,12 +39,12 @@ const props = withDefaults(defineProps<{
                 </div>
 
                 <!-- Post Title -->
-                <h2 class="text-base font-bold text-(--text-primary-light) dark:text-(--text-primary-dark) mb-2 line-clamp-2">
+                <h2 class="text-base font-bold text-foreground mb-2 line-clamp-2">
                     {{ props.title }}
                 </h2>
 
                 <!-- Post Description -->
-                <p class="text-xs md:text-sm text-(--text-secondary-light) dark:text-(--text-secondary-dark) leading-relaxed mb-4 line-clamp-3 grow">
+                <p class="text-xs md:text-sm text-muted-foreground leading-relaxed mb-4 line-clamp-3 grow">
                     {{ props.description }}
                 </p>
 

package/src/components/blog/SocialShareSidebar.vue

@@ -59,7 +59,7 @@ const socialPlatforms = computed(() => {
             <Card class="p-5! flex flex-col space-y-4 items-center">
                 <CardContent class="p-0! gap-4 items-center">
                     <!-- Share icon -->
-                    <HugeiconsIcon :icon="Share08Icon" class="size-5 text-(--text-secondary-light) dark:text-(--text-secondary-dark) mb-2" />
+                    <HugeiconsIcon :icon="Share08Icon" class="size-5 text-muted-foreground mb-2" />
 
                     <!-- Social share links (desktop) -->
                     <template v-for="platform in socialPlatforms" :key="platform.name">

package/src/components/blog/TableOfContents.vue

@@ -286,18 +286,18 @@ const openMobileToc = () => {
 // Get classes for heading button
 const getHeadingButtonClasses = (level: number, isActive: boolean) => {
     // Base classes for all titles
-    const baseClasses = 'block w-full text-left px-2.5 py-2 md:px-3 md:py-2 rounded border-l-2 border-transparent transition-all duration-200 hover:bg-(--bg-selected-light) dark:hover:bg-(--bg-selected-dark) cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 motion-reduce:transition-none';
+    const baseClasses = 'block w-full text-left px-2.5 py-2 md:px-3 md:py-2 rounded border-l-2 border-transparent transition-all duration-200 hover:bg-accent cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 motion-reduce:transition-none';
 
     // Add classes based on heading level
     let levelClasses = '';
     if (level === 2) {
-        levelClasses = 'text-(--text-primary-light) dark:text-(--text-primary-dark) font-semibold text-xs md:text-sm';
+        levelClasses = 'text-foreground font-semibold text-xs md:text-sm';
     } else {
-        levelClasses = 'text-(--text-secondary-light) dark:text-(--text-secondary-dark) pl-6! text-xs md:text-sm';
+        levelClasses = 'text-muted-foreground pl-6! text-xs md:text-sm';
     }
 
     // Add classes if the heading is active
-    const activeClasses = isActive ? 'bg-(--bg-selected-light) dark:bg-(--bg-selected-dark) border-l-primary text-(--text-primary-light) dark:text-(--text-primary-dark)' : '';
+    const activeClasses = isActive ? 'bg-accent border-l-primary text-foreground' : '';
 
     // Return combined classes
     return [baseClasses, levelClasses, activeClasses];
@@ -367,12 +367,12 @@ onUnmounted(() => {
                         <div class="flex min-w-0 items-center gap-3">
                             <!-- Mobile table of contents icon -->
                             <div class="flex h-10 w-10 shrink-0 items-center justify-center rounded border border-(--border-light) bg-(--bg-card-light) dark:border-(--border-dark) dark:bg-(--bg-card-dark)">
-                                <HugeiconsIcon :icon="Bookmark01Icon" class="size-4 text-(--text-secondary-light) dark:text-(--text-secondary-dark)" />
+                                <HugeiconsIcon :icon="Bookmark01Icon" class="size-4 text-muted-foreground" />
                             </div>
 
                             <!-- Mobile table of contents title and description -->
                             <div class="min-w-0">
-                                <SheetTitle class="text-sm md:text-base! font-semibold text-(--text-primary-light) dark:text-(--text-primary-dark)">
+                                <SheetTitle class="text-sm md:text-base! font-semibold text-foreground">
                                     {{ tocTitle }}
                                 </SheetTitle>
                                 <SheetDescription class="sr-only">

package/src/components/blog/index.ts

@@ -4,6 +4,7 @@ export { default as BlogFAQSection } from './BlogFAQSection.vue';
 export { default as BlogInfoSection } from './BlogInfoSection.vue';
 export { default as BlogHeaderSection } from './BlogHeaderSection.vue';
 export { default as BlogSectionTitle } from './BlogSectionTitle.vue';
+export { default as BlogTagsSection } from './BlogTagsSection.vue';
 export { default as CategoriesList } from './CategoriesList.vue';
 export { default as CategoriesSection } from './CategoriesSection.vue';
 export { default as CategoryCard } from './CategoryCard.vue';

package/src/components/busy-indicator/busy-indicator-state.ts

@@ -1,4 +1,5 @@
 import { h, reactive, render, type HTMLAttributes } from 'vue';
+import { getUiVintageRuntimeMessage } from '../../lib/i18n';
 
 export interface SetBusyOptions {
     label?: string;
@@ -20,7 +21,7 @@ let busyIndicatorMountPromise: Promise<void> | null = null;
 // Shared busy state
 export const busyIndicatorState: BusyIndicatorState = reactive({
     show: false,
-    label: 'Loading...',
+    label: getUiVintageRuntimeMessage('uiVintage.common.loading.title', 'Loading...'),
     class: undefined,
     overlayClass: undefined
 });
@@ -70,7 +71,7 @@ const ensureBusyIndicatorMounted = () => {
 export const setBusy = (show: boolean, options: SetBusyOptions = {}) => {
     // Prepare the overlay before showing it
     if (show) {
-        busyIndicatorState.label = options.label ?? busyIndicatorState.label ?? 'Loading...';
+        busyIndicatorState.label = options.label ?? getUiVintageRuntimeMessage('uiVintage.common.loading.title', 'Loading...');
         busyIndicatorState.class = options.class;
         busyIndicatorState.overlayClass = options.overlayClass;
         void ensureBusyIndicatorMounted();

package/src/components/chip/Chip.vue

@@ -1,7 +1,9 @@
 <script setup lang="ts">
 import { Cancel01Icon } from '@hugeicons/core-free-icons';
 import { HugeiconsIcon } from '@hugeicons/vue';
+import { computed } from 'vue';
 import type { HTMLAttributes } from 'vue';
+import { useI18n } from 'vue-i18n';
 import { getSurfaceToneClasses, type ToneColor } from '../../lib/color-tokens';
 import { cn } from '../../lib/utils';
 
@@ -12,10 +14,12 @@ const props = withDefaults(defineProps<{
     removeLabel?: string;
     class?: HTMLAttributes['class'];
 }>(), {
-    color: 'gray',
-    removeLabel: 'Remove'
+    color: 'gray'
 });
 
+const { t } = useI18n();
+const resolvedRemoveLabel = computed(() => props.removeLabel || t('uiVintage.buttons.remove'));
+
 // Emits
 const emits = defineEmits<{
     remove: []
@@ -28,13 +32,13 @@ const handleRemove = () => {
 </script>
 
 <template>
-    <div data-slot="chip" :class="cn('inline-flex items-center gap-2 rounded border px-3 py-2 text-sm font-semibold transition-colors duration-300 ease-in-out', getSurfaceToneClasses(props.color), props.class)">
+    <div data-slot="chip" :class="cn('inline-flex items-center gap-2 rounded border px-3 py-2 text-sm font-semibold transition-colors duration-150', getSurfaceToneClasses(props.color), props.class)">
         <!-- Text content -->
         <span class="leading-none">{{ props.text }}</span>
 
         <!-- Remove button -->
-        <button type="button" :aria-label="props.removeLabel" class="inline-flex size-4 items-center justify-center rounded-sm opacity-70 transition-all duration-200 ease-in-out hover:bg-black/5 hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-current/20 dark:hover:bg-white/10" @click="handleRemove">
-            <HugeiconsIcon :icon="Cancel01Icon" class="size-3" />
+        <button type="button" :aria-label="resolvedRemoveLabel" class="group/remove inline-flex size-4 cursor-pointer items-center justify-center rounded-sm opacity-70 [transition:opacity_150ms,background-color_150ms,scale_300ms_var(--ease-spring)] hover:bg-black/5 hover:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-current/20 active:scale-75 dark:hover:bg-white/10" @click="handleRemove">
+            <HugeiconsIcon :icon="Cancel01Icon" class="size-3 transition-transform duration-300 ease-spring group-hover/remove:rotate-90" />
         </button>
     </div>
 </template>