🕰️ macOS-Style Flip Clock & Timer

A sleek, minimalist, web-based flip clock and countdown timer inspired by the clean aesthetics of macOS. Built entirely with vanilla JavaScript, CSS 3D transforms, and Tailwind CSS. No frameworks, and it works fully offline: just open and run!

🔴 View Live Demo Here

✨ Features

• Dual Modes: Seamlessly switch between a real-time Clock and a customizable Countdown Timer, with quick presets (5m/10m/15m/30m/1h/2h) and manual +5m/-5m/+1m/-1m adjustment while running.
• 3D Flip Animations: Hardware-accelerated CSS animations using transform-style: preserve-3d for a smooth, realistic mechanical flip effect.
• Intelligent Theming: Automatically detects your system's light/dark mode preference, with a manual toggle for quick overriding.
• Immersive View: A built-in fullscreen/large-view toggle for distraction-free focus.
• Quote Library: Cycles through curated, built-in quote sets — no network required. Pick a style: general Quotes, time-aware Motivational (tone shifts as the timer runs down), or Life Wisdom.
• Exam Mode: A dedicated proctoring-friendly mode with editable, persisted Pre-Start and Post-Exam rule lists, a duration summary on the instructions screen, and a link out to your institution's exam-conduct policy.
• Research-Backed Exam Options — a set of opt-in settings grounded in test-anxiety and accessibility research, each explained (with cited sources) on an in-app Research page (ℹ️ icon):
  • Calm Display: hides the exact numeric countdown during an exam and shows a softer, centered progress visual with a coarse phase caption instead of exact time.
  • Configurable Time Warnings: replace the fixed 5-min/1-min beeps with any set of checkpoints you choose (e.g. 30-min, 15-min marks for longer exams).
  • Accessible Text: switches the rules screens to a higher-contrast, wider-spaced, more legible layout.
  • Read Rules Aloud: reads the pre-start rules aloud via the browser's built-in text-to-speech, automatically preferring a natural-sounding voice and skipping bracketed citations.
• Stays Accurate & Awake: Timestamp-based countdown that resists tab throttling, a screen Wake Lock while running, and resume-after-reload so an accidental refresh won't lose the timer.
• Precision Control: Option to show or hide the seconds panel to reduce visual clutter.
• Audio & Visual Alerts: Progress bar that shifts amber then red, configurable warning beeps, and a Web Audio alarm when your timer finishes — all generated locally.

🚀 Getting Started

The app is plain HTML, CSS, and JavaScript with every asset (including the compiled Tailwind CSS and the Inter font) checked into the repo, so it needs no network connection and no install step to run.

1. Clone the repository:

   git clone https://github.com/drarahimi/clock-timer.git

2. Navigate to the directory:

   cd clock-timer

3. Run the app: Simply double-click the index.html file to open it in your default web browser. (Alternatively, use an extension like VS Code Live Server for a better development experience).

Development

You only need Node.js if you change Tailwind classes or want to run the tests.

npm install
npm run build:css        # regenerate css/tailwind.css after changing Tailwind classes
npm run watch:css        # or rebuild automatically while you edit
npx playwright install chromium   # first time only
npm test                 # run the browser test suite

Commit the regenerated css/tailwind.css along with your markup changes, since the site is served straight from the repo.

🛠️ Tech Stack & Architecture

• Structure: index.html (markup), css/app.css (custom styles and 3D flip animations), and js/app.js (app logic). No bundler and no runtime dependencies.
• Styling: Tailwind CSS, compiled ahead of time into css/tailwind.css from css/tailwind.src.css with the Tailwind CLI, so pages never depend on a CDN.
• Logic: Vanilla JavaScript handles the time calculations, DOM manipulation, interval management, timestamp-based countdown, Wake Lock, and Web Audio alerts.
• Tests: Playwright tests in tests/ cover offline loading, countdown accuracy, pause, warnings, resume-after-reload, rule persistence, and accessible names.
• Browser APIs used: Web Audio API (locally generated beeps/alarm, no sound files), Screen Wake Lock API, Web Speech API (speechSynthesis, for Read Rules Aloud), and localStorage to persist mode, rules, quote style, and exam-option preferences across sessions.
• Typography: The highly legible Inter font, self-hosted from fonts/, serves as the primary typeface, utilizing font-variant-numeric: tabular-nums to ensure the flipping digits remain perfectly aligned.

🎨 How the Flip Animation Works

The mechanical flip effect is achieved by splitting each digit into a top and bottom "plate". A third element, the "flap," is layered on top and anchored at the bottom (transform-origin: bottom). When the time changes, the flap rotates -180 degrees on the X-axis using @keyframes, revealing the new number underneath.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📜 License

Distributed under the MIT License. See LICENSE for more information.