@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/app.config.ts

@@ -0,0 +1,596 @@
+import type { IconColorClasses } from './utils/icon-color'
+import { UI_ICON_SLOTS } from '../shared/icons/ui-slots'
+
+// Nuxt UI's internal icon slots reference semantic role names directly; @nuxt/icon's
+// global aliases (registered by build/design-system.ts) resolve them to the
+// chosen set's id at build time. So the framework primitives (selects, alerts,
+// pagination, accordions…) follow the active icon set without this file pulling the
+// role registry into the client runtime. Edit roles in shared/icons/registry.ts.
+export default {
+  // Brand seams for a site that extends this layer. `iconColors` adds or remaps
+  // an icon colour role that getIconColor() resolves, e.g.
+  // `lime: { bg: 'bg-lime-500/10', text: 'text-lime-500' }`.
+  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',
+  },
+  toaster: {
+    position: 'bottom-right' as const,
+    // Collapsed peek-deck that fans out on hover (Sonner/Linear). Read by UiToaster.
+    max: 3,
+    duration: 5000,
+  },
+  ui: {
+    colors: {
+      primary: 'violet',
+      neutral: 'slate',
+      pro: 'violet',
+    },
+    icons: UI_ICON_SLOTS,
+
+    // Button — primary is violet solid, secondary actions use semantic neutral tokens
+    // so light/dark modes both resolve correctly via --ui-* vars.
+    button: {
+      slots: {
+        base: 'cursor-pointer disabled:cursor-not-allowed aria-disabled:cursor-not-allowed',
+        item: '!py-0',
+        link: 'flex flex-col items-center justify-start w-full gap-0.5 w-[90px]',
+        linkLabel: 'text-xs text-toned',
+        linkTrailing: 'absolute right-2 top-2',
+        linkTrailingIcon: 'size-4 text-dimmed',
+        // inner menu
+        childList: '!grid-cols-5',
+        childLink: 'flex flex-col items-center justify-start w-full gap-0.5',
+        childLinkLabel: 'text-[10px] text-center text-muted',
+        childLinkIcon: 'size-6 !text-primary-400',
+      },
+      variants: {
+        variant: {
+          solid: '',
+          outline: 'ring-default hover:bg-elevated',
+          ghost: 'hover:bg-muted',
+          link: '',
+        },
+      },
+      compoundVariants: [
+        // Primary CTA — Vercel/PostHog-style inversion. bg-inverted/text-inverted
+        // auto-flip per mode (dark slate on light, white on dark), so contrast
+        // stays balanced without saturated brand colour fighting the surface.
+        // Mode-specific shadows: light mode gets a top inner sheen ("lit from
+        // above"); dark mode swaps to a hairline ring so the white button feels
+        // carved instead of floating. Hover lifts 1px, press returns and scales
+        // 0.99 — the 1000-small-details polish.
+        // Saturated violet is reserved for `color="pro"` (purchase/upgrade only).
+        {
+          color: 'primary',
+          variant: 'solid',
+          class: 'bg-inverted text-inverted shadow-[inset_0_1px_0_0_rgba(255,255,255,0.08),0_1px_2px_0_rgba(0,0,0,0.06)] dark:shadow-[0_1px_2px_0_rgba(0,0,0,0.3),0_0_0_1px_rgba(0,0,0,0.04)] hover:bg-inverted/90 hover:shadow-[inset_0_1px_0_0_rgba(255,255,255,0.1),0_2px_4px_-1px_rgba(0,0,0,0.1)] dark:hover:shadow-[0_2px_6px_-1px_rgba(0,0,0,0.4),0_0_0_1px_rgba(0,0,0,0.04)] disabled:bg-inverted/40 disabled:text-inverted/60 disabled:shadow-none aria-disabled:bg-inverted/40 aria-disabled:text-inverted/60 aria-disabled:shadow-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500 transition-[background-color,box-shadow] duration-200 ease-[var(--ease-standard)]',
+        },
+        // Pro CTA — refined violet for purchase/upgrade moments. Same hover
+        // lift + press scale as primary so the gesture vocabulary is
+        // consistent; a top inner sheen and soft drop shadow give it that
+        // "lit from above" Stripe/Linear quality.
+        {
+          color: 'pro',
+          variant: 'solid',
+          class: 'bg-primary-600 hover:bg-primary-500 text-white shadow-[inset_0_1px_0_0_rgba(255,255,255,0.12),0_1px_2px_0_rgba(0,0,0,0.12)] hover:shadow-[inset_0_1px_0_0_rgba(255,255,255,0.16),0_3px_8px_-1px_rgba(0,0,0,0.18)] disabled:bg-inverted/40 disabled:text-inverted/60 disabled:shadow-none aria-disabled:bg-inverted/40 aria-disabled:text-inverted/60 aria-disabled:shadow-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500 transition-[background-color,box-shadow] duration-200 ease-[var(--ease-standard)]',
+        },
+        {
+          color: 'neutral',
+          variant: 'outline',
+          class: 'ring-default text-toned hover:bg-elevated focus-visible:ring-accented',
+        },
+        {
+          color: 'neutral',
+          variant: 'ghost',
+          class: 'text-muted hover:text-highlighted hover:bg-muted',
+        },
+        // Primary subtle/soft — keep monochrome. Nuxt UI's defaults pull
+        // bg-primary-50 + text-primary-700 (violet); we redirect to the
+        // elevated/muted semantic tokens so the surface stays neutral and
+        // colour is reserved for `color="pro"`.
+        {
+          color: 'primary',
+          variant: 'subtle',
+          class: 'bg-elevated text-default ring-default hover:bg-accented disabled:bg-elevated/60 disabled:text-muted aria-disabled:bg-elevated/60 aria-disabled:text-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500',
+        },
+        {
+          color: 'primary',
+          variant: 'soft',
+          class: 'bg-muted text-default hover:bg-accented disabled:bg-muted/60 disabled:text-muted aria-disabled:bg-muted/60 aria-disabled:text-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500',
+        },
+        {
+          color: 'primary',
+          variant: 'outline',
+          class: 'ring-default text-default hover:bg-elevated disabled:text-muted aria-disabled:text-muted focus-visible:ring-accented',
+        },
+        {
+          color: 'primary',
+          variant: 'ghost',
+          class: 'text-default hover:text-highlighted hover:bg-muted disabled:text-muted aria-disabled:text-muted',
+        },
+      ],
+    },
+
+    // Badge — semantic neutral tokens so soft/subtle variants flip correctly in light mode
+    badge: {
+      slots: {
+        base: 'rounded-md',
+      },
+      variants: {
+        size: {
+          xs: 'text-[10px] px-1 py-px leading-tight',
+        },
+      },
+      compoundVariants: [
+        {
+          color: 'neutral',
+          variant: 'soft',
+          class: 'bg-elevated text-muted',
+        },
+        {
+          color: 'neutral',
+          variant: 'subtle',
+          class: 'bg-elevated/50 ring-default text-muted',
+        },
+        {
+          color: 'neutral',
+          variant: 'outline',
+          class: 'ring-default text-dimmed',
+        },
+        {
+          color: 'primary',
+          variant: 'soft',
+          class: 'bg-primary-500/10 text-primary-500',
+        },
+      ],
+    },
+
+    // Card — cards sit at the "lg" radius tier per the radius-by-elevation rule.
+    // Arbitrary box-shadow syntax (rather than a `shadow-*` utility) keeps the
+    // CSS variable live at runtime so .dashboard-theme can swap it for the
+    // hairline ring. A regular shadow utility would inline the value at build.
+    card: {
+      slots: {
+        root: 'rounded-lg [box-shadow:var(--elevation-raised)]',
+      },
+      variants: {
+        variant: {
+          outline: {
+            root: 'bg-muted ring-default',
+          },
+          soft: {
+            root: 'bg-muted/50',
+          },
+          subtle: {
+            root: 'bg-muted ring-default',
+          },
+        },
+      },
+    },
+
+    // PageCard — same structural treatment as Card
+    pageCard: {
+      slots: {
+        root: 'rounded-lg [box-shadow:var(--elevation-raised)]',
+        title: 'text-highlighted',
+        description: 'text-muted',
+        leadingIcon: 'text-primary-500',
+      },
+      variants: {
+        variant: {
+          outline: {
+            root: 'bg-muted ring-default hover:ring-accented',
+          },
+          subtle: {
+            root: 'bg-muted ring-default',
+          },
+          soft: {
+            root: 'bg-muted/50',
+          },
+        },
+      },
+    },
+
+    // Input — rounded-md per DESIGN.md radius-by-elevation (inputs tier); full-width
+    // by default (the root wrapper is inline-flex otherwise, so inputs collapse to
+    // content width in form grids). Semantic tokens for background and ring.
+    input: {
+      slots: {
+        root: 'w-full',
+        base: 'w-full rounded-md bg-muted placeholder:text-dimmed',
+      },
+      variants: {
+        variant: {
+          outline: 'ring-default focus-visible:ring-accented',
+          subtle: 'bg-muted ring-default',
+        },
+      },
+      compoundVariants: [
+        {
+          color: 'primary',
+          variant: 'outline',
+          class: 'focus-visible:ring-primary-500/50',
+        },
+      ],
+    },
+
+    // Textarea - Match input styling (full-width, rounded-md). Auto-grow
+    // (field-sizing) is applied in global.css so it survives Tailwind's
+    // app.config class-scanning gap.
+    textarea: {
+      slots: {
+        root: 'w-full',
+        base: 'w-full rounded-md bg-muted placeholder:text-dimmed',
+      },
+      variants: {
+        variant: {
+          outline: 'ring-default focus-visible:ring-accented',
+        },
+      },
+    },
+
+    // Select — match input: full-width trigger, rounded-md, semantic ring so the
+    // native-style select doesn't read narrower/lighter than its sibling inputs.
+    select: {
+      slots: {
+        base: 'w-full rounded-md',
+      },
+      variants: {
+        variant: {
+          outline: 'ring-default focus-visible:ring-accented',
+        },
+      },
+    },
+
+    // Separator - Subtle divider
+    // A full pager wraps on a narrow screen instead of widening the page.
+    pagination: {
+      slots: {
+        list: 'flex-wrap justify-center sm:justify-start',
+      },
+    },
+    separator: {
+      slots: {
+        border: 'border-default',
+      },
+      variants: {
+        color: {
+          neutral: {
+            border: 'border-default',
+          },
+        },
+      },
+    },
+
+    // UiPageHeader - Documentation page headers
+    pageHeader: {
+      slots: {
+        root: '',
+        container: '',
+        wrapper: '',
+        headline: 'text-muted font-medium text-sm',
+        title: 'text-3xl md:text-4xl font-semibold tracking-tight text-highlighted leading-normal',
+        description: 'text-lg text-muted mt-2',
+        links: 'mt-4',
+      },
+    },
+
+    // PageBody - Documentation page content
+    pageBody: {
+      slots: {
+        root: '',
+      },
+    },
+
+    // ContentSurround - Prev/next navigation
+    contentSurround: {
+      slots: {
+        root: 'grid grid-cols-1 sm:grid-cols-2 gap-4',
+        link: 'grid grid-cols-[auto_minmax(0,1fr)] items-center gap-x-3 gap-y-0.5 p-4 rounded-lg border border-default hover:border-accented hover:bg-muted/50 transition-colors group',
+        linkLeading: 'row-span-2 self-center shrink-0',
+        linkLeadingIcon: 'size-5 text-dimmed group-hover:text-primary-500 transition-colors',
+        linkTitle: 'col-start-2 font-medium text-highlighted truncate group-hover:text-primary-400 transition-colors',
+        linkDescription: 'col-start-2 text-sm text-dimmed line-clamp-1',
+      },
+    },
+
+    // Link — modern inline link convention. Underline is always rendered but
+    // transparent by default; on hover the decoration color animates to the
+    // primary tint and text lifts to highlighted. Saturated violet stays
+    // reserved for CTAs/active nav (60-30-10). Apply to <ULink> usages.
+    link: {
+      base: 'underline underline-offset-4 decoration-1 decoration-transparent hover:decoration-[var(--ui-color-primary-500)] focus-visible:outline-primary transition-[color,text-decoration-color] duration-200',
+      variants: {
+        active: {
+          true: 'text-primary decoration-[var(--ui-color-primary-500)]',
+          false: 'text-default',
+        },
+        disabled: {
+          true: 'cursor-not-allowed opacity-75',
+        },
+      },
+      compoundVariants: [
+        {
+          active: false,
+          disabled: false,
+          class: 'hover:text-highlighted',
+        },
+      ],
+    },
+
+    // Tooltip - Subtle border, adapts to light/dark
+    tooltip: {
+      slots: {
+        content: 'bg-muted text-highlighted ring-default rounded-lg',
+        arrow: 'fill-[var(--ui-bg-muted)]',
+      },
+    },
+
+    // DropdownMenu — tooltip-grade chrome (5-layer shadow + inset edges) plus
+    // outline-ring hover on items and a left accent bar on the active item.
+    // Style only; behaviour stays default Nuxt UI v4 / Reka.
+    dropdownMenu: {
+      slots: {
+        content: 'ui-popover-content',
+        item: 'ui-dropdown-item rounded-md transition-colors items-center',
+        itemLeadingIcon: 'ui-dropdown-lead-icon !size-3 text-dimmed group-data-highlighted:!text-default',
+        itemLabel: 'tracking-[-0.005em]',
+        itemTrailingKbds: 'gap-0.5',
+        itemTrailingKbd: 'font-mono text-[10px] bg-muted rounded-sm px-1 py-px',
+        separator: 'ui-dropdown-separator mx-2 border-default',
+      },
+    },
+
+    // Popover — same chrome treatment as dropdown/tooltip.
+    popover: {
+      slots: {
+        content: 'ui-popover-content',
+      },
+    },
+
+    // ContextMenu — match dropdown chrome.
+    contextMenu: {
+      slots: {
+        content: 'ui-popover-content',
+        item: 'ui-dropdown-item rounded-md transition-colors items-center',
+        itemLeadingIcon: 'ui-dropdown-lead-icon !size-3 text-dimmed',
+      },
+    },
+
+    // Avatar - Subtle border
+    avatar: {
+      slots: {
+        root: 'ring-default',
+      },
+    },
+
+    // NavigationMenu - Semantic tokens so light/dark both work
+    navigationMenu: {
+      slots: {
+        item: '!py-0',
+        link: 'flex flex-col items-center justify-start w-full gap-0.5 w-[90px]',
+        linkLabel: 'text-xs text-muted',
+        linkTrailing: 'absolute right-2 top-2',
+        linkTrailingIcon: 'size-4 text-dimmed',
+        childList: '!grid-cols-5',
+        childLink: 'flex flex-col items-center justify-start w-full gap-0.5',
+        childLinkLabel: 'text-[10px] text-center text-dimmed',
+        childLinkIcon: 'size-6 !text-primary-400',
+      },
+      variants: {
+        active: {
+          false: {
+            linkLeadingIcon: 'text-muted',
+          },
+          true: {
+            link: 'text-primary-500',
+          },
+        },
+      },
+    },
+
+    // Accordion - Semantic tokens for light/dark parity
+    accordion: {
+      slots: {
+        root: 'border-default',
+        item: 'border-default',
+        trigger: 'text-highlighted hover:bg-muted',
+        content: 'text-muted',
+      },
+    },
+
+    // Drawer - Semantic tokens for light/dark parity
+    drawer: {
+      slots: {
+        content: 'bg-default ring-default',
+        handle: 'bg-accented',
+      },
+    },
+
+    // Tabs - Neutral white active to sit quietly below the sidebar's primary nav.
+    // Primary violet is reserved for CTAs; tabs are sub-navigation and should read
+    // as text-level emphasis with a thin white underline.
+    tabs: {
+      slots: {
+        trigger: 'text-muted',
+        indicator: 'rounded-full',
+      },
+      compoundVariants: [
+        {
+          variant: 'link',
+          class: {
+            trigger: 'data-[state=active]:text-highlighted',
+            indicator: 'bg-inverted',
+          },
+        },
+      ],
+    },
+
+    // Form elements
+    formField: {
+      slots: {
+        label: 'text-toned',
+        description: 'text-dimmed',
+        error: 'text-error',
+      },
+    },
+
+    // Checkbox - Primary color when checked
+    checkbox: {
+      slots: {
+        base: 'border-accented data-[state=checked]:bg-primary-500 data-[state=checked]:border-primary-500',
+      },
+    },
+
+    // SelectMenu - Dropdown with semantic tokens + overlay chrome
+    selectMenu: {
+      slots: {
+        content: 'bg-muted ring-default ui-popover-content',
+        item: 'ui-dropdown-item rounded-md text-toned data-[highlighted]:text-highlighted',
+        itemLeadingIcon: 'ui-dropdown-lead-icon !size-3 text-dimmed',
+      },
+    },
+    contentNavigation: {
+      slots: {
+        list: 'space-y-2',
+        listWithChildren: 'border-none transform mb-5',
+      },
+      variants: {
+        active: {
+          true: {
+            link: 'text-toned after:-left-[1px] font-semibold rounded-[10px] after:rounded-[10px] after:w-full after:h-full after:absolute after:bottom-0 after:block after:bg-elevated/50 after:shadow-xs',
+          },
+          false: {
+            link: 'text-toned',
+            linkLeadingIcon: 'text-dimmed',
+          },
+        },
+      },
+      compoundVariants: [
+        {
+          color: 'primary',
+          variant: 'pill',
+          active: true,
+          class: {
+            link: 'text-highlighted ',
+          },
+        },
+      ],
+    },
+    // Markdown rendering. The `prose-*` class names below carry no utilities;
+    // they are the stable hooks the "Docs prose" block in css/global.css keys
+    // on, so a defect in upstream module Markdown is fixed once, here, for
+    // docs + learn-seo + recipes.
+    prose: {
+      // The body-copy and code-pill treatment lives on `prose-callout` in
+      // css/global.css. A `text-default` variant override here only reached
+      // light mode: Nuxt UI tints with `text-{color}-600 dark:text-{color}-300`
+      // and tailwind-merge treats the `dark:` step as a separate key, so the
+      // override dropped the light class and left the dark one standing.
+      callout: {
+        slots: {
+          base: 'prose-callout',
+          icon: 'prose-callout-icon',
+        },
+      },
+      // Heading ladder: the h1 dominates, h2/h3 stay modest and the gap above a
+      // section is ~40px, not ~70px, so a new h2 reads as a section and not as
+      // a new page.
+      h2: {
+        slots: {
+          base: 'prose-h2 text-xl font-semibold mt-10 mb-3',
+        },
+      },
+      h3: {
+        slots: {
+          base: 'prose-h3 text-base font-semibold mt-8 mb-2',
+        },
+      },
+      h4: {
+        slots: {
+          base: 'prose-h4 text-sm font-semibold mt-6 mb-2',
+        },
+      },
+      ul: {
+        base: 'prose-ul',
+      },
+      // `prose-table-scroll` is the hook for the edge-shadow rule in
+      // css/global.css: a table wider than the article scrolls here, and
+      // nothing on the border said so.
+      table: {
+        slots: {
+          root: 'prose-table-scroll my-6 overflow-x-auto overscroll-x-contain rounded-lg border border-default bg-default',
+          base: 'prose-table w-full border-collapse rounded-none',
+        },
+      },
+      thead: {
+        base: 'bg-muted',
+      },
+      th: {
+        base: 'border-0 border-b border-default px-4 py-3 text-sm font-semibold text-highlighted text-left whitespace-nowrap first:border-s-0',
+      },
+      td: {
+        base: 'border-0 border-b border-default px-4 py-3 text-sm align-top',
+      },
+      tr: {
+        base: 'transition-colors [&:last-child>td]:border-b-0',
+      },
+      // Long type signatures (`urls: MaybeFunction<MaybePromise<...>>`) set the
+      // page's min-content width and scrolled the whole document sideways on a
+      // phone. The wrap rule lives in css/global.css on this hook.
+      code: {
+        base: 'prose-code',
+      },
+      // The filename header and the code body are one surface; the header was
+      // `bg-default` against a `bg-muted` body, which read as two cards.
+      pre: {
+        slots: {
+          header: 'bg-muted',
+          filename: 'text-muted',
+          // `prose-pre` is the hook for the scroll rule in css/global.css: a
+          // fenced block keeps its lines intact and scrolls sideways instead of
+          // wrapping a URL or a type signature mid-token.
+          base: 'prose-pre',
+          // The copy button renders at 28px. Extend the hit area to the 44px
+          // touch floor with a pseudo-element instead of growing the glyph.
+          copy: 'after:absolute after:-inset-2 after:content-[\'\']',
+        },
+      },
+      codeGroup: {
+        slots: {
+          // The strip still scrolls, but at 390px a five-tab install group ran
+          // 7px past the viewport and cut the last icon in half. Tighter
+          // padding below `sm` fits it.
+          list: 'bg-muted max-sm:gap-0.5 max-sm:p-1.5',
+          // `prose-code-tab`/`-icon` are the hooks for the brand-mark rule in
+          // css/global.css: five full-colour logos read as a wash on a
+          // near-monochrome page, so only the selected tab spends colour.
+          trigger: 'prose-code-tab max-sm:px-1.5 text-muted data-[state=active]:text-highlighted',
+          triggerIcon: 'prose-code-tab-icon size-3.5',
+        },
+      },
+      codeIcon: {
+        'robots.txt': 'vscode-icons:file-type-robots',
+        'txt': 'vscode-icons:file-type-text',
+      },
+      a: {
+        base: [
+          'prose-link relative border-none underline underline-offset-4 text-default decoration-transition-all decoration-opacity-70 decoration-[0.1rem] decoration-[var(--ui-text-dimmed)]',
+          // set a :after border under the link
+          'transition-[color,text-decoration-color,text-underline-offset,text-decoration-thickness]',
+          'hover:text-dimmed decoration-opacity-100 hover:underline-offset-1 hover:decoration-[0.1rem]',
+        ],
+      },
+    },
+  },
+}

