# 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](#1-variables) | `--fin-*` custom properties | Palette, typeface, corners and density, everywhere at once |
| [Classes](#2-classes) | `className` and `classNames` | One block, or one of its parts, in one place |
| [Attributes](#3-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](#4-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 `fin` cascade 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 the `spin`, `ping`, `pulse` and `enter`
  keyframes. Rename your own keyframes if they use those names.

In a Tailwind app, declare the layer order once, above your Tailwind import:

```css title="app/globals.css"
@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.

```css title="fin-theme.css"
: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;
}
```

> [!TIP]
> Keep each step's lightness when you change a scale's hue, so text keeps its contrast. The
> `Themes/Alternate` story sets a whole scale this way.

> [!NOTE]
> On a phone, an approval's terms open in a sheet at the end of `body`. Set variables on `:root`
> so they reach it.

| 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:

```css
.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:

```tsx title="branded-approval.tsx"
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](/react-components).

## 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:

```css
[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:

```css
[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:

```tsx title="plain-approval.tsx"
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>
  );
}
```

> [!IMPORTANT]
> Whatever draws an approval must show the terms Fin derived, and offer only Cancel for one it
> cannot read: nobody approves terms they were not shown.

The [view models](/react-model) cover the thread, replies, activity, automations, amounts and
tokens the same way.
