@nuxtseo/design-system 0.0.0-stage → 0.1.1

package/app/components/element/UiFaviconStack.vue

@@ -0,0 +1,84 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { UiFavicon, UiTooltip } from '#components'
+
+export interface FaviconStackSite {
+  /** Hostname, full URL, or `sc-domain:` property — `UiFavicon` normalises it. */
+  domain: string
+  /** The visible Site name. Names the Site in the tooltip and the fallback initial. */
+  label: string
+}
+
+/**
+ * A row's Site identity, as favicons only.
+ *
+ * List rows repeat their Site on every line. Spelled out, the name is a second
+ * text column that competes with the diagnosis and truncates first on narrow
+ * screens. A framed favicon carries the same identity in 20px and reads as an
+ * icon, not as content. The name is one hover away, and the caller still owns
+ * the accessible name of any control the stack sits inside.
+ *
+ * Mirrors `UiSourceLogos`: the same frame, the same `-ml-1.5` overlap, the same
+ * `role="img"` wrapper. Sources say WHERE a finding came from; this says WHICH
+ * Site it belongs to. One Site renders as a single frame, which is the same
+ * markup with nothing to overlap.
+ */
+
+const { sites, size = 'sm', max = 4 } = defineProps<{
+  sites: readonly FaviconStackSite[]
+  /** Favicon pixel size: `xs` is 14px, `sm` is 16px. */
+  size?: 'xs' | 'sm'
+  /** Favicons rendered before the rest collapse into a `+N` frame. */
+  max?: number
+}>()
+
+const shown = computed(() => sites.slice(0, Math.max(1, max)))
+const overflow = computed(() => sites.length - shown.value.length)
+
+// Every Site is named, including the ones behind `+N` — the tooltip is the only
+// place the reader can recover a name the row no longer prints.
+const accessibleLabel = computed(() => sites.map(site => site.label).join(', '))
+
+const iconPixels = computed(() => (size === 'xs' ? 14 : 16))
+const frameClass = computed(() => (size === 'xs' ? 'size-5' : 'size-6'))
+</script>
+
+<template>
+  <!--
+    `trigger-as="child"` so the trigger IS the stack. The default `span` wrapper
+    would add an inline-block layer inside the row's flex line, and the `button`
+    variant would nest a control inside rows that are themselves one button or
+    one link.
+  -->
+  <UiTooltip v-if="sites.length" :text="accessibleLabel" trigger-as="child">
+    <span
+      class="inline-flex shrink-0 items-center"
+      role="img"
+      :aria-label="accessibleLabel"
+    >
+      <span
+        v-for="(site, index) in shown"
+        :key="site.domain"
+        class="inline-flex shrink-0 items-center justify-center rounded-md border border-default bg-default shadow-xs"
+        :class="[frameClass, index ? '-ml-1.5' : '']"
+        aria-hidden="true"
+      >
+        <!-- `fallbackLabel` so a domain with no reachable favicon still shows an
+             initial rather than an empty frame — the frame IS the identity here. -->
+        <UiFavicon
+          :domain="site.domain"
+          :size="iconPixels"
+          :fallback-label="site.label"
+          fallback-surface="transparent"
+          decorative
+        />
+      </span>
+      <span
+        v-if="overflow > 0"
+        class="-ml-1.5 inline-flex shrink-0 items-center justify-center rounded-md border border-default bg-default text-mini font-medium tabular-nums leading-none text-muted shadow-xs"
+        :class="frameClass"
+        aria-hidden="true"
+      >+{{ overflow }}</span>
+    </span>
+  </UiTooltip>
+</template>

package/app/components/element/UiFilterMenu.vue

