An interactive CSS learning tool that teaches layout by building it — drag components, apply real CSS properties, and watch live style changes. No code editor required.
This is a documentation-only showcase repository. It describes a real, working application — its architecture, features, and engineering decisions — without including the application's source code. The source lives in a separate private repository.
 |
 |
 |
 |
Full-page captures of the dark theme. See screenshots/README.md for details.
CSS Direct is a local-first, offline-capable web application for learning CSS by doing. Instead of reading property definitions or watching videos, learners work in a real sandbox: drag one of 20 realistic UI components (button, navbar, modal, pricing card…) onto a canvas, drag a CSS property onto it, pick a value, and see the computed result applied live.
The product targets three distinct modes, each built on the same engine:
- Sandbox — free-form exploration. No lesson, no goal; just build and experiment. Composers can resize, reorder layers, compare before/after states, preview at multiple breakpoints, and export the final CSS.
- Guided lessons — a step engine validates the learner's actual canvas against the current step using a composable check engine (11 check types with logical combinators), gives targeted hints on miss, applies teacher-style commentary on hit, and auto-advances.
- Challenges — procedurally generated exercises from 6 templates, with difficulty scaling and a grade breakdown.
Everything runs in the browser: there is no backend server. State persists to versioned localStorage, and learners can optionally sync progress to a GitHub Gist they own via a pluggable sync adapter. This makes the app private by default, usable offline, and free to host anywhere.
- Interactive CSS validation — lessons don't compare strings; they run a predicate-style check engine against the live scene (element selected, property applied, computed style matched, layout matched, element counts…), composed with
and/or/not. - A real design tool, not a demo — the canvas is a miniature editor: scene tree, layers, selection, resize handles with alignment guides, undo/redo with style snapshots, responsive previews, and CSS/JSON export.
- Local-first persistence with a migration chain — versioned storage keys, an in-place migration runner, and a persistence boundary designed so the storage backend can be swapped for something like PostgreSQL (JSONB) without touching domain logic.
- Zero-backend sync — a small adapter pattern that lets users back up progress to their own GitHub Gist using a personal access token. No accounts, no servers, no data held by the product.
- Procedural content — the challenge generator produces never-identical exercises from parametrized templates instead of a fixed hand-written bank.
- Sandbox with drag-and-drop component placement and property application
- Real CSS engine — 23+ visual properties with value pickers, computed-style inspection, and a color picker
- 16 guided lessons built on a composable validation engine with progressive hints
- Procedural challenge generator — 6 templates, difficulty tiers, grade scoring
- Undo / redo with style snapshots and history
- Comparison view — before/after side-by-side; responsive breakpoint previews
- Export to CSS, JSON, or a rendered image
- Command palette (⌘K) — search lessons, components, properties, and actions
- Gamification — XP, levels, daily streaks with freezes, and badges
- "Show me" demos — scripted, guided walkthroughs with a ghost cursor and narration
- Local-first persistence with schema migrations; optional GitHub Gist sync
- Keyboard-first and accessible — full keyboard operation, focus-region cycling, live announcements, reduced-motion support
User (Browser)
↓
React 19 SPA (Vite)
├── UI layer — pages, components, theme tokens
├── Feature modules — CSS engine · canvas · lessons · drag & drop · gamification · generator
├── State & persistence — Zustand slices · versioned localStorage · migration chain
└── Optional sync — GitHub Gist / local file adapter
The browser is the only runtime. All lesson logic, style computation, scene editing, and user progress live client-side; static JSON content is bundled at build time. See architecture/architecture.md and architecture/architecture.png.
- Frontend — React 19, Vite 8, React Router 7
- Styling & design system — Tailwind CSS v4, CSS custom-property token system (dark/light)
- State — Zustand (store slices for UI, scene, lessons)
- Interactions — @dnd-kit (drag & drop), lucide-react (icons), html-to-image (export)
- Persistence — versioned
localStoragewith migration chain - Sync — optional GitHub Gist adapter (personal access token)
- Testing — Vitest (unit/integration), Playwright (end-to-end), axe-core (accessibility)
- Tooling — ESLint, Vite build tooling
- A predicate-style lesson validation engine (11 check types + logical combinators) that evaluates real canvas state instead of comparing outputs.
- Portable persistence layer: a single module owns all storage I/O; domain modules stay storage-agnostic, and the schema maps cleanly to a relational/JSONB backend.
- Extensibility-by-adapter sync: pluggable storage adapters (local file, GitHub Gist) behind one interface.
- Procedural, difficulty-scaling challenge generation from parameterized templates.
- Accessibility-parity interaction model: keyboard drag, focus-region cycling, live announcements — the product is fully operable without a pointer.
The notable decisions — including why each was made and the trade-offs accepted — are documented in docs/engineering-decisions.md. A concise system-level walkthrough is in docs/technical-overview.md, and docs/project-structure.md describes the conceptual module layout.
CSS Direct is a complete, tested, functional application (this showcase tracks a mature revision). Current verified scope:
- ~20 UI component types across mainstream patterns (navigation, surfaces, forms, media, feedback, patterns)
- 23+ visual CSS properties with typed value pickers
- 16 guided lessons with prerequisite-based unlocks
- 6 procedural challenge templates
- 30-term built-in CSS glossary
- 74 test files / 1,003 unit & integration tests passing (Vitest), complementary Playwright E2E and axe accessibility suites
- Dark/light theming, offline operation, and optional Gist-based progress sync
No production traffic, user, or revenue figures are reported here — the project has not been presented with fabricated business metrics.
Because this showcase intentionally excludes the application's source code, there are no install-and-run instructions here. If a public demo is made available later, it will be linked from demo/README.md. The application itself runs fully in-browser with no server or database setup.
The application source code is intentionally NOT included in this repository. This is a documentation/demo-only representation created for portfolio purposes. If you are evaluating the project and would like access to the private source repository, please contact the author directly.