Skip to main content

Theming

Customize the Knidian SDK appearance to match your brand and design system.

Overview​

The SDK supports extensive theming through:

  • Dark Mode Support: Light, dark, and system-based themes
  • Color Customization: Hex colors converted to HSL
  • Semantic Color Tokens: Specialized colors for editors, inputs, and surfaces
  • Typography Control: Custom fonts and spacing
  • CSS Isolation: Scoped styles prevent conflicts with your app

All theme options are configured in the theme object when initializing the SDK.

Basic Theme Configuration​

const sdk = KnidianSDK.create({
  authUrl: 'https://your-backend.com/api/knidian-auth',
  userId: 'user-123',
  container: '#app',
  theme: {
    mode: 'light', // 'light', 'dark', or 'system'
    primaryColor: '#3b82f6',
    secondaryColor: '#64748b',
    fontFamily: 'Inter, sans-serif',
    borderRadius: '0.5rem',
    spacing: 'comfortable',
  }
});

Dark Mode Support​

The SDK includes full dark mode support with automatic system preference detection and persistent user preferences.

Theme Modes​

theme: {
  mode: 'light'   // Always use light mode
  mode: 'dark'    // Always use dark mode
  mode: 'system'  // Follow system preference (default)
}

System Preference Detection​

When mode: 'system' is set, the SDK automatically:

  • Detects the user's OS-level dark mode preference
  • Updates when the system preference changes
  • Persists user's manual toggle in localStorage

Custom Dark Mode Colors​

Customize colors specifically for dark mode:

theme: {
  mode: 'system',
  // Light mode colors
  primaryColor: '#3b82f6',
  backgroundColor: '#ffffff',
  textColor: '#1f2937',
  editorBackground: '#f9fafb',

  // Dark mode overrides
  dark: {
    primaryColor: '#60a5fa',      // Brighter blue for dark mode
    backgroundColor: '#1f2937',
    textColor: '#f3f4f6',
    editorBackground: '#111827',
  }
}

If no dark overrides are provided, the SDK uses carefully designed default dark mode colors that maintain readability and contrast.

Programmatic Theme Switching​

You can also toggle themes programmatically using the theme context:

// The SDK exposes theme control through the theme context
// Access via: sdkInstance.themeContext.setThemeMode()

// Toggle to dark mode
document.querySelector('.knidian-sdk-root').classList.add('dark');

// Toggle to light mode
document.querySelector('.knidian-sdk-root').classList.remove('dark');

Semantic Color Tokens​

New semantic tokens provide better control over specific UI elements:

Editor Background​

Customize the background color of the TipTap medical notes editor:

theme: {
  editorBackground: '#f9fafb',  // Light mode
  dark: {
    editorBackground: '#1e293b' // Dark mode
  }
}

Default Light: #f9fafb (very light gray) Default Dark: #1e293b (dark slate)

Input Background​

Customize background color for form input fields:

theme: {
  inputBackground: '#ffffff',   // Light mode
  dark: {
    inputBackground: '#374151'  // Dark mode
  }
}

Default Light: #ffffff (white) Default Dark: #374151 (dark gray)

Use Cases​

These semantic tokens are particularly useful when:

  • Your brand's secondary color is too vibrant for text input areas
  • You want consistent input styling across light and dark modes
  • You need fine-grained control over different UI surfaces

Color System​

The SDK uses a comprehensive color system that automatically converts hex colors to HSL for better theming control.

Primary Color​

The main brand color used for:

  • Primary buttons
  • Active states
  • Links
  • Progress indicators
theme: {
  primaryColor: '#3b82f6' // Blue
}

Secondary Color​

Used for:

  • Secondary buttons
  • Less prominent UI elements
  • Borders
  • Disabled states
theme: {
  secondaryColor: '#64748b' // Slate gray
}

Error Color​

Used for:

  • Error messages
  • Validation errors
  • Destructive actions
theme: {
  errorColor: '#ef4444' // Red
}

Default: #ef4444

Success Color​

Used for:

  • Success messages
  • Confirmations
  • Completed states
theme: {
  successColor: '#10b981' // Green
}

Default: #10b981

Background and Text Colors​

theme: {
  backgroundColor: '#ffffff', // White
  textColor: '#0f172a'        // Dark slate
}

Typography​

Font Family​

Customize the font used throughout the SDK:

theme: {
  fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif'
}

