Theming

Customize the appearance of Open Ledger components.

Open Ledger components can be styled to match your application’s design system through the theme prop on the OpenLedgerProvider.

Theme Structure

The theme object allows you to customize colors, typography, spacing, and other visual aspects of the Open Ledger components.

TypeScript
1const theme = {
2 colors: {
3 primary: { hex: '#3366FF' },
4 secondary: { hex: '#FF6B3D' },
5 accent: { hex: '#00C851' },
6 error: { hex: '#FF4444' },
7 warning: { hex: '#FFBB33' },
8 info: { hex: '#33B5E5' },
9 background: { hex: '#F8F9FA' },
10 surface: { hex: '#FFFFFF' },
11 text: { hex: '#212529' }
12 },
13 typography: {
14 fontFamily: "'Roboto', sans-serif",
15 fontSize: '16px',
16 fontWeights: {
17 regular: 400,
18 medium: 500,
19 bold: 700
20 },
21 headings: {
22 h1: {
23 fontSize: '2.5rem',
24 fontWeight: 700,
25 lineHeight: 1.2
26 },
27 h2: {
28 fontSize: '2rem',
29 fontWeight: 700,
30 lineHeight: 1.3
31 },
32 h3: {
33 fontSize: '1.75rem',
34 fontWeight: 500,
35 lineHeight: 1.4
36 }
37 }
38 },
39 spacing: {
40 unit: 8, // Base spacing unit in pixels
41 small: 8,
42 medium: 16,
43 large: 24,
44 xlarge: 32
45 },
46 borderRadius: {
47 small: 4,
48 medium: 8,
49 large: 12
50 },
51 shadows: {
52 small: '0 2px 4px rgba(0,0,0,0.1)',
53 medium: '0 4px 8px rgba(0,0,0,0.12)',
54 large: '0 8px 16px rgba(0,0,0,0.14)'
55 }
56};

Applying a Theme

Pass your theme object to the OpenLedgerProvider to apply it to all Open Ledger components:

TypeScript
1import { OpenLedgerProvider } from "@openledger/accounting-react";
2
3function App() {
4return (
5<OpenLedgerProvider
6entityId="your-entity-id"
7developerId="your-developer-id"
8developerSecret="your-api-key"
9environment="development"
10theme={theme} // Your custom theme
11apiUrl="your-api-url" >
12<YourApp />
13</OpenLedgerProvider>
14);
15}

Adaptive Styling

Open Ledger components use advanced color adaptation functions to automatically adjust to light and dark themes. These functions ensure optimal contrast, readability, and aesthetics regardless of your color palette.

Automatic Light/Dark Detection

Components intelligently detect whether your theme uses a light or dark background and adjust styling accordingly:

TypeScript
1// Example of how our components detect theme brightness
2const isLightColor = (hexColor) => {
3 // Convert hex to RGB and calculate perceived brightness
4 const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hexColor);
5 if (!result) return false;
6
7 const r = parseInt(result[1], 16);
8 const g = parseInt(result[2], 16);
9 const b = parseInt(result[3], 16);
10
11 // Perceived brightness formula (ITU-R BT.709)
12 return (r * 299 + g * 587 + b * 114) / 1000 > 140;
13};

Adaptive Shading

Tables, cards, and input elements automatically adjust their background shade based on your theme colors:

TypeScript
1// Example of how our components create adaptive background shades
2const getAdaptiveShade = (hexColor) => {
3 // Determine if color is light or dark, then adjust accordingly
4 const isLight = isLightColor(hexColor);
5
6 if (isLight) {
7 // Subtle darkening for light themes
8 return `rgba(${r - 8}, ${g - 8}, ${b - 8}, 0.04)`;
9 } else {
10 // Subtle lightening for dark themes
11 return `rgba(${r + 12}, ${g + 12}, ${b + 12}, 0.25)`;
12 }
13};

Context-Aware Shadows

Shadow styles automatically adapt to your theme’s light or dark mode:

TypeScript
1// Example of how our components apply adaptive shadows
2const getCardShadow = (isLight) => {
3 if (isLight) {
4 // Subtle shadows for light themes
5 return `
6 0 1px 2px rgba(0,0,0,0.04),
7 0 2px 4px rgba(0,0,0,0.02)
8 `;
9 } else {
10 // Stronger, more defined shadows for dark themes
11 return `0 1px 2px rgba(0,0,0,0.25)`;
12 }
13};

Theme Properties

Colors

The colors object defines the color palette for your Open Ledger components:

| Property | Description | |-------------|------------------------------------------------------------| | primary | Main brand color used for primary buttons and actions | | secondary | Secondary brand color for alternative actions | | accent | Accent color for highlights and special elements | | error | Color for error states and negative feedback | | warning | Color for warning states and cautionary messages | | info | Color for informational messages and states | | background| Default background color for the application | | surface | Background color for cards and elevated surfaces | | text | Text color for content |

The color format is an object with a hex property:

TypeScript
1{
2 primary: { hex: '#3366FF' },
3 background: { hex: '#F8F9FA' }
4}

Typography

The typography object controls the text styling throughout the components:

PropertyDescription
fontFamilyMain font family for all text elements
font size for the application
font weights
levels

Spacing

The spacing object defines consistent spacing throughout the UI:

| Property | Description | |----------|-----------------------------------------------------------| | unit | Base unit for spacing calculations | | small | Small spacing value (typically used for tight spacing) | | medium | Medium spacing value (default spacing between elements) | | large | Large spacing value (used for more generous spacing) | | xlarge | Extra large spacing (used for section separation) |

Theme Examples

Light Theme

TypeScript
1const lightTheme = {
2 colors: {
3 primary: { hex: '#3366FF' },
4 secondary: { hex: '#FF6B3D' },
5 accent: { hex: '#00C851' },
6 background: { hex: '#F8F9FA' },
7 surface: { hex: '#FFFFFF' },
8 text: { hex: '#212529' }
9 }
10};

Dark Theme

TypeScript
1const darkTheme = {
2 colors: {
3 primary: { hex: '#5C7CFA' },
4 secondary: { hex: '#FF8F6B' },
5 accent: { hex: '#00E676' },
6 background: { hex: '#121212' },
7 surface: { hex: '#1E1E1E' },
8 text: { hex: '#E1E1E1' }
9 }
10};

Responsive Design

All Open Ledger components are designed to be fully responsive, automatically adapting to different screen sizes. Our components use:

  • Flexible grid layouts
  • Mobile-optimized table designs
  • Collapsible panels for small screens
  • Touch-friendly interaction targets

Accessibility Considerations

When customizing colors, keep these accessibility guidelines in mind:

  1. Color contrast: Maintain sufficient contrast ratios between text and background colors (minimum 4.5:1 for regular text, 3:1 for large text)

  2. Focus indicators: Ensure elements retain visible focus indicators when navigating with keyboard

  3. Text sizing: Allow text to scale when user adjusts browser font size

  4. Screen reader support: Our components include ARIA attributes for screen reader compatibility

Best Practices

  1. Maintain consistency: Try to use the same color palette and typography as the rest of your application for a seamless integration.

  2. Test all states: When customizing colors, ensure they work well for all component states (hover, active, disabled, etc.).

  3. Accessibility: Make sure your color choices maintain sufficient contrast ratios for readability and accessibility compliance.

  4. Responsive considerations: Test your theme across different screen sizes to ensure components look good on all devices.