Skip to content

Latest commit

 

History

History
120 lines (81 loc) · 3.72 KB

CONTRIBUTING.md

File metadata and controls

120 lines (81 loc) · 3.72 KB

Contributing to VeloraCSS

VeloraCSS is a fully original utility-first CSS framework. Every class, variable, and token is branded vel- / --vel-. There are zero references to Tailwind, Bootstrap, or Bulma in any output — they are research only.

Project Overview

  • Utility classes: vel-{property}-{value} — e.g. vel-flex, vel-p-4, vel-text-lg
  • Component classes: vel-{component} — e.g. vel-btn, vel-card
  • CSS custom properties: --vel-{category}-{name} — e.g. --vel-color-primary, --vel-space-4

The built output lives in dist/velora.css. The source lives in src/. Never ship class names or variable names from other frameworks.

Project Structure

src/
  tokens.css          CSS custom properties (--vel-*)
  reset.css           Modern CSS reset
  utilities/          One file per utility category
  components/         One file per component
  velora.css          @import entry point
dist/                 Built output (git-ignored, regenerated by npm run build)
playground/           Live demo app (Vite + React + Monaco Editor)
nextjs-demo/          Docs site (Next.js static export)
docs/                 Committed static output for GitHub Pages
build.mjs             PostCSS build script

Local Setup

git clone https://github.com/VeloraX/veloracss.git
cd veloracss
npm install
npm run build

npm run build runs the PostCSS pipeline and writes dist/velora.css and dist/velora.min.css.

Running the Playground

npm run playground

Opens the Vite + React + Monaco Editor playground at http://localhost:5173. It builds the framework first, then starts Vite. The preview iframe injects dist/velora.css as inline styles.

Running the Docs Site

npm run demo

Builds the framework, then starts the Next.js dev server for the docs site at http://localhost:3000.

CSS Authoring Rules

  • All utility classes must use the vel- prefix. No exceptions.
  • All CSS custom properties must use the --vel- prefix.
  • No class names, variable names, or comments may reference Tailwind, Bootstrap, or Bulma.
  • Tokens live in src/tokens.css. Do not hard-code values in utility or component files — reference --vel-* properties.
  • Every change to src/ requires a rebuild (npm run build) before testing.

Adding a New Utility

  1. Identify the category file under src/utilities/ (e.g. spacing.css, typography.css).
  2. Add your classes following the vel-{property}-{value} pattern.
  3. Reference existing --vel-* tokens rather than hard-coded values where possible.
  4. Run npm run build.
  5. Verify the output in dist/velora.css.

Adding a New Component

  1. Create src/components/{component-name}.css.
  2. Import it in src/velora.css using @import.
  3. Name the base class vel-{component} and modifiers vel-{component}-{modifier}.
  4. Run npm run build.
  5. Add a docs page at nextjs-demo/app/docs/{component-name}/page.tsx.
  6. Register the page in nextjs-demo/app/docs/_data/nav.ts.

Pull Request Guidelines

  • Keep changes scoped to a single feature, fix, or utility category.
  • Run npm run build and confirm it passes before opening a PR.
  • No Tailwind, Bootstrap, or Bulma class names may appear anywhere in dist/velora.css.
  • All new classes must use vel- prefix. All new CSS vars must use --vel- prefix.
  • If you add a docs page, update nav.ts. If you skip this, the page will be unreachable.
  • Describe what your PR changes and why in the PR description.

Reporting Issues

Open an issue at https://github.com/VeloraX/veloracss/issues

Please include browser, OS, VeloraCSS version, and a minimal reproduction when reporting bugs.

Community

Join the Discord: https://discord.gg/RKmSyudqAv