Skip to the content.

Nuxt template layers: architecture blueprint

Companion to the roadmap 2026-10-14-ui-template-revision.md. Task briefs point at the section that applies to them. Items marked “verify” were not confirmed against source. This is a design blueprint: where it differs from shipped code, the code and the package docs (nuxt-layer-base.md) win.

1. Layer topology

packages/nuxt-layer-base   @tgmc/nuxt-layer-base   (no PrimeVue)
  nuxt.config.ts           modules @nuxt/a11y, src/module/tgmc-features.ts; Sass injection; icon/a11y defaults
  src/config/{a11y,icons,scss,features,feature-packages,index}.ts
  src/module/              tgmc-features.ts (`tgmc:` flags; installs @nuxt/icon), theme-fallback.ts,
                           feature-off.ts, kit.ts (export "./module-kit")
  scss/                    _fallback.scss, fallback.css (theme-off fallback; export "./scss/fallback")
  app/components/a11y/     UiSkipLink, UiAnnouncer, UiVisuallyHidden
  app/composables/         useA11yAnnouncer, useFocusTrap, useInertOutside, useMatchMedia,
                           usePrefersReducedMotion
  app/utils/               focus-trap.ts, inert-outside.ts (single copies)
  src/runtime/motion.ts    MOTION_PREFERENCE_STATE_KEY ('tgmc-motion'), export "./motion"

packages/nuxt-layer-ui     @tgmc/nuxt-layer-ui     (extends ['@tgmc/nuxt-layer-base'])
  nuxt.config.ts           src/module/tgmc-ui.ts (installs @primevue/nuxt-module); primevue config;
                           components dir
  src/config/primevue.ts   moved from core/web/config-properties (export "./primevue")
  src/config/prime-components.ts  the Prime* names stubbed when PrimeVue is off
  app/components/ui/       39 Ui* (UiCodeBlock stays in core/web), including the forms parts, UiSelectButton, UiConfirmInline and UiUndoNotice
                           (UiForm, UiFormField, UiFormErrorSummary, UiFormActions) and
                           UiConfirmDialog — shipped; the data / editor / upload components below
                           are planned
  app/components/media/    registered only with `tgmc.media` (empty until the media components land)
  app/feature-plugins/     toast-primevue.client.ts or toast-native.client.ts ($toast; added by the
                           ui module, not auto-scanned)
  app/composables/         shipped: useUiStack, useAppToast (export "./toast"), useForm,
                           useUnsavedChangesGuard;
                           planned: useCrudResource, useConfirmUndo, usePagedList,
                           useRouteQueryState, useUploadQueue, useChartTheme
  app/forms/               form-values.ts, form-controller.ts (export "./forms"), unsaved-changes.ts:
                           plain TypeScript on Vue reactivity, not auto-scanned
  app/utils/               planned: upload-queue.ts, chart-colors.ts, markdown-policy.ts
  shared/form-errors.ts    error shapes and readers, no Vue or DOM (export "./form-errors")
export function tgmcScssAdditionalData(extraUses: string[] = []) {
  const header = ['@use "pkg:@tgmc/theme/scss/nuxt-auto" as *;', ...extraUses].join('\n');
  return (source: string, filename: string) =>
    !filename.includes('.vue') || filename.includes('node_modules') || source.includes('nuxt-auto')
      ? source
      : `${header}\n${source}`;
}
Package Placement in base Placement in ui
nuxt, vue peer peer
@nuxt/kit dep ^4.5.2 dep ^4.5.2
@nuxt/icon optional peer ^2.5.1 via base
@nuxt/a11y dep, root’s resolved version via base
@iconify-json/lucide optional peer, root range via base
@tgmc/theme optional peer * dep * (UiImage, PrimeVue preset)
@tgmc/utilities dep * via base
primevue, @primevue/nuxt-module — optional peer "4"
@tgmc/media-client, @tgmc/media-player — optional peer *
@primeuix/themes — via @tgmc/theme
chart.js — dep ^4
@tiptap/vue-3, @tiptap/pm, @tiptap/starter-kit, @tiptap/extensions, @tiptap/markdown — dep
@standard-schema/spec — dep ^1.1.0 (types only)
zod — devDep ^4.6.7 (apps own schemas; web-layer-admin dep)
@primevue/forms — not adopted

