Palette

Standard provides physical color families with 12 steps: 100, 150, 200, 300, 400, 500, 600, 700, 800, 850, 900, and 950. The interactive palette ↗ shows the actual source colors in light and dark appearance.

Start with semantic roles

Use roles for component surfaces, text, focus, and state. The defaults are:

<div class="bg-color:neutral-100 border-color:neutral-600 text-color:neutral-950">
  A surface that follows the selected neutral palette
</div>

Steps guide selection; they do not guarantee contrast. Check the actual text/background pair in both appearances and do not communicate state through color alone. Fixed physical names such as teal-600 remain valid for content that requires that specific hue; reusable components should follow roles.

The default ink palette supplies gray surfaces and near-black 800/850 fills in light appearance, with near-white fills in dark appearance. Its 200 step remains a subtle surface. It has all 12 steps and is consumed through the existing primary role. gray and sage remain available.

TeaCSS 0.8.1 provides 000 as the text color on 800 and 850 fills. Use bg-color:primary-800 text-color:primary-000 for a brand action. The lime-800 fill is #BAC836 in light appearance and #C6D43B in dark appearance. Pair either with lime-000 for its dark text.

Neutral roles supply structural surfaces, borders and hover states. Primary uses 900 for values, links and checked fills, with neutral-100 marks, or 200 and 300 for selection. State roles use 200 with 950 for soft messages, or 900 with neutral-100 for strong treatments.

Register palette choices

The CSS entry declares which built-in physical palettes a role may select:

@presets "standard,icons,official";
@primary "ink,gray,blue";
@neutral "gray,sage,slate";
@custom focused "primary";
@success "jade,green";
@warning "amber,orange";
@failure "red,ruby";
@general "blue,cyan";
@teacss;

Lists register choices without changing the default. Their names must be built-in physical palettes; custom colors and role-to-role references cannot be registered as choices. Repeated lists are combined.

Absent role attributes use the ink/gray defaults even without candidate lists. Explicit root selections, including ink, require a matching list. To keep the earlier gray/sage combination when upgrading, register both palettes and select data-css-primary="gray" data-css-neutral="sage" on html; a list alone does not select them.

Choose a registered palette on <html>:

<html lang="en" data-css-primary="blue" data-css-neutral="slate" data-css-appearance="light">
  <body>...</body>
</html>

These attributes are document-wide. Descendant attributes do not create a local palette. Missing, empty, unknown, or unregistered role choices restore the configured defaults. focused follows the effective global neutral selection by default. Bind it once with @custom focused "primary";, "neutral", or a complete physical palette. @focused lists are removed and data-css-focused has no effect. No regeneration is needed to switch among registered choices.

Resolve light and dark appearance

Set data-css-appearance="light" or data-css-appearance="dark" on <html>. It selects color-mode values and drives @light and @dark conditions; @os-light and @os-dark independently follow the operating system. There is no implicit .dark class or descendant theme scope. Without a valid explicit appearance, neither @light nor @dark matches, while the configured base color table still applies.

Astra applications can place one AppearanceScript in <head> before styles and use AppearanceSwitch to manage the preference. See Astra for ownership and persistence. The root stores the resolved light or dark value; system is a preference that the manager resolves, not a third CSS appearance.

Add application colors

Register supported color values in the CSS entry:

@presets "standard";
@source "./src/**/*.{astro,html,js,jsx,ts,tsx}";
@custom {
  --color-brand-500: #0f766e;
}
@teacss;

This adds bg-color:brand-500 and text-color:brand-500. Custom names remain utility values; this does not add a selectable physical palette. @custom accepts supported theme namespaces. Ordinary application variables belong in native CSS or the $name:value utility. Color mode blocks can override colors; non-color values do not become per-mode theme settings.

Continue with Standard for properties and conditions.