ui-bundle-anatomy

name

ui-bundle-anatomy

description

How the pdocs Antora UI bundle package (code/packages/ui-bundle) is structured and built — directory layout, the gulp/esbuild/PostCSS pipeline, the Handlebars template tree, the helper compilation contract, the TypeScript config split and the preview harness. USE WHEN adding or editing a partial, layout, helper, browser script or stylesheet in that package, changing anything under gulp.d, debugging a build/preview failure, or working out where a change belongs. EXAMPLES: 'add a new partial', 'my helper isn't registered', 'why is the font corrupted in the zip', 'add a language to syntax highlighting', 'the preview doesn't rebuild', 'where does site.js come from'.

UI bundle — anatomy

code/packages/ui-bundle (@inditextech/pdocs-ui-bundle) is an Antora UI bundle: a zip of layouts, partials, helpers, CSS, JS and images that Antora unpacks and uses to render every page of a site. It is a fork of antora-ui-default, modernised (gulp 5, esbuild, PostCSS 8, TypeScript) and re-skinned onto the IOP Design System.

It builds one artifact:

build/ui-bundle-<version>.zip   canonical, versioned — the thing you publish
build/ui-bundle.zip             copy of the above under a stable name

<version> is package.json's version, moved in lockstep with the workspace by just bump. The unversioned copy exists because Antora's ui.bundle.url takes a literal path and does not glob, so a versioned-only output would force a playbook edit on every bump.

This skill covers the package itself. For what CSS to write read iop-ds-foundations (tokens, theming, breakpoints); for what markup to emit read iop-ds-components.

Layout

path	what it is
src/ui.yml	bundle descriptor. Only declares static_files (files copied to the site root verbatim)
src/layouts/*.hbs	page shells. default.hbs, home.hbs, 404.hbs. A page picks one via page-layout
src/partials/*.hbs	every other template. Registered by basename, included as {{> stem}}
src/helpers/*.ts	Handlebars helpers. Filename = helper name. Compiled to CommonJS
src/js/NN-*.ts	browser behaviour, bundled into js/site.js
src/js/vendor/*.bundle.ts	separately bundled third-party scripts → js/vendor/*.js
src/css/*.css	stylesheets, all reached through src/css/site.css
src/img/*.svg	icons, optimised with svgo on release builds
src/static/**	copied to the site root, not the UI root (currently .nojekyll)
types/ui.d.ts	typings for the Handlebars call shape helpers receive
types/browser.d.ts	ambient globals for the browser scripts
gulpfile.js, gulp.d/	the build. Tasks in gulp.d/tasks, shared utilities in gulp.d/lib
preview-src/	standalone preview: ui-model.yml fixture plus .adoc pages
index.js	placeholder so the package is resolvable with require.resolve

Generated, all gitignored: public/ (preview site; public/_ is the staged bundle), build/ (zips), .tsbuild/helpers (compiled helpers).

Inside the zip the tree is flat and fixed — Antora looks for these exact names:

ui.yml  layouts/  partials/  helpers/  css/site.css  js/site.js  js/vendor/  img/  font/

Where a change goes

you want to	edit	then
change page structure / chrome	a partial in src/partials, or a layout	nothing — partials are auto-registered by basename
add styling	a file in src/css	add an @import to src/css/site.css in the right position
add page behaviour	a new src/js/NN-name.ts	add an explicit import './NN-name' to src/js/index.ts
add template logic	a new src/helpers/name.ts	nothing — but it must use export =
ship a third-party script	src/js/vendor/name.bundle.ts	reference js/vendor/name.js from a partial
copy a file to the site root	drop it in src/static/	list it under static_files in src/ui.yml

Import order in site.css is load-bearing: design system tokens first, then bridge.css (maps legacy --body-* names onto --ids-*), then vars.css (layout metrics only), then the leaf stylesheets. Anything that consumes a token must come after the token layer.

Browser scripts are side-effect IIFEs and their numeric prefixes encode execution order, so numbering and the explicit import list are both deliberate — no glob import.

Constraints that fail silently

Each of these has cost someone a debugging session. They are enforced by nothing but this list and the comments in the source.

• Helpers must be CommonJS with export =. Antora requires each file in helpers/ and expects module.exports to be the function. That is why helpers go through tsc (tsconfig.helpers.json → .tsbuild/helpers) and not esbuild, whose CJS output would expose the function as exports.default — Handlebars would then register a non-callable helper and every use renders as nothing.
• Never put a shared module in src/helpers/. Every file there becomes a helper named after its basename. Shared types live in types/ui.d.ts for exactly this reason.
• Never flatten custom properties at build time. Dark mode, the density scale and the resolution tiers are runtime custom-property swaps done by the design system. A build that inlines their values ships a permanently light, fixed-density site.
• Any vfs.src that can touch a binary needs encoding: false, removeBOM: false. vinyl-fs 4 decodes contents as UTF-8 by default (v3 did not) and corrupts fonts and raster images — woff2 files came out of the zip at nearly double size and browsers rejected them with incorrect file size in WOFF header.
• An async gulp task must await its own stream, await finished(stream.resume()). Gulp waits on a returned stream or a returned promise; a promise that resolves to a stream is only awaited as a promise, so the task reports success before anything is written — and the stream stalls at the object-mode highWaterMark because nobody drains it.
• Vendor entries must be named *.bundle.ts. The infix is stripped to produce the output name; a file without it is not bundled at all.
• Optional source directories must go through existingGlobs. src/css/vendor and src/font do not exist until someone adds a vendored stylesheet or a self-hosted font, and vinyl-fs 4 throws ENOENT on a glob whose literal prefix is missing.
• Lint and format are Nx targets, not gulp tasks. The gulp wrappers for eslint and stylelint are ESM-only and this pipeline is CommonJS; Nx caches the standalone binaries anyway.
• The inline theme bootstrap in head-prelude.hbs and src/js/08-theme.ts share a storage key and class names. Change one, change the other. The inline copy exists to set the theme before first paint; IDS keys theming off a class on ( / ), not a data attribute.

Commands

Run from code/ (the Nx workspace root — pnpm does not resolve above it).

command	does
just preview-ui	live-reloading preview on http://localhost:5252
pnpm nx run @inditextech/pdocs-ui-bundle:build	gulp bundle — clean, build, pack, alias
pnpm nx run @inditextech/pdocs-ui-bundle:typecheck	both tsconfigs (helpers strict, browser loose)
pnpm nx run @inditextech/pdocs-ui-bundle:lint	eslint + stylelint (lint:fix to autofix)
pnpm nx run @inditextech/pdocs-ui-bundle:clean	remove build/, public/, .tsbuild/

Nx infers these targets from package.json scripts — the package has no project.json. Caching, inputs and outputs come from targetDefaults in code/nx.json; build is cached with output {projectRoot}/build, preview and clean are not cached.

Gulp task names, if you invoke gulp directly: bundle (default), build, bundle:build, bundle:pack, bundle:alias, clean, preview, preview:build.

Environment:

variable	effect
LIVERELOAD=false	disables gulp-connect livereload in the preview (on by default)
SOURCEMAPS=true	emit sourcemaps from a non-preview build (preview always does)
CI	suppresses the bundle-path log from bundle:alias; also hides the edit-this-page link

Reference

• reference/build-pipeline.md — task graph, every file in gulp.d, the PostCSS chain, esbuild config, and what each piece replaced upstream.
• reference/templates.md — the full layout/partial tree, the UI model, the helper catalogue, and the conventions templates rely on.
• reference/preview.md — the preview harness, the sample UI model, and the TypeScript / eslint / stylelint configuration split.