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.

8 npm packages, released together at 1.0.0-beta.2 under the MIT license
77 custom elements: 55 themed components and 22 AI interaction elements
11,132 test results passed in the 1.0.0-beta.1 release run across Node, Chromium, Firefox, and WebKit, with none failed
49 architecture 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.

  1. Cleanup follows the element. One Scope owns every listener, timer, effect, and request, and disposes them on disconnect.

  2. Tokens work without JavaScript. One brand color becomes a contrast-checked theme, from the same pure generator everywhere.

  3. Design and code are tested against each other. The Figma library's variables and components are compared with the code.

  4. AI interfaces are components. Twenty-two elements and headless controllers; the host keeps the model, the data, and the policy.

  5. One metadata source. Static analysis feeds the docs, the agent kits, the composition schemas, and change impact.

  6. Changes explain themselves. A token edit traces to the components, examples, and checks it touches.

  7. 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.

    Needs: core and tokens

  • @oddkin/ai

    22 elements for AI interfaces.

    • Conversations, prompt input, streaming responses, citations, tool calls, approvals, task plans, and change review.
    • 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.

  1. 01 · Connect

    A fresh scope

    Each real connection creates a new Scope and calls connected(scope), then mounted(scope) once the DOM is committed.

  2. 02 · Own

    Work registers with it

    listen, interval, timeout, effect, child, and use register work; scope.signal cancels fetches and streams.

  3. 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.

  4. 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.

  1. 01 · Configure

    ThemeConfig

    A brand color is the only required input. Modes, products, density, conditions, and overrides are optional.

  2. 02 · Resolve

    Precedence

    Oddkin defaults, then a preset, then your configuration, then explicit overrides. Every token records its origin.

  3. 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.

  4. 04 · Compose

    Modes and products

    Light and dark are scopes over the same components; products and densities re-declare only the tokens that change.

  5. 05 · Validate

    Real role pairs

    Contrast is checked on the pairs components actually use, with units and target sizes; diagnostics point into the configuration.

  6. 06 · Emit

    Every format

    CSS custom properties in the odd.tokens cascade layer, JSON, DTCG, Sass modules, and typed TypeScript references.

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.

@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.

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.

  1. 01 · Source

    Typed definitions

    OddkinElement.with() properties, compose() definitions, events, slots, parts, and defineExamples, written once.

  2. 02 · Analyze

    oddkin-analyze

    Static analysis that never runs component code. After the tests, their contract evidence is attached to the result.

  3. 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.

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

  1. Tokencolor.surface.specimen
  2. Stylecombobox.styles.js#comboboxStyles
  3. Definitionodd-combobox
  4. Componentodd-combobox
  5. 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
  • Reviewclass:odd-menu changed
  • Reviewtemplate:menu.template.js#menuTemplate changed
  • Reviewtoken:color.surface.specimen value changed
  • Reviewtheme:base changed
  • Informationalpart:odd-menu#menuitem added

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.

  1. 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.

  2. 02 · Build

    Everything generated

    Production builds, token assets, component CSS, metadata, schemas, AI demos, and agent kits.

  3. 03 · Test

    Node and three engines

    1,536 passed in Node, 2,856 in Chromium, 2,801 in Firefox, and 2,808 in WebKit.

  4. 04 · Budgets

    Metadata and size

    Contract-test evidence attached to the metadata, the API vocabulary checked, and bundle and stylesheet size budgets enforced.

  5. 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.

  6. 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.