Callaloo

Appearance

Theming ​

The CLThemeProvider component is the foundation of Callaloo's theming system. It configures the visual appearance of your application and enables the use of custom themes. You should wrap your entire application with this component to ensure all Callaloo components receive proper styling.

Basic Usage ​

Default Theme ​

To use Callaloo with the default theme, wrap your application with the CLThemeProvider component:

vue
<script setup lang="ts">
import CLThemeProvider from '@codeandfunction/callaloo/CLThemeProvider';
</script>

<template>
  <div class="my-awesome-app">
    <CLThemeProvider>
      <!-- All of your components that contain any Callaloo components -->
    </CLThemeProvider>
  </div>
</template>

Custom Theme ​

To use a custom theme configuration, pass a themeConfig prop to the CLThemeProvider:

vue
<script setup lang="ts">
import CLThemeProvider from '@codeandfunction/callaloo/CLThemeProvider';
import { CLThemeConfig } from '@codeandfunction/callaloo';

const themeConfig: CLThemeConfig = {
  colors: {
    primary: {
      '100': '#FF34FF',
      // ... additional color shades
    },
    // ... other color palettes
  },
  darkMode: false,
  fontFamily: 'Arial'
};
</script>

<template>
  <div class="my-awesome-app">
    <CLThemeProvider :theme-config="themeConfig">
      <!-- All of your components that contain any Callaloo components -->
    </CLThemeProvider>
  </div>
</template>

CSS Variables ​

Typography and sizing are controlled by CSS variables, so you can customize them from your own stylesheet. Callaloo declares its defaults in the callaloo.tokens cascade layer, so any unlayered CSS you write takes precedence regardless of load order.

css
:root {
  --clll-base-size: 16px;
  --clll-font-family: 'Inter', sans-serif;
  --clll-font-family-heading: 'Playfair Display', serif;
  --clll-font-family-label: 'Inter', sans-serif;
  --clll-font-family-mono: 'JetBrains Mono', monospace;
  --clll-letter-spacing: normal;
  --clll-letter-spacing-heading: -0.02em;
  --clll-letter-spacing-label: 0.04em;
  --clll-letter-spacing-mono: 0;
}

Variables ​

VariableDefaultWhere it can be set
--clll-base-size1rem:root, or the host element of a Shadow DOM
--clll-font-familySystem font stackAny element
--clll-font-family-heading--clll-font-familyAny element
--clll-font-family-label--clll-font-familyAny element
--clll-font-family-monomonospaceAny element
--clll-letter-spacingNot set (inherited)Any element
--clll-letter-spacing-heading--clll-letter-spacingAny element
--clll-letter-spacing-label--clll-letter-spacingAny element
--clll-letter-spacing-mono--clll-letter-spacingAny element

With no overrides, every component renders exactly as it did before these variables existed.

Font roles ​

Each component uses one of four font roles:

RoleComponents
HeadingCLHeading, including the titles of CLModal and CLBanner
LabelCLButton, CLPill, CLBadge
MonoCLMaskedText (monospace mode), the color value in CLInput
BodyEvery other component, including form labels

Form labels use the body role. To give them the label font instead:

css
label[class*='clll-'] {
  --clll-font-family: var(--clll-font-family-label);
  --clll-letter-spacing: var(--clll-letter-spacing-label);
}

Letter-spacing ​

The letter-spacing variables are not set by default, so text inherits the letter-spacing of the surrounding page, as it always has. Native form controls (CLInput, CLSelect, CLTextArea, CLTimePicker) keep the browser default of normal until --clll-letter-spacing is set.

Base size ​

Spacing, font sizes, border radii and control heights all derive from --clll-base-size. Its default of 1rem follows the font size of the document's <html> element. If your page changes the root font size (for example html { font-size: 18px }) and you don't want Callaloo to scale with it, set the base size explicitly:

css
:root {
  --clll-base-size: 16px;
}

--clll-base-size only takes effect on :root or on a Shadow DOM host element. Setting it on any other element has no effect, because the derived sizes are calculated where they are declared.

Shadow DOM ​

When Callaloo's styles are loaded inside a shadow root, the variables are declared on :host. Set your overrides on the host element itself, either from the page or from a :host rule inside the shadow root. Overrides on the page's :root do not reach inside the shadow root.

css
/* In the page */
my-widget {
  --clll-base-size: 16px;
  --clll-font-family: 'Inter', sans-serif;
}

Using with Tailwind CSS ​

If you define fonts in Tailwind's @theme, point the Callaloo variables at them:

css
@import 'tailwindcss';

@theme {
  --font-body: 'Chakra Petch', sans-serif;
  --font-display: 'Silkscreen', monospace;
}

