@asd20/ui-next

Shared Vue 3 UI package for Academy District 20 websites and web apps.

Current local version: 2.10.4

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

• Node >=20
• npm >=10
• Vue peer dependency ^3.0.0
• Package build system: Vue CLI / webpack
• Unit test runner: Vitest
• Component development: Storybook

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

npm install
npm run storybook
npm test
npm run build

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 packs the staged package, installs it into a temporary Vue 3 smoke app, imports the public components/templates/icons/helpers/directives/styles, and confirms the consumer build succeeds.

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.

Change Guidance

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.