package/app/component-attributes.d.ts

@@ -0,0 +1,8 @@
+import type { AriaAttributes, HTMLAttributes } from 'vue'
+
+declare module 'vue' {
+  // Components pass these standard attributes and listeners through $attrs.
+  interface ComponentCustomProps extends AriaAttributes, Pick<HTMLAttributes, 'autocapitalize' | 'autocorrect' | 'spellcheck' | 'onBlur' | 'onFocus' | 'onPointermove' | 'inputmode' | 'onLoad' | 'role' | 'tabindex' | 'onInput' | 'onKeydown' | 'onKeyup' | 'onPointerdown' | 'onPaste'> {
+    onClick?: ((event: MouseEvent) => void) | Array<(event: MouseEvent) => void>
+  }
+}

package/app/components/README.md

@@ -0,0 +1,38 @@
+# Design system components
+
+Canonical UI primitives. Every component here must render with prop fixtures alone: no `useFetch`, no [Drizzle](https://orm.drizzle.team), no Caller, no auth/billing state. Domain data is passed in via props or slots, never resolved internally.
+
+See [ADR-0029](../../../docs/adr/0029-component-placement-contract.md) for the placement contract that decides what lives here vs in `layers/saas/`, `apps/pro/`, or a feature layer.
+
+## Taxonomy
+
+Three subdirs by composition shape. Pick by what the component is for, not what it looks like.
+
+### `container/`
+
+Wraps other content and manages its surface, layout, or portal. Has at least one `<slot />`. Renaming "Card" without children is a leaf; renaming with children is a container.
+
+Current: `Alert`, `Card`, `DateRangePicker`, `EmptyState`, `LoadingCard`, `LockedCard`, `PageHeader`, `SampleDataOverlay`, `SectionHeader`, `UiNoData`, `UiPopover`, `UiWidgetState`.
+
+### `data/`
+
+Renders structured data: tables, rows of metrics, structured cells. Takes a row/value/series and decides how to present it. Often slotted into a `container/`.
+
+Current: `DataList`, `FacetStrip`, `MetricCard`, `MetricLabel`, `MetricsRow`, `MetricToggle`, `SparklineLoader`, `UiBarChart`, `UiDonutChart`, `UiLineChart`, `UiSparkline`, `UiStat`, `UiStats`, `UiTable*` family, `UiDataTableSection`, `cells/`.
+
+### `element/`
+
+Leaf primitives. No nested slots beyond a single optional `<slot />`. Includes dots, badges, chips, icons, buttons, and single-purpose displays.
+
+Current: `Chip`, `DotLabel`, `EjectMenu`, `Favicon`, `HealthDot`, `ProgressPercent`, `SeverityDot`, `StatusBadge`, `SyncDot`, `TogglePill`, `UiHelpLabel`, `UiButton`, `UiPillSelect`, `UiProgressCircle`, `UiSkeleton`, `UiTooltip`, `UiTooltipGrid`, `UiTrend`.
+
+## Naming rules
+
+- **No scope prefixes.** Not `Pro*`, not `Admin*`, not `Tool*`, not `Docs*`. The layer name is the scope. Promotion from `pro-saas` → here drops the prefix in the same PR ([ADR-0029](../../../docs/adr/0029-component-placement-contract.md)).
+- **`Ui*` is grandfathered**, not preferred. New primitives don't add the prefix; existing `Ui*` files keep it until a rename batch is convenient.
+- **PascalCase**, single basename word where possible (`Card`, not `CardSurface`; `Chip`, not `BadgeChip`).
+- **Auto-import registers them under the bare name** (see `nuxt.config.ts` here: `pathPrefix: false`).
+
+## Priority
+
+The design-system layer registers its components dir with `priority: 10` (see `nuxt.config.ts`). This wins shadow conflicts against same-basename files in other layers (e.g. `apps/site/app/components/content/Alert.vue`, owned by the content team). When you add a new primitive, check `ripast components --dups` to confirm it doesn't introduce a new shadow that's load-bearing somewhere.