Parametric geometry
Change any dimension and the entire toolbox model recalculates instantly from one authoritative TypeScript domain engine.
Open Source · TypeScript · Woodworking
Japanese Toolbox Designer is a browser-based tool for designing the traditional Japanese toolbox with inset end walls, integral grab handles and the characteristic sliding lid secured by a captured tapered wedge.
The application calculates the interacting relationships between overall box dimensions, inset end walls, housing dados, end caps, asymmetric lid overlaps, release travel, locking batten and the captured tapered wedge.
The woodworking problem
The carcass of a Japanese toolbox is relatively straightforward joinery: long side boards, housed end walls, grab handles and a fastened bottom. But the traditional sliding lid mechanism contains a web of tightly interacting physical dimensions that are frustratingly awkward to calculate by hand.
When closed, the lid panel slides under fixed wooden end caps at both ends. To remove the lid, the tapered locking wedge is pulled out, allowing the lid to slide backwards into the locking-end pocket until the opposite end clears its end cap and can be lifted clear.
The application enforces the exact kinematic conditions required for this mechanism:
Joinery and anatomy
The application models a traditional joinery arrangement designed for strength, functional handling and long-term timber stability.
End walls are set in from the carcass ends and seated in 3 mm shallow housing dados cut into the side boards, resisting racking forces without exposed fasteners.
The side-board extensions create natural handle bays, spanned by thick solid grab handles that provide comfortable single-handed or two-handed carrying.
A full-footprint bottom board with configurable thickness, allowing heavier stock for the base without unnecessarily increasing carcass wall weight.
Fixed end caps, a straight stop batten, and a complementary tapered locking batten that traps the wedge against the side wall under tension.
Complete workshop workflow
Designed as a practical CAD tool for real workshop projects, from initial parameter sizing to technical drawings and printing a cutting schedule.
Change any dimension and the entire toolbox model recalculates instantly from one authoritative TypeScript domain engine.
Exact millimetre precision internally with seamless display formatting between whole millimetres and 1/16-inch woodworking fractions.
Interactive Front, Plan and End SVG vector drawings with architectural dimension lines, annotation callouts, zooming and panning.
WebGL Three.js model showing 13 individual physical parts, compound dados, wood species materials and standard camera presets.
Manage named designs locally in the browser with New, Save, Open, Rename, Duplicate and Delete workflows.
Portable single-file JSON import and export for offline sharing, with automatic Schema V1 and V2 in-memory migration.
9 bundled wood species (Hinoki, Japanese Cedar, Pine, Douglas Fir, Paulownia, Ash, Oak, Beech, Custom) with zero external asset requests.
Calculated stock blank bill of materials (8 line items, 12 blanks, 13 finished parts, 1 combined locking set blank).
Deterministic joinery sequence covering stock preparation, carcass dados, handle shaping, lid fitting and compound wedge manufacture.
Structured multi-page A4 PDF generated entirely in the browser using pdf-lib, containing project specifications, vector technical drawings, a complete cut list table and paginated process instructions.
Architecture
The fundamental architectural rule of the application is strict single-source geometry:
There is exactly one authoritative implementation of the toolbox geometry.
React form controls do not calculate joinery dimensions. SVG viewers do not compute cut lines. The Three.js 3D viewer does not derive part sizes. The cut list and PDF exporter do not independently reproduce formulas.
Every view, renderer and export pipeline is a pure projection of the canonical CalculatedToolboxGeometry data structure. This design rule made rapid iterative refactoring safe throughout development.
Technology stack
Built with a modern TypeScript and React 19 toolchain, relying on browser standards rather than server infrastructure.
Strict type checking, modern component state and deterministic property flow.
Hardware-accelerated 3D rendering with lazy chunk loading (~935 kB deferred).
Vector technical drawings and client-side multi-page A4 document composition.
Comprehensive unit, component and cross-browser testing across Chromium, Firefox and WebKit.
Engineering method
Japanese Toolbox Designer was not built by asking an AI model to write an entire application at once. It was created through a disciplined three-way engineering collaboration where each participant had distinct, complementary responsibilities.
Product & Engineering Direction
Reasoning & Specifications
Implementation & Verification
Disciplined delivery
The project was deliberately developed through a sequence of small, reviewable, testable phases rather than an unconstrained single prompt.
AI accelerated code generation and refactoring dramatically, but the quality of the finished software relied entirely on maintaining tight feedback loops and rigorous engineering standards.
Real-world learning
Genuine engineering is demonstrated when initial assumptions are challenged and corrected through evidence during development.
An early prototype placed the end walls flush at the carcass ends. Physical evaluation showed this lacked traditional racking resistance and lost the integral grab handles.
The domain model was revised to support inset end walls, 3 mm housing dados, handle recesses, solid grab handles and independent bottom thickness. All views, 3D meshes and migrations were updated seamlessly.
The first implementation assumed symmetrical lid overlaps at both ends. Practical dimension testing revealed that symmetric overlaps forced end caps to be unnecessarily wide.
The geometry engine was generalised to support independent asymmetric overlaps (6 mm stop end, 20 mm locking end), with automatic migration preserving existing user designs.
Subtle layout issues — such as clipped dimension text in generated PDFs, overlapping Plan annotations, and sub-optimal wide-monitor space usage — were discovered through direct human inspection.
Each issue was isolated and resolved in dedicated follow-up phases backed by visual regression tests.
Quality assurance
Automated testing was written alongside feature code rather than added as an afterthought.
Critical woodworking relationships are tested against hand-calculated mathematical fixtures rather than simply duplicating production formulas.
296
Vitest unit & component tests
36
Playwright E2E browser tests
332
Total test definitions
Simplicity & Privacy
The entire application runs client-side inside the user's browser without requiring a server or database.
No login required, no tracking cookies, and zero user data transmitted across the network.
Designs persist in browser local storage and export as portable single-file JSON documents.
Deployed directly to GitHub Pages with instant loading and near-zero operational complexity.
3D WebGL scenes, vector SVG drawings and multi-page A4 PDFs render directly on the client machine.
Future roadmap
Potential candidates for future exploration and enhancement planned for V2:
Visualise separate component parts in 3D space to clarify joinery and assembly relationships.
Interactive kinematics visualising wedge removal, backwards lid sliding, lifting and seating.
Procedural timber grain shaders and realistic texturing while maintaining zero external downloads.
Support for through dovetails, finger joints and alternative traditional toolbox arrangements.
Optional removable nested trays, tool dividers and internal storage compartments.
Automated nesting algorithms to calculate efficient cutting layouts from standard timber stock with kerf allowance.
Calculate estimated finished weight and board-foot material costs using timber density tables.
Export 2D vector technical drawings to DXF and 3D geometry to STL / GLTF mesh formats.
Explicit printable architectural scales such as 1:5 or 1:10 for workshop use.
Encode complete design parameters into lightweight, portable and shareable web links.
Offline installation manifest allowing woodworkers to use the application in the workshop without an internet connection.
Engineering reflection
AI accelerated the implementation, but the finished application came from repeated cycles of modelling, testing, review and correction. The useful part of AI-assisted software engineering is not generating a lot of code quickly; it is using the tools within a disciplined engineering process.
Japanese Toolbox Designer is released under the permissive MIT licence and is freely available for woodworkers and developers.
Launch the live browser application to design a custom toolbox, or explore the TypeScript and Three.js source code on GitHub.