Getting started
Technical overview.
Aestheria, the design context layer, is three layers in one package: a framework-agnostic token layer in CSS, a React component implementation, and a machine-readable design context your agent reads. This page is the contract for what ships and how you consume it.
The three layers
Aestheria ships as three layers, stacked from the most portable to the most specific.
The token layer is the floor everything stands on, and the layer that travels furthest. The component layer is React-specific. The context layer is what makes the other two legible to an agent, not just a human.
The token layer is framework-agnostic
Tokens are CSS custom properties, organized in three tiers: a fixed palette, semantic tokens that components reference, and a theme map for light and dark. Components never touch a raw palette value. They read a semantic token, and the theme map decides what that token resolves to.
Because they are ordinary CSS variables, tokens are not tied to React. Any surface that renders CSS can read them: a React app, a static HTML page, a Vue or Lit component, an email template. Set data-theme and data-mode on a wrapper and every token below it resolves for that brand and mode.
The token and component styles are published as two stylesheets, tokens.css and components.css, importable from a CDN. That is the whole design language, portable, in two files.
The component layer is React
The component implementation is React. It is built on React 19, and the published package, @aestheria/react, works with React 18 and up. Components are distributed as ES modules, with React left as a peer dependency your app already provides.
You import a component and compose it with props, the same as any React component. State and events follow the standard React model. There is no runtime to adopt beyond a theme wrapper, and no Aestheria-specific build step.
What the component layer ships:
- 34 components across inputs, actions, data display, navigation, and overlays
- 27 chart and data-visualization types
- 14 card archetypes
- Interaction patterns and full-page SaaS templates
- Every component in its empty, loading, error, disabled, and selected states, in light and dark, across three themes
The components are authored in React and ship as JavaScript modules. Using them outside React means the tokens still travel, but the components do not. That surface reads the CSS and rebuilds the markup, or waits for a web-component build.
The design context layer
The third layer is what separates a design context layer from a component library. Alongside the visual system, Aestheria ships a machine-readable description of it: what each component is for, when to use it, and the rules that govern it.
An agent reads this context two ways. AGENTS.md points it at the system from the repo root. An MCP server serves the same source live over the wire, so an agent queries current tokens, components, and patterns on demand instead of working from a snapshot pasted into a prompt.
The context is versioned as a contract. It is the interface the MCP preserves, so an agent that builds against it today builds against the same shape tomorrow.
How you consume it
Three ways in, by how much you run yourself.
| Path | Format | You run | Best for |
|---|---|---|---|
| MCP | A hosted server over the Model Context Protocol | Nothing | Agents that should build on-system from the first prompt |
| Self-host | The React package plus the CSS bundle, in your repo | The package, pinned to a version | Teams that want the system owned and versioned in their own project |
| CDN | tokens.css and components.css over a URL | Nothing | Reading the tokens and component styles on any surface, framework or not |
See plans and pricing
Builds and artifacts
The repository builds with Vite and installs with npm. A handful of build commands produce the artifacts a consumer actually receives, each generated from one source.
| Artifact | What it is |
|---|---|
| @aestheria/react | The React component package: ES modules with React externalized, plus one bundled stylesheet. |
| tokens.css | The full token layer: palette, semantic tokens, and every theme, concatenated into one file. |
| components.css | The component class library, referencing semantic tokens only. |
| Studio package | The self-host download: the entire Studio system, wired to run as a standalone install. |
There is no hand-maintained copy that can drift from the system the Studio shows. What the docs render, what the package ships, and what the MCP serves all resolve against the same files.
One version, in lockstep
The whole design system releases under a single version number. The React package, the CSS bundle path, and the version the MCP reports all track it, so there is never a question of which tokens pair with which components.
Pin a version and the system holds still. Move it and every layer moves together. A self-host consumer controls exactly when that happens. An MCP consumer reads the latest by default, and can build against a fixed version when they need to.
The framework boundary
One line to remember. Tokens are framework-agnostic. The component implementation is React.
That boundary is deliberate. The layer most teams need to share across tools and surfaces, the design language itself, travels as plain CSS. The layer that benefits from a real component model, the interactive product UI, is built in React and stays there. Where you need the components in another framework, the tokens still carry the design, and a compatible adapter or a separate web-component build carries the rest.