@@ -0,0 +1,324 @@
+<script setup lang="ts">
+import { computed, nextTick, ref, watch } from 'vue'
+import { ToggleGroupItem, ToggleGroupRoot, UiIcon, UiMetricLabel, UInput, UiPopover } from '#components'
+// Presentational filter primitive: a popover combining a dimension search,
+// dimension shortcuts, a branded toggle, saved filters and preset filters.
+// All data is prop-driven and actions are emitted — the consumer owns
+// persistence and what each dimension/preset means.
+
+interface DimensionOption {
+  label: string
+  value: string
+  icon: string
+}
+interface SavedFilter {
+  id: string
+  label: string
+}
+interface PresetFilter {
+  id: string
+  label: string
+  icon?: string
+}
+interface BrandedOption {
+  label: string
+  value: string
+  icon?: string
+}
+
+const {
+  dimensions = [],
+  dimensionValues = {},
+  brandedOptions = [],
+  savedFilters = [],
+  presetFilters = [],
+  activePreset = '',
+  activeCount = 0,
+  label = 'Filter',
+  searchable = true,
+  searchPlaceholder = 'Search…',
+  showSaved = true,
+} = defineProps<{
+  /** Dimension shortcuts (Query/Page/Country/Device). Clicking opens that dimension's `#picker` sub-view. */
+  dimensions?: DimensionOption[]
+  /** Current applied value per dimension (keyed by dimension value) — shown as a trailing label on the row. */
+  dimensionValues?: Record<string, string>
+  /** Branded segmented toggle options; omit to hide the section. */
+  brandedOptions?: BrandedOption[]
+  /** User-persisted saved filters. */
+  savedFilters?: SavedFilter[]
+  /** Built-in preset filters. */
+  presetFilters?: PresetFilter[]
+  /** The currently-applied preset id — shown active in the list. */
+  activePreset?: string
+  /** Count shown in the trigger badge. */
+  activeCount?: number
+  /** Trigger label. */
+  label?: string
+  /** Show the in-popover search input. Disable when the consumer renders its own. */
+  searchable?: boolean
+  /** Placeholder for the search input. */
+  searchPlaceholder?: string
+  /** Show the Saved Filters section (header + Save current + list). Disable on
+   *  surfaces that don't implement saved filters so no dead "Save current"
+   *  button renders. */
+  showSaved?: boolean
+}>()
+
+const emit = defineEmits<{
+  selectDimension: [value: string]
+  applySaved: [id: string]
+  removeSaved: [id: string]
+  applyPreset: [id: string]
+  save: []
+  clear: []
+}>()
+const search = defineModel<string>('search', { default: '' })
+const branded = defineModel<string>('branded', { default: '' })
+
+const open = ref(false)
+
+// Two-level popover: selecting a dimension row swaps the menu for that
+// dimension's value picker (rendered via the `#picker` slot) with a back
+// affordance, matching the seogets filter UX. Reset when the popover closes.
+const activeDimension = ref('')
+const activeDimensionLabel = computed(() => dimensions.find(d => d.value === activeDimension.value)?.label ?? '')
+const backBtn = ref<HTMLButtonElement | null>(null)
+const dimensionsRoot = ref<HTMLElement | null>(null)
+
+function openDimension(value: string) {
+  activeDimension.value = value
+  emit('selectDimension', value)
+}
+function closeDimension() {
+  activeDimension.value = ''
+}
+
+// Keep keyboard focus inside the popover when the sub-view swaps: focus the
+// back affordance on entering a dimension, and return focus to the originating
+// dimension row when leaving (falling back to the dimensions group).
+watch(activeDimension, async (value, prev) => {
+  await nextTick()
+  if (value) {
+    backBtn.value?.focus()
+  }
+  else if (prev) {
+    const row = dimensionsRoot.value?.querySelector<HTMLButtonElement>(`[data-dimension="${prev}"]`)
+    ;(row ?? dimensionsRoot.value?.querySelector<HTMLButtonElement>('button'))?.focus()
+  }
+})
+
+watch(open, (v) => {
+  if (!v)
+    activeDimension.value = ''
+})
+</script>
+
+<template>
+  <UiPopover v-model:open="open" :content="{ align: 'start', side: 'bottom', sideOffset: 8 }">
+    <button
+      type="button"
+      :aria-label="activeCount ? `Filter (${activeCount} active)` : 'Filter'"
+      :aria-expanded="open"
+      class="cursor-pointer inline-flex items-center justify-center gap-1.5 px-2 py-1.5 min-h-11 min-w-11 sm:min-h-0 sm:min-w-0 rounded-lg text-xs font-medium transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-primary outline-none"
+      :class="open || activeCount ? 'bg-elevated text-default' : 'text-muted hover:text-default hover:bg-[var(--ui-bg-elevated)]/50'"
+    >
+      <UiIcon name="filter" class="size-3.5" aria-hidden="true" />
+      <span data-toolbar-label>{{ label }}</span>
+      <span
+        v-if="activeCount"
+        class="min-w-4 px-1 h-4 inline-flex items-center justify-center rounded-full bg-primary text-inverted text-mini font-semibold tabular-nums"
+      >{{ activeCount }}</span>
+    </button>
+
+    <template #panel>
+      <div class="w-[270px] py-1.5">
+        <!-- Dimension value-picker sub-view: replaces the menu while a
+         dimension is active, with a back affordance. -->
+        <template v-if="activeDimension">
+          <button
+            ref="backBtn"
+            type="button"
+            :aria-label="`Back to filters, from ${activeDimensionLabel}`"
+            class="cursor-pointer w-full flex items-center gap-1.5 px-3 py-2.5 sm:py-1 text-xs font-medium text-muted hover:text-default transition-colors outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-inset"
+            @click="closeDimension"
+          >
+            <UiIcon name="chevron-left" class="size-3.5 shrink-0" aria-hidden="true" />
+            <span>{{ activeDimensionLabel }}</span>
+          </button>
+          <div class="mx-3 my-1.5 border-t border-default/50" role="separator" />
+          <div class="px-2.5 pb-1">
+            <slot name="picker" :dimension="activeDimension" :close="closeDimension" />
+          </div>
+        </template>
+
+        <template v-else>
+          <!-- Active-filter header + one-click clear (only when something is applied). -->
+          <div v-if="activeCount" class="px-3 pt-0.5 pb-1.5 flex items-center justify-between">
+            <UiMetricLabel aria-hidden="true">
+              {{ activeCount }} active
+            </UiMetricLabel>
+            <button
+              type="button"
+              aria-label="Clear all filters"
+              class="min-h-11 cursor-pointer rounded text-mini text-muted outline-none hover:text-default focus-visible:ring-2 focus-visible:ring-primary sm:min-h-0"
+              @click="emit('clear')"
+            >
+              Clear all
+            </button>
+          </div>
+
+          <!-- Search -->
+          <div v-if="searchable" class="px-2 pb-1.5">
+            <UInput
+              v-model="search"
+              type="search"
+              :placeholder="searchPlaceholder"
+              :aria-label="searchPlaceholder"
+              icon="search"
+              size="xs"
+              class="w-full"
+              autocomplete="off"
+            />
+          </div>
+
+          <!-- Facets slot (consumer-rendered value editors, e.g. country/device) -->
+          <div v-if="$slots.facets" class="px-2.5 pb-1.5">
+            <slot name="facets" />
+          </div>
+
+          <!-- Dimension shortcuts -->
+          <div v-if="dimensions.length" ref="dimensionsRoot" role="group" aria-label="Filter dimensions">
+            <button
+              v-for="d in dimensions"
+              :key="d.value"
+              type="button"
+              :data-dimension="d.value"
+              :aria-label="`${d.label}${dimensionValues[d.value] ? `: ${dimensionValues[d.value]}` : ''}`"
+              class="cursor-pointer w-full flex items-center gap-2 px-3 py-2.5 sm:py-1 text-xs text-muted hover:text-default hover:bg-[var(--ui-bg-elevated)]/50 transition-colors outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-inset"
+              @click="openDimension(d.value)"
+            >
+              <UiIcon :name="d.icon" class="size-3.5 shrink-0 text-dimmed" aria-hidden="true" />
+              <span class="flex-1 text-left">{{ d.label }}</span>
+              <span v-if="dimensionValues[d.value]" class="text-default font-medium truncate max-w-28">{{ dimensionValues[d.value] }}</span>
+              <UiIcon name="chevron-right" class="size-3 shrink-0 text-dimmed" aria-hidden="true" />
+            </button>
+          </div>
+
+          <!-- Branded toggle -->
+          <template v-if="brandedOptions.length">
+            <div class="mx-3 my-1.5 border-t border-default/50" role="separator" />
+            <div class="px-3 pb-1">
+              <UiMetricLabel aria-hidden="true">
+                Branded
+              </UiMetricLabel>
+            </div>
+            <div class="px-2.5 pb-1">
+              <ToggleGroupRoot
+                :model-value="branded"
+                type="single"
+                aria-label="Branded filter"
+                class="flex items-center gap-1 p-0.5 rounded-md bg-[var(--ui-bg-elevated)]/60"
+                @update:model-value="(v: unknown) => { if (typeof v === 'string' && v) branded = v }"
+              >
+                <ToggleGroupItem
+                  v-for="b in brandedOptions"
+                  :key="b.value"
+                  :value="b.value"
+                  class="cursor-pointer flex-1 inline-flex items-center justify-center gap-1 px-2 py-1 rounded text-mini font-medium whitespace-nowrap transition-colors outline-none focus-visible:ring-2 focus-visible:ring-primary"
+                  :class="branded === b.value
+                    ? 'bg-default text-default'
+                    : 'text-muted hover:text-default'"
+                >
+                  <UiIcon v-if="b.icon" :name="b.icon" class="size-3" aria-hidden="true" />
+                  <span>{{ b.label }}</span>
+                </ToggleGroupItem>
+              </ToggleGroupRoot>
+            </div>
+          </template>
+
+          <!-- Saved filters -->
+          <template v-if="showSaved">
+            <div class="mx-3 my-1.5 border-t border-default/50" role="separator" />
+            <div class="px-3 pb-1 flex items-center justify-between">
+              <UiMetricLabel aria-hidden="true">
+                Saved Filters
+              </UiMetricLabel>
+              <button
+                type="button"
+                class="cursor-pointer text-mini text-primary hover:underline outline-none focus-visible:ring-2 focus-visible:ring-primary rounded"
+                @click="emit('save')"
+              >
+                Save current
+              </button>
+            </div>
+            <div v-if="savedFilters.length" role="group" aria-label="Saved filters">
+              <div
+                v-for="s in savedFilters"
+                :key="s.id"
+                class="group w-full flex items-center gap-2 px-3 py-2.5 sm:py-1 text-xs text-muted hover:bg-[var(--ui-bg-elevated)]/50 transition-colors"
+              >
+                <button
+                  type="button"
+                  class="cursor-pointer flex-1 flex items-center gap-2 text-left hover:text-default outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-inset rounded"
+                  @click="emit('applySaved', s.id)"
+                >
+                  <UiIcon name="bookmark" class="size-3.5 shrink-0 text-dimmed" aria-hidden="true" />
+                  <span class="truncate">{{ s.label }}</span>
+                </button>
+                <button
+                  type="button"
+                  :aria-label="`Remove saved filter ${s.label}`"
+                  class="cursor-pointer opacity-0 group-hover:opacity-100 focus-visible:opacity-100 text-dimmed hover:text-error transition-[color,opacity] outline-none focus-visible:ring-2 focus-visible:ring-primary rounded"
+                  @click="emit('removeSaved', s.id)"
+                >
+                  <UiIcon name="close" class="size-3" aria-hidden="true" />
+                </button>
+              </div>
+            </div>
+            <p v-else class="px-3 pb-1 text-mini text-dimmed leading-snug">
+              Add filters and save them to quickly access them later.
+            </p>
+          </template>
+
+          <!-- Preset filters -->
+          <template v-if="presetFilters.length">
+            <div class="mx-3 my-1.5 border-t border-default/50" role="separator" />
+            <div class="px-3 pb-1">
+              <UiMetricLabel aria-hidden="true">
+                Preset Filters
+              </UiMetricLabel>
+            </div>
+            <div role="group" aria-label="Preset filters">
+              <button
+                v-for="p in presetFilters"
+                :key="p.id"
+                type="button"
+                :aria-pressed="activePreset === p.id"
+                class="relative flex min-h-11 w-full cursor-pointer items-center gap-2 px-3 py-2.5 text-xs outline-none transition-colors focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-inset sm:min-h-0 sm:py-1"
+                :class="activePreset === p.id
+                  ? 'text-default bg-elevated'
+                  : 'text-muted hover:text-default hover:bg-[var(--ui-bg-elevated)]/50'"
+                @click="emit('applyPreset', p.id)"
+              >
+                <span
+                  v-if="activePreset === p.id"
+                  class="absolute left-0 inset-y-0.5 w-[2px] rounded-full bg-primary"
+                  aria-hidden="true"
+                />
+                <UiIcon :name="p.icon ?? 'ai'" class="size-3.5 shrink-0 text-dimmed" aria-hidden="true" />
+                <span class="flex-1 text-left">{{ p.label }}</span>
+                <UiIcon
+                  v-if="activePreset === p.id"
+                  name="check"
+                  class="size-3 text-primary"
+                  aria-hidden="true"
+                />
+              </button>
+            </div>
+          </template>
+        </template>
+      </div>
+    </template>
+  </UiPopover>
+</template>