Add a guard: layer dependency ranges must equal the root ranges. core/web/tests/layer-dependency-ranges.spec.ts checks dependencies, devDependencies and peerDependencies, and that every feature package is an optional peer (never a dependency).

An optional peer isn’t installed for the app. Each app declares the packages of the features it keeps on, as generated apps do (§ 1a). core/web and core/admin therefore list primevue and @primevue/nuxt-module ("4") in their own dependencies: with the packages only in the root’s devDependencies and an optional peer of the ui layer, npm marks PrimeVue devOptional in the lockfile, and a production install (--omit=dev) would leave it out.

1a. Optional features

An app turns layer features off in nuxt.config.ts; every flag defaults to true:

export default defineNuxtConfig({
  extends: ['@tgmc/nuxt-layer-ui'],
  tgmc: { theme: true, icon: true, primevue: true, media: true },
});
Flag Layer Off means
theme base No @tgmc/theme stylesheet or Sass. scss/fallback.css gives the theme names the layers read, with CSS system colours, and SFC styles get scss/_fallback.scss (the focus mixins).
icon base @nuxt/icon isn’t installed; <Icon> is a null stub. Icon-only controls show their accessible name as text.
primevue ui @primevue/nuxt-module isn’t installed; Prime* tags are null stubs; the kit renders native markup; $toast feeds UiToastHost’s native list. Needs theme.
media ui app/components/media isn’t registered; @tgmc/media-client / @tgmc/media-player needn’t be installed. A base-only app ignores primevue and media.

2. Standard component structure

Tier Examples Shape Native fallback
0 Accessibility primitives (base) UiSkipLink, UiAnnouncer, UiVisuallyHidden .vue native only
1 Primitives UiButton, UiInputText, UiSelect ui/UiX.vue required (useUiStack)
2 Composites UiFormField, UiForm, UiConfirmDialog, UiDrawer, UiConfirmInline, UiUndoNotice ui/UiX.vue required
3 Complex UiDataTable, UiChart, UiRichTextEditor, UiMultiUpload, UiCrudView ui/UiX/index.vue + UiX.scss (<style src scoped>) + types.ts simplest semantic equivalent

The working standard derived from this section is UI components. UiVisuallyHidden doesn’t exist yet: until it does, the theme’s .sr-only class covers it (UiButton’s new-tab note uses it).

Tier 3 fallbacks (each also covers no-JS and SSR):

App* / Admin* components stay in the apps. Logic lives in composables and utils; components are views.

Code conventions:

UiButton:

interface UiButtonProps {
  label?: string;
  icon?: string;
  ariaLabel?: string;
  severity?: 'secondary' | 'success' | 'info' | 'warn' | 'danger' | 'contrast' | 'help';
  variant?: 'outlined' | 'text' | 'link' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  loading?: boolean; // aria-busy + aria-disabled, stays focusable, clicks ignored
  to?: RouteLocationRaw;
  href?: string; // NuxtLink / a with p-button classes
  external?: boolean; // target=_blank + visually hidden "(opens in a new tab)"
  type?: 'button' | 'submit' | 'reset';
  disabled?: boolean;
}

loading is ignored on links (to / href).

Testing:

Docs:

3. Forms: in-house useForm on Standard Schema (zod 4)

Why not @primevue/forms:

Shipped in PR 3. The working reference (examples, every option, the leave dialog, tests) is UI components § Forms; this section keeps the design.

Where the code lives. Nuxt auto-imports every export of a layer’s app/utils and app/composables, and server code mustn’t import app/ files, so the pure code sits elsewhere:

The blueprint’s useFormField and shared/types.ts weren’t needed: UiFormField reads the controller that UiForm provides.

