@nuxtseo/design-system 0.1.1 → 0.1.2

package/README.md

@@ -39,13 +39,14 @@ export default defineNuxtConfig({
 })
 ```
 
-- Peers: `nuxt` 4.6+, `vue` 3.5+, `typescript` 5.8 to 6, `@nuxt/ui` 4.11+, `motion-v` 2.4+, `tailwindcss` 4.3+, and `zod` 4. The Vue SFC compiler resolves the layer's prop types through the TypeScript JS API, and TypeScript 7 has none.
-- The layer shares your copy of each peer, so the app runs one Nuxt UI, one Tailwind, one motion-v context, and one zod. pnpm and npm install a missing peer for you. You need no `overrides` for the layer.
+- Peers: `nuxt` 4.6+, `vue` 3.5+, `typescript` 5.8 to 6, `@nuxt/ui` 4.11+, `@nuxt/scripts` 1.3+ or 2, `@vueuse/core` 14 or 15, `motion-v` 2.4+, `tailwindcss` 4.3+, and `zod` 4. The Vue SFC compiler resolves the layer's prop types through the TypeScript JS API, and TypeScript 7 has none. A TypeScript 7 native typecheck of your app still passes over the layer's components.
+- The layer shares your copy of each peer, so the app runs one Nuxt UI, one `@nuxt/scripts`, one [VueUse](https://vueuse.org), one Tailwind, one motion-v context, and one zod. pnpm and npm install a missing peer for you. You need no `overrides` for the layer.
 - If [pnpm](https://pnpm.io) reports ignored build scripts, allow `esbuild` and `@parcel/watcher` under `allowBuilds` in `pnpm-workspace.yaml`.
-- Import components from `#components`. The layer turns auto-imports off, in Nitro too.
+- Import components from `#components`. The layer turns auto-imports off, in Nitro too. If your app turns them back on, the layer's composables and utils stay out of its scan, so a name such as `formatNumber` never shadows your own. Import them by path.
 - Write `app.config.ts` as a plain object. `defineAppConfig` is an auto-import, so the server bundle has no such function.
 - Import other modules by their path: `@nuxtseo/design-system/app/composables/formatting`. A directory with an `index.ts` imports by its name: `@nuxtseo/design-system/shared/icons`, `@nuxtseo/design-system/shared/contracts`, and `@nuxtseo/design-system/types`.
-- The layer ships no favicon and loads no fonts. Set both through the brand seams below.
+- To wrap a component, import its props from a `.ts` module, never from the `.vue` file: the SFC compiler cannot resolve a type inside a package `.vue` file. `UiTableProps` and `UiTableSlots` live in `@nuxtseo/design-system/app/shared/table`, `UiStatProps` in `app/shared/stat`, and `UiToastProps` and `UiToasterProps` in `app/shared/toast`.
+- The layer ships no favicon and no font files. Set both through the brand seams below.
 
 ### Overrides
 
