Case Study: Tessera - A Frontend Framework Where the Design System Is the Framework

Creator & Lead Engineer

Most frontend frameworks make the component the core abstraction. Design tokens, accessibility, documentation and enforcement get bolted on afterward, so drift from the design system is caught in code review, if it is caught at all.

Tessera flips that. It is a design-system-first framework where the contract, the tokens and the compiler come first, and drift becomes a build error instead of a review comment. It is also my answer to a question I kept hitting at Privacy Bee: what if the guardrails lived in the toolchain instead of in a document?

The Friction (What was breaking)

• Drift is a social problem: Design systems rely on people remembering to use the right token, the right variant and the right ARIA role. Under deadline pressure, they don't.
• Docs rot: Hand-written documentation, accessibility tests and changelogs fall out of sync with the code the moment someone ships a change.
• AI tools guess: Coding assistants happily invent raw hex values, off-scale spacing and variants that don't exist, because nothing tells them what the system actually allows.
• Adoption is all-or-nothing: Strict enforcement is useless if turning it on in an existing app produces ten thousand errors on day one.

The Architecture

Tessera is a pnpm monorepo written in strict TypeScript and built on Vite, published as a single package, @pixelscriptio/tessera, with subpath exports. The internal packages stay internal and get bundled in, so the install stays simple while the codebase stays modular.

1. The Contract: Every component is a .tess file with a contract, script, template and style block. The contract declares the anatomy, variants, states, ARIA role and contrast pairings once. Types, docs, the playground and accessibility tests are all derived from it.
2. The Tokens: Tokens use the W3C DTCG format in three tiers (primitive, semantic, component) and compile to CSS custom properties in cascade layers. Themes can override values but can never invent new token names.
3. The Compiler: It parses, validates the contract, template and styles, then generates DOM-creating functions bound to fine-grained signals. There is no virtual DOM, and the core has zero runtime dependencies.

The Strategy

Enforcement only works if people can live with it, so most of the design effort went into making strictness feel helpful instead of hostile.

Errors that tell you the fix

Every error has a stable code, a file location and a "Did you mean" suggestion. Write tone="sucess" and the compiler points at success. Use 13px for padding and it suggests the nearest step on the scale. Where a fix is unambiguous, --fix applies it without changing the computed visual result.

A way in for existing code

A baseline records today's violations per file so an existing app can turn enforcement on with zero errors. Counts can only go down, exemptions need a reason and an expiry date, and tessera report tracks the remaining debt so the cleanup is visible.

Everything derived, nothing hand-written

• Docs: tessera docs generates a documentation app with a page for every component and token group, a contrast checker and coverage reports.
• Accessibility: tessera a11y generates axe-core tests for every variant, state and theme, and the docs spell out what automation can't cover.
• Change management: tessera diff classifies changes as breaking, additive or cosmetic (a value change that flips a contrast result counts as breaking), and tessera codemod applies renames.
• Interchange: Tokens move between DTCG files, Tokens Studio, Penpot, Figma variables and CSS custom properties.

Beyond .tess files

Not every team will rewrite their app. tessera lint checks CSS against your tokens in any project, and tessera elements builds the design system as custom elements with examples for React, Vue, Svelte and Angular. The starter preset ships 11 elements in about 9 kB of JavaScript and 3 kB of CSS, gzipped.

Built for AI tools

Tessera exports a manifest, generated AGENTS.md and llms.txt files, and a read-only MCP server. Agents can search components, read contracts, resolve a raw value to the nearest token and validate a snippet with the compiler's own checks before they write anything. I treated this as a bet to test, not a claim: in a small informal run, prompts without the tools produced 2 errors across 15 files, and with them, 0 errors across 9. It is a smoke test, not proof, and the site says so.

The Payoff

Tessera is live at tessera.pixelscript.io, with generated docs at tessera-docs.pixelscript.io and the source on GitHub. It is early development (v0.6) and the API will change, but the core idea already holds up: when tokens, accessibility and variants are enforced by the compiler, the design system stops being a document people are asked to follow and becomes the thing the code is built from.