@teasim/astra — Teasim

@teasim/astra provides the element layer for Astro. Each family renders semantic HTML and adds browser behavior where the platform does not provide it. An accordion uses details; modal content uses dialog. Public props, parts, recipes, and native behavior form the component contract.

This guide targets Astra 0.5.0 with TeaCSS 0.7.1.

Install

Configure GitHub Packages and supply a package-read credential through the environment:

ini

@teasim:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GIT_TOKEN}

bun add @teasim/[email protected] @teacss/[email protected]
bun add -d [email protected] @teacss/[email protected]

Astra requires Node.js 24.2.0 or later, Astro >=7.2.0, and exact TeaCSS / Classes peers 0.7.1. Install Classes directly so application and package recipes share one runtime module. Keep Astro and the TeaCSS adapter’s host requirements satisfied as well.

Generate the styles

Astra ships its TeaCSS declarations, not a compiled stylesheet. At the project-root index.css, import the declarations and scan the distributed components:

css

@import "@teasim/astra/index.shortcuts.css";
@presets "standard,icons,official";
@source "./src/**/*.{astro,ts,tsx,js,jsx,md,mdx,css}";
@source "./node_modules/@teasim/astra/dist/**/*.{js,astro,css}";
@teacss;

The CSS import registers shared shortcuts and safelists. Scanning finds the classes actually used by recipes and Astro markup; both steps are required. Keep the package in Astro’s SSR build:

import { defineConfig } from "astro/config";
import { teacss } from "@teacss/astro";

export default defineConfig({
  integrations: [teacss()],
  vite: { resolve: { noExternal: ["@teasim/astra"] } },
});

Installation explains entry-relative globs and adding Aster’s sources. Components use TeaCSS semantic roles; select palettes on <html> as described in Palette.

Public imports and styling

import { Accordion, AccordionItem, AccordionSummary, AccordionContent } from "@teasim/astra";
import { accordionRecipe } from "@teasim/astra/recipes";
import { cn, recipe } from "@teacss/classes";

Components, public family helpers, and types come from the package root. Component subpaths and source deep imports are private. Recipes come from @teasim/astra/recipes; prop-authoring helpers have their own @teasim/astra/helpers entry. @teasim/astra/runtime exposes curated client utilities, not family installers, and importing it installs no listeners.

Each documented part owns its namespaced data-slot; callers must not replace it. Components take class, while recipe resolvers take className and merge caller classes last. Define new application recipes with defaults, as shown in Classes. Native and ARIA forwarding is part-specific: a component’s owned attributes cannot be overridden.

Shared appearance

Place one initializer in <head> before styles. It resolves the stored or system preference before the first paint:

astro

---
import { AppearanceScript, AppearanceSwitch } from "@teasim/astra";
---
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <AppearanceScript defaultAppearance="system" />
  </head>
  <body>
    <AppearanceSwitch label="Dark mode" />
    <slot />
  </body>
</html>

AppearanceScript owns the resolved <html data-css-appearance="light|dark"> and CSS color-scheme. Its default storage key is teasim-appearance; defaultAppearance accepts system, light, or dark. The switcher changes light/dark preference, while palette selection remains the application’s responsibility. Use one appearance manager instead of writing a competing initializer. The document emits teasim:appearance-change when the state changes. Style against @dark / @light or data-css-appearance, never a separate data-theme attribute or implicit .dark class.

Continue reading

The Accordion guide covers native disclosure, controlled events, and keyboard behavior. Code covers syntax highlighting, annotations, scrolling, and code copying. Page composition belongs to Aster; source validation and navigation data belong to Astro.