package/app/components/element/UiFocusedSurface.vue

@@ -0,0 +1,129 @@
+<script setup lang="ts">
+import { useHead } from 'nuxt/app'
+import { ClientOnly, UiAtmosphere, UiIcon, ULink } from '#components'
+import { useColorMode } from '#imports'
+// The focused, full-bleed surface shared by the auth screens (login, sign-up)
+// and the onboarding wizard: dashboard-theme scope, a masked dot-grid backdrop,
+// and a top-left exit link. No dashboard chrome. The single source of this
+// substrate — the pro-auth layout and UiWizardShell both compose it, and the
+// brand-kit showcase renders it directly.
+//
+// Height is the consumer's call (attrs fall through to the root <main>): the
+// live pages pass `min-h-screen`; an embedded preview passes a fixed height.
+//
+//  - align="center" centres a single child both axes (auth card).
+//  - align="top" stacks content from the top (wizard column).
+//  - exitTo renders a real link; otherwise the exit affordance emits `exit`.
+const {
+  align = 'center',
+  exitLabel = 'Home',
+  exitTo,
+  exitExternal = false,
+  showExit = true,
+  as = 'main',
+} = defineProps<{
+  align?: 'center' | 'top'
+  exitLabel?: string
+  exitTo?: string
+  exitExternal?: boolean
+  showExit?: boolean
+  /**
+   * Root element. Defaults to `main` (the page-level landmark) for the real
+   * full-page surfaces. Pass `as="div"` when more than one surface renders on a
+   * page (e.g. the brand-kit showcase) to avoid duplicate `<main>` landmarks.
+   */
+  as?: string
+}>()
+
+const emit = defineEmits<{ exit: [] }>()
+const colorMode = useColorMode()
+
+function toggleColorMode() {
+  colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
+}
+
+// The dashboard palette is keyed on `.dark.dashboard-theme` / `.light.dashboard-theme`
+// — BOTH classes on the same element — and the color-mode class only ever lands
+// on `<html>`. A `dashboard-theme` that sits on this div alone therefore misses
+// every `--ui-bg-*` / `--ui-text-*` override and the surface silently renders on
+// the marketing slate palette: in dark that means page background and outline
+// controls both resolve to the same near-black, so inputs and buttons vanish.
+// Mirror it onto `<html>` whenever this surface IS the page (as="main"); an
+// embedded preview (`as="div"`, brand-kit) must not restyle its host page.
+if (as === 'main')
+  useHead({ htmlAttrs: { class: 'dashboard-theme' } })
+</script>
+
+<template>
+  <component
+    :is="as"
+    class="ui-focused dashboard-theme relative overflow-hidden flex flex-col items-center px-4 pb-10"
+    :class="[
+      align === 'center' ? 'justify-center' : '',
+      as === 'main' && showExit ? 'pt-20 sm:pt-10' : 'pt-10',
+    ]"
+    :data-align="align"
+  >
+    <UiAtmosphere preset="front-door" />
+    <div aria-hidden="true" class="ui-focused-dots pointer-events-none absolute inset-0" />
+
+    <ULink
+      v-if="showExit && exitTo"
+      :to="exitTo"
+      :external="exitExternal"
+      class="absolute top-3 left-3 z-10 inline-flex min-h-11 items-center gap-1 px-2 text-sm text-muted transition-colors hover:text-highlighted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary rounded-md sm:top-5 sm:left-5"
+    >
+      <UiIcon name="back" class="size-3.5 shrink-0" aria-hidden="true" />
+      <span class="leading-none">{{ exitLabel }}</span>
+    </ULink>
+    <button
+      v-else-if="showExit"
+      type="button"
+      class="absolute top-3 left-3 z-10 inline-flex min-h-11 items-center gap-1 px-2 text-sm text-muted transition-colors hover:text-highlighted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary rounded-md sm:top-5 sm:left-5"
+      @click="emit('exit')"
+    >
+      <UiIcon name="back" class="size-3.5 shrink-0" aria-hidden="true" />
+      <span class="leading-none">{{ exitLabel }}</span>
+    </button>
+
+    <ClientOnly v-if="as === 'main'">
+      <button
+        type="button"
+        class="group/theme absolute top-3 right-3 z-10 inline-flex size-11 items-center justify-center rounded-xl text-muted transition-colors hover:text-highlighted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary sm:top-5 sm:right-5"
+        :aria-label="`Switch to ${colorMode.value === 'dark' ? 'light' : 'dark'} mode`"
+        :title="`Switch to ${colorMode.value === 'dark' ? 'light' : 'dark'} mode`"
+        @click="toggleColorMode"
+      >
+        <span class="inline-flex size-8 items-center justify-center rounded-lg bg-default/60 ring-1 ring-default backdrop-blur-sm transition-colors group-hover/theme:bg-elevated">
+          <UiIcon
+            :name="colorMode.value === 'dark' ? 'light' : 'dark'"
+            class="size-4"
+            aria-hidden="true"
+          />
+        </span>
+      </button>
+      <template #fallback>
+        <span class="absolute top-3 right-3 size-11 sm:top-5 sm:right-5" aria-hidden="true" />
+      </template>
+    </ClientOnly>
+
+    <slot />
+  </component>
+</template>
+
+<style scoped>
+.ui-focused-dots {
+  background-image: radial-gradient(circle at 1px 1px, color-mix(in oklab, var(--ui-bg-inverted) 8%, transparent) 1px, transparent 0);
+  background-size: 28px 28px;
+}
+
+.ui-focused[data-align="center"] .ui-focused-dots {
+  mask-image: radial-gradient(ellipse 60% 50% at 50% 50%, black 0%, transparent 75%);
+  -webkit-mask-image: radial-gradient(ellipse 60% 50% at 50% 50%, black 0%, transparent 75%);
+}
+
+.ui-focused[data-align="top"] .ui-focused-dots {
+  mask-image: radial-gradient(ellipse 70% 50% at 50% 30%, black 0%, transparent 75%);
+  -webkit-mask-image: radial-gradient(ellipse 70% 50% at 50% 30%, black 0%, transparent 75%);
+}
+</style>

