open-index/open-npm huggingface dataset:
npm package: @mmnl.crngl/astro-ui
Description: Token-driven Astro UI component system
Latest version: 0.3.11

# Astro UI System

A token-driven, class-based UI system for Astro.

## Philosophy

- **Token-first**: primitives, semantics, and component tokens are layered CSS variables.
- **Class-only variants**: all component variants resolve to pre-defined classes.
- **Global radius control**: one semantic token (`--aui-radius-base`) controls rounding across the system.
- **No runtime styling engine**: no Tailwind and no inline-style API.

## Installation

```bash
npm install @mmnl.crngl/astro-ui astro
```

Import root styles once:

```ts
import '@mmnl.crngl/astro-ui/styles.css';
```

## Token System

- `src/tokens/primitive.css` defines spacing, color, type, shadow, z-index.
- `src/tokens/semantic.css` maps design meaning and dark theme overrides.
- Component tokens and styles are co-located with their respective components for optimal on-demand CSS rendering.

## On-Demand CSS Rendering

Component styles are automatically included only when their respective components are imported. This means:

- Smaller CSS bundles - only styles for imported components are included
- Better tree-shaking and code splitting
- Improved performance through automatic optimization

Simply import the components you need:

```astro
import { Button, Card } from '@mmnl.crngl/astro-ui';
```

Only Button and Card styles will be included in your bundle.

## Layout Usage

```astro
---
import { Container, Stack, Grid, Box } from '@mmnl.crngl/astro-ui';
---

<Container>
  <Stack gap="md">
    <Grid cols={3}>
      <Box surface={true}>Card 1</Box>
    </Grid>
  </Stack>
</Container>
```

## Theming

Dark mode tokens are enabled with:

```html
<html data-theme="dark">
```

Custom brand profiles can override semantic tokens:

```css
:root[data-brand='flat'] {
  --aui-radius-base: 0px;
}
```

## Radius Override

Set `--aui-radius-base` at root or container scope to globally tune the corner style without touching components.

## Roadmap

- Phase 1: foundation ✅
- Phase 2: controls ✅
- Phase 3: feedback ✅
- Phase 4: composites ✅ (interaction behavior to be deepened)
- Phase 5: release docs + playground