import type { StandardSchemaV1 } from '@standard-schema/spec';
type In<S extends AnyFormSchema> = StandardSchemaV1.InferInput<S>;
type Out<S extends AnyFormSchema> = StandardSchemaV1.InferOutput<S>;
export type AnyFormSchema = StandardSchemaV1<Record<string, unknown>>;
export type FieldErrors = Record<string, string[]>; // dot paths
export type ServerFormError = { fieldErrors?: FieldErrors; formError?: string };
export type FormStatus = 'idle' | 'invalid' | 'pending' | 'saved' | 'failed';
export interface UseFormOptions<S extends AnyFormSchema> {
  schema: S;
  initialValues: In<S>;
  id?: string; // id prefix: `${id}-${name}`; default useId()
  validateOn?: { initial: 'blur' | 'submit'; afterError: 'change' }; // default { initial: 'submit', afterError: 'change' }
  onSubmit(values: Out<S>, ctx: { signal: AbortSignal }): Promise<void> | void;
  mapServerError?(error: unknown): ServerFormError | null; // default reads FetchError.data.data; null = handled elsewhere
  announce?: { saving?: string; saved?: string } | false;
}
export interface FormController<S extends AnyFormSchema = AnyFormSchema> {
  readonly id: string;
  readonly values: Ref<In<S>>;
  readonly errors: Readonly<Ref<FieldErrors>>;
  readonly formError: Ref<string | null>;
  readonly touched: Readonly<Ref<ReadonlySet<string>>>;
  readonly dirty: ComputedRef<boolean>;
  readonly pending: Readonly<Ref<boolean>>;
  readonly status: Readonly<Ref<FormStatus>>;
  readonly statusMessage: ComputedRef<string>; // "Saving…", the saved text while clean, else ''
  readonly submitCount: Readonly<Ref<number>>;
  readonly errorCount: ComputedRef<number>; // fields with an error, plus one for a form-level error
  fieldId(name: string): string;
  error(name: string): string | undefined;
  field(name: string): FieldBinding;
  handleSubmit(event?: Event): Promise<void>;
  validate(name?: string): Promise<boolean>;
  setErrors(errors: ServerFormError): void;
  reset(values?: In<S>): void; // no argument: back to the last baseline
  rebase(name: string, normalized: unknown): void;
  focusFirstInvalid(): void;
  abort(): void;
}
export interface FieldBinding {
  id: string;
  name: string;
  modelValue: unknown;
  'onUpdate:modelValue': (value: unknown) => void;
  onBlur: () => void;
  'aria-invalid'?: 'true';
  'aria-describedby'?: string; // only when it points at something
  'aria-labelledby'?: string; // added by UiFormField
  'aria-required'?: 'true'; // added by UiFormField
}
UiForm(:form="form", aria-labelledby="post-form-title")
  UiFormErrorSummary
  UiFormField(name="title", label="Title", required, v-slot="{ field, invalid }")
    UiInputText(v-bind="field", :invalid="invalid")
  UiFormField(name="body", label="Body", hint="Markdown", required, v-slot="{ field, invalid }")
    UiTextarea(v-bind="field", :invalid="invalid", :rows="16")
  UiFormActions
    UiButton(type="submit", label="Save", :loading="form.pending.value")
UiConfirmDialog(v-bind="leavePrompt.dialog.value")

4. Data and CRUD

