Meowland docs
Workbench

Package guide

meowtail

The component library: cross-application components, semantic layout, the standard theme and the complete Assistant.

v0.2.0-alpha.3

Installation

bun add meowtail

Overview

Meowtail is the component library the rest of Meowland is built from. It owns the cross-application components, the semantic layout, the standard theme and the complete Assistant composition. Networking, execution, permissions and persistence stay with the host.

A component declares, the theme paints

A component names its parts and its style axes. It does not carry CSS.

tsx
import { defineComponent, type Props } from "meowjsx";
import { defineOptions } from "meowcss";
import { defineStyleProps, type StyledComponentContract } from "meowcss/meowjsx";

export const calloutOptions = defineOptions("callout", {
  tone: ["neutral", "accent"],
});

export const calloutContract = {
  name: "callout",
  parts: ["root", "title"],
  styleProps: defineStyleProps(calloutOptions, { defaults: { tone: "neutral" } }),
} as const satisfies StyledComponentContract;

export const Callout = defineComponent<Props, "callout", "root" | "title">(
  calloutContract,
  ({ title, children, ...props }, context) =>
    context.part("root", "aside", props, context.part("title", "strong", null, title), children),
);

The theme file paints those parts. The component never writes a data-meowui-part or a data-option-tone attribute by hand: the style plugin writes them when the component is registered.

Three steps to a working page

Importing components is not enough. A page needs the component registry installed on its runtime, the theme stylesheet mounted, and the theme root bound to the document.

tsx
import { createRuntime, h } from "meowjsx";
import { createWebRenderer } from "meowjsx/web";
import { Button, createMeowUI } from "meowtail";
import { standardTheme } from "meowtail/theme";
import { applyTheme, mountStyles } from "meowcss/web";

const runtime = createRuntime({ plugins: [createMeowUI()] });
const renderer = createWebRenderer(runtime);
const document = globalThis.document;

mountStyles(document, standardTheme.cssText);
applyTheme(document.documentElement, standardTheme);
renderer.render(h(Button, null, "Save"), document.querySelector("#app"));

This site is made of it

Every frame, table, badge and link on this site is a Meowtail component, painted by a theme that extends the standard theme. The site does not carry a second palette or a second radius scale.

Components

Every component the library publishes, with its live example and its style axes.

Basic controls

  • ActionRowA row of actions that stays on one line while it fits and stacks whole when it does not: text actions become full-width lines in DOM order and icon actions stay together, so a row never ends ragged or leaves one action alone.
  • AvatarA face or the initials that remain when the image is missing.
  • BadgeA small label that names a category, such as a version or a release stage.
  • ButtonTriggers one action, in one of six levels and three sizes.
  • CardA bordered surface that groups one object's title, content and actions.
  • CardActionThe actions at the end of a card header.
  • CardContentThe body of a card.
  • CardDescriptionThe supporting line under a card title.
  • CardFooterThe row of actions at the end of a card; it stacks whole when it does not fit, like ActionRow.
  • CardHeaderThe top of a card: its title, description and actions.
  • CardTitleThe title of a card.
  • ChoiceSelectSingle-choice listbox.
  • HoverCardA preview card that opens while a trigger is hovered or focused; its text stays selectable.
  • IconButtonA button that shows only an icon and carries its name for assistive technology.
  • ItemA single readable destination.
  • LinkThemed inline text link.
  • MenuButtonA button that opens the existing Menu below it, including nested items.
  • PathLabelA file path that keeps the file name visible when space runs out.
  • PillA capsule fact, or a native button when supplied an action.
  • RiskConfirmationOne host-requested acknowledgement; it never decides which actions need confirmation.
  • SegmentedControlA single choice, using native radio keyboard semantics; tabs remain a separate component.
  • ShortcutKeysA keyboard shortcut, shown as keys.
  • StateDotA small dot that marks a state beside its text.
  • StatusThe state badge: a decorative dot and the state in a word or two, on a soft tint of the state's ink.
  • StatusDotA dot that shows the state of a piece of work.
  • TagA static fact beside content.
  • TextShimmerText with a light sweep across it, for work in progress.

Form inputs

  • CheckboxA native checkbox with its label, including the mixed state.
  • ChoiceGroupVisible single choices with native radio keyboard, validation and form semantics.
  • FieldA labelled form control with optional help text and an error message.
  • FieldGroupA titled set of related fields, as a native fieldset.
  • NumberInputA number the user can type or step.
  • PathPickerControlled path editing with an optional host-owned chooser.
  • SearchInputA text input for search, with a search icon.
  • SelectA native select menu, themed.
  • SliderNative range control.
  • SwitchA native checkbox with switch semantics; form reset and keyboard remain native.
  • TextareaA multi-line text input.

Conversation components

  • AppBarCompact application chrome: one title, one optional status line, and the actions that belong to the whole screen.
  • ChatAttachmentsFiles attached to a message or a draft, with preview, download and remove actions.
  • ChatBubbleA message surface; placement and author metadata belong to ChatMessage.
  • ChatComposerThe message input of a conversation, with attachments, model choice and send.
  • ChatConversationA scrolling transcript that follows new messages.
  • ChatFrameThe outer surface of a conversation that holds its header, messages and composer.
  • ChatHeaderThe top of a conversation: its title, status and actions.
  • ChatMessageOne message in a conversation: the author, the time, the body and its actions.
  • ChatMessageActionsThe row of actions under a message, such as copy or retry.
  • ChatMessageListThe ordered messages of a conversation, announced as a log.
  • ChatProcessA collapsible row for work that happened between messages, with its details inside.
  • ChatQuestionA question the assistant asks the user, with choices and a written answer.
  • ChatSourcesThe sources an answer cites, as a collapsible list of links.
  • ChatToolCallOne tool call in an assistant's work: what ran, on what, and how it ended.
  • ComposerPanelA ChatComposer and optional page-level meta row.
  • PageFrameA frame with fixed chrome and a body that takes the remaining space; the parent owns the chrome.
  • ProcessGroupCollapsible record of what the assistant did; native details owns expansion and keyboard.
  • ProcessStepOne row of a ProcessGroup: icon, a single truncated line, a quiet fact.
  • WorkCardA work reference inside a conversation: one control that opens the work's details.

