@asd20/ui-next
Shared Vue 3 UI package for Academy District 20 websites and web apps.
Current local version: 2.34.6
This package is the active shared presentation layer for the ASD20 web platform. It provides reusable components, public website templates, app-shell templates, icons, design tokens, Sass helpers, assets, directives, and helper functions used by the Nuxt website, standalone apps, and selected CommCenter preview surfaces.
Platform Role
This repo owns the packaged UI contract for:
- public website templates consumed by
asd20-website - app templates and components consumed by calendar, directory, school directory, and file directory apps
- selected CommCenter preview components and icon/template imports
- global design tokens and Sass helpers shared across consumers
- icon metadata and SVG component exports
- helper functions for event/message/page/file/people mapping, search calls, organization labels, link handling, cookies, email, and analytics feedback
The package is published to npm as @asd20/ui-next. It should be treated as a
multi-repo contract, not as an app-local component folder.
Runtime Contract
Development, builds, and releases use Node 24.22.2 and npm 11.19.1
(bundled with that Node release). .nvmrc, .node-version, packageManager,
and the release workflow pin those versions. CI explicitly installs the pinned
npm version to keep local and release tooling aligned.
The published library keeps these consumer requirements:
- Node
>=20 - npm
>=10 - Vue peer dependency
^3.0.0
Development tools:
- Demo and packed-consumer build system: Vite
- Unit test runner: Vitest
- Component development: Storybook 10 with Vite
Breadcrumb Navigation
Website templates accept an optional breadcrumbContext page reference supplied
by the website's client navigation tracker. A visitor arriving from a wayfinding
page sees that section in the breadcrumb when the destination is one of its
message detail links or related pages. The context can continue between related
detail pages and is cleared when the visitor leaves that section.
Context is stored with the browser history entry, so refresh and Back/Forward can restore the context of that visit. Native same-tab links can also carry a short-lived arrival record when the referring page confirms the transition. Direct visits, unknown origins, unavailable browser storage, and discarded history state fall back to existing breadcrumbs. Context is restored after hydration.
Only the header links change. URLs, Related Pages, parentPage, dates,
categories, and the existing announcement/story navigation retain their behavior.
There is no per-page editor setting or additional breadcrumb data request.
Rollout requires releasing this UI package, updating the website's UI dependency, and deploying the website integration. CommCenter and the database need no changes.
Public Entry Points
Supported import paths are defined in package.json and guarded by
scripts/public-api-contract.js:
@asd20/ui-next@asd20/ui-next/components@asd20/ui-next/templates@asd20/ui-next/templates/*@asd20/ui-next/icons@asd20/ui-next/helpers@asd20/ui-next/directives@asd20/ui-next/install@asd20/ui-next/styles.css@asd20/ui-next/design/*@asd20/ui-next/assets/*@asd20/ui-next/package.json
Downstream repos should import through those paths. Private source imports are
not part of the supported contract unless they are explicitly covered by the
package exports map.
Source Layout
| Path | Purpose |
|---|---|
components.js | Public component exports. |
templates.js | Public template exports. |
icons.js | Generated icon component exports. |
helpers.js | Public helper exports. |
directives.js | Public directive exports. |
install.js | Vue plugin install helpers. |
src/components/atoms/ | Base UI components. |
src/components/molecules/ | Combined controls and display units. |
src/components/organisms/ | Larger site/app sections. |
src/components/templates/ | Website and app templates. |
src/design/ | CSS tokens, Sass helpers, typography, template stack, images. |
src/assets/icons/ | Raw SVG icon assets. |
src/helpers/ | Shared helper implementation. |
src/directives/ | Directive implementation. |
scripts/ | Build, package, release, and verification scripts. |
docs/migration/ | Historical migration and release notes. |
Local Development
nvm install
nvm use
npm install --global [email protected]
node --version # v24.22.2
npm --version # 11.19.1
npm ci
npm run storybook
npm test
npm run build
Optional harnesses are available to facilitate repeatable physical-device checks for scrolling, touch, focus, keyboard, and viewport changes:
npm run test:mobile:storybook
npm run test:mobile:package
These commands are manual testing aids. They are not testing, CI, release, or package-publishing requirements.
See Physical Mobile Device Testing for the device checklist, packed-consumer workflow, options, and troubleshooting.
Regenerate icon metadata after adding, removing, or renaming SVG icon assets:
npm run generate:icons
npm run verify:icon-metadata
Package Verification
Build the staged publish artifact:
npm run build:package
Verify the source and staged package contract:
npm run verify:publish
That command rebuilds dist/package, verifies public exports, verifies Vue 3
input/lifecycle/instance-id contracts, verifies the staged package, and runs
npm pack --dry-run.
Verify the packed consumer install path:
npm run verify:release
That command checks icon metadata, runs the unit tests and verify:publish,
then packs the staged package and extracts it into a temporary Vue 3 Vite
smoke app with dependencies linked from this checkout. It imports the public
components/templates/icons/helpers/directives/styles, verifies the package's
complete Vite development optimizer input set from a clean cache, and confirms
the production consumer build succeeds with Vite's default CSS minifier.
Release
npm run release
The release flow publishes from dist/package, tags as ui-next-v${version},
and runs npm run verify:release before publishing.
The main-branch workflow publishes automatically. For local validation, run
npm run lint, npm run verify:release, and npm run build-storybook;
verify:release includes verify:publish. These checks do not publish.
A development-runtime upgrade alone does not require a new library release.
Change Guidance
The PDFService implementation overview records the shared PDF publishing proposal, Azure findings, contextual heading requirements, affected repositories, and staged implementation work.
Before changing this package, identify which public entry point is affected and which downstream repos consume it. Template, style/token, icon, input model, and helper changes are especially likely to require downstream website or app verification.
For broader architecture context, see
../asd20-website/docs/platform/shared-ui-contract.md.
The migration record under docs/migration/ is retained for audit history,
release decisions, and future cleanup planning.