export interface CrudAdapter<T, Id, F, C = Partial<T>, U = Partial<T>> {
  getId(item: T): Id;
  list(p: {
    filter: F;
    offset: number;
    limit: number;
    sort?: SortState;
    signal: AbortSignal;
  }): Promise<{ items: T[]; total?: number }>;
  get?(id: Id): Promise<T>;
  create?(input: C): Promise<T>;
  update?(id: Id, patch: U): Promise<T>;
  remove?(id: Id): Promise<void>;
}
export interface SortState {
  field: string;
  order: 'asc' | 'desc';
}
export function usePagedList<T>(o: {
  fetchPage: (p: { offset: number; limit: number; signal: AbortSignal }) => Promise<{ items: T[]; total?: number }>;
  pageSize?: number;
  key: MaybeRefOrGetter<unknown>;
}): {
  items: Ref<T[]>;
  total: Ref<number | undefined>;
  loading: Ref<boolean>;
  error: Ref<unknown>;
  hasMore: ComputedRef<boolean>;
  loadMore(): Promise<void>;
  reset(): void;
};
export function useConfirmUndo<T, Id>(o: {
  getId(item: T): Id;
  describe(item: T): string;
  hide(item: T): void;
  restore(item: T): void;
  commit(item: T): Promise<void>;
  delayMs?: number;
}): {
  confirmingId: Ref<Id | null>;
  request(item: T): void;
  cancel(): void;
  confirm(item: T): void;
  undo(id: Id): void;
  pending: Ref<Array<{ item: T; deadline: number; paused: boolean }>>;
  pause(id: Id): void;
  resume(id: Id): void;
  flush(): Promise<void>;
};
export function useCrudResource<T, Id, F>(
  adapter: CrudAdapter<T, Id, F>,
  o: { filter: Ref<F>; pageSize?: number }
): ReturnType<typeof usePagedList<T>> & {
  save(id: Id | null, input: Partial<T>): Promise<T>;
  undoable: ReturnType<typeof useConfirmUndo<T, Id>>;
  selected: Ref<T | null>;
};
export function useRouteQueryState<S extends object>(
  codec: { keys: readonly string[]; read(q: LocationQuery, d: S): S; write(s: S, d: S): LocationQuery },
  defaults: S
): ToRefs<S> & { filtered: ComputedRef<boolean>; clear(): void };
// useBrowseQuery becomes useRouteQueryState(browseCodec, defaults), keeping the same behaviour

UiDataTable wraps PrimeVue DataTable and Column:

export interface UiDataTableColumn<T> {
  field: string;
  header: string;
  sortable?: boolean;
  align?: 'start' | 'end';
  format?(value: unknown, row: T): string;
  priority?: 1 | 2 | 3;
  headerHidden?: boolean;
}
export interface UiDataTableProps<T> {
  rows: T[];
  columns: UiDataTableColumn<T>[];
  rowKey: string | ((r: T) => string);
  caption: string;
  captionHidden?: boolean;
  loading?: boolean;
  emptyMessage?: string;
  selectionMode?: 'single' | 'multiple';
  paginator?: { rows: number; totalRecords?: number } | false;
  lazy?: boolean;
}
// v-model:sort / selection / page; emits rowActivate; slots cell-<field>, actions, empty, toolbar

UiChart wraps PrimeVue Chart (Chart.js):

export type ChartTone = 'primary' | 'secondary' | 'accent' | 'success' | 'warning' | 'error' | 'info' | 'neutral';
export interface UiChartProps {
  type: 'bar' | 'line' | 'pie' | 'doughnut';
  title: string;
  summary: string;
  labels: string[];
  series: Array<{ label: string; data: number[]; tone?: ChartTone }>;
  valueFormat?(n: number): string;
  table?: 'toggle' | 'visible';
  height?: string;
}

UiCrudView:

export interface UiCrudViewProps<T, Id, F> {
  resource: ReturnType<typeof useCrudResource<T, Id, F>>;
  title: string;
  columns: UiDataTableColumn<T>[];
  itemLabel(row: T): string;
  filters?: Array<{
    key: keyof F & string;
    label: string;
    type: 'chips' | 'select' | 'search';
    options?: { value: string; label: string }[];
  }>;
  editor?: 'drawer' | 'page';
  canCreate?: boolean;
  canEdit?: boolean;
  canDelete?: boolean;
}
// v-model:view ('table'|'grid'); slots toolbar, summary (UiChart), cell-<field>, grid-item, editor({ item, close }), empty

5. UiRichTextEditor (Tiptap v3)

export interface UiRichTextEditorProps {
  modelValue?: string;
  id?: string;
  label?: string;
  ariaDescribedby?: string;
  invalid?: boolean;
  placeholder?: string;
  maxLength?: number;
  headingLevels?: Array<2 | 3 | 4>;
  sourceToggle?: boolean;
}
// emits update:modelValue(md), normalized(md) → form.rebase, blur; expose focus()

6. UiMultiUpload

export type UploadStatus =
  'queued' | 'uploading' | 'processing' | 'done' | 'error' | 'canceled' | 'conflict' | 'rejected';
