Internal Style Guide

This guide documents the OFFER-HUB design system, including colors, typography, and component styling for both light and dark modes.

API Schema Components

Use ParamTable for request parameters and ResponseSchema for response fields. Both components use the theme tokens and keep wide tables inside a labelled, keyboard-focusable scroll region on small screens. Nested fields start expanded and can be collapsed; field metadata supports defaults, enums, nullable values, and deprecation notes.

The example below is reviewed against the checked-in Orchestrator contract at public/openapi.json: the /balances operation (get-user-balances) and its response example. In the orchestrator source, keep the corresponding controller and DTO references alongside the contract when updating a schema page.

{
  "code": 200,
  "type": "success",
  "ok": true,
  "message": "Balances retrieved",
  "data": {
    "balances": [
      {
        "currency": "USD",
        "available": 1250,
        "held": 200
      }
    ]
  }
}

Color System

OFFER-HUB uses CSS variables for theme-aware colors. All colors automatically adapt when switching between light and dark modes.

Background Colors

Text Colors

Brand Colors

Semantic Colors

Shadow Colors (Neumorphic)

Border Colors

Tailwind Utility Classes

Use these Tailwind classes for theme-aware styling:

Backgrounds

// Page background
<div className="bg-bg-base" />

// Card/elevated surface
<div className="bg-bg-elevated" />

// Sunken/inset area
<div className="bg-bg-sunken" />

Text

// Primary text (headings)
<h1 className="text-content-primary" />

// Secondary text (body)
<p className="text-content-secondary" />

// Muted text (hints)
<span className="text-content-muted" />

Brand Colors

// Primary color
<button className="bg-theme-primary hover:bg-theme-primary-hover" />

// Accent color
<span className="text-theme-accent" />

Neumorphic Shadows

// Raised surface
<div className="shadow-neu-raised" />

// Small raised surface
<div className="shadow-neu-raised-sm" />

// Sunken/pressed surface
<div className="shadow-neu-sunken" />

// Subtle sunken
<div className="shadow-neu-sunken-subtle" />

Borders

<div className="border border-theme-border" />

Typography

Font Family

OFFER-HUB uses Inter as the primary font:

font-family: var(--font-inter), Roboto, Outfit, sans-serif;

Font Weights

Text Sizes

Component Styling

Buttons

Primary Button (Neumorphic)

<button className="btn-neumorphic-primary px-6 py-2 rounded-full text-sm font-semibold">
  Button Text
</button>

Secondary Button (Neumorphic)

<button className="btn-neumorphic-secondary px-6 py-2 rounded-full text-sm font-semibold">
  Button Text
</button>

Cards

<div className="bg-bg-elevated shadow-neu-raised rounded-2xl p-6">
  <h3 className="text-content-primary font-bold">Card Title</h3>
  <p className="text-content-secondary">Card description</p>
</div>

Inputs

<input
  type="text"
  className="bg-bg-sunken shadow-neu-sunken-subtle rounded-xl px-4 py-3 text-content-primary placeholder:text-content-muted border-none outline-none"
  placeholder="Enter text..."
/>

Diagram System

All generated diagrams (Mermaid today — the same token contract is designed to carry over to a future static/offline pipeline) share one neumorphic theme module: src/lib/diagram-theme.ts. It reads colors directly from the CSS custom properties documented above — never hardcoded hex values — so every diagram matches the current site in both light and dark mode automatically, with no per-diagram theme code.

How it works

• readDiagramColorTokens() reads --color-bg-elevated, --color-bg-sunken, --color-text-primary, --color-text-secondary, --color-border, --shadow-dark, and --shadow-light from whichever scope (:root or .dark) is active.
• getMermaidThemeVariables() maps those tokens onto Mermaid's themeVariables (node fill, text, line color, cluster background). Node and cluster borders use the neutral --color-border token — never --color-primary — so diagram structure reads through soft shadow depth, not a colored outline.
• getNeumorphicDiagramCSS() applies the same dual drop-shadow used by shadow-neu-raised (dark shadow bottom-right, light highlight top-left — the 145° light source from docs/design/neumorphism.md) directly to every node shape, via Mermaid's themeCSS hook.
• src/components/shared/MermaidDiagram.tsx is the single rendering component; src/components/docs/MermaidDiagram.tsx and src/components/architecture/MermaidDiagram.tsx are thin re-exports of it. Every fenced mermaid code block in MDX renders through it automatically via src/components/docs/mdx-components.tsx, so it already produces a correct light and a correct dark rendering of each diagram — no separate -light/-dark source files to maintain until the static diagram pipeline (tracked separately) lands.

Accessibility

• Node and edge labels use --color-text-primary, documented in docs/design/color-palette.md at 12.5:1 contrast against --color-bg-elevated — well past the 4.5:1 WCAG AA requirement for text.
• Edges (lineColor) use --color-text-secondary, documented at 4.8:1 against the base background — past the 3:1 AA requirement for non-text graphical elements.
• No diagram hardcodes a color or uses a border-l-4-style accent bar. Contribute new diagram styling through diagram-theme.ts only.

Node Type Reference

Every shape below renders through the shared theme. State names are taken from the Orchestrator's real order lifecycle (docs/architecture/state-machines.md, "Order States", in the OFFER-HUB/OFFER-HUB repo) instead of placeholder labels.

Process

Decision

Start / End

Database / Store

Subroutine (external call)

Cluster

Z-Index Scale

Dark Mode Implementation

Using the Theme Toggle

The theme can be toggled using the useTheme hook:

import { useTheme } from '@/components/providers/ThemeProvider';

function MyComponent() {
  const { resolvedTheme, toggleTheme } = useTheme();

  return (
    <button onClick={toggleTheme}>
      Current theme: {resolvedTheme}
    </button>
  );
}

Theme Persistence

Theme preference is automatically saved to localStorage under the key offer-hub-theme and persists across sessions.

System Preference

When set to "system", the theme automatically follows the user's OS preference and updates in real-time if changed.

Migration Guide

When migrating components to support dark mode, replace hardcoded colors with theme-aware alternatives: