Implementing Ionic Theming

1. Using CSS Variables

Variable Name	Default Value	Description
--ion-background-color	`#ffffff`	Background color of the app
--ion-text-color	`#000000`	Default text color
--ion-primary	`#3880ff`	Primary brand color
--ion-secondary	`#3dc2ff`	Secondary brand color
--ion-tertiary	`#5260ff`	Tertiary brand color
--ion-success	`#10b981`	Success color (e.g., for success buttons)
--ion-warning	`#ffd535`	Warning color (e.g., for warning buttons)
--ion-danger	`#ff4757`	Danger color (e.g., for error buttons)
--ion-dark	`#222428`	Dark theme color
--ion-medium	`#92949c`	Medium gray for text or UI elements
--ion-light	`#f4f5f8`	Light gray for backgrounds or UI elements

Example: Overriding CSS Variables

:root {
  --ion-primary: #ff6b6b;
  --ion-background-color: #f0f0f0;
  --ion-text-color: #333333;
}

Example: Using CSS Variables in Components

<ion-button color="primary">Primary Button</ion-button>
<ion-card style="background-color: var(--ion-background-color)">
  <ion-card-content>Card content</ion-card-content>
</ion-card>

2. Creating Color Variants

Property	Values	Description
--ion-color-primary	`#3880ff`	Primary brand color
--ion-color-secondary	`#3dc2ff`	Secondary brand color
--ion-color-tertiary	`#5260ff`	Tertiary brand color
--ion-color-success	`#2dd36f`	Success color for positive actions
--ion-color-warning	`#ffc409`	Warning color for cautionary actions
--ion-color-danger	`#ff2b50`	Danger color for destructive actions
--ion-color-light	`#f4f5f8`	Light background color
--ion-color-medium	`#92949c`	Medium gray for text and icons
--ion-color-dark	`#222428`	Dark background color

Example: Define a custom color variant

$my-colors: (
  primary: (
    base: #6431b5,
    contrast: #ffffff,
  ),
  secondary: (
    base: #6431b5,
    contrast: #ffffff,
  ),
);

:root {
  --ion-color-primary: #6431b5;
  --ion-color-primary-rgb: 100, 49, 181;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
}

Note: Custom color variants should be defined in your src/theme/variables.scss file to ensure they are properly compiled and available throughout your app.

3. Defining Custom Colors

Property	Value	Description
--ion-color-primary	`#3880ff`	Primary brand color
--ion-color-secondary	`#3dc2ff`	Secondary brand color
--ion-color-tertiary	`#5260ff`	Tertiary brand color
--ion-color-success	`#2dd36f`	Success color (e.g., for success buttons)
--ion-color-warning	`#ffc409`	Warning color (e.g., for warning buttons)
--ion-color-danger	`#eb445a`	Danger color (e.g., for error buttons)
--ion-color-light	`#f4f5f8`	Light background color
--ion-color-medium	`#929495`	Medium gray for text and icons
--ion-color-dark	`#222428`	Dark background color

Example: Defining a Custom Color

$custom-colors: (
  primary: #ff0000,
  secondary: #00ff00,
  tertiary: #0000ff
);

:root {
  --ion-color-primary: map-get($custom-colors, primary);
  --ion-color-secondary: map-get($custom-colors, secondary);
  --ion-color-tertiary: map-get($custom-colors, tertiary);
}

Note: Custom color definitions should be made in src/theme/variables.scss to ensure they are globally available.

4. Setting Up Dark Mode

Dark mode in Ionic can be implemented using CSS variables and the ion-app component. The theme is controlled by setting CSS variables in the root of your application.

Variable	Default Value	Description
--ion-background-color	`#ffffff`	Background color of the app
--ion-text-color	`#000000`	Text color of the app
--ion-toolbar-background	`#ffffff`	Background color of the toolbar
--ion-toolbar-text	`#000000`	Text color of the toolbar

Example: Dark Mode CSS Variables

:root {
  --ion-background-color: #121212;
  --ion-text-color: #ffffff;
  --ion-toolbar-background: #1e1e1e;
  --ion-toolbar-text: #ffffff;
}

Note: To apply dark mode, you can use CSS classes or JavaScript to toggle the dark class on the <ion-app> element.

