Documentation index for AI agents (llms.txt). Markdown versions of every page are available by appending .md to the page URL. The full corpus is at /llms-full.txt.

Mixins

Cherry exports the CSS mixins its own components are built from, so custom elements in your app can share the exact same look and behavior. All of them are plain styled-components css fragments or helper functions - interpolate them into any styled component.

interactiveStyles

The hover, focus, and active affordance used for interactive surfaces like cards, tiles, and block-level links: a transparent 1px border that picks up the primary color on hover, plus a soft focus ring. Pair it with resetButton for clickable elements that aren't Buttons.

import styled from "styled-components";
import { interactiveStyles, resetButton } from "cherry-styled-components";

const ClickableCard = styled.button`
  ${resetButton}
  ${interactiveStyles}
  border-radius: 12px;
  padding: 20px;
`;

errorInteractiveStyles

The destructive-action sibling of interactiveStyles: identical hover, focus, and active behavior, but in the theme error red (the same red the $error Button uses). Use it for delete and remove affordances.

import styled from "styled-components";
import { errorInteractiveStyles, resetButton } from "cherry-styled-components";

const RemoveTile = styled.button`
  ${resetButton}
  ${errorInteractiveStyles}
  border-radius: 12px;
  padding: 20px;
`;

Color helpers

Three functions for deriving a shade from a token instead of hardcoding a second hex value. Each takes a CSS color and a percentage:

  • alpha(color, percent) - Fades the color to percent opacity.
  • shade(color, percent) - Darkens the color by percent toward black.
  • tint(color, percent) - Lightens the color by percent toward white.
import styled from "styled-components";
import { alpha, shade, tint } from "cherry-styled-components";

const DangerZone = styled.div`
  background: ${({ theme }) => tint(theme.colors.error, 90)};
  border: solid 1px ${({ theme }) => alpha(theme.colors.error, 40)};
  color: ${({ theme }) => shade(theme.colors.error, 20)};
`;

They return a native CSS color-mix(in srgb, ...) string rather than a computed value, which means the browser does the math at paint time. Two consequences worth knowing:

  • The input can be any valid CSS color, including a var(--token) reference. If you white-label Cherry through CSS custom properties, the helpers keep working, where a JavaScript color library would choke on the unresolved var().
  • The output is a CSS string, not a hex value. Interpolate it into a style declaration; do not try to parse it or feed it to something expecting #rrggbb.

color-mix() is supported in all current browsers (Chrome 111+, Safari 16.2+, Firefox 113+). Cherry uses these helpers internally for its own hover and focus states, so the same baseline applies to the library as a whole.

Filled text helpers

Helpers for a brand-colored fill and the text sitting on it, extracted from the filled Button and shared by Avatar and the chat kit's user bubble:

  • primaryFillColor(theme) - The solid primary fill: the theme's primaryFill, else primary.
  • primaryFillHoverColor(theme) - That fill on hover: a 10% shade of primaryFill, else primaryDark.
  • filledTextColor(theme, fill?) - The label color on a fill. fill is "primary" or "other" (the default). On a primary fill it returns the theme's onPrimary when it sets one; otherwise the theme's onFilled, else the palette's contrasting end: colors.light in light mode, colors.dark in dark mode.
  • darkFilledTextRule(theme, fill?) - The same choice restated as a rule scoped to a dark class on <html>, which is what apps resolving the mode in CSS key off before hydration can swap the theme object. Additive: with an already-dark theme object both paths resolve to the same color. On a primary fill, only a dark theme object's onPrimary applies; a light one cannot know the dark value, so it keeps the palette's dark. Empty when the theme sets onFilled, whose value already follows the mode. Interpolate it alongside filledTextColor.
import styled from "styled-components";
import {
  darkFilledTextRule,
  filledTextColor,
  primaryFillColor,
  primaryFillHoverColor,
} from "cherry-styled-components";

