@hybridlabor-api/ui-motion-library

v0.1.0

Published

13 days ago

BDB UI Motion Library. W3C-DTCG tokens, motion icons and shadcn-registry components.

Downloads

246

0High
0Medium
0Low

hybridlabor-api

bdb-ui-library

BDB AOS Component Registry / Library — Single Source of Truth fuer Tokens, Komponenten und Motion-Icons.

Name: @hybridlabor-api/ui-motion-library
npm-Scope: @hybridlabor-api | shadcn-Namespace: @bdb
Status: P0-P4 (Scaffold, Tokens, Registry-Core, Pipeline, Distribution, Start-Set: 7 Items)
Lizenz: MIT

Aufnahme-Checkliste (pro Item, P2-Pipeline)

So kommt JEDES neue Item in die Registry (Video-Agents bekommen spaeter dieselbe Pipeline):

Vorlage kopieren: src/components/_template.tsx → src/components/{Name}.tsx, registry/_template.json → registry/{name}.json; Item in registry.json items ergaenzen (_-Praefix-Files sind Vorlagen und werden von validate/evidence ausgenommen).
DTCG-only Styling: alle Farben/Abstaende/Radien/Schatten/Durations ueber CSS-Variablen aus src/tokens/ (npm run tokens → tokens.css). Keine Hardcoded-Hex/px-Werte im Component-Code.
Dark/Light: Item muss unter beiden Themes korrekt rendern (:root Light-Default, [data-theme="dark"]); Pruefung im Evidence-Screenshot (BDB_EVIDENCE_THEME/Theme-Attribut in demo/evidence.html).
prefers-reduced-motion: Pflicht-Guard bei jeder Animation (@media (prefers-reduced-motion: reduce) { ... animation: none } oder Respektierung via Motion-Utilities).
A11y-Primitives: interaktive Components auf Base UI bzw. Radix-Primitives aufbauen (Standard-Nennung, ADR-Basis), plus role/aria-label/Keyboard (tabIndex 0).
Evidence: npm run evidence erzeugt production_artifacts/evidence/{name}.png; fehlt ein PNG → Exit 1 (CI-Gate). Detail/Verhalten: scripts/README.md.
Validierung: node scripts/registry-validate.mjs Exit 0; npm run typecheck && npm test gruen.
Stil-Referenzen beobachten, Code immer neu schreiben: erlaubte Referenzen mit MIT-Lizenz sind /MIT-Referenzen Space UI und Componentry. ui-experiments (origin-space) hat eine NO-REDISTRIBUTION-Lizenz — strikt: nur Stil beobachten, kein Code kopieren, nichts redistributieren.

Distribution (templates/components.json, P3)

Verbraucher-Projekte (Apps, die shadcn nutzen) tragen die BDB-Registry in ihre components.json unter registries ein. Vorlagen liegen in templates/:

