@dataengineeringformachinelearning/viking-ui 1.0.2 → 3.0.0-alpha.2

package/README.md

@@ -1,69 +1,208 @@
-# @dataengineeringformachinelearning/viking-ui
+# Viking-UI
 
-**Viking-UI** is DEML's clinical Angular design system — lab-coat aesthetics on THEME.md tokens.
+Universal DEML component library for Astro, Angular, and Django.
 
-- **8px grid** spacing (`--space-1` … `--space-8`)
-- **16px** main content / **14px** UI chrome typography
-- **Crayola blue** (`#2176ff`) primary, **blue-bell** (`#33a1fd`) accents
-- Zero-dependency components (`viking-*` selectors, `--viking-*` tokens)
-- WCAG 2.1 AA focus rings, axe-core tested templates
+## Architecture
 
-## Install
+- `src/styles/_variables.scss` defines the canonical `--viking-*` design tokens.
+- `src/styles/components-bundle.scss` defines static CSS primitives shared by every app.
+- `src/tokens/viking-tokens.json` exposes the same token contract for tooling.
+- `src/elements/` contains framework-neutral Web Components with Shadow DOM style isolation.
+- `dist/design-tokens.css`, `dist/viking-components.css`, `dist/deml-components.css`, `dist/viking-ui.css`, `dist/viking-tokens.json`, and `dist/viking-ui-elements.js` are the built artifacts.
+- `dist/viking-ui.css` is the full app bundle. Load it once per surface; do not stack it with the split CSS artifacts.
+
+## Build
 
 ```bash
-npm install @dataengineeringformachinelearning/viking-ui
+npm run build --prefix packages/viking-ui
+npm run test:viking-ui:package
 ```
 
-Peer dependencies: `@angular/core` ^22, `@angular/common` ^22, `@angular/forms` ^22.
+## Versioning
 
-## Usage
+Viking-UI uses Changesets from the repository root:
 
-```typescript
-import {
-  VikingButton,
-  VikingField,
-  VikingInput,
-} from '@dataengineeringformachinelearning/viking-ui';
+```bash
+npm run changeset
+npm run version:viking-ui
 ```
 
-Load static CSS for non-Angular surfaces (marketing, Django templates):
+See [docs/viking-ui-release.md](../../docs/viking-ui-release.md) for the full
+release, visual regression, and propagation workflow.
+
+## Consumption
 
 ```html
-<link rel="stylesheet" href="/assets/design-tokens.css" />
 <link rel="stylesheet" href="/assets/viking-ui.css" />
+<script type="module" src="/assets/viking-ui-elements.js"></script>
 ```
 
-## Build
+```ts
+import "@dataengineeringformachinelearning/viking-ui/elements.js";
+import "@dataengineeringformachinelearning/viking-ui/viking-ui.css";
+```
 
-```bash
-npm run build:viking-ui
-npm run build:viking-ui-css
-npm run serve:viking-ui-showcase
+## Use via CDN (jsDelivr)
+
+The package artifacts are published in `dist/`, so you can load them directly from jsDelivr:
+
+### 1) CSS only
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@latest/dist/viking-ui.css"
+/>
 ```
 
-## Version bump
+### 2) Web Components only
 
-Bump `package.json` in this directory before every publish (npm will not overwrite an existing version).
+```html
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@latest/dist/web-components.js"
+></script>
+```
 
-```bash
-cd frontend/projects/viking-ui
-npm version patch --no-git-tag-version   # or minor / major
+### 3) CSS + Web Components together
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@latest/dist/viking-ui.css"
+/>
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@latest/dist/web-components.js"
+></script>
 ```
 
-| Bump  | When                                     |
-| ----- | ---------------------------------------- |
-| patch | Bug fixes, token/CSS tweaks, a11y fixes  |
-| minor | New components, additive APIs            |
-| major | Breaking input/output or removed exports |
+### 4) Version pinning
 
-## Publish
+Use `@latest` for latest stable assets, or replace it with a concrete version for locked
+builds.
 
-Requires membership in the npm org `dataengineeringformachinelearning` (scope `@dataengineeringformachinelearning`).
+```html
+<!-- Latest -->
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@3.0.0-alpha.2/dist/viking-ui.css"
+/>
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@3.0.0-alpha.2/dist/web-components.js"
+></script>
+```
+
+```html
+<!-- Pinned -->
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@3.0.0-alpha.2/dist/viking-ui.css"
+/>
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@3.0.0-alpha.2/dist/web-components.js"
+></script>
+```
+
+### 5) Full minimal HTML example (copy/paste)
+
+```html
+<!doctype html>
+<html lang="en" data-theme="dark">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Viking-UI CDN demo</title>
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@latest/dist/viking-ui.css"
+    />
+    <script
+      type="module"
+      src="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@latest/dist/web-components.js"
+    ></script>
+  </head>
+  <body>
+    <main
+      style="max-width: 680px; margin: 2rem auto; display: grid; gap: 1rem;"
+    >
+      <h1 class="viking-heading viking-heading-xl">Viking widget</h1>
+      <viking-card-wc compact>
+        <h2 class="viking-heading viking-heading-sm">Widget card</h2>
+        <p class="viking-text-muted">
+          Works in marketing pages and external websites.
+        </p>
+      </viking-card-wc>
+      <viking-button-wc variant="primary">Open dashboard</viking-button-wc>
+    </main>
+  </body>
+</html>
+```
+
+### 6) Status widget via jsDelivr (no npm install)
+
+Use this when embedding a live status badge on external pages:
+
+```html
+<!doctype html>
+<html lang="en" data-theme="dark">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>DEML Status Widget</title>
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@latest/dist/viking-ui.css"
+    />
+    <script
+      type="module"
+      src="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@latest/dist/web-components.js"
+    ></script>
+    <script
+      src="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@latest/dist/widget.js"
+      async
+      defer
+      data-page-id="platform-status"
+      data-backend-url="https://api.example.com"
+      data-frontend-url="https://deml.app"
+    ></script>
+  </head>
+  <body></body>
+</html>
+```
+
+Pinned release example:
+
+```html
+<script
+  src="https://cdn.jsdelivr.net/npm/@dataengineeringformachinelearning/viking-ui@3.0.0-alpha.2/dist/widget.js"
+  async
+  defer
+  data-page-id="platform-status"
+  data-backend-url="https://api.example.com"
+  data-frontend-url="https://deml.app"
+></script>
+```
+
+Replace `api.example.com` with your backend URL and update `data-page-id` / `data-frontend-url` for your status page.
+
+This package is the source of truth. Existing Angular wrappers in `frontend/projects/viking-ui` adapt the design system for Angular while migration continues; Astro and Django consume the package artifacts directly through synced static assets.
+
+Angular app shells consume the package CSS from `angular.json`:
+
+```json
+{
+  "styles": ["../packages/viking-ui/dist/viking-ui.css", "src/styles.scss"]
+}
+```
+
+Django, marketing, and showcase static assets are copied from `packages/viking-ui/dist` by:
 
 ```bash
-cd frontend
-npm run test:viking-ui
-npm run build:viking-ui
-cd dist/viking-ui
-npm publish --access public --otp=YOUR_CODE
+python scripts/sync_design_system.py
+node scripts/validate_viking_ui_assets.mjs
 ```
+
+See [MIGRATION_PLAN.md](./MIGRATION_PLAN.md) for the rebuild phases.