Example: Toggle Dark Mode with JavaScript

const app = document.querySelector('ion-app');
app.classList.toggle('dark');

Example: Using CSS Classes for Dark Mode

.dark {
  --ion-background-color: #121212;
  --ion-text-color: #ffffff;
  --ion-toolbar-background: #1e1e1e;
  --ion-toolbar-text: #ffffff;
}

5. Using Platform-Specific Styles

Platform	Style Variable	Description
iOS	`--ion-background-color`	Background color for iOS platform
Android	`--ion-background-color`	Background color for Android platform
Web	`--ion-background-color`	Background color for web platform

Example: Platform-specific background color

.my-component {
  background-color: var(--ion-background-color);
}

@media (prefers-color-scheme: dark) {
  .my-component {
    background-color: var(--ion-background-color-dark);
  }
}

Note: Platform-specific styles can be overridden using CSS variables or SCSS variables.

Warning: Ensure that platform-specific styles do not conflict with each other.

6. Customizing Component Styles

Component	Property	Values	Description
ion-button	`color`	`primary`, `secondary`, `danger`, `light`, `dark`	Sets the color theme of the button
ion-button	`fill`	`solid`, `outline`, `clear`	Defines the visual style of the button
ion-card	`color`	`primary`, `secondary`, `danger`	Applies a color theme to the card
ion-card	`mode`	`ios`, `md`	Sets the component mode (iOS or Material Design)

Example: Customizing Button Style

<ion-button color="primary" fill="outline">Custom Button</ion-button>

Example: Customizing Card Style

<ion-card color="secondary">
  <ion-card-content>
    <h2>Custom Card</h2>
  </ion-card-content>
</ion-card>

Note: Component styles can also be customized using CSS variables in the global stylesheet.

7. Implementing Global Styles

Example: Defining global CSS variables

:root {
  --ion-color-primary: #3880ff;
  --ion-color-secondary: #3dc2ff;
  --ion-color-tertiary: #5260ff;
  --ion-color-success: #10b981;
  --ion-color-warning: #ffd534;
  --ion-color-danger: #f04141;
  --ion-color-medium: #92949c;
  --ion-color-light: #f4f5f8;
  --ion-color-dark: #222428;
}

Property	Value	Description
--ion-color-primary	`#3880ff`	Primary brand color for the app
--ion-color-secondary	`#3dc2ff`	Secondary brand color for the app
--ion-color-tertiary	`#5260ff`	Tertiary brand color for the app
--ion-color-success	`#10b981`	Color for success states or actions
--ion-color-warning	`#ffd534`	Color for warning states or actions
--ion-color-danger	`#f04141`	Color for error or destructive actions
--ion-color-medium	`#92949c`	Medium gray for text or backgrounds
--ion-color-light	`#f4f5f8`	Light gray for backgrounds or cards
--ion-color-dark	`#222428`	Dark gray for text or dark mode backgrounds

Note: These CSS variables are used throughout the Ionic framework to style components and can be overridden in src/theme/variables.css.

Example: Using global styles in SCSS

ion-content {
  --background: var(--ion-color-light);
}

ion-toolbar {
  --background: var(--ion-color-primary);
  --color: white;
}

Example: Customizing global font styles

body {
  font-family: 'Roboto', sans-serif;
  font-size: 16px;
  line-height: 1.5;
}

h1, h2, h3 {
  font-weight: 600;
}

8. Using Ionic Color Generator

Example: Generate color variables using Ionic Color Generator

$ion-color-primary: #3880ff;
$ion-color-secondary: #3dc2ff;
$ion-color-tertiary: #5260ff;
$ion-color-success: #10b981;
$ion-color-warning: #ff9f00;
$ion-color-danger: #f44444;
$ion-color-dark: #222428;
$ion-color-medium: #92949c;
$ion-color-light: #f4f5f8;

Property	Value	Description
--ion-color-primary	`#3880ff`	Primary brand color for the app
--ion-color-secondary	`#3dc2ff`	Secondary brand color for the app
--ion-color-tertiary	`#5260ff`	Tertiary brand color for the app
--ion-color-success	`#10b981`	Color for success states (e.g., success messages)
--ion-color-warning	`#ff9f00`	Color for warning states (e.g., warnings)
--ion-color-danger	`#f44444`	Color for error states (e.g., errors)
--ion-color-dark	`#222428`	Dark theme color for text and backgrounds
--ion-color-medium	`#92949c`	Medium gray for text and UI elements
--ion-color-light	`#f4f5f8`	Light theme color for backgrounds