Overlays and feedback

  • AlertA message about the page or a task, in one of the status tones.
  • ContextMenuRight-click or Shift+F10 opens the existing Menu, including nested items.
  • DialogThe native dialog element, themed; Modal builds a complete dialog on top of it.
  • DialogActionsThe row of buttons that ends a dialog; it stacks whole when it does not fit, like ActionRow.
  • DialogHeaderThe title block of a dialog: an optional eyebrow, the title, a description and actions.
  • DialogPanelThe body of a dialog, with an optional header that stays in place while the body scrolls.
  • EmptyStateWhat a region shows while it has nothing: artwork, a title, a line of help and an optional next step.
  • MenuA list of actions in a popover, with keyboard navigation and nested submenus.
  • ModalA complete native modal dialog over the Dialog primitives: the host owns the open state and every business action, while the Modal owns the native showModal/close mechanics, Escape and backdrop dismissal, focus return and the generated title/description ids.
  • PopoverA floating panel anchored to a trigger, in the top layer.
  • ProgressNative progress: a known amount, or an indeterminate bar when value is omitted.
  • SkeletonDecorative placeholder; the caller owns loading text and aria-busy on the content region.
  • SkeletonBoundaryShows skeletons in place of a region while it loads.
  • SpinnerAn indeterminate loading indicator with a label that says what is loading.
  • ToastA short notice that appears over the page.
  • TooltipNon-interactive help.

Navigation and layout

  • AccordionGrouped disclosures.
  • AspectRatioKeeps its content at a fixed width-to-height ratio.
  • BreadcrumbThe trail of pages from the top of a site to the current one.
  • ContainerCenters content at one of the page widths.
  • DescriptionItemA native description group; its value can compose text and existing layout components.
  • DescriptionListRelated terms and values share a natural label column within the available width.
  • DetailSectionOne titled block inside a detail surface (a side panel or a full-screen reader).
  • DisclosureA section the reader can expand and collapse.
  • DrawerA modal panel that slides in from the start edge over a scrim, for navigation on narrow screens.
  • GridLays out children in responsive columns.
  • IconRailA narrow icon column that expands into a labelled drawer over the page.
  • InlineLays out children in a row that wraps, with a gap from the spacing scale.
  • LayoutItemA wrapper that sets how one child of a Stack or Inline grows, shrinks and aligns.
  • ListGroupRows that read as one set: a single rounded outline with hairlines between the rows.
  • ListRowOne entry in a ListGroup, or alone as a summary.
  • NavItemOne navigation entry: an icon, a label and an optional badge, marked when it is the current location.
  • NavListData-first site navigation: labelled groups of links and actions that own the grouping, the active location and the link/button semantics.
  • PageHeaderThe title block at the top of a full page: a name, one line of purpose, page-level actions.
  • ProseLong-form reading content.
  • RailItemOne destination in an IconRail: an icon alone when collapsed, icon and label when expanded.
  • RailSectionA group of related destinations that folds into one shortcut icon when the rail is collapsed.
  • RegionLayoutThe parent container allocates space; a narrow window combines reading and input, and going back keeps the draft and list focus.
  • ResourceCardOne prepared capability on an overview page: what it is, whether it runs, what to do next.
  • ResourceLinkA reference to one thing that can be opened: a file, a message, a record.
  • SeparatorA thin rule that divides groups of content or tools.
  • StackLays out children in a column, with a gap from the spacing scale.
  • TableData table.
  • TabsHorizontal tabs with automatic keyboard activation.
  • TextOne run of copy in a theme text role.
  • TimelineAn ordered run of events that share one vertical line, newest or most active first.
  • TimelineItemOne event on a Timeline: a marker, a title, its state and optional details.
  • ToolbarA group of related controls that shares one Tab stop; the arrow keys move between them.
  • WindowTitleBarThe title bar of a window whose native title bar is hidden but whose window controls remain (a desktop shell).

Composition examples

  • ActionRailAn action row with wrapping groups.
  • ChatStatusThe connection or activity state of a conversation, as a dot and a word.
  • InputA single-line text input.
  • MetaRowA page-level fact row.
  • PageA content page inside an existing host region: it arranges the identity block, an optional toolbar and notice, and the page content column.
  • SectionOne titled region inside a page or a card surface.
  • Design language · Panorama board

Agent process

  • ChatReasoningA model's visible reasoning before it answers.
  • TaskListAn ordered plan of host-reported steps that an agent works through.

Icons and brand

  • Brand iconsBrand and illustration graphics keep their own shapes, while functional icon convenience entries reuse the same Lucide outline. Toggle light and dark to check readability.
  • IconOne icon from the library's set, by name.
  • IconSourceRender caller-supplied icon data through the shared functional-icon frame.

Assistant

Content

Forms