:root {
  --clll-font-family: var(--font-body);
  --clll-font-family-heading: var(--font-display);
  --clll-font-family-label: var(--font-display);
}

CSS variables and themeConfig.fontFamily ​

themeConfig.fontFamily still works. When it is set to anything other than the default, CLThemeProvider applies it as an inline style, which takes precedence over --clll-font-family in your stylesheet. Use one or the other. The CSS variables are recommended, because they also cover the heading, label and mono roles.

Component API ​

CLThemeProvider ​

Props ​

Optional:

  • theme-config: CLThemeConfig - A custom theme configuration that will be applied to all slotted content of the CLThemeProvider component.

Required:

  • None

Colors ​

The Callaloo design system uses a comprehensive color palette where each color has various shades represented from 100 to 900. The color system includes:

  • Primary colors - Main brand colors
  • Neutral colors - Grays and backgrounds
  • Semantic colors - Success, warning, error states
  • Interactive colors - Hover, focus, and active states

Each color shade serves different purposes:

  • 100-300: Light tones for backgrounds and subtle elements
  • 400-600: Medium tones for borders and secondary elements
  • 700-900: Dark tones for text and primary elements

Default Color Palette ​

Here are the default color values included in Callaloo's theme:

Primary Colors ​

ShadeColorHex CodeUsage
0
#ffffffPure white
100
#def5ffLight backgrounds
200
#b6eeffSubtle elements
300
#75e3ffLight accents
400
#2cd6ffMedium elements
500
#00c8ffBase primary
600
#009cd4Interactive elements
700
#007cabText and borders
800
#00688dDark text
900
#065674Darkest shade

Neutral Colors ​

ShadeColorHex CodeUsage
0
#ffffffPure white
100
#F7F7F7Light backgrounds
200
#F2F2F2Subtle backgrounds
300
#EBEBEBLight borders
400
#E6E6E6Medium borders
500
#DEDEDEBase neutral
600
#B3B3B3Disabled elements
700
#858585Secondary text
800
#595959Primary text
900
#2B2B2BDarkest text

Semantic Colors ​

Success (Green)

ShadeColorHex CodeUsage
0
#ffffffPure white
100
#9effb2Light success backgrounds
200
#69f68dSuccess highlights
300
#56e57eLight success accents
400
#41d56eMedium success elements
500
#22c55dBase success
600
#00a147Success interactions
700
#007230Success text
800
#00441aDark success
900
#001f08Darkest success

Danger (Red)

ShadeColorHex CodeUsage
0
#ffffffPure white
100
#ffd3ceLight error backgrounds
200
#ffb2acError highlights
300
#ff8e88Light error accents
400
#fe6561Medium error elements
500
#e74c4cBase danger
600
#d20e27Error interactions
700
#9b0018Error text
800
#63000cDark error
900
#360003Darkest error

Warning (Yellow)

ShadeColorHex CodeUsage
0
#ffffffPure white
100
#ffeabaLight warning backgrounds
200
#ffdf95Warning highlights
300
#ffd36aLight warning accents
400
#fdc836Medium warning elements
500
#f5be1aBase warning
600
#c79800Warning interactions
700
#8a6900Warning text
800
#4f3b00Dark warning
900
#211700Darkest warning

Info (Blue)

ShadeColorHex CodeUsage
0
#ffffffPure white
100
#cfe2ffLight info backgrounds
200
#afceffInfo highlights
300
#8eb9ffLight info accents
400
#6ca4ffMedium info elements
500
#4e8ff8Base info
600
#2470e7Info interactions
700
#004cb5Info text
800
#002e73Dark info
900
#00153eDarkest info

Secondary (Gray-Blue)

ShadeColorHex CodeUsage
0
#ffffffPure white
100
#DEE2E8Light secondary backgrounds
200
#BFC7D4Secondary highlights
300
#9EAABDLight secondary accents
400
#8090A8Medium secondary elements
500
#61738EBase secondary
600
#4F5D73Secondary interactions
700
#3A4555Secondary text
800
#272F3ADark secondary
900
#13161BDarkest secondary

Theme Configuration ​

The CLThemeConfig interface allows you to customize:

  • Colors: Complete color palette with shades 100-900
  • Dark Mode: Enable/disable dark mode styling
  • Font Family: Set the body font family for your application. For heading, label and mono fonts, letter-spacing and the base size, use the CSS variables

Best Practices ​

  1. Application Root: Always place CLThemeProvider at the root of your application to ensure consistent theming across all components.

  2. Color Consistency: When creating custom themes, maintain the 100-900 shade structure for consistent component behavior.

  3. Theme Switching: You can dynamically change themes by updating the theme-config prop reactively.

Released under the MIT License.

Copyright © 2024-present Code+Function