@@ -95,16 +96,33 @@ export default {
 }
 ```
 
-**Type.** Set `--font-sans`, `--font-display`, `--font-title`, and `--font-mono` in your stylesheet, and register the faces with `fonts.families`. `--font-title` carries page titles (`.text-title` and the `font-title` utility). Its default is the display family. The layer self-hosts Nuxt SEO's Hubot Sans and Fira Code but registers neither by default, so no page preloads them. To use them, opt in:
+**Type.** Set `--font-sans`, `--font-display`, `--font-title`, and `--font-mono` in your stylesheet, and register the faces with `fonts.families`. `--font-title` carries page titles (`.text-title` and the `font-title` utility). Its default is the display family. The layer ships no font files and registers no faces.
 
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  extends: ['@nuxtseo/design-system'],
-  designSystem: { fonts: true },
-})
+**Type scale.** Set these properties at `:root` to resize or recase the dense tiers. Unset, each keeps the value in the second column.
+
+| Property | Default | Sets |
+| --- | --- | --- |
+| `--ui-label-size`, `--ui-label-weight`, `--ui-label-case`, `--ui-label-tracking` | `10px`, `600`, `uppercase`, `0.05em` | `.text-label` and `UiMetricLabel` |
+| `--ui-table-cell-size`, `--ui-table-cell-leading` | `--text-xs` and its leading | Body cells of `UiTable` and `UiTableTd` |
+| `--ui-table-head-size`, `--ui-table-head-leading` | `--ui-label-size`, inherited | Header labels of `UiTable` and `UiTableTh` |
+| `--ui-trend-2xs-size`, `--ui-trend-xs-size`, `--ui-trend-xs-leading` | `10px`, `--text-xs` and its leading | `UiTrend` sizes `2xs` and `xs` |
+| `--ui-trend-badge-case` | `uppercase` | `UiTrend` New and Lost |
+
+```css
+:root {
+  --ui-label-size: 0.75rem;
+  --ui-label-weight: 500;
+  --ui-label-case: none;
+  --ui-label-tracking: normal;
+  --ui-table-cell-size: var(--text-sm);
+  --ui-table-cell-leading: var(--text-sm--line-height);
+  --ui-table-head-size: var(--text-sm);
+  --ui-trend-badge-case: none;
+}
 ```
 
+**Surfaces.** The layer sets every `--ui-bg*`, `--ui-text*` and `--ui-border*` token on `.light`, `.dark` and `.dashboard-theme` inside `:where()`, so those rules carry no specificity. Set a surface token in a plain `:root` rule and it wins in both modes; set it in a `.dark` rule to change dark mode only. Source order does not matter.
+
 **Own-site links.** An absolute HTTP or HTTPS prose link gets an external-link arrow. List the hosts that count as your site, and links to them get none. Unset, the layer lists no host.
 
 ```ts
@@ -134,7 +152,7 @@ export default defineNuxtConfig({
 })
 ```
 
-**Text and dashboard neutrals.** Three light mode text tokens sit on Nuxt SEO's violet hue, off the neutral ramp. The dashboard (`.dashboard-theme`) swaps the neutral ramp to mauve. Set these properties to re-hue them; never override the selectors. Unset, each keeps Nuxt SEO's value.
+**Text and dashboard neutrals.** Three light mode text tokens sit on Nuxt SEO's violet hue, off the neutral ramp. The dashboard (`.dashboard-theme`) swaps the neutral ramp to mauve. Set these properties to re-hue them. Unset, each keeps Nuxt SEO's value.
 
 | Property | Sets |
 | --- | --- |
@@ -177,6 +195,54 @@ export default {
 }
 ```
 
