Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mr-sunset/zen/llms.txt

Use this file to discover all available pages before exploring further.

Contributions to Zen — whether a bug report, a feature idea, or a code change — are welcome via GitHub. The project is intentionally small and calm, and the contribution process reflects that: no CLAs, no CI pipelines to navigate, and no toolchain to install.

​
Reporting a bug

If something isn’t working as expected, opening a GitHub issue is the fastest way to get it looked at.
  1. Go to https://github.com/mr-sunset/zen/issues and click New issue.
  2. Describe what happened and what you expected to happen as clearly as possible.
  3. Include your browser name and version (e.g. Chrome 124, Safari 17) and your operating system.
  4. Note whether the issue occurs in light mode, dark mode, or both — some visual bugs are mode-specific.
  5. If the problem involves audio, mention whether your browser prompted for autoplay permission and how you responded.
The more detail you provide upfront, the easier it is to reproduce the issue. A short screen recording or screenshot is always appreciated but never required.

​
Suggesting a feature

New ideas are welcome — open an issue at https://github.com/mr-sunset/zen/issues with a clear description of what you have in mind and why it would improve the experience. Before submitting, consider Zen’s core ethos: minimal, calm, and dependency-free. The project deliberately avoids frameworks, build tools, and third-party libraries. Proposals that add complexity, introduce npm dependencies, or significantly expand the scope may not align with the project’s goals and could be declined — but the conversation is still worthwhile.
The best feature suggestions are small, self-contained, and serve the calming purpose of the project. If your idea can be implemented in a few lines of vanilla HTML, CSS, or JS, it is a strong candidate.

​
Opening a pull request

Code contributions are made through the standard GitHub fork-and-PR flow. Test your changes locally with a simple HTTP server before opening the PR.
1

Fork the repository

Click Fork on https://github.com/mr-sunset/zen to create a personal copy under your GitHub account.
2

Clone your fork

git clone https://github.com/<your-username>/zen.git
cd zen
3

Make your changes and test locally

Edit the files you need, then start a local server to verify the result:
# Python 3
python3 -m http.server 8080

# Node.js
npx serve .
Open http://localhost:8080 and confirm everything looks and sounds correct in both light and dark mode.
4

Commit with a clear message

git add .
git commit -m "Brief description of what changed and why"
git push origin main
Keep the commit message concise and in the imperative mood (e.g. “Fix audio not looping on iOS Safari” rather than “Fixed the audio bug”).
5

Open a pull request against main

Go to your fork on GitHub and click Compare & pull request. Set the base repository to mr-sunset/zen and the base branch to main. Describe your change and link to any related issue.
There is no automated test suite — review is done by reading the diff and testing in a browser. Make sure your changes work without a build step; if a reviewer cannot drop the files into a local server and see them working, the PR will need revision.

​
Code style

Zen is written in plain, uncompiled, framework-free code. When contributing, please follow the same conventions already in use:
  • JavaScript — vanilla ES6+, no frameworks, no bundlers, no import statements that require a module system. Keep logic in script.js.
  • CSS — all rules live in style.css. Class and ID names mirror the element IDs already defined in index.html; introduce new names only when necessary and keep them descriptive.
  • HTML — semantic elements where possible; avoid adding unnecessary wrapper <div> layers.
  • Dependencies — the project has zero runtime dependencies and intends to keep it that way. Do not add a package.json or reference any CDN-hosted library in index.html.
When in doubt, optimise for readability over cleverness. Someone should be able to read any file in this project and understand what it does without tooling, documentation, or prior framework knowledge.

Build docs developers (and LLMs) love

Get started for freeTalk to us