2048 Game
🎮 Responsive 2048 browser game built with vanilla JavaScript, modular CSS, and Webpack.
▶ Play the demo
The classic 2048 puzzle as a compact static web game, written without a UI framework. The code is split into small object-oriented layers: a model with the rules, views, input, storage and controllers. It keeps production habits from larger projects: a Webpack build, size budgets, CI, linting hooks, and accessibility.
✨ Features
- Three board sizes (3×3, 4×4, 5×5), each with its own high score and a reset for it
- A win target for each board size (on 4×4: 1024, 2048 or 4096), saved with the game
- Animated moves: tiles slide, merge and pop in; a
+N score pop and a New record! badge
- Light and dark themes that follow the system until you choose, with a circular reveal and no flash on load
- The game in progress is saved and restored after a reload
- All-time statistics (games played, wins, best score, best tile) with a reset
- Win and game-over dialogs with a game summary, and a confirmation before progress or records are lost
- A layout that fits any screen, a phone in landscape included, clear of notches
- Accessible: screen reader names and announcements, focus rings, 44px targets, reduced motion
🎮 Controls
| Action | Keyboard | Touch |
|---|
| Move the tiles | Arrow keys or WASD | Swipe anywhere on the page |
| New game, switch theme, open settings | Tab to a toolbar button, then Enter or Space | Tap a toolbar button |
| Close settings, cancel, continue after a win | Escape | Tap Close, Cancel or Continue playing |
🧰 Tech Stack
- HTML
- CSS
- JavaScript
- Webpack 5
- Lightning CSS
- Terser
- ESLint
- Prettier
- Husky
- lint-staged
- size-limit
- GitHub Actions
- Vercel
- Yarn
📁 Project Structure
src/
index.html Page markup, metadata and the four dialogs
favicon.svg SVG favicon
fonts/ Self-hosted Rubik (Latin woff2)
scripts/
main.js Composition root: finds the DOM, creates and wires the objects
constants.js Board sizes, win tiles, timings, storage keys, settings table
themeHead.js Plain script inlined into <head>: sets the theme before the first paint
game/ Model: Board, Game, Settings, Statistics (rules and values, no DOM)
ui/ Views: grid, score, dialogs, settings, theme switch, footer
input/ Keyboard and swipe input
storage/ Safe localStorage wrapper
controllers/ Use cases and flow state: game, high score, saved game, settings, statistics, theme
styles/
main.css CSS entry, imports the rest
theme.css Scales and every UI colour for both themes, the theme reveal
base.css Font face, reset, page base, focus ring
layout.css Page layout, the short landscape layout, footer
header.css Header: logo, score boxes, score pop, record badge
board.css Board, cells, tiles and their animation classes
tiles.css Tile palette, one rule per tile value
overlays.css Dialogs: win, game over, confirmation, settings
controls.css Buttons, segmented control, toolbar, icon buttons
animations.css Every @keyframes
motion.css Reduced-motion overrides
public/ Files with an unhashed URL, copied as they are: link preview image, robots.txt, llms.txt
webpack/ Webpack config in parts: paths, browser targets, loaders, plugins
assets/ The gameplay GIF shown above
ai/ Agent docs: repo map, rules, decisions, skills, prompts, plans
🚀 Scripts
Install dependencies, which also installs the pre-commit hook (needs Node.js 20.19+, 22.13+ or 24+, and Yarn 1):
yarn install
Run the development server at http://localhost:8080:
yarn dev
Build the production version into dist/:
yarn build
Preview the production build locally (run yarn build first):
yarn preview
Lint the code (yarn lint:fix also fixes what it can):
yarn lint
Format the code with Prettier (yarn format:check only checks):
yarn format
Check the bundle sizes against their budgets (run yarn build first):
yarn size
🔄 CI
Every push runs lint, the format check, the build and the size budgets from .size-limit.json on GitHub Actions.
The pre-commit hook runs ESLint and Prettier on the staged files through Husky and lint-staged.
main is deployed to Vercel, and other branches get preview deployments.
🧱 Architecture Notes
- Object-oriented layers (model, views, input, storage, controllers) are created and wired in
main.js (rules)
- Tiles are elements over a background grid, animated from the move result the model reports (decision)
- Modals are native
<dialog> elements, with one shared confirmation that answers a Promise (decision)
- Colours are tokens, and the theme is
data-theme, set by a head script before the first paint (decision)
- No UI framework and no automated tests, by design (decisions)
🤖 AI Workflow
The game is built and maintained by AI agents (Claude Code) under the author's review. Everything they need lives in the repo, written for any agent rather than one tool:
| Part | What it gives an agent |
|---|
AGENTS.md | The entry point: project defaults and the rules that never bend |
ai/map.md | Where every file, class and storage key lives |
ai/rules/ | How to write the code and the docs, and the Definition of Done |
ai/decisions/ | Why things are the way they are, so nothing settled gets "fixed" back |
ai/skills/ | Playbooks: adding a feature, self-review, remaking the link preview |
ai/prompts/ | Session prompts: one task, or an orchestrator running several in parallel |
ai/superpowers/ | The plan (and spec) of every past task |
Every change follows one workflow: a Linear issue → a plan → the code on its own branch → checks and a run in the browser → self-review → the author's approval → a local merge into main.