-**Onboarding copy.** `UiOnboardingAnswers` takes an `intents` prop for the goal list and a `copy` prop for its strings: `roleQuestion`, `siteCountQuestion`, `seoExperienceQuestion`, `intentsQuestion`, `intentsHint`, `otherLabel`, and `otherPlaceholder`. Pass any of them. Unset keys keep the strings in `ONBOARDING_ANSWERS_COPY`. Onboarding Answers store the option ids, so the ids never change.
+**Onboarding copy.** `UiOnboardingAnswers` takes an `intents` prop for the goal list and a `copy` prop for its strings: `roleQuestion`, `siteCountQuestion`, `seoExperienceQuestion`, `intentsQuestion`, `intentsHint`, `otherLabel`, and `otherPlaceholder`. Pass any of them. Unset keys keep the strings in `ONBOARDING_ANSWERS_COPY`. An empty `intentsHint` hides the hint. Onboarding Answers store the option ids, so the ids never change.
+
+**Onboarding controls.** Two scoped slots draw `UiOnboardingAnswers` in your own look and keep its answer logic. `#option="{ question, option, selected, pick }"` draws one single-choice option; `pick()` selects it, or clears it when it is already picked. `#intents="{ intents, selected, toggle, other, setOther }"` draws the goals and the free-text box. Your heading, Skip, and Save sit around the component, and saving stays with your app: the layer never fetches.
+
+```vue
+<UiOnboardingAnswers v-model="answers" :copy="{ intentsHint: '' }">
+  <template #option="{ option, selected, pick }">
+    <UButton :label="option.label" :variant="selected ? 'soft' : 'outline'" :aria-pressed="selected" @click="pick" />
+  </template>
+  <template #intents="{ selected, toggle, other, setOther }">
+    <MyGoalsGrid :selected="selected" :other="other" @toggle="toggle" @update:other="setOther" />
+  </template>
+</UiOnboardingAnswers>
+```
+
+**Trend colour.** `UiTrend` draws a change in neutral text unless a caller passes `colored`, because Nuxt SEO spends colour on hero trends only. A site that colours every trend sets the default once:
+
+```ts
+// app.config.ts
+export default {
+  designSystem: { trend: { colored: true } },
+}
+```
+
+**Atmosphere.** `UiAtmosphere` draws no grain and leaves the `bloom` geometry unmasked unless asked. Pass `grain` or `bloom-mask` on one instance, or turn either on for the whole site with `designSystem: { atmosphere: { grain: true, bloomMask: true } }` in `app.config.ts`. Nuxt SEO's own brand layer turns both on.
+
+**Failure copy.** `UiWidgetState`, `UiDataList` and `UiErrorState` state a failed read in copy the layer owns (COPY.md, Shared primitive assets). Reword any of it in `app.config.ts`. A failure keeps its retry behaviour; only the words change. Unset keys keep the defaults in `FAILURE_COPY` (`app/shared/failure-copy.ts`).
+
+```ts
+// app.config.ts
+export default {
+  designSystem: {
+    failureCopy: {
+      failures: { server: { title: 'We could not load this data' } },
+      retryLabel: 'Try again',
+    },
+  },
+}
+```
+
+## Component notes
+
+- **`UiTable` cell slots.** A `#<column id>-cell="{ row, cell, value }"` slot draws that column's cells and wins over the column's `cell` renderer. Columns with no slot keep their renderer. `#empty` replaces the zero-rows line.
+- **`UiTableTd` and `UiTableTh`** take `colspan` and `title`.
+- **`UiConfirmDialog`** takes a `#body` slot; `useConfirm()` takes a `body` render function for the same place. Pass `action` to `useConfirm()` and the confirm button runs it with a loading state, the dialog cannot be dismissed meanwhile, and then it closes. A rejected action rejects the `useConfirm()` promise.
+- **`UiAlert`** takes `:animated="false"` to skip its entrance.
+- **`UiSectionHeader size="lg"`** is the long-form page tier: a 24 to 30px heading over a top rule.
+- **`UiSkeleton`** draws whole loading shapes with `type="table-row"`, `"stat"`, `"chart"` or `"card"`; `count` sets how many.
+- **`UiTopEntityStackChart`** has no `yMax` or `bucketTotal`. `scale="share"` fills each bar to 100%, and the tooltip states each bucket's total through `format`.
 
 **Motion.** The layer provides motion-v's `domAnimation` features to the whole app, `error.vue` included. A site needs no `<LazyMotion>` wrapper.

package/app/components/container/UiAlert.vue

@@ -8,7 +8,7 @@ import { semanticColors } from '../../composables/semanticColors'
 import { useEntranceMotion } from '../../composables/useEntranceMotion'
 import { entrancePresets } from '../../shared/motion'
 
