For the complete documentation index, see /llms.txt. A single-fetch full bundle is at /llms-full.txt. Every docs page is also available as Markdown by appending.mdto its URL, or by requesting it withAccept: text/markdown.
Theming
@erc8004/ui uses CSS variables for theming. This gives you a set of named color and radius tokens that every component references. Override those tokens in your CSS to change the look of the entire library without touching component code.
Out of the box, the library ships with a light theme and a dark theme. No configuration required — just import the stylesheet and go. Colors use OKLCH rather than hex. OKLCH is perceptually uniform — lightening or darkening a value produces a predictable visual shift, which makes themes easier to build and tweak.
import "@erc8004/ui/styles.css"OKLCH Color Format
All color tokens are raw OKLCH values — three space-separated numbers for lightness chroma hue:
- Lightness —
0(black) to1(white). - Chroma — saturation.
0is gray, higher values are more vivid. - Hue — color angle in degrees.
260blue,145green,300purple,25red-orange.
For neutral grays, chroma and hue are both 0 (e.g., 0.556 0 0 is a medium gray). Use oklch.com to pick values interactively.
Playground
Click a preset to see all the token changes take effect live. The code block below the preview shows exactly what CSS you would write to reproduce that theme in your own app.
DataSift Agent
Real-time data pipelines and stream processing. Supports MCP for tool orchestration.
// Default — no overrides needed.
// Import the stylesheet and you're done:
import "@erc8004/ui/styles.css"How It Works
Every component in the library uses Tailwind classes like bg-erc8004-card and text-erc8004-muted-fg instead of hardcoded colors. These classes reference CSS variables defined under the .erc8004 scope — a wrapper that the ERC8004Provider renders automatically.
Because the variables are scoped to .erc8004, they never conflict with your app's own styles. If your app uses shadcn, Tailwind's default palette, or any other styling system, everything coexists cleanly. Dark and light mode work by swapping the variable values when a .dark or .light class is present on an ancestor — see Dark and Light Mode below.
Three Ways to Customize
Pick the broadest method that does the job. Use CSS variables to retheme everything, provider className to scope a theme to a section of your app, or component className for one-off tweaks.
Option 1 — CSS Variable Overrides — retheme everything
Override the variables in your own stylesheet. Every component picks up the changes instantly.
/* your-app.css */
.erc8004 {
--erc8004-accent: 0.55 0.25 300; /* purple instead of blue */
--erc8004-radius: 0.75rem; /* rounder corners */
}Option 2 — Provider className — scope a theme to a subtree
The provider accepts a className prop that gets merged onto the .erc8004 wrapper. Two common uses:
Toggle light or dark mode:
<ERC8004Provider apiKey="..." className="dark">
{/* dark theme active for all components inside */}
</ERC8004Provider>
<ERC8004Provider apiKey="..." className="light">
{/* forces light theme, even inside a .dark ancestor */}
</ERC8004Provider>Apply a custom theme class:
/* Define a custom theme class */
.erc8004.my-brand {
--erc8004-accent: 0.55 0.25 300;
--erc8004-radius: 0.75rem;
}<ERC8004Provider apiKey="..." className="my-brand">
{/* all components inside use the custom theme */}
</ERC8004Provider>Option 3 — Component className — one-off tweaks
Every component accepts a className prop. Your classes override the component's defaults when they target the same CSS property — padding replaces padding, background replaces background.
<ReputationScore
agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
agentId={2290}
className="shadow-lg rounded-2xl p-6"
/>Token Convention
Tokens follow a background / foreground pair pattern. The base token controls the surface color, and the -fg suffixed token controls the text and icon color that sits on that surface.
For example, given these variables:
.erc8004 {
--erc8004-card: 1 0 0; /* white surface */
--erc8004-card-fg: 0.145 0 0; /* near-black text */
}A component using bg-erc8004-card text-erc8004-card-fg will render dark text on a white card. Override the variables, and the component adapts — you never need to change the component itself.
Dark and Light Mode
The default theme is light — no setup needed. Adding a .dark ancestor class switches components to dark mode. This is the standard Tailwind dark mode convention that most apps already use.
<body class="dark">
<!-- ERC8004 components automatically use dark colors -->
</body>Adding a .light ancestor class explicitly forces light mode, even inside a .dark parent. This is useful for embedding components in a light section of an otherwise-dark app.
<body class="dark">
<!-- dark everywhere... -->
<div class="light">
<!-- ...except these components stay light -->
<ERC8004Provider apiKey="...">
<ReputationScore agentRegistry="..." agentId={2290} />
</ERC8004Provider>
</div>
</body>Either class can go on the body tag, a container div, or directly on ERC8004Provider via the className prop. If your app already handles dark mode by toggling a .dark class, the library follows along automatically.
Overriding dark mode colors
To customize specific colors in dark mode, target .dark .erc8004:
.dark .erc8004 {
--erc8004-accent: 0.7 0.2 260; /* brighter blue in dark mode */
--erc8004-card: 0.18 0.01 260; /* slight blue tint to cards */
}Overriding light mode colors
Similarly, to customize colors only in explicit light mode, target .light .erc8004:
.light .erc8004 {
--erc8004-accent: 0.5 0.22 260; /* deeper blue in light mode */
--erc8004-card: 0.98 0.005 80; /* warm white cards */
}Token Reference
Surfaces
Accent
Semantic
Borders & Focus
Chart Palette
Radius
Radius Scale
The library derives a set of radius sizes from the single --erc8004-radius base value:
Change --erc8004-radius once, and the entire radius scale updates proportionally:
.erc8004 {
--erc8004-radius: 0.75rem; /* everything gets rounder */
}.erc8004 {
--erc8004-radius: 0; /* sharp corners everywhere */
}Examples
Match your brand color
.erc8004 {
--erc8004-accent: 0.55 0.25 300; /* purple */
--erc8004-ring: 0.55 0.25 300; /* focus rings match */
}Warm neutral palette
.erc8004 {
--erc8004-bg: 0.98 0.005 80; /* warm white */
--erc8004-card: 0.96 0.008 80; /* warm off-white */
--erc8004-muted: 0.94 0.01 80; /* warm gray */
--erc8004-border: 0.9 0.01 80; /* warm border */
}Compact with sharp corners
<ReputationScore
agentRegistry="eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
agentId={2290}
className="p-2 text-sm rounded-none"
/>Full custom theme via CSS class
/* teal-brand.css */
.erc8004.teal-brand {
--erc8004-accent: 0.6 0.22 160; /* teal */
--erc8004-positive: 0.6 0.22 160; /* match accent for positive */
--erc8004-negative: 0.55 0.2 0; /* warm red */
--erc8004-border: 0.88 0.01 160; /* subtle teal borders */
--erc8004-radius: 1rem; /* very rounded */
}<ERC8004Provider apiKey="your-graph-api-key" className="teal-brand">
{/* all components use the teal theme */}
</ERC8004Provider>Provider Props
The only theming-relevant prop on ERC8004Provider is className, which gets merged onto the .erc8004 wrapper. See the ERC8004Provider component page for the full prop reference.
<ERC8004Provider apiKey="..." className="dark my-theme">
{children}
</ERC8004Provider>FAQ
Does the library ship its own font?
No. Components inherit font-family from their parent, so they adopt whatever typography your app uses. Set the font on .erc8004 or any ancestor and components will follow. Some elements like numeric scores and addresses use monospace (font-mono) for readability, but no base font is bundled or required.
Can I force light mode inside a dark app?
Yes. Add className="light" to the provider (or any ancestor of the components you want to stay light). This works even when a higher ancestor has .dark set.
Will this conflict with my app's Tailwind config?
No. All tokens are namespaced under erc8004- and scoped to the .erc8004 class. They don't touch your app's --primary, --background, or any other standard Tailwind/shadcn variables.
Do I need Tailwind in my project to use className?
Not strictly — className accepts any CSS class string. But the library is built with Tailwind, so overriding with Tailwind classes gives you the most predictable results since tailwind-merge understands the conflict resolution. If your project doesn't use Tailwind, you can still pass regular CSS classes or use the CSS variable overrides instead.
Can I theme individual components differently?
Yes. Wrap a subset of components in a div with overridden variables:
<ERC8004Provider apiKey="...">
{/* These use the default theme */}
<ReputationScore agentRegistry="..." agentId={1} />
{/* These use a custom accent */}
<div style={{ "--erc8004-accent": "0.55 0.25 300" } as React.CSSProperties}>
<ReputationScore agentRegistry="..." agentId={2} />
<FeedbackList agentRegistry="..." agentId={2} />
</div>
</ERC8004Provider>Since CSS variables inherit downward, any div that redefines a variable creates a new scope for its children.
What color format should I use?
Raw OKLCH values: three space-separated numbers for lightness, chroma, and hue. For example, 0.55 0.2 260 is a medium-brightness blue. You can use any OKLCH color picker to find values. For grays, set chroma and hue to 0 (e.g., 0.5 0 0 is medium gray).