templates/components.json — canonical: @bdb zuerst (https://unpkg.com/@hybridlabor-api/ui-motion-library@latest/publish/registry/{name}.json, ab P5 via npm-CDN), dann @aceternity (https://ui.aceternity.com/registry/{name}.json), @magicui, @cultui, @watermelon. Lookup-Reihenfolge = Reihenfolge der Eintraege.
templates/components.local.json — Dev-Variante bis P5: @bdb zeigt auf http://127.0.0.1:4899/{name}.json (lokal geservter Registry-Build). Die Third-Party-Eintraege sind in beiden Vorlagen identisch.

shadcn-CLI-Kompatibilitaet (verifiziert, 4.21): jeder registries-Wert muss eine URL mit {name}-Platzhalter sein. Werte ohne {name} (https://ui.aceternity.com) oder Namespace-Referenzen (@spaceui/essentials) machen die komplette components.json invalid (Invalid configuration found ...). @spaceui/@componentry sind deshalb (bis ein verifizierter URL-Endpunkt existiert) nicht in den Vorlagen; ihre Registry-Packages bleiben ueber ihre eigene Doku konsumierbar.

Einbau (canonical, ab P5):

cp templates/components.json /pfad/zum/verbraucher-projekt/components.json
npx shadcn@latest add @bdb/knob

Einbau (dev bis P5):

npm run registry:build   # shadcn build registry.json -o serve/r (inlined file contents)
npm run registry:serve   # statischer Server auf http://127.0.0.1:4899 (serviert serve/r)
# im Verbraucher-Projekt: components.json aus templates/components.local.json kopieren
npx shadcn@latest add @bdb/knob

Alternativ ohne components.json-Eintrag (direktes lokales File): npx shadcn@latest add "$(pwd)/serve/r/knob.json".

Registry-Verhalten (verifiziert, shadcn CLI 4.21.3)

Namespaced-Registry-Werte werden ausschliesslich als URLs aufgeloest. Ein relativer Pfad wie ../bdb-ui-library/registry/{name}.json wird zu https://ui.shadcn.com/r/../bdb-ui-library/registry/knob.json gemischt und schlaegt fehl: The item at https://ui.shadcn.com/r/../bdb-ui-library/registry/knob.json was not found.
file:-URLs sind im CLI nicht implementiert: Request to file:///... failed, reason: not implemented... yet...
Item-JSONs ohne inliniertes content in files[] (unser registry/{name}.json Authoring-Format) schreiben beim Add nichts (No files updated). Konsum laeuft deshalb ueber npm run registry:build (Output serve/r/) oder das npm-Paket.

Items

| Name | Beschreibung | Type | Files | Dependencies | Animationen | |---|---|---|---|---|---| | knob | Rundes Steuergeraet/Einstellknopf als Motion-Icon im Lucide-Stil. Aussenbogen statisch, innerer Knopf (Kreis + Indikator-Punkt) rotiert selbst. Self-animated. | registry:component | src/icons/Knob.tsx, src/icons/use-as-motion-icon.tsx, src/icons/index.ts | react only (core); lucide-react/motion-icons-react optional | spin, pulse, none | | thermostat | Dial-Thermostat als Motion-Icon. Aussenring + Top-Tick statisch, inneres Display (Gauge-Bogen, Nadel, Indikator-Dot) rotiert selbst. Self-animated. | registry:component | src/icons/Thermostat.tsx, src/icons/use-as-motion-icon.tsx, src/icons/index.ts | react only (core); lucide-react/motion-icons-react optional | spin, pulse, none | | volume | Lautsprecher mit Volumenring als Motion-Icon. Ring-Track statisch, Ring-Fuellbogen wandert auf spin, Wellen pulsieren auf pulse. Self-animated. | registry:component | src/icons/Volume.tsx, src/icons/use-as-motion-icon.tsx, src/icons/index.ts | react only (core); lucide-react/motion-icons-react optional | spin, pulse, none | | statuspill | Pill mit Status-Dot, Varianten success/warn/error/info ueber Semantik-Tokens. role=status, optionale Dot-Puls-Animation (reduced-motion-respektierend). | registry:component | src/components/StatusPill.tsx | react only | pulse (Dot, opt-in) | | thinkingorb | Pulsierender Lade-/Thinking-Orb: Acid-Gradient-Kern + Glow-Layer, CSS-Anims aus Motion-Tokens, role=status, reduced-motion rendert statischen Orb. | registry:component | src/components/ThinkingOrb.tsx | react only | breathe (Glow/Kern) | | glasscard | Glassmorphism-Karte: backdrop-filter (blur sm/md/lg via Tokens), translucide Token-mixed Surface/Border, Theme-Shadow, dark+light. | registry:component | src/components/GlassCard.tsx | react only | - | | particletext | Canvas-Partikel-Typografie: Text wird gesampelt, Partikel konvergieren in die Glyphen. Farben via Tokens, echtes Text-Element als Screenreader-Text, reduced-motion rendert statischen Endzustand. | registry:component | src/components/ParticleText.tsx | react only | converge (einmalig) |

Install

shadcn-Registry (Standard, ab P5 via unpkg/npm-CDN):

npx shadcn@latest add @bdb/knob

npm-Package:

npm install @hybridlabor-api/ui-motion-library

import { KnobIcon } from '@hybridlabor-api/ui-motion-library';
import { MotionIcon } from '@hybridlabor-api/ui-motion-library/motion';
import '@hybridlabor-api/ui-motion-library/tokens.css';

<MotionIcon name="Knob" animation="spin" />

Registry-Items direkt (Agent-native):

Index: https://unpkg.com/@hybridlabor-api/ui-motion-library@latest/publish/registry/registry.json (lokal nach registry:build: serve/r/registry.json)
Item: https://unpkg.com/@hybridlabor-api/ui-motion-library@latest/publish/registry/knob.json (lokal: serve/r/knob.json)

Konventionen (Binding fuer alle Items)

DTCG-Tokens-only Styling: Components stylen ueber CSS-Variablen aus src/tokens/; keine Hardcoded-Hex/px-Werte im Component-Code. Tokens-Build: npm run tokens → tokens.css (Light-Default :root, Dark via [data-theme="dark"]).
Jedes Item liefert dark + light Variante.
prefers-reduced-motion-Guard ist Pflicht bei animierten Components.
A11y-Basis: role, aria-label, keyboard-faehig (interactive → tabIndex 0).
Keine Code-Kommentare in Quellfiles; Kommentar-generatoren (Agents) erzeugen statt kopieren.
Evidence-Pflicht: pro Item ein Headless-Screenshot unter production_artifacts/evidence/{name}.png.
Validierung: node scripts/registry-validate.mjs (Exit 0) ist Gate vor jedem Merge.

API (Knob / MotionIcon)

interface KnobIconProps {
  size?: number;               // Default 24
  color?: string;              // Default currentColor
  strokeWidth?: number;        // Default 2
  animation?: 'spin' | 'pulse' | 'none';  // Default 'spin'
  animationDuration?: number;  // ms, ueberschreibt Klassendauer
  className?: string;
  'aria-label'?: string;
  onClick?: (event: React.MouseEvent<HTMLSpanElement>) => void;
  onMouseEnter?: (event: React.MouseEvent<HTMLSpanElement>) => void;
  onMouseLeave?: (event: React.MouseEvent<HTMLSpanElement>) => void;
}

<MotionIcon name="Knob" animation="spin" size={48} />

MotionIcon registriert eigene Icons via registerIcon(name, component, selfAnimated?). Optional-Peers: lucide-react und motion-icons-react fuer Consumers, die Lucide-Icons in die Registry registrieren — der Knob-Kern braucht nur react.

Fremdprojekt in 2 Zeilen (P5, npm-CDN)

Die content-inlinierten Registry-Items werden mit dem npm-Paket ausgeliefert (publish/registry/ im Tarball) und sind ueber unpkg abrufbar. components.json im Fremdprojekt:

{ "registries": { "@bdb": "https://unpkg.com/@hybridlabor-api/ui-motion-library@latest/publish/registry/{name}.json" } }

npx shadcn add @bdb/statuspill

Wichtig: registry/{name}.json im Tarball ist das Authoring-Format OHNE inlined content — shadcn schreibt bei diesen nichts (verifiziert, 4.21). Der Registry-URL-Pfad ist deshalb publish/registry/{name}.json (content-inliniert, von npm run pack-registry aus serve/r/ befuellt).

Verifikation nach erstem Publish (noch offen):

curl -fsSL "https://unpkg.com/@hybridlabor-api/ui-motion-library@latest/publish/registry/statuspill.json" | grep -c content
# im Scratch-Projekt mit obiger components.json:
npx shadcn add @bdb/statuspill

Publish (P5)

Zwei Wege, beide publizieren @hybridlabor-api/ui-motion-library@<version> mit --access public:

GitHub-Workflow (empfohlen): Tag pushen.

git tag v0.1.0 && git push origin v0.1.0

.github/workflows/release.yml baut, testet und publishst. Voraussetzung: Einmalig Repo-Secret NPM_TOKEN anlegen (GitHub Repo → Settings → Secrets and variables → Actions → New repository secret) mit einem npm-Automation-Token fuer den Scope @hybridlabor-api. Token nie ins Repo committen.

Lokal (Token aus ~/_local-secrets/fleet-master.env, Variable NPM_API_TOKEN; Muster ohne Token-Wert — die temporaere npmrc enthaelt nur den Platzhalter):

set -a; source ~/_local-secrets/fleet-master.env; set +a
printf '//registry.npmjs.org/:_authToken=${NPM_API_TOKEN}\n' > "$TMPDIR/npmrc-bdb-publish"
cd ~/dev/bdb-dev/bdb-ui-library && npm publish --access public --userconfig "$TMPDIR/npmrc-bdb-publish"
rm "$TMPDIR/npmrc-bdb-publish"

Der Token-Wert selbst steht ausschliesslich in ~/_local-secrets/fleet-master.env und wird nie in eine committete (oder sonstige dauerhafte) Datei geschrieben. Lokaler Pack-Check vor dem Publish: npm pack --dry-run (listet alle Tarball-Files + Size; Gate: publish/registry/*.json muessen mit content inlined dabei sein).

Verify (lokal)

npm run build      # tsup (cjs+esm+dts) + tokens.css
npm test           # vitest
npm run validate   # registry.json + registry/*.json
npm run demo:build # vite build (demo/)

Struktur

src/icons/            Motion-Icons (Knob zuerst)
src/tokens/           W3C-DTCG: primitives/semantic/dark/light
registry.json         shadcn-Registry-Index
registry/knob.json    pro-Item-Definition
scripts/              tokens-build.mjs, registry-validate.mjs
demo/                 Vite-Preview (Beweis-Renderer)