An accessible, browser-only 3×3 Rubik's Cube trainer with a modern 3D interface, manual cube-state entry, physical-state validation, animated moves, and an in-browser solver.
- Interactive 3D cube built with Three.js
- Mouse and touch layer turns
- Color-paint mode for copying a physical cube
- Accessible 2D cube map for keyboard and screen-reader users
- Keyboard shortcuts for all six face turns
- Physical cube validation: color counts, piece combinations, orientation, and parity
- Browser-side solver using cube.js
- Previous, next, play, pause, restart, and animation-speed controls
- Beginner layer-by-layer lesson cards
- High-contrast and reduced-motion modes
- Installable PWA shell and runtime caching
- GitHub Pages deployment workflow
- No backend, database, npm install, or build step
The app uses JavaScript modules, a web worker, and a service worker, so serve it over HTTP rather than opening index.html through file://.
- Create a new GitHub repository.
- Upload every file and folder from this project.
- Push or upload to the
mainbranch. - Open Settings → Pages.
- Under Build and deployment, select GitHub Actions.
- The included workflow publishes the site automatically.
The final URL will normally follow this format:
https://YOUR-USERNAME.github.io/YOUR-REPOSITORY/
Any simple static server works. Examples:
python -m http.server 8080or use the Live Server extension in VS Code. Then open:
http://localhost:8080
The app itself ships with no build step, but the pure cube-state logic in
src/cube-logic.js (validation, parity, scramble generation, move helpers) has a
Node test suite. It runs in CI on every push and can be run locally:
npm install # dev-only: installs the cube.js engine and the test runner
npm test # node --test| Key | Action |
|---|---|
U, R, F, D, L, B |
Turn that face clockwise |
Shift + face key |
Turn that face counterclockwise |
Space |
Play the next guided move while the Guided solve tab is open |
Ctrl/Cmd + Z |
Undo the latest manual change |
Tab, Enter, arrow keys |
Navigate controls and edit through the 2D cube map |
CubeFlow assumes this fixed color scheme while copying a cube:
- Up: white
- Right: red
- Front: green
- Down: yellow
- Left: orange
- Back: blue
Hold the physical cube with white on top, green facing you, and red on the right while entering colors.
cubeflow/
├── index.html
├── styles.css
├── manifest.webmanifest
├── sw.js
├── package.json # dev tooling only (test runner); the app needs no build
├── src/
│ ├── app.js # UI, state, and event wiring
│ ├── cube-logic.js # pure cube-state logic (no DOM/Three), shared with tests
│ ├── cube-renderer.js # Three.js 3D rendering
│ └── solver-worker.js
├── test/
│ └── cube-logic.test.mjs
├── assets/
│ └── icon.svg
└── .github/workflows/pages.yml
The first online visit loads these open-source libraries from jsDelivr:
- Three.js 0.184.0 for 3D rendering
- cube.js 1.3.2 for cube modeling and solving
The service worker caches fetched resources for later visits. For a repository with zero external runtime dependencies, download those library files into assets/vendor/ and replace the CDN paths in index.html and src/solver-worker.js.
- The guided solver provides an efficient move sequence for the entered state.
- The Learn tab teaches the beginner layer-by-layer path separately.
- Camera-based color scanning is not included in this version; manual color entry is more reliable for the first release.
- GitHub Pages must be served over HTTPS for installation and service-worker features.
- Native buttons, tabs, dialog, form controls, and progress semantics
- Visible focus indicators
- No mouse-only required action
- Parallel 2D editor for the canvas content
- Screen-reader status announcements
- High-contrast mode
- Reduced-motion mode and system preference support
- Responsive layout and touch-sized controls
MIT