export interface UploadItem<R = unknown> {
  id: string;
  file: File;
  name: string;
  status: UploadStatus;
  progress: number | null;
  error?: string;
  conflict?: { suggestedName: string | null; message: string };
  result?: R;
  attempts: number;
}
export class UploadConflictError extends Error {
  constructor(
    readonly suggestedName: string | null,
    msg: string
  ) {
    super(msg);
  }
}
export interface UploaderAdapter<R> {
  readonly reportsProgress: boolean;
  readonly maxBytes?: number;
  upload(
    file: File,
    ctx: { name: string; signal: AbortSignal; onProgress(loaded: number, total: number): void }
  ): Promise<R>;
}
export interface UploadRules {
  accept?: string[];
  maxBytes?: number;
  maxFiles?: number;
  allowEmpty?: boolean;
}
export type ConflictDecision = { action: 'rename'; name: string } | { action: 'skip' };
export function useUploadQueue<R>(o: {
  adapter: UploaderAdapter<R>;
  rules?: UploadRules;
  concurrency?: number;
  onConflict?(item: UploadItem<R>): Promise<ConflictDecision>;
}): {
  items: Ref<UploadItem<R>[]>;
  add(files: FileList | File[]): void;
  cancel(id: string): void;
  cancelAll(): void;
  retry(id: string): void;
  retryFailed(): void;
  remove(id: string): void;
  active: ComputedRef<boolean>;
  summary: ComputedRef<{ done: number; failed: number; total: number }>;
};

7. Duplicates to consolidate

8. Defects to fix in the nuxt-layer-base draft (Task 4)

  1. useA11yAnnouncer uses module-level refs, which leak between SSR requests. Use useState('tgmc:a11y:polite' | 'tgmc:a11y:assertive'), run timers only on the client, and clear any pending timer.
  2. role="status" combined with a dynamic aria-live="assertive" contradicts itself. Render two always-present regions, one role="status" and one role="alert", mounted once with an instance guard.
  3. UiSkipLink:
    • Its colour literals (#ffffff, #111827, #0284c7, rgba(...)) fail colors-scss.
    • top: -9999px fails the units policy.
    • outline: none plus a shadow-only focus state disappears in forced-colors mode.

    Fix: theme roles, the focus-ring-shadow mixin, min-height: var(--touch-target) and transform: translateY(-120%). The target <main id> needs tabindex="-1"; check for an existing skip link in layouts/site.vue.

  4. Templates aren’t Pug. Use the theme’s visually-hidden utility (check its name in theme/core/scss/globals).
  5. The ../../theme/core path works only inside the monorepo. Use pkg: or createRequire.
  6. additionalData collides with the apps’ own (the app’s function wins), and it lacks the node_modules and nuxt-auto guards. Make the layer the single owner via tgmcScssAdditionalData(extra).
  7. @nuxt/icon ^1.10.3 installs a nested v1. Align to ^2.5.1, pin @nuxt/a11y to root’s resolved version, set nuxt ^4.5, and add @iconify-json/lucide.
  8. The icon config has no clientBundle. Move the list into src/config/icons.ts and retarget the test.
  9. Auto-imports:
    • imports.imports doesn’t cover server routes (that needs nitro.imports).
    • imports.dirs: ['app/composables'] probably resolves to app/app/composables (verify); drop it.
    • Prefer explicit imports over generic names (isObject, deepMerge), and verify they exist in @tgmc/utilities/universal.
  10. The head meta duplicates Nuxt’s defaults; use app.head.charset / viewport. htmlAttrs.lang conflicts with @nuxtjs/i18n, so leave it to the app.
  11. The a11y config fails on violations and writes its report in every environment, and rules: [] does nothing. Scope it: $development for highlights and logging, $test for the report with fail-on-violation, $production disabled.
  12. Missing plumbing: Nx targets, tsconfig.json, eslint.config.js, Prettier Pug config, vitest.config.ts, and a nuxt prepare step for types.
  13. Name collisions: register under app/components/a11y with pathPrefix: false and check that no Ui* names are duplicated.
  14. Announcer race: the 50ms clear-then-set loses back-to-back messages. Queue messages or use { id, text }, and clear the timer on each call.