Theming
Fin's blocks look like near.com until you restyle them. Four levels restyle them, from a few variables to entirely your own markup. Use the lightest that does what you need; they combine.
| Level | You change | Use it for |
|---|---|---|
| Variables | --fin-* custom properties | Palette, typeface, corners and density, everywhere at once |
| Classes | className and classNames | One block, or one of its parts, in one place |
| Attributes | CSS on data-fin-part and data-fin-ui | A part or a primitive (every button, badge, notice) in every block |
| Your own markup | The view models in @nearai/financial-agents-react/model | A block drawn entirely by your components |
How the stylesheet stays out of your way
@nearai/financial-agents-react/styles.css styles nothing outside Fin's blocks:
- Every element rule sits in the
fincascade layer, so your unlayered CSS always wins. - Every class is prefixed
fin:and every variable--fin-, so nothing collides with your classes or theme, Tailwind's included. - Its small reset applies only to Fin's elements. Pages without Tailwind render the blocks correctly; pages with it see no change.
- What any Tailwind 4 build shares sits outside the layer: the
--tw-*and--twsa-*properties registered with@property, and thespin,ping,pulseandenterkeyframes. Rename your own keyframes if they use those names.
In a Tailwind app, declare the layer order once, above your Tailwind import:
@layer theme, base, fin, components, utilities;
@import "tailwindcss";1. Variables
Set --fin-* variables on :root, or on any element above Fin's blocks. This makes them look like another product: an indigo accent, warm greys, a serif face, square corners and a denser rhythm.
:root {
--fin-font-sans: Georgia, "Times New Roman", serif;
--fin-color-green-500: oklch(0.831 0.12 277);
--fin-color-green-600: oklch(0.711 0.16 277);
--fin-color-green-700: oklch(0.5935 0.2 277);
--fin-color-gray-500: oklch(0.556 0.011 70);
--fin-color-gray-900: oklch(0.205 0.006 70);
--fin-radius-md: 0px;
--fin-radius-lg: 0px;
--fin-radius-xl: 0px;
--fin-spacing: 0.2rem;
}| Variables | Steps | Drives |
|---|---|---|
--fin-color-green-<step> | 50, 100, 200 … 900, 950 | The accent: primary buttons, success, rising figures, the agent's mark |
--fin-color-red-<step> | 50, 100, 200 … 900, 950 | Danger and falling figures |
--fin-color-yellow-<step> | 50, 100, 200 … 900, 950 | Caution: pending approvals and holds |
--fin-color-gray-<step> | 10, 25, 50, 100, 150, 200, 300 … 800, 850, 875, 900, 950 | Surfaces, borders and ink |
--fin-color-blue-<step> | 300, 500, 700 | Information |
--fin-color-white | Text on a filled accent | |
--fin-font-sans, --fin-font-mono | Typefaces. Fin loads no fonts of its own | |
--fin-font-weight-<weight> | normal, medium, semibold, bold | Weights |
--fin-text-<size>, --fin-text-<size>--line-height | xs, sm, base, lg, xl, 2xl, 3xl, 4xl | The type scale |
--fin-leading-<name>, --fin-tracking-<name> | tight, snug, normal; tight, wide | Line height and letter spacing |
--fin-radius-<size> | sm, md, lg, xl, 2xl, 3xl | Corners |
--fin-spacing | The base of every padding, margin and gap | |
--fin-container-<size> | sm, md, lg, xl, 3xl, 4xl | The widths some cards stop growing at |
--fin-ease-<curve> | out, in-out | Easing curves |
--fin-default-transition-<setting> | duration, timing-function | The default transition |
--fin-animate-<name> | spin, pulse, ping | Spinners and live dots |
Dark mode
Blocks draw dark inside an element with the dark class (near.com's and next-themes' class strategy), or inside data-fin-theme="dark". .not-dark or data-fin-theme="light" keeps a subtree light. Scope variables to one theme:
.dark,
[data-fin-theme="dark"] {
--fin-color-gray-900: oklch(0.96 0.004 70);
}2. Classes
Every block takes className for its root. A block with named parts also takes classNames, one class per part:
import { ApprovalCard, type ApprovalCardProps } from "@nearai/financial-agents-react";
export function BrandedApproval(props: ApprovalCardProps) {
return (
<ApprovalCard
{...props}
className="my-card"
classNames={{ band: "my-card-band", actions: "my-card-actions" }}
/>
);
}Your classes come after Fin's and your CSS sits outside its layer, so yours win. Each block's parts are in the components reference.
3. Attributes
Two attributes are the stable hooks for CSS that reaches into a block. Fin's own class names are not: they can change in any release.
data-fin-part
Names every block and part: approval-card on an approval card, approval-card-evidence on its exact terms. Target a part everywhere it appears:
[data-fin-part="approval-card-evidence"] {
display: none;
}Root data-fin-part | Block |
|---|---|
activity-group | ActivityGroup |
approval-card | ApprovalCard. Inside: decision-countdown, the time left to decide; execution-swaps, a multi-swap execution's swaps; grid-band, a grid approval's band |
asset-icon | AssetIcon |
asset-link | A token in a card or a ticker in a reply, linked to your page for it by routes.asset |
automation-card | AutomationCard |
comparison-card | ComparisonCard. Inside: sparkline, each asset's trend line |
contacts-card | ContactsCard |
contract-terms | ContractTerms |
memecoins-card | MemecoinsCard |
grid-band | GridBand, also inside a grid's ApprovalCard and GridCard |
grid-card | GridCard |
message-markdown | MessageMarkdown. Inside: sparkline, a bolded asset's trend line |
mint-address | A Solana token's address, shortened, with its copy button, where a Solana card shows one to tell look-alikes apart: in TokenCandidatesCard, MemecoinsCard, SolanaTokenCard and SolanaHoldingsCard |
next-steps | NextSteps |
orders-card | OrdersCard |
perps-firing-card | PerpsFiringCard |
holdings-card | HoldingsCard |
pending-approval-chip | PendingApprovalChip |
prediction-market-card | PredictionMarketCard |
prediction-preview-card | PredictionPreviewCard |
predictions-card | PredictionsCard |
price-card | PriceCard |
question-card | QuestionCard |
run-footer | RunFooter |
run-progress | RunProgress |
run-receipt | RunReceipt |
settlement-receipt | SettlementReceipt |
solana-holdings-card | SolanaHoldingsCard |
solana-receipt | SolanaReceipt |
solana-token-card | SolanaTokenCard |
token-candidates-card | TokenCandidatesCard |
tool-call-card | ToolCallCard |
vaults-card | VaultsCard |
wallet-card | WalletCard |
data-fin-ui
Names every primitive a block draws with: each button, badge, notice and line of text. Where it applies, a primitive also carries data-fin-variant, data-fin-size, data-fin-tone and data-fin-state, so one rule restyles it in every block:
[data-fin-ui="button"] {
border-radius: 9999px;
}
[data-fin-ui="button"][data-fin-variant="primary"] {
background: #312e81;
color: #ffffff;
}
[data-fin-ui="badge"] {
border-radius: 2px;
letter-spacing: 0.06em;
text-transform: uppercase;
}data-fin-ui | Is | Carries |
|---|---|---|
button | A button | variant: primary, accent, secondary, outline, dark, light, transparent, destructive, destructive-soft, success-soft; size: xs, sm, md, lg, xl |
icon-button | An icon-only button, such as a notice's dismiss or a reply's thumbs | variant, size |
badge | A status label | tone: neutral, accent, caution, danger, info; variant: outline, soft, solid; size: sm, md |
notice | A message under a card, such as a refusal | tone: info, accent, caution, danger |
text | A line of text | variant: display, title, heading, subheading, body, body-sm, label, caption, mono, muted; tone: default, soft, muted, faint, accent, caution, danger |
prose | A reply's text | size: sm, md |
stream-caret | The caret after live text | |
card | A panel | tone: raised, flat, inset, caution, danger, accent |
disclosure | A section that opens in place | size: sm, md |
dialog | A dialog | variant: modal, drawer, page, sheet; size: sm, md, lg; tone: neutral, danger |
spinner | Work in progress | size: xs, sm, md |
kbd | A key cap, such as a question card's number keys | |
segmented-control | A radio group drawn as one control, such as a price card's range tabs | size: sm, md |
tool-indicator | A tool call's status glyph | state: running, completed, failed, denied, invalid_input, pending_approval, pending_input, pending_confirmation, refunded, partial, not_executed |
json-view | An exact input or result, as JSON | |
token-icon | A token's disc | |
network-badge | A token's network badge |
The Themes/Parts stories show both attributes at work.
4. Your own markup
@nearai/financial-agents-react/model holds the logic behind every block, so your components can draw Fin's data with none of its markup or styles. approvalContent reads an approval as the card does:
import { type ApprovalView, approvalContent } from "@nearai/financial-agents-react/model";
export function PlainApproval(props: { approval: ApprovalView; onDecide: (ok: boolean) => void }) {
const content = approvalContent(props.approval);
return (
<article aria-label={content.headline}>
<h3>{content.headline}</h3>
<dl>
{content.terms.map((term) => (
<div key={term.label}>
<dt>{term.label}</dt>
<dd>{term.value}</dd>
</div>
))}
</dl>
{content.readable ? null : <p>Update the app to review this request.</p>}
<button type="button" onClick={() => props.onDecide(false)}>
Cancel
</button>
{content.readable ? (
<button type="button" onClick={() => props.onDecide(true)}>
{content.approveLabel}
</button>
) : null}
</article>
);
}The view models cover the thread, replies, activity, automations, amounts and tokens the same way.