Note: The Ionic Color Generator is a tool that helps developers generate color schemes for their Ionic apps. It allows customization of base colors and generates corresponding CSS variables.

Warning: When using custom color schemes, ensure that the contrast ratio meets accessibility standards (WCAG 2.1).

9. Configuring Theme Variables

Variable	Default Value	Description
--ion-color-primary	`#3880ff`	Primary brand color for the app
--ion-color-secondary	`#3dc2ff`	Secondary brand color for the app
--ion-color-tertiary	`#5260ff`	Tertiary brand color for the app
--ion-color-success	`#2dd36f`	Color for success states or actions
--ion-color-warning	`#ffc409`	Color for warning states or actions
--ion-color-danger	`#ff3b30`	Color for danger states or actions
--ion-color-light	`#f4f5f8`	Light background or text color
--ion-color-medium	`#929495`	Medium gray for backgrounds or text
--ion-color-dark	`#222428`	Dark background or text color

Example: Overriding Theme Variables

$ion-color-primary: #ff6b6b;
$ion-color-secondary: #4ecdc4;

:root {
  --ion-color-primary: #ff6b6b;
  --ion-color-secondary: #4ecdc4;
}

Note: Theme variables can be overridden in your global SCSS file or within component-specific stylesheets.

10. Creating Dynamic Themes

Property	Description	Values	Notes
--ion-color-primary	Primary brand color	`#3880ff`	Used for primary actions and highlights
--ion-color-secondary	Secondary brand color	`#3dc2ff`	Used for secondary actions and accents
--ion-color-tertiary	Tertiary brand color	`#5260ff`	Used for tertiary actions and highlights
--ion-color-success	Success color	`#2dd36f`	Used for success states and confirmations
--ion-color-warning	Warning color	`#ffc409`	Used for warning states and alerts
--ion-color-danger	Danger color	`#ff2b50`	Used for error states and destructive actions
--ion-color-medium	Medium gray color	`#929495`	Used for medium contrast elements
--ion-color-light	Light gray color	`#f4f5f8`	Used for light backgrounds and surfaces
--ion-color-dark	Dark gray color	`#222428`	Used for dark backgrounds and text

Example: Defining a Custom Theme

$my-theme: (
  primary: #ff6b6b,
  secondary: #4ecdc4,
  tertiary: #45b7d1,
  success: #98d8c8,
  warning: #ffd166,
  danger: #ef476f,
  medium: #a9a9a9,
  light: #f8f9fa,
  dark: #2d3436
);

:root {
  --ion-color-primary: map-get($my-theme, primary);
  --ion-color-secondary: map-get($my-theme, secondary);
  --ion-color-tertiary: map-get($my-theme, tertiary);
  --ion-color-success: map-get($my-theme, success);
  --ion-color-warning: map-get($my-theme, warning);
  --ion-color-danger: map-get($my-theme, danger);
  --ion-color-medium: map-get($my-theme, medium);
  --ion-color-light: map-get($my-theme, light);
  --ion-color-dark: map-get($my-theme, dark);
}

Example: Switching Themes at Runtime

import { IonApp } from '@ionic/react';

// Define theme switcher function
const switchTheme = (themeName: string) => {
  const root = document.documentElement;
  switch(themeName) {
    case 'dark':
      root.style.setProperty('--ion-color-primary', '#00ff00');
      root.style.setProperty('--ion-color-secondary', '#0000ff');
      break;
    case 'light':
      root.style.setProperty('--ion-color-primary', '#3880ff');
      root.style.setProperty('--ion-color-secondary', '#3dc2ff');
      break;
    default:
      root.style.setProperty('--ion-color-primary', '#3880ff');
      root.style.setProperty('--ion-color-secondary', '#3dc2ff');
  }
};

// Apply theme on app load
switchTheme('dark');

Note: Dynamic themes require careful handling of CSS variables and may need additional logic to ensure all components update correctly.