package/app/components/element/UiHealthDot.vue

@@ -0,0 +1,32 @@
+<script setup lang="ts">
+import type { HealthStatus } from '../../composables/semanticColors'
+import { healthColors } from '../../composables/semanticColors'
+
+const { health = 'unknown', size = 'sm', pulse = false, label } = defineProps<{
+  health?: HealthStatus | null
+  size?: 'xs' | 'sm' | 'md'
+  pulse?: boolean
+  /**
+   * Accessible name for the status. Pass when the dot stands alone (no adjacent
+   * text), so the color is not the only channel conveying state. Omit when a
+   * visible text label sits next to the dot — it stays decorative then.
+   */
+  label?: string
+}>()
+
+const sizeClass = { xs: 'size-1.5', sm: 'size-2', md: 'size-2.5' } as const
+</script>
+
+<template>
+  <span
+    class="rounded-full shrink-0"
+    :class="[
+      sizeClass[size],
+      healthColors(health).dot,
+      pulse && 'motion-safe:animate-pulse',
+    ]"
+    :role="label ? 'img' : undefined"
+    :aria-label="label || undefined"
+    :aria-hidden="label ? undefined : 'true'"
+  />
+</template>

package/app/components/element/UiHelpLabel.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import { UiIcon, UiTooltip } from '#components'
+/**
+ * UiHelpLabel
+ *
+ * Label text with an inline (?) help icon that shows a tooltip on hover.
+ * Used by UiStat, UiDataList, and anywhere a title needs contextual help.
+ */
+const { text, tooltip, tooltipTitle } = defineProps<{
+  text: string
+  tooltip: string
+  /** Bold title in tooltip panel. Defaults to `text`. */
+  tooltipTitle?: string
+}>()
+</script>
+
+<template>
+  <UiTooltip :title="tooltipTitle || text" :description="tooltip" trigger-as="button">
+    <!-- The trigger is a button, which centres its text; a label that wraps
+         must stay start-aligned like the heading it sits in. `mx-0.5` cancels
+         the button's `-m-0.5` hit-area bleed, so the label starts on the same
+         edge as a plain heading beside it. -->
+    <span class="mx-0.5 inline-flex items-center gap-1 text-left">
+      {{ text }}
+      <UiIcon name="help" class="size-3 opacity-50 shrink-0" aria-hidden="true" />
+    </span>
+  </UiTooltip>
+</template>

