chordia-ui

Chordia Design System — UI components, design tokens, and Tailwind CSS preset for the Chordia conversation intelligence platform. Published to npm as chordia-ui.

Philosophy

• Evidence-based, explainable interfaces
• "No Judgment" principle: colors categorize, never indicate good/bad
• Clarity over cleverness
• Calm interfaces that build trust through transparency

Installation

npm install chordia-ui

Peer Dependencies

Make sure your app has these installed (they are peer deps of chordia-ui):

npm install react react-dom lucide-react recharts

Usage

1. Import the Tailwind Preset (optional)

In your tailwind.config.js:

module.exports = {
  presets: [require('chordia-ui/tailwind-preset')],
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    // If you want Tailwind to see chordia-ui classNames:
    './node_modules/chordia-ui/dist/**/*.{js,jsx}',
  ],
  // your overrides...
};

2. Import Design Tokens

In your global CSS (e.g. globals.css):

@import 'chordia-ui/tokens';

Or import individual token files:

@import 'chordia-ui/tokens/colors.css';
@import 'chordia-ui/tokens/typography.css';
@import 'chordia-ui/tokens/spacing.css';

3. Use Components

import { Card, SmallButton, SignalCard, ScoreDriverCard, DeviationIndicator } from 'chordia-ui';

You can also import feature-specific shells, like the reusable overlay panel for modals/dialogs:

import { OverlayPanel } from 'chordia-ui/components/models';

4. Optional toast integration (DataTable)

Some components (like DataTable) emit semantic events instead of importing a toast library directly. For example, DataTable exposes an onMaxColumnsError callback that fires when a user tries to select more than the allowed number of columns. How you surface that error is up to the host app:

npm install react-hot-toast

// In your app root/layout
import { Toaster } from 'react-hot-toast';

export function RootLayout({ children }) {
  return (
    <>
      {children}
      <Toaster position="bottom-right" reverseOrder={false} />
    </>
  );
}

// Where you render DataTable
import toast from 'react-hot-toast';
import { DataTable } from 'chordia-ui/components/data';

<DataTable
  {...props}
  onMaxColumnsError={(message) => toast.error(message, { id: 'max-columns-toast' })}
/>;

If you omit onMaxColumnsError, the table still works; users just won’t see a toast for the max‑columns case.

5. DataTable theming note

DataTable uses design tokens for top surfaces (header row, filter row, and top control strip). Set --primary-foreground in your host theme to control these backgrounds consistently across table chrome.

LoginPage Integration

LoginPage delegates all auth behavior to host callbacks.

Expected props

<LoginPage
  descopeProjectId={process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID}
  loading={loading}
  error={error}
  codeError={codeError}
  onLogin={handleLogin}
  onOneTimeCode={handleOneTimeCode}
  onVerifyCode={handleVerifyCode}
  onResendCode={handleResendCode}
  onSignUp={handleSignUp}
  onGoToLogin={() => { setError(null); setCodeError(false); }}
  onDescopeSuccess={() => router.push('/')}
  onDescopeError={() => setError('Could not log in via SSO. Please try again.')}
/>

Button -> callback mapping

• Sign In -> onLogin(email, password)
• Send One-time Code -> onOneTimeCode(email)
• Verify Code -> onVerifyCode(email, otp)
• Verify & Sign In -> onOneTimeCode(email, fullName, otp)
• Resend -> onResendCode(email)

Important: onOneTimeCode has 2 signatures

Handle both host-side:

• handleOneTimeCode(email) for send OTP
• handleOneTimeCode(email, fullName, otp) for verify + sign in flow

Example:

async function handleOneTimeCode(email, fullName, otp) {
  if (!email) return;
  if (fullName && otp) {
    return handleVerifyCode(email, otp, fullName);
  }
  // otherwise: send OTP API call
}

OTP error display

LoginPage renders the external error prop on OTP verification screens.
If your verify API returns:

{ "detail": "Invalid or expired OTP" }

set error to that message in host state to show it in the UI.

Component Categories

| Category | Components | |---|---| | Primitives | Card, DetailCard, SmallButton, Tag, Badge, SectionLabel, Checkbox, TextInput, TextArea, Select, FormLabel, InlineConfirm, Tabs, Tooltip, DeviationIndicator, ColorPalette | | Data | DataTable, DataTableFilters, SummaryStatsPanel | | Interaction Details / Compass | SignalCard, ObservationCard, SmallObservationCard, ScoreDriverCard, ScoreDriverCardVariant, ConditionCard, ModelScoreCard, SummarySection, ExpandPatternComparison | | Media | TranscriptCard, Timeline, ConversationTurn, InteractionSummaryCard | | Chat | ChatInterface, ChatMessage, ChatHistoryPanel, MessageThread | | Navigation | Sidebar, NavigationBar | | Layout | FirstCallScreen, OnboardingChecklist, DemoProjectBanner, IntegrationCard | | Notifications | NotificationPanel, NotificationItem |

Utilities

import { cn } from 'chordia-ui/utils';
// Tailwind class merging utility (clsx + tailwind-merge)

Development

This package now ships a built library in dist/. Consuming apps import from the npm package (chordia-ui) and do not need special transpile configuration in most bundlers. Tailwind-specific configuration is only needed if you want Tailwind to scan chordia-ui’s class names.

Docs

See docs/UIComponentsPage.jsx for a comprehensive component showcase with sample data.