Tips:

  • Include fallback fonts
  • Use web-safe fonts or ensure custom fonts are loaded
  • Test readability in medical contexts

Popular Medical App Fonts:

// Modern and professional
fontFamily: 'Inter, sans-serif'

// Classic medical
fontFamily: 'Lato, sans-serif'

// Clean and minimal
fontFamily: 'Roboto, sans-serif'

// Elegant
fontFamily: 'Source Sans Pro, sans-serif'

CSS Variables​

The SDK exposes CSS variables for theming (applied to .knidian-sdk-root):

.knidian-sdk-root {
  /* Colors (HSL format without hsl()) */
  --kn-primary: 185 65% 45%;
  --kn-secondary: 185 50% 94%;
  --kn-background: 185 40% 98%;
  --kn-foreground: 195 60% 28%;

  /* Semantic tokens */
  --kn-editor-background: 185 50% 97%;
  --kn-input-background: 0 0% 100%;
  --kn-surface: 0 0% 100%;

  /* Other */
  --kn-radius: 0.75rem;
}

/* Dark mode */
.knidian-sdk-root.dark {
  --kn-primary: 185 70% 55%;
  --kn-background: 195 30% 12%;
  --kn-foreground: 180 20% 95%;
  --kn-editor-background: 185 25% 18%;
  /* ... etc */
}

CSS Isolation & Embedded Mode​

Scoped Styles​

The SDK uses several techniques to prevent style conflicts with your application:

  1. CSS Variable Scoping: All theme variables are applied to .knidian-sdk-root instead of :root
  2. Tailwind Prefix: All utility classes use the kn- prefix (e.g., kn-flex, kn-bg-primary)
  3. Scoped Base Styles: Tailwind base styles only apply to .knidian-sdk-root *
  4. Variable Prefix: All CSS variables use the --kn- prefix

Embedded Mode​

The SDK respects parent container constraints when embedded in your application:

<!-- Your app structure -->
<div class="my-app">
  <header class="app-header">My Medical App</header>

  <!-- SDK container -->
  <div id="sdk-container" style="flex: 1; overflow: hidden;">
    <!-- SDK will render here and respect the container height -->
  </div>

  <footer class="app-footer">Footer</footer>
</div>
// Initialize SDK in embedded mode
const sdk = KnidianSDK.create({
  authUrl: 'https://your-backend.com/api/knidian-auth',
  userId: 'user-123',
  container: '#sdk-container',
  theme: {
    mode: 'system', // Will respect your app's theme
  }
});

Key Points:

  • SDK uses height: 100% instead of height: 100vh to respect parent constraints
  • Parent container should have defined height (flex, grid, or explicit height)
  • SDK handles its own scrolling internally

Preventing Style Conflicts​

If you experience style conflicts:

  1. Increase specificity of your app's styles:
/* Your app styles */
.my-app .my-button {
  /* Your styles will override SDK if needed */
}
  1. Use the SDK's class prefix:
/* Only target SDK elements */
.knidian-sdk-root .custom-override {
  /* Your customization */
}
  1. Avoid global resets after SDK initialization:
/* ❌ Bad - affects SDK */
* { margin: 0; padding: 0; }

/* ✅ Good - scoped to your app */
.my-app * { margin: 0; padding: 0; }

Best Practices​

  1. Keep it Professional: Medical applications should look trustworthy
  2. Ensure Readability: Use sufficient contrast and appropriate font sizes
  3. Test in Context: Preview with real medical content
  4. Consistent Spacing: Use the spacing presets rather than custom CSS
  5. Brand Alignment: Match your existing design system
  6. Accessibility First: Always test with screen readers and keyboard navigation

Troubleshooting​

Theme Not Applying​

  1. Check that colors are valid hex format: #rrggbb
  2. Ensure custom CSS is valid and properly scoped
  3. Clear browser cache
  4. Check browser console for errors

Colors Look Wrong​

The SDK converts hex to HSL automatically. If colors appear incorrect:

  1. Verify hex values are 6 digits (e.g., #0066cc not #06c)
  2. Test in different browsers
  3. Check for conflicting CSS from your application

Custom CSS Not Working​

  1. Use browser DevTools to inspect elements
  2. Check CSS specificity (SDK uses .kn- prefixes)
  3. Ensure selectors match actual DOM structure
  4. Use !important sparingly as a last resort

Next Steps​