@kode4/react-foundation

A typed application foundation for React: a typed router that turns route definitions into the app's single source of truth, a themed UI component library, and a CSS-variable design system — built to be consumed by humans and by AI agents.

• Typed router as the app spine — declare each route once with defineRoute (path, Zod-validated params/search, loader, typed action, eager or lazyComponent code-split component, document title, menu/tabs metadata); the library derives the React Router v7 config plus typed links (TypedLink with prefetch/viewTransition, pathTo), menus, breadcrumbs, guards via chain(), scroll restoration (window + inner containers), an aria-live route announcer, a designed 404 (notFoundRoute), and onNavigate/onError observability seams.
• UI component library — 70+ components on Radix primitives (shadcn/ui as the blueprint): the full input family (incl. PasswordInput, OTPInput, TagInput, NumberInput, Rating, MaskInput, ComboBox), date/time pickers with a partial-aware value model + DateRangePicker, rich editors (MarkdownEditor, HtmlEditor, SignaturePad), media (Gallery, Video, ZoomImage), a multi-step Wizard (branching, persistence, per-step loaders), EmptyState, DataTable (sorting, pagination, row selection, column visibility, global filter, pinning/resizing, per-column filters, row expanding + grouping/aggregation, CSV export + a virtualization recipe — client or server mode, over TanStack Table), and the layout frames/nav chrome.
• Forms layer — react-hook-form + Zod with 20+ form-bound …Field components (label/description/error wired for you), WizardForm for multi-step forms, and a busy-gate for async fields like uploads.
• Charts — LineChart/BarChart/PieChart over recharts, colored by design tokens (dark mode included).
• File uploads — a headless upload layer (progress, cancel, hashing, dedupe, upload-handle model) behind FileField/ImageField (with cropper).
• Design system — semantic CSS-variable tokens (shadcn standard names) with light/dark mode; re-theme everything without a rebuild, no Tailwind required in your app. Built-in label layer (I18nProvider) for i18n with no framework dependency.
• A11y + tests as a posture — 2189 Vitest unit/integration tests (every component axe-checked) plus Playwright end-to-end and pixel visual-regression suites over the demo.

src/lib is the library (published to npm). src/demo is the showcase app that exercises every feature — it's also the living reference for the documented patterns.

Quick start

Scaffold a ready-wired app (Vite + React + TS, provider stack, typed router, locale routing, sample routes):

npm create @kode4/react-foundation@latest my-app
cd my-app && npm install && npm run dev

Or add the library to an existing app:

npm install @kode4/react-foundation

import { createAppRouter, defineRoute, ThemeProvider } from '@kode4/react-foundation';
import '@kode4/react-foundation/styles.css'; // once, near the app root
import { RouterProvider } from 'react-router-dom';

const homeRoute = defineRoute({ index: true, component: HomePage, title: 'Home' });
const shellRoute = defineRoute({ component: Shell, children: [homeRoute] });

const router = createAppRouter([shellRoute], { queryClient });

export const App = () => (
	<ThemeProvider>
		<RouterProvider router={router} />
	</ThemeProvider>
);

The full bootstrap (providers, menus, guards, theming) is in docs/INSTRUCTIONS.md.

If you are an AI agent building an app on this library, read docs/INSTRUCTIONS.md first — it is written for you. It is the complete consumer contract: the mental model, the typed-router patterns, the component catalog with props and idioms, theming, data/forms recipes, and the pitfall checklist. Follow it and the app comes out idiomatic, type-safe, and themeable.

Documentation

The consumer-facing docs below ship inside the npm package (see the DOCS list in scripts/build-lib.mjs), so these links resolve both in the repo and in node_modules/@kode4/react-foundation.

For consumers (building an app on the library)

• docs/INSTRUCTIONS.md — start here. The consumer contract: read it when building or extending an app on the library (router, catalog, theming, data, forms, uploads, effects, errors, testing).
• docs/DESIGN-SYSTEM.md — the theming/token contract: read it when restyling — every token, the -foreground convention, fonts, light/dark mechanics.
• docs/combo-box.md — the ComboBox living spec: read it when working with async sources, value modes, or creatable selects.
• docs/date-picker.md — the date/time design contract: read it when you need the partial-aware value model, ranges, or bounds explained in depth.
• docs/gallery.md — the Gallery carousel/lightbox living spec: read it when composing galleries, slideshows, or the lightbox.

For contributors (working in this repo — not shipped in the package)

• CLAUDE.md — repo-internal conventions: read it before changing library or demo code (boundaries, barrels, BEM/k4- styling, what "done" includes).
• docs/TESTING.md — the testing policy: read it before adding tests — the change→test decision table, the done checklist, and the visual-regression/baseline mechanics.
• docs/FEATURES.md — the shipped-capability record: read it to see what larger features are already built (the companion to the roadmap; the full component catalog is in INSTRUCTIONS.md).
• docs/ROADMAP.md — upcoming, not-yet-built work only: read it before proposing a new component (Tier 3 + cross-cutting items remain; shipped work lives in FEATURES.md).
• docs/IMPROVEMENTS.md — the audit-findings backlog: read it before starting broad cleanup work.
• docs/RELEASING.md — the release checklist: read it when publishing the library and/or the initializer (order matters).
• docs/docker.md — deploying the demo as a two-container Docker/Portainer stack: read it when shipping the demo.
• docs/website-migration.md — the notes behind the demo's default Kode4 landing/theme.
• create/ — the npm create @kode4/react-foundation initializer (separate package @kode4/create-react-foundation); its template/ is a real consumer app and a public surface.

Working in this repo

npm install
npm run dev        # demo at http://localhost:3010 (mock /api mounted into Vite)

Scripts

# build & checks
npm run build              # typecheck + boundary check + production bundle (demo)
npm run build:lib          # build the publishable package into dist-lib/
npm run typecheck          # tsc --noEmit (demo + lib; typecheck:server for server/)
npm run lint               # eslint (lint:fix to autofix)
npm run format             # prettier --write (format:check in CI)
npm run check:boundaries   # enforce lib/demo import boundaries

# tests (see docs/TESTING.md)
npm test                   # Vitest unit + integration (jsdom); :watch / :coverage
npm run test:e2e           # Playwright end-to-end (demo, real browser); :ui / :report
npm run test:visual        # pixel screenshots against the Linux baselines (Docker)
npm run test:visual:update # regenerate the screenshot baselines (Docker)

# release validation (see docs/RELEASING.md)
npm run validate:lib       # build dist-lib + publint + arethetypeswrong + import smoke
npm run validate:template  # scaffold from create/ against a local tarball and build it

# demo backend & codegen
npm run dev:server         # mock API standalone (dev mounts it into Vite automatically)
npm run gen:spec           # emit openapi.json from the server (gen:spec:fetch to download)
npm run gen:api            # generate the typed client schema from openapi.json
npm run start              # serve built demo + /api from one Node process
npm run docker:build       # build the demo's Docker images (--push or docker:publish to push; see docs/docker.md)

Publish: npm run build:lib && npm publish ./dist-lib (library first, then the initializer — see docs/RELEASING.md).

License: MIT.