Important
Temporary Contribution Guidelines & Freeze Notice
Due to the high volume of contributions and multiple merge conflicts affecting framework stability, PRs modifying core files, workflows, configs, or shared framework code are temporarily restricted.
For now, only self-contained submissions inside submissions/examples/* will be reviewed and merged.
This is being done to stabilize the repository, reduce breaking changes, and ensure contributor work is preserved without conflicts or accidental overwrites.
Core contribution access may reopen once the framework structure and validation systems are fully stabilized.
Thank you for your interest in improving EaseMotion CSS.
Tip
Join our Discord Community!
We have an official Discord server for EaseMotion CSS. Join us to chat with other contributors, seek help with your submissions, discuss design choices, and receive announcements: Join the EaseMotion CSS Discord
Before writing any code, read this document in full. The contribution model is intentionally different from most open-source projects.
EaseMotion CSS is designed and curated by Saptarshi Sadhu. All contributions are reviewed, standardized, and approved by the maintainer before becoming part of the framework.
EaseMotion CSS is curated. Contributors do not directly modify the framework source. Instead:
Contributor Maintainer
───────────────────────────────── ─────────────────────────────────────
Submits a raw HTML + CSS demo Reviews the submission
inside submissions/examples/ Decides if it fits EaseMotion CSS
Standardizes class naming to ease-*
Optimizes the CSS
Integrates into core/ or components/
Merges the PR
This model exists to maintain quality, naming consistency, and design coherence across the framework.
One place only:
submissions/examples/your-feature-name/
That is the only directory you should add or modify in your PR.
To maintain repository stability, review quality, and fair contribution distribution, EaseMotion CSS enforces a soft daily rate limit:
- Contributors may submit up to 30 PRs per day
- Focus on quality, originality, accessibility, and proper testing
- Low-effort, repetitive, or mass-generated PRs may be closed without review
EaseMotion CSS has grown rapidly with hundreds of contributors and thousands of merged PRs. This update helps:
- Reduce merge conflicts
- Improve review quality
- Maintain framework consistency
- Encourage meaningful contributions over quantity
To keep the repository's git history clean and readable, contributors must follow these rules:
- Squash your commits: Ensure all commits in your Pull Request are squashed into a single meaningful commit (or a few logical commits) before submitting for review. Do not push dozens of micro-commits (e.g., "fix", "typo", "update style.css", etc.) for a single change.
- Keep history clean: PRs containing noisy, repetitive, or excessive commit histories (e.g., dozens of micro-commits) may be closed without review or blocked from merging.
- Write clear commit messages: Use descriptive commit messages following the Conventional Commits format (e.g.,
feat: add card componentorfix: resolve hover animation issue).
All contributions are welcome and eligible for merge when submitted inside the submissions/examples/ folder following the repository structure and guidelines.
To avoid naming conflicts and overlapping components, contributors must append a short unique identifier or abbreviation to their feature/component name.
Example:
ease-hover-sapease-tabs-akease-card-pr
This ensures:
- Unambiguous component naming,
- Preservation of every contributor’s work,
- Conflict-free merges,
- Easier maintenance and review workflow,
- Support for parallel implementations of similar ideas.
The project encourages creative variations and parallel implementations rather than overwriting existing contributor work.
Your submission folder must contain exactly three files:
A self-contained HTML demo. Must work by opening directly in a browser with no server. No CDN links, no external frameworks.
Your raw CSS. Write it however you like — no need to follow the ease- naming convention. The maintainer handles all renaming and standardization.
Answer these three questions:
- What does this do? — one sentence.
- How is it used? — show the HTML class usage.
- Why is it useful? — explain how it fits EaseMotion CSS's philosophy.
| Who | Rule |
|---|---|
| Contributors | Use any class name that makes sense to you |
| Maintainer | Renames everything to follow ease-kebab-case convention |
You do not need to worry about the ease- prefix. Do not try to pre-standardize — just write clear, readable CSS.
These rules are enforced at PR review. Violations result in immediate close without feedback.
- Edit any file in core/
- Edit any file in components/
- Modify docs/
- Modify examples/
- Merge your own pull request
- Add your feature inside submissions/examples/your-feature-name/
- Include all three required files (demo.html, style.css, README.md)
- Keep one PR focused on one feature
- Fill out the PR template checklist completely
For any non-trivial feature, open a GitHub issue before coding. Use the Feature Request template. This lets you confirm the idea fits EaseMotion CSS before investing time in the code.
Small fixes (documentation typos, broken demo links) can go directly to a PR.
Maximum 2 active assigned issues per contributor at any time.
This rule exists to keep assignments fair and ensure active contributors can always pick up work.
✅ You have 0–1 active assignments → request a new issue freely
✅ You have 2 active assignments → finish or unassign one first
❌ You have 2+ active assignments → new assignment requests will be declined
If an assigned issue has no progress for 24 hours (1 day), the maintainer will unassign it and open it for others.
This rule is enforced by the maintainer. It is not personal — it keeps the project healthy for everyone.
- Fork this repository
- Create a branch:
git checkout -b feature/your-feature-name - Add your files inside
submissions/examples/your-feature-name/ - Push your branch and open a PR against
main - Fill out the PR template — every checkbox must be addressed
- Wait for maintainer review. Do not ping or bump. Reviews happen on a rolling basis.
- The maintainer will either:
- Request changes — update your submission accordingly
- Accept — the maintainer integrates the code and merges the PR
- Close — the idea doesn't fit; the issue will explain why
Reminder: Only Saptarshi Sadhu merges pull requests.
Do not self-merge, even if you have repository write access.
EaseMotion CSS follows a strict submission-first pipeline. No PR should ever modify core/ or components/ directly.
PR submitted
↓
submissions/examples/ (contributor writes raw CSS here)
↓
Maintainer tests it
↓
Maintainer standardizes to ease-* naming
↓
Maintainer promotes to core/ or components/
↓
PR merged
This ensures:
- Every class is framework-quality before it ships
- Naming stays consistent across the entire API
- No regressions from unreviewed direct edits
PRs that touch core/ or components/ will be closed immediately, regardless of quality.
The maintainer uses the following labels to communicate submission status:
| Label | Meaning |
|---|---|
curated |
Submission accepted into the framework |
maintainer-approved |
Reviewed and approved, pending integration |
featured |
Exceptional submission — will be showcased in docs |
good first issue |
Great starting point for new contributors |
animation |
Hover effects, entrance animations, keyframes |
component |
New UI components |
enhancement |
Improvements to existing classes |
documentation |
README, docs, submission guide updates |
Open a GitHub issue with:
- The class name(s) involved
- Expected vs. actual behavior
- Browser name and version
- Operating system
- A minimal HTML snippet that reproduces the bug
Feedback is technical and direct. Be respectful of other contributors and the maintainer's time. Submissions of all skill levels are welcome.
Saptarshi Sadhu
GitHub: @SAPTARSHI-coder