Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
289 lines (215 loc) · 11.9 KB

CONTRIBUTING.md

File metadata and controls

289 lines (215 loc) · 11.9 KB
Raw

Contributing to OrbUX

Thank you for helping make AI and agent interfaces more expressive, accessible, and dependable. OrbUX welcomes bug fixes, new loaders, accessibility improvements, documentation, tests, and focused design proposals.

By participating, you agree to follow the Code of Conduct. Contributions are accepted under the project's MIT License; see Licensing below.

Before you start

  • Search existing issues and pull requests before opening a duplicate.
  • Use a bug report for reproducible defects and a loader proposal for new visual concepts.
  • For a large core API, registry schema, generator, or site architecture change, open a proposal before investing in an implementation.
  • Security vulnerabilities must follow SECURITY.md, not the public issue tracker.
  • General usage questions belong in the support channel described in SUPPORT.md.

Small, well-scoped fixes do not need an issue first.

Project principles

Contributions should preserve the qualities that make loaders interchangeable:

  1. One public contract. Every loader uses the shared OrbUX state, sizing, speed, theming, accessibility, pause, and lifecycle behavior.
  2. Every state is intentional. idle, thinking, streaming, tool-calling, waiting, done, error, and cancelled must all produce a deliberate result.
  3. Reduced motion is a design state. It must remain useful and legible, not blank or stale.
  4. Motion communicates. Prefer changes that explain activity, progress, success, or failure over ornamental movement.
  5. Dependency-free loaders. Loader runtime code should use the platform and @vikast908/core unless a dependency is discussed and approved first.
  6. Original visual work. Inspiration is welcome; copied artwork, logos, characters, proprietary symbols, or misleading brand references are not.
  7. Generated code has one source of truth. Edit the catalog or shared generator, never an individual generated adapter.

Development setup

Requirements:

  • Node.js 20 or newer
  • pnpm 10.26.2, preferably through Corepack
  • Git
  • A Chromium-based browser for browser verification

Clone and install:

git clone https://github.com/vikast908/ORBUX.git
cd ORBUX
corepack enable
pnpm install --frozen-lockfile

Start the gallery at http://localhost:4321:

pnpm dev

If browser verification cannot locate Chrome automatically, set CHROME_PATH to the browser executable before running it.

Repository map

Path Responsibility
packages/core State model, base custom elements, lifecycle, motion, tokens, and accessibility
packages/loaders/src Handcrafted loaders and generated structural loader adapters
packages/loaders/src/recipe-catalog.json Canonical structural recipe matrix
packages/loaders/src/generated-loader.ts Shared structural-loader implementation
registry/schema.json Loader metadata contract
registry/registry.json Generated gallery and distribution registry
apps/site Astro gallery, loader detail pages, lab, and documentation
scripts Registry, browser bundles, catalog generation, scaffolding, and browser/UI checks
tests Core contract and loader catalog tests

Useful commands

Command Purpose
pnpm dev Regenerate the registry and run the gallery
pnpm new:loader <id> <tier> Scaffold a handcrafted loader
pnpm catalog:generate Reconcile the 200 generated structural loaders
pnpm registry Validate metadata and regenerate registry/registry.json
pnpm browser-bundles Build browser modules used by copy-paste examples
pnpm typecheck Type-check core, loaders, and site
pnpm test Build @vikast908/core + @vikast908/loaders, then run Node contract/catalog tests
pnpm test:browser Chromium lab contract (running server, or self-hosts apps/site/dist)
pnpm test:ui Build the static gallery, then audit gallery clicks and controls
pnpm lint Run Biome checks
pnpm format Format supported files with Biome
pnpm build Validate the registry and build the workspace

Choose the right loader path

OrbUX has two kinds of CSS/SVG contribution, and they should not be mixed.

Handcrafted loader

Choose this when the loader needs its own silhouette, markup, material, choreography, or state language. Signature effects, progress components, Canvas loaders, and WebGL loaders belong here.

Scaffold it with:

pnpm new:loader my-loader css-svg
# tiers: css-svg | canvas | webgl | lottie

The scaffolder creates:

packages/loaders/src/my-loader/
  my-loader.ts
  meta.json
  README.md

Then:

  1. Implement the visual using the generated tier-appropriate base class.
  2. Add both the import and named export to packages/loaders/src/index.ts.
  3. Confirm the package subpath export in packages/loaders/package.json (scaffolded by pnpm new:loader).
  4. Complete meta.json; remove every placeholder and list only tokens the loader reads.
  5. Document the loader's purpose, tier, theming, progress behavior, and reduced-motion composition.
  6. Run pnpm registry and include the regenerated registry in the pull request.

Structural recipe

Choose this only when a new form or motion topology adds a reusable dimension to the structural catalog. Do not create variants by changing only state, size, speed, or color.

Edit the canonical sources:

  • packages/loaders/src/recipe-catalog.json for forms and motion topology names
  • packages/loaders/src/generated-loader.ts for shared rendering behavior
  • scripts/generate-recipe-catalog.mjs only when generation mechanics must change

Then run:

pnpm catalog:generate
pnpm registry

Files containing the generated notice or the generated-recipe metadata tag must not be edited directly. The generator reconciles them and may overwrite or remove local edits.

Loader acceptance checklist

