@nuxtseo/design-system 0.1.0 → 0.1.2

package/app/utils/app-favicon.ts

@@ -0,0 +1,64 @@
+/**
+ * The app's own theme-aware favicon and touch icon, set under `favicon` in
+ * app.config. Every path is optional: the layer ships no brand images, so an
+ * unset path emits no link. A mode with no path of its own uses the other
+ * mode's path.
+ */
+export interface AppFaviconConfig {
+  light?: string
+  dark?: string
+  appleTouchLight?: string
+  appleTouchDark?: string
+}
+
+export type AppFaviconLink
+  = { id: 'favicon', rel: 'icon', href: string, type?: string, sizes?: string }
+    | { id: 'apple-touch-icon', rel: 'apple-touch-icon', href: string, sizes: string }
+
+const MIME_BY_EXTENSION: Readonly<Record<string, string>> = {
+  avif: 'image/avif',
+  gif: 'image/gif',
+  ico: 'image/x-icon',
+  jpeg: 'image/jpeg',
+  jpg: 'image/jpeg',
+  png: 'image/png',
+  svg: 'image/svg+xml',
+  webp: 'image/webp',
+}
+
+/** The MIME type a favicon path declares, read from its extension. Undefined for an unknown extension. */
+export function faviconMimeType(href: string): string | undefined {
+  const path = href.split(/[?#]/, 1)[0] ?? ''
+  const extension = /\.([a-z0-9]+)$/i.exec(path)?.[1]?.toLowerCase()
+  return extension === undefined ? undefined : MIME_BY_EXTENSION[extension]
+}
+
+function pick(dark: boolean, light: string | undefined, darkPath: string | undefined): string | undefined {
+  return dark ? (darkPath ?? light) : (light ?? darkPath)
+}
+
+function iconSizes(type: string | undefined): string | undefined {
+  if (type === 'image/svg+xml')
+    return 'any'
+  if (type === 'image/x-icon')
+    return undefined
+  return '32x32'
+}
+
+/**
+ * The head links for the app's favicon in one colour mode. The ids let an app
+ * replace either link with its own `useHead` entry.
+ */
+export function appFaviconLinks(config: AppFaviconConfig | undefined, dark: boolean): AppFaviconLink[] {
+  const links: AppFaviconLink[] = []
+  const icon = pick(dark, config?.light, config?.dark)
+  if (icon !== undefined) {
+    const type = faviconMimeType(icon)
+    const sizes = iconSizes(type)
+    links.push({ id: 'favicon', rel: 'icon', ...(type ? { type } : {}), ...(sizes ? { sizes } : {}), href: icon })
+  }
+  const touch = pick(dark, config?.appleTouchLight, config?.appleTouchDark)
+  if (touch !== undefined)
+    links.push({ id: 'apple-touch-icon', rel: 'apple-touch-icon', sizes: '180x180', href: touch })
+  return links
+}

package/build/design-system.ts

@@ -1,8 +1,11 @@
 import type { ModuleOptions as IconModuleOptions } from '@nuxt/icon'
 import type { NuxtOptions } from 'nuxt/schema'
 import type { IconSet } from '../shared/icons'
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs'
 import { defineNuxtModule } from 'nuxt/kit'
+import { dirname, resolve } from 'pathe'
 import { iconAliasMap, iconBundleList, parseIconSet } from '../shared/icons'
+import { externalLinkMarkerCss } from './external-links'
 
 export interface DesignSystemOptions {
   /**
@@ -10,6 +13,19 @@ export interface DesignSystemOptions {
    * Install the matching `@iconify-json/<set>` collection in the app.
    */
   iconSet?: IconSet
+  /**
+   * Keep the layer's composables and utils in the app's auto-import scan, and
+   * so in `#imports`. Defaults to false: their names, such as a one-argument
+   * `formatNumber`, would clash with a site's own helpers. A site imports
+   * them by path instead. Nuxt SEO's private `layers/brand` turns it on.
+   */
+  autoImportUtils?: boolean
+  /**
+   * Hosts that count as this site. An absolute prose link to one of them gets
+   * no external-link arrow. Defaults to none, so every absolute http(s) link
+   * is marked. Matches a substring of the href after `//`, so list `www.` too.
+   */
+  internalLinkHosts?: string[]
 }
 
 /**
@@ -43,5 +59,47 @@ export default defineNuxtModule<DesignSystemOptions>({
     icon.aliases = { ...iconAliasMap(iconSet), ...icon.aliases }
     icon.clientBundle ??= {}
     icon.clientBundle.icons = [...new Set([...iconBundleList(iconSet), ...(icon.clientBundle.icons ?? [])])]
+
+    // A plain file, not a Nuxt template. In dev, Nuxt links every
+    // `nuxt.options.css` entry the module graph has not loaded, matching by
+    // file path. The graph holds a template as a `virtual:nuxt:` id with no
+    // such path, so a template stylesheet was linked twice, the second copy
+    // after the site's own CSS. The CLI clears the build directory after
+    // modules load, so the file is written when the build starts.
+    const externalLinks = resolve(nuxt.options.buildDir, 'design-system/external-links.css')
+    nuxt.options.css.push(externalLinks)
+    nuxt.hook('build:before', () => {
+      mkdirSync(dirname(externalLinks), { recursive: true })
+      writeFileSync(externalLinks, externalLinkMarkerCss(options.internalLinkHosts ?? []))
+    })
+
+    // The layer's templates pass `aria-*` attributes and a few listeners to
+    // components through $attrs, and `app/component-attributes.d.ts` types
+    // them. A consumer's tsconfig excludes node_modules, so the declaration
+    // never reached its program and a TypeScript 7 native typecheck failed
+    // inside the layer's templates. A reference ignores that exclude.
+    nuxt.hook('prepare:types', ({ references }) => {
+      references.push({ path: resolve(LAYER_ROOTS[0]!, 'app/component-attributes.d.ts') })
+    })
+
+    // Nuxt scans every layer's composables/ and utils/ for auto-imports, and a
+    // layer's `imports.scan: false` would merge into the app and stop its scan
+    // too. So the layer removes only its own directories here.
+    if (!options.autoImportUtils) {
+      nuxt.hook('imports:dirs', (dirs) => {
+        const kept = dirs.filter(dir => !isLayerPath(dir))
+        dirs.splice(0, dirs.length, ...kept)
+      })
+    }
   },
 })
+
+const LAYER_ROOTS = [...new Set([resolve(import.meta.dirname, '..'), resolve(realpathSync(resolve(import.meta.dirname, '..')))])]
+
+/** Whether a directory sits inside this layer, through a symlink or not. */
+export function isLayerPath(dir: string): boolean {
+  const paths = [resolve(dir)]
+  if (existsSync(dir))
+    paths.push(resolve(realpathSync(dir)))
+  return paths.some(path => LAYER_ROOTS.some(root => path === root || path.startsWith(`${root}/`)))
+}

package/build/external-links.ts

@@ -0,0 +1,38 @@
+/**
+ * The external-link arrow on outbound prose links. Only an absolute http(s)
+ * link that leaves the site gets it; a relative link never matches, and a
+ * link around an image is excluded because the arrow would hang off the
+ * corner of the figure.
+ *
+ * Which hosts count as this site is a brand choice, so the rules are built
+ * from `designSystem.internalLinkHosts`. A CSS custom property cannot feed an
+ * attribute selector, so the hosts have to reach the selector at build time.
+ *
+ * The marker is a background on a pseudo-element whose only content is a
+ * no-break space: the NBSP glues the arrow to the last word, so it can never
+ * orphan onto a line of its own, and there is no text for a screen reader to
+ * announce. The mask resolves `currentColor` against the image's own initial
+ * colour, which is opaque black, so the arrow always paints in the link's
+ * colour and the CSS holds no colour of its own.
+ */
+export function externalLinkMarkerCss(internalHosts: readonly string[]): string {
+  const own = internalHosts
+    .map(host => `:not([href*="//${host.replace(/["\\]/g, '\\$&')}"])`)
+    .join('')
+  const link = `a.prose-link[href^="http"]${own}:not(:has(img))`
+  return `${link}::after {
+  content: '\\00a0';
+  padding-inline-end: 0.72em;
+  background-color: currentcolor;
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M7 7h10v10'/%3E%3Cpath d='M7 17 17 7'/%3E%3C/svg%3E");
+  mask-repeat: no-repeat;
+  mask-position: right center;
+  mask-size: 0.72em 0.72em;
+  opacity: 0.65;
+  vertical-align: baseline;
+}
+${link}:hover::after {
+  opacity: 1;
+}
+`
+}

package/css/global.css

@@ -1,9 +1,14 @@
 @import 'tailwindcss';
 @import '@nuxt/ui';
 
+/* Type families. A site sets its own in an unlayered `:root` rule; OG images
+   read them from the Tailwind entry instead (README, Brand seams). `--font-title`
+   carries page titles (`.text-title`, `font-title`) and defaults to the display
+   family. The layer registers no faces; a site loads its own (README). */
 @theme {
   --font-sans: 'Hubot Sans', sans-serif;
   --font-display: 'Hubot Sans', sans-serif;
+  --font-title: 'Hubot Sans', sans-serif;
   --font-mono: 'Fira Code', monospace;
 }
 
@@ -271,11 +276,40 @@
   --color-viz-resource-image: var(--ui-viz-resource-image, var(--_viz-resource-image, var(--color-cyan-500)));
   --color-viz-resource-font: var(--ui-viz-resource-font, var(--color-pink-500));
 
-  --text-color-viz-inp: var(--ui-viz-inp, var(--ui-text-warning));
-  --text-color-viz-device-tablet: var(--ui-viz-device-tablet, var(--ui-text-warning));
-  --text-color-viz-rank-7: var(--ui-viz-rank-7, var(--ui-text-warning));
-  --text-color-viz-current: var(--ui-viz-current, var(--_viz-current-text));
-  --text-color-viz-comparison: var(--ui-viz-comparison, var(--_viz-comparison-text));
+  /* Text side. `--ui-viz-<slot>-text` recolours only the `text-viz-<slot>`
+     class, for a mark hue that fails AA as text; unset, text follows the mark. */
+  --text-color-viz-clicks: var(--ui-viz-clicks-text, var(--ui-viz-clicks, var(--color-blue-500)));
+  --text-color-viz-impressions: var(--ui-viz-impressions-text, var(--ui-viz-impressions, var(--color-purple-500)));
+  --text-color-viz-ctr: var(--ui-viz-ctr-text, var(--ui-viz-ctr, var(--_viz-ctr, var(--color-emerald-500))));
+  --text-color-viz-position: var(--ui-viz-position-text, var(--ui-viz-position, var(--_viz-position, var(--color-orange-500))));
+  --text-color-viz-sessions: var(--ui-viz-sessions-text, var(--ui-viz-sessions, var(--color-blue-500)));
+  --text-color-viz-users: var(--ui-viz-users-text, var(--ui-viz-users, var(--_viz-users, var(--color-cyan-500))));
+  --text-color-viz-pageviews: var(--ui-viz-pageviews-text, var(--ui-viz-pageviews, var(--color-purple-500)));
+  --text-color-viz-lcp: var(--ui-viz-lcp-text, var(--ui-viz-lcp, var(--color-blue-500)));
+  --text-color-viz-inp: var(--ui-viz-inp-text, var(--ui-viz-inp, var(--ui-text-warning)));
+  --text-color-viz-cls: var(--ui-viz-cls-text, var(--ui-viz-cls, var(--color-purple-500)));
+  --text-color-viz-current: var(--ui-viz-current-text, var(--ui-viz-current, var(--_viz-current-text)));
+  --text-color-viz-comparison: var(--ui-viz-comparison-text, var(--ui-viz-comparison, var(--_viz-comparison-text)));
+  --text-color-viz-device-desktop: var(--ui-viz-device-desktop-text, var(--ui-viz-device-desktop, var(--_viz-device-desktop, var(--color-blue-400))));
+  --text-color-viz-device-mobile: var(--ui-viz-device-mobile-text, var(--ui-viz-device-mobile, var(--_viz-device-mobile, var(--color-green-400))));
+  --text-color-viz-device-tablet: var(--ui-viz-device-tablet-text, var(--ui-viz-device-tablet, var(--ui-text-warning)));
+  --text-color-viz-brand: var(--ui-viz-brand-text, var(--ui-viz-brand, var(--color-violet-500)));
+  --text-color-viz-non-brand: var(--ui-viz-non-brand-text, var(--ui-viz-non-brand, var(--_viz-non-brand, var(--color-emerald-500))));
+  --text-color-viz-rank-1: var(--ui-viz-rank-1-text, var(--ui-viz-rank-1, var(--color-blue-500)));
+  --text-color-viz-rank-2: var(--ui-viz-rank-2-text, var(--ui-viz-rank-2, var(--color-purple-500)));
+  --text-color-viz-rank-3: var(--ui-viz-rank-3-text, var(--ui-viz-rank-3, var(--_viz-rank-3, var(--color-emerald-400))));
+  --text-color-viz-rank-4: var(--ui-viz-rank-4-text, var(--ui-viz-rank-4, var(--_viz-rank-4, var(--color-orange-500))));
+  --text-color-viz-rank-5: var(--ui-viz-rank-5-text, var(--ui-viz-rank-5, var(--_viz-rank-5, var(--color-cyan-500))));
+  --text-color-viz-rank-6: var(--ui-viz-rank-6-text, var(--ui-viz-rank-6, var(--color-pink-500)));
+  --text-color-viz-rank-7: var(--ui-viz-rank-7-text, var(--ui-viz-rank-7, var(--ui-text-warning)));
+  --text-color-viz-rank-8: var(--ui-viz-rank-8-text, var(--ui-viz-rank-8, var(--color-indigo-400)));
+  --text-color-viz-rank-9: var(--ui-viz-rank-9-text, var(--ui-viz-rank-9, var(--_viz-rank-9, var(--color-teal-400))));
+  --text-color-viz-rank-10: var(--ui-viz-rank-10-text, var(--ui-viz-rank-10, var(--_viz-rank-10, var(--color-rose-400))));
+  --text-color-viz-resource-document: var(--ui-viz-resource-document-text, var(--ui-viz-resource-document, var(--color-blue-500)));
+  --text-color-viz-resource-script: var(--ui-viz-resource-script-text, var(--ui-viz-resource-script, var(--_viz-resource-script, var(--color-orange-500))));
+  --text-color-viz-resource-stylesheet: var(--ui-viz-resource-stylesheet-text, var(--ui-viz-resource-stylesheet, var(--color-purple-500)));
+  --text-color-viz-resource-image: var(--ui-viz-resource-image-text, var(--ui-viz-resource-image, var(--_viz-resource-image, var(--color-cyan-500))));
+  --text-color-viz-resource-font: var(--ui-viz-resource-font-text, var(--ui-viz-resource-font, var(--color-pink-500)));
 }
 
 :root {
@@ -541,7 +575,13 @@
   touch-action: manipulation;
 }
 
-.light {
+/* Surface seam. The mode and dashboard blocks below sit in `:where()`, so
+   they carry no specificity: a site's plain `:root` rule sets any surface
+   token in both modes, and its `.dark` rule sets dark, whichever stylesheet
+   loads last. Nuxt UI's own defaults sit in `@layer theme` and still lose to
+   these. Source order decides between these blocks, so the dashboard blocks
+   stay after the mode blocks. */
+:where(.light) {
   color-scheme: light;
   /* Bind surfaces to `--ui-color-neutral-*` (Nuxt UI's neutral alias → the
      hue-292 slate override) rather than stock `--color-neutral-*` (cold hue
@@ -552,11 +592,13 @@
   --ui-bg-elevated: var(--ui-color-neutral-100);
   --ui-bg-accented: var(--ui-color-neutral-200);
   --ui-bg-inverted: var(--ui-color-neutral-900);
-  --ui-text-dimmed: oklch(47.5% 0.052 292);
+  /* Text seam. These three sit on Nuxt SEO's violet hue, off the neutral
+     ramp; a site re-hues them by setting `--ui-light-text*` (README). */
+  --ui-text-dimmed: var(--ui-light-text-dimmed, oklch(47.5% 0.052 292));
   --ui-text-muted: var(--ui-color-neutral-600);
   --ui-text-toned: var(--ui-color-neutral-700);
-  --ui-text: oklch(37% 0.044 285);
-  --ui-text-highlighted: oklch(21% 0.042 285);
+  --ui-text: var(--ui-light-text, oklch(37% 0.044 285));
+  --ui-text-highlighted: var(--ui-light-text-highlighted, oklch(21% 0.042 285));
   --ui-text-inverted: #fff;
   --ui-border: var(--ui-color-neutral-200);
   --ui-border-muted: var(--ui-color-neutral-100);
@@ -573,7 +615,7 @@
   --nuxtseo-brand-tile-ink: oklch(98.4% 0.005 292);
 }
 
-.dark {
+:where(.dark) {
   color-scheme: dark;
   /* Tier ladder in dark: 8.5 → 15 → 21 → 30. The old 7.5 → 13 gap read flat
      on large surfaces; the new deltas give nav / body / elevated cards a
@@ -1155,29 +1197,30 @@ textarea {
 .section-accent-sky { @apply bg-sky-50 dark:bg-sky-500/5 border-sky-200/50 dark:border-sky-500/10; }
 
 /* Dashboard mauve palette: editorial monochrome tone reserved for /pro/dashboard.
-   Marketing/docs pages stay on the warm-slate neutral (hue 285). */
-.dashboard-theme {
-  --ui-color-neutral-50: var(--color-mauve-50, oklch(98.5% 0 0));
-  --ui-color-neutral-100: var(--color-mauve-100, oklch(96.7% 0.001 286.375));
-  --ui-color-neutral-200: var(--color-mauve-200, oklch(92% 0.004 286.32));
-  --ui-color-neutral-300: var(--color-mauve-300, oklch(87.1% 0.006 286.286));
-  --ui-color-neutral-400: var(--color-mauve-400, oklch(70.5% 0.015 286.067));
-  --ui-color-neutral-500: var(--color-mauve-500, oklch(55.2% 0.016 285.938));
-  --ui-color-neutral-600: var(--color-mauve-600, oklch(44.2% 0.017 285.786));
-  --ui-color-neutral-700: var(--color-mauve-700, oklch(37.4% 0.016 285.822));
-  --ui-color-neutral-800: var(--color-mauve-800, oklch(27.4% 0.006 286.033));
-  --ui-color-neutral-900: var(--color-mauve-900, oklch(21% 0.006 285.885));
-  --ui-color-neutral-950: var(--color-mauve-950, oklch(14.1% 0.005 285.823));
-}
-
-.light.dashboard-theme {
+   Marketing/docs pages stay on the warm-slate neutral (hue 285). A site keeps
+   its own ramp here by setting `--ui-dashboard-neutral-<step>` (README). */
+:where(.dashboard-theme) {
+  --ui-color-neutral-50: var(--ui-dashboard-neutral-50, var(--color-mauve-50, oklch(98.5% 0 0)));
+  --ui-color-neutral-100: var(--ui-dashboard-neutral-100, var(--color-mauve-100, oklch(96.7% 0.001 286.375)));
+  --ui-color-neutral-200: var(--ui-dashboard-neutral-200, var(--color-mauve-200, oklch(92% 0.004 286.32)));
+  --ui-color-neutral-300: var(--ui-dashboard-neutral-300, var(--color-mauve-300, oklch(87.1% 0.006 286.286)));
+  --ui-color-neutral-400: var(--ui-dashboard-neutral-400, var(--color-mauve-400, oklch(70.5% 0.015 286.067)));
+  --ui-color-neutral-500: var(--ui-dashboard-neutral-500, var(--color-mauve-500, oklch(55.2% 0.016 285.938)));
+  --ui-color-neutral-600: var(--ui-dashboard-neutral-600, var(--color-mauve-600, oklch(44.2% 0.017 285.786)));
+  --ui-color-neutral-700: var(--ui-dashboard-neutral-700, var(--color-mauve-700, oklch(37.4% 0.016 285.822)));
+  --ui-color-neutral-800: var(--ui-dashboard-neutral-800, var(--color-mauve-800, oklch(27.4% 0.006 286.033)));
+  --ui-color-neutral-900: var(--ui-dashboard-neutral-900, var(--color-mauve-900, oklch(21% 0.006 285.885)));
+  --ui-color-neutral-950: var(--ui-dashboard-neutral-950, var(--color-mauve-950, oklch(14.1% 0.005 285.823)));
+}
+
+:where(.light.dashboard-theme) {
   background-color: var(--ui-bg);
   --ui-bg: #fff;
   --ui-bg-muted: var(--ui-color-neutral-50);
   --ui-bg-elevated: var(--ui-color-neutral-100);
   --ui-bg-accented: var(--ui-color-neutral-200);
   --ui-bg-inverted: var(--ui-color-neutral-900);
-  --ui-text-dimmed: oklch(47.5% 0.018 286);
+  --ui-text-dimmed: var(--ui-dashboard-light-text-dimmed, oklch(47.5% 0.018 286));
   --ui-text-muted: var(--ui-color-neutral-600);
   --ui-text-toned: var(--ui-color-neutral-700);
   --ui-text: var(--ui-color-neutral-800);
@@ -1189,7 +1232,7 @@ textarea {
   --ui-border-inverted: var(--ui-color-neutral-900);
 }
 
-.dark.dashboard-theme {
+:where(.dark.dashboard-theme) {
   background-color: var(--ui-bg);
   --color-mauve-50: oklch(98.5% 0.002 326);
   --color-mauve-100: oklch(96.4% 0.005 325.6);
@@ -1202,22 +1245,13 @@ textarea {
   --color-mauve-800: oklch(24.4% 0.032 320.12);
   --color-mauve-900: oklch(18.9% 0.026 322.12);
   --color-mauve-950: oklch(14.8% 0.018 326);
-  --ui-color-neutral-50: var(--color-mauve-50, oklch(98.5% 0 0));
-  --ui-color-neutral-100: var(--color-mauve-100, oklch(96.7% 0.001 286.375));
-  --ui-color-neutral-200: var(--color-mauve-200, oklch(92% 0.004 286.32));
-  --ui-color-neutral-300: var(--color-mauve-300, oklch(87.1% 0.006 286.286));
-  --ui-color-neutral-400: var(--color-mauve-400, oklch(70.5% 0.015 286.067));
-  --ui-color-neutral-500: var(--color-mauve-500, oklch(55.2% 0.016 285.938));
-  --ui-color-neutral-600: var(--color-mauve-600, oklch(44.2% 0.017 285.786));
-  --ui-color-neutral-700: var(--color-mauve-700, oklch(37.4% 0.016 285.822));
-  --ui-color-neutral-800: var(--color-mauve-800, oklch(27.4% 0.006 286.033));
-  --ui-color-neutral-900: var(--color-mauve-900, oklch(21% 0.006 285.885));
-  --ui-color-neutral-950: var(--color-mauve-950, oklch(14.1% 0.005 285.823));
+  /* `.dashboard-theme` binds `--ui-color-neutral-*` to these steps on this same
+     element, so the dark values above flow through without a second binding. */
 
   /* Mauve 400 measures 4.48:1 on mauve 700 (bg-accented), so muted and dimmed
      share one step just above it: 4.6:1 there, 7.7:1 on bg-default. */
-  --ui-text-dimmed: oklch(71.5% 0.032 323);
-  --ui-text-muted: oklch(71.5% 0.032 323);
+  --ui-text-dimmed: var(--ui-dashboard-dark-text-dimmed, oklch(71.5% 0.032 323));
+  --ui-text-muted: var(--ui-dashboard-dark-text-muted, oklch(71.5% 0.032 323));
   --ui-text-toned: var(--ui-color-neutral-300);
   --ui-text: var(--ui-color-neutral-200);
   --ui-text-highlighted: #fff;
@@ -1328,7 +1362,7 @@ textarea {
   mask-image: linear-gradient(to bottom, black 0%, transparent 86%);
   -webkit-mask-image: linear-gradient(to bottom, black 0%, transparent 86%);
 }
-.ui-atmosphere[data-geometry="bloom"] {
+.ui-atmosphere[data-geometry="bloom"][data-bloom-mask] {
   mask-image: radial-gradient(58% 50% at 50% 38%, black, transparent 76%);
   -webkit-mask-image: radial-gradient(58% 50% at 50% 38%, black, transparent 76%);
 }
@@ -1338,7 +1372,8 @@ textarea {
 }
 /* veil = full scrim tint over a faded preview; no mask, softer by default */
 
-/* grain — baked in, static (soft-light so it reads as tooth, not dirt) */
+/* grain — opt in through `grain` or `designSystem.atmosphere.grain`; static,
+   soft-light so it reads as tooth, not dirt */
 .ui-atmosphere[data-grain]::after {
   content: "";
   position: absolute;
@@ -1360,7 +1395,7 @@ textarea {
 /* Page title — the largest in-page heading (page headers, hero metrics). Size is
    a role var so it stays editorial on marketing, compact inside .dashboard-theme. */
 .text-title {
-  font-family: var(--font-display);
+  font-family: var(--font-title);
   font-size: var(--size-title);
   font-weight: var(--wght-title);
   font-stretch: var(--wdth-heading);
@@ -1449,10 +1484,40 @@ textarea {
    need primary/success/current keep overriding it (an unlayered rule would beat
    the utility and silently force muted). */
 @layer components {
+  /* Type seam: a site sets `--ui-label-size`, `--ui-label-weight`,
+     `--ui-label-case` and `--ui-label-tracking` at `:root` to retune every
+     label at once (README, Brand seams). Unset, each keeps this spec. */
   .text-label {
-    @apply text-[10px] font-semibold uppercase tracking-wider;
+    font-size: var(--ui-label-size, 10px);
+    font-weight: var(--ui-label-weight, 600);
+    text-transform: var(--ui-label-case, uppercase);
+    letter-spacing: var(--ui-label-tracking, 0.05em);
     color: var(--ui-text-muted);
   }
+
+  /* Table type seam. Cells read `--ui-table-cell-size` and
+     `--ui-table-cell-leading`; header labels read `--ui-table-head-size`, then
+     the label size. Declared after `.text-label`, so a header carrying both
+     takes the table size. Unset leading inherits, as the old rules did. */
+  .ui-table-cell {
+    font-size: var(--ui-table-cell-size, var(--text-xs));
+    line-height: var(--ui-table-cell-leading, var(--text-xs--line-height));
+  }
+
+  .ui-table-head {
+    font-size: var(--ui-table-head-size, var(--ui-label-size, 10px));
+    line-height: var(--ui-table-head-leading);
+  }
+
+  /* `UiTrend` sizes `xs`; `2xs` sits below, unlayered like `.text-mini`. */
+  .ui-trend-xs {
+    font-size: var(--ui-trend-xs-size, var(--text-xs));
+    line-height: var(--ui-trend-xs-leading, var(--text-xs--line-height));
+  }
+}
+
+.ui-trend-2xs {
+  font-size: var(--ui-trend-2xs-size, 10px);
 }
 
 /* Micro label — the 9px tier below .text-label, for the tiniest tags (table
@@ -1739,32 +1804,8 @@ pre.prose-pre::-webkit-scrollbar-thumb {
   border-radius: 9999px;
 }
 
-/* Outbound prose links carry the same arrow the docs overflow menu already
-   uses for an external item, so "this leaves the site" means one thing in both
-   places. Only absolute http(s) links that are not ours: every `/docs/*` and
-   `/learn-seo/*` link is relative and never matches. A link around an image is
-   excluded — the arrow would hang off the corner of the figure.
-
-   The marker is a background on a pseudo-element whose only content is a
-   no-break space: the NBSP glues the arrow to the last word, so it can never
-   orphan onto a line of its own, and there is no text for a screen reader to
-   announce. The mask resolves `currentColor` against the image's own initial
-   colour, which is opaque black, so the arrow always paints in the link's
-   colour and the CSS holds no colour of its own. */
-a.prose-link[href^="http"]:not([href*="//nuxtseo.com"]):not([href*="//www.nuxtseo.com"]):not(:has(img))::after {
-  content: '\00a0';
-  padding-inline-end: 0.72em;
-  background-color: currentcolor;
-  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M7 7h10v10'/%3E%3Cpath d='M7 17 17 7'/%3E%3C/svg%3E");
-  mask-repeat: no-repeat;
-  mask-position: right center;
-  mask-size: 0.72em 0.72em;
-  opacity: 0.65;
-  vertical-align: baseline;
-}
-a.prose-link[href^="http"]:not([href*="//nuxtseo.com"]):not([href*="//www.nuxtseo.com"]):not(:has(img)):hover::after {
-  opacity: 1;
-}
+/* The external-link arrow on outbound prose links lives in
+   build/external-links.ts: its own-site hosts are a build option. */
 
 /* Inline code inside a link. `prose.code` is an atomic inline (`inline-block`
    with its own fill), so the link underline stopped at the pill and the pill's

package/nuxt.config.ts

@@ -80,33 +80,23 @@ export default defineNuxtConfig({
     ],
   },
 
-  // Canonical type stack for every surface that extends this layer (root app
-  // + apps/brand-kit brand-kit). Keep in sync via this single block —
-  // don't redeclare in root or app configs.
+  // The type stack is a brand seam. The layer ships and registers no faces, so
+  // a site sets its own through `fonts.families` and the `--font-*` tokens.
   fonts: {
-    // Both families are global. CSS variable discovery cannot add another
-    // face, so avoid parsing every component style during each Vite build.
+    // CSS variable discovery cannot add another face, so avoid parsing every
+    // component style during each Vite build.
     processCSSVariables: false,
-    families: [
-      // Keep build inputs in this layer. Provider downloads make every app
-      // build depend on Google Fonts availability after compilation finishes.
-      // Hubot Sans keeps variable weight and width axes for the design tokens.
-      {
-        name: 'Hubot Sans',
-        src: '/fonts/hubot-sans-var-latin.woff2',
-        weight: '200 900',
-        stretch: '75% 125%',
-        style: 'normal',
-        global: true,
-      },
-      {
-        name: 'Fira Code',
-        src: '/fonts/fira-code-var-latin.woff2',
-        weight: '400 500',
-        style: 'normal',
-        global: true,
-      },
-    ],
+  },
+
+  vite: {
+    optimizeDeps: {
+      // The layer's tables run @tanstack/vue-table 9, and @nuxt/ui's UTable
+      // runs 8. Vite pre-bundles one copy per package name, so whichever it
+      // meets first serves both, and a layer table fails with "does not
+      // provide an export named 'useTable'". Unbundled, each importer resolves
+      // its own copy.
+      exclude: ['@tanstack/vue-table', '@tanstack/table-core'],
+    },
   },
 
   icon: {
@@ -125,7 +115,10 @@ export default defineNuxtConfig({
     experimental: { componentDetection: true },
     content: true,
     theme: {
-      colors: ['primary', 'secondary', 'tertiary', 'info', 'success', 'warning', 'error', 'pro'],
+      // Each colour adds its variants to every Nuxt UI component theme in the
+      // CSS every page inlines. No app.config maps a `tertiary` colour and no
+      // component asks for one, so it is not listed.
+      colors: ['primary', 'secondary', 'info', 'success', 'warning', 'error', 'pro'],
     },
   },
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nuxtseo/design-system",
   "type": "module",
-  "version": "0.1.0",
-  "description": "Nuxt SEO design system layer: UI primitives, tokens, fonts, motion, and chart helpers. Extend it from a Nuxt app.",
+  "version": "0.1.2",
+  "description": "Nuxt SEO design system layer: UI primitives, tokens, motion, and chart helpers. Extend it from a Nuxt app.",
   "license": "MIT",
   "homepage": "https://nuxtseo.com",
   "repository": {
@@ -26,7 +26,10 @@
     "./composables/*": "./app/composables/*.ts",
     "./package.json": "./package.json",
     "./server/*": "./server/*.ts",
-    "./shared/*": "./shared/*.ts"
+    "./shared/contracts": "./shared/contracts/index.ts",
+    "./shared/icons": "./shared/icons/index.ts",
+    "./shared/*": "./shared/*.ts",
+    "./types": "./types/index.ts"
   },
   "main": "./nuxt.config.ts",
   "files": [
@@ -34,18 +37,23 @@
     "build",
     "css",
     "nuxt.config.ts",
-    "public",
     "server",
     "shared",
     "types"
   ],
   "peerDependencies": {
+    "@nuxt/scripts": "^1.3.10 || ^2.0.0-beta.14",
+    "@nuxt/ui": "^4.11.1",
+    "@vueuse/core": "^14.0.0 || ^15.0.0",
+    "motion-v": "^2.4.2",
     "nuxt": "^4.6.0",
+    "tailwindcss": "^4.3.0",
     "typescript": ">=5.8.0 <7",
-    "vue": "^3.5.0"
+    "vue": "^3.5.0",
+    "zod": "^4.0.0"
   },
   "dependencies": {
-    "@comark/nuxt": "0.7.0",
+    "@comark/nuxt": "^0.7.0",
     "@iconify-json/hugeicons": "^1.2.34",
     "@iconify-json/logos": "^1.2.14",
     "@iconify-json/lucide": "^1.2.130",
@@ -55,27 +63,27 @@
     "@nuxt/fonts": "^1.0.1",
     "@nuxt/icon": "^2.5.1",
     "@nuxt/image": "^2.1.0",
-    "@nuxt/scripts": "2.0.0-beta.14",
-    "@nuxt/ui": "^4.11.1",
     "@tanstack/table-core": "^9.2.4",
     "@tanstack/vue-table": "^9.2.4",
     "@unovis/ts": "^1.6.7",
     "@unovis/vue": "^1.6.7",
-    "@vueuse/core": "^14.4.0",
-    "motion-v": "2.4.2",
     "nuxtseo-shared": "^6.0.2",
     "pathe": "^2.0.3",
     "rangi": "^2.2.0",
-    "reka-ui": "^2.10.4",
-    "tailwindcss": "^4.3.3",
-    "zod": "^4.6.7"
+    "reka-ui": "^2.10.4"
   },
   "devDependencies": {
+    "@nuxt/scripts": "^2.0.0-beta.14",
+    "@nuxt/ui": "^4.11.1",
+    "@vueuse/core": "^14.4.0",
     "ai": "^7.0.122",
+    "motion-v": "2.4.2",
     "nuxt": "4.6.1",
     "sharp": "^0.35.4",
     "site-typecheck": "0.0.0",
-    "vue": "^3.5.43"
+    "tailwindcss": "^4.3.3",
+    "vue": "^3.5.43",
+    "zod": "^4.6.7"
   },
   "publishConfig": {
     "access": "public"