FormaUI

FormaUI — a modern, professional hybrid CSS framework (utility-first core + headless & styled React components).
Implemented with TypeScript for the developer-facing packages and documentation, and Rust for the high-performance generator tooling (native CLI + WASM).

Project goals

• Production-quality, extensible design system and utility framework.
• Token-first architecture: canonical tokens -> CSS variables -> utilities & components.
• Fast build-time tooling: Rust generator (JIT + optimizer), optional WASM bindings for Node/browser.
• First-class React support: headless primitives + styled component wrappers.
• Professional DX: typed APIs, CI, tests, accessibility, changelogs, and automated releases.

Status

• Repository: https://github.com/Evotrix-Labs/FormaUI
• npm scope (public): @formaui (e.g. @formaui/components-react)
• Optional umbrella package (unscoped): formaui
• Rust crates (crates.io): formaui-generator, formaui-cli

Quick links

• License: MIT (see LICENSE)
• Contributing guide: CONTRIBUTING.md
• Security policy: SECURITY.md

Recommended CSS variable prefix

• --frm- (example: --frm-color-primary)

Repository layout (monorepo, pnpm workspaces)

• packages/
  • core-utils/ — TypeScript tokens, token generation, helper utilities
  • components-react/ — React components (headless primitives + styled variants)
  • cli-wrapper/ — TypeScript wrapper that shells to the native CLI / WASM
  • docs/ — docs site, MDX examples, playground
  • umbrella/ — optional umbrella meta-package (unscoped formaui)
• crates/
  • formaui-generator/ — Rust: JIT generator, optimizer, wasm-bindings
  • formaui-cli/ — Rust: CLI binary
• infra/
  • .github/workflows/ — CI and release workflows
• package.json (root), pnpm-workspace.yaml, tsconfig.json, etc.

Prerequisites (developer)

• Node.js (use Volta or nvm; Node >= 16 recommended)
• pnpm (workspace package manager)
• Rust toolchain (rustup, stable)
• wasm-pack (optional, for WASM builds)
• JetBrains IDEs recommended: WebStorm (TypeScript/React) + RustRover (Rust) — keep both open for the best DX

Getting started (local dev)

1. Install common tools (example using Volta):

   • Install Volta: https://volta.sh
   • Install pnpm: npm i -g pnpm (or via Volta)
   • Install Rust toolchain: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Bootstrap and install dependencies

   • pnpm install
   • pnpm -w run bootstrap # if you use a bootstrap script (see root package.json)

3. Run the docs site / playground (example)

   • pnpm -w --filter @formaui/docs dev

4. Build all packages

   • pnpm -r run build

5. Run tests

   • pnpm -r run test
   • Cargo tests for Rust crates:
     • cd crates/formaui-generator && cargo test
     • cd crates/formaui-cli && cargo test

Development notes

• TypeScript: follow strict mode and ESM-first exports. Build with tsc / tsup as configured in package scripts.
• Rust: use cargo fmt and cargo clippy. Use wasm-pack to build wasm artefacts for publishing to npm (packaged under @formaui/generator-wasm).
• Formatters & linters:
  • JS/TS: Prettier + ESLint
  • Rust: rustfmt + clippy

CI & Releases

• CI: GitHub Actions runs lint, build, and tests for both Node and Rust on every PR.
• Release: on tag (vX.Y.Z), Actions will:
  • Build & publish scoped npm packages (@formaui/*) with --access public.
  • Optionally publish the unscoped formaui umbrella package (if PUBLISH_UNSCOPED secret is set).
  • Publish Rust crates to crates.io and create GitHub Releases (attach binaries if produced).
• Multi-package versioning: We recommend using Changesets to manage changelogs and coordinated publishing.

Contributing

• See CONTRIBUTING for how to open issues and PRs, commit message conventions (Conventional Commits), tests, and code review expectations.
• All public API changes should include documentation updates and migration notes.

Security

• If you discover a security vulnerability, follow SECURITY (preferred: use GitHub Security Advisories or contact the security contact listed in SECURITY).

Code of Conduct

• All contributors must follow the Code of Conduct (see CODE_OF_CONDUCT). Be respectful and collaborative.

Contact

• Project maintainers: Evotrix Labs team
• For security disclosures: see SECURITY

Thank you for contributing to FormaUI — a modern, professional, extensible design system.