const Badge = styled.span`
  background: ${({ theme }) => primaryFillColor(theme)};
  color: ${({ theme }) => filledTextColor(theme, "primary")};
  ${({ theme }) => darkFilledTextRule(theme, "primary")};

  &:hover {
    background: ${({ theme }) => primaryFillHoverColor(theme)};
  }
`;

Fill a labelled primary surface with these instead of theme.colors.primary and theme.colors.light, so a theme's primaryFill and onPrimary apply (see Theme). Fills with no label on them (dots, bars, rings) stay on primary.

Mode token helpers

Helpers for the choices a theme's optional mode tokens make, so your own components follow a theme whose colors are CSS variables (see Theming through CSS variables). Each returns the theme's token when it sets one, else the isDark choice it replaces:

  • accentColor(theme) - Hover and emphasis text: the theme's accent, else primaryDark in light mode and primaryLight in dark mode.
  • linkColor(theme) - The link color: the theme's link, else primary in light mode and dark in dark mode.
  • primaryTintColor(theme, kind) - The primary tint behind a surface, kind being "hover", "drop" or "active": the theme's primaryTintHover, primaryTintDrop or primaryTintActive, else primary faded to the mode's amount.
  • darkPrimaryTintRule(theme, kind) - That tint's dark value as a rule scoped to a dark class on <html>, for apps that resolve the mode in CSS before hydration. Empty when the theme sets the token. Interpolate it alongside primaryTintColor.
import styled from "styled-components";
import {
  accentColor,
  darkPrimaryTintRule,
  primaryTintColor,
  resetButton,
} from "cherry-styled-components";

const Tile = styled.button`
  ${resetButton}

  &:hover {
    color: ${({ theme }) => accentColor(theme)};
    background: ${({ theme }) => primaryTintColor(theme, "hover")};
    ${({ theme }) => darkPrimaryTintRule(theme, "hover")};
  }
`;

thinScrollbar

A slim, theme-aware scrollbar for internal scroll areas - chat transcripts, code blocks, wide tables - so the chunky native bar does not stand out, especially in dark mode. Used by ChatMessageList and Prose.

import styled from "styled-components";
import { thinScrollbar } from "cherry-styled-components";

const CodeScroller = styled.pre`
  overflow-x: auto;
  ${thinScrollbar};
`;

Resets

  • resetButton - Strips native button styling (appearance, border, background, padding, margin) and sets box-sizing: border-box, cursor: pointer, and outline: none. Since the focus outline is removed, pair it with interactiveStyles or provide your own focus style. The base of Button, IconButton, and ThemeToggle.
  • resetInput - Minimal input reset used by the form components.

Form helpers

  • fullWidthStyles(fullWidth) - Returns width: 100% when the flag is set. Backs the $fullWidth prop across components. Unlike the other two helpers, its parameter has no $ sigil.
  • statusBorderStyles($error, $success, theme) - Border color for error and success validation states.
  • formElementHeightStyles($size) - Shared height for form elements in the three sizes (small, default, big).

Responsive style generators

Used internally by the layout components, and available for custom components that take per-breakpoint props:

  • generateGapStyles, generateColsStyles, generateColSpanStyles
  • generatePaddingStyles, generateJustifyContentStyles
  • generateAlignItemsStyles, generateAlignContentStyles, generateDirectionStyles

Each takes (size: keyof Breakpoints<number>, value) and returns the declaration wrapped in the mq(size) min-width media query for that breakpoint (xs, sm, md, lg, xl, xxl, xxxl):

import styled from "styled-components";
import {
  generateGapStyles,
  generateDirectionStyles,
} from "cherry-styled-components";

const Toolbar = styled.div`
  display: flex;
  ${generateGapStyles("xs", 10)}
  ${generateGapStyles("lg", 20)}
  ${generateDirectionStyles("xs", "column")}
  ${generateDirectionStyles("lg", "row")}
`;

The component style mixins buttonStyles and iconButtonStyles are documented on the Button and IconButton pages; proseStyles on the Prose page; and chatTextStyles on the Chat Messages page.