The AI-native differentiator
Most design systems target human consumers — a designer in Figma, an engineer in docs, a snippet copied into an IDE. Aura is more than a component library: it is purpose-built because AI agents write a significant portion of product code, and it is designed to be consumed equally well by humans and agents. That distinction shapes what Aura ships alongside components and how guidance is packaged and delivered.What “AI-native” means in practice
A traditional design system ships components and documentation. Aura ships components, documentation, and a layer of structured AI tooling that makes correct implementation the path of least resistance for agents and humans.- Skills — Structured prompt modules for Cursor, Claude, and other AI tools that activate automatically when a relevant pattern is detected. Skills enforce the right component, the right token, and the right pattern before any code is written.
- DESIGN.md — A machine-readable source of truth for foundations and primitives. Agents can read this file to understand the system’s constraints and intent, just as engineers would read documentation.
- LLM metadata — Every component carries structured
llmUsagemetadata: when to use the component, when to reach for another primitive, and what pairs well with it. This metadata surfaces directly in agent context windows. - MCP server — A Model Context Protocol server that exposes Aura’s documentation to AI tools at query time. Agents can retrieve up-to-date guidance without hallucinating from stale training data.
Why this matters
When an agent implements UI without design system guidance, it improvises. Improvisation accumulates into visual debt, broken theming, inaccessible patterns, and inconsistent experiences that are expensive to fix. Aura gives agents the same opinionated guardrails an engineer would enforce in code review, but earlier in the loop and at scale.How Aura differs from a traditional design system
| Category | Traditional design system | Aura (AI-native) |
|---|---|---|
| What it ships | Components and written documentation | Components, documentation, and structured AI tooling |
| Who consumes it | Humans reading docs and Storybook | Humans and AI agents equally |
| Where guidance lives | Notion, Confluence, or static sites | Machine-readable files (DESIGN.md, llmUsage, skills) |
| How tokens are applied | Interpreted and manually applied by developers | Enforced at the skill layer before code is written |
| How conformance works | Depends on human discipline in code review | Built into the agent workflow, not only code review |
| Agent tooling | Out of scope | Skills, MCP server, and Cursor rules are first-class deliverables |
What Aura defines
Aura provides three layers that work together:| Layer | What it covers | Where it lives |
|---|---|---|
| Foundations | Color, typography, spacing, radii, effects, motion, icons | Tokens, Figma, DESIGN.md |
| Primitives | Component behavior, variants, composition rules, accessibility | NPM package, Storybook, llmUsage |
| Patterns | Repeatable multi-component solutions: layouts, flows, surfaces | Skills, docs, Storybook |
Aura ships in two tiers. Core components are production-ready, risk-reviewed, and available in the
@cognite/aura package. Labs components are available for use but are still being stabilized and may change before graduating to Core. Patterns are in progress. See In development for the current roadmap.Who this documentation is for
Aura serves three distinct audiences, and this documentation is organized with all three in mind.Designers
Designers
You work in the Figma library, prototype with Cursor or Claude, contribute to the system, and make decisions about how components look and behave. Use this documentation to understand usage intent, token semantics, and the design rationale behind system decisions. The Figma library is the canonical visual reference; this documentation explains the why behind it.Start here: Color → Primitives overview
Engineers
Engineers
You implement product UI using the
@cognite/aura package, with Storybook as your API reference and tokens as your styling system. Use this documentation for the decision-level guidance that doesn’t live in props tables: when to reach for one component over another, how tokens are structured, and how to stay conformant without reading every Figma file.Start here: Installing Aura → StorybookAI agents
AI agents
You implement UI on behalf of engineers and designers. Consume Aura through its structured tooling layer: skills activate automatically for common patterns,
DESIGN.md and llmUsage metadata provide scoped guidance, and the MCP server gives you access to up-to-date documentation at query time. Never invent component behavior or use raw hex values — always defer to the token and component system.Start here: Installing Aura → Exploring Aura foundations