Public behavior

  • Uses a unique kebab-case ID and the matching orbux-<id> custom-element tag.
  • Extends OrbuxElement, Canvas2DElement, or ShaderElement as appropriate.
  • Handles all eight agent states without throwing, going blank, or retaining stale visuals.
  • Treats progress as 0..1 when supportsProgress is true and visibly represents it.
  • Honors the public size, speed, paused, and label behavior inherited from core.
  • Does not overwrite a consumer-provided role or aria-live value.
  • Survives disconnect/reconnect, resize, theme refresh, tab hiding, and offscreen pausing.

Motion and accessibility

  • Provides a meaningful static composition for prefers-reduced-motion: reduce.
  • Stops continuous or decorative motion when reduced motion is active.
  • Uses the shared duration scale for CSS animation durations and delays.
  • Uses frame-rate-independent time calculations for Canvas and WebGL movement.
  • Avoids flashing, high-frequency luminance changes, and movement that obscures state.
  • Keeps terminal done and error transitions brief and settles afterward.

Performance

  • Avoids layout reads, getComputedStyle, canvas creation, and color parsing per frame.
  • Avoids unbounded arrays, timers, event listeners, particles, trails, or GPU resources.
  • Cleans up observers and listeners through the base lifecycle.
  • Uses device-pixel-ratio-aware rendering for Canvas and WebGL tiers.
  • Adds no runtime dependency without prior maintainer agreement.

Metadata and distribution

  • meta.json validates against registry/schema.json.
  • id, folder, source filename, tag, registration, and package export all agree.
  • states, supportsProgress, placement, dependencies, files, and CSS variables are truthful.
  • Preview colors are six-digit hex values and remain readable in light and dark gallery modes.
  • Browser copy snippets resolve to a generated /orbux/<id>.js module.

Originality

  • The implementation and assets are original or have a compatible, documented license.
  • The loader does not reproduce a protected character, logo, insignia, or named franchise effect.
  • Any third-party asset includes its source, author, license, and required attribution in the PR.

Core, registry, and site changes

Core changes affect every loader. Add or update tests in tests/core and verify CSS, Canvas, and WebGL examples. Changes to the state model or public attributes require a compatibility discussion.

Registry and generator changes must fail loudly on invalid input and must not leave partially written generated output. Keep paths workspace-relative and reject traversal outside a loader folder.

Site changes should work in both color schemes, remain keyboard navigable, preserve visible focus, use associated labels, avoid unsolicited live-region announcements, and honor reduced motion.

Testing before a pull request

Run the focused checks while developing, then the complete local gate:

pnpm format
pnpm lint
pnpm typecheck
pnpm test
pnpm build

pnpm format changes files; inspect its diff before committing. If a browser test is unavailable in your environment, state that clearly in the pull request and describe the manual browser coverage.

Browser and gallery UI verification

pnpm test:browser checks the loader lab contract in Chromium. It uses http://127.0.0.1:4321 if something is already serving the gallery; otherwise it hosts apps/site/dist.

# terminal 1
pnpm dev

# terminal 2
pnpm test:browser

Set ORBUX_BASE_URL for a different host. Set CHROME_PATH if Chrome is not found automatically.

pnpm test:ui builds the static gallery and runs headless checks for theme, filters, state chips, copy/download feedback, detail controls, lab, and matrix. Use it when changing apps/site/src/scripts/app.ts, gallery CSS, or page scripts on catalog, lab, matrix, or docs.

pnpm test:ui
# after an existing site build:
node scripts/ui-ux-audit.mjs
node scripts/ui-click-verify.mjs

Headless Chrome often blocks the clipboard API. The audit still requires visible copy feedback text (✓ Copied or Copy failed), not an empty pill.

For visual or interaction changes, cover at least:

  • all eight states on cards, detail, lab, and matrix
  • home tier filter; catalog use-case + technology filters
  • Copy, Copy HTML, and Download HTML feedback
  • detail size, speed, color, and progress (double-click progress to clear)
  • light and dark themes
  • reduced motion
  • pause/resume and offscreen return
  • narrow and wide viewports
  • progress 0, 0.5, and 1 when the loader supports it

Commits and pull requests

  • Keep each pull request focused enough to review and revert independently.
  • Use imperative commit subjects, for example fix ripple static composition.
  • Explain the user-facing problem and why the chosen approach fits the shared contract.
  • Include before/after captures for visual changes when practical.
  • Call out generated files, new dependencies, breaking changes, and untested paths.
  • Do not commit build outputs, browser screenshots, environment files, or credentials.
  • Resolve review threads with code or a concise explanation; do not silently dismiss them.

Maintainers may ask to split broad pull requests or move a one-off variant into the structural catalog. Passing automation is necessary but does not guarantee acceptance.

Licensing

The repository is licensed under MIT. Unless explicitly stated otherwise, submitting a contribution means you have the right to provide it and agree that it will be licensed under the same MIT terms. OrbUX does not currently require a contributor license agreement.

Do not submit code, images, shader source, SVG paths, audio, fonts, or other material copied from a source whose license is unknown or incompatible. When attribution is required, include it in the relevant loader README and pull-request description.

Getting help

Read SUPPORT.md for the correct channel. If the contribution process itself is unclear, open a documentation issue with the exact section that blocked you.