@nuxtseo/design-system 0.1.0 → 0.1.2

package/README.md

@@ -15,7 +15,7 @@ Design system layer: design language extended by every app. It owns UI primitive
 
 **Depends on:** `nuxtseo-shared` (brand marks) and the published Nuxt modules in `package.json`. No workspace package.
 
-**Consumed by:** `apps/site`, `apps/pro`, `apps/admin`, `apps/brand-kit`, and outside sites through the [npm](https://npmjs.com) package `@nuxtseo/design-system`.
+**Consumed by:** `layers/brand`, which every Nuxt SEO app (`apps/site`, `apps/pro`, `apps/admin`, `apps/brand-kit`) extends in its place, and outside sites through the [npm](https://npmjs.com) package `@nuxtseo/design-system`.
 
 ## Rules
 
@@ -39,16 +39,21 @@ export default defineNuxtConfig({
 })
 ```
 
-- Peers: `nuxt` 4.6+, `vue` 3.5+, and `typescript` 5.8 to 6. The Vue SFC compiler resolves the layer's prop types through the TypeScript JS API, and TypeScript 7 has none.
+- 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.
+- 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`.
+- 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
 
 | What | How |
 | --- | --- |
 | Nuxt UI colours, slots, icons, toaster, favicon paths | `app.config.ts` in your app. It merges over the layer's `app/app.config.ts`. |
-| Tokens: colours, fonts, density, elevation | CSS custom properties in your own stylesheet, loaded after the layer's `css/global.css`. Override `--ui-*`, `--density-*`, and `--elevation-*`; never `--_depth-*`. |
+| Tokens: colours, fonts, density, elevation | CSS custom properties in your own stylesheet, loaded after the layer's `css/global.css`. Override `--ui-*`, `--font-*`, `--density-*`, and `--elevation-*`; never `--_depth-*` or `--_viz-*`. |
 | One instance | Props and slots on the component. |
 | Icon set, chart colours, icon colour roles | The brand seams below. |
 
@@ -77,12 +82,103 @@ export default defineNuxtConfig({
 })
 ```
 
-**Chart colours.** Every chart identity slot in `dataVizColors.ts` reads a `--ui-viz-<slot>` custom property: `clicks`, `impressions`, `ctr`, `position`, `sessions`, `users`, `pageviews`, `lcp`, `inp`, `cls`, `current`, `comparison`, `device-desktop`, `device-mobile`, `device-tablet`, `brand`, `non-brand`, `rank-1` to `rank-10`, `resource-document`, `resource-script`, `resource-stylesheet`, `resource-image`, `resource-font`, `category-1` to `category-5`, and `neutral`. The SVG paint, the `bg-viz-*` and `text-viz-*` classes, and the `/15` fills all follow it. Text classes use the same colour, so pick one that passes AA as text. Unset, light mode reads a deeper default for any slot whose stock hue falls under 3:1 on white; dark mode keeps the stock hue.
+**Favicon.** The layer's favicon plugin emits a theme-aware icon link and an Apple touch icon link from `favicon` in `app.config.ts`. Unset, it emits neither. Each link's MIME type follows the file extension, so an SVG declares `image/svg+xml`. A mode without its own path uses the other mode's path. The links carry `id: 'favicon'` and `id: 'apple-touch-icon'`.
+
+```ts
+// app.config.ts
+export default {
+  favicon: {
+    light: '/icon-light.svg',
+    dark: '/icon-dark.svg',
+    appleTouchLight: '/touch-icon.png',
+    appleTouchDark: '/touch-icon-dark.png',
+  },
+}
+```
+
+**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.
+
+**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
+// nuxt.config.ts
+export default defineNuxtConfig({
+  designSystem: { internalLinkHosts: ['example.com', 'www.example.com'] },
+})
+```
+
+**OG images.** [nuxt-og-image](https://nuxtseo.com/docs/og-image) compiles OG images against one Tailwind entry: the `#tailwindcss` alias, or else the first CSS entry that imports Tailwind, which is the layer's. Runtime `:root` overrides never reach it. To give OG images your theme, write an entry that imports the layer's stylesheet and restates your theme values. Then point the alias at it. Browsers never load this file.
+
+```css
+/* app/assets/css/og-theme.css */
+@import '@nuxtseo/design-system/css/global.css';
+
+@theme {
+  --font-sans: 'DM Sans', system-ui, sans-serif;
+  --font-display: 'Poppins', system-ui, sans-serif;
+  --font-title: 'Poppins', system-ui, sans-serif;
+}
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  alias: { '#tailwindcss': fileURLToPath(new URL('./app/assets/css/og-theme.css', import.meta.url)) },
+})
+```
+
+**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 |
+| --- | --- |
+| `--ui-light-text`, `--ui-light-text-dimmed`, `--ui-light-text-highlighted` | `--ui-text`, `--ui-text-dimmed`, `--ui-text-highlighted` in light mode |
+| `--ui-dashboard-neutral-50` to `--ui-dashboard-neutral-950` | The dashboard's neutral ramp, both modes |
+| `--ui-dashboard-light-text-dimmed` | Dashboard `--ui-text-dimmed`, light mode |
+| `--ui-dashboard-dark-text-dimmed`, `--ui-dashboard-dark-text-muted` | Dashboard `--ui-text-dimmed` and `--ui-text-muted`, dark mode |
+
+```css
+:root {
+  --ui-light-text: var(--color-olive-800);
+  --ui-dashboard-neutral-50: var(--color-olive-50);
+  /* and each step to 950 */
+}
+```
+
+A `var()` inside a custom property resolves on the element that declares it. So `:root { --ui-dashboard-dark-text-muted: var(--ui-color-neutral-400) }` reads the marketing ramp's 400 step. Name a fixed colour or a `--color-*` step instead.
+
+**Chart colours.** Every chart identity slot in `dataVizColors.ts` reads a `--ui-viz-<slot>` custom property: `clicks`, `impressions`, `ctr`, `position`, `sessions`, `users`, `pageviews`, `lcp`, `inp`, `cls`, `current`, `comparison`, `device-desktop`, `device-mobile`, `device-tablet`, `brand`, `non-brand`, `rank-1` to `rank-10`, `resource-document`, `resource-script`, `resource-stylesheet`, `resource-image`, `resource-font`, `category-1` to `category-5`, and `neutral`. The SVG paint, the `bg-viz-*` and `text-viz-*` classes, and the `/15` fills all follow it. Unset, light mode reads a deeper default for any slot whose stock hue falls under 3:1 on white; dark mode keeps the stock hue. Text classes use the mark colour unless `--ui-viz-<slot>-text` is set. If the mark colour fails AA as text, set it.
 
 ```css
 :root {
   --ui-viz-clicks: var(--ui-primary);
   --ui-viz-neutral: #94a3b8;
+  --ui-viz-comparison: #a3a292;
+  --ui-viz-comparison-text: #67713a;
 }
 ```
 
@@ -92,11 +188,61 @@ A palette `hex` field is a CSS colour, such as `var(--ui-viz-clicks, #3b82f6)`.
 
 ```ts
 // app.config.ts
-export default defineAppConfig({
+export default {
   designSystem: {
     iconColors: { lime: { bg: 'bg-lime-500/10', text: 'text-lime-500' } },
   },
-})
+}
+```
+
+**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/app.config.ts

@@ -1,3 +1,4 @@
+import type { AppFaviconConfig } from './utils/app-favicon'
 import type { IconColorClasses } from './utils/icon-color'
 import { UI_ICON_SLOTS } from '../shared/icons/ui-slots'
 
@@ -13,16 +14,11 @@ export default {
   designSystem: {
     iconColors: {} as Record<string, IconColorClasses>,
   },
-  // Theme-aware browser and installed-app brand marks. touch-icon(-dark).png are
-  // deliberately not named apple-touch-icon*.png: nuxt-seo-utils auto-generates a
-  // <link rel="apple-touch-icon"> for any public file matching that convention,
-  // which duplicated the reactive one this plugin already emits.
-  favicon: {
-    light: '/favicon-light.png',
-    dark: '/favicon-dark.png',
-    appleTouchLight: '/touch-icon.png',
-    appleTouchDark: '/touch-icon-dark.png',
-  },
+  // Theme-aware favicon and touch icon paths, read by plugins/favicon.ts. The
+  // layer ships no brand images, so every path is unset here and the plugin
+  // emits nothing until an app names its own files. The MIME type follows
+  // each file's extension.
+  favicon: {} as AppFaviconConfig,
   toaster: {
     position: 'bottom-right' as const,
     // Collapsed peek-deck that fans out on hover (Sonner/Linear). Read by UiToaster.

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/UiDataTableSection.vue

@@ -116,6 +116,7 @@ function errorText(value: unknown): string {
           type="search"
           class="w-full sm:w-56"
           :placeholder="searchPlaceholder"
+          icon="search"
           autocomplete="off"
           size="sm"
           :ui="{ base: 'min-h-11 transition-[width] duration-200 focus-within:w-72 sm:min-h-0' }"

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.