-const { status = 'info', icon, title } = defineProps<{
+const { status = 'info', icon, title, animated = true } = defineProps<{
   /** Semantic status — drives the accent icon + bar + corner bloom (surface
    *  stays neutral for every status). Shared name across the status family
    *  (UiChip, UiStatusBadge). */
@@ -21,6 +21,8 @@ const { status = 'info', icon, title } = defineProps<{
   description?: string
   /** Show close/dismiss button */
   dismissible?: boolean
+  /** Fade the alert in when the client mounts it. Set false for an alert that must not move, such as one inside a dialog. */
+  animated?: boolean
 }>()
 
 const emit = defineEmits<{
@@ -51,7 +53,7 @@ const resolvedIcon = computed(() => icon || defaultIcons[status])
 const isUrgent = computed(() => status === 'error' || status === 'warning')
 const dismissLabel = computed(() => title ? `Dismiss alert: ${title}` : 'Dismiss alert')
 
-const entrance = useEntranceMotion(entrancePresets.fadeUp)
+const entrance = useEntranceMotion(entrancePresets.fadeUp, () => animated)
 </script>
 
 <template>

package/app/components/container/UiErrorState.vue

@@ -2,6 +2,7 @@
 import type { ErrorStateSource } from '../../shared/error-state'
 import { computed } from 'vue'
 import { UiAlert, UiButton } from '#components'
+import { readFailureCopy } from '../../composables/design-system-config'
 import { resolveErrorState } from '../../shared/error-state'
 
 const { error } = defineProps<{
@@ -16,7 +17,7 @@ const { error } = defineProps<{
    * the caught message, which quotes the request URL.
    */
   error: ErrorStateSource | null
-  /** Optional retry handler. When set (and no #action slot), renders a "Try again" button. */
+  /** Optional retry handler. When set (and no #action slot), renders a retry button ("Try again" unless app.config rewords it). */
   onRetry?: () => void
 }>()
 
@@ -27,7 +28,8 @@ defineSlots<{
 
 // `Date.now()` is read once per resolve, the same as the old inline reset
 // maths. The reset hint counts down only when something else re-renders.
-const view = computed(() => error ? resolveErrorState(error, Date.now()) : null)
+const copy = readFailureCopy()
+const view = computed(() => error ? resolveErrorState(error, Date.now(), copy) : null)
 </script>
 
 <template>
@@ -53,7 +55,7 @@ const view = computed(() => error ? resolveErrorState(error, Date.now()) : null)
       purpose="secondary"
       size="xs"
       icon="refresh"
-      label="Try again"
+      :label="copy.errorStateRetryLabel"
       class="mt-2"
       @click="onRetry()"
     />

package/app/components/container/UiSectionHeader.vue

@@ -19,6 +19,7 @@ const {
   chat,
   mcp,
   schema,
+  size = 'sm',
 } = defineProps<{
   title: string
   description?: string
@@ -35,14 +36,23 @@ const {
   chat?: EjectChat
   mcp?: EjectMcp
   schema?: EjectLink
+  /**
+   * `sm` is the dashboard tier: the `.text-heading` section heading. `lg` is
+   * the long-form page tier: a 24 to 30px heading over a top rule, so page
+   * sections keep their hierarchy above an on-page FAQ heading.
+   */
+  size?: 'sm' | 'lg'
 }>()
 
 const slots = useSlots()
 const hasEject = computed(() => !!(chat || mcp || schema))
+const headingClass = computed(() => size === 'lg'
+  ? 'font-sans text-2xl font-semibold tracking-[-0.025em] text-default md:text-3xl'
+  : 'text-heading text-default')
 </script>
 
 <template>
-  <div class="flex items-center justify-between gap-3 mb-3">
+  <div class="flex items-center justify-between gap-3" :class="size === 'lg' ? 'mb-6 border-t border-accented pt-5' : 'mb-3'">
     <div class="flex items-center gap-2 min-w-0">
       <!-- A section that reads through one Source passes its mark here, in
            place of the decorative icon. -->
@@ -50,7 +60,7 @@ const hasEject = computed(() => !!(chat || mcp || schema))
         <UiNavIcon v-if="icon" :icon="icon" />
       </slot>
       <div class="min-w-0">
-        <h2 class="text-heading text-default flex items-center gap-2">
+        <h2 class="flex items-center gap-2" :class="headingClass">
           <slot name="title">
             {{ title }}
           </slot>

package/app/components/container/UiToast.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
-import type { Component } from 'vue'
 import type { SemanticStatus } from '../../composables/semanticColors'
+import type { ToastAction, UiToastProps } from '../../shared/toast'
 import { useElementSize } from '@vueuse/core'
 import { computed, useTemplateRef, watch } from 'vue'
 import { UiButton, UiIcon } from '#components'
@@ -13,42 +13,6 @@ import { semanticColors } from '../../composables/semanticColors'
 // renders this inside a `<motion.li>`. Rendered exclusively from the shared
 // useToast() queue, so every existing `toast.add(...)` call site keeps working.
 
-export interface ToastAction {
-  label: string
-  icon?: string
-  to?: string
-  onClick?: (e: MouseEvent) => void
-  /** Visual emphasis. `primary` = filled, `neutral` = quiet. */
-  color?: 'primary' | 'neutral'
-}
-
-export interface UiToastProps {
-  /** Heading text (string or a render component). */
-  title?: string | Component
-  /** Body text (string or a render component). */
-  description?: string | Component
-  /** Semantic status — drives accent + default icon. Wins over `color`. */
-  status?: SemanticStatus
-  /** Nuxt UI color compatibility for existing `toast.add({ color })` call sites. */
-  color?: 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error' | 'neutral'
-  /** Icon override. Defaults to the status icon. */
-  icon?: string
-  /** Inline action buttons. */
-  actions?: ToastAction[]
-  /**
-   * Bug-report handler. When set, failure toasts (error/warning) that carry no
-   * action of their own get a "Report bug" button. Wired by the app (the
-   * design system must not reach for the feedback drawer itself).
-   */
-  reportBug?: (toast: { title?: string, description?: string }) => void
-  /** Show the close button. */
-  close?: boolean
-  /** Auto-dismiss progress 0..1 (remaining), or false to hide the bar. */
-  progress?: number | false
-  /** Collapsed back card — fade content so the deck reads as peeking cards. */
-  peek?: boolean
-}
-
 const {
   title,
   description,

package/app/components/container/UiToaster.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { UiToastProps } from './UiToast.vue'
+import type { UiToasterProps, UiToastProps } from '../../shared/toast'
 import { useMounted, useRafFn } from '@vueuse/core'
 import { AnimatePresence, motion, useReducedMotion } from 'motion-v'
 import { computed, reactive, ref, watch } from 'vue'
@@ -15,16 +15,6 @@ import UiToast from './UiToast.vue'
 // Nuxt UI's shared useToast() queue, so every existing `toast.add(...)` keeps
 // working unchanged. (Interaction model: brand-kit /toasts → "Fire 5 at once".)
 
-export interface UiToasterProps {
-  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
-  /** Max cards rendered in the deck (older ones collapse into a "+N" pill). */
-  max?: number
-  /** Default auto-dismiss in ms; a per-toast `duration` overrides. 0 = sticky. */
-  duration?: number
-  /** Passed to every card: adds "Report bug" to failure toasts. See UiToast. */
-  reportBug?: UiToastProps['reportBug']
-}
-
 const {
   position = 'bottom-right',
   max = 3,

package/app/components/container/UiWidgetState.vue

@@ -4,7 +4,8 @@ import type { ViewState } from '../../shared/view-state'
 import type { WidgetFailure } from '../../shared/widget-failure'
 import { computed, onMounted, ref } from 'vue'
 import { UiButton, UiEmptyState, UiIcon, UiSkeleton } from '#components'
-import { toWidgetFailure, WIDGET_FAILURE_COPY } from '../../shared/widget-failure'
+import { readFailureCopy } from '../../composables/design-system-config'
+import { toWidgetFailure } from '../../shared/widget-failure'
 
 const {
   state,
@@ -88,8 +89,9 @@ const failure = computed(() => toWidgetFailure(state?._tag === 'error' ? state.e
 const data = computed(() => state?._tag === 'data' ? state.data : undefined)
 // A refresh failed while an earlier answer is still on screen. The content
 // stays and a notice says the refresh failed.
-const refreshFailure = computed(() => state?._tag === 'data' && state.refreshError ? WIDGET_FAILURE_COPY[toWidgetFailure(state.refreshError)._tag] : null)
-const failureCopy = computed(() => WIDGET_FAILURE_COPY[failure.value._tag])
+const copy = readFailureCopy()
+const refreshFailure = computed(() => state?._tag === 'data' && state.refreshError ? copy.failures[toWidgetFailure(state.refreshError)._tag] : null)
+const failureCopy = computed(() => copy.failures[failure.value._tag])
 </script>
 
 <template>
@@ -114,7 +116,7 @@ const failureCopy = computed(() => WIDGET_FAILURE_COPY[failure.value._tag])
           {{ failureCopy.body }}
         </p>
         <UiButton v-if="failureCopy.retryable" size="xs" purpose="secondary" icon="refresh" @click="emit('retry')">
-          Retry
+          {{ copy.retryLabel }}
         </UiButton>
       </div>
     </slot>
@@ -133,7 +135,7 @@ const failureCopy = computed(() => WIDGET_FAILURE_COPY[failure.value._tag])
           <span class="font-medium text-default">{{ refreshFailure.title }}.</span> {{ refreshFailure.body }}
         </p>
         <UiButton v-if="refreshFailure.retryable" purpose="secondary" size="xs" icon="refresh" @click="emit('retry')">
-          Retry
+          {{ copy.retryLabel }}
         </UiButton>
       </div>
       <slot :data="data" />

package/app/components/data/UiDataList.vue

@@ -3,6 +3,7 @@ import type { UiIcon as UiIconName } from '../../shared/ui-icons'
 import type { ViewState } from '../../shared/view-state'
 import { computed, onMounted, ref } from 'vue'
 import { NuxtLink, UiButton, UiHelpLabel, UiIcon, UiNavIcon, UiSkeleton } from '#components'
+import { readFailureCopy } from '../../composables/design-system-config'
 import { widgetFailureCopy } from '../../shared/widget-failure'
 import { getIconColor } from '../../utils/icon-color'
 
@@ -113,11 +114,12 @@ const view = computed<ViewState<readonly T[]>>(() => {
 })
 const isLoading = computed(() => view.value._tag === 'loading')
 const rows = computed<readonly T[]>(() => view.value._tag === 'data' ? view.value.data : [])
+const copy = readFailureCopy()
 const failure = computed(() => {
   if (view.value._tag === 'error')
-    return widgetFailureCopy(view.value.error)
+    return widgetFailureCopy(view.value.error, copy.failures)
   if (view.value._tag === 'data' && view.value.refreshError != null)
-    return widgetFailureCopy(view.value.refreshError)
+    return widgetFailureCopy(view.value.refreshError, copy.failures)
   return null
 })
 
@@ -207,7 +209,7 @@ function itemKey(item: T, index: number): string | number {
             {{ failure.body }}
           </p>
           <UiButton v-if="onRetry && failure.retryable" purpose="secondary" size="xs" icon="refresh" class="mt-2" @click="onRetry()">
-            Retry
+            {{ copy.retryLabel }}
           </UiButton>
         </div>
       </div>
@@ -238,7 +240,7 @@ function itemKey(item: T, index: number): string | number {
           <span class="font-medium text-default">{{ failure.title }}.</span> {{ failure.body }}
         </p>
         <UiButton v-if="onRetry && failure.retryable" purpose="secondary" size="xs" icon="refresh" @click="onRetry()">
-          Retry
+          {{ copy.retryLabel }}
         </UiButton>
       </div>
       <div v-if="view._tag === 'data'" class="flex-1 p-1 space-y-0.5">

package/app/components/data/UiMetricLabel.vue

@@ -8,9 +8,11 @@ const { size = 'xs', tone = 'dimmed' } = defineProps<{
 
 // xs = the dense .text-label tier (10px); sm = a 12px label for popover/list
 // section headings. (Both were 10px before — the sm tier was a dead no-op.)
+// Both follow the label case and tracking seam (`--ui-label-case`,
+// `--ui-label-tracking`), so a sentence-case site sets them once.
 const sizeClass = {
   xs: 'text-label',
-  sm: 'text-xs uppercase tracking-wider font-semibold',
+  sm: 'text-xs font-semibold [text-transform:var(--ui-label-case,uppercase)] [letter-spacing:var(--ui-label-tracking,0.05em)]',
 } as const
 
 const toneClass = {

package/app/components/data/UiStat.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { UiIcon as UiIconName } from '../../shared/ui-icons'
+import type { UiStatProps } from '../../shared/stat'
 import type { SlotTextOptions } from '../../utils/slot-text'
 import { useElementHover } from '@vueuse/core'
 import { computed, onMounted, ref, useSlots } from 'vue'
@@ -41,65 +41,6 @@ const {
 // NuxtLink auto-registers globally; resolve by name so we don't depend on
 // the `#components` virtual (which doesn't narrow nicely in a layer).
 
-type Datum = Record<string, number | string>
-
-export interface UiStatProps {
-  // link
-  to?: string
-
-  // label
-  icon?: UiIconName
-  title?: string
-  tooltip?: string
-  tooltipDescription?: string
-
-  // value
-  value?: string | number | null
-  suffix?: string
-  valueClass?: string
-  format?: (n: number) => string
-
-  // trend
-  trend?: number | null
-  /**
-   * Formats the trend magnitude. The value `format` never applies: the trend is
-   * a percent or a delta, so a currency formatter printed "+$12.5%".
-   */
-  trendFormat?: (n: number) => string
-  trendSuffix?: string
-  trendLabel?: string
-  invertTrend?: boolean
-  /**
-   * Trend color budget (DESIGN.md Composition): colored success/error trends
-   * belong to the hero zone only. Default renders neutral; `UiStats
-   * variant="cards"` (the hero pattern) opts its stats in automatically.
-   */
-  trendColored?: boolean
-
-  // sparkline
-  sparkline?: Datum[]
-
-  // sizing
-  size?: 'sm' | 'md' | 'lg'
-  /** Keep report-visible labels and deltas at the 14px readable tier. */
-  readableLabels?: boolean
-
-  // state
-  loading?: boolean
-
-  /**
-   * Rolls compact metric values when they change. Defaults on for numeric-ish
-   * values; pass false for dense/realtime surfaces or object options to tune.
-   */
-  animatedValue?: boolean | SlotTextOptions
-
-  // threshold alerting
-  status?: 'crisis' | 'warning' | 'good'
-
-  // render the value area inside a card, keeping the header outside
-  card?: boolean
-}
-
 const hydrated = ref(false)
 onMounted(() => {
   hydrated.value = true

package/app/components/data/UiStats.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import type { UiStatProps } from './UiStat.vue'
+import type { UiStatProps } from '../../shared/stat'
 // Port of nuxtseo/core UiStats. Swaps tailwind-merge for a plain
 // filter+join — the component doesn't generate conflicting Tailwind classes,
 // and consumer `class` attrs cascade normally via the class attribute merge.

package/app/components/data/UiTable.vue

@@ -8,12 +8,12 @@ import type {
   RowSelectionState,
   SortingState,
 } from '@tanstack/vue-table'
-import type { UiTableColumn, UiTableFeatures, UiTableRowId, UiTableSize } from '../../shared/table'
+import type { UiTableColumn, UiTableFeatures, UiTableProps, UiTableSlots } from '../../shared/table'
 import { FlexRender, functionalUpdate, useTable } from '@tanstack/vue-table'
 import { useIntersectionObserver } from '@vueuse/core'
-import { computed, ref, toRef, useId, useSlots, useTemplateRef, watch } from 'vue'
+import { computed, ref, toRef, useId, useTemplateRef, watch } from 'vue'
 import { UiButton, UiSkeleton, UiTableExport, UiTableFrame, UiTableHeaderCell, UPagination } from '#components'
-import { resolveUiTableRowId, uiTableCellSizeClass, uiTableFeatures, uiTableSkeletonSizeClass, uiTableVisibleFromClass } from '../../shared/table'
+import { resolveUiTableRowId, uiTableCellSizeClass, uiTableCellSlotName, uiTableFeatures, uiTableSkeletonSizeClass, uiTableVisibleFromClass } from '../../shared/table'
 import { uiTableExport } from '../../shared/table-export'
 
 const {
@@ -51,6 +51,8 @@ const emit = defineEmits<{
   'sortColumn': [column: string]
 }>()
 
+const slots = defineSlots<UiTableSlots<T>>()
+
 const selectedModel = defineModel<RowSelectionState>('selected')
 const pageModel = defineModel<number>('page', { default: 1 })
 const sortingModel = defineModel<SortingState>('sorting', { default: () => [] })
@@ -170,8 +172,6 @@ function onRowKeydown(e: KeyboardEvent, row: T, tanstackRow: Row<UiTableFeatures
   }
 }
 
-const slots = useSlots()
-
 // Optional trailing actions column (row buttons/menus). Rendered outside the
 // TanStack column model so callers express rich actions as a slot, not a cell
 // render fn. `colSpan` accounts for it in the empty/skeleton rows.
@@ -283,49 +283,6 @@ if (import.meta.dev) {
 }
 </script>
 
-<script lang="ts">
-export interface UiTableProps<T extends object> {
-  data: T[]
-  columns: UiTableColumn<T>[]
-  selected?: RowSelectionState
-  controlledSelection?: boolean
-  rowHover?: boolean
-  rowClickable?: boolean
-  enableSorting?: boolean
-  /** Caller owns sort state; UiTable emits @sortColumn and bypasses client-side sorting. */
-  manualSorting?: boolean
-  pageSize?: number
-  ignoreHeader?: boolean
-  size?: UiTableSize
-  loading?: boolean
-  loadingRows?: number
-  rowId?: UiTableRowId<T>
-  manualPagination?: boolean
-  disablePagination?: boolean
-  total?: number
-  /** Accessible name for the table. Rendered as a visually-hidden <caption>. */
-  label: string
-  /** Draw the canonical rounded table surface. */
-  bordered?: boolean
-  /** Pagination density. Compact renders previous, page position, and next only. */
-  paginationPreset?: 'default' | 'compact'
-  /** Fill the caller's available height and keep pagination pinned to the bottom. */
-  fill?: boolean
-  /** Extra classes applied per data row — e.g. a selection highlight. */
-  rowClass?: (row: T) => string
-  /** Row id presented as the active item in a click-through table. */
-  activeRowId?: string
-  /** Row id to open when the table first receives deep-linked evidence. */
-  initialExpandedRowId?: string
-  /**
-   * Show Export CSV and Export JSON, saving to this file name without the
-   * extension. The export holds every filtered and sorted row, not one page.
-   * Ignored with `manualPagination`: mount `UiTableExport` with every row.
-   */
-  exportFilename?: string
-}
-</script>
-
 <template>
   <div class="w-full" :class="fill && 'flex h-full min-h-0 flex-col'">
     <UiTableExport
@@ -353,7 +310,7 @@ export interface UiTableProps<T extends object> {
             <th
               v-for="header in headerGroup.headers"
               :key="header.id"
-              class="text-label text-left whitespace-nowrap border-b border-default bg-default"
+              class="text-label ui-table-head text-left whitespace-nowrap border-b border-default bg-default"
               :class="[
                 uiColumnDef(header.column).noPadding ? '' : header.column.getCanSort() ? 'px-2' : 'px-3',
                 getTextAlignClass(uiColumnDef(header.column).align, uiColumnDef(header.column).numeric),
@@ -397,7 +354,7 @@ export interface UiTableProps<T extends object> {
                   v-for="cell in row.getVisibleCells()"
                   :key="cell.id"
                   :scope="uiColumnDef(cell.column).rowHeader ? 'row' : undefined"
-                  class="text-xs font-normal text-default relative"
+                  class="ui-table-cell font-normal text-default relative"
                   :class="[
                     uiTableCellSizeClass[size],
                     uiColumnDef(cell.column).noPadding ? '' : cell.column.getCanSort() ? 'px-2' : 'px-3',
@@ -422,6 +379,13 @@ export interface UiTableProps<T extends object> {
                     :base="60"
                     :range="50"
                   />
+                  <slot
+                    v-else-if="slots[uiTableCellSlotName(cell.column.id)]"
+                    :name="uiTableCellSlotName(cell.column.id)"
+                    :row="row"
+                    :cell="cell"
+                    :value="cell.getValue()"
+                  />
                   <FlexRender v-else :cell="cell" />
                 </component>
                 <td v-if="hasActions" class="text-right whitespace-nowrap px-3" :class="uiTableCellSizeClass[size]" @click.stop>
@@ -444,7 +408,7 @@ export interface UiTableProps<T extends object> {
               <td
                 v-for="(col, j) in columns"
                 :key="j"
-                class="text-xs px-3"
+                class="ui-table-cell px-3"
                 :class="[
                   uiTableCellSizeClass[size],
                   getTextAlignClass(col.align, col.numeric),
@@ -458,7 +422,7 @@ export interface UiTableProps<T extends object> {
 
           <tr v-else>
             <td :colspan="colSpan" class="h-24 text-center" role="status">
-              <slot name="empty-component">
+              <slot name="empty">
                 <span class="text-xs font-mono text-dimmed">0 rows · adjust filters</span>
               </slot>
             </td>

package/app/components/data/UiTableTd.vue

@@ -10,10 +10,16 @@ const {
   numeric = false,
   rowHeader = false,
   visibleFrom,
+  colspan,
+  title,
 } = defineProps<UiTableCellProps & {
   size?: UiTableSize
   noPadding?: boolean
   rowHeader?: boolean
+  /** Columns this cell spans, e.g. a full-width note row. */
+  colspan?: number | string
+  /** Native tooltip, e.g. the full value behind a truncated cell. */
+  title?: string
 }>()
 
 const resolvedAlign = computed(() => numeric ? 'right' : align)
@@ -25,7 +31,9 @@ const padClass = computed(() => noPadding ? '' : 'px-3')
   <component
     :is="rowHeader ? 'th' : 'td'"
     :scope="rowHeader ? 'row' : undefined"
-    class="text-xs font-normal text-default relative"
+    :colspan="colspan"
+    :title="title"
+    class="ui-table-cell font-normal text-default relative"
     :class="[
       uiTableCellSizeClass[size],
       padClass,