package/app/components/element/UiIcon.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import type { UiIcon } from '../../shared/ui-icons'
+import { UIcon } from '#components'
+
+/**
+ * UiIcon — the icon primitive. A thin, typed wrapper over Nuxt UI's `<UIcon>`.
+ *
+ * The `name` is a curated semantic role (`refresh`, `next`, `delete`, …) or an
+ * explicitly sourced `i-*` id. Roles resolve to the active set's icon via @nuxt/icon's global aliases
+ * (registered in the design-system nuxt.config from the registry), so this component
+ * passes `name` straight through — no runtime registry, nothing extra shipped to the
+ * client. The `UiIcon` type keeps role autocomplete; type-only import is erased at build.
+ *
+ * The brand-kit set comparison calls `resolveUiIcon(role, set)` and feeds the
+ * resulting whitelisted id back through this primitive.
+ */
+const { name } = defineProps<{ name?: UiIcon }>()
+</script>
+
+<template>
+  <UIcon :name="name" />
+</template>

package/app/components/element/UiInput.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts" generic="T extends InputValue = InputValue">
+import type { InputEmits, InputProps, InputValue } from '@nuxt/ui'
+import { UInput } from '#components'
+
+/**
+ * UiInput — thin wrapper around Nuxt UI v4's UInput.
+ *
+ * Tokens (radius, ring, background) are already centralized in
+ * `app.config.ts`'s `ui.input` — this component isn't a re-theme, it's the
+ * single legal entry point for `<input>`-style fields (raw `<UInput>` is
+ * ESLint-banned via `eslint/selectors.ts`) so a future behavioral change
+ * lands in one file instead of another repo-wide sweep. Every prop, emit,
+ * and slot passes straight through unchanged.
+ */
+
+defineOptions({ inheritAttrs: false })
+
+const props = defineProps<Props>()
+const emit = defineEmits<InputEmits<T>>()
+type Props = Omit<InputProps<T>, 'defaultValue'>
+</script>
+
+<template>
+  <!-- @vue-generic {T, NonNullable<InputProps<T>['modelModifiers']>} -->
+  <UInput
+    v-bind="{ ...props, ...$attrs }"
+    @update:model-value="emit('update:modelValue', $event)"
+    @blur="emit('blur', $event)"
+    @change="emit('change', $event)"
+  >
+    <template v-for="(_, name) in ($slots as Record<string, unknown>)" #[name]="slotProps" :key="name">
+      <slot :name="name" v-bind="slotProps || {}" />
+    </template>
+  </UInput>
+</template>

