Frontend framework / design system / developer tooling / solo build
Oddkin
Oddkin is a modular frontend framework built on custom elements and browser APIs. It brings together an
authoring core, a design-token pipeline, 55 themed components,
22 AI interaction elements, and the tooling that documents, tests, and
explains them: eight packages, published on npm
under the MIT license.
It is the largest system I have built, and I built all of it myself: the architecture and its
49 decision records, the Figma design framework and the documentation-site
designs, every package, the docs site at oddkin.dev, and the release process that ships it.
The oddkin.dev home page as I designed it in Figma. The live site is an Oddkin application, built from the same packages it documents.
8npm packages, released together at 1.0.0-beta.2 under the MIT license
77custom elements: 55 themed components and 22 AI interaction elements
11,132test results passed in the 1.0.0-beta.1 release run across Node, Chromium, Firefox, and WebKit, with none failed
49architecture decision records, each with its evidence and the condition that would reopen it
Counts, versions, dependencies, and test results on this page are synced from npm, the published packages, and the Oddkin repository.
What Oddkin is
A frontend framework you can adopt one layer at a time. Each package depends only on the ones it needs, so the
documentation offers five starting points instead of one install:
Tokens only. The design tokens as CSS custom properties, with no Oddkin JavaScript.
Components in any app. Register the elements you use, then write ordinary HTML, in a plain page or in React, Vue, Svelte, or Angular.
Author custom elements. Typed properties, templates that update only what changed, scoped styles, and cleanup that follows the element.
A full Oddkin application. An application root that owns its services, a store provided as context, a router, and requests that cancel themselves.
Document any library. Workbench generates component pages, API tables, and live previews from a Custom Elements Manifest.
What makes it different
The research behind Oddkin compared twelve systems, from Lit, FAST, and Stencil to React, Angular, Vue, Svelte,
and Solid. Its conclusion: the individual ideas exist elsewhere, and the value is a coherent combination that
is proven with evidence.
Cleanup follows the element. One Scope owns every listener, timer, effect, and request, and disposes them on disconnect.
Releases ship with evidence. Lint, types, tests in three engines, size budgets, and packed installs gate the release.
Package architecture
Eight packages. Each one depends only on what it needs.
The six browser packages have no
third-party runtime dependencies. A boundary check enforces the graph in CI:
it fails on a cycle, a private deep import, a component that reaches for state or routing, or an application
bundle that pulls in the tooling.
FoundationNo dependencies. Tokens work in plain CSS; core is the authoring layer.
@oddkin/tokens
Theme configuration and a deterministic token pipeline.
A brand color is the only required input; ramps, roles, modes, products, and density are generated and checked.
Emits CSS custom properties in a cascade layer, JSON, DTCG, Sass, and TypeScript references.
oddkin-tokens init | build | check; the pure generator also runs in the browser and in a Worker.
Needs: nothing
@oddkin/core
The authoring foundation.
signal, computed, and effect: one reactive graph for elements, stores, and resources.
OddkinElement.with() typed properties, html templates, css, compose(), and define().
Scope ownership, layout recipes, collections, models, i18n, and controllers for focus, announcements, forms, and positioning.
Needs: nothing · a minimal counter stays under a 9.5 KiB gzip budget
ElementsRegister only what a page uses. Works in any framework or none.
@oddkin/components
55 themed custom elements.
Fields, pickers, menus, dialogs, drawers, tabs, trees, tables, calendars, a command palette, toasts, and layout helpers.
One registration entry per element, or an autoloader that registers what the page uses.
Typings for React, Vue, and Svelte; ships its manifest, metadata, schemas, and agent kit.
DOM-free records and controllers, with server-sent event and AI SDK UI message stream adapters.
Never calls a model or stores data: the host owns transport, persistence, and policy.
Needs: components, core, and tokens
Optional servicesApplication structure when you want it. Components never require it.
@oddkin/state
Stores and context.
createStore, selectors, and actions on the same reactive graph.
Context through the community context protocol.
Versioned persistence with migrations and validation, plus inspection.
Needs: core
@oddkin/app
Application lifetime, routing, and async work.
createApp: one root scope per run, with its services and context.
A router with nested and lazy routes, typed params, focus, announcements, and scroll restoration.
Resources that cancel and ignore stale results; commands with retry and concurrency policies.
Needs: core and state
ToolingNode and development time. Reads what the packages publish; applications never ship it.
@oddkin/analyzer
Static analysis and what it produces.
oddkin-analyze: a Custom Elements Manifest and oddkin.metadata.json, without executing component code.
oddkin-impact: contract snapshots and change-impact reports.
oddkin-kit: agent guides and references, an AGENTS.md section, and llms.txt.
Needs: core and the TypeScript compiler
@oddkin/workbench
Documentation sites from metadata.
oddkin workbench dev serves a live site; oddkin workbench build writes a static one.
Catalog, component pages with interactive examples and API tables, foundations, and Theme Studio.
Documents any custom-element library that has a standard Custom Elements Manifest.
Needs: analyzer, app, components, core, state, and tokens
Core / ownership
Cleanup follows the element.
Leaked listeners, timers, observers, and requests are the most common custom-element bug. In Oddkin each
connection gets a fresh Scope, and everything started through it ends with it: no teardown array
and no matching removeEventListener().
An element that owns its work
import { OddkinElement, signal, type Scope } from '@oddkin/core';
class DemoClock extends OddkinElement {
private now = signal(Date.now());
connected(scope: Scope) {
scope.interval(() => { this.now.value = Date.now(); }, 1000);
scope.listen(this.ownerDocument, 'visibilitychange', () => {
this.now.value = Date.now();
});
}
}
From the core contract. The interval and the listener end when the element disconnects; nothing else is needed.
Updates only where the value is
One DOM-free signal graph serves elements, stores, context, and resources. Reading a signal while rendering
schedules one deduplicated render; a signal placed directly in a template binds to that single DOM part and
updates it without running render() again.
Templates are tagged html literals prepared once as cached <template>
elements: no virtual DOM, no compiler, and no decorators. Dynamic values become text, on* and
innerHTML bindings are rejected, javascript: URLs are replaced, and templates run
under a strict Content Security Policy with Trusted Types enforced in Chromium, Firefox, and WebKit.
01 · Connect
A fresh scope
Each real connection creates a new Scope and calls connected(scope), then mounted(scope) once the DOM is committed.
02 · Own
Work registers with it
listen, interval, timeout, effect, child, and use register work; scope.signal cancels fetches and streams.
03 · Disconnect
Everything ends
Disposal aborts the signal, disposes child scopes and effect runs, and runs every cleanup in reverse order, even when one throws.
04 · Reconnect
A new lifetime
A new connection gets a new scope, and an aborted signal is never reused. A supported move with moveBefore() keeps the connection.
scopeStats() counts live scopes, listeners, timers, and effects. The leak tests mount and remove 100
counters 100 times in three engines and require every count to return to its baseline.
Tokens / Theme Studio
One brand color in, a checked theme out.
@oddkin/tokens turns a small configuration into every token a theme needs. The generator is pure
and deterministic: run in a Worker, it produces the same bytes as the command line and the shipped CSS, which
is what lets Theme Studio edit a real theme in the browser.
01 · Configure
ThemeConfig
A brand color is the only required input. Modes, products, density, conditions, and overrides are optional.
02 · Resolve
Precedence
Oddkin defaults, then a preset, then your configuration, then explicit overrides. Every token records its origin.
03 · Generate
Ramps and scales
Eleven-step OKLCH ramps, gamut-mapped to sRGB or Display P3 without moving hue or lightness, plus spacing, type, radius, elevation, and motion.
04 · Compose
Modes and products
Light and dark are scopes over the same components; products and densities re-declare only the tokens that change.
05 · Validate
Real role pairs
Contrast is checked on the pairs components actually use, with units and target sizes; diagnostics point into the configuration.
06 · Emit
Every format
CSS custom properties in the odd.tokens cascade layer, JSON, DTCG, Sass modules, and typed TypeScript references.
Theme Studio: controls on the left, the same components in light and dark from one theme, and an inspector that traces a value from override to role to component.The color editor in dark mode: eleven lightness steps from one brand hue, six gamut-mapped to sRGB, and 124 of 124 applicable contrast pairs passing.
Figma design framework
The design files are under test too.
I designed Oddkin in two Figma files: a design framework with foundations, primitives, composed components, AI
components, and icons; and the documentation site, in desktop and mobile layouts, from the home page to every
Theme Studio editor. The repository keeps the design honest instead of trusting it by eye.
Variables
A snapshot of the library's variables, text styles, and effects is compared with the default theme in light and dark. The test lists variables without a token, tokens Figma lacks, and every alias gap.
Parity pass
On October 22, 2026: 336 variable comparisons, 134 light and dark role comparisons, and 52 text-style metrics matched, with zero mismatches.
Components
Browser tests mount components and compare them with a snapshot of the Figma components. Each deliberate difference is listed in the test with its reason.
Icons
1,723 original outline icons in General, GIS, and Healthcare sets, on a 20-pixel grid with 1.5-pixel strokes, with one validated catalog that maps every SVG to its Figma component.
Primitives in dark mode, from the design framework's review pages: the same components and roles as light mode.Every combined state is drawn, selection crossed with focus, invalid, and disabled, so keyboard focus is designed rather than left to the browser.
@oddkin/ai
AI interfaces as components, with the host in control.
The AI package covers conversation, inline assistance, research, and agent workflows. Elements request and the
host decides: the package never calls a model, stores a conversation, or enforces authorization, and approving
an action is never shown as the action succeeding.
Elements
Twenty-two in the current release: action approval, activity, AI label, artifact, change review, checkpoint, citation, context picker, conversation, inline assist, message, model select, prompt input, question, response, response feedback, sources, task plan, tool call, transcript, usage meter, and voice input.
Controllers
DOM-free records and controllers for conversations, composers, document sessions, and voice. Transport, attempts, tools, approvals, and stops are separate state machines, so one never implies another.
Streams
A server-sent events parser, an adapter for the AI SDK UI message stream, a simulation adapter for demos and tests, and streaming Markdown with a URL policy. The streaming chat example runs under a strict Content Security Policy.
odd-action-approval in light and dark: the affected file, the risk, a before-and-after change, an optional reason, and an explicit decision.
Metadata / agent tooling
One metadata source feeds the docs, the agents, and the tools.
The analyzer reads component source with the TypeScript compiler and never executes it. What it writes is the
single description the rest is generated from, so the documentation and the agent guides describe the version
that shipped.
01 · Source
Typed definitions
OddkinElement.with() properties, compose() definitions, events, slots, parts, and defineExamples, written once.
02 · Analyze
oddkin-analyze
Static analysis that never runs component code. After the tests, their contract evidence is attached to the result.
03 · Publish
Two files in every package
The standard Custom Elements Manifest, plus oddkin.metadata.json: when to use each element, accessibility and keyboard notes, token mappings, and examples.
One source feeds four surfaces
Docs
Workbench pages and oddkin.dev: the catalog, API tables, interactive examples, and live previews.
Agents
A kit in every package: a GUIDE.md within an 8 KiB budget, one reference per element, llms.txt, and a fingerprinted kit.json.
Composition
Interfaces as data: renderComposition() renders only published elements, attributes, and properties, with no scripts or HTML strings.
Impact
oddkin-impact snapshots the contracts and compares two versions: what changed, what it affects, and which checks cover it.
Workbench's interactive example for odd-button: controls, slots, and accessibility requirements come from the metadata, and the preview updates as you edit.
Change impact
A change explains what it touches.
oddkin-impact compares two snapshots of a library's contracts. The repository records a real run:
two commits that renamed a menu part and lightened one theme token, each revision built with its own build
steps.
One reason path from the report
Tokencolor.surface.specimen
Stylecombobox.styles.js#comboboxStyles
Definitionodd-combobox
Componentodd-combobox
Exampleodd-combobox/default
6changes: 1 incompatible, 4 to review, and 1 informational
4components affected: combobox, menu, picker, and split button
29checks selected by reason path, all passed in Chromium, Firefox, and WebKit
5agent-kit files changed, generated from both revisions
Incompatiblepart:odd-menu#item removed: a possible rename to part:odd-menu#menuitem, marked unconfirmed
Every selected check passed, and the report still marks the removed part incompatible: passing checks do not
make a contract change compatible.
Verification
Releases ship with their evidence.
Every push to main runs the same pipeline. For 1.0.0-beta.1, the
release commit's run, its test results, and each package's integrity hash are attached to the GitHub Release.
The counts below are from that run.
01 · Static
Lint and types
Contracts, package boundaries, CSS compatibility with the browser floor, page layout, and formatting; then types for packages, tests, JSX, and frameworks.
02 · Build
Everything generated
Production builds, token assets, component CSS, metadata, schemas, AI demos, and agent kits.
03 · Test
Node and three engines
1,536 passed in Node, 2,856 in Chromium, 2,801 in Firefox, and 2,808 in WebKit.
04 · Budgets
Metadata and size
Contract-test evidence attached to the metadata, the API vocabulary checked, and bundle and stylesheet size budgets enforced.
05 · Consumers
End to end and packed
Playwright in three engines (381, 375, and 375 passed), then packed tarballs installed outside the workspace, imported, and type-checked.
06 · Evidence
Attached to the release
A change-impact summary and the release evidence: commit, package integrity, generated-file hashes, and results.
Before publishing, fresh Vite, React, Vue, Svelte, and Angular apps installed the packed packages and built them
with their own tools in three engines, and two versions of core ran side by side on one page.
How I built it
Oddkin is a solo project. I did the research, wrote the implementation plan, and made every architectural and
product decision, recording each one as a decision record or a dated owner decision. I designed both Figma
files, the design framework and the documentation site, before and alongside the code.
I ran the implementation as a coordinated AI-assisted engineering effort: up to four coding agents in parallel,
each in its own git worktree, working lanes I defined from the plan's milestones. Integration ran through the
same lint, type, test, size, and packaging checks, and a verification log records what each run proved and
what it did not.
First commit on October 17, 2026; 1.0.0-beta.0 on npm on October 28; the current release,
1.0.0-beta.2, on
November 8, 2026; and
500+ commits on main.
Honest limits
It is a beta: contracts may change before 1.0.0, and Workbench's and the analyzer's contracts stay open after it.
Screen readers are not yet verified, and no accessibility conformance level is claimed. Keyboard paths and axe-core checks run in three engines.
Safari is tested through Playwright's WebKit, not on Apple hardware, and mobile browsers are not tested.
pnpm, Yarn, webpack, Rspack, and Node.js below 24 are not tested, and server-side rendering is not supported.
There is no MCP server or agent package yet; the kits and the metadata are the agent interface.
No comparative performance benchmark is published, so the documentation claims no performance lead.
Why it matters
Design intent, carried all the way to production.
Oddkin is the most complete expression of how I work: decide in writing, design the system and its edge cases,
build it in layers, and back each claim with a check that someone else can run again.