package/app/components/element/UiLogoPlausible.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// Official Plausible Analytics brand mark, brand colour #5850EC baked into the
+// asset (single-colour mark — there is no multicolour version). Inline SVG so the
+// colour survives, vs an icon set that would monotone it to currentColor.
+// Sizing/aria fall through from the parent (e.g. class="size-6").
+</script>
+
+<template>
+  <svg viewBox="0 0 24 24" fill="#5850EC" xmlns="http://www.w3.org/2000/svg">
+    <path d="M12.1835.0017c-.6378-.0097-1.2884.022-1.7246.0996C8.601.424 7.035 1.2116 5.7384 2.4782 4.406 3.7806 3.582 5.299 3.1818 7.1929l-.1387.6445c-.0118 5.3872-.0233 10.7744-.035 16.1617.2914.0081.591-.0392.8416-.0606 2.348-.2868 4.3442-1.7083 5.4315-3.8651.2749-.5497.472-1.182.6094-1.9707.1135-.6691.1195-.8915.1016-4.3807l-.0176-3.6737.1425-.3574c.1972-.49.7425-1.0352 1.2324-1.2324l.3574-.1426 3.3457-.0058c1.8401 0 3.4545-.025 3.58-.0489.5854-.1135 1.2118-.6027 1.4628-1.1464.0717-.1494.1671-.4415.209-.6387.0657-.3286.0604-.4186-.0352-.789-.2987-1.0993-1.3503-2.6234-2.4257-3.5136C16.6247 1.1638 15.2798.4887 13.828.1482c-.3824-.0866-1.0067-.1368-1.6445-.1465zm8.5369 6.8006c-.0506.1798-.098.3662-.172.5215-.3358.7278-1.0382 1.2776-1.8221 1.4296-3.6737.0566-2.5392.0561-3.6737.0566l-3.248.0059-.2695.1074c-.3135.1262-.827.6397-.9531.9531l-.1074.2676.0175 3.576c.0149 2.8888.007 3.5821-.0605 4.125a8.9918 8.9918 0 0 0 1.5683.1386c4.9662.0001 8.992-4.0258 8.992-8.992a8.9918 8.9918 0 0 0-.2715-2.1893Z" />
+  </svg>
+</template>